Merge remote-tracking branch 'origin/rustify' into worktree-agent-afe80868604fef704

# Conflicts:
#	IRIS.md
#	RUST.md

.cargo/config.toml

@@ -0,0 +1,6 @@
+# xtask convention (https://github.com/matklad/cargo-xtask), without folding
+# every crate in this repo into one workspace -- they are deliberately
+# independent (see run-tests.sh, which cds into each). `cargo xtask apk`
+# from the repo root runs xtask/src/main.rs directly.
+[alias]
+xtask = "run --quiet --manifest-path xtask/Cargo.toml --"

.dev-updater.ron

@@ -55,4 +55,21 @@ components: [
         // the terminal the QR would be printed on.
         enroll: "server/enroll-link.sh",
     ),
+    // E5 (RUST.md): app/shellApp packaged by the xtask instead of Gradle
+    // (cargo ndk -> javac -> d8 -> aapt2 -> zipalign -> apksigner), signed
+    // with the same release key as "app" above so the two can install
+    // over each other -- a separate component, not a mode of "app" above,
+    // because it is a different applicationId (com.example.aiapp.shell)
+    // built by a different tool from different sources. No `cwd`: it
+    // defaults to this checkout's root, which both the `cargo xtask`
+    // alias (`.cargo/config.toml`, resolved relative to the working
+    // directory cargo is run from) and `cargo xtask apk`'s own publishing
+    // step (`xtask/build/outputs/apk/<mode>/*.apk`, matching discover.rs's
+    // `*/build/outputs/apk/*/*.apk` pattern -- see apk.rs's module doc)
+    // both need.
+    Apk(
+        name: "shell",
+        modes: ["release", "debug"],
+        build: "cargo xtask apk",
+    ),
 ],

.gitignore

@@ -1,12 +1,20 @@
 .gradle/
 build/
 app/androidApp/build/
+app/shellApp/build/
 local.properties
 .kotlin/
 *.iml
 .idea/
 .DS_Store
 server/target/
+event-model/target/
+client-core/target/
+android-shell/target/
+
+# E3's native library, built by cargo-ndk straight into the Gradle module
+# (RUST.md) -- an artifact, like server/target/ above, not source.
+app/shellApp/src/main/jniLibs/
 
 # Server logs from a development run (ai-server.log by convention,
 # wg-test.log from ./test-wg-tunnel.sh).
@@ -24,3 +32,11 @@ sessions/
 
 # iris, the in-house UI library, is vendored at iris/ and built by cargo.
 iris/target/
+iris/android-app/target/
+
+# E5's packaging xtask (RUST.md). `build/` above already covers
+# xtask/build/outputs/apk (the published APK, see apk.rs's module doc).
+# The repo root has no Cargo workspace, so this is xtask's own
+# intermediate working files (target/xtask/apk/...), not a shared one.
+xtask/target/
+/target/

CLIENT_CORE.md

@@ -0,0 +1,146 @@
+# client-core
+
+`client-core/` is the app's pure logic held once instead of twice, per
+RUST.md's recommendation item 1. It is a plain Rust library crate with no UI
+framework dependency of any kind, so it can outlive whichever one the app
+ends up drawing with (Masonry, iris, or something else -- see RUST.md).
+`event-model/` is its sibling: the wire shape both this crate and `server/`
+share, extracted from `server/src/session/driver.rs` and
+`session/transcript.rs` on 2026-09-04.
+
+Neither crate is wired into anything yet. `server/` re-exports `event-model`
+so its own behaviour is unchanged (`./run-tests.sh` covers it); `client-core`
+has no caller -- it exists for whichever experiment in RUST.md picks it up
+next (a Masonry or iris transcript screen, most likely).
+
+## What's here, and what Kotlin file it replaces
+
+| `client-core/src/…`                     | Kotlin original                          | Status |
+|------------------------------------------|-------------------------------------------|--------|
+| `event-model/src/lib.rs` (shared crate)   | `Events.kt` (the enum mirror)             | Done   |
+| `ansi.rs`                                 | `Ansi.kt`                                 | Done, ported test-for-test |
+| `highlight/mod.rs`, `languages.rs`        | `Highlighter.kt`, `Languages.kt`          | Done, ported test-for-test |
+| `highlight/markdown.rs`                   | `MarkdownSyntax.kt`                       | Done, ported test-for-test |
+| `transcript_cache.rs`                     | `TranscriptCache.kt`                      | Done, ported test-for-test |
+| `sse.rs`                                  | `Sse.kt` (the framing half)               | Done, new tests (Kotlin had none of its own beyond integration) |
+| `api.rs`                                  | `Api.kt`                                  | Partial -- see below |
+| `event_stream.rs`                         | `EventStream.kt`                          | Done |
+| `transcript_fold.rs`                      | `TranscriptItems.kt`, `ToolRows.kt`       | Partial -- see below |
+| `config.rs`                                | `ServerConfig.kt`'s `handleEnrollment`   | New, desktop-only so far -- see below |
+| *(not started)*                           | `TranscriptSource.kt`                     | Not started |
+| *(not ported, and may never be)*          | `TranscriptUnits.kt`                      | Out of scope -- see below |
+
+Every file above whose Kotlin counterpart had a JVM unit test (`AnsiTest`,
+`HighlighterTest`, `TranscriptCacheTest`) has had every one of those test
+cases ported alongside it, plus new tests for the pieces that had none
+(`sse.rs`, `api.rs`, `event_stream.rs`, `transcript_fold.rs`). Test count by
+crate as of this writing: **85 in `client-core`**, 0 in `event-model` (its
+types carry no logic of their own to test -- `server/`'s own tests exercise
+them via `session::transcript`'s round-trip coverage).
+
+## Correspondence notes worth knowing before touching either side
+
+- **`ansi.rs`'s `StyledText`/`Style`/`Rgb`** stand in for Compose's
+  `AnnotatedString`/`SpanStyle`/`Color`, since this crate has no Compose.
+  `StyledText` is plain text plus a `Vec<(Range<usize>, Style)>` of
+  non-overlapping spans. Whatever UI framework ends up consuming this
+  crate maps `Style` onto its own text-styling type; nothing here should
+  change to accommodate a particular one.
+- **`highlight`'s `Span`/`Kind`** use **char indices, not byte offsets**
+  (`Vec<char>` internally), mirroring the Kotlin original's `Char`-indexed
+  strings. `highlight::span_text` turns a `Span` back into text for a
+  caller working the same way; a caller that wants byte offsets into a
+  `&str` has to convert.
+- **`transcript_cache.rs`'s `SessionCache::guard`** found a real
+  translation bug while it was being written: an early draft let a
+  *damaged* chunk (one file unreadable, discard just this session) and a
+  genuine I/O failure (disk gone, disable the whole cache) both surface as
+  the same `Err` from one closure, which would have disabled every
+  session's cache over a single corrupt chunk. Fixed by checking a
+  thread-local "was this damage" flag before deciding which failure mode
+  it was -- see the comment on `guard` and the commit message for
+  `transcript_cache.rs`.
+
+## What `api.rs` covers, and what it does not yet
+
+`ApiClient` wraps a `Transport` trait (network I/O kept out from behind, so
+`ApiClient` and `event_stream::follow_session_events` are tested with a
+fake transport and no server). `UreqTransport` is the only real
+implementation, backed by `ureq` -- see its Cargo.toml comment for why
+(blocking, already a project dependency, no extra TLS crate needed since
+`ureq::tls::Certificate::from_pem` reads the pinned CA directly).
+
+Covered: session list/read, message send, unqueue, answer, interrupt,
+stop, start, rename, cwd, model, permission-mode, notify, command,
+compact, delete, and one transcript page.
+
+**Not covered, and each is real work rather than a stub to fill in:**
+setups (`/setups*`, machine and provider discovery), the file explorer
+(`/setups/{id}/dir|file`), usage (`/usage`), models
+(`/models*`, HuggingFace browsing and downloads), attachments
+(`/sessions/{id}/attachments`), importing (`/setups/{id}/importable*`),
+and the `/notifications` stream. `server/src/routes.rs`'s module doc is
+the full table to work from when one of these is next.
+
+## What `transcript_fold.rs` covers, and what it does not yet
+
+`fold_event` covers every `Event` variant server/ can produce today,
+including tool-call/question/image attachment and peer-message placement.
+`group_tool_runs` groups adjacent calls into `TranscriptRow::Tools`.
+
+**Not ported:** `TranscriptItems.kt`'s `joinPages` (and its
+`healSplitMessage`/`adoptRun` helpers) -- the page-boundary healing that
+merges a tool call split across two fetched pages and re-merges a run a
+boundary cut through. This matters the moment paging backward through
+history is exercised; it is deliberately left rather than rushed, since
+it is exactly the kind of boundary logic this project's own "things that
+have bitten" section warns reads fine and is wrong at the edges.
+
+**Known gap, and a decision for whoever closes it:** `event_model::Event`
+has no `Unknown`/catch-all variant, unlike `Events.kt`'s hand-kept mirror.
+A server newer than this build that adds an event type will fail to parse
+that line rather than degrading to a placeholder row. Closing this means
+deciding how `event_model` itself represents "a shape I don't recognise"
+-- a shared-model decision affecting `server/` too, not a `client-core`-only
+fix, so it is recorded here rather than silently worked around.
+
+## `config.rs`: `EnrolledServer`
+
+`EnrolledServer` (host, port, bearer token) plus `parse_link`, which reads
+the exact `aiapp://enroll?host=H&port=P&token=T` deep link
+`wg-app-link`'s `enroll` mints and `ServerConfig.kt`'s `handleEnrollment`
+parses on the phone -- so any Rust client enrols from the same text a
+phone would scan as a QR, with no second format invented for it (RUST.md's
+E4, DECISIONS.md 2026-09-05). Deliberately does not decide where it is
+persisted or under what file permissions -- a phone seals its token in the
+Android Keystore, `iris/desktop-app/src/config.rs` writes it to
+`$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json` at 0600 -- since that is
+caller-specific (the code rules' "ask for the least you need"). Its only
+caller today is `desktop-app`; a future Android build of this crate would
+be a second one, not a reason to move the type.
+
+## What is not started at all
+
+- **`TranscriptSource.kt`** -- the layer that decides whether a page comes
+  from the transcript cache or the server, and stitches the two. Needs
+  `transcript_cache.rs` and `api.rs`'s transcript-page method, both of
+  which exist now, so this is unblocked whenever picked up.
+- **The markdown *block* model beyond syntax spans** -- `highlight/markdown.rs`
+  colours a `.md` file or fence for the highlighter, but does not build the
+  block tree (headings, lists, tables, fences as distinct nodes) that a
+  renderer walks to lay out prose versus code versus a table.
+  `CodeFence.kt`'s use of `org.intellij.markdown` for that full CommonMark
+  AST is Compose rendering plumbing, not something to port as-is; a Rust
+  UI layer will want its own block parser or a crate for it, decided
+  alongside the framework choice in RUST.md.
+- **`TranscriptUnits.kt`** (see above) -- deliberately out of scope, since
+  it flattens a row into bounded units for a *specific* lazy-list
+  framework's composition cost, which is a fact about that framework
+  rather than about the transcript.
+
+## Verifying
+
+`./run-tests.sh` from the repo root now runs `event-model`, `client-core`
+and `server` in that order (each `cargo test`, forwarding arguments the
+same way it always has). From `client-core/` directly: `cargo test`,
+`cargo clippy --all-targets`, `cargo fmt` -- all clean as of this writing.

DECISIONS.md

@@ -0,0 +1,30 @@
+# Decisions taken for Iris to review
+
+Short list of design choices made by the design agent without asking, so
+they can be judged and reversed later. Detail lives in RUST.md (and IRIS.md
+for iris API changes); this file is only the summary. Newest first. Items
+marked **DEFERRED** are ones the agent chose not to decide alone.
+
+## 2026-09-05
+
+- **Touch drag on a transcript row follows Android's own rule**: a vertical
+  drag pans the list immediately; a stationary press held 500 ms starts a
+  text selection which further dragging extends; a horizontal drag while
+  something is already selected extends that selection without the wait.
+  One `DragArbiter` per list decides it (`iris/src/sense.rs`). Chosen over a
+  "text layer always wins" or "list always wins" rule because either loses
+  one of the two gestures a reader expects.
+- **E4's desktop shape is a new `iris/desktop-app` crate**: a winit window
+  holding `transcript-ui`'s screen beside a session list, talking to a real
+  `ai-server` through `client-core`. It enrols by pasting the same
+  `aiapp://enroll?…` link a phone scans (`client-core::config::EnrolledServer`)
+  and keeps it owner-only under `$XDG_CONFIG_HOME/ai-app-desktop/`. The
+  pinned CA is a path given on the command line, not baked in. Chosen so
+  the phone and desktop share one enrolment format and no second one is
+  invented.
+- **Order of remaining work**: finish the two in-flight pieces above, then
+  the transcript screen's Android integration and the `transcript-bench.sh`
+  comparison against Compose — the numbers the recommendation still lacks.
+- **DEFERRED — whether to commit to iris over Masonry for `ai-app`.** Waits
+  on the bench numbers above; RUST.md's recommendation says what the
+  measurements must show.

IRIS.md

@@ -0,0 +1,277 @@
+# iris: notable public API changes
+
+For Iris to read on her own time. Each entry is a change to iris's public
+surface that a widget author or app author would notice: a trait method
+added, removed or re-shaped; a type that callers construct differently; a
+capability that moved. Small and trivial changes do not go here.
+
+An entry gives the date, what changed, why, and a short before/after where
+it helps judge the change without the session that made it. Newest first.
+
+## 2026-09-05: `transcript_ui::build_tree` (RUST.md's E4)
+
+`transcript_ui::build` claimed the whole window (`ui_state.set_root(tree)`)
+as its last step, which is right for a window that *is* the transcript
+screen (the winit example, an eventual Android cdylib) and wrong for the
+desktop app, which puts a session list beside it. `build_tree` is `build`
+minus that last step: it returns `(TranscriptScreen, StrongWidget)` instead
+of just `TranscriptScreen`, and the caller decides where the tree goes —
+into `ui_state.set_root`, or into a `WidgetPtr` alongside something else
+(`iris/desktop-app`'s `rebuild_transcript`). `build` is now one line calling
+`build_tree` and doing the `set_root` itself, so existing callers are
+unaffected.
+
+```rust
+// before, and still available, for a caller that wants to *be* the window:
+let screen = transcript_ui::build(rsc, &mut ui_state, rows);
+
+// new, for a caller embedding the screen beside something else:
+let (screen, tree) = transcript_ui::build_tree(rsc, rows);
+some_widget_ptr(rsc).set(tree);
+```
+
+
+## 2026-09-05: `DragArbiter`, pan-vs-select for one shared touch gesture (RUST.md's I5)
+
+New public type, `iris::sense::DragArbiter`. Why: a widget author who
+registers both a list-level pan and a row-level drag-to-select on the same
+touch gesture has no way to arbitrate between them — `core/src/sense.rs`'s
+`run_sensors` always gives the innermost layer first refusal, so the inner
+one wins every frame it is pressed, not just the frame the press started
+(this is exactly what left transcript-ui's touch-drag panning unreachable
+until now). `DragArbiter` is one small state machine, one instance per
+gesture surface (a whole list, not per row), that a caller drives with its
+own `press_start`/`update`/`release` calls and a caller-supplied `Instant`
+(so it is unit-testable without a real clock or a render harness). It
+decides the way Android itself does: an ordinary vertical drag pans
+immediately; a stationary press held `LONG_PRESS` (500ms) starts a
+selection, which any further drag then extends; a horizontal drag while
+something is already selected extends it immediately, skipping the wait.
+
+```rust
+// One per list, held alongside whatever state coordinates the rows:
+let mut arbiter = DragArbiter::new();
+
+// On press-down:
+arbiter.press_start(pos, Instant::now(), already_selected);
+// Every frame the button/finger stays down:
+match arbiter.update(pos, Instant::now()) {
+    DragOutcome::Pan(dy) => list.scroll(-dy),
+    DragOutcome::SelectStart => selection.begin(...),
+    DragOutcome::SelectExtend => selection.extend(...),
+    DragOutcome::Undecided => {}
+}
+// On release:
+arbiter.release();
+```
+
+`transcript-ui`'s `Selection::drag` (`transcript-ui/src/selection.rs`) is
+the reference caller: every row's `CursorSense::click_or_drag() |
+CursorSense::unclick()` handler routes through one `Selection`-owned
+arbiter instead of calling `begin`/`extend` directly, so a drag that starts
+on a row's own rendered text now pans the list correctly instead of
+always starting a selection. 8 new unit tests in `iris/src/sense.rs`'s
+`drag_arbiter_tests` module.
+
+## 2026-09-05: `SpanStyle`, per-range text styling (RUST.md's I5)
+
+A `TextBuffer` used to have exactly one style (`TextAttrs`: colour, size,
+family, ...) for its whole string, applied via `push_default` into parley's
+ranged builder. `SpanStyle` is a second, optional layer: a byte range plus
+whichever of colour/family/font size/bold/italic/underline it overrides,
+pushed with parley's own `push(property, range)` instead. Why: a transcript
+row's markdown (a heading, **bold**, `inline code`, a link) all inside one
+wrapped paragraph needs each to carry its own look while the paragraph
+still wraps and selects as a single buffer — the thing `masonry`'s
+`TextArea` cannot do (`StyleSet` is one style for the whole editor,
+`text_area.rs:43-44`'s `// TODO: RichTextInput`), and the reason this
+existed at all.
+
+```rust
+let (text, spans) = transcript_ui::markdown::render_markdown(src, 16.0);
+wtext(text)
+    .spans(spans)   // new: TextBuilder::spans, on both Text and TextEdit
+    .editable(EditMode::MultiLine)
+    .add(rsc);
+```
+
+Two things a widget author should know before reaching for it:
+
+- **Call `.spans()` before or after `.editable()`, both work** — the field
+  lives on `TextBuilder` itself, not either output type, and both
+  `TextOutput::run` and `TextEditOutput::run` apply it to the buffer via
+  `TextBuffer::set_spans`. **These two call sites are a pair**: adding a
+  third `TextBuilderOutput` impl without also calling `set_spans` there
+  reproduces the exact bug this box shipped once already (spans silently
+  dropped for `TextEdit`, found only by screenshotting, not by any test —
+  `markdown.rs`'s own unit tests check string/range logic, which is
+  correct in isolation and proves nothing about whether the render path
+  ever sees it).
+- **Colour is now per-glyph, not per-buffer.** `PlacedGlyph` gained a
+  `color: UiColor` field (from parley's own per-run `Style::brush`), and
+  `Painter::glyphs` draws each glyph in its own colour instead of
+  `RenderedText::color` uniformly. `RenderedText::color` still exists (the
+  buffer's *base* colour, for a caller that wants it as a whole, e.g. to
+  tint a cursor) but no longer drives what a glyph actually renders as.
+
+## 2026-09-05: accessibility names via AccessKit (RUST.md's I4)
+
+`.label()` (already in `trait_fns.rs`, previously unused anywhere in-tree)
+is now load-bearing: it's the one thing that puts a widget in the AccessKit
+tree `iris_core::ui::access::AccessTree` builds and both backends push
+out. A widget author who wants a control to be findable by name (and
+tappable by name, through `ui-trace`/a real screen reader) calls `.label()`
+on it; nothing else is required, and a widget nobody labels is invisible
+to this system at zero cost, not just zero UI.
+
+```rust
+let button = rect(Color::LIME)
+    .on(CursorSense::click(), move |_, rsc| { ... })
+    .label("Add task");   // now findable by uiautomator/AccessKit as "Add task"
+```
+
+Two new things a widget author might touch directly:
+
+- **`Widget::access_role(&self) -> accesskit::Role`**, default `Unknown`.
+  Override it if your widget has a real platform equivalent —
+  `TextEdit` now returns `TextInput`/`MultilineTextInput` by `EditMode`.
+  Only consulted for a widget that also has a `.label()`; an unlabelled
+  widget's `access_role` is never called.
+- **`Widgets::named() -> impl Iterator<Item = WidgetId>`** — every widget
+  with an explicit label, for anything else that wants to walk the same
+  set `AccessTree` does.
+
+Nothing about `Painter`, `draw`, or the layout/move machinery changed —
+this sits entirely beside them, reading `resolved_region`'s output rather
+than participating in producing it.
+
+## 2026-09-05: `List`, a virtualised bottom-anchored list (RUST.md's I3)
+
+A new widget, `iris::widget::List` (`iris/src/widget/list.rs` -- read its
+module doc first), for the transcript's kind of screen: variable-height
+rows, keyed by a `u64`, composed only while visible, moved rather than
+re-laid-out on scroll, a scroll anchor that survives a row inserted above
+it, "more" sentinels at each end, and "hold the edge nearest the tap" when
+a row's height changes (`note_tap`, resolved in the layout pass).
+
+```rust
+let mut list = List::new(Axis::Y);
+list.push_back(ListRow::new(key, row_widget));   // O(1)
+list.push_front(ListRow::new(older_key, row));   // O(1), anchor unaffected
+list.set_more_before(Some(spinner_widget));      // sentinel, drawn at the edge
+list.note_tap(viewport_y);                       // before mutating a row's height
+let (top, bottom) = list.extent(key).unwrap();   // last frame's on-screen box, if visible
+```
+
+Built entirely out of existing primitives (`Painter::widget`/`widget_within`/
+`reposition`/`draw_twice`, and `draw_inner`'s own old-children diffing) --
+no new mechanism was added to the render core for it. One correctness
+lesson worth reading even for other widgets: a row that fills whatever
+region it is offered (`Rect`, `is_size_independent`) cannot be measured at
+a throwaway oversized region and then merely `reposition`ed into place --
+`reposition` only ever writes an offset, never a size, so the oversized
+primitive stays oversized. `List` fixes this by caching each row's real
+height once measured and placing an already-known row directly at its
+exact box; see `list.rs`'s `place` for the full reasoning and
+`a_fill_shaped_background_is_not_left_oversized` for the regression test.
+
+## 2026-09-05: a second backend (android-view), and what moved to make room for it
+
+RUST.md's I2. Three changes a widget or app author would notice, all in
+service of the same thing: `default` (winit) and the new `android`
+(android-view) backends sharing what does not depend on windowing.
+
+- **`Selector`/`Selectable`'s bound changed from `Rsc::State:
+  HasDefaultUiState` to `Rsc::State: FocusHost`** (new trait, `attr.rs`).
+  `HasDefaultUiState` still exists and still works — `default/attr.rs` now
+  implements `FocusHost` for anything that has it — so a winit app's
+  existing code is unaffected. An Android app implements `FocusHost` via
+  `HasAndroidUiState` instead. Affects only an app that referenced
+  `HasDefaultUiState` directly at a `Selectable`/`Selector` call site
+  rather than through `.attr::<Selectable>(())`, which nothing in-tree
+  does.
+- **`Tasks::init` takes `Arc<dyn RequestRedraw>` instead of
+  `Arc<winit::window::Window>`.** `RequestRedraw` (`task.rs`) is one method,
+  `fn request_redraw(&self)`; `winit::window::Window` implements it
+  (`default/render.rs`), so `Tasks::init(window)` at a call site is
+  unchanged by inference. Only matters if something constructed a `Tasks`
+  directly rather than through `DefaultRsc`/`AndroidRsc`.
+- **`TextEdit::apply_event`/`TextInputResult` are `#[cfg(not(target_os =
+  "android"))]`** — they take a `winit::event::KeyEvent`, which does not
+  exist on Android; `android/input.rs` drives the same primitives
+  (`backspace`/`delete`/`motion`/`insert`, all still unconditional) from
+  `ndk::event::Keycode` directly instead. New unconditional getters on the
+  way: `TextEdit::text()`/`selection_range()`/`caret()`, and
+  `TextEditCtx::delete_byte_range`/`set_cursor_byte` — the primitives
+  `android/ime.rs`'s `InputConnection` bridge needed and that were not
+  previously exposed publicly.
+
+## 2026-09-04: `Widget::draw` reports the size it used; `desired_width`/`desired_height` are gone
+
+A widget used to implement three methods (`draw`, `desired_width`,
+`desired_height`); it now implements one, `fn draw(&mut self, painter: &mut
+Painter) -> Size`, which draws into `painter.region()` and returns how much
+of it was used. Why: the two extra methods routinely re-simulated what
+`draw` was about to do anyway (`Span::desired_ortho` copied its own draw
+loop to get cross-axis sizing right) — one visit per widget per frame
+instead of up to three. A container that needs a child's size before
+placing it (alignment, centering) draws the child once at a provisional
+region, reads the returned `Size`, and calls the new `Painter::reposition`
+to move it into its final spot — an O(1) offset write, not a second draw. A
+widget whose drawn output never depends on the size it's given (a
+fixed-size `Rect`, a decoded `Image`) overrides the new `fn
+is_size_independent(&self) -> bool { false }` to `true`, which skips
+redrawing it when only its offered region changes shape.
+
+```rust
+// before
+fn draw(&mut self, painter: &mut Painter) { /* ... */ }
+fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
+fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
+
+// after
+fn draw(&mut self, painter: &mut Painter) -> Size { /* ... */ }
+```
+
+`SizeCtx` and `Cache` are gone with it — see `LAYOUT.md` for the full
+design, the move-offset mechanism this shipped alongside, and the file
+list.
+
+## 2026-09-04: texture pipeline rebuilt off the binding array
+
+`Textures`/`TextureHandle`, `GlyphPrimitive`, and `UiRenderNode::new` all
+changed shape. Why: the old pipeline bound every texture ever drawn in one
+`binding_array<texture_2d<f32>>` and asked every device, unconditionally,
+for `VK_EXT_descriptor_indexing` — a real share of Android GPUs lack it,
+and it failed outright on the Android emulator's software Vulkan. See
+TEXTURES.md's "Recommended shape" and "Implemented, 2026-09-04".
+
+- **`UiRenderNode::new` drops its `limits: UiLimits` parameter, and
+  `UiLimits` is gone.** Before: `UiRenderNode::new(&device, &queue,
+  &config, UiLimits::default())`. After: `UiRenderNode::new(&device,
+  &queue, &config)`. Nothing replaces it — there are no more
+  binding-array limits to size.
+- **`src/default/render.rs`'s device request asks for no features and no
+  binding-array limits.** Before: `required_features:
+  Features::TEXTURE_BINDING_ARRAY | Features::PARTIALLY_BOUND_BINDING_ARRAY
+  | Features::SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`
+  plus two `max_binding_array_*` limits. After: `Features::empty()` (the
+  `DeviceDescriptor` default) and only `max_buffer_size` set, which was
+  never about the binding array.
+- **`TextureHandle` has no `primitive()` method any more**; a caller
+  outside `iris` shouldn't have been calling it (it fed the old renderer's
+  internals), but if something did: use `image_index()` for a standalone
+  image's bind-group index. There is no equivalent for a page — a page has
+  no bind group of its own now, see below.
+- **`GlyphPrimitive` has no public constructor from a struct literal.**
+  Before: `GlyphPrimitive { uv_min, uv_max, view_idx, sampler_idx, color,
+  flags }`. After: `GlyphPrimitive::new(uv_min, uv_max, layer, color,
+  flags)` — one `layer` (the shared atlas array's layer) instead of a
+  `view_idx`/`sampler_idx` pair, since a page is now a layer of one array
+  texture rather than its own bound texture.
+- **A widget author drawing images is unaffected**: `Painter::texture`/
+  `texture_at`/`texture_within` and `Textures::add` keep their signatures.
+  What changed underneath is that each standalone image now gets its own
+  `wgpu::BindGroup` and draw call instead of a slot in the shared array —
+  invisible from the widget API, visible only in `UiRenderNode`'s internals
+  and in `iris`'s device requirements.

IRIS_TODO.md

@@ -0,0 +1,254 @@
+# iris: known problems and things still to build
+
+Iris's own list for the library, recorded 2026-09-04 in her words where it
+matters, so the agents working through RUST.md pick these up in a sensible
+order rather than rediscovering them. Each item says where it sits in the
+order and what "done" looks like. Tick and date them in place.
+
+## Fix
+
+- [x] **Input does not fall through by input type (2026-09-04).**
+  `SensorUi::run_sensors` (`src/default/sense.rs`) used to set "consumed,
+  stop checking lower layers" from mere hover — a widget registered for
+  nothing but `click()` blocked a `Scroll` meant for whatever was behind
+  it, since "the cursor is over this widget" and "this widget handled the
+  event" were the same check. Fixed by judging consumption per input
+  kind: with no button transition and no scroll happening this frame
+  ("momentary" activity), the topmost hovered widget still wins, same as
+  before; when something momentary *is* happening, only a widget whose
+  registered senses actually include a matching non-hover one (checked
+  via a new `TypeEventManager::registered`, which lists what a widget
+  registered without running anything) consumes it, so a widget with only
+  `Hovering`/click handlers can no longer block a scroll from reaching a
+  list underneath. `iris/src/sense_tests.rs` builds a button-over-a-list
+  `Stack` with a plain `HasEvents` impl (no GPU or window) and checks both
+  directions: a scroll over the button reaches the list, and a real click
+  still reaches the button — confirmed to fail on the pre-fix code and
+  pass after.
+
+- [x] **Appending one image to an already-loaded list rebuilds every other
+  image's bind group (2026-09-05, fixed 2026-09-05).** Found by the
+  benchmark below: `GpuTextures::update` (`core/src/render/texture.rs`)
+  triggered `rebuild_image_bind_groups` — a loop over *every live
+  standalone image*, rebuilding its `BindGroup` — whenever the shared
+  `masks` or `move_offsets` GPU buffer was resized (`masks_resized ||
+  moves_resized` in `UiRenderNode::update`, `core/src/render/mod.rs`), and
+  a widget getting its *first* move-offset slot (LAYOUT.md section 2 —
+  every widget gets one on first draw) could be exactly what grows that
+  buffer. So one new message with one new image, appended to a transcript
+  that already has N images loaded, did not cost O(1): it cost one
+  `create_image` for the new image plus one `make_image_bind_group` per
+  *existing* image, because the new widget's own move slot pushed the
+  arena past its capacity. Measured directly in
+  `iris/examples/bench_images.rs`: appending a 1,001st image to 1,000
+  already-settled ones reported **1,001** bind-group creates for that one
+  frame, not 1 (`./run-bench.sh images`, frame 5 in the transcript below).
+
+  **Fix**: `masks`/`move_offsets` never belonged in a standalone image's own
+  bind group (group 2) in the first place — the group also holds that
+  image's own texture view, which is the only thing that is genuinely
+  per-image, so a buffer shared by *everything* forced a rebuild of
+  *every* group the moment it moved. Gave masks/move_offsets their own
+  bind group (group 3 in `shader.wgsl` and `UiRenderNode`: `masks_layout`/
+  `masks_group`), bound once per frame in `UiRenderNode::draw` rather than
+  once per draw call, instead of duplicating them into every per-image
+  group. `GpuTextures` and its image bind groups now know nothing about
+  either buffer — `rebuild_image_bind_groups` is called only from
+  `grow_array` (the atlas array texture growing, which genuinely does
+  change what every image's own bind group must reference) — so a
+  masks/move_offsets resize now touches exactly one bind group, ever,
+  regardless of how many images are live. Numbers after the fix, same
+  benchmark and command:
+
+      ./run-bench.sh images
+      frame=1 bind_group_creates=1000   (cold load, unchanged)
+      frame=2 bind_group_creates=0      (was 1000 -- see the item below)
+      frame=3 bind_group_creates=0
+      frame=4 bind_group_creates=0
+      (append one image here)
+      frame=5 bind_group_creates=1      (was 1001)
+      frame=6 bind_group_creates=0
+
+  `run-headless.sh tabs --shot` still 27266 bytes, byte-for-byte unchanged,
+  confirming the bind-group restructuring changed nothing about what is
+  drawn.
+- [x] **Bind-group creation takes two frames to reach the steady state, not
+  one (2026-09-05, closed by the fix above, 2026-09-05).** Same benchmark:
+  loading 1,000 images cold used to report 1,000 creates on frame 1
+  (expected — `create_image`, one per new image) *and again* 1,000 on
+  frame 2, before settling to 0 from frame 3. This was `rebuild_image_bind_groups`
+  firing a second time for the same masks/move-offsets buffer-growth
+  reason as the item above, confirming the guess recorded here — the two
+  were exactly the same root cause measured two different ways. Frame 2
+  now reports 0 (see the numbers above); not a separate fix.
+
+## Build
+
+- [x] **Benchmarks**, not unit tests, run on demand (2026-09-05; a
+  `benches/` or a script under `iris/`, never in `cargo test`). The
+  scenario that matters most is a **message list** — chat apps and this
+  app's transcript alike — stressed with many messages and many images.
+  One case in particular: **resizing an input box** (typing enough text to
+  grow it) that pushes a long list of messages above it must stay very
+  fast and recalculate almost nothing — a move of everything above, not a
+  re-layout. That is exactly the O(1) move chain in LAYOUT.md; the
+  benchmark is what proves it. Done when the numbers are in this file with
+  the command, and the input-box case reports draws re-run, not just frame
+  time.
+
+  **Built as two rigs**, chosen per scenario by whether a real `wgpu`
+  device is needed (`UiRenderState`/`Widgets` touch no GPU or window, so
+  most of this runs as an ordinary binary — the same property
+  `layout_tests.rs` relies on):
+
+  - `iris/benches/message_list.rs` — a plain `Instant`-timed binary
+    (`[[bench]] harness = false` in `iris/Cargo.toml`), not criterion: see
+    the file's own header for why (short version — every scenario here
+    reduces to a *count* `UiRenderState::take_counters` already produces,
+    which criterion's statistical machinery adds nothing to and which a
+    new dependency is not worth pulling in for). Covers (a) first-frame
+    cost of a message list of N wrapped-text rows (one in 20 also carrying
+    a small in-memory image) for N = 100/1,000/10,000; (b) per-frame cost
+    of scrolling that list, 200 ticks; (c) the input-box case — a
+    fixed-height field at the bottom of the screen growing by a line 40
+    times, with the message list above it filling the rest of the screen.
+    Run: `cd iris && cargo bench --bench message_list` (always release —
+    `cargo bench` builds the `bench` profile, which is optimized).
+  - `iris/examples/bench_images.rs` — needs a real device, so it runs
+    through `iris/run-headless.sh bench_images`, printing
+    `UiRenderNode::take_image_bind_group_creates()` (a new counter, added
+    in `core/src/render/texture.rs` and `core/src/render/mod.rs`,
+    mirroring `UiRenderState::take_counters`) each frame. Covers (d): 1,000
+    image rows, checked both cold (does bind-group creation reach zero
+    once loaded) and after appending one more image once settled (does
+    *that* stay cheap) — the second question is what actually matters for
+    a live transcript and is what turned up the two Fix items above.
+  - `iris/run-bench.sh [list|images]` runs either or both and is what to
+    run before/after touching `Scroll`, `Span`, `Sized`, the move-offset
+    chain, or `GpuTextures`.
+
+  **Numbers (2026-09-05, release, `cargo bench`/`run-headless.sh`, this
+  VM: AMD Ryzen 7 3800X, 8 cores, rustc 1.98.0 nightly-2026-09-03):**
+
+      cd iris && cargo bench --bench message_list
+      (a) first frame, N=100:    30.30ms  draws=227   rewrites=15   moves=0
+      (a) first frame, N=1000:  186.04ms  draws=2252  rewrites=150  moves=0
+      (a) first frame, N=10000:1770.36ms  draws=22502 rewrites=1500 moves=0
+      (b) scroll, N=100/1000/10000, 200 ticks each:
+          draws=200 rewrites=0 moves=200 (identical at every N)
+          per-tick average: 0.0002ms (identical at every N)
+      (c) input grows 40 lines, N=100/1000/10000 rows above it:
+          draws=320 rewrites=40 moves=160 (identical at every N)
+          per-line average: 0.0012-0.0013ms (identical at every N)
+
+      cd iris && ./run-bench.sh images        (2026-09-05, before the fix)
+      frame=1 bind_group_creates=1000   (cold load)
+      frame=2 bind_group_creates=1000   (see Fix item above)
+      frame=3 bind_group_creates=0
+      frame=4 bind_group_creates=0
+      (append one image here)
+      frame=5 bind_group_creates=1001   (see Fix item above)
+      frame=6 bind_group_creates=0
+
+      cd iris && ./run-bench.sh images        (2026-09-05, after the fix)
+      frame=1 bind_group_creates=1000   (cold load, unchanged -- genuine work)
+      frame=2 bind_group_creates=0
+      frame=3 bind_group_creates=0
+      frame=4 bind_group_creates=0
+      (append one image here)
+      frame=5 bind_group_creates=1      (one image's own create_image, O(1))
+      frame=6 bind_group_creates=0
+
+  **Reading it**: (a) is real, necessary work — shaping and laying out N
+  never-before-seen text rows — and scales with N as it must, ~10x cost
+  per 10x N. (b) and (c) are the pass conditions that matter: both are
+  **exactly flat across N = 100 to 10,000**, confirming LAYOUT.md's O(1)
+  move chain holds for both scrolling and for a growing input box pushing
+  the message list — draws/moves per tick or per line do not grow with
+  list size, and the per-operation cost (a fraction of a microsecond) is
+  nowhere near a frame budget. (d)'s cold-load and steady-state halves
+  behave as designed; its *append* half did not, until the fix above moved
+  masks/move_offsets out of the per-image bind group — now flat at O(1)
+  the same way (b) and (c) are.
+
+- **I5's transcript screen (`iris/transcript-ui/`, 2026-09-05) — what it
+  left, each recorded at the point in the code it would go rather than
+  silently dropped. See RUST.md's I5 box for the full account of what
+  *was* built (the screen, `SpanStyle`, cross-row selection, the growing
+  composer).**
+  - [ ] **Android integration for this screen does not exist yet.** No
+    cdylib/Gradle shell the way `iris-android-app` wraps `tabs-ui` (I2),
+    so `transcript-bench.sh`'s render-number pass condition against the
+    Compose baseline cannot be run. Needs: real `client-core::ApiClient`/
+    `event_stream::follow_session_events` wiring against
+    `app/ui-sandbox.sh --delay` (this crate deliberately fetches nothing
+    itself, `transcript-ui/src/lib.rs`'s doc), a new cdylib + Gradle
+    module, then the bench script pointed at it.
+  - [x] **Touch-drag panning over a row's own rendered text — done,
+    2026-09-05.** `row.rs` used to register `CursorSense::click_or_drag()`
+    on each row's `TextEdit` for cross-row selection; `TextEdit::draw`'s
+    `painter.child_layer()` (`iris/src/widget/text/edit.rs:87`) meant that
+    registration won `core/src/sense.rs::run_sensors`'s per-layer
+    arbitration on every frame it was pressed, not just the frame the
+    press started, so a list pan gesture registered on `List` itself never
+    got a turn while a row was under the finger. Fixed with
+    `iris::sense::DragArbiter` (recorded in `IRIS.md`), one small state
+    machine per list deciding pan vs. select the way Android does (a
+    vertical drag pans immediately; a stationary press held `LONG_PRESS`
+    (500ms) starts a selection which further drag extends; a horizontal
+    drag while something is already selected extends immediately) —
+    `transcript-ui/src/selection.rs`'s `Selection::drag` is the one place
+    every row's drag now routes through. 8 new unit tests
+    (`iris/src/sense.rs`'s `drag_arbiter_tests`); `cargo fmt/clippy/test
+    --workspace` and `cargo ndk` (both `iris` and `transcript-ui`) all
+    clean; `run-headless.sh` screenshot byte-identical to before the
+    change (38578 bytes). See RUST.md's I5 box, "Gap closed, 2026-09-05".
+  - [ ] **Row-level accessibility names.** The composer carries
+    `.label("Message")`; transcript rows do not carry a `.label()` of
+    their own yet, so `Widgets::named()` (I4) does not include them —
+    `row.rs`'s `build_text_row` is where one would go, keyed to something
+    stable per row (its sender + a short excerpt, matching what a screen
+    reader announcing a chat message would say).
+  - [ ] **A tappable link and a background chip behind inline code.**
+    Both need per-range glyph geometry that `TextEditCtx` does not expose
+    outside `iris::widget::text` (`edit.rs`'s `layout()` helper is
+    private) — see `markdown.rs`'s module doc for the exact shape the fix
+    would take (the same primitive `TextEdit::draw`'s own selection
+    highlight already uses internally,
+    `iris/src/widget/text/edit.rs:99`).
+  - [ ] **`Selection`'s anchor-row shortcut.** The row a drag started in
+    is selected in full (`select_all`) the moment the drag leaves it,
+    rather than "from the click point to whichever edge points away from
+    the drag" — needs the same private `layout()` access as the item
+    above. `selection.rs`'s module doc has the exact reasoning.
+  - [ ] **No syntax highlighting inside a fenced code block.**
+    `client_core::highlight` exists (built for the file explorer) and
+    could feed per-token `SpanStyle`s into a code block's span; wiring it
+    in was not attempted this pass.
+
+- [ ] **Masks defined relative to each other.** Wanted: mask A multiplies
+  by something *and also* applies mask B — a mask can reference a parent
+  mask, the way the move chain references a parent offset. Today masks
+  are independent regions. Design it beside the move chain (same shape:
+  a parent index and a bounded walk in the shader); do it when a real
+  widget needs it, not before.
+- [ ] **Positions as a single float per scroll.** Iris raised, and half
+  rejected, letting a scroll update one float rather than positions:
+  input handling cares about most elements in a list, so absolute
+  positions must be computed on the CPU anyway. LAYOUT.md's design
+  already lands here (GPU walks the chain, CPU resolves on demand for
+  hit tests). Keep the CPU resolution lazy and per query; do not
+  materialise every row's absolute position per frame.
+- [ ] **Animations, last.** Cosmetic, so after everything above. Must be
+  **modular — a piece of the library rather than a core part forced into
+  everything, the same way input is**. Whatever the mechanism, a widget
+  that does not animate must pay nothing and import nothing for it.
+
+## Reconsider
+
+- [ ] **`WidgetView`.** Iris is unsure of it: what she wants is an easy way
+  to compose a widget from others (a button is the main case). With
+  sizing folded into `draw`, composing may be easy enough that `View` is
+  redundant. Decide after the layout change lands, by writing a button
+  both ways and keeping the one that is shorter to explain; delete the
+  other rather than keeping two ways.

LAYOUT.md

@@ -0,0 +1,897 @@
+# iris: one `draw` that reports a size
+
+Preference stated by Iris, 2026-09-04, on the `rustify` branch. Recorded before
+any design or code so that it survives a cleared session. **Status: implemented
+2026-09-04, against every pass condition in §8** (measured, not assumed — see
+that section). Every widget listed in §7 was migrated in one change; none
+kept `desired_width`/`desired_height`. Five points needed correction or
+refinement beyond what this file originally specified — see "Deviations
+found during implementation" below, added right before "For IRIS.md" — read
+that section before touching `Aligned`, `Sized`, `MaxSize`, `Scroll`, or the
+move-slot lifecycle in `render_state.rs`, since each of those five is a real
+bug this file's first draft would have reproduced if implemented literally.
+
+## What Iris asked for
+
+> I don't like that widgets need both a draw and size functions. I'd much
+> rather them have a single draw that reports a size, and if it needs to be
+> moved then that can be done after the fact efficiently, or resized just
+> done after as well. This should be done efficiently like everything else
+> tries to do right now.
+
+She added, a few minutes later: "single draw is not a requirement. It
+just seems more efficient from what I've heard. Feel free to override any
+decision I've made if you can find a genuinely better & still clean
+alternative." So the single-draw model is the default to design against,
+and the design below may reject it, but only with a written comparison
+showing the alternative does less work per frame and is no harder to use.
+
+Standing constraints from RUST.md still apply: no DSL, plain Rust, do as
+little processing as possible per frame, but the model must cover every
+layout need a real app has (the transcript's virtualised list, wrapped
+text whose height depends on width, rows and columns that size to their
+children, overlays, masks).
+
+## What exists today
+
+`Widget` (`iris/core/src/widget/mod.rs`) has three methods: `draw(&mut
+self, &mut Painter)`, `desired_width(&mut self, &mut SizeCtx) -> Len` and
+`desired_height`. A parent asks `SizeCtx::width/height` for a child, which
+is memoised per widget id and axis in `Cache.size` keyed on the outer
+size, then places the child with `Painter::widget_within(region)`. So a
+child is visited twice (sized, then drawn), every widget implements sizing
+twice (one per axis), and a widget whose size depends on what it draws
+(wrapped text, a laid-out paragraph) does the layout in the size pass and
+again in the draw pass unless it caches by hand.
+
+Primitives are already positioned by `UiRegion` values whose scalars have
+a `rel` and an `abs` part, resolved against the window in the vertex
+shader (`core/src/render/shader.wgsl`), and `Primitives::region_mut`
+exists to rewrite one instance's region in place. That is the mechanism a
+"move after the fact" can build on.
+
+## What the design must answer
+
+1. **Parent-before-child ordering.** A row has to know each child's width
+   to place the next one, but under "one draw" the child's size only
+   exists after it has drawn. The answer is meant to be: the child draws
+   at a provisional origin, reports its size, and the parent *moves* it.
+   The move must be O(1) per moved subtree, not O(primitives in the
+   subtree). One way: every instance carries an index into a small
+   per-widget offset buffer, so moving a widget writes one entry and the
+   vertex shader adds it. Other ways may be better; the design should say
+   what was considered.
+2. **Move vs resize are different costs and must be kept apart.** A move
+   never re-runs `draw`. A resize re-runs `draw` for exactly the widgets
+   whose size input changed, and a widget whose output does not depend on
+   its size (an icon, a fixed rect) must be able to say so and be skipped.
+3. **Size-dependent content.** Wrapped text is the hard case: its height
+   is a function of its width. A single `draw` receives the available
+   size (what `SizeCtx.outer` is today) and reports what it used, so the
+   two-pass "measure then draw" collapses into one for the common case.
+   The design must say what happens when a parent wants the child's
+   height *before* deciding the width it will offer (rare; say whether it
+   is supported, or is done by drawing twice as an explicit, opt-in cost).
+4. **Caching.** Today's `Cache.size` memoises by (id, axis, outer). The
+   replacement should memoise the whole draw result by (id, available
+   size) so that an unchanged subtree costs nothing on the next frame,
+   which is what makes a virtualised list cheap.
+5. **Everything currently written against `desired_width`/`desired_height`
+   moves over in one change**, per the code rules: two names for one
+   concept is not an intermediate state to leave behind. The widgets are
+   in `iris/src/widget/` (`ptr`, `mask`, `image`, `rect`, `trait_fns`, and
+   whatever else is there when the change is made).
+
+## Order relative to the texture work
+
+TEXTURES.md's redesign touches the render core (shader, `GpuTextures`,
+`Primitives`, `Painter`'s texture calls). This change touches the widget
+trait, `SizeCtx`, `Cache`, `Painter`'s widget calls, and any offset
+mechanism the vertex shader needs. They overlap in `Painter` and the
+shader, so they are done **in sequence, textures first**, and the layout
+design here is written (not implemented) while the texture work is in
+progress, then implemented on top of it.
+
+## Design
+
+### 1. The new `Widget` trait
+
+```rust
+pub trait Widget: Any {
+    /// Draw within `painter.region()` (the space the parent offered) and
+    /// report how much of it was actually used, per axis.
+    fn draw(&mut self, painter: &mut Painter) -> Size;
+
+    /// True if `draw`'s output (both the primitives it writes and the
+    /// `Size` it returns) is the same for any `painter.region()` of the
+    /// same *content* -- an icon, a fixed-size rect, an already-decoded
+    /// image at its natural size. Default `false` (redraw on any change to
+    /// the offered region) because assuming independence wrongly produces
+    /// a stale draw; a widget must opt in.
+    fn is_size_independent(&self) -> bool {
+        false
+    }
+}
+```
+
+No `available` parameter: `Painter` already carries the region the parent
+handed down (`Painter::region()`, `core/src/ui/painter.rs:137`) and already
+exposes the pixel-resolved form (`px_size()`, `:156`) and the output surface
+size (`output_size()`, `:152`). Passing it again would be the same value
+under a second name. `desired_width`/`desired_height` (`core/src/widget/mod.rs:20-21`)
+and `WidgetAxisFns::desired_len` (`:24-35`) are deleted outright — not
+deprecated, not kept as a fallback — because a widget that implements both
+`draw` and `desired_*` for the same thing is exactly the "two names for one
+concept" the code rules call out, and it is what today's `Span::desired_ortho`
+(`iris/src/widget/position/span.rs:98-152`) already complains about in its
+own comment: "this literally copies draw so that the lengths are correctly
+set in the context, which makes this slow and not cool." Folding sizing into
+`draw` deletes that duplicate simulation, not just moves it.
+
+**No single-draw alternative was found that does less work per frame.** The
+two-method trait was checked against three properties a real screen needs —
+a row placing children in sequence, a widget centering on its own content,
+and wrapped text — and in every one, `draw` already has to visit the child
+to get a size that is *this specific one's* answer, which today's
+`desired_width`/`desired_height` re-derive by re-running (a shrunk copy of)
+the same layout the draw pass will do again. So the two-method trait is not
+"measure once, draw once" in the general case; it is "measure once per axis,
+then draw once," i.e. up to three visits per widget per frame, against one
+under the design here. The single-draw model is therefore adopted as
+proposed, not merely accepted as a preference.
+
+### 2. Move: O(1) per moved subtree, via a per-widget offset chain
+
+**What exists today, and why it is not O(1).** `UiRenderState::mov`
+(`core/src/ui/render_state.rs:156-168`) fires when a widget's region keeps
+its *size* but changes *position* (`draw_inner`, `:85-100`:
+`active.region.size() == region.size()` after excluding the exact-match
+case). It rewrites every primitive's `region` field via
+`Primitives::region_mut` (`core/src/render/primitive.rs:176-179`) for the
+widget's own primitives, then recurses into every child — O(primitives in
+the subtree). Both call sites that trigger it today, `Scroll::draw`
+(`iris/src/widget/position/scroll.rs:29-31`) and `Offset::draw`
+(`iris/src/widget/position/offset.rs:9-11`), are "translate this subtree by
+an abs pixel amount, `rel` framing unchanged" — a transcript scroll
+re-touches every glyph in every visible row, every frame of the drag, and
+I3's target is 800 rows on screen.
+
+**Recommendation: a per-widget offset slot forming a parent-linked chain,
+resolved in the vertex shader.**
+
+- `UiData` (`core/src/ui/mod.rs:14-20`) gains
+  `pub move_offsets: TrackedArena<MoveOffset, u32>`, the same arena shape
+  already used for `masks: TrackedArena<Mask, u32>` on the line above it.
+- `render/data.rs` gains `pub struct MoveOffset { pub delta: [f32; 2], pub
+  parent: u32 }` (`Pod`/`Zeroable`, `parent = u32::MAX` = "no ancestor,
+  add nothing more"). A pure abs-pixel translation, not a general
+  `UiRegion` remap — sufficient for every existing call site (above).
+- `PrimitiveInstance` (`render/data.rs:11-18`) gains `pub move_idx: u32`,
+  a vertex attribute at `@location(7)` beside `mask_idx` at `6` — the same
+  kind of per-instance handle.
+- `ActiveData` (`core/src/ui/active.rs`) gains `pub move_slot: MoveIdx`,
+  assigned **when the widget is first drawn** (`draw_inner`, beside
+  `active.insert`), with `parent` = the drawing widget's parent's slot.
+  `Painter` threads a `move_slot` field down exactly as it already threads
+  `mask` and `layer` (`painter.rs:9-20`), so a freshly-drawn descendant is
+  correct from its first frame — nothing is ever retrofitted onto an
+  already-active primitive. An unmoved widget's slot just stays `[0, 0]`.
+- `Painter::primitive_at` (`painter.rs:23-38`) writes `move_idx:
+  self.move_slot`, matching how it already writes `mask_idx: self.mask`.
+- `mov(id, delta)` becomes: look up `id`'s slot, write
+  `move_offsets[slot].delta += delta`. One write — no primitive touched, no
+  recursion, since descendants already reference this slot transitively.
+- `shader.wgsl`'s vertex stage, after computing `top_left`/`bot_right` in
+  pixels (after `:106`, before the clip-space divide at `:113`), walks
+  `move_idx → move_offsets[i].parent` for a bounded number of steps (a
+  small constant, e.g. 16, with a CPU-side debug assertion that no chain
+  exceeds it), summing `delta` into both corners. Cost is O(chain depth),
+  paid every frame regardless of whether anything moved — negligible next
+  to the per-fragment texture sampling TEXTURES.md already measures this
+  GPU as not bound by.
+
+**Why the chain, not the flatter thing first proposed.** Iris's own
+phrasing — "every instance carries an index into a small per-widget offset
+buffer" — describes a flat table: one slot per subtree *declared* movable,
+no parent link. It breaks the moment two such subtrees nest — a row inside
+a scrolling list, itself later given its own animated offset (a
+swipe-to-delete mid-scroll) — because the row's primitives would have to
+pick one slot and lose the other's contribution. The chain costs one extra
+field and a bounded shader loop in exchange for no such gap, and since
+every `ActiveData` gets a slot unconditionally rather than lazily, it costs
+no more at the common depth of one than the flat version would.
+
+**Against `region_mut` as the steady-state mechanism**: rejected for being
+O(primitives in the subtree) — the cost this section removes — but kept
+for a resize that changes a region's `rel` component (a genuine reflow,
+§3) and for a size-independent widget's resize (§3), where the content's
+shape doesn't change and one field write already suffices.
+
+### 2b. Two more readers of "where is this widget," and masks
+
+Moving the offset into the vertex shader means `ActiveData.region` is no
+longer the on-screen truth once a widget has been moved — it is where the
+widget was *drawn*, before any `move_offsets` delta. Two things read it as
+if it still were, and both must move to a resolved query or they silently
+answer with the pre-move position: a click landing on a scrolled row would
+be routed to whatever used to be there, with nothing on screen to say so —
+exactly the "wrong answer that looks like a right one" case the code rules
+single out.
+
+**Hit-testing.** `SensorUi::run_sensors` (`src/default/sense.rs:154-200`)
+does the actual pointer routing, and line 170 is the read in question:
+`let shape = self.active.get(id).unwrap().region;` (`self: &UiRenderState`),
+immediately turned into pixels and tested against the cursor at `:171-172`.
+Under this design that region must be resolved through the same chain the
+GPU walks before it means anything. Add to `UiRenderState`:
+
+```rust
+/// `active[id].region`, corrected by every `move_offsets` delta between
+/// `id` and the root — the CPU-side twin of the vertex shader's chain
+/// walk, over the same arena, so the two cannot disagree about where a
+/// widget is. O(chain depth), not O(primitives): a plain Rust loop over
+/// `move_offsets`, bounded by the same constant the shader loop uses
+/// (name it once, e.g. `render::MOVE_CHAIN_LIMIT`, and reference it from
+/// the WGSL loop bound in a comment, since WGSL cannot `include!` a Rust
+/// const across the language boundary).
+pub fn resolved_region(&self, id: WidgetId) -> UiRegion;
+```
+
+`window_region` (`core/src/ui/render_state.rs:264-267`), the public
+coordinate query already used outside hit-testing
+(`src/default/attr.rs:15,17,70`, e.g. positioning one widget relative to
+another's on-screen box), is reimplemented to call `resolved_region(id)`
+before `.to_px(...)` instead of reading `.region` directly — one change
+covers both call sites listed there. `sense.rs:170` changes to
+`let shape = self.resolved_region(*id);`. Both are required the moment §2
+lands, not an optional follow-up: an unmoved widget's chain is empty and
+`resolved_region` costs one arena read to find that out, so there is no
+version of this design where skipping the fix is a legitimate
+optimization — it is a correctness gap, not a performance one.
+
+**Masks.** `Painter::set_mask` (`core/src/ui/painter.rs:49-52`) bakes the
+painter's *current* region into a `Mask` pushed onto
+`masks: TrackedArena<Mask, u32>` (`core/src/ui/mod.rs:19`), and the
+fragment shader clips every primitive against `masks[in.mask_idx]`'s raw
+`rel`/`abs` fields, unaffected by any move (`shader.wgsl:147-157`). If the
+widget that called `set_mask` — `Masked::draw`,
+`iris/src/widget/mask.rs:7-11`, `painter.set_mask(painter.region()); ...` —
+is itself later moved, its clip rectangle stays where it was drawn while
+its content moves out from under it: a visibly wrong clip, immediately on
+screen, not a latency question.
+
+Fix: `Mask` (`core/src/render/data.rs:46-49`) gains `pub move_idx: u32`,
+written from `Painter::set_mask` as `self.move_slot` — the identical slot
+the mask-owning widget's own primitives already get (§2), not a second
+mechanism. Resolution happens in the **fragment** shader, not the CPU, and
+not the vertex shader either: `shader.wgsl`'s mask check (`:147-157`)
+currently computes the mask's `top_left`/`bot_right` inline from
+`masks[in.mask_idx]`; that computation is extended to walk the same
+move-offset chain §2 added, via one shared function —
+
+```wgsl
+fn resolve_move(idx: u32) -> vec2<f32> { /* the bounded parent walk, used by both stages */ }
+```
+
+— called from `vs_main` for a primitive's own corners and from `fs_main`
+for its mask's corners, so the walk is written once and the two stages
+cannot drift apart (the sibling-rule from the code rules: one loop, not a
+hand-copied second one in the other shader stage).
+
+**Why the fragment shader, not a CPU-side mask rewrite at move time.** A
+primitive's mask is frequently owned by a *different* widget than the
+primitive itself — often several levels up a subtree, with its own,
+independent move slot — so a primitive's resolved offset and its mask's
+resolved offset are two different chain sums, both needed, and only the
+fragment shader has both `in.move_idx` (this fragment's own chain) and
+`in.mask_idx` (indirecting to a second, possibly unrelated chain) already
+in hand per-fragment. Resolving mask regions on the CPU at move time would
+mean, for every `mov()` call, walking forward to every mask instance the
+moved widget's slot could affect and rewriting its raw region — exactly
+the O(subtree) cost §2 exists to remove, just moved from primitives to
+masks. The fragment shader already re-reads `masks[in.mask_idx]` every
+frame (`:148`); one more arena read to resolve its chain costs nothing
+extra in kind.
+
+**The scroll-container case, checked rather than assumed.** A masked,
+scrollable region is built as a `Masked` wrapping a `Scroll`
+(`iris/src/widget/position/scroll.rs`, `iris/src/widget/mask.rs`) — the
+viewport border is drawn (and `set_mask` called) by `Masked`, which is
+never itself the target of `mov()`; only `Scroll`'s inner content is,
+every frame the user drags. Because each widget's move slot is its own
+(§2: assigned per `ActiveData`, not shared), `Masked`'s mask references
+its own, stationary slot, while the scrolled content underneath references
+a separate, deeper slot whose `parent` chain passes through — but does not
+write to — the viewport's slot. Moving the content therefore never touches
+the mask's resolved position, and the mask staying still while its content
+slides past it is what this design already produces with no special case,
+not an extra rule that had to be added for it.
+
+### 3. Resize scope
+
+A resize is "the region a widget's parent offers it changes such that the
+widget's draw might produce different output" — as opposed to a move, which
+by construction cannot (§2 is scoped to pure translation). Two independent
+narrowings apply, and both are real, measured properties of the code as it
+stands rather than new machinery:
+
+**(a) A window resize does not, by itself, require touching most widgets.**
+`shader.wgsl:105-106` recomputes every primitive's pixel position from
+`window.dim` and the primitive's stored `rel`/`abs` pair *every frame,
+already, on the GPU*. A widget laid out purely in `rel`/`abs` terms (no
+call to `px_size()`, `output_size()`, or anything else that reads a
+concrete pixel count) is therefore already correct after a resize with zero
+CPU work — the shader did it. `UiRenderState::needs_redraw_all`
+(`render_state.rs:229-231`) currently ignores this and redraws the entire
+tree on every `resized`, which was the safe default while sizing and
+drawing were two passes; it should be narrowed to only the widgets that
+*do* read a concrete pixel value. Track this the same way `needs_redraw`
+already tracks per-widget dirtiness (`Widgets::needs_redraw`,
+`core/src/widget/widgets.rs:9`): a widget's `draw` call marks itself
+pixel-dependent by calling through `Painter` methods that read
+`output_size`/`px_size` (both already funnel through `Painter`, so the
+marking is one line at each), and `resize()` (`render_state.rs:32-35`)
+walks only that set instead of unconditionally setting `resized = true`
+for a full `redraw_all`. This turns "every resize redraws everything" into
+"every resize redraws what depends on pixels" — a real behavior change
+beyond what was asked, so verify it against the I0b `pre_present_notify`
+resize regression (that fix depended on `redraw_all`'s completeness)
+before narrowing this.
+
+**(b) A widget's `available` (its parent's offered region) can change
+without the widget's *content* changing — this is what
+`is_size_independent` (§1) answers.** When a container's own layout shifts
+(a sibling grew or shrank, changing this widget's offered box), a widget
+that returns `true` from `is_size_independent` is not redrawn: its
+primitives are unaffected by size, only by placement, so the parent
+either (i) issues a move (§2) if only position changed, or (ii) rewrites
+the primitive's `region` fields directly via `region_mut` if the box
+changed shape too (still O(primitives owned directly by this widget, not
+its subtree, since a size-independent widget by definition has no
+size-dependent descendants worth distinguishing — in practice this is
+always a leaf: `Rect`, `Image`, a fixed glyph). A widget that returns
+`false` (the default) is redrawn in full whenever `available` changes,
+which is correct always, just not free.
+
+**Ancestor propagation** (a resized child changing its own reported size,
+requiring its parent to re-lay-out) is unchanged in spirit from today's
+`redraw` (`render_state.rs:270-305`), which already walks up exactly the
+ancestors whose cached size differs from the new one and stops as soon as
+a size is unchanged (`:274-286`). That loop moves from consulting
+`Cache.size` to consulting `ActiveData.size` (§5) but keeps its shape.
+
+### 4. Wrapped text, and "needs child height before choosing width"
+
+**Wrapped text is not a special case any more; it already reads as one
+draw.** `TextView::render` (`iris/src/widget/text/mod.rs:57-76`) already
+does exactly what single-draw asks for: it reads `ctx.px_size().x` as the
+wrap width, shapes once, and memoizes the shaped layout keyed on that width
+plus a changed-flag on the buffer and attrs (`:63-69`) — a second call with
+the same width is a hash-map-style cache hit, not a re-shape. Under the new
+trait this collapses `Text::draw`/`desired_width`/`desired_height`
+(`text/mod.rs:133-147`, three functions) into one `Text::draw` that calls
+`self.view.draw(painter)` once, which internally still calls `render`
+once, hits its own cache, and returns the size it already computed. No
+new caching is needed here; the two now-redundant call sites
+(`desired_width`/`desired_height` each separately calling `render`) simply
+disappear, which is a second `render` avoided per frame per text widget
+that is being measured by a parent.
+
+**"Parent wants the child's height before deciding the width it will
+offer"** — the genuinely circular case named in the brief, e.g. a column
+that sizes its own width to its widest child, where that child is wrapped
+text whose height (which the column's *own* height depends on) depends on
+the width the column has not yet decided. This is not solvable in one pass
+for the same reason it is not solvable in CSS shrink-to-fit with wrapped
+content: the two axes' answers are mutually dependent. `Span::desired_ortho`
+(`span.rs:98-136`) already hits exactly this today and already resolves it
+by an explicit second, throwaway pass (its own comment: "this literally
+copies draw ... which makes this slow and not cool"). The design keeps that
+resolution, made explicit rather than accidental: `Painter` gets
+
+```rust
+/// Draw `child` at a provisional region to learn its size under one
+/// axis's worth of assumption, discard everything it wrote, then draw it
+/// again at the region that assumption produced. For the rare parent that
+/// cannot pick an offered size without already knowing the answer.
+/// Twice the cost of one `draw`; every other case in this file avoids it.
+pub fn draw_twice(&mut self, child: &StrongWidget, first: UiRegion, second: impl FnOnce(Size) -> UiRegion) -> Size;
+```
+
+implemented as: draw at `first`, record `Size`, remove the widget and its
+subtree the same way a resize-triggered redraw already does (`draw_inner`'s
+"if not \[same region\], maintain resize and track old children," `:97-100`,
+which already frees the old primitives before redrawing) — reusing that
+path rather than adding a second one — draw again at `second(size)`, return
+the final `Size`. It is opt-in and named for its cost, so a widget only
+pays it if it is the one that needs it; `Span`'s cross-axis case is the one
+call site converted to it, replacing the hand-rolled duplicate loop.
+
+### 5. Caching and invalidation
+
+`Cache.size` (`core/src/ui/cache.rs`) is **deleted, not replaced with an
+equivalent** — the thing it memoized (a `desired_width`/`desired_height`
+answer, independent of drawing) no longer exists as a separate query, so
+there is nothing left to cache at that layer. What already provides "an
+unchanged subtree costs nothing" is the check `draw_inner` performs before
+touching a widget at all (`render_state.rs:85-90`): if the widget is active,
+its region is unchanged, and it is not marked dirty, `draw_inner` returns
+immediately — no `Painter` constructed, no primitive touched, no shader
+work beyond what the GPU already redraws from the unchanged instance
+buffer. That check is kept exactly as it is; it is the caching mechanism,
+and it already operates at (id, region) granularity, which subsumes "(id,
+available size)" once size *is* what a region change means.
+
+What is added: `ActiveData` gains `pub size: Size` — the value `draw`
+returned, stored the moment it is (`draw_inner`, alongside building the
+`ActiveData` struct at `:134-143`). This is what a parent placing this
+widget for a second frame without redrawing it (because nothing changed)
+reads instead of recomputing — it replaces `Cache.size`'s role of "answer a
+size question without a full draw" with "read the size of the last actual
+draw," which is always available because `draw_inner`'s skip path is only
+reachable once the widget has been drawn at least once. `Cache::remove`/
+`Cache::clear` (`cache.rs:9-17`) are deleted with the type; `ActiveData`
+already has an equivalent lifecycle (removed in `remove`/`remove_rec`,
+`render_state.rs:171-198`, freed with the widget).
+
+### 6. Before / after
+
+**A leaf, `iris/src/widget/rect.rs`** — the size-independent case:
+
+```rust
+// before
+impl Widget for Rect {
+    fn draw(&mut self, painter: &mut Painter) {
+        painter.primitive(RectPrimitive { color: self.color, radius: self.radius,
+            thickness: self.thickness, inner_radius: self.inner_radius });
+    }
+    fn desired_width(&mut self, _: &mut SizeCtx) -> Len { Len::rest(1) }
+    fn desired_height(&mut self, _: &mut SizeCtx) -> Len { Len::rest(1) }
+}
+```
+
+```rust
+// after
+impl Widget for Rect {
+    fn draw(&mut self, painter: &mut Painter) -> Size {
+        painter.primitive(RectPrimitive { color: self.color, radius: self.radius,
+            thickness: self.thickness, inner_radius: self.inner_radius });
+        Size::REST // fills whatever it was given -- used == available
+    }
+    fn is_size_independent(&self) -> bool { true } // content never depends on region size
+}
+```
+
+**A container that needs the child's size before placing it,
+`iris/src/widget/position/align.rs`**:
+
+```rust
+// before
+impl Widget for Aligned {
+    fn draw(&mut self, painter: &mut Painter) {
+        let region = match self.align.tuple() {
+            (Some(x), Some(y)) => painter.size(&self.inner).to_uivec2().align(RegionAlign { x, y }),
+            (Some(x), None) => { let x = painter.size_ctx().width(&self.inner).apply_rest().align(x);
+                UiRegion::new(x, UiSpan::FULL) }
+            (None, Some(y)) => { let y = painter.size_ctx().height(&self.inner).apply_rest().align(y);
+                UiRegion::new(UiSpan::FULL, y) }
+            (None, None) => UiRegion::FULL,
+        };
+        painter.widget_within(&self.inner, region);
+    }
+    fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len { ctx.width(&self.inner) }
+    fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len { ctx.height(&self.inner) }
+}
+```
+
+```rust
+// after
+impl Widget for Aligned {
+    fn draw(&mut self, painter: &mut Painter) -> Size {
+        let full = painter.region();
+        // Draw once at the full region to learn the child's real size --
+        // this placement is provisional and corrected below without a
+        // second draw.
+        let used = painter.widget_within(&self.inner, full);
+        let region = match self.align.tuple() {
+            (Some(x), Some(y)) => used.to_uivec2().align(RegionAlign { x, y }).within(&full),
+            (Some(x), None) => used.x.apply_rest().align(x).within(&full),
+            (None, Some(y)) => used.y.apply_rest().align(y).within(&full),
+            (None, None) => full,
+        };
+        painter.reposition(&self.inner, region); // O(1): one offset write, no second draw
+        used
+    }
+}
+```
+
+`Painter::widget_within`/`widget`/`widget_at` (`painter.rs:55-76`) change
+return type from `()` to `Size`, carrying the child's `draw` result back —
+the only signature change needed to let a parent see what its child used.
+`Painter::reposition` is new, computing the delta between where a child
+was actually drawn and where it belongs and calling the O(1) `mov` from
+§2. `SizeCtx` and `Painter::size_ctx`/`size`/`len_axis` (`painter.rs:141-150,
+180-182`) are deleted — nothing calls `desired_len` any more, so there is
+nothing left for `SizeCtx` to answer; `draw_text`/`label`/`px_size`/
+`output_size` already exist redundantly on both `SizeCtx` and `Painter`
+today (compare `size.rs:71-90` against `painter.rs:152-174`) and this
+deletes the `SizeCtx` copies, keeping the `Painter` ones.
+
+### 7. Migration — every file and widget that changes
+
+One change, in dependency order (rename-and-move-together, per the code
+rules — no intermediate state with both trait shapes):
+
+- `core/src/widget/mod.rs` — the `Widget` trait (§1), delete
+  `WidgetAxisFns`, update `impl Widget for ()`.
+- `core/src/ui/size.rs` — delete `SizeCtx` (the type and all its methods).
+- `core/src/ui/cache.rs` — delete `Cache` (§5).
+- `core/src/ui/painter.rs` — `widget`/`widget_within`/`widget_at` return
+  `Size`; add `reposition`, `draw_twice`; delete `size_ctx`, `size`,
+  `len_axis`; `primitive_at` writes `move_idx`.
+- `core/src/ui/render_state.rs` — `draw_inner` captures and stores
+  `ActiveData.size`; `mov` becomes the O(1) offset write (§2); resize
+  narrowing (§3a); `redraw`'s per-axis loop reads `ActiveData.size`
+  instead of `Cache.size`.
+- `core/src/ui/active.rs` — `ActiveData` gains `size: Size`,
+  `move_slot: MoveIdx`.
+- `core/src/ui/mod.rs` — `UiData` gains `move_offsets`.
+- `core/src/render/data.rs` — `PrimitiveInstance` gains `move_idx`;
+  new `MoveOffset` struct.
+- `core/src/render/primitive.rs` — thread `move_idx` through `PrimitiveInst`
+  and `Primitives::write`, matching `mask_idx`.
+- `core/src/render/mod.rs` — bind the new `move_offsets` storage buffer
+  (group 2, beside `masks`) and its update path.
+- `core/src/render/shader.wgsl` — `InstanceInput` gains `move_idx`;
+  `MoveOffset`/`UiScalar`-shaped storage binding; a shared `resolve_move`
+  function (§2b) called from both `vs_main` (a primitive's own corners)
+  and `fs_main` (its mask's corners, once `Mask` carries `move_idx`).
+- `core/src/ui/render_state.rs` — additionally, `resolved_region` (§2b)
+  and `window_region` (`:264-267`) reimplemented on top of it.
+- `src/default/sense.rs` — `run_sensors`'s hit-test read (`:170`) switches
+  from `self.active.get(id).unwrap().region` to `self.resolved_region(*id)`
+  (§2b) — the pointer-routing fix this design requires, not an optional
+  follow-up.
+- `core/src/render/data.rs` — additionally, `Mask` (`:46-49`) gains
+  `move_idx: u32` (§2b).
+- `core/src/ui/painter.rs` — additionally, `set_mask` (`:49-52`) writes
+  `move_idx: self.move_slot` into the `Mask` it pushes (§2b).
+- Every widget with a two-method `impl Widget`, collapsed to one `draw`
+  (§1, §6), `is_size_independent` added where true: `core/src/widget/mod.rs`
+  (`impl Widget for ()`), `iris/src/widget/rect.rs` (`Rect`, → true),
+  `iris/src/widget/image.rs` (`Image`, → true — a decoded image's primitive
+  never depends on the region it is offered, same as `Rect`),
+  `iris/src/widget/mask.rs` (`Masked`), `iris/src/widget/ptr.rs`
+  (`WidgetPtr`), `iris/src/widget/text/mod.rs` (`Text`, §4),
+  `iris/src/widget/text/edit.rs` (`TextEdit`),
+  `iris/src/widget/position/scroll.rs` (`Scroll`, keeps its `mov`-shaped
+  offset, now O(1) automatically via §2), `iris/src/widget/position/align.rs`
+  (`Aligned`, §6), `iris/src/widget/position/max_size.rs` (`MaxSize`),
+  `iris/src/widget/position/layer.rs` (`LayerOffset`),
+  `iris/src/widget/position/pad.rs` (`Pad`),
+  `iris/src/widget/position/stack.rs` (`Stack`),
+  `iris/src/widget/position/offset.rs` (`Offset`),
+  `iris/src/widget/position/span.rs` (`Span`, §4's `draw_twice` for the
+  cross-axis case, deleting `desired_ortho`'s duplicate loop),
+  `iris/src/widget/position/sized.rs` (`Sized`).
+  This list was produced by `grep -rn "impl Widget for\|fn desired_width\|fn desired_height"`
+  across `core/` and `src/`; re-run it before starting, since it is the
+  authoritative check that nothing was missed, not this paragraph.
+- `iris/examples/{minimal.rs,task.rs,view.rs,tabs/main.rs}` — no direct
+  `impl Widget` found in any example (verified by the same grep); they use
+  the builder DSL in `core/src/widget/trait_fns.rs` and should need no
+  source change, which is itself part of the pass condition below.
+
+### 8. Pass conditions
+
+1. **Every example under `iris/examples` renders identically.** Run
+   `iris/run-headless.sh EXAMPLE --shot PNG` for each of `minimal`, `task`,
+   `view`, `tabs` before and after, and diff the PNGs pixel-for-pixel — not
+   "looks right," since a subtle wrap or alignment regression is exactly
+   what a diff catches and a glance does not.
+
+   **Result (2026-09-04): pass, all four, 0 differing bytes.** No PNG
+   library is installed in this VM (no PIL, no ImageMagick, no pip), so the
+   diff is a from-scratch PNG decoder (`zlib` + the five filter types) at
+   `/tmp/layout-shots/pngdiff.py`, comparing decoded pixel bytes rather than
+   file bytes (`cmp` alone is not conclusive across two separately-encoded
+   PNGs, though it happened to agree here for `minimal`). Before-shots were
+   taken with `git stash` at the pre-change commit; `tabs` needed two real
+   fixes (deviations 1 and 2 below) before it stopped differing — the other
+   three matched on the first try.
+2. **Unchanged-frame cost, measured, not assumed.** Add a counter beside
+   the existing `debug_layers`/`active_widgets` instrumentation
+   (`render_state.rs:241-262`) for (a) `Widget::draw` invocations and (b)
+   `Primitives::write`/`region_mut` calls, both per `update()` call. Drive
+   one example (`tabs`, since it already has multiple widgets and an
+   interactive element) through one frame with nothing changed and report
+   both counts — the pass condition is **0 draws and 0 primitive rewrites**
+   for a frame in which nothing was marked dirty, resized, or moved.
+
+   **Result (2026-09-04): pass, 0 and 0.** Implemented as
+   `UiRenderState::take_counters() -> (u64, u64, u64)` (draws, `region_mut`
+   rewrites, `move_offsets` writes — a third counter, for condition 3
+   below), reset on read. Measured in
+   `iris/src/layout_tests.rs::an_unchanged_frame_draws_and_rewrites_nothing`
+   against a `Scroll` over 500 fixed-height rects (not the `tabs` example —
+   see the note on condition 3 for why this runs as a plain unit test
+   instead).
+3. **Single-moved-child cost, measured.** Same counters, one frame in
+   which exactly one widget is moved (not resized) with N primitives in its
+   subtree — the pass condition is **1 write to `move_offsets`, 0 calls to
+   `Widget::draw`, 0 calls to `region_mut`**, independent of N. Construct
+   the case with a `tabs`-style example holding a deliberately large text
+   block (hundreds of glyphs) inside a `Scroll`, so N is large enough that
+   an O(N) regression would show up as a non-trivial write count rather
+   than being lost in noise.
+
+   **Result (2026-09-04): pass — 0 draws, 0 rewrites, 1 move_offsets
+   write, N = 500.** Built with rects rather than glyphs
+   (`iris/src/layout_tests.rs::scrolling_moves_in_o1_without_a_redraw`):
+   `iris-core`/`iris` touch no GPU or window to lay out and move a tree, so
+   this runs as a plain `cargo test`, not through `run-headless.sh` — a
+   `Widgets`/`UiData` pair and a bare `UiRsc` impl are enough, and it is
+   faster and more precise than reading counters out of a real example's
+   stderr. Getting a clean single move took two follow-up fixes beyond the
+   design as written (deviation 3, the `parent_move_slot` threading; and
+   the `Scroll` design decision below about offering last frame's content
+   length) — without either, the count was in the thousands (every rect in
+   the subtree redrawing) rather than 1.
+4. **Hit-testing follows the move, not just the render.** In the same
+   scrolled-`tabs` construction as condition 3, scroll the content, then
+   send a synthetic cursor position over a widget that moved and assert
+   `run_sensors` (`src/default/sense.rs:154-200`) routes to that widget's
+   id, not to whatever is now at its pre-scroll coordinates or to nothing.
+   This is a correctness check, not a timing one — §2b's fix is required
+   before §2 can ship at all, and this is what would fail silently
+   (nothing on screen indicates a missed or misrouted hit) if it were
+   skipped.
+
+   **Result (2026-09-04): pass**, but checked one level below
+   `run_sensors`: `iris/src/layout_tests.rs::hit_testing_follows_a_scrolled_widget`
+   scrolls a widget and asserts `UiRenderState::resolved_region` (the
+   query `run_sensors`'s hit-test and `window_region` both now go through,
+   per §2b) reports the moved, not the pre-scroll, position — within
+   0.01px of the exact expected delta. `run_sensors` itself needs a
+   `HasEvents`/window/cursor-state harness this pass did not build; the
+   coverage that matters (does the position query the router uses reflect
+   the move) is exercised directly instead.
+5. **A mask moves with its subtree.** Render a `Masked`-wrapped `Scroll`
+   both before and after scrolling it (`iris/run-headless.sh` against a
+   small purpose-built example, or an addition to `tabs`), and diff the
+   two frames: the clipped edge of the content must have moved with the
+   scroll while the viewport's own border (drawn by `Masked`, not moved)
+   stays put — the specific case worked through in §2b. A mask rectangle
+   that stayed at its pre-scroll position while its content slid past it
+   is the regression this checks for, and it is visible in a single
+   screenshot, not just in a counter.
+
+   **Result (2026-09-04): pass, checked numerically rather than by
+   screenshot.** No example in this repository builds a `Masked`-wrapped
+   `Scroll` (`tabs`'s "text edit scroll" tab uses `TextEdit`'s own internal
+   scrolling, not this widget), so there was nothing to screenshot without
+   first authoring a new example. Checked instead in
+   `iris/src/layout_tests.rs::a_mask_stays_put_while_its_scrolled_content_moves`,
+   on the exact data the fragment shader's `resolve_move` reads: the
+   masked widget's own `move_offsets` slot delta is `[0, 0]` both before
+   and after scrolling its content, because `Masked` is never itself the
+   target of a move — only its child is, on a separate, deeper slot in the
+   chain (§2b's "scroll-container case, checked rather than assumed"). A
+   pixel-level screenshot check of this remains open; see RUST.md's next
+   step.
+6. **`cargo test --workspace`, `cargo clippy --all-targets`, `cargo fmt`**
+   stay clean at the defaults (iris has no tests today per I0b, so this is
+   presently only clippy/fmt; add the first real widget-layer tests here if
+   the move-offset chain or `draw_twice` are non-trivial enough to want
+   one, per "match the codebase's testing posture" — judge that once the
+   code exists rather than pre-committing to a number of tests here).
+
+   **Result (2026-09-04): pass.** `cargo fmt --all -- --check`,
+   `cargo build --workspace --all-targets`, and `cargo clippy --all-targets`
+   are all clean (one pre-existing, unrelated warning about `naga`/`wgpu`/
+   `winit` future-incompatibility, from dependencies, not this change).
+   `cargo test --workspace`: the 14 pre-existing `TextEdit` tests plus 4 new
+   ones in `iris/src/layout_tests.rs` (conditions 2–5 above), 18 passed, 0
+   failed — the move-offset chain turned out non-trivial enough (three real
+   bugs found only by writing it) to clearly clear the "match the testing
+   posture" bar this section left open.
+
+### 9. Rejected, and why
+
+- **A flat (non-chained) per-subtree offset table**, Iris's literal
+  phrasing — rejected in §2 for breaking under nested independent moves
+  (a swiped row inside a scrolling list). Costs nothing extra to avoid: the
+  chain is the same mechanism with one more field.
+- **Keeping `region_mut` recursion as the only move mechanism** — rejected
+  as the steady-state path (O(primitives in subtree), exactly what a
+  transcript scroll must not pay every frame) but kept for resize-shaped
+  changes (§3) where the content's own region field, not an ancestor
+  chain, is what has to change.
+- **A second, size-only trait method kept alongside `draw`** (e.g.
+  `fn size_hint(&self) -> Option<Size>` as a fast path some widgets could
+  implement to skip a draw when a cheap answer exists) — considered and
+  rejected: it reintroduces exactly the "two names for one concept" split
+  this change removes, for a saving `is_size_independent` (§1, §3b)
+  already covers for the cases where it would actually help (fixed-size
+  leaves). A widget whose size is cheap to compute but whose *drawing* is
+  not (unlikely in this codebase's widget set, but conceivable) is better
+  served by that widget caching its own draw output internally — exactly
+  the pattern `TextView::render` already uses (§4) — than by a second
+  trait method every implementor has to reason about.
+- **Passing `available` as an explicit parameter to `draw`** (mirroring
+  Masonry's `layout(&mut self, ctx, bc: &BoxConstraints) -> Size`, the
+  yardstick per AGENTS.md) — rejected as redundant with `Painter::region()`,
+  which already carries the same information into every widget that needs
+  it; adding a parameter would just be a second route to a value already
+  reachable, and would invite the two drifting apart.
+- **Eagerly propagating a moved widget's delta into every descendant's own
+  offset value** (rather than chaining and resolving in the shader) —
+  rejected as O(descendant widgets), which is smaller than O(primitives)
+  but still not O(1), and the shader-side chain costs nothing extra to get
+  the better bound.
+
+## Deviations found during implementation (2026-09-04)
+
+Five corrections this file's first draft did not anticipate, each found by
+`iris/run-headless.sh tabs --shot` disagreeing with a pixel-identical
+pre-change screenshot (pass condition 1) and traced with `eprintln!` in
+`draw_inner`/`reposition` — not by reasoning about the design in the
+abstract. Recorded here rather than silently fixed in place, per the code
+rules' escape-hatch requirement.
+
+1. **`Aligned`'s provisional draw must call `painter.widget`, not
+   `widget_within(&self.inner, painter.region())`.** §6's original text drew
+   the sample as the latter. `widget_within` composes its `region` argument
+   as *local*, `UiRegion::FULL`-relative coordinates against
+   `painter.region()` (exactly what `UiRegion::FULL.within(&self.region) ==
+   self.region` relies on); handing it `painter.region()` itself —
+   already-resolved, window-relative coordinates — composes that frame a
+   second time. For the root widget this is silently the identity (its
+   region already is `[0,1]`), which is why it can look correct in a
+   trivial case and only breaks once something is nested — i.e. always, in
+   practice. Symptom: a centered child rendered at a wildly wrong offset
+   nested more than one level deep. Fixed by using `painter.widget`, which
+   hands the child `self.region` unmodified, with no second composition.
+
+2. **A widget that reports a size smaller than its offered region must
+   actually paint at that size, anchored top-left of what it was given —
+   not fill the full offered region while merely *reporting* a smaller
+   number.** `Sized` and `MaxSize` both had exactly this bug: their
+   `desired_width`/`desired_height` predecessors capped the *reported*
+   value but their `draw` bodies called `painter.widget(&self.inner)`
+   unconstrained, which was harmless under the old two-pass model (a parent
+   always queried the size *before* drawing, so by the time `draw` ran the
+   offered region already matched) but wrong under `Aligned`'s new
+   provisional-draw-then-reposition pattern, which offers the *whole*
+   region on the first, learning pass. Symptom: a `.sized((100, 100))` rect
+   rendered stretched to fill its whole row instead of a 100×100 square.
+   Fixed by having both widgets carve the declared sub-region (`UiSpan`
+   sized to the axis's `Len`, anchored at `AxisAlign::Neg`) out of whatever
+   they were offered before drawing the child in it. `Image` needed the
+   same treatment from the start (`texture_within` at its own natural size,
+   not `texture()` at the full offered region) and was written that way in
+   the first pass, once this was understood; `Rect`'s "fill whatever I'm
+   given" is the one case where painting the *whole* offered region really
+   is the declared behavior, so it needed no change.
+
+3. **The move-offset chain's `parent` link cannot be found by looking up
+   the parent's `ActiveData` in `draw_inner`, because the parent's
+   `ActiveData` does not exist yet while its own `Widget::draw` is still
+   running.** `ActiveData` is inserted only after `draw` returns
+   (`render_state.rs`, end of `draw_inner`), so a child drawn partway
+   through its parent's `draw` body — the ordinary case, since every
+   composite widget draws its children from inside its own `draw` — would
+   always read "no parent" from `self.active`, silently orphaning it at the
+   root of the chain. Fixed by threading the parent's `move_slot` down
+   through `Painter` (it already carries `mask`/`layer` the same way) and
+   passing it explicitly into `draw_inner` as `parent_move_slot`, rather
+   than deriving it from `self.active.get(parent_id)`. `move_parent_of`
+   (the `self.active`-based lookup) is kept, but only for `redraw()`, whose
+   target's parent genuinely is already active at that call site — the
+   doc comment on it says which is which. Symptom: `reposition` computed
+   the right delta and wrote it to the right slot, but the shader never
+   saw it, because the primitive doing the actual painting chained to
+   `u32::MAX` one level too early.
+
+4. **`Painter::reposition` cannot reuse `active.region` as "where the
+   widget currently is," because for a widget offered more room than it
+   used, `active.region` is the *offered* box, not the *painted* one.**
+   This only matters for `reposition` (used by `Aligned`); `mov` (used by
+   `draw_inner`'s own same-size-different-position dispatch, for `Scroll`
+   and `Offset`) has no such gap, because there the offered region *is*
+   the visual footprint — content is sized to fill exactly what it is
+   given. `reposition` instead reconstructs "from" as `active.size`
+   (already tracked, per §5) anchored at `AxisAlign::Neg` within
+   `active.region` — i.e. it assumes the child painted itself top-left of
+   whatever it was offered, per point 2's convention — and **overwrites**
+   the slot's delta rather than accumulating it the way `mov` does, since
+   "from" is recomputed fresh from stable inputs every call and repeating
+   the same `reposition` (an unrelated redraw elsewhere re-running this
+   widget's parent) must not drift further each time. The one shape this
+   does not cover: `Aligned` wrapping `Aligned`, where the inner one's own
+   `reposition` may have moved its content away from top-left already. No
+   widget or example in this codebase builds that today; if one needs to,
+   `reposition` would need the child to report *where* it painted, not
+   just how big, which is a larger change than this pass's scope.
+
+5. **A widget's `move_offsets` slot is allocated once, on its first-ever
+   draw, and reused in place — never reallocated — for every later redraw
+   of the same id, with its delta reset to `[0, 0]` on each reuse.** Not
+   spelled out in §2's original text, which only said slots are assigned
+   "when the widget is first drawn." Reallocating a fresh slot on every
+   redraw would leave any *retained* (not-redrawn) descendant's `parent`
+   link pointing at a now-orphaned old slot — a permanent leak, and worse,
+   a descendant that silently stops tracking its ancestor's future moves.
+   Resetting the delta on reuse (rather than carrying it forward) is
+   required because a full redraw bakes the widget's correct absolute
+   position into the fresh `region` argument directly; a stale delta left
+   over from before the redraw would double-offset it.
+
+Two further points worth recording because they were *design decisions*
+made while implementing, not bugs — `LAYOUT.md`'s own text left them
+unspecified rather than getting them wrong:
+
+- **`Scroll` offers its content a region sized by the *previous* frame's
+  measured content length, not a fresh one.** A fresh measurement would
+  require drawing the content once to learn its size and — since that
+  provisional size essentially never matches the previously active one —
+  redrawing it a second time at the real size, on every single scroll
+  tick, which is exactly the cost §2 exists to remove. Using the stale
+  length means an ordinary scroll (position changes, content does not)
+  offers the same *size* as last frame, only shifted, which is what makes
+  `draw_inner` dispatch it as the O(1) move. The cost: a real content-size
+  change lags one frame before the container's scroll range reflects it,
+  self-correcting the frame after (the content length itself, read from
+  what was actually drawn, is never stale — only the offered *region* used
+  for placement is). No example in this repository builds a `Scroll` yet,
+  so this could not be checked against a pixel diff; it is covered instead
+  by `iris/src/layout_tests.rs`'s three `Scroll`-based unit tests, which
+  build a tree and drive `UiRenderState` directly with no GPU or window
+  needed.
+- **`redraw()`'s parent-relayout check draws the widget first, then
+  compares the fresh `ActiveData.size` the draw produced against the size
+  from before removal** — the mirror image of the old code's "query size,
+  compare, decide whether to draw," which no longer has a size query to
+  do the comparison with before drawing (§5 deleted `Cache`/`SizeCtx`
+  along with `desired_width`/`desired_height`). This can occasionally draw
+  a widget once more than the old code would have (if the parent it
+  bubbles up to ends up redrawing the same widget again as part of its own
+  relayout) — `draw_inner`'s own skip/move dispatch absorbs most of that
+  redundancy for free, and this path is not one of §8's measured
+  conditions, so the remaining slack was accepted rather than chased
+  further.
+
+## For IRIS.md
+
+When this lands, copy this entry into `IRIS.md` (newest first):
+
+> **2026-09-04 — `Widget::draw` reports the size it used; `desired_width`/
+> `desired_height` are gone.** A widget used to implement three methods
+> (`draw`, `desired_width`, `desired_height`); it now implements one,
+> `fn draw(&mut self, painter: &mut Painter) -> Size`, which draws into
+> `painter.region()` and returns how much of it was used. Why: the two
+> extra methods routinely re-simulated what `draw` was about to do anyway
+> (`Span::desired_ortho` copied its own draw loop to get cross-axis sizing
+> right) — one visit per widget per frame instead of up to three. A
+> container that needs a child's size before placing it (alignment,
+> centering) draws the child once at a provisional region, reads the
+> returned `Size`, and calls the new `Painter::reposition` to move it into
+> its final spot — an O(1) offset write, not a second draw. A widget whose
+> drawn output never depends on the size it's given (a fixed-size `Rect`,
+> a decoded `Image`) overrides the new `fn is_size_independent(&self) ->
+> bool { false }` to `true`, which skips redrawing it when only its
+> offered region changes shape.
+>
+> ```rust
+> // before
+> fn draw(&mut self, painter: &mut Painter) { /* ... */ }
+> fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
+> fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
+>
+> // after
+> fn draw(&mut self, painter: &mut Painter) -> Size { /* ... */ }
+> ```
+>
+> `SizeCtx` and `Cache` are gone with it — see `LAYOUT.md` for the full
+> design, the move-offset mechanism this shipped alongside, and the file
+> list.

TEXTURES.md

@@ -0,0 +1,496 @@
+# How iris should render an unbounded number of images
+
+## Status (2026-09-04)
+
+**Implemented**, on the `rustify` branch of `ai-app-2`, in `iris/core` and
+`iris/src/default/render.rs`. See "Implemented, 2026-09-04" at the bottom for
+what landed, what differs from the proposal below and why, and what was
+verified versus merely reasoned about. The short version: the binding array
+is gone, `request_device` asks for no features and no binding-array limits,
+and that is now proven on the emulator's software Vulkan
+(`rigs/gpu-probe`), not just read from the code. `RUST.md`'s blocking item
+is resolved.
+
+Iris (the person) asked whether iris's (the library's) approach to
+"draw however many images happen to be on screen" — relevant here because a
+transcript can hold an unbounded number of attached screenshots — actually
+works on mobile, her recollection being that it does not. Checked rather
+than assumed, on 2026-09-04, on the `rustify` branch of `ai-app-2`. This
+file is that investigation and the resulting recommendation, written for a
+second agent to review before anything in iris's render core changes — no
+code has been written against this yet.
+
+## The problem
+
+Every texture iris ever creates — every `Image` widget
+(`iris/src/widget/image.rs`) and every glyph atlas page — gets a permanent
+slot in one array via `Textures::add` (`iris/core/src/primitive/texture.rs:65`).
+Both of iris's texture-sampling primitives (`TEXTURE` and `GLYPH`) read that
+array by index: `core/src/render/shader.wgsl:56` declares
+`var views: binding_array<texture_2d<f32>>`, sized by
+`UiLimits::default()` (`core/src/render/mod.rs:347`) at **100,000 textures,
+1,000 samplers**. Getting a device to accept that layout needs three wgpu
+features — `TEXTURE_BINDING_ARRAY`,
+`SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`,
+`PARTIALLY_BOUND_BINDING_ARRAY` — which correspond to Vulkan's
+`VK_EXT_descriptor_indexing` ("bindless"), promoted to Vulkan core at 1.2.
+
+A transcript with an unbounded number of image attachments is exactly the
+case that grows this array without bound: each attachment becomes its own
+`Image` widget, which takes its own permanent array slot until dropped.
+
+## What was measured
+
+**A new rig, `rigs/gpu-probe`**, asks a device for exactly iris's features
+and limits with no window and no APK — a plain executable pushed with
+`adb push` and run from `/data/local/tmp`. It has two parts:
+`wgpu::Adapter::request_device` with iris's exact `Features`/`Limits`
+(`src/main.rs`), and a raw Vulkan query bypassing wgpu entirely via `ash`
+(`src/vk.rs`), to tell "the driver doesn't have it" apart from "wgpu didn't
+detect it."
+
+- **On this VM's own GPU** (Vulkan via Venus onto an RX 7900 XT):
+  `IRIS DEVICE: ok`. Not the case that matters — nobody's phone is a
+  discrete desktop GPU — but it is why the design was never checked before
+  now: it always worked in the one place it was tried.
+- **On the Android emulator's guest Vulkan**, both ICDs it ships
+  (`vk_swiftshader_icd.json` and, cold-booted, `lvp_icd.json`/lavapipe):
+  `request_device` **fails** —
+  `Unsupported features were requested: TEXTURE_BINDING_ARRAY |
+  SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING |
+  PARTIALLY_BOUND_BINDING_ARRAY`. The raw `ash` query on lavapipe shows the
+  driver itself reporting all seven descriptor-indexing sub-features as
+  `true` at device API version 1.3 — so wgpu-hal's own feature detection is
+  being more conservative than the driver here, for a reason not chased
+  further (a likely instance-version negotiation gap, since the extension
+  only promoted to core at 1.2). That part is a wgpu-hal/emulator question,
+  not the finding that matters, and is **not** why this design is rejected.
+
+**The finding that matters is about real phones, sourced rather than
+recalled:**
+
+- The **Android Vulkan Profile 2025** — Google and Khronos's current
+  baseline, covering **80.1% of active Vulkan-capable Android devices** as
+  of October 2025
+  ([developer.android.com/ndk/guides/graphics/android-vulkan-profile](https://developer.android.com/ndk/guides/graphics/android-vulkan-profile)) —
+  does **not** require `VK_EXT_descriptor_indexing` or any descriptor-
+  indexing feature. It requires `shaderSampledImageArrayDynamicIndexing`
+  (indexing by a value uniform across the invocation — Vulkan 1.0 baseline,
+  unrelated to bindless) and stops there; true of the 2021 and 2022
+  profiles as well.
+- Arm's own developer documentation states **"`VK_EXT_descriptor_indexing`
+  is supported on all Valhall and 5th Gen GPUs"**
+  ([developer.arm.com/mobile-graphics-and-gaming/vulkan-api-best-practices-on-arm-gpus](https://developer.arm.com/mobile-graphics-and-gaming/vulkan-api-best-practices-on-arm-gpus)) —
+  Mali generations from roughly 2019 (Mali-G77) onward, with no claim made
+  for Bifrost, Midgard or Utgard, which are still common in budget and
+  older Android phones that are still in daily use.
+- A search engine's summarized claim of "1% support on Android" for this
+  extension was checked against its cited source (an Arm blog post from
+  2021) and **was not actually there** — that number does not appear in
+  any primary source found and should not be repeated. The baseline-
+  profile finding above is the one with an attributable source; use it
+  instead.
+
+So this is not a software-renderer artifact. A real, currently-shipping
+share of the Android fleet lacks the feature iris's texture pipeline asks
+for unconditionally, and neither the emulator's failure nor the current
+official hardware baseline gives any reason to expect that to change soon.
+
+## What growth already costs today, before any redesign
+
+Checked directly in `core/src/render/mod.rs` and `core/src/render/texture.rs`,
+because "does this redesign make things worse" needs the current baseline
+first:
+
+- The `RenderPipeline` (`UiRenderNode::new`) is created **once** and never
+  rebuilt for any reason related to texture count — its bind group
+  *layouts* declare fixed slot counts (`limits.max_textures`,
+  `limits.max_samplers`) up front and that never changes at runtime. Growth
+  was never at risk of recreating the pipeline, in the current design or
+  any redesign discussed below.
+- What **does** get rebuilt: `UiRenderNode::update` calls
+  `self.textures.update(&mut ui.textures)`, and if that reports any change,
+  rebuilds `self.rsc_group` — one `BindGroup` whose entries are
+  `BindingResource::TextureViewArray(&tex_manager.views())`, collected
+  fresh over **every currently-live texture**, plus the sampler array and
+  the mask buffer. This happens on every texture `Push`, `Set`, or `Free`
+  — an image added anywhere in the whole app rebuilds one shared structure
+  referencing every other image too.
+- The one path already excluded from this, on purpose, is a `Patch` —
+  writing into an existing texture's pixels without changing which
+  textures exist. The code says why directly
+  (`core/src/render/texture.rs`, in `GpuTextures::update`): *"A patch
+  changes texture contents, not the binding array, so it must not report
+  `changed` — rebuilding the bind group per glyph is the cost this exists
+  to avoid."* This is exactly the mechanism I1 built for the glyph atlas:
+  growing an existing atlas page costs a `write_texture` into a sub-rect,
+  nothing else.
+
+So today, growth that stays inside an existing texture (glyphs added to an
+atlas page) is already free. Growth that adds a *new* texture — a new atlas
+page, or any standalone image — already rebuilds the one shared array
+regardless of how the array is populated, before any change discussed
+below. That existing cost is O(live texture count) in CPU work to collect
+the view list and in however expensive the driver finds a
+descriptor-set-sized-for-N-descriptors to be.
+
+## Prior art, checked rather than assumed
+
+Two independent projects were checked to see whether "atlas for images"
+is actually how this is normally done, rather than a guess:
+
+- **egui_wgpu** (`crates/egui-wgpu/src/renderer.rs` in emilk/egui), the
+  closest prior art to iris — an immediate-mode wgpu-backed UI library that
+  ships on Android. It keeps a `HashMap<TextureId, Texture>` and gives
+  **each texture its own ordinary `BindGroup`** — one texture, one sampler,
+  no array, no descriptor indexing of any kind. Draw calls are batched by
+  texture id and the bind group is switched between batches within the
+  render pass.
+- **Vello** — the renderer Masonry (E1/E2's Linebender stack) draws
+  through — hit the identical problem and wrote down why in their own
+  roadmap document
+  ([github.com/linebender/vello/blob/main/doc/roadmap_2023.md](https://github.com/linebender/vello/blob/main/doc/roadmap_2023.md)):
+  *"The number of images that may appear in a scene is not bounded, which
+  is not a good fit for the basic descriptor binding model... Until then,
+  we'll do a workaround of having a single atlas image containing all the
+  images in the scene."* Their reason is broader than Android — WebGPU 1.0
+  has no descriptor indexing at all — but it reaches the same conclusion
+  for the same shape of problem: atlas, not a bigger bindless array.
+
+**This is also a live hazard, not a solved one.** Vello's own changelog
+(Sparse Strips v0.2.0) lists a fix titled *"WebGL image-atlas allocation
+and growth on Mali-G52 GPUs, avoiding application-not-responding errors"*
+— an actual ANR, from atlas growth, on an actual mid-range Android GPU,
+in the renderer Masonry is built on. The same release added
+`AtlasSpaceDiagnostics`/`AtlasLayerDiagnostics` (per-layer free-space,
+utilization, fragmentation) because growth needed instrumenting in
+production, not because it turned out to be free.
+
+## Recommendation (not yet implemented)
+
+1. **Small, plentiful textures** — glyphs (already done, I1), thumbnails,
+   downscaled attachment previews, icons — go through a shared atlas, the
+   same technique as `core/src/render/atlas.rs` generalized beyond glyphs.
+   Adding one to an existing page is a `Patch`, already free per the
+   section above.
+2. **Large or one-off images** — a photo attachment opened at full
+   resolution, anything that would fragment a shared page — get their
+   **own ordinary, non-array bind group**, the egui_wgpu way. Creating one
+   is O(1): it references only itself, and does not touch any other
+   texture's binding, unlike today's shared array where every push
+   rebuilds a structure listing everything.
+3. **Opening a new atlas page** is the one case that still resembles
+   today's rebuild — infrequent (bounded by how many *pages* are needed,
+   not by how many images have ever been attached) but not free, and
+   Vello's Mali-G52 fix says this specifically deserves care: it should
+   never be allowed to block a frame, and it is worth having the
+   equivalent of Vello's atlas diagnostics before trusting it under load.
+4. **Net effect**: dropping `TEXTURE_BINDING_ARRAY`,
+   `SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`, and
+   `PARTIALLY_BOUND_BINDING_ARRAY` from iris's device request entirely.
+   Every path above is plain Vulkan 1.0 / GLES-level texture sampling.
+   This is also what fixes the emulator failure measured above, regardless
+   of the unresolved wgpu-hal question: a device that never asks for the
+   feature cannot be refused for lacking it.
+
+## What this touches, and what is still open
+
+Implementing this reworks iris's rendering core: the shader's binding
+group layout (`shader.wgsl`), `Textures` and `GpuTextures`
+(`core/src/primitive/texture.rs`, `core/src/render/texture.rs`), both
+texture-sampling primitives, and `core/src/ui/painter.rs`'s draw-call
+batching (today one draw call can reference any texture by index; the
+per-texture-bind-group path needs draws grouped by which bind group they
+use). Nothing has been started.
+
+Open questions a reviewer should weigh in on:
+
+- **The size threshold** between "goes in an atlas page" and "gets its own
+  bind group." Too low and ordinary attachment thumbnails end up as
+  one-off bind groups, losing the batching benefit the atlas exists for;
+  too high and a page fragments on a handful of medium images.
+- **Eviction policy** for atlas pages once the working set does not fit —
+  today's `GlyphAtlas` never evicts, because a font's glyph set is small
+  and bounded; images are not. An LRU at the page level, or at the
+  individual-image level within a page, has not been designed.
+- **Whether iris should keep any binding array at all**, even a small
+  fixed one (say, capped at a few dozen slots) for atlas pages themselves,
+  or whether every atlas page should also be its own ordinary bind group
+  like standalone images — the array's only remaining justification would
+  be avoiding a bind-group-per-draw-call switch cost that has not been
+  measured on this project's actual target hardware.
+- **How this interacts with I2/E2's virtualised list** (I3): a
+  bottom-anchored transcript composes only visible rows, so the live
+  texture set should already be bounded by what is on screen rather than
+  by the whole conversation — worth confirming that invariant holds before
+  relying on it to keep atlas/bind-group churn small.
+
+## Review, 2026-09-04
+
+A second pass over the file above against the code, done before anything
+is implemented. Iris's worry going in: a bind group per texture means a
+draw call per image, and she wants this as efficient as it can be.
+
+### What checked out
+
+Every code reference above is accurate as of this commit: the 100,000 /
+1,000 limits, the one-time pipeline, the `rsc_group` rebuild on every
+`Push`/`Set`/`Free`, and the `Patch` exclusion. The device request that
+asks for the three features is `iris/src/default/render.rs:96`, which the
+text above does not name. egui-wgpu and Vello are described correctly.
+
+### The emulator refusal is a wgpu-hal gap, now located
+
+The file guessed "a likely instance-version negotiation gap." It is
+narrower than that and it is in wgpu-hal, not the emulator. wgpu-hal
+28.0.0 (`src/vulkan/adapter.rs:1618`) only queries
+`PhysicalDeviceDescriptorIndexingFeaturesEXT` **when the device advertises
+the `VK_EXT_descriptor_indexing` extension string**. A Vulkan 1.2+ driver
+that has descriptor indexing as core need not list the extension, and
+lavapipe at 1.3 evidently does not, so wgpu never asks and reports the
+features absent, which is why `ash` sees seven `true`s and wgpu sees none.
+The properties query beside it (line 1486) correctly accepts
+`device_api_version >= 1.2 || extension`; the features query does not.
+wgpu-hal 30.0.1 in the local registry has the same asymmetry (lines
+1872 and 2036). Worth an upstream issue, but not a reason to keep the
+design: on real phones the gate that matters is stricter still.
+
+**wgpu's `TEXTURE_BINDING_ARRAY` needs six sub-features, not one**
+(`adapter.rs:160-177`): non-uniform indexing *and* update-after-bind for
+sampled images, storage images and storage buffers, all together, because
+wgpu marks every array-bearing descriptor set update-after-bind. So Arm's
+"the extension is supported on Valhall" is necessary but not sufficient;
+a driver with sampled-image indexing and without storage-buffer
+update-after-bind is refused too. That widens the excluded set beyond
+what the Arm quote suggests and strengthens the conclusion.
+
+### A live bug in the current code, found on the way
+
+`GpuTextures::update` (`core/src/render/texture.rs:33`) implements
+"a patch must not report changed" as `changed = false`, unconditionally,
+which also **cancels a `Push` earlier in the same batch**. That ordering is
+exactly what opening a new atlas page produces: `GlyphAtlas::allocate`
+pushes the page and `insert` patches it in the same frame, so the bind
+group is not rebuilt and the new page's view is not bound until some
+unrelated texture change happens to rebuild it. It is hidden today only
+because the masks path also sets `changed`. The fix is one line
+(`changed |= !matches!(update, Patch)` in spirit); it should go in with
+the redesign since that code is being replaced, and it is recorded here
+so it is not rediscovered.
+
+### In-layer draw order is already undefined
+
+Relevant to any batching redesign: `Primitives::apply_free`
+(`core/src/render/primitive.rs:147`) uses `swap_remove`, so the instance
+order within a layer is permuted whenever anything is freed. Overlap order
+inside one layer is therefore not something the renderer promises today;
+ordering is done with layers. That means grouping a layer's draws by
+texture, or drawing a layer's images after its rects and glyphs, loses
+nothing that currently exists. It should be written down as an invariant
+when the redesign lands, because the new code will depend on it.
+
+### On "a draw call per image"
+
+Two corrections to the worry. First, it is a draw per *distinct texture per
+layer*, not per image primitive: every glyph quad in a layer shares the
+atlas and stays one instanced draw, and a thumbnail atlas would do the same
+for previews. Second, the count is bounded by what is on screen, which I3's
+virtualised transcript already bounds, and a mobile GPU is not draw-call
+bound at tens of draws per frame; egui ships exactly this on Android. What
+does cost is per-frame *bind group creation* and per-frame *sorting*, and
+the current code already creates a `primitive_group` bind group every time
+a layer updates (`render/mod.rs:103`), so one more per new image is not a
+regression in kind.
+
+### Recommended shape (proposal, for Iris to accept or change)
+
+Aimed at the fewest moving parts that need no feature beyond Vulkan 1.0:
+
+1. **Atlas pages become layers of one `texture_2d_array`**, not separate
+   textures. Every page is already `PAGE`x`PAGE` RGBA8, which is the one
+   constraint an array texture imposes. A layer index is an ordinary
+   sampling operand in WGSL and needs no indexing feature, so `GLYPH`
+   (and any future atlased-image primitive) carries a layer instead of a
+   `view_idx` and all of a layer's text stays **one draw**. This answers
+   the open question above about keeping a small binding array: no. Cost
+   of opening a page: recreate the array with one more layer and
+   `copy_texture_to_texture` the old ones, GPU-side, no readback; grow
+   with headroom (double) so it is rare. wgpu's default
+   `max_texture_array_layers` is 256, at 4 MB each, so the cap is memory
+   rather than the API.
+2. **Every standalone image is its own texture with its own bind group**,
+   and its instances live in a **separate per-layer instance list**, not
+   the main one. Then the main instance buffer never contains an image,
+   there is nothing to sort, no handle remapping beyond what
+   `apply_free` already does, and each image is `draw(0..4, k..k+1)` with
+   its bind group set first. Group 2's layout becomes `{atlas array,
+   one image texture, sampler, masks}`; the main draw binds a 1x1 null
+   image in the image slot, each image draw binds its own. One pipeline,
+   one shader, one layout.
+3. **No thumbnail atlas in the first version.** With images on their own
+   textures, the threshold and eviction questions above disappear: an
+   image is freed when the row that owns its `TextureHandle` scrolls out.
+   Add an image atlas only if a measured screen shows enough small images
+   to matter, which a transcript rarely does.
+4. **Drop the three features and the two `max_binding_array_*` limits from
+   `src/default/render.rs`**, and the `UiLimits` counts with them.
+5. **Sampling is `NonFiltering` today** (`render/mod.rs:290,299`), so a
+   downscaled attachment will alias. Either request a filtering sampler
+   for the image slot or downscale on the CPU before upload; decide when
+   the image widget is touched, not as part of this.
+
+What this costs against the file's original recommendation: `Textures`
+needs to know an image from a page (two kinds of handle, or a kind on
+`TextureHandle`), and `Primitives` gets a second instance list per layer.
+What it saves: the sort, the size threshold, the eviction policy, and any
+per-page bind group switch.
+
+## Implemented, 2026-09-04
+
+The shape above, built as proposed with one structural addition the proposal
+didn't need to spell out and one bug it predicted made moot rather than
+literally fixed. Files: `core/src/primitive/texture.rs` (`Textures`,
+`TextureHandle`), `core/src/render/texture.rs` (`GpuTextures`),
+`core/src/render/primitive.rs` (`Primitives`, `GlyphPrimitive`),
+`core/src/render/atlas.rs`, `core/src/ui/painter.rs`,
+`core/src/render/mod.rs` (`UiRenderNode`, `UiLimits` removed),
+`core/src/render/shader.wgsl`, `src/default/render.rs`, and
+`rigs/gpu-probe/src/main.rs`.
+
+**1. Atlas pages as array layers.** `GpuTextures` owns one
+`texture_2d_array` (`array_texture`/`array_view`), grown by doubling
+(`grow_array`): a new texture is created at twice the layer capacity, the
+old layers are copied across with `copy_texture_to_texture` (GPU-side, no
+readback), and every bind group that referenced the old view — the main
+one and every live standalone image's — is rebuilt, since the view's
+identity changed. `GlyphPrimitive` carries `layer: u32` instead of
+`view_idx`/`sampler_idx`; the layer number is assigned synchronously in
+`Textures::add_page` (a plain counter, `next_page_layer`), not by the
+renderer, because `GlyphAtlas::insert` needs it in the same call, before
+any GPU sync happens — the renderer only finds out later, when it
+processes the queued `Push`.
+
+**2. Standalone images, one bind group each.** `TextureKind` on
+`TextureHandle`/`Textures` distinguishes `Image` (a plain bind-group index,
+`slot`) from `Page { layer }`. `Primitives` gained a second per-layer list
+— `images: Vec<PrimitiveInstance>`, tagged `IMAGE_BINDING` — separate from
+`instances` (rects and glyphs), written by `Painter::write_image` rather
+than through the generic `Primitive` trait, since an image has nowhere in
+`PrimitiveData` to put a per-instance entry once the bind group already
+picks the texture. `UiRenderNode::draw` draws a layer's `instance` buffer
+once as before, then walks `image_instance` one entry at a time, binding
+that texture's `BindGroup` (`GpuTextures::image_bind_group`) and issuing
+`draw(0..4, k..k+1)` per image. Group 2's layout is exactly the proposed
+`{atlas array, one image texture, sampler, masks}`; the main draw binds a
+1x1 null view in the image slot.
+
+**The one addition beyond the proposal**: the masks storage buffer lives
+in every per-image bind group (group 2, binding 3), and `ArrBuf<Mask>`
+recreates its buffer whenever the mask count changes size
+(`render/util/mod.rs`'s `ArrBuf::update` now returns whether it resized).
+A resize invalidates every bind group holding the old buffer, not just the
+main one, so `GpuTextures::update` takes a `masks_resized: bool` and calls
+`rebuild_image_bind_groups` when it's set, alongside the same rebuild the
+array-growth path already needed. This wasn't a design question the
+proposal had to answer (it treated bind-group construction as a given),
+but it's exactly the shape of trap layer growth already had, so it uses
+the same fix.
+
+**3. No thumbnail atlas.** Not built, as proposed.
+
+**4. Removed**: `TEXTURE_BINDING_ARRAY`, `PARTIALLY_BOUND_BINDING_ARRAY`,
+`SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING` from
+`src/default/render.rs`'s `request_device`, and `UiLimits` (the type
+itself, not just its binding-array methods — once its two fields were
+gone there was nothing left in it, and `UiRenderNode::new` no longer takes
+a limits parameter). `binding_array` no longer appears anywhere in
+`shader.wgsl`.
+
+**5. Sampling** is still `NonFiltering`, unchanged, per the proposal's own
+note that this is a separate decision for whenever the image widget itself
+is touched.
+
+**The `changed = false` bug is structurally gone, not patched.** The old
+`GpuTextures::update` held one `changed: bool` that a `Patch` reset
+unconditionally, which could erase an earlier `Push` in the same batch (a
+new atlas page's `Push` immediately followed by `GlyphAtlas::insert`'s
+`Patch`, both queued before the renderer ever runs). The new `update`
+computes the rebuild signal by OR-ing each event's own answer
+(`rebuild_main |= self.push(...)`), and `Patch`'s arm simply never
+contributes to it — there is no shared mutable flag left for a `Patch` to
+stomp on. Documented at the call site
+(`core/src/render/texture.rs`, `GpuTextures::update`'s doc comment and the
+`Patch` match arm's comment) rather than fixed as a one-line diff, since
+the mechanism that could go wrong no longer exists.
+
+**In-layer draw order is an explicit invariant now, not just a fact about
+`swap_remove`.** `UiRenderNode::draw` draws every layer's images after its
+rects and glyphs, and `Primitives::apply_free`'s doc comment states
+directly that both of a layer's lists (`instances` and `images`) free with
+`swap_remove` and that nothing may assume adjacency survives a free —
+recorded there because `apply_free` is the one place a change to either
+list's ordering would have to be reconciled.
+
+**Verified:**
+
+- `cargo fmt --all -- --check`, `cargo build --workspace --all-targets`,
+  `cargo clippy --all-targets`, `cargo test --workspace` all clean in
+  `iris/`, on the pinned `nightly-2026-09-03` toolchain. 14 tests pass
+  (unchanged from I1; nothing here is pure-logic enough to add a unit
+  test to — it's all GPU resource wiring).
+- `iris/run-headless.sh minimal --shot /tmp/minimal.png` and
+  `iris/run-headless.sh tabs --shot /tmp/tabs.png`: both render correctly
+  on this VM's GPU (Venus) — `tabs`'s glyph-atlas text renders in every
+  panel, confirming `GlyphPrimitive.layer` addresses the array correctly.
+- The standalone-image path specifically: a throwaway example (not
+  committed) with an `image(...)` widget as part of the root, run the same
+  way, rendered the image next to glyph-atlas text in one frame —
+  confirming a live `BindGroup` built by `GpuTextures::create_image` and
+  bound per-`draw()` call actually samples the right texture. `tabs`'s own
+  "image span" tab exercises the same widget but needs a click to reach,
+  which the headless compositor can't deliver (no seat devices, per I1's
+  own note on this file) — the throwaway example is what stood in for it.
+- **Exercised, 2026-09-04: `grow_array` under real load, on `tabs`.**
+  Rather than building a purpose-made glyph flood, `PAGE`
+  (`core/src/render/atlas.rs`) was temporarily dropped from 1024 to 64 —
+  small enough that `tabs`'s ordinary mix of sizes and families (nothing
+  exotic: a handful of `Text` widgets at a few sizes, one at
+  `Family::Monospace`) already exceeds one page's worth of distinct
+  glyphs. A one-line `eprintln!` in `grow_array` confirmed two real grows
+  in a single run (`GROW_ARRAY: 1 -> 2` then `GROW_ARRAY: 2 -> 4`, i.e.
+  glyphs landed on at least a third layer), and
+  `iris/run-headless.sh tabs --shot` showed every tab's text rendering
+  correctly with no corruption or missing glyphs — confirming the
+  `copy_texture_to_texture` grow-and-relocate path and cross-layer
+  sampling (`GlyphPrimitive.layer` addressing a layer beyond the first)
+  both work. Command:
+  `sed -i 's/PAGE: u32 = 1024/PAGE: u32 = 64/' core/src/render/atlas.rs`,
+  rebuild, `./run-headless.sh tabs --shot /tmp/x.png`, then
+  `git checkout -- core/src/render/atlas.rs` to revert — this is a
+  throwaway diagnostic value, never a committed change, since a real
+  1024px page holding only a handful of glyphs at a time would be mostly
+  wasted space in normal use. Confirmed the revert left `tabs` and
+  `minimal` byte-identical to the pre-check screenshots afterward.
+- **The decisive check**, `rigs/gpu-probe` rewritten to request iris's new
+  (empty) feature/limit set and run on this checkout's own emulator
+  (`ai-app-2`, via `emu`), booted with `EMU_GPU=software` so the guest gets
+  a real Vulkan device (SwiftShader) rather than the `-gpu host` default,
+  which disables Vulkan in this VM entirely (`-feature -Vulkan`, because
+  gfxstream can't pair Venus with the real GPU here — worth remembering,
+  since the *default* `emu up` gives a device with **no** Vulkan adapter
+  at all, which reads exactly like the old bindless failure if you don't
+  know to ask for `EMU_GPU=software`):
+
+      cd rigs/gpu-probe
+      ANDROID_NDK_HOME=$HOME/Android/Sdk/ndk/29.0.14206865 \
+        cargo ndk -t arm64-v8a -P 26 build --release
+      EMU_GPU=software emu up   # from ~/repos/emulator-tools
+      adb push target/aarch64-linux-android/release/gpu-probe /data/local/tmp/
+      adb shell chmod 755 /data/local/tmp/gpu-probe
+      adb shell /data/local/tmp/gpu-probe
+
+  Output: `adapters: 1 — Vulkan SwiftShader Device (Subzero) (Cpu)`,
+  `features iris requires:` (none listed — the set is empty),
+  `max_buffer_size … ok`, and **`IRIS DEVICE: ok`**. This is the fix
+  measured working, on the exact rig that first measured it failing.
+  Emulator stopped afterward (`emu down`); nothing was left running.

android-shell/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "android-shell"
+version = "0.1.0"
+edition = "2024"
+
+# The JNI bridge behind E3's two Java stub classes (`MainActivity`,
+# `NotificationService` -- see RUST.md's "How much Java is unavoidable" for
+# why those two classes cannot be anything but Java/Kotlin, registered from
+# the manifest by name). Everything they would otherwise have done in
+# Kotlin -- the SSE follow loop, deciding where a notification is shown,
+# picking a session for a share -- is here instead, built on `client-core`
+# so the networking and parsing are not duplicated a third time next to the
+# server and the Kotlin app.
+#
+# `cdylib` for `System.loadLibrary`; `lib` too so `cargo test`/`clippy` run
+# on a normal host target without an Android NDK toolchain, the same
+# posture `client-core` and `server` already have.
+
+[lib]
+name = "android_shell"
+crate-type = ["cdylib", "lib"]
+
+[dependencies]
+client-core = { path = "../client-core" }
+jni = "0.22"
+log = "0.4"
+
+# `LogErrorAndDefault` (the `native_method!` error policy this crate uses
+# throughout, see lib.rs) logs through the `log` facade, which is a no-op
+# without a backend installed -- so without this, every recoverable error
+# at a native entry point would be silently dropped rather than reaching
+# logcat. Android-only: nothing else here needs it, and it does not build
+# off-device (see `notify::ensure_logger`'s call site, the only place this
+# is used).
+[target.'cfg(target_os = "android")'.dependencies]
+android_logger = "0.15"

android-shell/src/jcall.rs

@@ -0,0 +1,152 @@
+//! Thin wrappers around the five `Env` calls this crate makes constantly
+//! (a class name, a method name and a signature, all as plain `&str`).
+//!
+//! `jni` 0.22 wants a class or method *name* as `AsRef<JNIStr>` (its own
+//! modified-UTF-8 type; `JNIString::new` is the runtime conversion, used
+//! here uniformly rather than switching to the compile-time `jni_str!`
+//! literal macro call by call -- these are a handful of short, one-off
+//! lookups, not a hot loop, so the difference is not worth two code paths
+//! for the same thing) and a *signature* as a parsed `MethodSignature`/
+//! `FieldSignature`, which is why those go through
+//! `RuntimeMethodSignature`/`RuntimeFieldSignature::from_str` instead: the
+//! parsed form is what lets these calls skip re-validating the signature
+//! against the arguments on every call, which is the whole reason `jni`
+//! moved to it.
+//!
+//! **The classloader gotcha, found by testing (2026-09-05).** A class
+//! lookup by name (`find_class`, `new_object`, `call_static_method`,
+//! `get_static_field` -- anything that resolves a *class*, as opposed to
+//! `call_method` on an object it already has, which needs no such lookup)
+//! defaults to `FindClass`'s ordinary search when it cannot find the
+//! calling thread a classloader through `Thread.getContextClassLoader()`.
+//! That default is fine on a thread the JVM itself started -- an
+//! `onCreate`/`onStartCommand` callback -- but every one of these calls
+//! from `android-shell`'s own background thread (the notification
+//! follow-loop, the share upload) is running on a thread *Rust* spawned
+//! and attached with `JavaVM::attach_current_thread`, which the platform
+//! never gave an app classloader. Framework classes
+//! (`android.app.Notification$Builder`, ...) still resolve, because they
+//! are reachable from the bootstrap loader `FindClass` falls back to --
+//! `androidx.core.app.NotificationManagerCompat` is not, since it is
+//! packaged inside this app's own APK. The failure was
+//! `Error::NoClassDefFound`, logged by `notify::show`'s `LogErrorAndDefault`
+//! as "failed to resolve Java class ... (class not found or linkage
+//! error)" -- on a real device this reads as "the notification silently
+//! never arrives," since the whole call is inside the follow loop and the
+//! ongoing foreground notification (built on the main thread, in
+//! `try_start`, before the background thread exists) posts fine either
+//! way. `remember_class_loader` caches the app's own `ClassLoader` the
+//! first time any entry point has a `Context` to ask, and every class
+//! lookup below goes through it explicitly via `LoaderContext::Loader`
+//! rather than the thread-dependent default -- so it is correct on the
+//! main thread and on this crate's own background threads alike.
+
+use jni::Env;
+use jni::errors::Result;
+use jni::objects::{JClass, JClassLoader, JObject, JValue, JValueOwned};
+use jni::refs::{Global, LoaderContext};
+use jni::signature::{RuntimeFieldSignature, RuntimeMethodSignature};
+use jni::strings::JNIString;
+use std::sync::OnceLock;
+
+static CLASS_LOADER: OnceLock<Global<JClassLoader<'static>>> = OnceLock::new();
+
+/// Caches `context`'s own `ClassLoader`, the first time this is called.
+/// Cheap to call from every entry point that has a `Context` on hand
+/// (`MainActivity`'s and `NotificationService`'s all do): later calls are
+/// a `OnceLock::get` and nothing else.
+pub fn remember_class_loader(env: &mut Env, context: &JObject) -> Result<()> {
+    if CLASS_LOADER.get().is_some() {
+        return Ok(());
+    }
+    // context.getClass().getClassLoader() -- resolved via `call_method` on
+    // real objects throughout, so this needs no class-name lookup of its
+    // own and has nothing to bootstrap.
+    let class_obj = call_method(env, context, "getClass", "()Ljava/lang/Class;", &[])?.l()?;
+    let loader_obj = call_method(
+        env,
+        &class_obj,
+        "getClassLoader",
+        "()Ljava/lang/ClassLoader;",
+        &[],
+    )?
+    .l()?;
+    let loader = env.cast_local::<JClassLoader>(loader_obj)?;
+    let global = env.new_global_ref(&loader)?;
+    // Lost the race with another entry point calling this concurrently --
+    // both loaders name the same app, so either one is fine and there is
+    // nothing to reconcile.
+    let _ = CLASS_LOADER.set(global);
+    Ok(())
+}
+
+/// Resolves `name` (slash-separated, e.g. `androidx/core/app/NotificationCompat`)
+/// through the cached app classloader when one has been remembered, and
+/// through the ordinary default otherwise -- which is every call made
+/// before any entry point has run, and is also correct for a main-thread
+/// caller, so there is no case this makes worse.
+fn resolve_class<'local>(env: &mut Env<'local>, name: &str) -> Result<JClass<'local>> {
+    match CLASS_LOADER.get() {
+        Some(loader) => {
+            let binary_name = name.replace('/', ".");
+            LoaderContext::Loader(loader).load_class(env, JNIString::new(&binary_name), true)
+        }
+        None => env.find_class(JNIString::new(name)),
+    }
+}
+
+pub fn find_class<'local>(env: &mut Env<'local>, name: &str) -> Result<JClass<'local>> {
+    resolve_class(env, name)
+}
+
+/// A new Java string as a plain `JObject` -- what every call site here
+/// wants it as (`JValue::Object` takes `&JObject`, not `&JString`, and
+/// `JString: Into<JObject>` is the documented way across).
+pub fn jstr_obj<'local>(env: &mut Env<'local>, text: impl AsRef<str>) -> Result<JObject<'local>> {
+    Ok(env.new_string(text)?.into())
+}
+
+pub fn new_object<'local>(
+    env: &mut Env<'local>,
+    class: &str,
+    sig: &str,
+    args: &[JValue],
+) -> Result<JObject<'local>> {
+    let sig = RuntimeMethodSignature::from_str(sig)?;
+    let class = resolve_class(env, class)?;
+    env.new_object(class, sig.method_signature(), args)
+}
+
+pub fn call_method<'local>(
+    env: &mut Env<'local>,
+    obj: &JObject,
+    method: &str,
+    sig: &str,
+    args: &[JValue],
+) -> Result<JValueOwned<'local>> {
+    let sig = RuntimeMethodSignature::from_str(sig)?;
+    env.call_method(obj, JNIString::new(method), sig.method_signature(), args)
+}
+
+pub fn call_static_method<'local>(
+    env: &mut Env<'local>,
+    class: &str,
+    method: &str,
+    sig: &str,
+    args: &[JValue],
+) -> Result<JValueOwned<'local>> {
+    let sig = RuntimeMethodSignature::from_str(sig)?;
+    let class = resolve_class(env, class)?;
+    env.call_static_method(class, JNIString::new(method), sig.method_signature(), args)
+}
+
+pub fn get_static_field<'local>(
+    env: &mut Env<'local>,
+    class: &str,
+    field: &str,
+    sig: &str,
+) -> Result<JValueOwned<'local>> {
+    let sig = RuntimeFieldSignature::from_str(sig)?;
+    let class = resolve_class(env, class)?;
+    env.get_static_field(class, JNIString::new(field), sig.field_signature())
+}

android-shell/src/lib.rs

@@ -0,0 +1,131 @@
+//! The JNI bridge behind E3's two Java stub classes. See `Cargo.toml`'s
+//! package comment for what this crate is and RUST.md's E3 entry for the
+//! design decisions.
+//!
+//! Each native method is declared with `jni`'s [`native_method!`] macro
+//! rather than a hand-written `#[no_mangle] extern "system" fn Java_...`:
+//! the macro derives the mangled export name and the JNI signature from the
+//! Rust function itself, so the two cannot drift apart the way a
+//! hand-typed name string and a hand-typed `"(Landroid/...;)V"` signature
+//! routinely do. `error_policy = LogErrorAndDefault` matches
+//! `Notifications.kt`'s own posture: a failure here (a lost connection, a
+//! JNI call that threw) is reported to logcat, not thrown back into Java
+//! as an exception that would crash the app over something recoverable.
+//!
+//! Each `const _: NativeMethod = native_method! { ... };` binding is
+//! otherwise unused by name -- `_` is the idiomatic way to keep a
+//! side-effecting const (here, generating the `#[export_name]`d function
+//! the JVM resolves by the JNI naming convention) without a `dead_code`
+//! warning for a binding nothing reads.
+
+mod jcall;
+mod notify;
+mod settings;
+mod share;
+
+use jni::errors::LogErrorAndDefault;
+use jni::objects::{JClass, JObject};
+use jni::sys::jint;
+use jni::{Env, NativeMethod, native_method};
+
+/// Installs the `log` backend that routes to logcat, once per process.
+/// Without it, `LogErrorAndDefault` (every native method below) and any
+/// `log::error!` inside `jni` itself (e.g. `JString`'s `Display` fallback)
+/// call into the `log` facade's default no-op logger, and a real failure
+/// vanishes with nothing on logcat to say so -- silently *more* wrong than
+/// crashing, since nothing on screen or in the log says a notification was
+/// dropped. Called from every entry point below rather than a Java-side
+/// `Application.onCreate`, since this crate deliberately has no such class
+/// to hook (see RUST.md's E3 entry on the two-Java-classes floor).
+fn ensure_logger() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        #[cfg(target_os = "android")]
+        android_logger::init_once(
+            android_logger::Config::default()
+                .with_max_level(log::LevelFilter::Debug)
+                .with_tag("android-shell"),
+        );
+    });
+}
+
+// The parameters are spelled as their Java types, not as `JObject`: the
+// macro encodes each argument into the exported symbol's JNI signature
+// (and JNI resolves `Java_...` names *by* that signature), so a generic
+// `JObject` here would export `(Ljava/lang/Object;...)` against a Java
+// method actually declared `(Landroid/app/Activity;...)` -- two different
+// symbols that never resolve to each other, silently, with no compiler
+// error on either side. `android.app.Activity` etc. have no dedicated
+// Rust wrapper in this crate, so they fall back to plain `JObject` in the
+// implementation functions below (the "Built-in Types" note in
+// `native_method!`'s docs).
+const _: NativeMethod = native_method! {
+    java_type = "com.example.aiapp.shell.MainActivity",
+    static extern fn native_handle_intent(activity: android.app.Activity, intent: android.content.Intent) -> (),
+    error_policy = LogErrorAndDefault,
+};
+
+/// `MainActivity.nativeHandleIntent` -- called from `onCreate` and
+/// `onNewIntent`. See `share::handle_intent` for what an intent can mean.
+fn native_handle_intent<'local>(
+    env: &mut Env<'local>,
+    _class: JClass<'local>,
+    activity: JObject<'local>,
+    intent: JObject<'local>,
+) -> Result<(), jni::errors::Error> {
+    ensure_logger();
+    jcall::remember_class_loader(env, &activity)?;
+    share::handle_intent(env, &activity, &intent)
+}
+
+const _: NativeMethod = native_method! {
+    java_type = "com.example.aiapp.shell.NotificationService",
+    static extern fn native_sync(context: android.content.Context) -> (),
+    error_policy = LogErrorAndDefault,
+};
+
+/// `NotificationService.nativeSync` -- called both from `MainActivity` (an
+/// enrollment may have just landed) and from `NotificationService.sync`
+/// itself. See `notify::sync`.
+fn native_sync<'local>(
+    env: &mut Env<'local>,
+    _class: JClass<'local>,
+    context: JObject<'local>,
+) -> Result<(), jni::errors::Error> {
+    ensure_logger();
+    jcall::remember_class_loader(env, &context)?;
+    notify::sync(env, &context)
+}
+
+const _: NativeMethod = native_method! {
+    java_type = "com.example.aiapp.shell.NotificationService",
+    static extern fn native_on_start_command(service: android.app.Service) -> jint,
+    error_policy = LogErrorAndDefault,
+};
+
+/// `NotificationService.nativeOnStartCommand`. See `notify::on_start_command`.
+fn native_on_start_command<'local>(
+    env: &mut Env<'local>,
+    _class: JClass<'local>,
+    service: JObject<'local>,
+) -> Result<jint, jni::errors::Error> {
+    ensure_logger();
+    jcall::remember_class_loader(env, &service)?;
+    Ok(notify::on_start_command(env, service))
+}
+
+const _: NativeMethod = native_method! {
+    java_type = "com.example.aiapp.shell.NotificationService",
+    static extern fn native_on_destroy() -> (),
+    error_policy = LogErrorAndDefault,
+};
+
+/// `NotificationService.nativeOnDestroy`. See `notify::on_destroy`.
+fn native_on_destroy<'local>(
+    _env: &mut Env<'local>,
+    _class: JClass<'local>,
+) -> Result<(), jni::errors::Error> {
+    ensure_logger();
+    notify::on_destroy();
+    Ok(())
+}

android-shell/src/notify.rs

@@ -0,0 +1,556 @@
+//! Where a notification is said, and the foreground service that keeps
+//! the connection open while the app is closed. Ported from
+//! `Notifications.kt`'s `NotificationService`, minus the "session on
+//! screen" / "hand to the app as a banner" branches: those read
+//! process-wide state that only exists because a screen is drawn to
+//! register against, and this experiment draws no screen yet (that is
+//! E4's job, on iris). So every notification here takes the third branch
+//! Kotlin's `show` already had -- the platform's own drawer -- which is
+//! also exactly the case E3's pass condition asks for: **a notification
+//! arrives with the app closed.**
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+
+use client_core::api::UreqTransport;
+use client_core::notifications::{SessionNotification, follow_notifications};
+use jni::Env;
+use jni::errors::Result;
+use jni::objects::{JObject, JValue};
+use jni::sys::{JNI_TRUE, jint};
+
+use crate::settings::{self, ServerSettings};
+
+const ALERT_CHANNEL: &str = "sessions";
+const ONGOING_CHANNEL: &str = "connection";
+const ONGOING_ID: i32 = 1;
+const ALERT_ID: i32 = 2;
+/// Same backoff as `Notifications.kt`'s `RECONNECT_DELAY_MS`.
+const RECONNECT_DELAY: Duration = Duration::from_millis(5_000);
+
+/// Whether the follow-loop thread is already running. **A deviation from
+/// `Notifications.kt`, found by testing rather than planned**: the Kotlin
+/// `onStartCommand` spawns a fresh `thread(isDaemon = true) { follow(...) }`
+/// on *every* call, with nothing to notice a previous one is still going --
+/// and `sync()` calling `startForegroundService` when the service is
+/// already running is an ordinary Android start, not a restart, so
+/// `onStartCommand` runs again. Enrolling from `MainActivity` (which calls
+/// `sync` once itself, then again inside `handle_enrollment` after saving
+/// the token) hits exactly this path and was observed opening **two**
+/// concurrent connections to `/notifications` from one process -- caught
+/// on this build via `adb logcat` showing two `jni::vm::java_vm: Attached
+/// thread ai-app-notifications` lines for one enrollment. Guarded here
+/// rather than left to match Kotlin's behaviour exactly, since duplicating
+/// a live connection is a resource leak with no upside; worth carrying the
+/// same guard back to `Notifications.kt` separately.
+static RUNNING: AtomicBool = AtomicBool::new(false);
+
+/// Set by `nativeOnDestroy`, checked by the follow loop between
+/// reconnects. **Known gap, recorded rather than hidden**: unlike
+/// `HttpURLConnection.disconnect()` in the Kotlin original, nothing here
+/// can interrupt a `ureq` read already blocked inside one connection --
+/// `Transport::stream` hands back a plain `Read` with no cancellation
+/// handle. So a stop lands at the next reconnect, not mid-read. `/notifications`
+/// is idle between events (a keep-alive, per `server/src/routes.rs`), so in
+/// practice this is a bounded wait rather than a hang; closing that gap
+/// for real means adding a cancellation point to `client_core::Transport`,
+/// which is a decision affecting every caller of that trait, not just this
+/// one -- left for whoever next depends on prompt shutdown.
+static STOPPING: AtomicBool = AtomicBool::new(false);
+
+fn static_int(env: &mut Env, class: &str, field: &str) -> Result<i32> {
+    crate::jcall::get_static_field(env, class, field, "I")?.i()
+}
+
+fn notification_manager<'l>(env: &mut Env<'l>, context: &JObject) -> Result<JObject<'l>> {
+    crate::jcall::call_static_method(
+        env,
+        "androidx/core/app/NotificationManagerCompat",
+        "from",
+        "(Landroid/content/Context;)Landroidx/core/app/NotificationManagerCompat;",
+        &[JValue::Object(context)],
+    )?
+    .l()
+}
+
+fn create_channel(
+    env: &mut Env,
+    manager: &JObject,
+    id: &str,
+    name: &str,
+    importance: i32,
+) -> Result<()> {
+    let id_j = crate::jcall::jstr_obj(env, id)?;
+    let builder = crate::jcall::new_object(
+        env,
+        "androidx/core/app/NotificationChannelCompat$Builder",
+        "(Ljava/lang/String;I)V",
+        &[JValue::Object(&id_j), JValue::Int(importance)],
+    )?;
+    let name_j = crate::jcall::jstr_obj(env, name)?;
+    crate::jcall::call_method(
+        env,
+        &builder,
+        "setName",
+        "(Ljava/lang/CharSequence;)Landroidx/core/app/NotificationChannelCompat$Builder;",
+        &[JValue::Object(&name_j)],
+    )?;
+    let channel = crate::jcall::call_method(
+        env,
+        &builder,
+        "build",
+        "()Landroidx/core/app/NotificationChannelCompat;",
+        &[],
+    )?
+    .l()?;
+    crate::jcall::call_method(
+        env,
+        manager,
+        "createNotificationChannel",
+        "(Landroidx/core/app/NotificationChannelCompat;)V",
+        &[JValue::Object(&channel)],
+    )?;
+    Ok(())
+}
+
+/// Two channels, because they are two different things to be told -- see
+/// `Notifications.kt`'s `createChannels` for the reasoning; the names and
+/// importances here are copied from it exactly, since a phone that has
+/// seen both apps should not learn two different vocabularies for the
+/// same fact.
+fn create_channels(env: &mut Env, context: &JObject) -> Result<()> {
+    let manager = notification_manager(env, context)?;
+    let default = static_int(
+        env,
+        "androidx/core/app/NotificationManagerCompat",
+        "IMPORTANCE_DEFAULT",
+    )?;
+    let min = static_int(
+        env,
+        "androidx/core/app/NotificationManagerCompat",
+        "IMPORTANCE_MIN",
+    )?;
+    create_channel(
+        env,
+        &manager,
+        ALERT_CHANNEL,
+        "Sessions needing attention",
+        default,
+    )?;
+    create_channel(env, &manager, ONGOING_CHANNEL, "Staying connected", min)?;
+    Ok(())
+}
+
+fn new_intent_for<'l>(
+    env: &mut Env<'l>,
+    context: &JObject,
+    class_name: &str,
+) -> Result<JObject<'l>> {
+    let target_class = crate::jcall::find_class(env, class_name)?;
+    crate::jcall::new_object(
+        env,
+        "android/content/Intent",
+        "(Landroid/content/Context;Ljava/lang/Class;)V",
+        &[JValue::Object(context), JValue::Object(&target_class)],
+    )
+}
+
+/// The intent a tap on an alert opens -- mirrors `Notifications.kt`'s
+/// `sessionIntent`, including building the URI through `Uri.Builder`
+/// rather than string concatenation, for the same reason: an id needing
+/// escaping must survive the round trip.
+fn session_intent<'l>(
+    env: &mut Env<'l>,
+    context: &JObject,
+    session_id: &str,
+) -> Result<JObject<'l>> {
+    let intent = new_intent_for(env, context, "com/example/aiapp/shell/MainActivity")?;
+    let action_view = crate::jcall::jstr_obj(env, "android.intent.action.VIEW")?;
+    crate::jcall::call_method(
+        env,
+        &intent,
+        "setAction",
+        "(Ljava/lang/String;)Landroid/content/Intent;",
+        &[JValue::Object(&action_view)],
+    )?;
+    let builder = crate::jcall::new_object(env, "android/net/Uri$Builder", "()V", &[])?;
+    let scheme = crate::jcall::jstr_obj(env, settings::SCHEME)?;
+    crate::jcall::call_method(
+        env,
+        &builder,
+        "scheme",
+        "(Ljava/lang/String;)Landroid/net/Uri$Builder;",
+        &[JValue::Object(&scheme)],
+    )?;
+    let authority = crate::jcall::jstr_obj(env, "session")?;
+    crate::jcall::call_method(
+        env,
+        &builder,
+        "authority",
+        "(Ljava/lang/String;)Landroid/net/Uri$Builder;",
+        &[JValue::Object(&authority)],
+    )?;
+    let path = crate::jcall::jstr_obj(env, session_id)?;
+    crate::jcall::call_method(
+        env,
+        &builder,
+        "appendPath",
+        "(Ljava/lang/String;)Landroid/net/Uri$Builder;",
+        &[JValue::Object(&path)],
+    )?;
+    let uri = crate::jcall::call_method(env, &builder, "build", "()Landroid/net/Uri;", &[])?.l()?;
+    crate::jcall::call_method(
+        env,
+        &intent,
+        "setData",
+        "(Landroid/net/Uri;)Landroid/content/Intent;",
+        &[JValue::Object(&uri)],
+    )?;
+    Ok(intent)
+}
+
+fn pending_activity<'l>(
+    env: &mut Env<'l>,
+    context: &JObject,
+    intent: &JObject,
+) -> Result<JObject<'l>> {
+    let update_current = static_int(env, "android/app/PendingIntent", "FLAG_UPDATE_CURRENT")?;
+    let immutable = static_int(env, "android/app/PendingIntent", "FLAG_IMMUTABLE")?;
+    crate::jcall::call_static_method(
+        env,
+        "android/app/PendingIntent",
+        "getActivity",
+        "(Landroid/content/Context;ILandroid/content/Intent;I)Landroid/app/PendingIntent;",
+        &[
+            JValue::Object(context),
+            JValue::Int(0),
+            JValue::Object(intent),
+            JValue::Int(update_current | immutable),
+        ],
+    )?
+    .l()
+}
+
+fn builder_call<'l>(
+    env: &mut Env<'l>,
+    builder: &JObject<'l>,
+    method: &str,
+    sig: &str,
+    args: &[JValue],
+) -> Result<()> {
+    crate::jcall::call_method(env, builder, method, sig, args)?;
+    Ok(())
+}
+
+/// The type Android 14+ requires a foreground service to declare, and
+/// nothing before it -- mirrors `Notifications.kt`'s `foregroundType`.
+fn foreground_type(env: &mut Env) -> Result<i32> {
+    let sdk = static_int(env, "android/os/Build$VERSION", "SDK_INT")?;
+    let upside_down_cake = static_int(env, "android/os/Build$VERSION_CODES", "UPSIDE_DOWN_CAKE")?;
+    if sdk >= upside_down_cake {
+        static_int(
+            env,
+            "android/content/pm/ServiceInfo",
+            "FOREGROUND_SERVICE_TYPE_SPECIAL_USE",
+        )
+    } else {
+        Ok(0)
+    }
+}
+
+fn ongoing_notification<'l>(env: &mut Env<'l>, context: &JObject) -> Result<JObject<'l>> {
+    let channel = crate::jcall::jstr_obj(env, ONGOING_CHANNEL)?;
+    let builder = crate::jcall::new_object(
+        env,
+        "androidx/core/app/NotificationCompat$Builder",
+        "(Landroid/content/Context;Ljava/lang/String;)V",
+        &[JValue::Object(context), JValue::Object(&channel)],
+    )?;
+    let title = crate::jcall::jstr_obj(env, "Watching for sessions that need you")?;
+    builder_call(
+        env,
+        &builder,
+        "setContentTitle",
+        "(Ljava/lang/CharSequence;)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Object(&title)],
+    )?;
+    let icon = static_int(env, "android/R$drawable", "stat_notify_sync")?;
+    builder_call(
+        env,
+        &builder,
+        "setSmallIcon",
+        "(I)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Int(icon)],
+    )?;
+    builder_call(
+        env,
+        &builder,
+        "setOngoing",
+        "(Z)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Bool(JNI_TRUE)],
+    )?;
+    let priority_min = static_int(env, "androidx/core/app/NotificationCompat", "PRIORITY_MIN")?;
+    builder_call(
+        env,
+        &builder,
+        "setPriority",
+        "(I)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Int(priority_min)],
+    )?;
+    crate::jcall::call_method(env, &builder, "build", "()Landroid/app/Notification;", &[])?.l()
+}
+
+/// Starts the service if there is a server to connect to, and stops it
+/// otherwise -- mirrors `Notifications.kt`'s `NotificationService.sync`.
+pub fn sync(env: &mut Env, context: &JObject) -> Result<()> {
+    let service_intent =
+        new_intent_for(env, context, "com/example/aiapp/shell/NotificationService")?;
+    if settings::load(env, context)?.is_none() {
+        crate::jcall::call_method(
+            env,
+            context,
+            "stopService",
+            "(Landroid/content/Intent;)Z",
+            &[JValue::Object(&service_intent)],
+        )?;
+        return Ok(());
+    }
+    create_channels(env, context)?;
+    crate::jcall::call_static_method(
+        env,
+        "androidx/core/content/ContextCompat",
+        "startForegroundService",
+        "(Landroid/content/Context;Landroid/content/Intent;)V",
+        &[JValue::Object(context), JValue::Object(&service_intent)],
+    )?;
+    Ok(())
+}
+
+/// The `Service.onStartCommand` body -- loads settings, starts the
+/// foreground notification, and spawns the follow-loop thread. Answers the
+/// platform's `START_STICKY`/`START_NOT_STICKY` constant, read from the
+/// framework rather than hardcoded so a wrong guess at their values cannot
+/// silently pick the other behaviour.
+pub fn on_start_command(env: &mut Env, service: JObject) -> jint {
+    match try_start(env, &service) {
+        Ok(true) => static_int(env, "android/app/Service", "START_STICKY").unwrap_or(1),
+        Ok(false) => {
+            let _ = crate::jcall::call_method(env, &service, "stopSelf", "()V", &[]);
+            static_int(env, "android/app/Service", "START_NOT_STICKY").unwrap_or(2)
+        }
+        Err(e) => {
+            log_error(env, "onStartCommand", &e);
+            static_int(env, "android/app/Service", "START_NOT_STICKY").unwrap_or(2)
+        }
+    }
+}
+
+fn try_start(env: &mut Env, service: &JObject) -> Result<bool> {
+    let Some(settings) = settings::load(env, service)? else {
+        return Ok(false);
+    };
+    let ca = settings::load_pinned_ca(env)?;
+    let notification = ongoing_notification(env, service)?;
+    let fg_type = foreground_type(env)?;
+    crate::jcall::call_static_method(
+        env,
+        "androidx/core/app/ServiceCompat",
+        "startForeground",
+        "(Landroid/app/Service;ILandroid/app/Notification;I)V",
+        &[
+            JValue::Object(service),
+            JValue::Int(ONGOING_ID),
+            JValue::Object(&notification),
+            JValue::Int(fg_type),
+        ],
+    )?;
+
+    // See `RUNNING`'s doc: a second `onStartCommand` while the loop from
+    // the first is still going -- the ordinary case for this service,
+    // since `sync()` is called from more than one place -- must not open
+    // a second connection.
+    if RUNNING.swap(true, Ordering::SeqCst) {
+        return Ok(true);
+    }
+
+    let vm = env.get_java_vm()?;
+    let context = env.new_global_ref(service)?;
+    STOPPING.store(false, Ordering::SeqCst);
+    std::thread::Builder::new()
+        .name("ai-app-notifications".to_string())
+        .spawn(move || {
+            // Requests a *permanent* attachment (detached only when this thread
+            // exits), matching the Kotlin original's `thread(isDaemon = true)`:
+            // this is the long-lived follow loop, not a one-shot callback.
+            let _: jni::errors::Result<()> = vm.attach_current_thread(|env| {
+                follow_loop(env, &context, settings, &ca);
+                Ok(())
+            });
+        })
+        .ok();
+    Ok(true)
+}
+
+/// Follows the backend's notification stream, reconnecting until stopped
+/// -- mirrors `Notifications.kt`'s `follow`. A dropped connection is the
+/// ordinary case, so it retries quietly and forever; nothing is shown when
+/// it cannot connect, for the same reason as the Kotlin original: a
+/// notification saying "I could not tell you whether anything happened" is
+/// noise about a condition nobody can act on.
+fn follow_loop(env: &mut Env, context: &JObject, settings: ServerSettings, ca: &[u8]) {
+    while !STOPPING.load(Ordering::SeqCst) {
+        if let Ok(transport) = UreqTransport::new(settings.base_url(), settings.token.clone(), ca) {
+            let _ = follow_notifications(&transport, |notification| {
+                if let Err(e) = show(env, context, &notification) {
+                    log_error(env, "show", &e);
+                }
+                !STOPPING.load(Ordering::SeqCst)
+            });
+        }
+        if STOPPING.load(Ordering::SeqCst) {
+            return;
+        }
+        std::thread::sleep(RECONNECT_DELAY);
+    }
+}
+
+/// One notification per session, replacing that session's previous one --
+/// mirrors `Notifications.kt`'s `show`, minus the on-screen/banner
+/// branches this module's doc comment explains.
+fn show(env: &mut Env, context: &JObject, notification: &SessionNotification) -> Result<()> {
+    let manager = notification_manager(env, context)?;
+    let sdk = static_int(env, "android/os/Build$VERSION", "SDK_INT")?;
+    let tiramisu = static_int(env, "android/os/Build$VERSION_CODES", "TIRAMISU")?;
+    let allowed = if sdk < tiramisu {
+        true
+    } else {
+        let permission = crate::jcall::jstr_obj(env, "android.permission.POST_NOTIFICATIONS")?;
+        let granted = static_int(
+            env,
+            "android/content/pm/PackageManager",
+            "PERMISSION_GRANTED",
+        )?;
+        let result = crate::jcall::call_static_method(
+            env,
+            "androidx/core/content/ContextCompat",
+            "checkSelfPermission",
+            "(Landroid/content/Context;Ljava/lang/String;)I",
+            &[JValue::Object(context), JValue::Object(&permission)],
+        )?
+        .i()?;
+        result == granted
+    };
+    let enabled =
+        crate::jcall::call_method(env, &manager, "areNotificationsEnabled", "()Z", &[])?.z()?;
+    if !allowed || !enabled {
+        return Ok(());
+    }
+    let intent = session_intent(env, context, &notification.session_id)?;
+    let pending = pending_activity(env, context, &intent)?;
+    let channel = crate::jcall::jstr_obj(env, ALERT_CHANNEL)?;
+    let builder = crate::jcall::new_object(
+        env,
+        "androidx/core/app/NotificationCompat$Builder",
+        "(Landroid/content/Context;Ljava/lang/String;)V",
+        &[JValue::Object(context), JValue::Object(&channel)],
+    )?;
+    let title = crate::jcall::jstr_obj(env, &notification.title)?;
+    builder_call(
+        env,
+        &builder,
+        "setContentTitle",
+        "(Ljava/lang/CharSequence;)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Object(&title)],
+    )?;
+    let text = crate::jcall::jstr_obj(env, notification.kind.attention_line())?;
+    builder_call(
+        env,
+        &builder,
+        "setContentText",
+        "(Ljava/lang/CharSequence;)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Object(&text)],
+    )?;
+    let icon = static_int(env, "android/R$drawable", "stat_notify_chat")?;
+    builder_call(
+        env,
+        &builder,
+        "setSmallIcon",
+        "(I)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Int(icon)],
+    )?;
+    builder_call(
+        env,
+        &builder,
+        "setContentIntent",
+        "(Landroid/app/PendingIntent;)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Object(&pending)],
+    )?;
+    builder_call(
+        env,
+        &builder,
+        "setAutoCancel",
+        "(Z)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Bool(JNI_TRUE)],
+    )?;
+    let when = (notification.at * 1000.0) as i64;
+    builder_call(
+        env,
+        &builder,
+        "setWhen",
+        "(J)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Long(when)],
+    )?;
+    builder_call(
+        env,
+        &builder,
+        "setShowWhen",
+        "(Z)Landroidx/core/app/NotificationCompat$Builder;",
+        &[JValue::Bool(JNI_TRUE)],
+    )?;
+    let built =
+        crate::jcall::call_method(env, &builder, "build", "()Landroid/app/Notification;", &[])?
+            .l()?;
+    let tag = crate::jcall::jstr_obj(env, &notification.session_id)?;
+    crate::jcall::call_method(
+        env,
+        &manager,
+        "notify",
+        "(Ljava/lang/String;ILandroid/app/Notification;)V",
+        &[
+            JValue::Object(&tag),
+            JValue::Int(ALERT_ID),
+            JValue::Object(&built),
+        ],
+    )?;
+    Ok(())
+}
+
+/// Ends the follow loop -- mirrors `Notifications.kt`'s `onDestroy`, with
+/// the gap this module's `STOPPING` doc explains.
+pub fn on_destroy() {
+    STOPPING.store(true, Ordering::SeqCst);
+    // `RUNNING`'s path out. Same race as `STOPPING` itself (this doc's own
+    // comment): the old thread may still be inside a blocked read when a
+    // new `onStartCommand` follows immediately, which would spawn a
+    // second one before the first has actually stopped. Narrower than not
+    // resetting at all -- a service destroyed and never restarted would
+    // otherwise wedge `RUNNING` true forever -- and no worse than the
+    // known gap already accepted above.
+    RUNNING.store(false, Ordering::SeqCst);
+}
+
+pub fn log_error(env: &mut Env, where_: &str, error: &jni::errors::Error) {
+    let message = format!("android-shell: {where_}: {error}");
+    let _ = (|| -> Result<()> {
+        let tag = crate::jcall::jstr_obj(env, "android-shell")?;
+        let msg = crate::jcall::jstr_obj(env, &message)?;
+        crate::jcall::call_static_method(
+            env,
+            "android/util/Log",
+            "e",
+            "(Ljava/lang/String;Ljava/lang/String;)I",
+            &[JValue::Object(&tag), JValue::Object(&msg)],
+        )?;
+        Ok(())
+    })();
+}

android-shell/src/settings.rs

@@ -0,0 +1,141 @@
+//! Enrollment: where the backend is, and the Keystore-sealed token to
+//! reach it. This crate does not reimplement the Android Keystore AES-GCM
+//! sealing in Rust -- it calls the same `wg-app-link` `ServerStore` Kotlin
+//! class the production app already uses (see `ServerConfig.kt`), through
+//! JNI, for two reasons: that code is shared with Dev Updater and already
+//! tested, and the sealed value on a real phone is keyed to the exact
+//! Keystore alias that class already uses -- reimplementing the crypto
+//! here would either duplicate it or invalidate an existing enrollment.
+
+use jni::Env;
+use jni::errors::Result;
+use jni::objects::{JObject, JString, JValue};
+
+/// Where the backend is and how to authenticate to it -- the Rust twin of
+/// `wg-app-link`'s `ServerSettings` data class, read back field by field
+/// rather than kept as a live JNI reference, so it can cross a thread
+/// boundary (a `JObject` is tied to one `Env`/thread).
+#[derive(Debug, Clone)]
+pub struct ServerSettings {
+    pub host: String,
+    pub port: i32,
+    pub token: String,
+}
+
+impl ServerSettings {
+    pub fn base_url(&self) -> String {
+        format!("https://{}:{}", self.host, self.port)
+    }
+}
+
+/// This experiment's own scheme and Keystore alias -- distinct from the
+/// production app's (`aiapp` / `aiapp-token-key`) so the two can be
+/// installed side by side on the same development device without
+/// colliding over which one a scanned QR or a deep link resolves to. See
+/// RUST.md's E3 entry for why they are not the same value.
+pub(crate) const SCHEME: &str = "aiappshell";
+const KEY_ALIAS: &str = "aiapp-shell-token-key";
+const STORE_CLASS: &str = "com/example/wgapplink/ServerStore";
+const SETTINGS_CLASS: &str = "com/example/wgapplink/ServerSettings";
+
+fn new_store<'l>(env: &mut Env<'l>) -> Result<JObject<'l>> {
+    let scheme = crate::jcall::jstr_obj(env, SCHEME)?;
+    let alias = crate::jcall::jstr_obj(env, KEY_ALIAS)?;
+    crate::jcall::new_object(
+        env,
+        STORE_CLASS,
+        "(Ljava/lang/String;Ljava/lang/String;)V",
+        &[JValue::Object(&scheme), JValue::Object(&alias)],
+    )
+}
+
+fn read_settings(env: &mut Env, settings_obj: &JObject) -> Result<ServerSettings> {
+    let host = get_string(env, settings_obj, "getHost")?;
+    let port = crate::jcall::call_method(env, settings_obj, "getPort", "()I", &[])?.i()?;
+    let token = get_string(env, settings_obj, "getToken")?;
+    Ok(ServerSettings { host, port, token })
+}
+
+fn get_string(env: &mut Env, obj: &JObject, getter: &str) -> Result<String> {
+    let value = crate::jcall::call_method(env, obj, getter, "()Ljava/lang/String;", &[])?.l()?;
+    let jstr: JString = env.cast_local::<JString>(value)?;
+    jstr.try_to_string(env)
+}
+
+/// The stored enrollment, or `None` when there is not one -- mirrors
+/// `ServerConfig.kt`'s `loadServerSettings`.
+pub fn load(env: &mut Env, context: &JObject) -> Result<Option<ServerSettings>> {
+    let store = new_store(env)?;
+    let settings_obj = crate::jcall::call_method(
+        env,
+        &store,
+        "load",
+        "(Landroid/content/Context;)Lcom/example/wgapplink/ServerSettings;",
+        &[JValue::Object(context)],
+    )?
+    .l()?;
+    if settings_obj.is_null() {
+        return Ok(None);
+    }
+    Ok(Some(read_settings(env, &settings_obj)?))
+}
+
+/// Seals and stores `settings` -- mirrors `ServerConfig.kt`'s `saveServerSettings`.
+pub fn save(env: &mut Env, context: &JObject, settings: &ServerSettings) -> Result<()> {
+    let store = new_store(env)?;
+    let host = crate::jcall::jstr_obj(env, &settings.host)?;
+    let token = crate::jcall::jstr_obj(env, &settings.token)?;
+    let settings_obj = crate::jcall::new_object(
+        env,
+        SETTINGS_CLASS,
+        "(Ljava/lang/String;ILjava/lang/String;)V",
+        &[
+            JValue::Object(&host),
+            JValue::Int(settings.port),
+            JValue::Object(&token),
+        ],
+    )?;
+    crate::jcall::call_method(
+        env,
+        &store,
+        "save",
+        "(Landroid/content/Context;Lcom/example/wgapplink/ServerSettings;)V",
+        &[JValue::Object(context), JValue::Object(&settings_obj)],
+    )?;
+    Ok(())
+}
+
+/// Parses an `aiappshell://enroll?...` URI -- mirrors `ServerConfig.kt`'s
+/// `parseEnrollmentUri`, asking the same Kotlin code that already owns the
+/// query-parameter rules rather than re-deriving them here.
+pub fn parse_enrollment_uri(env: &mut Env, uri: &JObject) -> Result<Option<ServerSettings>> {
+    let store = new_store(env)?;
+    let settings_obj = crate::jcall::call_method(
+        env,
+        &store,
+        "parseEnrollmentUri",
+        "(Landroid/net/Uri;)Lcom/example/wgapplink/ServerSettings;",
+        &[JValue::Object(uri)],
+    )?
+    .l()?;
+    if settings_obj.is_null() {
+        return Ok(None);
+    }
+    Ok(Some(read_settings(env, &settings_obj)?))
+}
+
+/// The CA this build pins, generated at build time the same way
+/// `androidApp`'s `generatePinnedCert` task does (see `build.gradle.kts`)
+/// but into a plain Java constant, since this module has no Kotlin of its
+/// own to generate into.
+pub fn load_pinned_ca(env: &mut Env) -> Result<Vec<u8>> {
+    let value = crate::jcall::get_static_field(
+        env,
+        "com/example/aiapp/shell/PinnedCa",
+        "PINNED_CA_PEM",
+        "Ljava/lang/String;",
+    )?
+    .l()?;
+    let jstr: JString = env.cast_local::<JString>(value)?;
+    Ok(jstr.try_to_string(env)?.into_bytes())
+}

android-shell/src/share.rs

@@ -0,0 +1,183 @@
+//! Deep links and the share sheet -- ported from `MainActivity.kt`'s
+//! `handleIntent`/`onNewIntent` and `Share.kt`'s `sharedContent`.
+//!
+//! **Scope cut, recorded rather than silent**: only shared *text*
+//! (`Intent.EXTRA_TEXT`) is attached to a session. `Attachments.kt`'s
+//! upload path -- `ContentResolver` reads of a shared file/photo URI,
+//! bitmap downscaling, EXIF rotation -- is real work of its own and is not
+//! ported here, because `client-core`'s `ApiClient` does not have the
+//! `/sessions/{id}/attachments` route yet either (see `CLIENT_CORE.md`'s
+//! "not covered" list). So `ACTION_SEND`/`ACTION_SEND_MULTIPLE` with a
+//! `content://` stream and no text falls through to a toast saying so,
+//! rather than silently doing nothing. Closing this gap is the same
+//! `client-core` work whichever caller needs it next.
+//!
+//! **Which session a share lands in** is also a placeholder: with no
+//! screen drawn yet (E4's job), there is no picker to ask, so this attaches
+//! to whichever session has the latest `last_activity` -- the one most
+//! likely to be what somebody meant. Worth revisiting once a real screen
+//! exists to ask instead of guessing.
+
+use client_core::api::{ApiClient, UreqTransport};
+use jni::Env;
+use jni::errors::Result;
+use jni::objects::{JObject, JString, JValue};
+
+use crate::notify;
+use crate::settings;
+
+const ACTION_SEND: &str = "android.intent.action.SEND";
+const ACTION_SEND_MULTIPLE: &str = "android.intent.action.SEND_MULTIPLE";
+const ACTION_VIEW: &str = "android.intent.action.VIEW";
+const EXTRA_TEXT: &str = "android.intent.extra.TEXT";
+
+fn get_string_method(env: &mut Env, obj: &JObject, method: &str) -> Result<Option<String>> {
+    let value = crate::jcall::call_method(env, obj, method, "()Ljava/lang/String;", &[])?.l()?;
+    if value.is_null() {
+        return Ok(None);
+    }
+    let jstr: JString = env.cast_local::<JString>(value)?;
+    Ok(Some(jstr.try_to_string(env)?))
+}
+
+fn toast(env: &mut Env, context: &JObject, message: &str) -> Result<()> {
+    let message = crate::jcall::jstr_obj(env, message)?;
+    crate::jcall::call_static_method(
+        env,
+        "com/example/aiapp/shell/MainActivity",
+        "toast",
+        "(Landroid/content/Context;Ljava/lang/String;)V",
+        &[JValue::Object(context), JValue::Object(&message)],
+    )?;
+    Ok(())
+}
+
+/// The one place an incoming intent is sorted into what it means -- mirrors
+/// `MainActivity.kt`'s `handleIntent`.
+pub fn handle_intent(env: &mut Env, activity: &JObject, intent: &JObject) -> Result<()> {
+    let action = get_string_method(env, intent, "getAction")?;
+    if matches!(
+        action.as_deref(),
+        Some(ACTION_SEND) | Some(ACTION_SEND_MULTIPLE)
+    ) {
+        return handle_share(env, activity, intent);
+    }
+    if action.as_deref() != Some(ACTION_VIEW) {
+        return Ok(());
+    }
+    let uri = crate::jcall::call_method(env, intent, "getData", "()Landroid/net/Uri;", &[])?.l()?;
+    if uri.is_null() {
+        return Ok(());
+    }
+    let scheme = get_string_method(env, &uri, "getScheme")?;
+    if scheme.as_deref() != Some(settings::SCHEME) {
+        return Ok(());
+    }
+    match get_string_method(env, &uri, "getHost")?.as_deref() {
+        Some("session") => handle_session_open(env, activity, &uri),
+        Some("enroll") => handle_enrollment(env, activity, &uri),
+        _ => Ok(()),
+    }
+}
+
+fn handle_session_open(env: &mut Env, activity: &JObject, uri: &JObject) -> Result<()> {
+    let Some(session_id) = get_string_method(env, uri, "getLastPathSegment")? else {
+        return Ok(());
+    };
+    // There is no session screen yet (E4's job); the toast is this
+    // experiment's stand-in proof that the tap was routed to the right
+    // session id.
+    toast(env, activity, &format!("Opened session {session_id}"))
+}
+
+fn handle_enrollment(env: &mut Env, activity: &JObject, uri: &JObject) -> Result<()> {
+    match settings::parse_enrollment_uri(env, uri)? {
+        Some(parsed) => {
+            settings::save(env, activity, &parsed)?;
+            notify::sync(env, activity)?;
+            toast(
+                env,
+                activity,
+                &format!("Enrolled with {}", parsed.base_url()),
+            )
+        }
+        None => toast(env, activity, "Not a valid enrollment code"),
+    }
+}
+
+/// The share sheet -- mirrors `Share.kt`'s `sharedContent` for what counts
+/// as a share, and `AttachmentButton`'s upload-then-message pattern for
+/// what happens to it, minus attachments per this module's doc comment.
+fn handle_share(env: &mut Env, activity: &JObject, intent: &JObject) -> Result<()> {
+    let extra_text = crate::jcall::jstr_obj(env, EXTRA_TEXT)?;
+    let text = crate::jcall::call_method(
+        env,
+        intent,
+        "getStringExtra",
+        "(Ljava/lang/String;)Ljava/lang/String;",
+        &[JValue::Object(&extra_text)],
+    )?
+    .l()?;
+    let text = if text.is_null() {
+        None
+    } else {
+        let jstr: JString = env.cast_local::<JString>(text)?;
+        Some(jstr.try_to_string(env)?)
+    };
+    let Some(text) = text.filter(|t| !t.trim().is_empty()) else {
+        return toast(
+            env,
+            activity,
+            "Nothing to share -- only shared text is supported so far",
+        );
+    };
+
+    // Network I/O must not run on the calling thread: `handle_intent` is
+    // called from `onCreate`/`onNewIntent`, both on the main thread, and a
+    // blocking socket read there is a `NetworkOnMainThreadException`. So
+    // the actual send happens on a JNI-attached background thread, the
+    // same shape `notify::try_start`'s follow loop uses; `toast` from that
+    // thread is safe because `MainActivity.toast` itself hops back to the
+    // main looper (see that method).
+    let vm = env.get_java_vm()?;
+    let activity_ref = env.new_global_ref(activity)?;
+    std::thread::spawn(move || {
+        let _: jni::errors::Result<()> = vm.attach_current_thread(|env| {
+            share_in_background(env, &activity_ref, text);
+            Ok(())
+        });
+    });
+    Ok(())
+}
+
+fn share_in_background(env: &mut Env, activity: &JObject, text: String) {
+    let outcome = attach_to_a_session(env, activity, &text);
+    let message = match outcome {
+        Ok(title) => format!("Shared into \"{title}\""),
+        Err(message) => message,
+    };
+    let _ = toast(env, activity, &message);
+}
+
+fn attach_to_a_session(
+    env: &mut Env,
+    activity: &JObject,
+    text: &str,
+) -> std::result::Result<String, String> {
+    let settings = settings::load(env, activity)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| "Not enrolled yet".to_string())?;
+    let ca = settings::load_pinned_ca(env).map_err(|e| e.to_string())?;
+    let transport = UreqTransport::new(settings.base_url(), settings.token.clone(), &ca)
+        .map_err(|e| e.to_string())?;
+    let client = ApiClient::new(transport);
+    let sessions = client.fetch_sessions().map_err(|e| e.to_string())?;
+    let target = sessions
+        .into_iter()
+        .max_by(|a, b| a.last_activity.total_cmp(&b.last_activity))
+        .ok_or_else(|| "No session to share into".to_string())?;
+    client
+        .send_message(&target.id, text, &[])
+        .map_err(|e| e.to_string())?;
+    Ok(target.title)
+}

app/settings.gradle.kts

@@ -17,6 +17,11 @@ dependencyResolutionManagement {
 
 include(":androidApp")
 
+// E3 (RUST.md): the Kotlin/Java shell over android-shell's JNI bridge, a
+// separate module from :androidApp so the ~13,000 lines of working Compose
+// UI there are untouched. See shellApp/build.gradle.kts's module comment.
+include(":shellApp")
+
 // The app half of wg-app-link, resolved by path through the submodule so
 // this checkout and the crate it consumes move together -- the same
 // arrangement `server/` uses for the Rust half. See that repo's README.

app/shellApp/build.gradle.kts

@@ -0,0 +1,163 @@
+plugins { alias(libs.plugins.androidApplication) }
+
+// E3 (RUST.md): the Kotlin/Java shell being replaced by a thin JNI bridge
+// into Rust (`../../android-shell`). Deliberately its own module rather
+// than a rewrite of `:androidApp` in place -- that module is ~13,000 lines
+// of working Compose UI this experiment does not touch, and the two can be
+// installed side by side on the same development device (see
+// `settings.SCHEME`'s doc in `android-shell` for why the deep-link scheme
+// and Keystore alias are not the production app's). No Compose plugin, no
+// Kotlin source of its own: `MainActivity`/`NotificationService` are plain
+// Java, and the CA constant below is generated as Java too.
+//
+// The CA this build pins is baked in the same way `androidApp`'s does --
+// see that module's `build.gradle.kts` comment for the reasoning (the
+// trust boundary follows the machine that builds, never a pasted copy).
+// `PinnedCa.java`'s package must match `android-shell`'s
+// `settings::load_pinned_ca` lookup (`com/example/aiapp/shell/PinnedCa`).
+val pinnedCaPath: String =
+    System.getenv("AI_APP_CA")
+        ?: "${System.getenv("XDG_CONFIG_HOME") ?: "${System.getProperty("user.home")}/.config"}" +
+            "/ai-app/certs/ca.pem"
+
+abstract class GeneratePinnedCa : DefaultTask() {
+    @get:Input abstract val caPath: Property<String>
+
+    @get:InputFile
+    @get:Optional
+    @get:PathSensitive(PathSensitivity.NONE)
+    abstract val caCertificate: RegularFileProperty
+
+    @get:OutputDirectory abstract val outputDir: DirectoryProperty
+
+    @TaskAction
+    fun generate() {
+        val path = caPath.get()
+        val ca = File(path)
+        if (!ca.isFile) {
+            throw GradleException(
+                "No CA certificate at $path.\n" +
+                    "Start ai-server (or app/ui-sandbox.sh) once on this machine first -- it " +
+                    "generates the CA this build pins.\n" +
+                    "Set AI_APP_CA=/path/to/ca.pem to build against a different one."
+            )
+        }
+        val pem = ca.readText().trim()
+        if (!pem.startsWith("-----BEGIN CERTIFICATE-----")) {
+            throw GradleException("$path is not a PEM certificate.")
+        }
+        val dir = outputDir.get().dir("com/example/aiapp/shell").asFile
+        dir.mkdirs()
+        // Same reasoning as androidApp's generatePinnedCert: the text block
+        // must start immediately after the opening `"""`, or
+        // CertificateFactory stops recognising the "-----BEGIN" preamble.
+        File(dir, "PinnedCa.java")
+            .writeText(
+                """
+                |// Generated from $path by the generatePinnedCa task. Do not edit.
+                |package com.example.aiapp.shell;
+                |
+                |public final class PinnedCa {
+                |    private PinnedCa() {}
+                |    public static final String PINNED_CA_PEM = ""${'"'}
+                |$pem""${'"'};
+                |}
+                |"""
+                    .trimMargin()
+            )
+    }
+}
+
+val generatePinnedCa =
+    tasks.register<GeneratePinnedCa>("generatePinnedCa") {
+        val ca = file(pinnedCaPath)
+        caPath.set(pinnedCaPath)
+        if (ca.isFile) {
+            caCertificate.set(ca)
+        }
+    }
+
+android {
+    namespace = "com.example.aiapp.shell"
+    compileSdk = 37
+
+    defaultConfig {
+        applicationId = "com.example.aiapp.shell"
+        minSdk = 24
+        targetSdk = 37
+        versionCode = 1
+        versionName = "1.0"
+    }
+    // Same reasoning and same key as androidApp's (see that module's comment): E5 (RUST.md)
+    // signs its own, Gradle-free build with this same keystore, and the two can only
+    // `adb install -r` over each other if they carry the same certificate.
+    val keystore = System.getenv("AI_APP_KEYSTORE")
+    signingConfigs {
+        if (keystore != null) {
+            create("release") {
+                storeFile = file(keystore)
+                storePassword = System.getenv("AI_APP_KEYSTORE_PASSWORD")
+                keyAlias = "ai-app"
+                keyPassword = storePassword
+            }
+        }
+    }
+    buildTypes {
+        getByName("release") {
+            isMinifyEnabled = false
+            if (keystore != null) signingConfig = signingConfigs.getByName("release")
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+}
+
+// E5 (RUST.md): the xtask dexes and packages this module's Java sources itself, but it does
+// not resolve Maven dependencies -- reimplementing a dependency resolver was out of scope for a
+// packaging step, so this one task is the single place Gradle still runs in that pipeline. It
+// asks the dependency graph for the *post-transform* jars (AARs already unpacked to a classes
+// jar, the same artifact type AGP's own dexing task consumes) rather than the raw configuration,
+// which would hand back .aar files d8 cannot read directly.
+val artifactType = Attribute.of("artifactType", String::class.java)
+
+tasks.register("printRuntimeClasspathJars") {
+    description = "Writes the resolved release runtime classpath jars, one per line, for xtask."
+    val outputFile = layout.buildDirectory.file("xtask/runtime-classpath.txt")
+    outputs.file(outputFile)
+    val jars =
+        configurations
+            .getByName("releaseRuntimeClasspath")
+            .incoming
+            .artifactView { attributes.attribute(artifactType, "android-classes-jar") }
+            .files
+    // Captured as a plain FileCollection (not the ArtifactView itself, which the
+    // configuration cache cannot serialize) so this task is still cacheable.
+    inputs.files(jars)
+    doLast {
+        val file = outputFile.get().asFile
+        file.parentFile.mkdirs()
+        file.writeText(jars.joinToString("\n") { it.absolutePath })
+    }
+}
+
+androidComponents {
+    onVariants { variant ->
+        variant.sources.java?.addGeneratedSourceDirectory(generatePinnedCa, GeneratePinnedCa::outputDir)
+    }
+}
+
+dependencies {
+    // The Keystore-sealed enrollment (ServerStore/ServerSettings) --
+    // android-shell's settings.rs calls into this Kotlin class directly
+    // over JNI rather than re-sealing the token in Rust; see that file's
+    // module doc.
+    implementation(project(":link"))
+    // NotificationCompat/NotificationManagerCompat/NotificationChannelCompat/
+    // ServiceCompat -- android-shell's notify.rs calls these classes over
+    // JNI so the pre-26 fallback behaviour (no channels) lives once, in
+    // the library that already has it, rather than being re-derived as a
+    // set of Build.VERSION.SDK_INT branches in Rust.
+    implementation(libs.androidx.core.ktx)
+}

app/shellApp/src/main/AndroidManifest.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+    <!-- Mirrors androidApp's manifest (AGENTS.md: reuse it rather than
+         re-deriving it) for the permissions and declarations E3 actually
+         exercises. Not carried over: the QR scanner activity (this
+         experiment enrolls via the aiappshell://enroll deep link directly,
+         per AGENTS.md's ui-sandbox.sh banner) and the app icon warning
+         suppression below, for the same reason androidApp's is there. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+
+    <application
+        android:label="AI Sessions (shell)"
+        android:allowBackup="true"
+        android:theme="@android:style/Theme.Material.Light.NoActionBar"
+        tools:ignore="MissingApplicationIcon">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+            <!-- Enrollment: aiappshell://enroll?host=...&port=...&token=...,
+                 per AGENTS.md's ui-sandbox.sh banner (fed to this app with
+                 `adb shell am start -a android.intent.action.VIEW -d
+                 'aiappshell://enroll?...'`, or -n'd at this component
+                 directly if a second app also claims the aiapp scheme). -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="aiappshell" android:host="enroll" />
+            </intent-filter>
+            <!-- The share sheet - see android-shell's share.rs. -->
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <action android:name="android.intent.action.SEND_MULTIPLE" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="*/*" />
+            </intent-filter>
+        </activity>
+
+        <!-- specialUse, not dataSync, for the reason androidApp's manifest
+             gives: a connection that has to keep listening overnight
+             cannot accept dataSync's six-hour cap. -->
+        <service
+            android:name=".NotificationService"
+            android:exported="false"
+            android:foregroundServiceType="specialUse">
+            <property
+                android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
+                android:value="E3 experiment: holds one connection to the sandbox server so a
+                    session that needs an answer can be reported while the app is closed." />
+        </service>
+    </application>
+</manifest>

app/shellApp/src/main/java/com/example/aiapp/shell/MainActivity.java

@@ -0,0 +1,50 @@
+package com.example.aiapp.shell;
+
+import android.app.Activity;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Bundle;
+import android.os.Handler;
+import android.os.Looper;
+import android.widget.Toast;
+
+/**
+ * E3's floor, per RUST.md's "How much Java is unavoidable": a class the framework
+ * constructs by name from the manifest, with its lifecycle methods handing straight to Rust
+ * (android-shell's {@code share::handle_intent}). No Compose, no layout -- there is no screen to
+ * draw yet (that is E4's job, on iris); {@link #toast} is this experiment's stand-in for showing
+ * something happened.
+ */
+public class MainActivity extends Activity {
+    static {
+        System.loadLibrary("android_shell");
+    }
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        NotificationService.sync(this);
+        nativeHandleIntent(this, getIntent());
+    }
+
+    // launchMode="singleTop": a notification tap or a share while this activity is already on
+    // top lands here rather than in a second instance -- same reasoning as MainActivity.kt's.
+    @Override
+    protected void onNewIntent(Intent intent) {
+        super.onNewIntent(intent);
+        setIntent(intent);
+        nativeHandleIntent(this, intent);
+    }
+
+    /**
+     * Called from android-shell, sometimes from a background thread (a share's network call is
+     * never made on the calling thread -- see share.rs). {@code Toast} itself is main-thread-only,
+     * so this hops there with a {@link Handler} rather than assuming the caller already has.
+     */
+    static void toast(Context context, String message) {
+        new Handler(Looper.getMainLooper())
+                .post(() -> Toast.makeText(context, message, Toast.LENGTH_LONG).show());
+    }
+
+    private static native void nativeHandleIntent(Activity activity, Intent intent);
+}

app/shellApp/src/main/java/com/example/aiapp/shell/NotificationService.java

@@ -0,0 +1,45 @@
+package com.example.aiapp.shell;
+
+import android.app.Service;
+import android.content.Context;
+import android.content.Intent;
+import android.os.IBinder;
+
+/**
+ * E3's second unavoidable Java class (RUST.md): a foreground service constructed by the framework
+ * from the manifest, existing only to hand its lifecycle to android-shell's {@code notify} module
+ * -- the SSE follow loop, deciding what a notification says, and posting it are all Rust reached
+ * through these three native calls. See {@code Notifications.kt}'s {@code NotificationService} for
+ * the Kotlin original this mirrors.
+ */
+public class NotificationService extends Service {
+    static {
+        System.loadLibrary("android_shell");
+    }
+
+    @Override
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        return nativeOnStartCommand(this);
+    }
+
+    @Override
+    public void onDestroy() {
+        nativeOnDestroy();
+    }
+
+    /** Starts this service if there is a server to connect to, and stops it otherwise. */
+    static void sync(Context context) {
+        nativeSync(context);
+    }
+
+    private static native void nativeSync(Context context);
+
+    private static native int nativeOnStartCommand(Service service);
+
+    private static native void nativeOnDestroy();
+}

client-core/Cargo.lock

@@ -0,0 +1,940 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "005ec2760ca554fae18df7a11195552ec576cd665632a881bc011d5bb2fd4d80"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "client-core"
+version = "0.1.0"
+dependencies = [
+ "event-model",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "ureq",
+]
+
+[[package]]
+name = "cookie"
+version = "0.18.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a373e3602691c3cdea496d2f0ee5935151e6168fe87739483c463db1b2f2f87"
+dependencies = [
+ "percent-encoding",
+ "time",
+ "version_check",
+]
+
+[[package]]
+name = "cookie_store"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206"
+dependencies = [
+ "cookie",
+ "document-features",
+ "idna",
+ "indexmap",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "time",
+ "url",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "deranged"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
+
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "event-model"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e0f1c7c3a72c66fd80abe965175f7523475c0489a87d3ff9d6e8c87d87a9d2d"
+
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+ "zlib-rs",
+]
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "icu_collections"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
+
+[[package]]
+name = "icu_properties"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
+dependencies = [
+ "displaydoc",
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
+
+[[package]]
+name = "icu_provider"
+version = "2.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
+
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "num-conv"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "powerfmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.43"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
+dependencies = [
+ "log",
+ "once_cell",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+dependencies = [
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "smallvec"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9be42f50aa861c555654aa3a37f52f4b1074bacf4e48fe0ef7fa584e80f1f0f"
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "time"
+version = "0.3.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134"
+dependencies = [
+ "deranged",
+ "num-conv",
+ "powerfmt",
+ "serde_core",
+ "time-core",
+ "time-macros",
+]
+
+[[package]]
+name = "time-core"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
+
+[[package]]
+name = "time-macros"
+version = "0.2.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "ureq"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "972d7902c8735f2695410b8aed7df6ed12a47394aa1c8d7af49f0497b731a94d"
+dependencies = [
+ "base64",
+ "cookie_store",
+ "flate2",
+ "log",
+ "percent-encoding",
+ "rustls",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "ureq-proto",
+ "utf8-zero",
+ "webpki-roots",
+]
+
+[[package]]
+name = "ureq-proto"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da5f78b09e6941e1a0f2e30e695e4b120377b54d5e0aec11b594bb57b3971613"
+dependencies = [
+ "base64",
+ "http",
+ "httparse",
+ "log",
+]
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8-zero"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8c0a043c9540bae7c578c88f91dda8bd82e59ae27c21baca69c8b191aaf5a6e"
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "writeable"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34b31d188d9d685a4f9c7b46d6e36631b07058d2cfe190267adce54dc230bf12"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

client-core/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "client-core"
+version = "0.1.0"
+edition = "2024"
+
+# The app's pure logic, held once instead of twice: the event model (shared
+# with `server/` via `event-model`), the REST + SSE clients for its HTTP
+# surface (see `server/src/routes.rs`'s module doc for the table), the
+# transcript fold and cache, the markdown block model, the syntax
+# highlighter and the ANSI parser. See CLIENT_CORE.md at the repo root for
+# what this holds today, what it does not yet, and how it corresponds to
+# the Kotlin it replaces.
+#
+# No UI framework dependency of any kind -- this crate is meant to outlive
+# whichever one the app ends up drawing with (see RUST.md).
+
+[dependencies]
+event-model = { path = "../event-model" }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["float_roundtrip"] }
+# The blocking HTTP client for the REST calls and the long-lived SSE GETs.
+# `server/` already depends on ureq for its own outbound HTTPS (the usage
+# poll in usage.rs) and it is rustls-backed like the rest of this project's
+# TLS, so this reuses that choice rather than pulling in reqwest's async
+# stack -- a client that runs one blocking request at a time, the way
+# Api.kt's `HttpURLConnection` calls and Sse.kt's blocking read loop do, has
+# no need of an async runtime, and RUST.md's brief for this port is
+# "lightweight" throughout.
+ureq = { version = "3", features = ["json"] }
+
+[dev-dependencies]
+tempfile = "3"

client-core/src/ansi.rs

@@ -0,0 +1,534 @@
+//! What a tool printed, with its terminal styling applied and everything
+//! else taken out. Ported from `app/.../Ansi.kt`, module for module: the
+//! Kotlin version builds a Compose `AnnotatedString`, which does not exist
+//! here, so a [`StyledText`] of plain text plus non-overlapping
+//! `(Range, Style)` spans stands in for it -- a future UI layer maps
+//! [`Style`] onto whatever it draws with.
+//!
+//! Bash output arrives exactly as the program wrote it, escape sequences
+//! included, and drawn verbatim those are line noise in the middle of the
+//! thing being read. Stripping them all would be the other half-answer --
+//! colour is often the whole of what a diff or a test run is saying.
+//!
+//! So the sequences that decide how text *looks* become spans, and every
+//! other one is dropped rather than shown: the rest move a cursor around a
+//! grid this is not, and "go to column 40" has no meaning in a scrolling
+//! document.
+//!
+//! A carriage return is honoured the way a terminal honours it: what was
+//! written since the last line break is thrown away and the line starts
+//! again. That is what makes a progress bar show its final state rather
+//! than every state it passed through.
+
+use std::ops::Range;
+
+/// An RGB colour, the same shape wherever this crate names one -- no alpha,
+/// because the one place that needs partial transparency (dimming) says so
+/// with a separate flag rather than baking it into the colour.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Rgb {
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+}
+
+impl Rgb {
+    pub const fn new(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b }
+    }
+}
+
+/// The sixteen colours a terminal program names, and the two it assumes.
+///
+/// Its own palette rather than the syntax one: a program that prints in red
+/// has chosen red, where a highlighter's colours are this app's reading of
+/// somebody else's code.
+#[derive(Debug, Clone)]
+pub struct AnsiPalette {
+    /// Indexes 0-7, then 8-15 bright, in the terminal's own order.
+    pub colours: [Rgb; 16],
+    /// What uncoloured text is, needed only where a style has to state a colour.
+    pub foreground: Rgb,
+    /// What the text sits on, needed for reverse video.
+    pub background: Rgb,
+}
+
+/// One span's worth of styling. `None` fields mean "unspecified", the same
+/// meaning `Color.Unspecified` and a null `FontWeight` carried in the Kotlin.
+#[derive(Debug, Clone, Copy, PartialEq, Default)]
+pub struct Style {
+    pub color: Option<Rgb>,
+    /// How much of `color`'s alpha survives, 0.0-1.0; `None` is opaque.
+    pub alpha: Option<f32>,
+    pub background: Option<Rgb>,
+    pub bold: bool,
+    pub italic: bool,
+    pub underline: bool,
+    pub strikethrough: bool,
+}
+
+/// Plain text plus the non-overlapping, ordered spans that style parts of it
+/// -- this crate's stand-in for Compose's `AnnotatedString`.
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct StyledText {
+    pub text: String,
+    pub spans: Vec<(Range<usize>, Style)>,
+}
+
+impl StyledText {
+    fn plain(text: String) -> Self {
+        Self {
+            text,
+            spans: Vec::new(),
+        }
+    }
+}
+
+const ESC: char = '\u{1B}';
+const BELL: char = '\u{7}';
+
+/// [text] with its terminal styling applied and everything else taken out;
+/// see the module doc.
+pub fn ansi_styled(text: &str, palette: &AnsiPalette) -> StyledText {
+    // The common case by a long way -- nothing to do, and nothing allocated
+    // to find that out.
+    if !text.contains(ESC) && !text.contains('\r') {
+        return StyledText::plain(text.to_string());
+    }
+
+    let chars: Vec<char> = text.chars().collect();
+    let mut runs: Vec<(String, Option<Style>)> = Vec::new();
+    let mut sgr = Sgr::PLAIN;
+    let mut at = 0usize;
+    let mut plain = String::new();
+
+    let flush = |plain: &mut String, sgr: Sgr, runs: &mut Vec<(String, Option<Style>)>| {
+        if !plain.is_empty() {
+            runs.push((std::mem::take(plain), sgr.span(palette)));
+        }
+    };
+
+    while at < chars.len() {
+        let c = chars[at];
+        if c == ESC {
+            flush(&mut plain, sgr, &mut runs);
+            at = skip_escape(&chars, at, |params, final_byte| {
+                if final_byte == 'm' {
+                    sgr = sgr.apply(params, palette);
+                }
+            });
+        } else if c == '\r' && chars.get(at + 1) != Some(&'\n') {
+            // A bare carriage return rewrites the line. One before a newline
+            // is the other half of a Windows line ending: it rewrites
+            // nothing, and it is dropped rather than kept, since that pair
+            // is one line break.
+            flush(&mut plain, sgr, &mut runs);
+            drop_line(&mut runs);
+            at += 1;
+        } else if c == '\r' {
+            at += 1;
+        } else if c >= ' ' || c == '\n' || c == '\t' {
+            // Everything printable, plus the two control characters that are
+            // layout rather than terminal commands. A stray bell or
+            // backspace goes for the same reason a cursor move does.
+            plain.push(c);
+            at += 1;
+        } else {
+            at += 1;
+        }
+    }
+    flush(&mut plain, sgr, &mut runs);
+
+    let mut out = String::new();
+    let mut spans = Vec::new();
+    for (run_text, style) in runs {
+        let start = out.len();
+        out.push_str(&run_text);
+        if let Some(style) = style {
+            spans.push((start..out.len(), style));
+        }
+    }
+    StyledText { text: out, spans }
+}
+
+/// Throws away everything written since the last line break, as a carriage
+/// return does.
+fn drop_line(runs: &mut Vec<(String, Option<Style>)>) {
+    while let Some((text, style)) = runs.pop() {
+        if let Some(break_at) = text.rfind('\n') {
+            runs.push((text[..=break_at].to_string(), style));
+            return;
+        }
+    }
+}
+
+/// The bytes that end a CSI sequence.
+fn is_csi_final(c: char) -> bool {
+    ('@'..='~').contains(&c)
+}
+
+/// Steps over the escape sequence starting at `at`, reporting a CSI's
+/// parameters and final byte. One reader for every kind, because the point
+/// is to *leave* them all behind: a sequence this did not recognise would
+/// otherwise have its body printed as ordinary text. Three shapes -- the CSI
+/// (`ESC [ ... letter`), the string escapes which run to a terminator, and
+/// the two-character ones.
+fn skip_escape(chars: &[char], at: usize, mut on_csi: impl FnMut(&str, char)) -> usize {
+    let Some(&next) = chars.get(at + 1) else {
+        return at + 1;
+    };
+    match next {
+        '[' => {
+            let mut end = at + 2;
+            while end < chars.len() && !is_csi_final(chars[end]) {
+                end += 1;
+            }
+            if end >= chars.len() {
+                // Cut off mid-sequence, which is what a stream that has not
+                // finished arriving looks like: drop the fragment rather
+                // than printing it, and the whole sequence arrives with the
+                // next delta.
+                chars.len()
+            } else {
+                let params: String = chars[at + 2..end].iter().collect();
+                on_csi(&params, chars[end]);
+                end + 1
+            }
+        }
+        ']' | 'P' | 'X' | '^' | '_' => {
+            // Runs to a string terminator: `ESC \`, or the bell that xterm
+            // allows after an OSC.
+            let mut end = at + 2;
+            while end < chars.len() {
+                if chars[end] == BELL {
+                    return end + 1;
+                }
+                if chars[end] == ESC && chars.get(end + 1) == Some(&'\\') {
+                    return end + 2;
+                }
+                end += 1;
+            }
+            chars.len()
+        }
+        _ => at + 2,
+    }
+}
+
+/// Everything an SGR sequence can turn on, as the terminal tracks it.
+#[derive(Debug, Clone, Copy, PartialEq)]
+struct Sgr {
+    fg: Option<Rgb>,
+    bg: Option<Rgb>,
+    bold: bool,
+    dim: bool,
+    italic: bool,
+    underline: bool,
+    strike: bool,
+    reverse: bool,
+}
+
+/// How much of its colour dim text keeps: enough to read, little enough to recede.
+const DIM_ALPHA: f32 = 0.65;
+
+impl Sgr {
+    const PLAIN: Sgr = Sgr {
+        fg: None,
+        bg: None,
+        bold: false,
+        dim: false,
+        italic: false,
+        underline: false,
+        strike: false,
+        reverse: false,
+    };
+
+    /// `None` while nothing is set, so unstyled output costs no spans at all.
+    fn span(&self, palette: &AnsiPalette) -> Option<Style> {
+        if *self == Sgr::PLAIN {
+            return None;
+        }
+        let front = if self.reverse {
+            Some(self.bg.unwrap_or(palette.background))
+        } else {
+            self.fg
+        };
+        let back = if self.reverse {
+            Some(self.fg.unwrap_or(palette.foreground))
+        } else {
+            self.bg
+        };
+        // Dim has to have a colour to dim, so where none was named it dims
+        // the ordinary one.
+        let stated = front.or(if self.dim {
+            Some(palette.foreground)
+        } else {
+            None
+        });
+        Some(Style {
+            color: stated,
+            alpha: if self.dim { Some(DIM_ALPHA) } else { None },
+            background: back,
+            bold: self.bold,
+            italic: self.italic,
+            underline: self.underline,
+            strikethrough: self.strike,
+        })
+    }
+
+    /// This state with `params` applied -- one `ESC[...m`, which carries any
+    /// number of them.
+    ///
+    /// A code this does not model is ignored rather than reset from: the
+    /// program meant something by it, and starting again would also drop
+    /// the codes beside it that are understood.
+    fn apply(&self, params: &str, palette: &AnsiPalette) -> Sgr {
+        // `ESC[m` means `ESC[0m`, and an empty parameter inside a list is a
+        // zero too.
+        let codes: Vec<i64> = params
+            .split(';')
+            .map(|p| p.trim().parse::<i64>().unwrap_or(0))
+            .collect();
+        let mut state = *self;
+        let mut at = 0usize;
+        while at < codes.len() {
+            let code = codes[at];
+            state = match code {
+                0 => Sgr::PLAIN,
+                1 => Sgr {
+                    bold: true,
+                    ..state
+                },
+                2 => Sgr { dim: true, ..state },
+                3 => Sgr {
+                    italic: true,
+                    ..state
+                },
+                4 => Sgr {
+                    underline: true,
+                    ..state
+                },
+                7 => Sgr {
+                    reverse: true,
+                    ..state
+                },
+                9 => Sgr {
+                    strike: true,
+                    ..state
+                },
+                21 | 22 => Sgr {
+                    bold: false,
+                    dim: false,
+                    ..state
+                },
+                23 => Sgr {
+                    italic: false,
+                    ..state
+                },
+                24 => Sgr {
+                    underline: false,
+                    ..state
+                },
+                27 => Sgr {
+                    reverse: false,
+                    ..state
+                },
+                29 => Sgr {
+                    strike: false,
+                    ..state
+                },
+                30..=37 => Sgr {
+                    fg: Some(palette.colours[(code - 30) as usize]),
+                    ..state
+                },
+                90..=97 => Sgr {
+                    fg: Some(palette.colours[(code - 90 + 8) as usize]),
+                    ..state
+                },
+                40..=47 => Sgr {
+                    bg: Some(palette.colours[(code - 40) as usize]),
+                    ..state
+                },
+                100..=107 => Sgr {
+                    bg: Some(palette.colours[(code - 100 + 8) as usize]),
+                    ..state
+                },
+                39 => Sgr { fg: None, ..state },
+                49 => Sgr { bg: None, ..state },
+                38 | 48 => {
+                    let (colour, last) = extended_colour(&codes, at, palette);
+                    at = last;
+                    if code == 38 {
+                        Sgr {
+                            fg: colour,
+                            ..state
+                        }
+                    } else {
+                        Sgr {
+                            bg: colour,
+                            ..state
+                        }
+                    }
+                }
+                _ => state,
+            };
+            at += 1;
+        }
+        state
+    }
+}
+
+/// The colour named by a `38`/`48` at `at`, and the index of that colour's
+/// last parameter.
+///
+/// Two forms: `5;n` for the 256-colour table and `2;r;g;b` for a literal
+/// one. The first sixteen of that table are the palette's own, so a program
+/// asking for "colour 1" through either spelling gets the same red.
+fn extended_colour(codes: &[i64], at: usize, palette: &AnsiPalette) -> (Option<Rgb>, usize) {
+    match codes.get(at + 1) {
+        Some(&5) => match codes.get(at + 2) {
+            None => (None, at + 1),
+            Some(&n) => (Some(indexed_colour(n, palette)), at + 2),
+        },
+        Some(&2) => {
+            let r = codes.get(at + 2);
+            let g = codes.get(at + 3);
+            let b = codes.get(at + 4);
+            match (r, g, b) {
+                (Some(&r), Some(&g), Some(&b)) => (
+                    Some(Rgb::new(
+                        r.clamp(0, 255) as u8,
+                        g.clamp(0, 255) as u8,
+                        b.clamp(0, 255) as u8,
+                    )),
+                    at + 4,
+                ),
+                _ => (None, at + 1),
+            }
+        }
+        _ => (None, at + 1),
+    }
+}
+
+/// The six levels of each channel in the 256-colour cube, as xterm defines them.
+const CUBE: [u8; 6] = [0, 95, 135, 175, 215, 255];
+
+/// One of the 256 colours: the palette's sixteen, then a 6x6x6 cube, then a
+/// grey ramp.
+fn indexed_colour(n: i64, palette: &AnsiPalette) -> Rgb {
+    if n < 0 {
+        palette.foreground
+    } else if n < 16 {
+        palette.colours[n as usize]
+    } else if n < 232 {
+        let i = (n - 16) as usize;
+        Rgb::new(CUBE[i / 36], CUBE[i / 6 % 6], CUBE[i % 6])
+    } else if n < 256 {
+        let grey = (8 + (n - 232) * 10) as u8;
+        Rgb::new(grey, grey, grey)
+    } else {
+        palette.foreground
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A palette matching the Kotlin test's: `colours[i] = Rgb(i, 0, 0)`,
+    /// white foreground, black background.
+    fn palette() -> AnsiPalette {
+        let mut colours = [Rgb::new(0, 0, 0); 16];
+        for (i, c) in colours.iter_mut().enumerate() {
+            *c = Rgb::new(i as u8, 0, 0);
+        }
+        AnsiPalette {
+            colours,
+            foreground: Rgb::new(255, 255, 255),
+            background: Rgb::new(0, 0, 0),
+        }
+    }
+
+    fn styled(text: &str) -> StyledText {
+        ansi_styled(text, &palette())
+    }
+
+    /// The style covering the first character of `word`, or `None` where
+    /// nothing styles it.
+    fn style_over(text: &str, word: &str) -> Option<Style> {
+        let out = styled(text);
+        let at = out
+            .text
+            .find(word)
+            .unwrap_or_else(|| panic!("no {word:?} in {}", out.text));
+        out.spans
+            .iter()
+            .find(|(range, _)| range.contains(&at))
+            .map(|(_, style)| *style)
+    }
+
+    #[test]
+    fn a_colour_becomes_a_span_and_the_sequence_itself_disappears() {
+        let text = format!("plain {ESC}[31mred{ESC}[0m plain");
+        assert_eq!(styled(&text).text, "plain red plain");
+        assert_eq!(
+            style_over(&text, "red").unwrap().color,
+            Some(Rgb::new(1, 0, 0))
+        );
+        assert!(style_over(&text, "plain").is_none());
+    }
+
+    #[test]
+    fn bright_background_and_256_colour_forms_all_reach_the_same_table() {
+        assert_eq!(
+            style_over(&format!("{ESC}[91mx"), "x").unwrap().color,
+            Some(Rgb::new(9, 0, 0))
+        );
+        assert_eq!(
+            style_over(&format!("{ESC}[44mx"), "x").unwrap().background,
+            Some(Rgb::new(4, 0, 0))
+        );
+        assert_eq!(
+            style_over(&format!("{ESC}[38;5;1mx"), "x").unwrap().color,
+            Some(Rgb::new(1, 0, 0))
+        );
+        assert_eq!(
+            style_over(&format!("{ESC}[38;5;16mx"), "x").unwrap().color,
+            Some(Rgb::new(0, 0, 0))
+        );
+        assert_eq!(
+            style_over(&format!("{ESC}[38;5;231mx"), "x").unwrap().color,
+            Some(Rgb::new(255, 255, 255))
+        );
+        assert_eq!(
+            style_over(&format!("{ESC}[38;2;10;20;30mx"), "x")
+                .unwrap()
+                .color,
+            Some(Rgb::new(10, 20, 30))
+        );
+    }
+
+    #[test]
+    fn everything_that_is_not_styling_is_dropped_rather_than_printed() {
+        // A cursor move, an erase, an OSC window title with its bell, and a
+        // bare two-character escape.
+        let text = format!("a{ESC}[2Jb{ESC}[Kc{ESC}]0;a title{BELL}d{ESC}=e");
+        assert_eq!(styled(&text).text, "abcde");
+    }
+
+    #[test]
+    fn a_carriage_return_rewrites_its_line_as_it_does_on_a_terminal() {
+        assert_eq!(styled("10%\r50%\rdone\n").text, "done\n");
+        assert_eq!(styled("kept\r\nfirst\rlast").text, "kept\nlast");
+    }
+
+    #[test]
+    fn a_sequence_cut_off_mid_stream_takes_no_text_with_it() {
+        assert_eq!(styled(&format!("text {ESC}[3")).text, "text ");
+    }
+
+    #[test]
+    fn unstyled_text_costs_no_spans_at_all() {
+        assert_eq!(styled("nothing to do here").spans.len(), 0);
+        assert_eq!(styled(&format!("a{ESC}[2Jb")).spans.len(), 0);
+    }
+}

client-core/src/api.rs

@@ -0,0 +1,543 @@
+//! The REST half of the backend's surface (see `server/src/routes.rs`'s
+//! module doc for the table); the SSE half is [`crate::event_stream`].
+//! Ported from `app/.../Api.kt`, but **not at full parity yet** -- see
+//! `CLIENT_CORE.md` for exactly which routes have a typed method here and
+//! which do not.
+//!
+//! Network I/O sits behind the [`Transport`] trait so the rest of this
+//! crate, and anything built on it, can be tested against a fake one with
+//! no server involved. [`UreqTransport`] is the only real implementation.
+
+use std::io::Read;
+
+use serde::Deserialize;
+use serde_json::Value;
+
+/// A request that did not produce what it asked for, carrying the server's
+/// own wording where it sent some.
+///
+/// `status` is the HTTP status where there was a response at all, and
+/// `None` where the server was never reached -- mirroring `ApiException` in
+/// `Api.kt`.
+#[derive(Debug, Clone)]
+pub struct ApiError {
+    pub message: String,
+    pub status: Option<u16>,
+}
+
+impl std::fmt::Display for ApiError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+impl std::error::Error for ApiError {}
+
+/// A request body to send, in whichever of the two shapes the surface
+/// takes: `Api.kt`'s `jsonBody` and `streamBody`.
+pub enum Body {
+    Json(Value),
+    Bytes {
+        content_type: String,
+        bytes: Vec<u8>,
+    },
+}
+
+/// What a transport hands back for a REST call: the status and the body
+/// read whole. A streamed body ([`Transport::stream`]) is a different
+/// method because its whole point is not reading it whole.
+pub struct RawResponse {
+    pub status: u16,
+    pub body: Vec<u8>,
+}
+
+/// The network boundary this crate's pure logic is kept out from behind.
+/// `server/src/routes.rs`'s module doc is the surface this drives.
+pub trait Transport: Send + Sync {
+    /// One request/response call -- everything but the long-lived SSE GETs.
+    fn request(
+        &self,
+        method: &str,
+        path: &str,
+        body: Option<Body>,
+    ) -> Result<RawResponse, ApiError>;
+
+    /// Opens `path` and answers a reader over the response body, for a
+    /// caller that reads it as a stream rather than all at once (the SSE
+    /// connections in [`crate::event_stream`]). Fails the same way
+    /// [`Transport::request`] does for a non-2xx response.
+    fn stream(&self, path: &str) -> Result<Box<dyn Read + Send>, ApiError>;
+}
+
+/// One session as `GET /sessions` and `GET /sessions/{id}` report it.
+/// Mirrors `Api.kt`'s `SessionSummary`; see that type's doc for what each
+/// field means and why `setup` is never shown.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionSummary {
+    pub id: String,
+    pub setup: String,
+    #[serde(default)]
+    pub keeps_own_transcript: bool,
+    pub setup_name: String,
+    pub provider: String,
+    pub title: String,
+    #[serde(default)]
+    pub model: Option<String>,
+    #[serde(default)]
+    pub permission_mode: Option<String>,
+    #[serde(default)]
+    pub imported: bool,
+    #[serde(default = "default_true")]
+    pub notify: bool,
+    #[serde(default)]
+    pub cwd: Option<String>,
+    #[serde(default)]
+    pub context_tokens: Option<u64>,
+    #[serde(default)]
+    pub max_image_edge: Option<u32>,
+    pub status: String,
+    pub last_activity: f64,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+/// A client-core equivalent of `requestFromServer` plus the typed calls
+/// built on it. Holds no state of its own beyond the transport -- the
+/// session id or setup id a call is about is a parameter, per this
+/// project's "ask for the least you need".
+pub struct ApiClient<T: Transport> {
+    transport: T,
+}
+
+impl<T: Transport> ApiClient<T> {
+    pub fn new(transport: T) -> Self {
+        Self { transport }
+    }
+
+    fn json_request<R: for<'de> Deserialize<'de>>(
+        &self,
+        method: &str,
+        path: &str,
+        body: Option<Value>,
+    ) -> Result<R, ApiError> {
+        let raw = self.transport.request(method, path, body.map(Body::Json))?;
+        serde_json::from_slice(&raw.body).map_err(|e| ApiError {
+            message: format!("Reached the server but couldn't read its response ({e})"),
+            status: Some(raw.status),
+        })
+    }
+
+    fn empty_request(&self, method: &str, path: &str, body: Option<Value>) -> Result<(), ApiError> {
+        self.transport.request(method, path, body.map(Body::Json))?;
+        Ok(())
+    }
+
+    pub fn fetch_sessions(&self) -> Result<Vec<SessionSummary>, ApiError> {
+        self.json_request("GET", "/sessions", None)
+    }
+
+    pub fn fetch_session(&self, session_id: &str) -> Result<SessionSummary, ApiError> {
+        self.json_request("GET", &format!("/sessions/{session_id}"), None)
+    }
+
+    pub fn send_message(
+        &self,
+        session_id: &str,
+        text: &str,
+        attachment_ids: &[String],
+    ) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/message"),
+            Some(serde_json::json!({ "text": text, "attachmentIds": attachment_ids })),
+        )
+    }
+
+    pub fn unqueue_message(&self, session_id: &str, message_id: &str) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/unqueue"),
+            Some(serde_json::json!({ "messageId": message_id })),
+        )
+    }
+
+    pub fn answer_question(
+        &self,
+        session_id: &str,
+        question_id: &str,
+        answers: &[String],
+    ) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/answer"),
+            Some(serde_json::json!({ "questionId": question_id, "answers": answers })),
+        )
+    }
+
+    pub fn interrupt_session(&self, session_id: &str) -> Result<(), ApiError> {
+        self.empty_request("POST", &format!("/sessions/{session_id}/interrupt"), None)
+    }
+
+    pub fn stop_session(&self, session_id: &str) -> Result<(), ApiError> {
+        self.empty_request("POST", &format!("/sessions/{session_id}/stop"), None)
+    }
+
+    pub fn start_session(&self, session_id: &str) -> Result<(), ApiError> {
+        self.empty_request("POST", &format!("/sessions/{session_id}/start"), None)
+    }
+
+    pub fn rename_session(&self, session_id: &str, title: &str) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/title"),
+            Some(serde_json::json!({ "title": title })),
+        )
+    }
+
+    pub fn set_session_cwd(&self, session_id: &str, cwd: &str) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/cwd"),
+            Some(serde_json::json!({ "cwd": cwd })),
+        )
+    }
+
+    pub fn set_session_model(&self, session_id: &str, model: &str) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/model"),
+            Some(serde_json::json!({ "model": model })),
+        )
+    }
+
+    pub fn set_session_permission_mode(
+        &self,
+        session_id: &str,
+        mode: &str,
+    ) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/permission-mode"),
+            Some(serde_json::json!({ "permissionMode": mode })),
+        )
+    }
+
+    pub fn set_session_notify(&self, session_id: &str, notify: bool) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/notify"),
+            Some(serde_json::json!({ "notify": notify })),
+        )
+    }
+
+    pub fn run_command(&self, session_id: &str, text: &str) -> Result<(), ApiError> {
+        self.empty_request(
+            "POST",
+            &format!("/sessions/{session_id}/command"),
+            Some(serde_json::json!({ "text": text })),
+        )
+    }
+
+    pub fn compact_session(&self, session_id: &str) -> Result<(), ApiError> {
+        self.empty_request("POST", &format!("/sessions/{session_id}/compact"), None)
+    }
+
+    pub fn delete_session(&self, session_id: &str, delete_foreign: bool) -> Result<(), ApiError> {
+        let path = if delete_foreign {
+            format!("/sessions/{session_id}?deleteForeign=true")
+        } else {
+            format!("/sessions/{session_id}")
+        };
+        self.empty_request("DELETE", &path, None)
+    }
+
+    /// A page of transcript history. `before` is the newest-first cursor
+    /// (server default is "the newest page" when absent, which a caller
+    /// gets by passing `None`); the events themselves are handed back as
+    /// [`event_model::SeqEvent`] via `crate::event_stream`'s parsing, kept
+    /// out of this method's signature so a caller that only wants the raw
+    /// lines (for the transcript cache) is not forced to parse them.
+    pub fn fetch_transcript_page(
+        &self,
+        session_id: &str,
+        before: Option<u64>,
+        limit: u32,
+        coalesce: bool,
+    ) -> Result<Vec<Value>, ApiError> {
+        let mut path = format!("/sessions/{session_id}/transcript?limit={limit}");
+        if let Some(before) = before {
+            path.push_str(&format!("&before={before}"));
+        }
+        if coalesce {
+            path.push_str("&coalesce=true");
+        }
+        self.json_request("GET", &path, None)
+    }
+}
+
+/// The blocking [`Transport`] backed by `ureq`, the same crate `server/`
+/// already depends on for its own outbound HTTPS (`usage.rs`'s Anthropic
+/// poll). Verifies the server's leaf against a single pinned CA, the way
+/// `ServerConfig.kt`'s `applyPinnedTls` does, rather than the system trust
+/// store -- the server's certificate is self-signed on purpose (see
+/// `wg-app-link`).
+pub struct UreqTransport {
+    agent: ureq::Agent,
+    base_url: String,
+    token: String,
+}
+
+impl UreqTransport {
+    /// `ca_pem` is the CA certificate `wg-app-link`'s `enroll` minted,
+    /// exactly as read from `certs/ca.pem`.
+    pub fn new(
+        base_url: impl Into<String>,
+        token: impl Into<String>,
+        ca_pem: &[u8],
+    ) -> Result<Self, ApiError> {
+        let cert = ureq::tls::Certificate::from_pem(ca_pem).map_err(|e| ApiError {
+            message: format!("The pinned CA certificate could not be read: {e}"),
+            status: None,
+        })?;
+        let tls_config = ureq::tls::TlsConfig::builder()
+            .root_certs(ureq::tls::RootCerts::new_with_certs(&[cert]))
+            .build();
+        let agent: ureq::Agent = ureq::Agent::config_builder()
+            .tls_config(tls_config)
+            // Read the body ourselves on every status, the way
+            // `requestFromServer` does: the server's own error wording is
+            // in the body of a 4xx/5xx, and the default behaviour throws
+            // it away before this code can read it.
+            .http_status_as_error(false)
+            .timeout_connect(Some(std::time::Duration::from_secs(5)))
+            .build()
+            .into();
+        Ok(Self {
+            agent,
+            base_url: base_url.into(),
+            token: token.into(),
+        })
+    }
+
+    fn url(&self, path: &str) -> String {
+        format!("{}{}", self.base_url, path)
+    }
+}
+
+impl Transport for UreqTransport {
+    fn request(
+        &self,
+        method: &str,
+        path: &str,
+        body: Option<Body>,
+    ) -> Result<RawResponse, ApiError> {
+        let url = self.url(path);
+        let auth = format!("Bearer {}", self.token);
+        let mut builder = ureq::http::Request::builder()
+            .method(method)
+            .uri(&url)
+            .header("Authorization", &auth);
+        let response = match body {
+            None => builder
+                .body(())
+                .map_err(ureq::Error::from)
+                .and_then(|req| self.agent.run(req)),
+            Some(Body::Json(value)) => {
+                builder = builder.header("Content-Type", "application/json");
+                builder
+                    .body(serde_json::to_vec(&value).unwrap_or_default())
+                    .map_err(ureq::Error::from)
+                    .and_then(|req| self.agent.run(req))
+            }
+            Some(Body::Bytes {
+                content_type,
+                bytes,
+            }) => {
+                builder = builder.header("Content-Type", content_type);
+                builder
+                    .body(bytes)
+                    .map_err(ureq::Error::from)
+                    .and_then(|req| self.agent.run(req))
+            }
+        };
+        let mut response = response.map_err(|e| transport_error(&self.base_url, path, e))?;
+        let status = response.status().as_u16();
+        let mut body = Vec::new();
+        response
+            .body_mut()
+            .as_reader()
+            .read_to_end(&mut body)
+            .map_err(|e| ApiError {
+                message: format!("Reached {url} but couldn't read its response ({e})"),
+                status: Some(status),
+            })?;
+        if !(200..300).contains(&status) {
+            return Err(response_error(status, &body, path));
+        }
+        Ok(RawResponse { status, body })
+    }
+
+    fn stream(&self, path: &str) -> Result<Box<dyn Read + Send>, ApiError> {
+        let url = self.url(path);
+        let auth = format!("Bearer {}", self.token);
+        let response = self
+            .agent
+            .get(&url)
+            .header("Authorization", &auth)
+            .header("Accept", "text/event-stream")
+            // No read timeout: between events there is nothing to read for
+            // as long as the thing being followed is idle, mirroring
+            // `EventStream.kt`'s `readTimeout = 0`.
+            .config()
+            .timeout_recv_response(None)
+            .build()
+            .call();
+        let mut response = response.map_err(|e| transport_error(&self.base_url, path, e))?;
+        let status = response.status().as_u16();
+        if status != 200 {
+            let mut body = Vec::new();
+            let _ = response.body_mut().as_reader().read_to_end(&mut body);
+            return Err(response_error(status, &body, path));
+        }
+        Ok(Box::new(response.into_body().into_reader()))
+    }
+}
+
+fn transport_error(base_url: &str, path: &str, e: ureq::Error) -> ApiError {
+    ApiError {
+        message: format!(
+            "Couldn't reach the server at {base_url} ({e}) -- is ai-server running, and is this \
+             device able to reach that address (WireGuard up)? [{path}]"
+        ),
+        status: None,
+    }
+}
+
+/// The 401 wording matches `Api.kt`'s, since that message is instructions
+/// for the reader rather than a diagnostic -- see this project's UI rule
+/// about shortening a failure in one place rather than at each display site.
+fn response_error(status: u16, body: &[u8], path: &str) -> ApiError {
+    let detail = String::from_utf8_lossy(body).trim().to_string();
+    let message = if status == 401 {
+        "The server rejected this device's token. Re-enroll by scanning the server's QR (or \
+         rotate with --rotate-token and scan the new one)."
+            .to_string()
+    } else if detail.is_empty() {
+        format!("Server returned HTTP {status} for {path}")
+    } else {
+        detail
+    };
+    ApiError {
+        message,
+        status: Some(status),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Cursor;
+    use std::sync::Mutex;
+
+    /// A transport with no network at all, for the pure-logic tests this
+    /// module can run without a server.
+    #[derive(Default)]
+    struct FakeTransport {
+        responses: Mutex<Vec<(String, String, RawResponse)>>,
+    }
+
+    impl FakeTransport {
+        fn respond(&self, method: &str, path: &str, status: u16, body: &str) {
+            self.responses.lock().unwrap().push((
+                method.to_string(),
+                path.to_string(),
+                RawResponse {
+                    status,
+                    body: body.as_bytes().to_vec(),
+                },
+            ));
+        }
+    }
+
+    impl Transport for FakeTransport {
+        fn request(
+            &self,
+            method: &str,
+            path: &str,
+            _body: Option<Body>,
+        ) -> Result<RawResponse, ApiError> {
+            let mut responses = self.responses.lock().unwrap();
+            let index = responses
+                .iter()
+                .position(|(m, p, _)| m == method && p == path)
+                .ok_or_else(|| ApiError {
+                    message: format!("no fake response for {method} {path}"),
+                    status: None,
+                })?;
+            let (_, _, response) = responses.remove(index);
+            if !(200..300).contains(&response.status) {
+                return Err(response_error(response.status, &response.body, path));
+            }
+            Ok(response)
+        }
+
+        fn stream(&self, _path: &str) -> Result<Box<dyn Read + Send>, ApiError> {
+            Ok(Box::new(Cursor::new(Vec::new())))
+        }
+    }
+
+    #[test]
+    fn fetch_sessions_parses_the_list() {
+        let transport = FakeTransport::default();
+        transport.respond(
+            "GET",
+            "/sessions",
+            200,
+            r#"[{"id":"s1","setup":"m1","setupName":"desktop","provider":"claude_cli",
+               "title":"hi","status":"idle","lastActivity":1.0}]"#,
+        );
+        let client = ApiClient::new(transport);
+        let sessions = client.fetch_sessions().unwrap();
+        assert_eq!(sessions.len(), 1);
+        assert_eq!(sessions[0].id, "s1");
+        assert_eq!(sessions[0].setup_name, "desktop");
+        // Defaults for fields the server omits.
+        assert!(sessions[0].notify);
+        assert_eq!(sessions[0].model, None);
+    }
+
+    #[test]
+    fn a_401_gets_the_enrollment_message_regardless_of_the_bare_body() {
+        let transport = FakeTransport::default();
+        transport.respond("POST", "/sessions/s1/interrupt", 401, "unauthorized");
+        let client = ApiClient::new(transport);
+        let err = client.interrupt_session("s1").unwrap_err();
+        assert!(err.message.contains("Re-enroll"));
+        assert_eq!(err.status, Some(401));
+    }
+
+    #[test]
+    fn a_bare_error_status_with_no_body_falls_back_to_a_generic_message() {
+        let transport = FakeTransport::default();
+        transport.respond("POST", "/sessions/s1/stop", 500, "");
+        let client = ApiClient::new(transport);
+        let err = client.stop_session("s1").unwrap_err();
+        assert!(err.message.contains("500"));
+    }
+
+    #[test]
+    fn a_server_explanation_in_the_body_is_surfaced_verbatim() {
+        let transport = FakeTransport::default();
+        transport.respond(
+            "POST",
+            "/sessions/s1/cwd",
+            409,
+            "that path does not exist on this machine",
+        );
+        let client = ApiClient::new(transport);
+        let err = client.set_session_cwd("s1", "/nope").unwrap_err();
+        assert_eq!(err.message, "that path does not exist on this machine");
+    }
+}

client-core/src/config.rs

@@ -0,0 +1,152 @@
+//! What a Rust client needs to reach one enrolled server: host, port and
+//! bearer token. Mirrors the shape `ServerConfig.kt`/`Api.kt`'s
+//! `handleEnrollment` parses out of an `aiapp://enroll?host=H&port=P&token=T`
+//! deep link -- the exact link `wg-app-link`'s `enroll` module mints and
+//! `app/ui-sandbox.sh`'s banner prints, so any Rust client can enrol from
+//! the same text a phone would scan as a QR, with no second format
+//! invented for it (RUST.md's E4).
+//!
+//! What this type deliberately does not decide: where it is persisted, and
+//! under what file permissions. A phone seals its token in the Android
+//! Keystore; a desktop client has its own `$XDG_CONFIG_HOME/<app>/`
+//! directory and its own file-mode conventions (MACHINE.md: owner-only,
+//! never in the repo). Both are caller-specific, so they stay out of this
+//! crate per the code rules' "ask for the least you need" -- see
+//! `iris/desktop-app/src/config.rs` for the desktop instance.
+
+use serde::{Deserialize, Serialize};
+
+/// One enrolled server: reachable at `https://{host}:{port}`, authenticated
+/// with `token` as a bearer header. Does not carry the pinned CA -- that is
+/// a public certificate rather than a secret, and where to find it differs
+/// by caller (a phone pins the one its APK was built against; a desktop
+/// client is told a path).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct EnrolledServer {
+    pub host: String,
+    pub port: u16,
+    pub token: String,
+}
+
+impl EnrolledServer {
+    /// Parses `aiapp://enroll?host=H&port=P&token=T` (query order does not
+    /// matter; unrecognised keys are ignored). `token` is percent-decoded,
+    /// since `ui-sandbox.sh` encodes it precisely because a raw token can
+    /// contain `+`, which turns into a space if left to a naive splitter.
+    pub fn parse_link(link: &str) -> Result<Self, String> {
+        let query = link.split_once('?').map(|(_, q)| q).ok_or_else(|| {
+            format!(
+                "'{link}' has no query string (expected \
+                 aiapp://enroll?host=...&port=...&token=...)"
+            )
+        })?;
+
+        let mut host = None;
+        let mut port = None;
+        let mut token = None;
+        for pair in query.split('&') {
+            let Some((key, value)) = pair.split_once('=') else {
+                continue;
+            };
+            let value = percent_decode(value);
+            match key {
+                "host" => host = Some(value),
+                "port" => port = Some(value),
+                "token" => token = Some(value),
+                _ => {}
+            }
+        }
+
+        let host = host.ok_or_else(|| format!("'{link}' is missing 'host'"))?;
+        let port_str = port.ok_or_else(|| format!("'{link}' is missing 'port'"))?;
+        let port: u16 = port_str
+            .parse()
+            .map_err(|e| format!("'{link}''s port ('{port_str}') is not a number: {e}"))?;
+        let token = token.ok_or_else(|| format!("'{link}' is missing 'token'"))?;
+
+        Ok(Self { host, port, token })
+    }
+
+    /// Where a `client_core::api::UreqTransport` reaches this server.
+    pub fn base_url(&self) -> String {
+        format!("https://{}:{}", self.host, self.port)
+    }
+}
+
+fn percent_decode(s: &str) -> String {
+    let bytes = s.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len());
+    let mut i = 0;
+    while i < bytes.len() {
+        if bytes[i] == b'%' && i + 2 < bytes.len() {
+            if let Ok(byte) =
+                u8::from_str_radix(std::str::from_utf8(&bytes[i + 1..i + 3]).unwrap_or(""), 16)
+            {
+                out.push(byte);
+                i += 3;
+                continue;
+            }
+        }
+        out.push(bytes[i]);
+        i += 1;
+    }
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_host_port_and_token() {
+        let server =
+            EnrolledServer::parse_link("aiapp://enroll?host=127.0.0.1&port=8547&token=abcDEF123")
+                .unwrap();
+        assert_eq!(
+            server,
+            EnrolledServer {
+                host: "127.0.0.1".to_string(),
+                port: 8547,
+                token: "abcDEF123".to_string(),
+            }
+        );
+        assert_eq!(server.base_url(), "https://127.0.0.1:8547");
+    }
+
+    #[test]
+    fn field_order_does_not_matter() {
+        let server =
+            EnrolledServer::parse_link("aiapp://enroll?token=tok&port=443&host=example.com")
+                .unwrap();
+        assert_eq!(server.host, "example.com");
+        assert_eq!(server.port, 443);
+        assert_eq!(server.token, "tok");
+    }
+
+    #[test]
+    fn a_percent_encoded_token_is_decoded() {
+        // ui-sandbox.sh's own reason for encoding: a raw '+' would
+        // otherwise arrive as a space.
+        let server =
+            EnrolledServer::parse_link("aiapp://enroll?host=h&port=1&token=a%2Bb%2Fc").unwrap();
+        assert_eq!(server.token, "a+b/c");
+    }
+
+    #[test]
+    fn a_missing_field_is_named_in_the_error() {
+        let err = EnrolledServer::parse_link("aiapp://enroll?host=h&port=1").unwrap_err();
+        assert!(
+            err.contains("token"),
+            "error should name the missing field: {err}"
+        );
+    }
+
+    #[test]
+    fn a_non_numeric_port_is_named_in_the_error() {
+        let err = EnrolledServer::parse_link("aiapp://enroll?host=h&port=x&token=t").unwrap_err();
+        assert!(
+            err.contains("port"),
+            "error should name the offending field: {err}"
+        );
+    }
+}

client-core/src/event_stream.rs

@@ -0,0 +1,142 @@
+//! The SSE half of the API: one long-lived GET per open session screen,
+//! replaying the transcript after a cursor and then following it live.
+//! Ported from `app/.../EventStream.kt`; the framing itself is
+//! [`crate::sse`].
+
+use std::io::{BufRead, BufReader};
+
+use event_model::SeqEvent;
+
+use crate::api::{ApiError, Transport};
+use crate::sse::SseReader;
+
+/// The frame name the server uses to say a cursor was too far behind to
+/// continue from. Must match `send_backlog` in `server/src/routes.rs`.
+const RESET_EVENT: &str = "reset";
+
+/// One frame of a session's event stream, folded from the wire shape the
+/// caller needs to act on -- mirroring what `EventStream.kt`'s three
+/// callbacks were for, as a single enum instead, since Rust has no
+/// equivalent of handing three closures to one blocking call.
+pub enum StreamItem {
+    /// The connection was accepted; the measured moment the stream is live
+    /// (see `EventStream.kt`'s doc on `onOpen` for why this, not the first
+    /// event, is what clears a previous failure on screen).
+    Open,
+    /// The cursor was too far behind to continue from: everything already
+    /// displayed is stale, and the events that follow are a fresh window.
+    /// Arrives before those events, so a caller that clears on it stays in
+    /// order.
+    Reset,
+    /// One event, as both the raw line the transcript cache stores and the
+    /// parsed [`SeqEvent`] the fold works from -- they have to be the same
+    /// line, so both travel together rather than being parsed twice from
+    /// two call sites.
+    Event { raw: String, event: SeqEvent },
+}
+
+/// Follows `/sessions/{id}/events?after={after}`, calling `on_item` for
+/// each [`StreamItem`] until the connection drops or `on_item` asks to
+/// stop (by returning `false`). Reconnecting -- with the last seq seen as
+/// the new cursor -- is the caller's job, same as in the Kotlin version.
+pub fn follow_session_events(
+    transport: &dyn Transport,
+    session_id: &str,
+    after: u64,
+    mut on_item: impl FnMut(StreamItem) -> bool,
+) -> Result<(), ApiError> {
+    let path = format!("/sessions/{session_id}/events?after={after}");
+    let body = transport.stream(&path)?;
+    if !on_item(StreamItem::Open) {
+        return Ok(());
+    }
+    let mut lines = BufReader::new(body).lines();
+    let mut reader = SseReader::new();
+    while let Some(line) = lines.next().transpose().map_err(|e| ApiError {
+        message: format!("Can't reach the server -- retrying. ({e})"),
+        status: None,
+    })? {
+        let Some(frame) = reader.feed_line(&line) else {
+            continue;
+        };
+        // A named frame carries no payload and a data frame has no name.
+        if frame.name.as_deref() == Some(RESET_EVENT) {
+            if !on_item(StreamItem::Reset) {
+                return Ok(());
+            }
+        } else if !frame.data.is_empty() {
+            let event: SeqEvent = serde_json::from_str(&frame.data).map_err(|e| ApiError {
+                message: format!("The server sent an event this build couldn't parse: {e}"),
+                status: None,
+            })?;
+            if !on_item(StreamItem::Event {
+                raw: frame.data,
+                event,
+            }) {
+                return Ok(());
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::{Body, RawResponse};
+    use std::io::Cursor;
+
+    struct FixtureTransport {
+        body: &'static str,
+    }
+
+    impl Transport for FixtureTransport {
+        fn request(
+            &self,
+            _method: &str,
+            _path: &str,
+            _body: Option<Body>,
+        ) -> Result<RawResponse, ApiError> {
+            unimplemented!("this fixture only serves a stream")
+        }
+
+        fn stream(&self, _path: &str) -> Result<Box<dyn std::io::Read + Send>, ApiError> {
+            Ok(Box::new(Cursor::new(self.body.as_bytes().to_vec())))
+        }
+    }
+
+    #[test]
+    fn events_and_a_reset_frame_are_told_apart() {
+        let transport = FixtureTransport {
+            body: "event:reset\n\ndata:{\"seq\":1,\"ts\":1.0,\"type\":\"status\",\"state\":\"idle\"}\n\n",
+        };
+        let mut items = Vec::new();
+        follow_session_events(&transport, "s1", 0, |item| {
+            items.push(match item {
+                StreamItem::Open => "open".to_string(),
+                StreamItem::Reset => "reset".to_string(),
+                StreamItem::Event { event, .. } => format!("event:{}", event.seq),
+            });
+            true
+        })
+        .unwrap();
+        assert_eq!(items, vec!["open", "reset", "event:1"]);
+    }
+
+    #[test]
+    fn the_caller_can_stop_early() {
+        let transport = FixtureTransport {
+            body: "data:{\"seq\":1,\"ts\":1.0,\"type\":\"status\",\"state\":\"idle\"}\n\n\
+                   data:{\"seq\":2,\"ts\":1.0,\"type\":\"status\",\"state\":\"idle\"}\n\n",
+        };
+        let mut count = 0;
+        follow_session_events(&transport, "s1", 0, |item| {
+            if matches!(item, StreamItem::Event { .. }) {
+                count += 1;
+            }
+            count < 1
+        })
+        .unwrap();
+        assert_eq!(count, 1);
+    }
+}

client-core/src/highlight/languages.rs

@@ -0,0 +1,581 @@
+//! A language the highlighter can colour, and the data-driven [`Rules`] each
+//! one scans by. Ported from `app/.../Languages.kt`; see that file's doc for
+//! why nearly every language is a row of data read by one shared scanner,
+//! with Markdown the one exception (`super::markdown`).
+
+use std::collections::HashSet;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Language {
+    C,
+    Coffeescript,
+    Cpp,
+    Csharp,
+    Dart,
+    Fish,
+    Go,
+    Java,
+    Javascript,
+    Json,
+    Kotlin,
+    Markdown,
+    Perl,
+    Php,
+    Python,
+    Ron,
+    Ruby,
+    Rust,
+    Shell,
+    Swift,
+    Toml,
+    Typescript,
+}
+
+impl Language {
+    /// Every value, for the same exhaustiveness check the Kotlin test runs
+    /// (`Language.entries`).
+    pub const ALL: [Language; 22] = [
+        Language::C,
+        Language::Coffeescript,
+        Language::Cpp,
+        Language::Csharp,
+        Language::Dart,
+        Language::Fish,
+        Language::Go,
+        Language::Java,
+        Language::Javascript,
+        Language::Json,
+        Language::Kotlin,
+        Language::Markdown,
+        Language::Perl,
+        Language::Php,
+        Language::Python,
+        Language::Ron,
+        Language::Ruby,
+        Language::Rust,
+        Language::Shell,
+        Language::Swift,
+        Language::Toml,
+        Language::Typescript,
+    ];
+}
+
+/// What [`super::scan`] needs to know about one language -- data, not code,
+/// so that adding a language is a row here rather than a branch anywhere.
+#[derive(Debug, Clone, Default)]
+pub struct Rules {
+    /// Words drawn as keywords. Only plain words; the scanner cannot reach
+    /// anything else.
+    pub keywords: HashSet<&'static str>,
+    /// Tokens that open a comment running to the end of the line.
+    pub line_comments: Vec<&'static str>,
+    /// Whether `line_comments` count only at the start of a word. The shells
+    /// need it: `$#`, `${#x}` and `a#b` are not comments.
+    pub line_comments_at_word_start: bool,
+    pub block_comment: Option<BlockComment>,
+    /// The string forms. The longest opener that matches wins, so `"""` is
+    /// tried before `"`.
+    pub quotes: Vec<Quote>,
+    pub attributes: Attributes,
+    /// Rust and RON: an optional `b`, `r`, n hashes, `"`, closing at `"` and n hashes.
+    pub raw_strings: bool,
+    /// Rust: `'` opens a character literal only when a backslash or one
+    /// character and a `'` follow. Otherwise it is a lifetime or a label.
+    pub lifetimes: bool,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct BlockComment {
+    pub open: &'static str,
+    pub close: &'static str,
+    pub nests: bool,
+}
+
+/// One string form. `escapes` is whether a backslash escapes the closer
+/// (and itself).
+#[derive(Debug, Clone, Copy)]
+pub struct Quote {
+    pub open: &'static str,
+    pub close: &'static str,
+    pub escapes: bool,
+}
+
+/// What opens a metadata span, of the shapes that exist across these languages.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum Attributes {
+    #[default]
+    None,
+    /// `@` and a word: Kotlin and Java annotations, Python decorators.
+    AtWord,
+    /// `#[` or `#![` through the matching `]`: Rust and RON attributes.
+    HashBracket,
+    /// `#` at the start of a line, to the end of it: the C preprocessor.
+    HashLine,
+    /// `[` at the start of a line through the matching `]`: a TOML table header.
+    LineBracket,
+}
+
+const C_STYLE: BlockComment = BlockComment {
+    open: "/*",
+    close: "*/",
+    nests: false,
+};
+const NESTING: BlockComment = BlockComment {
+    open: "/*",
+    close: "*/",
+    nests: true,
+};
+
+const DOUBLE: Quote = Quote {
+    open: "\"",
+    close: "\"",
+    escapes: true,
+};
+const SINGLE: Quote = Quote {
+    open: "'",
+    close: "'",
+    escapes: true,
+};
+const TRIPLE_DOUBLE: Quote = Quote {
+    open: "\"\"\"",
+    close: "\"\"\"",
+    escapes: true,
+};
+const TRIPLE_SINGLE: Quote = Quote {
+    open: "'''",
+    close: "'''",
+    escapes: true,
+};
+
+fn words(list: &'static str) -> HashSet<&'static str> {
+    list.split_whitespace().collect()
+}
+
+/// The rules for one language. A `match` rather than a lazily-built map --
+/// there is no once-per-process cost worth paying for in a language table
+/// this small, and it sidesteps the Kotlin version's own workaround for
+/// property initialization order.
+pub fn rules_for(language: Language) -> Rules {
+    match language {
+        Language::C => Rules {
+            keywords: words(KEYWORDS_C),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![DOUBLE, SINGLE],
+            attributes: Attributes::HashLine,
+            ..Default::default()
+        },
+        Language::Cpp => Rules {
+            keywords: words(KEYWORDS_CPP),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![DOUBLE, SINGLE],
+            attributes: Attributes::HashLine,
+            ..Default::default()
+        },
+        Language::Csharp => Rules {
+            keywords: words(KEYWORDS_CSHARP),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![DOUBLE, SINGLE],
+            ..Default::default()
+        },
+        // `###` opens and closes a block comment and `#` opens a line one,
+        // which is why the scanner tries the block opener first.
+        Language::Coffeescript => Rules {
+            keywords: words(KEYWORDS_COFFEESCRIPT),
+            line_comments: vec!["#"],
+            block_comment: Some(BlockComment {
+                open: "###",
+                close: "###",
+                nests: false,
+            }),
+            quotes: vec![TRIPLE_DOUBLE, TRIPLE_SINGLE, DOUBLE, SINGLE],
+            ..Default::default()
+        },
+        Language::Dart => Rules {
+            keywords: words(KEYWORDS_DART),
+            line_comments: vec!["//"],
+            block_comment: Some(NESTING),
+            quotes: vec![TRIPLE_DOUBLE, TRIPLE_SINGLE, DOUBLE, SINGLE],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Fish => Rules {
+            keywords: words(KEYWORDS_FISH),
+            line_comments: vec!["#"],
+            line_comments_at_word_start: true,
+            quotes: vec![DOUBLE, SINGLE],
+            ..Default::default()
+        },
+        Language::Go => Rules {
+            keywords: words(KEYWORDS_GO),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![
+                DOUBLE,
+                SINGLE,
+                Quote {
+                    open: "`",
+                    close: "`",
+                    escapes: false,
+                },
+            ],
+            ..Default::default()
+        },
+        Language::Java => Rules {
+            keywords: words(KEYWORDS_JAVA),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![DOUBLE, SINGLE],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Javascript => Rules {
+            keywords: words(KEYWORDS_JAVASCRIPT),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![
+                DOUBLE,
+                SINGLE,
+                Quote {
+                    open: "`",
+                    close: "`",
+                    escapes: true,
+                },
+            ],
+            ..Default::default()
+        },
+        Language::Json => Rules {
+            keywords: words(KEYWORDS_JSON),
+            quotes: vec![DOUBLE],
+            ..Default::default()
+        },
+        Language::Kotlin => Rules {
+            keywords: words(KEYWORDS_KOTLIN),
+            line_comments: vec!["//"],
+            block_comment: Some(NESTING),
+            quotes: vec![
+                Quote {
+                    open: "\"\"\"",
+                    close: "\"\"\"",
+                    escapes: false,
+                },
+                DOUBLE,
+                SINGLE,
+            ],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Perl => Rules {
+            keywords: words(KEYWORDS_PERL),
+            line_comments: vec!["#"],
+            quotes: vec![DOUBLE, SINGLE],
+            ..Default::default()
+        },
+        Language::Php => Rules {
+            keywords: words(KEYWORDS_PHP),
+            line_comments: vec!["//", "#"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![DOUBLE, SINGLE],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Python => Rules {
+            keywords: words(KEYWORDS_PYTHON),
+            line_comments: vec!["#"],
+            quotes: vec![TRIPLE_DOUBLE, TRIPLE_SINGLE, DOUBLE, SINGLE],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Ron => Rules {
+            keywords: words(KEYWORDS_RON),
+            line_comments: vec!["//"],
+            block_comment: Some(NESTING),
+            quotes: vec![DOUBLE, SINGLE],
+            attributes: Attributes::HashBracket,
+            raw_strings: true,
+            ..Default::default()
+        },
+        Language::Ruby => Rules {
+            keywords: words(KEYWORDS_RUBY),
+            line_comments: vec!["#"],
+            quotes: vec![DOUBLE, SINGLE],
+            ..Default::default()
+        },
+        Language::Rust => Rules {
+            keywords: words(KEYWORDS_RUST),
+            line_comments: vec!["//"],
+            block_comment: Some(NESTING),
+            // No `'` here: `lifetimes` decides when one opens a character literal.
+            quotes: vec![DOUBLE],
+            attributes: Attributes::HashBracket,
+            raw_strings: true,
+            lifetimes: true,
+            ..Default::default()
+        },
+        Language::Shell => Rules {
+            keywords: words(KEYWORDS_SHELL),
+            line_comments: vec!["#"],
+            line_comments_at_word_start: true,
+            // A shell's single quotes are literal: `'a\'` is not one string.
+            quotes: vec![
+                DOUBLE,
+                Quote {
+                    open: "'",
+                    close: "'",
+                    escapes: false,
+                },
+            ],
+            ..Default::default()
+        },
+        Language::Swift => Rules {
+            keywords: words(KEYWORDS_SWIFT),
+            line_comments: vec!["//"],
+            block_comment: Some(NESTING),
+            quotes: vec![TRIPLE_DOUBLE, DOUBLE],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        Language::Toml => Rules {
+            keywords: words(KEYWORDS_TOML),
+            line_comments: vec!["#"],
+            quotes: vec![
+                TRIPLE_DOUBLE,
+                Quote {
+                    open: "'''",
+                    close: "'''",
+                    escapes: false,
+                },
+                DOUBLE,
+                Quote {
+                    open: "'",
+                    close: "'",
+                    escapes: false,
+                },
+            ],
+            attributes: Attributes::LineBracket,
+            ..Default::default()
+        },
+        Language::Typescript => Rules {
+            keywords: words(KEYWORDS_TYPESCRIPT),
+            line_comments: vec!["//"],
+            block_comment: Some(C_STYLE),
+            quotes: vec![
+                DOUBLE,
+                SINGLE,
+                Quote {
+                    open: "`",
+                    close: "`",
+                    escapes: true,
+                },
+            ],
+            attributes: Attributes::AtWord,
+            ..Default::default()
+        },
+        // Markdown has no token rules; see `super::markdown::scan_markdown`.
+        Language::Markdown => Rules::default(),
+    }
+}
+
+// The keyword sets. Every list below other than RON, TOML, fish and JSON
+// came from dev.snipme:highlights 1.1.0 (Apache-2.0), the library the
+// Kotlin scanner replaced, so that no fence which was coloured there turns
+// plain here either.
+
+const KEYWORDS_C: &str =
+    "auto break case char const continue default do double else enum extern float for goto if
+    int long register return short signed sizeof static struct switch typedef union unsigned
+    void volatile while";
+
+const KEYWORDS_CPP: &str =
+    "asm auto bool break case catch char class const const_cast continue default delete do
+    double dynamic_cast else enum explicit export extern false float for friend goto if inline
+    int long mutable namespace new operator private protected public register reinterpret_cast
+    return short signed sizeof static static_cast struct switch template this throw true try
+    typedef typeid typename union unsigned using virtual void volatile wchar_t while";
+
+const KEYWORDS_CSHARP: &str =
+    "abstract as base bool break byte case catch char checked class const continue decimal
+    default delegate do double else enum event explicit extern false finally fixed float for
+    foreach goto if implicit in int interface internal is lock long namespace new null object
+    operator out override params private protected public readonly ref return sbyte sealed short
+    sizeof stackalloc static string struct switch this throw true try typeof uint ulong unchecked
+    unsafe ushort using virtual void volatile while";
+
+const KEYWORDS_COFFEESCRIPT: &str =
+    "Infinity NaN and arguments await break by case catch class continue debugger delete defer
+    default do else export extends false finally for function if import in instanceof is isnt
+    let loop new no not null of on or package return super switch this throw true try typeof
+    unless undefined var wait when with yield";
+
+const KEYWORDS_DART: &str =
+    "abstract as assert async await base break case catch class const continue covariant
+    default deferred do dynamic else enum export extends external factory false final finally
+    for get if implements import in interface is late library mixin new null on operator part
+    required rethrow return sealed set show static super switch this throw true try var void
+    when with while yield";
+
+/// fish is not in the library at all, so its fences are drawn plain today.
+/// The list is the shell's own words, which is what a fish fence is mostly
+/// made of.
+const KEYWORDS_FISH: &str =
+    "and begin break builtin case command continue else end exec for function if in not or
+    return switch while set echo test string math read source";
+
+const KEYWORDS_GO: &str =
+    "break case chan const continue default defer else fallthrough false for func go goto if
+    import interface map package range return select struct switch true type var";
+
+const KEYWORDS_JAVA: &str =
+    "abstract assert boolean break byte case catch char class const continue default do double
+    else enum extends final finally float for goto if implements import instanceof int interface
+    long native new null package private protected public return short static strictfp super
+    switch synchronized this throw throws transient try void volatile while";
+
+const KEYWORDS_JAVASCRIPT: &str =
+    "async await boolean break case catch class const continue debugger default delete do else
+    enum export extends false finally for function if implements import in instanceof interface
+    let new null package private protected public return super switch this throw true try typeof
+    var void while with yield";
+
+const KEYWORDS_JSON: &str = "true false null";
+
+const KEYWORDS_KOTLIN: &str =
+    "actual abstract annotation as break by catch class companion const constructor continue
+    coroutine crossinline data delegate dynamic do else enum expect external false final finally
+    for fun get if import in infix inline interface internal is lazy lateinit native null object
+    open operator out override package private protected public reified return sealed set super
+    suspend tailrec this throw true try typealias typeof val var vararg when while yield";
+
+const KEYWORDS_PERL: &str =
+    "__DATA__ __END__ __FILE__ __LINE__ __PACKAGE__ and cmp continue do else elsif eq eval for
+    foreach goto gt if last le lt my ne next no not or package redo ref return sub unless until
+    use while xor";
+
+const KEYWORDS_PHP: &str =
+    "__halt_compiler abstract and array as break callable case catch class clone const continue
+    declare default die do echo else elseif empty enddeclare endfor endforeach endif endswitch
+    endwhile eval exit extends final finally fn for foreach function global goto if implements
+    include include_once instanceof insteadof interface isset list match new or print private
+    protected public require require_once return static switch throw trait try unset use var
+    while xor yield";
+
+const KEYWORDS_PYTHON: &str =
+    "False True and as assert async await break class continue def del elif else except finally
+    for from global if import in is lambda nonlocal not or pass raise return try while with
+    yield";
+
+/// RON is not in the library either; these are the words a RON file can hold.
+const KEYWORDS_RON: &str = "true false Some None inf NaN";
+
+const KEYWORDS_RUBY: &str =
+    "__ENCODING__ __END__ __FILE__ __LINE__ BEGIN END alias and begin break case class def do
+    else elsif end ensure false for if in module next nil not or redo rescue retry return self
+    super then true undef unless until when while yield";
+
+const KEYWORDS_RUST: &str =
+    "as async await break const continue crate dyn else enum extern false fn for if impl in
+    let loop match mod move mut pub ref return Self self static struct super trait true type
+    union unsafe use where while abstract become box do final macro override priv try typeof
+    unsized virtual yield";
+
+const KEYWORDS_SHELL: &str =
+    "alias bg bind break builtin caller cd command compgen complete compopt continue declare
+    dirs disown echo enable eval exec exit export fc fg getopts hash help history jobs kill let
+    local logout popd printf pushd pwd read readonly return set shift shopt source suspend
+    test";
+
+const KEYWORDS_SWIFT: &str =
+    "_ associatedtype class deinit enum extension fileprivate func import init inout internal
+    let open operator private precedencegroup protocol public rethrows static struct subscript
+    typealias var break case catch continue default defer do else fallthrough for guard if in
+    repeat return throw switch where while Any as await false is nil self Self super throws true
+    try associativity convenience didSet dynamic final get indirect infix lazy left mutating none
+    nonmutating optional override postfix precedence prefix Protocol required right set some Type
+    unowned weak willSet";
+
+/// TOML is not in the library; `inf` and `nan` are values rather than
+/// names, like the booleans.
+const KEYWORDS_TOML: &str = "true false inf nan";
+
+const KEYWORDS_TYPESCRIPT: &str =
+    "abstract as asserts await break case catch class const constructor continue debugger
+    default delete do else enum export extends false finally for from function get if implements
+    import in infer instanceof interface is keyof let module namespace new null number object
+    package private protected public readonly require global return set static string super
+    switch this throw true try type typeof undefined unique unknown var void while with yield";
+
+/// The highlighter's language for a fence's info word, or `None` for one it
+/// has no rules for. Also what `super::file_language` reads for a file's
+/// extension -- one table, so a language added for fences is a language
+/// added for files.
+pub fn fence_language(name: Option<&str>) -> Option<Language> {
+    let name = name?.trim().to_lowercase();
+    FENCE_LANGUAGES
+        .iter()
+        .find(|(alias, _)| *alias == name)
+        .map(|(_, language)| *language)
+}
+
+/// The highlighter's language for a *file*, from its name.
+///
+/// The extension is the part after the *last* dot, which is what makes
+/// `build.gradle.kts` Kotlin. A leading dot is not one: `.bashrc` has no
+/// extension, it has a name that starts with a dot. A name with no dot at
+/// all -- `Makefile` -- is likewise `None`.
+pub fn file_language(name: &str) -> Option<Language> {
+    let dot = name.rfind('.')?;
+    if dot < 1 {
+        return None;
+    }
+    fence_language(Some(&name[dot + 1..]))
+}
+
+const FENCE_LANGUAGES: &[(&str, Language)] = &[
+    ("kotlin", Language::Kotlin),
+    ("kt", Language::Kotlin),
+    ("kts", Language::Kotlin),
+    ("rust", Language::Rust),
+    ("rs", Language::Rust),
+    ("sh", Language::Shell),
+    ("bash", Language::Shell),
+    ("shell", Language::Shell),
+    ("zsh", Language::Shell),
+    ("console", Language::Shell),
+    ("python", Language::Python),
+    ("py", Language::Python),
+    ("javascript", Language::Javascript),
+    ("js", Language::Javascript),
+    ("jsx", Language::Javascript),
+    ("typescript", Language::Typescript),
+    ("ts", Language::Typescript),
+    ("tsx", Language::Typescript),
+    ("java", Language::Java),
+    ("c", Language::C),
+    ("h", Language::C),
+    ("cpp", Language::Cpp),
+    ("c++", Language::Cpp),
+    ("cc", Language::Cpp),
+    ("hpp", Language::Cpp),
+    ("csharp", Language::Csharp),
+    ("cs", Language::Csharp),
+    ("c#", Language::Csharp),
+    ("go", Language::Go),
+    ("golang", Language::Go),
+    ("swift", Language::Swift),
+    ("dart", Language::Dart),
+    ("ruby", Language::Ruby),
+    ("rb", Language::Ruby),
+    ("php", Language::Php),
+    ("perl", Language::Perl),
+    ("pl", Language::Perl),
+    ("coffeescript", Language::Coffeescript),
+    ("coffee", Language::Coffeescript),
+    ("ron", Language::Ron),
+    ("toml", Language::Toml),
+    ("fish", Language::Fish),
+    ("json", Language::Json),
+    ("markdown", Language::Markdown),
+    ("md", Language::Markdown),
+];

client-core/src/highlight/markdown.rs

@@ -0,0 +1,681 @@
+//! Markdown read into the spans that carry a colour -- a ```markdown fence
+//! in a reply, and a `.md` file in the viewer. Ported from
+//! `app/.../MarkdownSyntax.kt`; see that file's doc for why this is its own
+//! scanner rather than a row of [`super::Rules`] (what a character means
+//! depends on where it sits, not on what it is) and why an indented code
+//! block is deliberately not recognised.
+//!
+//! Structure is read a line at a time and each line's prose left to right,
+//! except the two decisions that are not: a fenced block is state carried
+//! forward, and a table is found by its delimiter row, which comes after
+//! the header it belongs to (the one place here that looks ahead).
+
+use super::{Kind, Span};
+
+/// The characters an unordered list may be bulleted with.
+const BULLETS: &str = "-*+";
+/// The characters a thematic break, or a setext heading's underline, can be
+/// drawn with.
+const RULE_MARKERS: &str = "-*_=";
+/// The characters that can open emphasis, strong emphasis or a strikethrough.
+const EMPHASIS: &str = "*_~";
+/// Characters that end a bare URL wherever they appear, and ones only
+/// trimmed off the end.
+const URL_STOPS: &str = "<>\"'`|";
+const URL_TRAILING: &str = ".,:;!?";
+
+pub fn scan_markdown(code: &str) -> Vec<Span> {
+    MarkdownScanner::new(code).run()
+}
+
+struct MarkdownScanner {
+    code: Vec<char>,
+    spans: Vec<Span>,
+}
+
+impl MarkdownScanner {
+    fn new(code: &str) -> Self {
+        Self {
+            code: code.chars().collect(),
+            spans: Vec::new(),
+        }
+    }
+
+    fn run(mut self) -> Vec<Span> {
+        let mut at = 0usize;
+        // The delimiter run that opened the fenced block we are inside, or
+        // None between them.
+        let mut fence: Option<Vec<char>> = None;
+        // Whether the row above was part of a table, which is what makes
+        // this one a body row.
+        let mut table = false;
+        loop {
+            let end = self.line_end(at);
+            if let Some(open) = fence.clone() {
+                // The content and the closing line alike: a fence is one
+                // block of code, and its own delimiters belong to it the
+                // way a string's quotes belong to the string.
+                self.emit(at, end, Kind::String);
+                if self.closes_fence(at, end, &open) {
+                    fence = None;
+                }
+            } else {
+                let opened = self.opens_fence(at, end);
+                if opened.is_some() {
+                    table = false;
+                    fence = opened;
+                } else {
+                    table = self.row(at, end, table);
+                }
+            }
+            if end == self.code.len() {
+                break;
+            }
+            at = end + 1;
+        }
+        self.spans
+    }
+
+    /// The end of the line beginning at `at`: the newline, or the end of the text.
+    fn line_end(&self, at: usize) -> usize {
+        self.code[at..]
+            .iter()
+            .position(|&c| c == '\n')
+            .map(|p| at + p)
+            .unwrap_or(self.code.len())
+    }
+
+    /// One line that is not inside a fence, and whether the table it may be
+    /// part of is still open.
+    fn row(&mut self, start: usize, end: usize, table: bool) -> bool {
+        if self.table_delimiter(start, end) {
+            let indented = self.indented(start, end);
+            self.emit(indented, end, Kind::Mark);
+            return true;
+        }
+        let header = end < self.code.len() && self.table_delimiter(end + 1, self.line_end(end + 1));
+        if (table || header) && self.has_pipe(start, end) {
+            self.table_row(start, end);
+            return true;
+        }
+        self.structure(start, end);
+        false
+    }
+
+    /// A line of nothing but pipes, dashes, alignment colons and space, with
+    /// one of each needed.
+    fn table_delimiter(&self, start: usize, end: usize) -> bool {
+        let mut dashes = false;
+        let mut pipes = false;
+        for at in self.indented(start, end)..end {
+            match self.code[at] {
+                '-' => dashes = true,
+                '|' => pipes = true,
+                ':' | ' ' | '\t' => {}
+                _ => return false,
+            }
+        }
+        dashes && pipes
+    }
+
+    fn has_pipe(&self, start: usize, end: usize) -> bool {
+        let mut at = start;
+        while at < end {
+            if self.code[at] == '\\' {
+                at += 2;
+            } else if self.code[at] == '|' {
+                return true;
+            } else {
+                at += 1;
+            }
+        }
+        false
+    }
+
+    /// A table row: the pipes are the structure, and what is between them is prose.
+    fn table_row(&mut self, start: usize, end: usize) {
+        let mut at = self.indented(start, end);
+        let mut cell = at;
+        while at < end {
+            match self.code[at] {
+                '\\' => at += 2,
+                '|' => {
+                    self.inline(cell, at);
+                    self.emit(at, at + 1, Kind::Mark);
+                    at += 1;
+                    cell = at;
+                }
+                _ => at += 1,
+            }
+        }
+        self.inline(cell, end);
+    }
+
+    /// Spans, coalesced with the one before when they touch and agree.
+    fn emit(&mut self, start: usize, end: usize, kind: Kind) {
+        if end <= start {
+            return;
+        }
+        if let Some(last) = self.spans.last_mut()
+            && last.kind == kind
+            && last.end == start
+        {
+            last.end = end;
+            return;
+        }
+        self.spans.push(Span { start, end, kind });
+    }
+
+    /// The first character of the line at or after `start` that is not indentation.
+    fn indented(&self, start: usize, end: usize) -> usize {
+        let mut at = start;
+        while at < end && (self.code[at] == ' ' || self.code[at] == '\t') {
+            at += 1;
+        }
+        at
+    }
+
+    /// The run of backticks or tildes that could open or close a fence on
+    /// this line, or `None`.
+    fn fence_run(&self, start: usize, end: usize) -> Option<(usize, usize)> {
+        let at = self.indented(start, end);
+        if at == end {
+            return None;
+        }
+        let marker = self.code[at];
+        if marker != '`' && marker != '~' {
+            return None;
+        }
+        let mut run = at;
+        while run < end && self.code[run] == marker {
+            run += 1;
+        }
+        if run - at >= 3 { Some((at, run)) } else { None }
+    }
+
+    /// Draws an opening fence line and answers its delimiter, or `None` if
+    /// this is not one.
+    fn opens_fence(&mut self, start: usize, end: usize) -> Option<Vec<char>> {
+        let (run_start, run_end) = self.fence_run(start, end)?;
+        self.emit(run_start, run_end, Kind::String);
+        // The info word is what the fence is a fence *of*, which is
+        // metadata about the block rather than part of it.
+        let indented = self.indented(run_end, end);
+        self.emit(indented, end, Kind::Metadata);
+        Some(self.code[run_start..run_end].to_vec())
+    }
+
+    /// Whether this line closes a fence opened by `open`: the same
+    /// character, at least as many of them, and nothing else on the line.
+    fn closes_fence(&self, start: usize, end: usize, open: &[char]) -> bool {
+        let Some((run_start, run_end)) = self.fence_run(start, end) else {
+            return false;
+        };
+        if self.code[run_start] != open[0] || run_end - run_start < open.len() {
+            return false;
+        }
+        self.indented(run_end, end) == end
+    }
+
+    /// One ordinary line: what its opening characters make it, and then its prose.
+    fn structure(&mut self, start: usize, end: usize) {
+        let mut at = start;
+        // Quote markers come before everything else and can be several
+        // deep, and what follows one is an ordinary line again -- a heading
+        // inside a quote is still a heading.
+        while at < end && self.code[at] == '>' {
+            at += 1;
+            self.emit(at - 1, at, Kind::Mark);
+            at = self.indented(at, end);
+        }
+        if at == end {
+            return;
+        }
+        if self.heading(at, end) || self.thematic_break(at, end) {
+            return;
+        }
+        let text_start = self.bullet(at, end);
+        self.inline(text_start, end);
+    }
+
+    /// `#` to `######` and a space. Without the space it is a word
+    /// beginning with a hash.
+    fn heading(&mut self, start: usize, end: usize) -> bool {
+        let mut at = start;
+        while at < end && self.code[at] == '#' {
+            at += 1;
+        }
+        let depth = at - start;
+        if !(1..=6).contains(&depth) {
+            return false;
+        }
+        if at < end && self.code[at] != ' ' && self.code[at] != '\t' {
+            return false;
+        }
+        self.emit(start, end, Kind::Keyword);
+        true
+    }
+
+    /// A line made of one repeated rule character and nothing else.
+    fn thematic_break(&mut self, start: usize, end: usize) -> bool {
+        let marker = self.code[start];
+        if !RULE_MARKERS.contains(marker) {
+            return false;
+        }
+        let mut seen = 0usize;
+        for at in start..end {
+            let c = self.code[at];
+            if c == marker {
+                seen += 1;
+            } else if !c.is_whitespace() {
+                return false;
+            }
+        }
+        if seen < if marker == '=' { 1 } else { 3 } {
+            return false;
+        }
+        self.emit(start, end, Kind::Mark);
+        true
+    }
+
+    /// Draws a list marker if the line opens with one, and answers where
+    /// the item's text starts.
+    fn bullet(&mut self, start: usize, end: usize) -> usize {
+        let marker = self.code[start];
+        if BULLETS.contains(marker) && self.space_or_end(start + 1, end) {
+            self.emit(start, start + 1, Kind::Mark);
+            return self.indented(start + 1, end);
+        }
+        let mut digits = start;
+        while digits < end && self.code[digits].is_ascii_digit() {
+            digits += 1;
+        }
+        let delimiter = self.code.get(digits).copied();
+        if digits > start
+            && (delimiter == Some('.') || delimiter == Some(')'))
+            && self.space_or_end(digits + 1, end)
+        {
+            self.emit(start, digits + 1, Kind::Mark);
+            return self.indented(digits + 1, end);
+        }
+        start
+    }
+
+    fn space_or_end(&self, at: usize, end: usize) -> bool {
+        at >= end || self.code[at] == ' ' || self.code[at] == '\t'
+    }
+
+    /// The inline forms, left to right. Every branch answers a position
+    /// strictly after `start` of its call, so this terminates.
+    fn inline(&mut self, start: usize, end: usize) {
+        let mut at = start;
+        while at < end {
+            let c = self.code[at];
+            at = if c == '\\' {
+                // A backslash takes the character after it out of the
+                // running entirely, which is how `\*` stays an asterisk
+                // rather than opening emphasis.
+                at + 2
+            } else if c == '`' {
+                self.code_span(at, end)
+            } else if c == '[' {
+                self.link(at, at, end)
+            } else if c == '!' && self.code.get(at + 1) == Some(&'[') {
+                self.link(at, at + 1, end)
+            } else if c == '<' {
+                self.autolink(at, end)
+            } else if EMPHASIS.contains(c) {
+                self.emphasis(at, end)
+            } else {
+                self.url(at, end).unwrap_or(at + 1)
+            };
+        }
+    }
+
+    /// `` `code` ``, closed by a run of exactly as many backticks as opened it.
+    fn code_span(&mut self, start: usize, end: usize) -> usize {
+        let mut open = start;
+        while open < end && self.code[open] == '`' {
+            open += 1;
+        }
+        let ticks = open - start;
+        let mut at = open;
+        while at < end {
+            if self.code[at] != '`' {
+                at += 1;
+                continue;
+            }
+            let mut close = at;
+            while close < end && self.code[close] == '`' {
+                close += 1;
+            }
+            if close - at == ticks {
+                self.emit(start, close, Kind::String);
+                return close;
+            }
+            at = close;
+        }
+        // Nothing closes it on this line, so those were ordinary backticks.
+        open
+    }
+
+    /// `[text](destination)`, and the same with a leading `!` for an image.
+    fn link(&mut self, start: usize, bracket: usize, end: usize) -> usize {
+        let mut depth = 0i32;
+        let mut close = bracket;
+        while close < end {
+            match self.code[close] {
+                '\\' => close += 1,
+                '[' => depth += 1,
+                ']' => {
+                    depth -= 1;
+                    if depth == 0 {
+                        break;
+                    }
+                }
+                _ => {}
+            }
+            close += 1;
+        }
+        if close >= end {
+            return start + 1;
+        }
+        let destination = close + 1;
+        if self.code.get(destination) != Some(&'(') {
+            return start + 1;
+        }
+        let Some(paren_rel) = self.code[destination..].iter().position(|&c| c == ')') else {
+            return start + 1;
+        };
+        let paren = destination + paren_rel;
+        if paren >= end {
+            return start + 1;
+        }
+        self.emit(start, bracket + 1, Kind::Mark);
+        self.inline(bracket + 1, close);
+        self.emit(close, destination, Kind::Mark);
+        self.emit(destination, paren + 1, Kind::Metadata);
+        paren + 1
+    }
+
+    /// `<https://example.com>` and `<name@example.com>`, drawn as the
+    /// destination they are.
+    fn autolink(&mut self, start: usize, end: usize) -> usize {
+        let mut at = start + 1;
+        let mut addressed = false;
+        while at < end {
+            let c = self.code[at];
+            if c.is_whitespace() || c == '<' {
+                return start + 1;
+            }
+            if c == '>' {
+                if !addressed {
+                    return start + 1;
+                }
+                self.emit(start, at + 1, Kind::Metadata);
+                return at + 1;
+            }
+            if c == ':' || c == '@' {
+                addressed = true;
+            }
+            at += 1;
+        }
+        start + 1
+    }
+
+    /// A bare `scheme://...` written in prose, or `None` if one does not
+    /// start here.
+    fn url(&mut self, start: usize, end: usize) -> Option<usize> {
+        if start > 0 && is_word(self.code[start - 1]) {
+            return None;
+        }
+        let mut scheme = start;
+        while scheme < end && self.code[scheme].is_alphabetic() {
+            scheme += 1;
+        }
+        if scheme == start || !starts_with(&self.code, scheme, "://") {
+            return None;
+        }
+        let body = scheme + 3;
+        let mut at = body;
+        let mut openers = 0i32;
+        let mut closers = 0i32;
+        while at < end && !self.code[at].is_whitespace() && !URL_STOPS.contains(self.code[at]) {
+            if self.code[at] == '(' {
+                openers += 1;
+            } else if self.code[at] == ')' {
+                closers += 1;
+            }
+            at += 1;
+        }
+        while at > body {
+            let last = self.code[at - 1];
+            if URL_TRAILING.contains(last) {
+                at -= 1;
+            } else if last == ')' && closers > openers {
+                closers -= 1;
+                at -= 1;
+            } else {
+                break;
+            }
+        }
+        if at == body {
+            return None;
+        }
+        self.emit(start, at, Kind::Metadata);
+        Some(at)
+    }
+
+    /// `*emph*`, `**strong**`, `_emph_` and `~~struck~~`, drawn markers and
+    /// all.
+    fn emphasis(&mut self, start: usize, end: usize) -> usize {
+        let marker = self.code[start];
+        let mut open = start;
+        while open < end && self.code[open] == marker {
+            open += 1;
+        }
+        let length = open - start;
+        if marker == '~' && length != 2 {
+            return open;
+        }
+        if length > 3 {
+            return open;
+        }
+        if open == end || self.code[open].is_whitespace() {
+            return open;
+        }
+        if marker == '_' && start > 0 && is_word(self.code[start - 1]) {
+            return open;
+        }
+        let mut at = open;
+        while at < end {
+            if self.code[at] == '\\' {
+                at += 2;
+                continue;
+            }
+            if self.code[at] != marker {
+                at += 1;
+                continue;
+            }
+            let mut close = at;
+            while close < end && self.code[close] == marker {
+                close += 1;
+            }
+            let finish = at + length;
+            if close - at >= length
+                && !self.code[at - 1].is_whitespace()
+                && !(marker == '_' && finish < end && is_word(self.code[finish]))
+            {
+                self.emit(start, finish, Kind::Literal);
+                return finish;
+            }
+            at = close;
+        }
+        open
+    }
+}
+
+fn is_word(c: char) -> bool {
+    c.is_alphanumeric() || c == '_'
+}
+
+fn starts_with(code: &[char], at: usize, token: &str) -> bool {
+    let token: Vec<char> = token.chars().collect();
+    if at + token.len() > code.len() {
+        return false;
+    }
+    code[at..at + token.len()] == token[..]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::{Kind, Language, span_text, spans_of};
+
+    fn spans(code: &str, kind: Kind) -> Vec<String> {
+        let chars: Vec<char> = code.chars().collect();
+        spans_of(code, Language::Markdown)
+            .into_iter()
+            .filter(|s| s.kind == kind)
+            .map(|s| span_text(&chars, &s))
+            .collect()
+    }
+
+    fn assert_spans(code: &str, kind: Kind, expected: &[&str]) {
+        assert_eq!(spans(code, kind), expected.to_vec(), "{kind:?} in: {code}");
+    }
+
+    #[test]
+    fn a_heading_is_coloured_whole_and_a_hash_inside_a_word_is_not_one() {
+        let code = "## Layout\nissue #12 is fixed\n#hashtag";
+        assert_spans(code, Kind::Keyword, &["## Layout"]);
+    }
+
+    #[test]
+    fn seven_hashes_are_not_a_heading() {
+        assert_spans("####### deep", Kind::Keyword, &[]);
+    }
+
+    #[test]
+    fn a_fence_carries_its_language_as_metadata_and_its_body_as_one_string() {
+        let code = "text\n```kotlin\nval x = 1\n```\nmore";
+        assert_spans(code, Kind::Metadata, &["kotlin"]);
+        assert_spans(code, Kind::String, &["```", "val x = 1", "```"]);
+    }
+
+    #[test]
+    fn a_longer_fence_is_not_closed_by_a_shorter_one_and_a_heading_inside_it_is_not_a_heading() {
+        let code = "````\n```\n# not a heading\n````\nafter";
+        assert_spans(code, Kind::Keyword, &[]);
+        assert_spans(
+            code,
+            Kind::String,
+            &["````", "```", "# not a heading", "````"],
+        );
+    }
+
+    #[test]
+    fn an_unclosed_fence_runs_to_the_end_rather_than_panicking() {
+        assert_spans("```\nstill going", Kind::String, &["```", "still going"]);
+    }
+
+    #[test]
+    fn list_markers_and_quote_markers_colour_without_their_text() {
+        let code = "- one\n2. two\n> quoted";
+        assert_spans(code, Kind::Mark, &["-", "2.", ">"]);
+    }
+
+    #[test]
+    fn a_rule_and_a_setext_underline_are_the_same_mark() {
+        assert_spans("Title\n=====\n\n---", Kind::Mark, &["=====", "---"]);
+    }
+
+    #[test]
+    fn emphasis_needs_something_on_both_sides_of_it() {
+        assert_spans(
+            "**bold** and *thin*",
+            Kind::Literal,
+            &["**bold**", "*thin*"],
+        );
+        assert_spans("a * b * c and *p = *q", Kind::Literal, &[]);
+    }
+
+    #[test]
+    fn an_underscore_inside_a_word_emphasises_nothing() {
+        assert_spans("snake_case_name and _real_", Kind::Literal, &["_real_"]);
+    }
+
+    #[test]
+    fn a_code_span_holds_a_backtick_when_opened_with_two() {
+        assert_spans("``a ` b`` and `c`", Kind::String, &["``a ` b``", "`c`"]);
+    }
+
+    #[test]
+    fn an_unclosed_code_span_is_ordinary_text() {
+        assert_spans("a ` b", Kind::String, &[]);
+    }
+
+    #[test]
+    fn a_link_marks_its_brackets_and_colours_its_destination() {
+        let code = "see [the plan](PLAN.md) now";
+        assert_spans(code, Kind::Mark, &["[", "]"]);
+        assert_spans(code, Kind::Metadata, &["(PLAN.md)"]);
+    }
+
+    #[test]
+    fn a_table_is_found_by_its_delimiter_row_and_pipes_elsewhere_are_plain() {
+        let code = "| a | b |\n|---|---|\n| 1 | 2 |\n\nrun a | b in a paragraph";
+        assert_spans(
+            code,
+            Kind::Mark,
+            &["|", "|", "|", "|---|---|", "|", "|", "|"],
+        );
+    }
+
+    #[test]
+    fn a_table_without_outer_pipes_still_colours_and_the_table_ends_with_the_rows() {
+        let code = "a | b\n--- | ---\nnot a row";
+        assert_spans(code, Kind::Mark, &["|", "--- | ---"]);
+    }
+
+    #[test]
+    fn an_autolink_colours_and_an_html_tag_does_not() {
+        let code = "<https://example.com> and <a@b.com> and <div> and <img src=\"http://x\">";
+        assert_spans(
+            code,
+            Kind::Metadata,
+            &["<https://example.com>", "<a@b.com>", "http://x"],
+        );
+    }
+
+    #[test]
+    fn a_bare_url_gives_back_the_sentences_punctuation() {
+        assert_spans(
+            "see https://example.com/a., and ssh://host/x)",
+            Kind::Metadata,
+            &["https://example.com/a", "ssh://host/x"],
+        );
+    }
+
+    #[test]
+    fn a_bracket_a_url_opened_itself_stays_in_it() {
+        assert_spans(
+            "https://en.wikipedia.org/wiki/A_(b) here",
+            Kind::Metadata,
+            &["https://en.wikipedia.org/wiki/A_(b)"],
+        );
+    }
+
+    #[test]
+    fn a_url_inside_a_link_destination_is_not_coloured_twice() {
+        assert_spans(
+            "[x](https://example.com)",
+            Kind::Metadata,
+            &["(https://example.com)"],
+        );
+    }
+
+    #[test]
+    fn a_bracket_with_no_destination_after_it_is_left_plain() {
+        assert_spans("an [aside] here", Kind::Mark, &[]);
+    }
+}

client-core/src/highlight/mod.rs

@@ -0,0 +1,702 @@
+//! `code` read once, left to right, into the spans that carry a colour.
+//! Ported from `app/.../Highlighter.kt`.
+//!
+//! One pass with a small state -- in a comment, in a string, or in ordinary
+//! code -- rather than a locator per token kind over the whole text, which
+//! is what the library this replaced did and is why it found comments
+//! before it knew the language: a `#` inside a shell string, a `//` inside
+//! a URL and a block-comment opener inside a shell glob each commented out
+//! the rest of a line that was nothing of the sort.
+//!
+//! Every span is produced by advancing an index forward, so the result is
+//! ordered, non-overlapping and inside the code by construction. Nothing
+//! here panics: an unterminated string or comment runs to the end of the
+//! code, which is also what it looks like while a fence is still being
+//! written.
+//!
+//! **Indices are char offsets, not byte offsets** -- the scanner works over
+//! `Vec<char>`, mirroring the Kotlin original's `Char`-indexed strings, so
+//! [`span_text`] is how a caller (and every test here) turns a [`Span`]
+//! back into the text it covers.
+
+pub mod languages;
+pub mod markdown;
+
+pub use languages::{
+    Attributes, BlockComment, Language, Quote, Rules, fence_language, file_language, rules_for,
+};
+
+/// What a span of code is, in the terms a palette has a colour for.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Kind {
+    Keyword,
+    String,
+    Literal,
+    Comment,
+    Metadata,
+    Punctuation,
+    Mark,
+}
+
+/// A run of [`Kind`] in the code, as a half-open range of **char** indices.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Span {
+    pub start: usize,
+    pub end: usize,
+    pub kind: Kind,
+}
+
+/// The text a [`Span`] covers, for a caller working in char indices (every
+/// test in this module, and any UI that also holds `code` as `Vec<char>`).
+pub fn span_text(code: &[char], span: &Span) -> String {
+    code[span.start..span.end].iter().collect()
+}
+
+/// The spans `language` colours in `code` -- the one way to ask, whatever
+/// the language turns out to be made of. `None` draws plain.
+pub fn spans_of(code: &str, language: Language) -> Vec<Span> {
+    if language == Language::Markdown {
+        markdown::scan_markdown(code)
+    } else {
+        scan(code, &rules_for(language))
+    }
+}
+
+/// `code` read into the spans [`Rules`] describes. Also reachable directly
+/// for a caller that already has a [`Rules`] (there is currently only one:
+/// [`spans_of`]), kept public because the Kotlin original exposed it the
+/// same way.
+pub fn scan(code: &str, rules: &Rules) -> Vec<Span> {
+    Scanner::new(code, rules).run()
+}
+
+/// Characters coloured as punctuation, and as marks. Both sets are the ones
+/// the library this replaced used.
+const PUNCTUATION: &str = ",.:;";
+const MARKS: &str = "()={}<>-+[]|&";
+
+struct Scanner<'a> {
+    code: Vec<char>,
+    rules: &'a Rules,
+    spans: Vec<Span>,
+    at: usize,
+}
+
+impl<'a> Scanner<'a> {
+    fn new(code: &str, rules: &'a Rules) -> Self {
+        Self {
+            code: code.chars().collect(),
+            rules,
+            spans: Vec::new(),
+            at: 0,
+        }
+    }
+
+    fn run(mut self) -> Vec<Span> {
+        while self.at < self.code.len() {
+            // Every branch that answers true has advanced `self.at`, so
+            // this terminates.
+            let consumed = self.block_comment()
+                || self.line_comment()
+                || self.raw_string()
+                || self.character_or_lifetime()
+                || self.string()
+                || self.attribute()
+                || self.number()
+                || self.word()
+                || self.single_character();
+            if !consumed {
+                self.at += 1;
+            }
+        }
+        self.spans
+    }
+
+    fn emit(&mut self, start: usize, kind: Kind) {
+        if self.at > start {
+            self.spans.push(Span {
+                start,
+                end: self.at,
+                kind,
+            });
+        }
+    }
+
+    fn starts(&self, token: &str) -> bool {
+        starts_with_at(&self.code, self.at, token)
+    }
+
+    /// Whether a line comment token here opens one; see
+    /// [`Rules::line_comments_at_word_start`].
+    fn at_word_start(&self) -> bool {
+        self.at == 0
+            || self.code[self.at - 1].is_whitespace()
+            || ";|&(".contains(self.code[self.at - 1])
+    }
+
+    /// Whether only whitespace stands between the start of this line and here.
+    fn at_line_start(&self) -> bool {
+        let mut back = self.at as isize - 1;
+        while back >= 0 && self.code[back as usize] != '\n' {
+            if !self.code[back as usize].is_whitespace() {
+                return false;
+            }
+            back -= 1;
+        }
+        true
+    }
+
+    fn advance_to_end_of_line(&mut self) {
+        while self.at < self.code.len() && self.code[self.at] != '\n' {
+            self.at += 1;
+        }
+    }
+
+    /// From an open bracket through the one that matches it, or to the end
+    /// if none does.
+    fn advance_to_matching_bracket(&mut self) {
+        let mut depth = 0i32;
+        while self.at < self.code.len() {
+            match self.code[self.at] {
+                '[' => depth += 1,
+                ']' => depth -= 1,
+                _ => {}
+            }
+            self.at += 1;
+            if depth == 0 {
+                return;
+            }
+        }
+    }
+
+    fn block_comment(&mut self) -> bool {
+        let Some(comment) = self.rules.block_comment else {
+            return false;
+        };
+        if !self.starts(comment.open) {
+            return false;
+        }
+        let start = self.at;
+        self.at += comment.open.chars().count();
+        let mut depth = 1i32;
+        while self.at < self.code.len() && depth > 0 {
+            // The closer is tried first so that a language whose two
+            // delimiters are the same string -- CoffeeScript's `###` --
+            // closes rather than nesting forever.
+            if self.starts(comment.close) {
+                depth -= 1;
+                self.at += comment.close.chars().count();
+            } else if comment.nests && self.starts(comment.open) {
+                depth += 1;
+                self.at += comment.open.chars().count();
+            } else {
+                self.at += 1;
+            }
+        }
+        self.emit(start, Kind::Comment);
+        true
+    }
+
+    fn line_comment(&mut self) -> bool {
+        if !self.rules.line_comments.iter().any(|c| self.starts(c)) {
+            return false;
+        }
+        if self.rules.line_comments_at_word_start && !self.at_word_start() {
+            return false;
+        }
+        let start = self.at;
+        self.advance_to_end_of_line();
+        self.emit(start, Kind::Comment);
+        true
+    }
+
+    /// Rust and RON: `b`? `r` `#`* `"` ... `"` `#`*, with no escapes inside.
+    fn raw_string(&mut self) -> bool {
+        if !self.rules.raw_strings {
+            return false;
+        }
+        let mut ahead = self.at;
+        if self.code.get(ahead) == Some(&'b') {
+            ahead += 1;
+        }
+        if self.code.get(ahead) != Some(&'r') {
+            return false;
+        }
+        ahead += 1;
+        let mut hashes = 0usize;
+        while self.code.get(ahead) == Some(&'#') {
+            ahead += 1;
+            hashes += 1;
+        }
+        if self.code.get(ahead) != Some(&'"') {
+            return false;
+        }
+        let start = self.at;
+        let closer: String = std::iter::once('"')
+            .chain(std::iter::repeat_n('#', hashes))
+            .collect();
+        let closer_chars: Vec<char> = closer.chars().collect();
+        let closed = find_from(&self.code, ahead + 1, &closer_chars);
+        self.at = match closed {
+            Some(index) => index + closer_chars.len(),
+            None => self.code.len(),
+        };
+        self.emit(start, Kind::String);
+        true
+    }
+
+    /// See [`Rules::lifetimes`]: an apostrophe that is not a character
+    /// literal opens nothing.
+    fn character_or_lifetime(&mut self) -> bool {
+        if !self.rules.lifetimes || self.code[self.at] != '\'' {
+            return false;
+        }
+        let Some(&next) = self.code.get(self.at + 1) else {
+            return false;
+        };
+        if next == '\\' || self.code.get(self.at + 2) == Some(&'\'') {
+            self.quoted(Quote {
+                open: "'",
+                close: "'",
+                escapes: true,
+            });
+        } else {
+            self.at += 1;
+        }
+        true
+    }
+
+    fn string(&mut self) -> bool {
+        // Longest opener wins, so Kotlin's `"""` is one delimiter rather
+        // than an empty string followed by a quote.
+        let mut quote: Option<Quote> = None;
+        for candidate in &self.rules.quotes {
+            let current_len = quote.map(|q| q.open.chars().count()).unwrap_or(0);
+            if self.starts(candidate.open) && candidate.open.chars().count() > current_len {
+                quote = Some(*candidate);
+            }
+        }
+        let Some(quote) = quote else {
+            return false;
+        };
+        self.quoted(quote);
+        true
+    }
+
+    fn quoted(&mut self, quote: Quote) {
+        let start = self.at;
+        self.at += quote.open.chars().count();
+        while self.at < self.code.len() {
+            if quote.escapes && self.code[self.at] == '\\' && self.at + 1 < self.code.len() {
+                self.at += 2;
+                continue;
+            }
+            if self.starts(quote.close) {
+                self.at += quote.close.chars().count();
+                break;
+            }
+            self.at += 1;
+        }
+        self.at = self.at.min(self.code.len());
+        self.emit(start, Kind::String);
+    }
+
+    fn attribute(&mut self) -> bool {
+        let start = self.at;
+        match self.rules.attributes {
+            Attributes::None => return false,
+            Attributes::AtWord => {
+                if self.code[self.at] != '@' || !is_word_start(self.code.get(self.at + 1).copied())
+                {
+                    return false;
+                }
+                self.at += 1;
+                while self.at < self.code.len() && is_word_part(self.code[self.at]) {
+                    self.at += 1;
+                }
+            }
+            Attributes::HashBracket => {
+                if self.code[self.at] != '#' {
+                    return false;
+                }
+                let mut ahead = self.at + 1;
+                if self.code.get(ahead) == Some(&'!') {
+                    ahead += 1;
+                }
+                if self.code.get(ahead) != Some(&'[') {
+                    return false;
+                }
+                self.at = ahead;
+                self.advance_to_matching_bracket();
+            }
+            Attributes::HashLine => {
+                if self.code[self.at] != '#' || !self.at_line_start() {
+                    return false;
+                }
+                self.advance_to_end_of_line();
+            }
+            Attributes::LineBracket => {
+                if self.code[self.at] != '[' || !self.at_line_start() {
+                    return false;
+                }
+                self.advance_to_matching_bracket();
+            }
+        }
+        self.emit(start, Kind::Metadata);
+        true
+    }
+
+    /// A number is a run starting with a digit and carrying on through
+    /// letters, digits, `_` and `.` -- which covers `0xFF`, `1_000`, `1u32`
+    /// and `3.14` without a grammar for any of them.
+    fn number(&mut self) -> bool {
+        if !self.code[self.at].is_ascii_digit() {
+            return false;
+        }
+        let start = self.at;
+        while self.at < self.code.len() {
+            let c = self.code[self.at];
+            if c.is_alphanumeric() || c == '_' || c == '.' {
+                self.at += 1;
+            } else {
+                break;
+            }
+        }
+        self.emit(start, Kind::Literal);
+        true
+    }
+
+    fn word(&mut self) -> bool {
+        if !is_word_start(Some(self.code[self.at])) {
+            return false;
+        }
+        let start = self.at;
+        while self.at < self.code.len() && is_word_part(self.code[self.at]) {
+            self.at += 1;
+        }
+        let word: String = self.code[start..self.at].iter().collect();
+        if self.rules.keywords.contains(word.as_str()) {
+            self.emit(start, Kind::Keyword);
+        }
+        true
+    }
+
+    fn single_character(&mut self) -> bool {
+        let kind = if PUNCTUATION.contains(self.code[self.at]) {
+            Kind::Punctuation
+        } else if MARKS.contains(self.code[self.at]) {
+            Kind::Mark
+        } else {
+            return false;
+        };
+        self.at += 1;
+        self.emit(self.at - 1, kind);
+        true
+    }
+}
+
+fn is_word_start(c: Option<char>) -> bool {
+    matches!(c, Some(c) if c.is_alphabetic() || c == '_')
+}
+
+fn is_word_part(c: char) -> bool {
+    c.is_alphanumeric() || c == '_'
+}
+
+/// Whether `code[at..]` starts with `token`, both read as chars.
+fn starts_with_at(code: &[char], at: usize, token: &str) -> bool {
+    let token: Vec<char> = token.chars().collect();
+    if at + token.len() > code.len() {
+        return false;
+    }
+    code[at..at + token.len()] == token[..]
+}
+
+/// The first index at or after `from` where `code` contains `needle`, or
+/// `None`.
+fn find_from(code: &[char], from: usize, needle: &[char]) -> Option<usize> {
+    if needle.is_empty() || from > code.len() {
+        return None;
+    }
+    (from..=code.len().saturating_sub(needle.len())).find(|&i| code[i..i + needle.len()] == *needle)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn spans(code: &str, language: Language, kind: Kind) -> Vec<String> {
+        let chars: Vec<char> = code.chars().collect();
+        spans_of(code, language)
+            .into_iter()
+            .filter(|s| s.kind == kind)
+            .map(|s| span_text(&chars, &s))
+            .collect()
+    }
+
+    fn assert_spans(code: &str, language: Language, kind: Kind, expected: &[&str]) {
+        assert_eq!(
+            spans(code, language, kind),
+            expected.to_vec(),
+            "{kind:?} in: {code}"
+        );
+    }
+
+    #[test]
+    fn a_quoted_glob_is_one_string_not_a_comment() {
+        assert_spans("x '*/a/*'", Language::Shell, Kind::String, &["'*/a/*'"]);
+        assert_spans("x '*/a/*'", Language::Shell, Kind::Comment, &[]);
+    }
+
+    #[test]
+    fn a_find_with_globs_has_no_comment_in_it() {
+        let code = "find . -path '*/.git/*' -prune -o -name '*.kt' -print";
+        assert_spans(
+            code,
+            Language::Shell,
+            Kind::String,
+            &["'*/.git/*'", "'*.kt'"],
+        );
+        assert_spans(code, Language::Shell, Kind::Comment, &[]);
+    }
+
+    #[test]
+    fn a_url_does_not_comment_out_the_rest_of_a_shell_line() {
+        let code = "curl https://example.com/x && echo done";
+        assert_spans(code, Language::Shell, Kind::Comment, &[]);
+        assert_spans(code, Language::Shell, Kind::Keyword, &["echo"]);
+    }
+
+    #[test]
+    fn a_url_inside_a_kotlin_string_stays_a_string() {
+        let code = "val url = \"https://example.com\"\nfun f() = 1";
+        assert_spans(code, Language::Kotlin, Kind::Comment, &[]);
+        assert_spans(
+            code,
+            Language::Kotlin,
+            Kind::String,
+            &["\"https://example.com\""],
+        );
+        assert_spans(code, Language::Kotlin, Kind::Keyword, &["val", "fun"]);
+    }
+
+    #[test]
+    fn a_rust_attribute_is_metadata_and_the_struct_after_it_still_colours() {
+        let code = "#[derive(Debug)]\nstruct A { b: u8 }";
+        assert_spans(code, Language::Rust, Kind::Metadata, &["#[derive(Debug)]"]);
+        assert_spans(code, Language::Rust, Kind::Comment, &[]);
+        assert_spans(code, Language::Rust, Kind::Keyword, &["struct"]);
+    }
+
+    #[test]
+    fn an_inner_rust_attribute_closes_at_its_own_bracket() {
+        let code = "#![allow(dead_code)]\nfn f() {}";
+        assert_spans(
+            code,
+            Language::Rust,
+            Kind::Metadata,
+            &["#![allow(dead_code)]"],
+        );
+        assert_spans(code, Language::Rust, Kind::Keyword, &["fn"]);
+    }
+
+    #[test]
+    fn a_c_preprocessor_line_is_metadata_rather_than_a_comment() {
+        let code = "#include <stdio.h>\nint main() { return 0; }";
+        assert_spans(code, Language::C, Kind::Metadata, &["#include <stdio.h>"]);
+        assert_spans(code, Language::C, Kind::Comment, &[]);
+        assert_spans(code, Language::C, Kind::Keyword, &["int", "return"]);
+    }
+
+    #[test]
+    fn a_kotlin_annotation_is_metadata() {
+        assert_spans(
+            "@Composable fun f() {}",
+            Language::Kotlin,
+            Kind::Metadata,
+            &["@Composable"],
+        );
+    }
+
+    #[test]
+    fn a_hash_inside_a_kotlin_string_is_not_a_comment() {
+        let code = "val c = \"#FF0000\"\nval d = 1";
+        assert_spans(code, Language::Kotlin, Kind::Comment, &[]);
+        assert_spans(code, Language::Kotlin, Kind::String, &["\"#FF0000\""]);
+    }
+
+    #[test]
+    fn an_apostrophe_inside_a_kotlin_string_does_not_open_one() {
+        let code = "val a = \"don't\"\nval b = \"x\"";
+        assert_spans(
+            code,
+            Language::Kotlin,
+            Kind::String,
+            &["\"don't\"", "\"x\""],
+        );
+    }
+
+    #[test]
+    fn a_rust_lifetime_does_not_open_a_string_but_a_character_literal_does() {
+        let code = "fn f<'a>(x: &'a str) { let c = 'x'; }";
+        assert_spans(code, Language::Rust, Kind::String, &["'x'"]);
+    }
+
+    #[test]
+    fn an_escaped_quote_is_inside_the_rust_character_literal() {
+        assert_spans("let c = '\\'';", Language::Rust, Kind::String, &["'\\''"]);
+    }
+
+    #[test]
+    fn a_rust_raw_string_keeps_its_inner_quotes() {
+        let code = "let s = r#\"a \"quoted\" b\"#;";
+        assert_spans(
+            code,
+            Language::Rust,
+            Kind::String,
+            &["r#\"a \"quoted\" b\"#"],
+        );
+    }
+
+    #[test]
+    fn a_kotlin_triple_quoted_string_is_one_string() {
+        assert_spans(
+            "val s = \"\"\"a \"b\" c\"\"\"",
+            Language::Kotlin,
+            Kind::String,
+            &["\"\"\"a \"b\" c\"\"\""],
+        );
+    }
+
+    #[test]
+    fn a_shell_single_quoted_string_takes_no_escapes() {
+        assert_spans("echo 'a\\' b", Language::Shell, Kind::String, &["'a\\'"]);
+    }
+
+    #[test]
+    fn rust_and_kotlin_nest_block_comments() {
+        let code = "/* a /* b */ c */ x";
+        assert_spans(code, Language::Rust, Kind::Comment, &["/* a /* b */ c */"]);
+        assert_spans(
+            code,
+            Language::Kotlin,
+            Kind::Comment,
+            &["/* a /* b */ c */"],
+        );
+    }
+
+    #[test]
+    fn c_ends_a_block_comment_at_the_first_close() {
+        assert_spans(
+            "/* a /* b */ c */ x",
+            Language::C,
+            Kind::Comment,
+            &["/* a /* b */"],
+        );
+    }
+
+    #[test]
+    fn a_shell_comment_starts_only_at_a_word_boundary() {
+        let code = "${#x} $# a#b # real";
+        assert_spans(code, Language::Shell, Kind::Comment, &["# real"]);
+    }
+
+    #[test]
+    fn a_hash_anywhere_is_a_python_comment() {
+        assert_spans("x = 1 # note", Language::Python, Kind::Comment, &["# note"]);
+    }
+
+    #[test]
+    fn a_toml_table_header_is_metadata_and_a_hash_in_a_value_is_not_a_comment() {
+        let code = "[server]\ncolour = \"#FF0000\"\nport = 8080 # the real one";
+        assert_spans(code, Language::Toml, Kind::Metadata, &["[server]"]);
+        assert_spans(code, Language::Toml, Kind::String, &["\"#FF0000\""]);
+        assert_spans(code, Language::Toml, Kind::Comment, &["# the real one"]);
+        assert_spans(code, Language::Toml, Kind::Literal, &["8080"]);
+    }
+
+    #[test]
+    fn a_ron_attribute_and_its_values_colour() {
+        let code = "#![enable(implicit_some)]\n(count: 3, on: true)";
+        assert_spans(
+            code,
+            Language::Ron,
+            Kind::Metadata,
+            &["#![enable(implicit_some)]"],
+        );
+        assert_spans(code, Language::Ron, Kind::Keyword, &["true"]);
+        assert_spans(code, Language::Ron, Kind::Literal, &["3"]);
+    }
+
+    #[test]
+    fn an_unknown_fence_language_is_none() {
+        assert_eq!(fence_language(Some("brainfuck")), None);
+    }
+
+    #[test]
+    fn every_language_the_fence_table_knows_has_a_scanner() {
+        for language in Language::ALL {
+            spans_of("x", language);
+        }
+    }
+
+    /// The scanner must never panic and must never answer a span the code
+    /// does not contain: the library this replaced answered a reversed
+    /// range here, which crashed a card, and a fence still being written is
+    /// an unterminated string or comment on every keystroke.
+    #[test]
+    fn spans_stay_inside_the_code_for_every_language_and_every_nasty_input() {
+        let nasty = [
+            "",
+            "'",
+            "\"",
+            "\"unterminated",
+            "/* unterminated",
+            "###",
+            "#",
+            "#![",
+            "[",
+            "r#\"",
+            "\\",
+            "'''",
+            "\"\"\"",
+            "0x",
+            "1.2.3",
+            "a#b//c/*d*/'e\"f",
+            "```",
+            "*",
+            "**",
+            "~~",
+            "> ",
+            "- ",
+            "1.",
+            "[x](",
+            "#######",
+            "|",
+            "|---|",
+            "<",
+            "<>",
+            "http://",
+            "a://",
+            "\n\n   \n",
+        ];
+        for language in Language::ALL {
+            for code in nasty {
+                let chars: Vec<char> = code.chars().collect();
+                let spans = spans_of(code, language);
+                for s in &spans {
+                    assert!(
+                        s.start <= s.end && s.end <= chars.len(),
+                        "{language:?} answered {s:?} for {code:?}"
+                    );
+                }
+                let mut sorted = spans.clone();
+                sorted.sort_by_key(|s| s.start);
+                assert_eq!(
+                    spans, sorted,
+                    "{language:?} answered spans out of order for {code:?}"
+                );
+            }
+        }
+    }
+}

client-core/src/lib.rs

@@ -0,0 +1,15 @@
+//! The app's pure logic, shared between the server and any Rust client --
+//! see `CLIENT_CORE.md` at the repo root for what lives here and what does
+//! not yet.
+
+pub mod ansi;
+pub mod api;
+pub mod config;
+pub mod event_stream;
+pub mod highlight;
+pub mod notifications;
+pub mod sse;
+pub mod transcript_cache;
+pub mod transcript_fold;
+
+pub use event_model::*;

client-core/src/notifications.rs

@@ -0,0 +1,162 @@
+//! `GET /notifications`, the attention stream PLAN.md's "Notifications: two
+//! places, never both" describes. Ported from the parsing half of
+//! `app/.../Notifications.kt`'s `NotificationService` -- the framing
+//! ([`crate::sse`]) and the wire shape ([`SessionNotification`],
+//! [`NotificationKind`], mirroring `server/src/session/mod.rs`'s
+//! `Notification`/`NotificationKind`).
+//!
+//! What is deliberately **not** here, because it is a decision rather than
+//! logic: whether a given notification is shown at all (the session on
+//! screen gets nothing), handed to the app as a banner, or posted to the
+//! platform's own notification drawer. That three-way choice reads
+//! process-wide state (what screen is open, whether the app is in front)
+//! that has no meaning to a pure crate with no UI and no Android in it --
+//! see `android-shell` for where it lives for this port.
+
+use std::io::{BufRead, BufReader};
+
+use serde::Deserialize;
+
+use crate::api::{ApiError, Transport};
+use crate::sse::SseReader;
+
+/// One frame of `GET /notifications`, matching `server/src/session/mod.rs`'s
+/// `Notification` field for field.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SessionNotification {
+    pub session_id: String,
+    pub title: String,
+    pub kind: NotificationKind,
+    /// Epoch seconds, so a phone that was asleep can say how long ago.
+    pub at: f64,
+}
+
+/// Mirrors `server/src/session/mod.rs`'s `NotificationKind` -- serialized
+/// the same way, so this deserializes the wire's `"awaitingInput"` /
+/// `"finished"` directly rather than through a string match.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum NotificationKind {
+    AwaitingInput,
+    Finished,
+}
+
+impl NotificationKind {
+    /// What a notification asks of the reader, in the words they see --
+    /// ported verbatim from `Notifications.kt`'s `attentionLine`. One
+    /// function because the same fact is shown in two places (the
+    /// platform's drawer and the app's own banner) and two mappings of one
+    /// word drift.
+    pub fn attention_line(self) -> &'static str {
+        match self {
+            NotificationKind::AwaitingInput => "Waiting for you",
+            NotificationKind::Finished => "Finished",
+        }
+    }
+}
+
+/// Follows `/notifications`, calling `on_notification` for each frame until
+/// the connection drops or the callback asks to stop (by returning
+/// `false`). Reconnecting is the caller's job -- mirroring
+/// `NotificationService.follow`'s retry loop, which is a platform policy
+/// (how long to wait, whether to give up) rather than parsing logic.
+pub fn follow_notifications(
+    transport: &dyn Transport,
+    mut on_notification: impl FnMut(SessionNotification) -> bool,
+) -> Result<(), ApiError> {
+    let body = transport.stream("/notifications")?;
+    let mut lines = BufReader::new(body).lines();
+    let mut reader = SseReader::new();
+    while let Some(line) = lines.next().transpose().map_err(|e| ApiError {
+        message: format!("Can't reach the server -- retrying. ({e})"),
+        status: None,
+    })? {
+        let Some(frame) = reader.feed_line(&line) else {
+            continue;
+        };
+        if frame.data.is_empty() {
+            continue;
+        }
+        let notification: SessionNotification =
+            serde_json::from_str(&frame.data).map_err(|e| ApiError {
+                message: format!("The server sent a notification this build couldn't parse: {e}"),
+                status: None,
+            })?;
+        if !on_notification(notification) {
+            return Ok(());
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::{Body, RawResponse};
+    use std::io::Cursor;
+
+    struct FixtureTransport {
+        body: &'static str,
+    }
+
+    impl Transport for FixtureTransport {
+        fn request(
+            &self,
+            _method: &str,
+            _path: &str,
+            _body: Option<Body>,
+        ) -> Result<RawResponse, ApiError> {
+            unimplemented!("this fixture only serves a stream")
+        }
+
+        fn stream(&self, _path: &str) -> Result<Box<dyn std::io::Read + Send>, ApiError> {
+            Ok(Box::new(Cursor::new(self.body.as_bytes().to_vec())))
+        }
+    }
+
+    #[test]
+    fn a_notification_frame_parses_both_kinds() {
+        let transport = FixtureTransport {
+            body: "data:{\"sessionId\":\"s1\",\"title\":\"fix the bug\",\"kind\":\"awaitingInput\",\"at\":1.0}\n\n\
+                   data:{\"sessionId\":\"s2\",\"title\":\"add tests\",\"kind\":\"finished\",\"at\":2.0}\n\n",
+        };
+        let mut seen = Vec::new();
+        follow_notifications(&transport, |n| {
+            seen.push((n.session_id, n.kind));
+            true
+        })
+        .unwrap();
+        assert_eq!(
+            seen,
+            vec![
+                ("s1".to_string(), NotificationKind::AwaitingInput),
+                ("s2".to_string(), NotificationKind::Finished),
+            ]
+        );
+    }
+
+    #[test]
+    fn the_caller_can_stop_early() {
+        let transport = FixtureTransport {
+            body: "data:{\"sessionId\":\"s1\",\"title\":\"a\",\"kind\":\"finished\",\"at\":1.0}\n\n\
+                   data:{\"sessionId\":\"s2\",\"title\":\"b\",\"kind\":\"finished\",\"at\":2.0}\n\n",
+        };
+        let mut count = 0;
+        follow_notifications(&transport, |_| {
+            count += 1;
+            count < 1
+        })
+        .unwrap();
+        assert_eq!(count, 1);
+    }
+
+    #[test]
+    fn attention_line_matches_the_kotlin_original() {
+        assert_eq!(
+            NotificationKind::AwaitingInput.attention_line(),
+            "Waiting for you"
+        );
+        assert_eq!(NotificationKind::Finished.attention_line(), "Finished");
+    }
+}

client-core/src/sse.rs

@@ -0,0 +1,121 @@
+//! Server-sent-events framing, ported from `app/.../Sse.kt`: `data:` and
+//! `event:` lines accumulate until a blank line ends the frame, comments
+//! start with `:`, and a frame is either named with no payload or a payload
+//! with no name.
+//!
+//! Pure and line-at-a-time, unlike the Kotlin original which also owned the
+//! socket: `server/routes.rs`'s SSE bodies are one event per line, so a
+//! caller here feeds lines from wherever they came from (a real connection,
+//! a test fixture) and gets frames back with no I/O of its own -- which is
+//! what lets this be tested with no server, per RUST.md's "pure logic
+//! first" for this crate.
+
+/// One SSE frame: its name (`None` for an ordinary data frame) and its payload.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Frame {
+    pub name: Option<String>,
+    pub data: String,
+}
+
+/// Accumulates lines into [`Frame`]s. One instance per connection --
+/// `feed_line` is called for every line the transport reads (with line
+/// endings already stripped), and answers a frame when a blank line closes
+/// one.
+#[derive(Debug, Default)]
+pub struct SseReader {
+    data: String,
+    name: Option<String>,
+}
+
+impl SseReader {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Feeds one line (no trailing `\n`). Answers the frame this line
+    /// completed, if any.
+    pub fn feed_line(&mut self, line: &str) -> Option<Frame> {
+        if line.is_empty() {
+            if self.name.is_some() || !self.data.is_empty() {
+                let frame = Frame {
+                    name: self.name.take(),
+                    data: std::mem::take(&mut self.data),
+                };
+                return Some(frame);
+            }
+            return None;
+        }
+        if let Some(rest) = line.strip_prefix("data:") {
+            self.data.push_str(rest.trim());
+        } else if let Some(rest) = line.strip_prefix("event:") {
+            self.name = Some(rest.trim().to_string());
+        }
+        // `id:`, comments -- nothing to do.
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn frames(lines: &[&str]) -> Vec<Frame> {
+        let mut reader = SseReader::new();
+        lines.iter().filter_map(|l| reader.feed_line(l)).collect()
+    }
+
+    #[test]
+    fn a_data_only_frame_has_no_name() {
+        assert_eq!(
+            frames(&["data:hello", ""]),
+            vec![Frame {
+                name: None,
+                data: "hello".to_string()
+            }]
+        );
+    }
+
+    #[test]
+    fn a_named_frame_with_no_payload_still_completes() {
+        assert_eq!(
+            frames(&["event:reset", ""]),
+            vec![Frame {
+                name: Some("reset".to_string()),
+                data: String::new()
+            }]
+        );
+    }
+
+    #[test]
+    fn a_blank_line_with_nothing_pending_yields_no_frame() {
+        assert_eq!(frames(&[""]), vec![]);
+    }
+
+    #[test]
+    fn a_comment_and_an_id_line_are_ignored() {
+        assert_eq!(
+            frames(&[":keepalive", "id:5", "data:hi", ""]),
+            vec![Frame {
+                name: None,
+                data: "hi".to_string()
+            }]
+        );
+    }
+
+    #[test]
+    fn two_frames_in_a_row_are_both_reported() {
+        assert_eq!(
+            frames(&["data:one", "", "data:two", ""]),
+            vec![
+                Frame {
+                    name: None,
+                    data: "one".to_string()
+                },
+                Frame {
+                    name: None,
+                    data: "two".to_string()
+                },
+            ]
+        );
+    }
+}

client-core/src/transcript_fold.rs

@@ -0,0 +1,827 @@
+//! What the transcript renders: the event stream folded into displayable
+//! rows. Ported from `app/.../TranscriptItems.kt` and `ToolRows.kt`'s
+//! non-Compose half (`TranscriptRow`, `groupToolRuns`).
+//!
+//! Events are the only data source, and there is deliberately no second
+//! shape for history to drift from: a page fetched backwards, a live
+//! frame, and a line read out of the transcript cache are all the same
+//! events through the same fold.
+//!
+//! **Not ported**: `TranscriptUnits.kt`'s further flatten of a row into
+//! Compose list units (`TranscriptUnit`, `transcriptUnits`) -- that layer
+//! exists to bound how much a lazy list composes per frame, which is a
+//! fact about the UI framework drawing it, not about the transcript. See
+//! `CLIENT_CORE.md`.
+//!
+//! **Known gap**: unlike `Events.kt`'s hand-kept mirror, this crate
+//! deserializes straight into [`event_model::Event`], which has no
+//! `Unknown` catch-all -- an event type this build does not recognise
+//! fails to parse rather than degrading to a placeholder row. Closing that
+//! gap means giving `event_model::Event` its own forward-compatible
+//! variant, which is a shared-model decision for both sides of the wire
+//! and is deliberately left for whoever picks this up next (see
+//! `CLIENT_CORE.md`).
+
+use event_model::{Event, QuestionOption, SeqEvent, SessionStatus};
+
+/// A question this build has already asked the reader about, with what was
+/// answered so far -- distinct from [`QuestionOption`], which is what could
+/// be chosen.
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuestionCard {
+    pub seq: u64,
+    pub id: String,
+    pub prompt: String,
+    pub header: Option<String>,
+    pub options: Vec<QuestionOption>,
+    pub multi_select: bool,
+    pub answers: Vec<String>,
+}
+
+/// A tool call cannot be recognised as `AskUserQuestion` from a bare
+/// `ToolEnd` (its name is not carried), so `runIdFor` and the run-adoption
+/// logic name it explicitly.
+pub const ASK_USER_QUESTION: &str = "AskUserQuestion";
+
+/// This item's identity in the list: a `Seq` for everything with no
+/// identity of its own, `RunId` for a tool call (which keeps one across
+/// however many calls join or leave its run), matching `TranscriptItem.key`
+/// in the Kotlin original.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum ItemKey {
+    Seq(u64),
+    RunId(String),
+}
+
+/// One row of the transcript, folded from [`Event`]s. See each variant's
+/// Kotlin counterpart in `TranscriptItem` for the fuller rationale; this
+/// doc only says what changed in translation.
+#[derive(Debug, Clone, PartialEq)]
+pub enum TranscriptItem {
+    UserMsg {
+        seq: u64,
+        text: String,
+        attachments: Vec<String>,
+    },
+    AssistantMsg {
+        seq: u64,
+        text: String,
+        /// Whether this reply is finished -- see `AssistantMsg.settled`'s
+        /// Kotlin doc for why the split it licenses matters.
+        settled: bool,
+    },
+    ToolRun {
+        seq: u64,
+        id: String,
+        run_id: String,
+        tool: String,
+        input: String,
+        output: String,
+        done: bool,
+        asks: Vec<QuestionCard>,
+        images: Vec<String>,
+    },
+    QuestionCard(QuestionCard),
+    ErrorMsg {
+        seq: u64,
+        message: String,
+    },
+    ImageItem {
+        seq: u64,
+        r#ref: String,
+    },
+    /// A message from another agent. `arrived` is this row's own identity
+    /// ([`TranscriptItem::key`]); `seq` is where it *sorts*, which
+    /// [`place_peer_note`] may set to the turn's opening seq instead.
+    PeerNote {
+        seq: u64,
+        from: String,
+        text: String,
+        arrived: u64,
+    },
+    CommandRow {
+        seq: u64,
+        text: String,
+    },
+    /// Placeholder for an event kind this build could not fold -- see the
+    /// module doc's "known gap".
+    Note {
+        seq: u64,
+        text: String,
+    },
+    ClearedNote {
+        seq: u64,
+    },
+    CompactedNote {
+        seq: u64,
+        pre_tokens: Option<u64>,
+        post_tokens: Option<u64>,
+    },
+}
+
+impl TranscriptItem {
+    pub fn seq(&self) -> u64 {
+        match self {
+            Self::UserMsg { seq, .. }
+            | Self::AssistantMsg { seq, .. }
+            | Self::ToolRun { seq, .. }
+            | Self::ErrorMsg { seq, .. }
+            | Self::ImageItem { seq, .. }
+            | Self::PeerNote { seq, .. }
+            | Self::CommandRow { seq, .. }
+            | Self::Note { seq, .. }
+            | Self::ClearedNote { seq }
+            | Self::CompactedNote { seq, .. } => *seq,
+            Self::QuestionCard(card) => card.seq,
+        }
+    }
+
+    pub fn key(&self) -> ItemKey {
+        match self {
+            Self::ToolRun { run_id, .. } => ItemKey::RunId(run_id.clone()),
+            Self::PeerNote { arrived, .. } => ItemKey::Seq(*arrived),
+            other => ItemKey::Seq(other.seq()),
+        }
+    }
+
+    fn as_tool_run(&self) -> Option<&str> {
+        match self {
+            Self::ToolRun { id, .. } => Some(id),
+            _ => None,
+        }
+    }
+}
+
+/// The run a call joins: the one it lands next to, or a new one named
+/// after itself. See the Kotlin `runIdFor`'s doc for why the name, once
+/// picked, never changes.
+fn run_id_for(items: &[TranscriptItem], id: &str, tool: &str) -> String {
+    let Some(TranscriptItem::ToolRun {
+        run_id,
+        tool: previous_tool,
+        ..
+    }) = items.last()
+    else {
+        return id.to_string();
+    };
+    if tool == ASK_USER_QUESTION || previous_tool == ASK_USER_QUESTION {
+        id.to_string()
+    } else {
+        run_id.clone()
+    }
+}
+
+fn update_tool(
+    items: &[TranscriptItem],
+    id: &str,
+    change: impl Fn(&mut TranscriptItem),
+) -> Vec<TranscriptItem> {
+    items
+        .iter()
+        .cloned()
+        .map(|mut item| {
+            if item.as_tool_run() == Some(id) {
+                change(&mut item);
+            }
+            item
+        })
+        .collect()
+}
+
+/// Whether a status means the session is still doing something, mirroring
+/// `sessionWorking` in `Events.kt`.
+pub fn session_working(status: SessionStatus) -> bool {
+    matches!(status, SessionStatus::Running | SessionStatus::Compacting)
+}
+
+/// A status saying the session stopped working is the moment its newest
+/// reply is finished.
+fn settle_reply(items: &[TranscriptItem], status: SessionStatus) -> Vec<TranscriptItem> {
+    if session_working(status) {
+        return items.to_vec();
+    }
+    let Some(TranscriptItem::AssistantMsg { settled: false, .. }) = items.last() else {
+        return items.to_vec();
+    };
+    let mut items = items.to_vec();
+    if let Some(TranscriptItem::AssistantMsg { settled, .. }) = items.last_mut() {
+        *settled = true;
+    }
+    items
+}
+
+/// A peer message goes above the turn it started, not where it happened to
+/// arrive. See the Kotlin `placePeerNote`'s doc for the full reasoning;
+/// `turn_start` is `Event::PeerMessage`'s own field of that name.
+fn place_peer_note(
+    items: &[TranscriptItem],
+    seq: u64,
+    from: &str,
+    text: &str,
+    turn_start: Option<u64>,
+) -> Vec<TranscriptItem> {
+    let Some(at) = turn_start else {
+        let mut items = items.to_vec();
+        items.push(TranscriptItem::PeerNote {
+            seq,
+            from: from.to_string(),
+            text: text.to_string(),
+            arrived: seq,
+        });
+        return items;
+    };
+    let note = TranscriptItem::PeerNote {
+        seq: at,
+        from: from.to_string(),
+        text: text.to_string(),
+        arrived: seq,
+    };
+    let Some(index) = items.iter().position(|i| i.seq() > at) else {
+        let mut items = items.to_vec();
+        items.push(note);
+        return items;
+    };
+    let behind = match index.checked_sub(1).and_then(|i| items.get(i)) {
+        Some(TranscriptItem::ToolRun { run_id, .. }) => Some(run_id.clone()),
+        _ => None,
+    };
+    let mut out = items[..index].to_vec();
+    out.push(note);
+    out.extend(split_run(&items[index..], behind.as_deref()));
+    out
+}
+
+/// The calls the note now sits in front of, renamed if they were sharing a
+/// run with the calls behind it. See the Kotlin `splitRun`'s doc.
+fn split_run(tail: &[TranscriptItem], behind: Option<&str>) -> Vec<TranscriptItem> {
+    let Some(TranscriptItem::ToolRun {
+        run_id: first_run_id,
+        id: first_id,
+        ..
+    }) = tail.first()
+    else {
+        return tail.to_vec();
+    };
+    let Some(behind) = behind else {
+        return tail.to_vec();
+    };
+    if first_run_id != behind {
+        return tail.to_vec();
+    }
+    let run_len = tail
+        .iter()
+        .take_while(|i| matches!(i, TranscriptItem::ToolRun { run_id, .. } if run_id == behind))
+        .count();
+    let mut out: Vec<TranscriptItem> = tail[..run_len]
+        .iter()
+        .cloned()
+        .map(|mut item| {
+            if let TranscriptItem::ToolRun { run_id, .. } = &mut item {
+                *run_id = first_id.clone();
+            }
+            item
+        })
+        .collect();
+    out.extend(tail[run_len..].iter().cloned());
+    out
+}
+
+/// Folds one transcript event onto `items`, the way `foldEvent` does in
+/// `TranscriptItems.kt`. Every wire event has a case; see the module doc
+/// for the one difference from the Kotlin original (no `Unknown` fallback
+/// at the parse layer).
+pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptItem> {
+    let seq = entry.seq;
+    match &entry.event {
+        Event::UserMessage {
+            text, attachments, ..
+        } => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::UserMsg {
+                seq,
+                text: text.clone(),
+                attachments: attachments.clone(),
+            });
+            items
+        }
+        // `MessageTaken` is folded into `UserMessage` by the manager before
+        // it reaches a phone (see `PLAN.md`); if one arrives here anyway
+        // (a raw transcript line, say), it reads the same way.
+        Event::MessageTaken {
+            text, attachments, ..
+        } => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::UserMsg {
+                seq,
+                text: text.clone(),
+                attachments: attachments.clone(),
+            });
+            items
+        }
+        Event::AssistantText { delta } => {
+            // Deltas accumulate into the message they're streaming, which
+            // keeps the seq of the *first* of them: a row whose identity
+            // changed with every delta would be a new row every frame.
+            // "A message growing again is not finished" -- whatever a
+            // status said in between -- is why this always clears
+            // `settled` rather than preserving it.
+            if let Some(TranscriptItem::AssistantMsg {
+                seq: first_seq,
+                text,
+                ..
+            }) = items.last()
+            {
+                let first_seq = *first_seq;
+                let text = format!("{text}{delta}");
+                let mut items = items[..items.len() - 1].to_vec();
+                items.push(TranscriptItem::AssistantMsg {
+                    seq: first_seq,
+                    text,
+                    settled: false,
+                });
+                items
+            } else {
+                let mut items = items.to_vec();
+                items.push(TranscriptItem::AssistantMsg {
+                    seq,
+                    text: delta.clone(),
+                    settled: false,
+                });
+                items
+            }
+        }
+        Event::ToolStart { id, tool, input } => {
+            let run_id = run_id_for(items, id, tool);
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::ToolRun {
+                seq,
+                id: id.clone(),
+                run_id,
+                tool: tool.clone(),
+                input: input.to_string(),
+                output: String::new(),
+                done: false,
+                asks: Vec::new(),
+                images: Vec::new(),
+            });
+            items
+        }
+        Event::ToolUpdate { id, output } => update_tool(items, id, |item| {
+            if let TranscriptItem::ToolRun { output: out, .. } = item {
+                *out = output.clone();
+            }
+        }),
+        Event::ToolEnd { id, output } => {
+            if items.iter().any(|i| i.as_tool_run() == Some(id.as_str())) {
+                update_tool(items, id, |item| {
+                    if let TranscriptItem::ToolRun {
+                        output: out, done, ..
+                    } = item
+                    {
+                        *out = output.clone();
+                        *done = true;
+                    }
+                })
+            } else {
+                let run_id = run_id_for(items, id, "tool");
+                let mut items = items.to_vec();
+                items.push(TranscriptItem::ToolRun {
+                    seq,
+                    id: id.clone(),
+                    run_id,
+                    tool: "tool".to_string(),
+                    input: String::new(),
+                    output: output.clone(),
+                    done: true,
+                    asks: Vec::new(),
+                    images: Vec::new(),
+                });
+                items
+            }
+        }
+        Event::Question {
+            id,
+            prompt,
+            header,
+            options,
+            multi_select,
+            about,
+        } => {
+            let card = QuestionCard {
+                seq,
+                id: id.clone(),
+                prompt: prompt.clone(),
+                header: header.clone(),
+                options: options.clone(),
+                multi_select: *multi_select,
+                answers: Vec::new(),
+            };
+            let about_tool = about
+                .as_deref()
+                .is_some_and(|about| items.iter().any(|i| i.as_tool_run() == Some(about)));
+            if about_tool {
+                let about = about.clone().unwrap();
+                update_tool(items, &about, move |item| {
+                    if let TranscriptItem::ToolRun { asks, .. } = item {
+                        asks.push(card.clone());
+                    }
+                })
+            } else {
+                let mut items = items.to_vec();
+                items.push(TranscriptItem::QuestionCard(card));
+                items
+            }
+        }
+        Event::Answered { id, answers } => items
+            .iter()
+            .cloned()
+            .map(|item| match item {
+                TranscriptItem::QuestionCard(mut card) if &card.id == id => {
+                    card.answers = answers.clone();
+                    TranscriptItem::QuestionCard(card)
+                }
+                TranscriptItem::ToolRun {
+                    mut asks,
+                    seq,
+                    id: tid,
+                    run_id,
+                    tool,
+                    input,
+                    output,
+                    done,
+                    images,
+                } if asks.iter().any(|a| &a.id == id) => {
+                    for ask in asks.iter_mut() {
+                        if &ask.id == id {
+                            ask.answers = answers.clone();
+                        }
+                    }
+                    TranscriptItem::ToolRun {
+                        seq,
+                        id: tid,
+                        run_id,
+                        tool,
+                        input,
+                        output,
+                        done,
+                        asks,
+                        images,
+                    }
+                }
+                other => other,
+            })
+            .collect(),
+        Event::PeerMessage {
+            from,
+            text,
+            turn_start,
+        } => place_peer_note(items, seq, from, text, *turn_start),
+        Event::CommandSent { text, .. } => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::CommandRow {
+                seq,
+                text: text.clone(),
+            });
+            items
+        }
+        // Screen-level state, not transcript rows.
+        Event::CommandQueued { .. }
+        | Event::MessageQueued { .. }
+        | Event::MessageDropped { .. }
+        | Event::Settings { .. }
+        | Event::UsageDelta { .. } => items.to_vec(),
+        Event::Status { state } => settle_reply(items, *state),
+        Event::Error { message } => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::ErrorMsg {
+                seq,
+                message: message.clone(),
+            });
+            items
+        }
+        Event::Image { image, about } => {
+            let about_tool = about
+                .as_deref()
+                .is_some_and(|about| items.iter().any(|i| i.as_tool_run() == Some(about)));
+            if about_tool {
+                let about = about.clone().unwrap();
+                let image = image.clone();
+                update_tool(items, &about, move |item| {
+                    if let TranscriptItem::ToolRun { images, .. } = item {
+                        images.push(image.clone());
+                    }
+                })
+            } else {
+                let mut items = items.to_vec();
+                items.push(TranscriptItem::ImageItem {
+                    seq,
+                    r#ref: image.clone(),
+                });
+                items
+            }
+        }
+        Event::Cleared => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::ClearedNote { seq });
+            items
+        }
+        Event::Compacted {
+            pre_tokens,
+            post_tokens,
+            ..
+        } => {
+            let mut items = items.to_vec();
+            items.push(TranscriptItem::CompactedNote {
+                seq,
+                pre_tokens: *pre_tokens,
+                post_tokens: *post_tokens,
+            });
+            items
+        }
+    }
+}
+
+/// One row as the transcript draws it: a run of consecutive tool calls, or
+/// anything else. Ported from `ToolRows.kt`'s `TranscriptRow` and
+/// `groupToolRuns` -- the Compose card rendering in that file is not part
+/// of this crate.
+#[derive(Debug, Clone, PartialEq)]
+pub enum TranscriptRow {
+    Single(TranscriptItem),
+    /// Two or more calls with nothing between them.
+    Tools(Vec<TranscriptItem>),
+}
+
+impl TranscriptRow {
+    pub fn key(&self) -> ItemKey {
+        match self {
+            Self::Single(item) => item.key(),
+            Self::Tools(calls) => calls[0].key(),
+        }
+    }
+
+    pub fn start_seq(&self) -> u64 {
+        match self {
+            Self::Single(item) => item.seq(),
+            Self::Tools(calls) => calls[0].seq(),
+        }
+    }
+}
+
+/// Runs of adjacent tool calls become one row; everything else passes
+/// through. See the Kotlin `groupRuns`'s doc for why grouping is by the
+/// run each call names rather than by adjacency worked out here.
+pub fn group_tool_runs(items: &[TranscriptItem]) -> Vec<TranscriptRow> {
+    let mut rows = Vec::new();
+    let mut run: Vec<TranscriptItem> = Vec::new();
+
+    fn run_id_of(item: &TranscriptItem) -> Option<&str> {
+        match item {
+            TranscriptItem::ToolRun { run_id, .. } => Some(run_id),
+            _ => None,
+        }
+    }
+
+    let flush = |run: &mut Vec<TranscriptItem>, rows: &mut Vec<TranscriptRow>| match run.len() {
+        0 => {}
+        1 => rows.push(TranscriptRow::Single(run.drain(..).next().unwrap())),
+        _ => rows.push(TranscriptRow::Tools(std::mem::take(run))),
+    };
+
+    for item in items {
+        let joins = matches!(item, TranscriptItem::ToolRun { .. })
+            && (run.is_empty() || run_id_of(&run[0]) == run_id_of(item));
+        if joins {
+            run.push(item.clone());
+        } else {
+            flush(&mut run, &mut rows);
+            if matches!(item, TranscriptItem::ToolRun { .. }) {
+                run.push(item.clone());
+            } else {
+                rows.push(TranscriptRow::Single(item.clone()));
+            }
+        }
+    }
+    flush(&mut run, &mut rows);
+    rows
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn event(seq: u64, event: Event) -> SeqEvent {
+        SeqEvent {
+            seq,
+            ts: 1.0,
+            event,
+        }
+    }
+
+    fn fold_all(events: &[SeqEvent]) -> Vec<TranscriptItem> {
+        events
+            .iter()
+            .fold(Vec::new(), |items, e| fold_event(&items, e))
+    }
+
+    #[test]
+    fn assistant_deltas_accumulate_into_one_message() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::AssistantText {
+                    delta: "hel".to_string(),
+                },
+            ),
+            event(
+                2,
+                Event::AssistantText {
+                    delta: "lo".to_string(),
+                },
+            ),
+        ]);
+        assert_eq!(
+            items,
+            vec![TranscriptItem::AssistantMsg {
+                seq: 1,
+                text: "hello".to_string(),
+                settled: false
+            }]
+        );
+    }
+
+    #[test]
+    fn a_status_that_stopped_working_settles_the_newest_reply() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::AssistantText {
+                    delta: "hi".to_string(),
+                },
+            ),
+            event(
+                2,
+                Event::Status {
+                    state: SessionStatus::Idle,
+                },
+            ),
+        ]);
+        assert_eq!(
+            items,
+            vec![TranscriptItem::AssistantMsg {
+                seq: 1,
+                text: "hi".to_string(),
+                settled: true
+            }]
+        );
+    }
+
+    #[test]
+    fn a_working_status_does_not_settle_anything() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::AssistantText {
+                    delta: "hi".to_string(),
+                },
+            ),
+            event(
+                2,
+                Event::Status {
+                    state: SessionStatus::Running,
+                },
+            ),
+        ]);
+        assert_eq!(
+            items,
+            vec![TranscriptItem::AssistantMsg {
+                seq: 1,
+                text: "hi".to_string(),
+                settled: false
+            }]
+        );
+    }
+
+    #[test]
+    fn adjacent_tool_calls_group_and_a_lone_one_does_not() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::ToolStart {
+                    id: "a".to_string(),
+                    tool: "Bash".to_string(),
+                    input: serde_json::json!({}),
+                },
+            ),
+            event(
+                2,
+                Event::ToolStart {
+                    id: "b".to_string(),
+                    tool: "Bash".to_string(),
+                    input: serde_json::json!({}),
+                },
+            ),
+        ]);
+        let rows = group_tool_runs(&items);
+        assert_eq!(rows.len(), 1);
+        assert!(matches!(&rows[0], TranscriptRow::Tools(calls) if calls.len() == 2));
+
+        let solo = fold_all(&[event(
+            1,
+            Event::ToolStart {
+                id: "a".to_string(),
+                tool: "Bash".to_string(),
+                input: serde_json::json!({}),
+            },
+        )]);
+        let rows = group_tool_runs(&solo);
+        assert_eq!(rows.len(), 1);
+        assert!(matches!(
+            &rows[0],
+            TranscriptRow::Single(TranscriptItem::ToolRun { .. })
+        ));
+    }
+
+    #[test]
+    fn a_tool_end_with_no_matching_start_still_draws_a_row() {
+        let items = fold_all(&[event(
+            5,
+            Event::ToolEnd {
+                id: "x".to_string(),
+                output: "done".to_string(),
+            },
+        )]);
+        assert_eq!(
+            items,
+            vec![TranscriptItem::ToolRun {
+                seq: 5,
+                id: "x".to_string(),
+                run_id: "x".to_string(),
+                tool: "tool".to_string(),
+                input: String::new(),
+                output: "done".to_string(),
+                done: true,
+                asks: Vec::new(),
+                images: Vec::new(),
+            }]
+        );
+    }
+
+    #[test]
+    fn a_question_about_a_tool_call_attaches_to_its_row_rather_than_drawing_its_own() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::ToolStart {
+                    id: "a".to_string(),
+                    tool: "Bash".to_string(),
+                    input: serde_json::json!({}),
+                },
+            ),
+            event(
+                2,
+                Event::Question {
+                    id: "q1".to_string(),
+                    prompt: "run it?".to_string(),
+                    header: None,
+                    options: vec![QuestionOption::plain("yes"), QuestionOption::plain("no")],
+                    multi_select: false,
+                    about: Some("a".to_string()),
+                },
+            ),
+        ]);
+        assert_eq!(items.len(), 1);
+        match &items[0] {
+            TranscriptItem::ToolRun { asks, .. } => assert_eq!(asks.len(), 1),
+            other => panic!("expected a ToolRun, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn answering_resolves_a_bare_question_card() {
+        let items = fold_all(&[
+            event(
+                1,
+                Event::Question {
+                    id: "q1".to_string(),
+                    prompt: "pick one".to_string(),
+                    header: None,
+                    options: vec![QuestionOption::plain("a")],
+                    multi_select: false,
+                    about: None,
+                },
+            ),
+            event(
+                2,
+                Event::Answered {
+                    id: "q1".to_string(),
+                    answers: vec!["a".to_string()],
+                },
+            ),
+        ]);
+        match &items[0] {
+            TranscriptItem::QuestionCard(card) => assert_eq!(card.answers, vec!["a".to_string()]),
+            other => panic!("expected a QuestionCard, got {other:?}"),
+        }
+    }
+}

event-model/Cargo.lock

@@ -0,0 +1,107 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "event-model"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

event-model/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "event-model"
+version = "0.1.0"
+edition = "2024"
+
+# The common event model, extracted from `server/session/driver.rs` and
+# `session/transcript.rs` so a Rust client (`client-core`) can share one
+# definition with the server instead of hand-mirroring it the way
+# `app/.../Events.kt` used to. Nothing here talks to a process, a file, or a
+# socket -- it is exactly the wire shape in PLAN.md's "common event model",
+# plus the transcript envelope and the context-token rule three different
+# readers (the pump, the transcript, and a phone folding the same events)
+# have to agree on.
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+# `Event::ToolStart.input` is a tool's raw call arguments, whatever shape the
+# dialect gave them -- typing it further would mean this crate knowing every
+# driver's tool schema.
+serde_json = { version = "1", features = ["float_roundtrip"] }

event-model/src/lib.rs

@@ -0,0 +1,377 @@
+//! The common event model: what a driver's process turns into before it
+//! touches the transcript or the phone (see `PLAN.md`'s "The common event
+//! model"). Extracted from `server/src/session/driver.rs` and
+//! `session/transcript.rs` on 2026-09-04 so `client-core` shares this
+//! definition instead of hand-mirroring it, which is what
+//! `app/.../Events.kt` used to do. `server/`'s `session::driver` module
+//! re-exports everything here, so nothing downstream of it had to change.
+//!
+//! What stayed behind in `server/`: the `Driver` trait, `SessionCommand`,
+//! `Unqueued` and `EventSink`. Those are how *this* server runs a session,
+//! not part of what a client reads off the wire.
+
+use serde::{Deserialize, Serialize};
+
+/// The name a session's image is stored and served under -- minted for an
+/// upload or for one a tool produced, and fetched back from
+/// `/sessions/{id}/files/{ref}`. One id both directions, so the transcript
+/// renders them identically.
+pub type ImageRef = String;
+
+/// The name an upload is stored and served under: an image is
+/// `<hex>.<extension>` and is an [`ImageRef`] like any other; any other file
+/// keeps its own name after the hex, `<hex>-<name>`, because the name is what
+/// the reader attached and what the session is told. Told apart by
+/// `crate::media::media_type_for`.
+pub type AttachmentRef = String;
+
+/// One choice offered in answer to a [`Event::Question`]. More than a label
+/// because the reader is deciding rather than confirming: what an option
+/// means, and what picking it would produce, are what decide it.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QuestionOption {
+    pub label: String,
+    /// A sentence about what this option means.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// A block to show as written -- a mockup, a diff, a config file.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub preview: Option<String>,
+}
+
+impl QuestionOption {
+    pub fn plain(label: impl Into<String>) -> Self {
+        Self {
+            label: label.into(),
+            description: None,
+            preview: None,
+        }
+    }
+}
+
+/// Everything a session can tell the outside world. Every event is appended
+/// to the transcript with a sequence number, then fanned out to SSE
+/// subscribers, so reconnecting is just "events after seq N" -- no separate
+/// history path to drift from the live one.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+// `rename_all` renames the variants; `rename_all_fields` renames what is
+// inside them. Both are needed and only the first is obvious: every field
+// here was one lowercase word until `pre_tokens` arrived, so a multi-word
+// field went out as snake_case, the app looked for camelCase and found
+// nothing, and the event still rendered -- as the "no counts reported" case,
+// which is a state it is allowed to be in.
+#[serde(
+    tag = "type",
+    rename_all = "camelCase",
+    rename_all_fields = "camelCase"
+)]
+pub enum Event {
+    /// What the user sent, written into the transcript by the manager (not by
+    /// drivers) so every device renders the conversation from one stream.
+    /// Recorded when the session reads it, which is what `MessageTaken` reports.
+    UserMessage {
+        /// The [`Event::MessageQueued`] this resolves, when it waited. The
+        /// phone has a bubble on screen for the waiting message and needs to
+        /// know *which* one this is, rather than matching on the text and
+        /// clearing the wrong one when the same thing was sent twice.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        id: Option<String>,
+        text: String,
+        /// What was attached, by the ref the files route serves. On the
+        /// message rather than beside it: these used to be their own `Image`
+        /// events just before, which left the phone deciding from adjacency
+        /// which message an image belonged to. `images` on disk until
+        /// 2026-09-03, when files joined them; the alias reads the older rows.
+        #[serde(default, alias = "images", skip_serializing_if = "Vec::is_empty")]
+        attachments: Vec<AttachmentRef>,
+    },
+    /// A message accepted from the phone that the session cannot read yet.
+    ///
+    /// Recorded, unlike the message itself, and that difference is the point:
+    /// the message belongs in the transcript where the session read it, but
+    /// something has to say it is waiting, and it has to be the server. The
+    /// phone used to remember its own outgoing messages, so leaving the
+    /// screen showed nothing pending when something was.
+    ///
+    /// Carries no row of its own; resolved by the `UserMessage` bearing the
+    /// same id, as `CommandQueued` is resolved by `CommandSent`.
+    MessageQueued {
+        id: String,
+        text: String,
+        /// Carried for the same reason [`Event::UserMessage`] carries it,
+        /// and it matters more here: a waiting message is on screen for as
+        /// long as the turn runs, so its attachment has nowhere else to be.
+        #[serde(default, alias = "images", skip_serializing_if = "Vec::is_empty")]
+        attachments: Vec<AttachmentRef>,
+    },
+    /// A message taken out of the queue before the session read it.
+    ///
+    /// Recorded for the same reason `MessageQueued` is: the queue is the
+    /// server's, so what is waiting has to be answerable from the transcript
+    /// alone. Without it a phone that reconnects replays the `MessageQueued`
+    /// and puts back a bubble nothing will ever resolve -- the `UserMessage`
+    /// that normally does is exactly what is not coming.
+    ///
+    /// Only ever sent for a message that had not been handed over; see
+    /// [`Unqueued::AlreadySent`].
+    MessageDropped {
+        id: String,
+    },
+    /// A driver has taken one of the user's messages and started reading it.
+    /// The manager turns this into the `UserMessage` above, so it never
+    /// reaches a phone itself.
+    ///
+    /// It exists because sending and being read are not the same moment. A
+    /// message sent into a running turn waits, and recording it among things
+    /// already read puts it in the transcript above output that predates it.
+    MessageTaken {
+        /// The `MessageQueued` this answers, or `None` when it never waited.
+        /// Carried through onto the `UserMessage`.
+        id: Option<String>,
+        text: String,
+        #[serde(default, alias = "images", skip_serializing_if = "Vec::is_empty")]
+        attachments: Vec<AttachmentRef>,
+    },
+    /// Streaming assistant text; the phone renders the concatenation as
+    /// markdown.
+    AssistantText {
+        delta: String,
+    },
+    ToolStart {
+        id: String,
+        tool: String,
+        input: serde_json::Value,
+    },
+    ToolUpdate {
+        id: String,
+        output: String,
+    },
+    ToolEnd {
+        id: String,
+        output: String,
+    },
+    /// An image the session produced or was sent, saved under the session
+    /// dir and referenced by id; the phone fetches it by URL.
+    Image {
+        #[serde(rename = "ref")]
+        image: ImageRef,
+        /// The tool call whose result carried it, when one did. A screenshot
+        /// belongs under the call that took it, not floating beside it -- the
+        /// reader has to pair them by position otherwise, and position is
+        /// exactly what a page boundary breaks.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        about: Option<String>,
+    },
+    /// Anything the session needs a human for: AskUserQuestion, and
+    /// permission requests, are the same shape with different options.
+    Question {
+        id: String,
+        prompt: String,
+        /// A few words naming what the question is about, when the asker
+        /// offered one. `None` for a permission, which is about the call
+        /// above it.
+        header: Option<String>,
+        options: Vec<QuestionOption>,
+        /// Whether several options may be chosen at once. Here rather than
+        /// left for a phone to work out from the dialect underneath: how many
+        /// answers a question takes is a fact about the question, and the
+        /// alternative was Claude Code's tool-input schema written out a
+        /// second time in Kotlin, where no other dialect could reach it.
+        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+        multi_select: bool,
+        /// The tool call this is permission for, when it is one, so a phone
+        /// can draw the ask on the tool's own row rather than as a second
+        /// card repeating its input. `None` for anything not about a tool.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        about: Option<String>,
+    },
+    /// A message another agent sent this session.
+    ///
+    /// Its own kind rather than a `UserMessage`, because it is not something
+    /// the reader said and a transcript that renders it in their voice is
+    /// claiming they did. It also explains what would otherwise be
+    /// inexplicable: a session working on something nobody here asked for.
+    PeerMessage {
+        /// The sending session's own name, which is what the reader
+        /// recognises it by -- the socket path it came from is not.
+        from: String,
+        text: String,
+        /// The seq of the `Status::Running` that opened the turn this message
+        /// started, so a reader can draw it above that turn.
+        ///
+        /// The CLI says nothing about a peer message until the turn's
+        /// `result`, so the event is appended after everything it caused, and
+        /// an append-only transcript cannot go back and insert it. Carrying
+        /// the position instead keeps one order on the wire and one on screen.
+        ///
+        /// Filled in by the pump, the only place that knows a seq, and only
+        /// where a turn was open: `None` for a message replayed by `import`,
+        /// which already has it in the right place.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        turn_start: Option<u64>,
+    },
+    /// The manager's record of a question being answered, so a rendered
+    /// question card resolves on every device rather than only the one that
+    /// answered.
+    ///
+    /// A list because a question can take several answers, and one that took
+    /// one is the list of length one rather than a different shape.
+    Answered {
+        id: String,
+        answers: Vec<String>,
+    },
+    Status {
+        state: SessionStatus,
+    },
+    /// What the session is set to, as the session itself reports it.
+    ///
+    /// Asking for a change and having one are different things, and only this
+    /// is a measurement: a model name the dialect does not know, a mode it
+    /// refuses, or a driver whose model is fixed at startup all leave a
+    /// request that was sent and nothing that changed. Reporting from the
+    /// request put the answer on the phone before the question was answered.
+    ///
+    /// Either field alone, because the two are confirmed separately.
+    Settings {
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        model: Option<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        permission_mode: Option<String>,
+    },
+    /// Per-turn token counts, where the dialect reports them.
+    UsageDelta {
+        /// What this turn cost: the tokens it was charged for.
+        tokens: u64,
+        /// What the model was holding when the turn ended -- see
+        /// [`context_tokens`].
+        ///
+        /// Carried rather than summed by whoever is reading, because it is
+        /// not a sum: context goes *down* at a compaction and a clear, so
+        /// adding turns up would report a figure the session stopped being
+        /// true of long ago.
+        ///
+        /// `None` where the dialect did not say, which every reader has to be
+        /// able to draw.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        context: Option<u64>,
+    },
+    /// A compaction that finished, and how much context it recovered.
+    ///
+    /// The counts are the point, and a spinner is not. They are optional
+    /// because the record has shipped without them, and "the compaction
+    /// happened, we don't know by how much" is a state this has to be able to
+    /// say -- a plausible number would be indistinguishable from a counted one.
+    Compacted {
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        pre_tokens: Option<u64>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        post_tokens: Option<u64>,
+        /// What asked for it, in the dialect's own word -- `auto` when the
+        /// session compacted on its own. Carried rather than reduced to a bool
+        /// so an unrecognised trigger stays unrecognised: an automatic
+        /// compaction is the one worth naming, because it explains a wait
+        /// nobody asked for.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        trigger: Option<String>,
+    },
+    /// A command the session was asked to run on itself, held because it
+    /// cannot run yet. These are not messages: `/compact` and `/rename` are
+    /// instructions about the session, and a session mid-turn reads a line
+    /// written to it as something the model should see. So they wait, and
+    /// this is what a phone draws while they do.
+    CommandQueued {
+        id: String,
+        text: String,
+    },
+    /// The same command, now handed to the session. Its [`CommandQueued`]
+    /// stops being pending when this arrives, matched by `id`; a command
+    /// that ran immediately has only this.
+    CommandSent {
+        id: String,
+        text: String,
+    },
+    /// The conversation was cleared: everything above this is still in the
+    /// record but is no longer in the session's context.
+    ///
+    /// Nothing is deleted. A transcript is the thing a person scrolls back
+    /// through, so this is a divider, not a truncation.
+    ///
+    /// **Load-bearing, not decorative.** For any driver that rebuilds its
+    /// conversation from the transcript, this marker decides what the model
+    /// is given -- dropping it, or treating it as something only the phone
+    /// draws, silently puts a cleared conversation back in front of the model
+    /// at full cost. Today `llama::conversation` is the only fold that reads
+    /// it, which is why this is written down rather than left to be inferred
+    /// from a second example that does not exist.
+    Cleared,
+    Error {
+        message: String,
+    },
+}
+
+/// How much the model was holding, from the three figures a turn reports:
+/// the input side only, prompt plus both cache figures. A cached token is
+/// cheaper but it is still one the model was given; output is what the turn
+/// produced rather than what continuing has to carry.
+///
+/// One function so the definition cannot drift, because it is extracted two
+/// quite different ways -- the live translators have the usage object parsed,
+/// and `import::context_tokens` scans it out of a raw line without parsing.
+pub fn context_tokens(input: u64, cache_creation: u64, cache_read: u64) -> u64 {
+    input + cache_creation + cache_read
+}
+
+/// The context after `event`, given what it was before.
+///
+/// The whole rule in one place, because three readers need the same answer:
+/// the pump keeping a live session's figure, the transcript seeding it at
+/// startup, and the phone folding the same events into what it draws.
+///
+/// The two that *lower* it are the point. A clear takes the conversation away
+/// and a compaction replaces it with a summary, so a figure measured before
+/// either stopped being true at that moment -- and carrying it forward is how
+/// a session that had just been cleared went on reporting the context it no
+/// longer had.
+///
+/// `None` is "we don't know", which each of them can reach.
+pub fn context_after(current: Option<u64>, event: &Event) -> Option<u64> {
+    match event {
+        // `or`, so a turn the dialect reported no usage for leaves the last
+        // measurement standing: stale by a turn, which every context figure
+        // is, rather than wrong.
+        Event::UsageDelta { context, .. } => context.or(current),
+        Event::Compacted { post_tokens, .. } => *post_tokens,
+        Event::Cleared => None,
+        _ => current,
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum SessionStatus {
+    Idle,
+    Running,
+    AwaitingInput,
+    Compacting,
+    Exited,
+    /// There is a process recorded for this session and the machine will not
+    /// say whether it is still running.
+    ///
+    /// Its own state rather than the nearest of the others, because both
+    /// neighbours are lies with consequences: `Exited` invites starting a
+    /// second process against a conversation that may already have one, and
+    /// `Idle` claims a session is waiting for you when nobody has checked.
+    Unknown,
+}
+
+/// One transcript line: an [`Event`] plus its position and time. The event
+/// is flattened so the wire shape stays one flat object.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct SeqEvent {
+    pub seq: u64,
+    /// Epoch seconds.
+    pub ts: f64,
+    #[serde(flatten)]
+    pub event: Event,
+}

iris/Cargo.toml

@@ -8,20 +8,79 @@ edition.workspace = true
 [dependencies]
 iris-core = { workspace = true }
 iris-macro = { workspace = true }
-cosmic-text = { workspace = true }
-unicode-segmentation = { workspace = true }
-winit = { workspace = true }
-arboard = { workspace = true, features = ["wayland-data-control"] }
+parley = { workspace = true }
+swash = { workspace = true }
 pollster = { workspace = true }
 wgpu = { workspace = true }
 image = { workspace = true }
+accesskit = { workspace = true }
 tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] }
 
+# winit everywhere except Android; android-view (below) is what stands in
+# for it there. Both backends live in this crate (see `src/android/mod.rs`'s
+# doc comment) but are never compiled together: winit's own Android support
+# pulls in `android-activity`, which panics at compile time unless one of
+# its own backend features is picked, and picking one is exactly what
+# `iris-core` was kept free of (RUST.md's I0b). Confirmed by trying it
+# 2026-09-05: `cargo ndk -t x86_64 -P 26 build -p iris` failed inside
+# `android-activity` itself with "Either game-activity or native-activity
+# must be enabled" before this split existed.
+[target.'cfg(not(target_os = "android"))'.dependencies]
+winit = { workspace = true }
+arboard = { workspace = true, features = ["wayland-data-control"] }
+# I4 (RUST.md): the desktop half of the AccessKit push, `winit`'s own
+# adapter over `accesskit`. No pin needed the way android-view's rev is
+# pinned -- this is an ordinary crates.io release with no local abort to
+# track (that finding is Android-only, see below).
+accesskit_winit = "0.34.0"
+
+# Pinned to the exact commit RUST.md's E1 (2026-09-04) measured on this
+# emulator -- real Vulkan rendering, a working `InputConnection`, and the
+# accesskit-detach abort, all against this rev specifically. Advancing it
+# wants re-running E1's checks, the same reason the nightly toolchain pin
+# is dated rather than floating.
+[target.'cfg(target_os = "android")'.dependencies]
+android-view = { git = "https://github.com/rust-mobile/android-view.git", rev = "bec6c62a96cef8239b0fd7fedeef9b184d02e3a1" }
+# I4 (RUST.md): the Android half of the AccessKit push, over android-view's
+# `AccessibilityNodeProvider`. **0.8.0 carries the same detach-abort E1
+# found on 0.4.0** (the `State` enum still never returns to `Inactive`,
+# and `send_completed_event` still unwraps a Java exception) -- advancing
+# the version is not the fix, so pinning to a specific rev buys nothing
+# here the way it does for android-view itself. `android/view.rs`'s
+# `raise_if_enabled` is the mitigation, carried from E1.
+accesskit_android = "0.8.0"
+# Not re-exported by android-view (only `jni` and `ndk` are), and needed
+# for `android/insets.rs`'s own id -> state map -- the same reason
+# android-view's own `PEER_MAP` carries one.
+send_wrapper = "0.6.0"
+# For diagnostics visible through android_logger, wherever the app crate
+# installs it -- this crate never installs a logger itself.
+log = "0.4.28"
+
 [dev-dependencies]
 tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread", "time"] }
+# The tabs example's widget tree. A dev-dependency cycle back to this
+# package is fine -- cargo excludes dev-dependencies from the graph used
+# to build the library itself, so this only matters for `--examples`.
+tabs-ui = { path = "tabs-ui" }
+
+# Plain Instant-timed binaries, not criterion -- see benches/message_list.rs's
+# header for why. `harness = false` opts out of the unstable `#[bench]`
+# test-crate harness cargo would otherwise want, in favour of an ordinary
+# `fn main()`.
+[[bench]]
+name = "message_list"
+harness = false
 
 [workspace]
-members = ["core", "macro"]
+members = ["core", "macro", "tabs-ui", "transcript-ui", "desktop-app"]
+# android-app pulls in android-view, which needs the NDK sysroot to link
+# -- excluded so `cargo build --workspace --all-targets` on the host stays
+# buildable. Cross-compile it from its own directory (its own single-crate
+# workspace, since it has no `[workspace]` table of its own and this
+# exclusion stops it inheriting this one): `cd android-app && cargo ndk
+# -t x86_64 -P 26 build`.
+exclude = ["android-app"]
 
 [workspace.package]
 version = "0.1.0"
@@ -33,10 +92,16 @@ winit = "0.30.12"
 wgpu = "28.0.0"
 bytemuck = "1.23.1"
 image = "0.25.6"
-cosmic-text = "0.16.0"
-unicode-segmentation = "1.12.0"
+parley = "0.11.1"
+swash = "0.2.10"
 fxhash = "0.2.1"
 arboard = "3.6.1"
+accesskit = "0.25.0"
 iris-core = { path = "core" }
 iris-macro = { path = "macro" }
 tokio = "1.49.0"
+# Current stable as of 2026-09-05 (`cargo search`) -- I5's markdown block
+# model, the same crate E2's uncommitted `e2-transcript` experiment used for
+# the identical job (RUST.md), rather than reimplementing a CommonMark
+# parser.
+pulldown-cmark = "0.13.4"

iris/android-app/.gitignore

@@ -0,0 +1,6 @@
+.gradle/
+build/
+app/build/
+# Rebuilt by `cargo ndk -o app/src/main/jniLibs/ build` before every
+# Gradle build -- see RUST.md's I2 for the exact command.
+app/src/main/jniLibs/

iris/android-app/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "iris-android-app"
+version = "0.1.0"
+edition = "2024"
+
+# Deliberately outside the `iris` workspace (see that Cargo.toml's
+# `[workspace] exclude`): this crate exists only to be cross-compiled with
+# `cargo ndk` for the emulator/a phone, and pulls in android-view, which
+# needs the NDK sysroot to link. Folding it into the main workspace would
+# make `cargo build --workspace --all-targets` -- the host command RUST.md
+# and AGENTS.md both require to stay clean -- try to link a cdylib against
+# libraries that do not exist on this machine. See RUST.md's I2.
+
+[lib]
+name = "main"
+crate-type = ["cdylib"]
+
+[dependencies]
+iris = { path = "../" }
+tabs-ui = { path = "../tabs-ui" }
+android-view = { git = "https://github.com/rust-mobile/android-view.git", rev = "bec6c62a96cef8239b0fd7fedeef9b184d02e3a1" }
+android_logger = "0.15.0"
+log = "0.4.28"
+
+[profile.release]
+panic = "abort"
+
+[profile.dev]
+panic = "abort"

iris/android-app/app/build.gradle

@@ -0,0 +1,31 @@
+plugins {
+    id("com.android.application")
+}
+
+// The Rust side (this directory's Cargo.toml) is built separately with
+// `cargo ndk`, straight into src/main/jniLibs/ -- see the repo-root
+// AGENTS.md-style comment at the top of Cargo.toml for why this crate
+// stays outside the main Rust workspace, and RUST.md's I2 for the exact
+// build command.
+android {
+    namespace = "dev.iris.android.demo"
+    compileSdk = 37
+
+    defaultConfig {
+        applicationId = "dev.iris.android.demo"
+        minSdk = 26
+        targetSdk = 34
+        versionCode = 1
+        versionName = "1.0"
+    }
+
+    buildTypes {
+        debug {
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}

iris/android-app/app/src/main/AndroidManifest.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:allowBackup="true"
+        android:label="iris android-view demo"
+        android:theme="@android:style/Theme.Material.Light.NoActionBar">
+        <activity
+            android:name=".MainActivity"
+            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
+            android:exported="true"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <meta-data android:name="android.app.lib_name" android:value="main" />
+        </activity>
+    </application>
+
+</manifest>

iris/android-app/app/src/main/java/dev/iris/android/demo/IrisView.java

@@ -0,0 +1,36 @@
+package dev.iris.android.demo;
+
+import android.content.Context;
+
+import org.linebender.android.rustview.RustView;
+
+/**
+ * android-view's abstract base plus the two native methods it has no hook
+ * for: window insets and unregistering this view's entry in
+ * iris::android::insets's side table. See iris/src/android/insets.rs's doc
+ * comment for why those could not ride along on an existing android-view
+ * callback the way the back gesture does.
+ */
+public final class IrisView extends RustView {
+    @Override
+    protected native long newViewPeer(Context context);
+
+    native void applyWindowInsetsNative(
+            long peer, int left, int top, int right, int bottom, int imeBottom);
+
+    native void unregisterInsetsNative(long peer);
+
+    public IrisView(Context context) {
+        super(context);
+    }
+
+    void applyWindowInsets(int left, int top, int right, int bottom, int imeBottom) {
+        applyWindowInsetsNative(mViewPeer, left, top, right, bottom, imeBottom);
+    }
+
+    @Override
+    protected void onDetachedFromWindow() {
+        unregisterInsetsNative(mViewPeer);
+        super.onDetachedFromWindow();
+    }
+}

iris/android-app/app/src/main/java/dev/iris/android/demo/MainActivity.java

@@ -0,0 +1,47 @@
+package dev.iris.android.demo;
+
+import android.app.Activity;
+import android.os.Build;
+import android.os.Bundle;
+import android.view.WindowInsets;
+import android.widget.FrameLayout;
+
+/**
+ * The android-view backend's demo activity (RUST.md's I2): one IrisView
+ * filling the window, running iris's tabs example through
+ * iris-android-app's Rust side. Mirrors android-view's own
+ * DemoActivity, plus the window-insets wiring that has no android-view
+ * counterpart.
+ */
+public final class MainActivity extends Activity {
+    static {
+        System.loadLibrary("main");
+    }
+
+    @Override
+    public void onCreate(Bundle state) {
+        super.onCreate(state);
+        IrisView view = new IrisView(this);
+        view.setLayoutParams(new FrameLayout.LayoutParams(
+                FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT));
+        view.setFocusable(true);
+        view.setFocusableInTouchMode(true);
+        FrameLayout layout = new FrameLayout(this);
+        layout.addView(view);
+        setContentView(layout);
+        view.requestFocus();
+
+        view.setOnApplyWindowInsetsListener((v, insets) -> {
+            int left = insets.getSystemWindowInsetLeft();
+            int top = insets.getSystemWindowInsetTop();
+            int right = insets.getSystemWindowInsetRight();
+            int bottom = insets.getSystemWindowInsetBottom();
+            int imeBottom = 0;
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                imeBottom = insets.getInsets(WindowInsets.Type.ime()).bottom;
+            }
+            ((IrisView) v).applyWindowInsets(left, top, right, bottom, imeBottom);
+            return insets;
+        });
+    }
+}

iris/android-app/app/src/main/java/org/linebender/android/rustview/RustInputConnection.java

@@ -0,0 +1,153 @@
+package org.linebender.android.rustview;
+
+import android.os.Bundle;
+import android.os.Handler;
+import android.view.KeyEvent;
+import android.view.inputmethod.CompletionInfo;
+import android.view.inputmethod.CorrectionInfo;
+import android.view.inputmethod.ExtractedText;
+import android.view.inputmethod.ExtractedTextRequest;
+import android.view.inputmethod.InputConnection;
+import android.view.inputmethod.InputContentInfo;
+
+class RustInputConnection implements InputConnection {
+    private final RustView mView;
+
+    RustInputConnection(RustView view) {
+        mView = view;
+    }
+
+    private long getViewPeer() {
+        return mView.mViewPeer;
+    }
+
+    @Override
+    public CharSequence getTextBeforeCursor(int n, int flags) {
+        return mView.getTextBeforeCursorNative(getViewPeer(), n);
+    }
+
+    @Override
+    public CharSequence getTextAfterCursor(int n, int flags) {
+        return mView.getTextAfterCursorNative(getViewPeer(), n);
+    }
+
+    @Override
+    public CharSequence getSelectedText(int flags) {
+        return mView.getSelectedTextNative(getViewPeer());
+    }
+
+    @Override
+    public int getCursorCapsMode(int reqModes) {
+        return mView.getCursorCapsModeNative(getViewPeer(), reqModes);
+    }
+
+    @Override
+    public ExtractedText getExtractedText(ExtractedTextRequest request, int flags) {
+        return null;
+    }
+
+    @Override
+    public boolean deleteSurroundingText(int beforeLength, int afterLength) {
+        return mView.deleteSurroundingTextNative(getViewPeer(), beforeLength, afterLength);
+    }
+
+    @Override
+    public boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength) {
+        return mView.deleteSurroundingTextInCodePointsNative(getViewPeer(), beforeLength, afterLength);
+    }
+
+    @Override
+    public boolean setComposingText(CharSequence text, int newCursorPosition) {
+        return mView.setComposingTextNative(getViewPeer(), text.toString(), newCursorPosition);
+    }
+
+    @Override
+    public boolean setComposingRegion(int start, int end) {
+        return mView.setComposingRegionNative(getViewPeer(), start, end);
+    }
+
+    @Override
+    public boolean finishComposingText() {
+        return mView.finishComposingTextNative(getViewPeer());
+    }
+
+    @Override
+    public boolean commitText(CharSequence text, int newCursorPosition) {
+        return mView.commitTextNative(getViewPeer(), text.toString(), newCursorPosition);
+    }
+
+    @Override
+    public boolean commitCompletion(CompletionInfo text) {
+        return false;
+    }
+
+    @Override
+    public boolean commitCorrection(CorrectionInfo correctionInfo) {
+        return false;
+    }
+
+    @Override
+    public boolean setSelection(int start, int end) {
+        return mView.setSelectionNative(getViewPeer(), start, end);
+    }
+
+    @Override
+    public boolean performEditorAction(int editorAction) {
+        return mView.performEditorActionNative(getViewPeer(), editorAction);
+    }
+
+    @Override
+    public boolean performContextMenuAction(int id) {
+        return mView.performContextMenuActionNative(getViewPeer(), id);
+    }
+
+    @Override
+    public boolean beginBatchEdit() {
+        return mView.beginBatchEditNative(getViewPeer());
+    }
+
+    @Override
+    public boolean endBatchEdit() {
+        return mView.endBatchEditNative(getViewPeer());
+    }
+
+    @Override
+    public boolean sendKeyEvent(KeyEvent event) {
+        return mView.inputConnectionSendKeyEventNative(getViewPeer(), event);
+    }
+
+    @Override
+    public boolean clearMetaKeyStates(int states) {
+        return mView.inputConnectionClearMetaKeyStatesNative(getViewPeer(), states);
+    }
+
+    @Override
+    public boolean reportFullscreenMode(boolean enabled) {
+        return mView.inputConnectionReportFullscreenModeNative(getViewPeer(), enabled);
+    }
+
+    @Override
+    public boolean performPrivateCommand(String action, Bundle data) {
+        return false;
+    }
+
+    @Override
+    public boolean requestCursorUpdates(int cursorUpdateMode) {
+        return mView.requestCursorUpdatesNative(getViewPeer(), cursorUpdateMode);
+    }
+
+    @Override
+    public Handler getHandler() {
+        return null;
+    }
+
+    @Override
+    public void closeConnection() {
+        mView.closeInputConnectionNative(getViewPeer());
+    }
+
+    @Override
+    public boolean commitContent(InputContentInfo inputContentInfo, int flags, Bundle opts) {
+        return false;
+    }
+}

iris/android-app/app/src/main/java/org/linebender/android/rustview/RustView.java

@@ -0,0 +1,291 @@
+package org.linebender.android.rustview;
+
+import android.content.Context;
+import android.graphics.Rect;
+import android.os.Bundle;
+import android.view.Choreographer;
+import android.view.KeyEvent;
+import android.view.MotionEvent;
+import android.view.SurfaceHolder;
+import android.view.SurfaceView;
+import android.view.accessibility.AccessibilityNodeInfo;
+import android.view.accessibility.AccessibilityNodeProvider;
+import android.view.inputmethod.EditorInfo;
+import android.view.inputmethod.InputConnection;
+import android.view.inputmethod.InputMethodManager;
+
+public abstract class RustView extends SurfaceView
+        implements SurfaceHolder.Callback, Choreographer.FrameCallback {
+    // Vendored from android-view (bec6c62, https://github.com/rust-mobile/android-view)
+    // with one deliberate change: `protected` rather than package-private, so a
+    // subclass in a different package (dev.iris.android.demo.IrisView) can pass
+    // it to the window-insets native call android-view itself has no hook for --
+    // see iris/src/android/insets.rs's doc comment for why that call exists at
+    // all. No other line differs from upstream.
+    protected final long mViewPeer;
+    final InputMethodManager mInputMethodManager;
+
+    protected abstract long newViewPeer(Context context);
+
+    public RustView(Context context) {
+        super(context);
+        mViewPeer = newViewPeer(context);
+        getHolder().addCallback(this);
+        mInputMethodManager =
+                (InputMethodManager) context.getSystemService(Context.INPUT_METHOD_SERVICE);
+    }
+
+    private native int[] onMeasureNative(long peer, int widthSpec, int heightSpec);
+
+    @Override
+    protected void onMeasure(int widthSpec, int heightSpec) {
+        int[] result = onMeasureNative(mViewPeer, widthSpec, heightSpec);
+        if (result != null) {
+            setMeasuredDimension(result[0], result[1]);
+        } else {
+            super.onMeasure(widthSpec, heightSpec);
+        }
+    }
+
+    private native void onLayoutNative(
+            long peer, boolean changed, int left, int top, int right, int bottom);
+
+    @Override
+    protected void onLayout(boolean changed, int left, int top, int right, int bottom) {
+        onLayoutNative(mViewPeer, changed, left, top, right, bottom);
+        super.onLayout(changed, left, top, right, bottom);
+    }
+
+    private native void onSizeChangedNative(long peer, int w, int h, int oldw, int oldh);
+
+    @Override
+    protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+        onSizeChangedNative(mViewPeer, w, h, oldw, oldh);
+        super.onSizeChanged(w, h, oldw, oldh);
+    }
+
+    private native boolean onKeyDownNative(long peer, int keyCode, KeyEvent event);
+
+    @Override
+    public boolean onKeyDown(int keyCode, KeyEvent event) {
+        return onKeyDownNative(mViewPeer, keyCode, event) || super.onKeyDown(keyCode, event);
+    }
+
+    private native boolean onKeyUpNative(long peer, int keyCode, KeyEvent event);
+
+    @Override
+    public boolean onKeyUp(int keyCode, KeyEvent event) {
+        return onKeyUpNative(mViewPeer, keyCode, event) || super.onKeyUp(keyCode, event);
+    }
+
+    private native boolean onTrackballEventNative(long peer, MotionEvent event);
+
+    @Override
+    public boolean onTrackballEvent(MotionEvent event) {
+        return onTrackballEventNative(mViewPeer, event) || super.onTrackballEvent(event);
+    }
+
+    private native boolean onTouchEventNative(long peer, MotionEvent event);
+
+    @Override
+    public boolean onTouchEvent(MotionEvent event) {
+        return onTouchEventNative(mViewPeer, event) || super.onTouchEvent(event);
+    }
+
+    private native boolean onGenericMotionEventNative(long peer, MotionEvent event);
+
+    @Override
+    public boolean onGenericMotionEvent(MotionEvent event) {
+        return onGenericMotionEventNative(mViewPeer, event) || super.onGenericMotionEvent(event);
+    }
+
+    private native boolean onHoverEventNative(long peer, MotionEvent event);
+
+    @Override
+    public boolean onHoverEvent(MotionEvent event) {
+        return onHoverEventNative(mViewPeer, event) || super.onHoverEvent(event);
+    }
+
+    private native void onFocusChangedNative(
+            long peer, boolean gainFocus, int direction, Rect previouslyFocusedRect);
+
+    @Override
+    protected void onFocusChanged(boolean gainFocus, int direction, Rect previouslyFocusedRect) {
+        super.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
+        onFocusChangedNative(mViewPeer, gainFocus, direction, previouslyFocusedRect);
+    }
+
+    private native void onWindowFocusChangedNative(long peer, boolean hasWindowFocus);
+
+    @Override
+    public void onWindowFocusChanged(boolean hasWindowFocus) {
+        super.onWindowFocusChanged(hasWindowFocus);
+        onWindowFocusChangedNative(mViewPeer, hasWindowFocus);
+    }
+
+    private native void onAttachedToWindowNative(long peer);
+
+    @Override
+    protected void onAttachedToWindow() {
+        super.onAttachedToWindow();
+        onAttachedToWindowNative(mViewPeer);
+    }
+
+    private native void onDetachedFromWindowNative(long peer);
+
+    @Override
+    protected void onDetachedFromWindow() {
+        super.onDetachedFromWindow();
+        onDetachedFromWindowNative(mViewPeer);
+    }
+
+    private native void onWindowVisibilityChangedNative(long peer, int visibility);
+
+    @Override
+    protected void onWindowVisibilityChanged(int visibility) {
+        super.onWindowVisibilityChanged(visibility);
+        onWindowVisibilityChangedNative(mViewPeer, visibility);
+    }
+
+    private native void surfaceCreatedNative(long peer, SurfaceHolder holder);
+
+    @Override
+    public void surfaceCreated(SurfaceHolder holder) {
+        surfaceCreatedNative(mViewPeer, holder);
+    }
+
+    private native void surfaceChangedNative(
+            long peer, SurfaceHolder holder, int format, int width, int height);
+
+    @Override
+    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
+        surfaceChangedNative(mViewPeer, holder, format, width, height);
+    }
+
+    private native void surfaceDestroyedNative(long peer, SurfaceHolder holder);
+
+    @Override
+    public void surfaceDestroyed(SurfaceHolder holder) {
+        surfaceDestroyedNative(mViewPeer, holder);
+    }
+
+    void postFrameCallback() {
+        Choreographer c = Choreographer.getInstance();
+        c.removeFrameCallback(this);
+        c.postFrameCallback(this);
+    }
+
+    void removeFrameCallback() {
+        Choreographer.getInstance().removeFrameCallback(this);
+    }
+
+    private native void doFrameNative(long peer, long frameTimeNanos);
+
+    @Override
+    public void doFrame(long frameTimeNanos) {
+        doFrameNative(mViewPeer, frameTimeNanos);
+    }
+
+    private native void delayedCallbackNative(long peer);
+
+    private final Runnable mDelayedCallback =
+            new Runnable() {
+                @Override
+                public void run() {
+                    delayedCallbackNative(mViewPeer);
+                }
+            };
+
+    boolean postDelayed(long delayMillis) {
+        return postDelayed(mDelayedCallback, delayMillis);
+    }
+
+    boolean removeDelayedCallbacks() {
+        return removeCallbacks(mDelayedCallback);
+    }
+
+    private native boolean hasAccessibilityNodeProviderNative(long peer);
+
+    private native AccessibilityNodeInfo createAccessibilityNodeInfoNative(
+            long peer, int virtualViewId);
+
+    private native AccessibilityNodeInfo accessibilityFindFocusNative(long peer, int virtualViewId);
+
+    private native boolean performAccessibilityActionNative(
+            long peer, int virtualViewId, int action, Bundle arguments);
+
+    @Override
+    public AccessibilityNodeProvider getAccessibilityNodeProvider() {
+        if (!hasAccessibilityNodeProviderNative(mViewPeer)) {
+            return super.getAccessibilityNodeProvider();
+        }
+        return new AccessibilityNodeProvider() {
+            @Override
+            public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualViewId) {
+                return createAccessibilityNodeInfoNative(mViewPeer, virtualViewId);
+            }
+
+            @Override
+            public AccessibilityNodeInfo findFocus(int focusType) {
+                return accessibilityFindFocusNative(mViewPeer, focusType);
+            }
+
+            @Override
+            public boolean performAction(int virtualViewId, int action, Bundle arguments) {
+                return performAccessibilityActionNative(
+                        mViewPeer, virtualViewId, action, arguments);
+            }
+        };
+    }
+
+    private native boolean onCreateInputConnectionNative(long peer, EditorInfo outAttrs);
+
+    @Override
+    public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
+        if (!onCreateInputConnectionNative(mViewPeer, outAttrs)) {
+            return null;
+        }
+        return new RustInputConnection(this);
+    }
+
+    native String getTextBeforeCursorNative(long peer, int n);
+
+    native String getTextAfterCursorNative(long peer, int n);
+
+    native String getSelectedTextNative(long peer);
+
+    native int getCursorCapsModeNative(long peer, int reqModes);
+
+    native boolean deleteSurroundingTextNative(long peer, int beforeLength, int afterLength);
+
+    native boolean deleteSurroundingTextInCodePointsNative(
+            long peer, int beforeLength, int afterLength);
+
+    native boolean setComposingTextNative(long peer, String text, int newCursorPosition);
+
+    native boolean setComposingRegionNative(long peer, int start, int end);
+
+    native boolean finishComposingTextNative(long peer);
+
+    native boolean commitTextNative(long peer, String text, int newCursorPosition);
+
+    native boolean setSelectionNative(long peer, int start, int end);
+
+    native boolean performEditorActionNative(long peer, int editorAction);
+
+    native boolean performContextMenuActionNative(long peer, int id);
+
+    native boolean beginBatchEditNative(long peer);
+
+    native boolean endBatchEditNative(long peer);
+
+    native boolean inputConnectionSendKeyEventNative(long peer, KeyEvent event);
+
+    native boolean inputConnectionClearMetaKeyStatesNative(long peer, int states);
+
+    native boolean inputConnectionReportFullscreenModeNative(long peer, boolean enabled);
+
+    native boolean requestCursorUpdatesNative(long peer, int cursorUpdateMode);
+
+    native void closeInputConnectionNative(long peer);
+}

iris/android-app/build.gradle

@@ -0,0 +1,3 @@
+plugins {
+    id("com.android.application") version "9.4.0" apply false
+}

iris/android-app/settings.gradle

@@ -0,0 +1,15 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+rootProject.name = "iris-android-demo"
+include(":app")

iris/android-app/src/lib.rs

@@ -0,0 +1,87 @@
+//! The android-view demo app: iris's `tabs` widget tree (`tabs_ui::build`,
+//! shared with the winit example) running through
+//! `iris::android`'s `ViewPeer`. This is RUST.md's I2 pass condition made
+//! concrete -- there is no UI here beyond what `tabs-ui` already draws.
+//!
+//! `JNI_OnLoad` and `new_view_peer` mirror android-view's own demo
+//! (`~/src/android-view/demo/src/lib.rs`): the only android-view-specific
+//! plumbing a real app needs is registering its `View` subclass and
+//! wrapping `iris::android::new_peer`'s generic function in a concrete
+//! `extern "system" fn`, since `register_view_class` wants a plain
+//! function pointer.
+
+use android_view::{
+    Context, View,
+    jni::{
+        JNIEnv, JavaVM,
+        sys::{JNI_VERSION_1_6, JavaVM as RawJavaVM, jint, jlong},
+    },
+    register_view_class,
+};
+use iris::android::{AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState};
+use iris::prelude::*;
+use log::LevelFilter;
+use std::ffi::c_void;
+
+/// The app's `View` subclass, matching the Java side's package --
+/// `app/src/main/java/dev/iris/android/demo/IrisView.java`.
+const VIEW_CLASS: &str = "dev/iris/android/demo/IrisView";
+
+pub struct Client {
+    ui_state: AndroidUiState,
+}
+
+impl HasAndroidUiState for Client {
+    fn android_state(&self) -> &AndroidUiState {
+        &self.ui_state
+    }
+    fn android_state_mut(&mut self) -> &mut AndroidUiState {
+        &mut self.ui_state
+    }
+}
+
+impl AndroidAppState for Client {
+    fn new(mut ui_state: AndroidUiState, rsc: &mut AndroidRsc<Self>) -> Self {
+        // `widgets.info` is the winit example's frame-debug readout, kept
+        // current from `DefaultAppState::window_event` -- android-view has
+        // no per-frame hook to drive the equivalent from here yet, so it
+        // is left at its built "" text rather than wired to nothing.
+        let _ = tabs_ui::build(rsc, &mut ui_state);
+        Self { ui_state }
+    }
+
+    fn back_pressed(&mut self, _rsc: &mut AndroidRsc<Self>, _render: &mut UiRenderState) -> bool {
+        // Nothing in the tabs example has a back stack of its own to pop --
+        // declining lets the activity finish, which is the same "no
+        // handler" behaviour the default impl gives. Present as an
+        // explicit override (rather than relying on the default) so a
+        // reader checking "does the back gesture reach this app" finds an
+        // answer here rather than nothing.
+        false
+    }
+}
+
+extern "system" fn new_view_peer<'local>(
+    env: JNIEnv<'local>,
+    view: View<'local>,
+    context: Context<'local>,
+) -> jlong {
+    iris::android::new_peer::<Client>(env, view, context)
+}
+
+/// # Safety
+/// Interacting with JNI at load time is always unsafe at some level --
+/// mirrors android-view's own demo, which carries the same comment.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn JNI_OnLoad(vm: *mut RawJavaVM, _: *mut c_void) -> jint {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(LevelFilter::Debug)
+            .with_tag("iris-android-app"),
+    );
+    let vm = unsafe { JavaVM::from_raw(vm) }.unwrap();
+    let mut env = vm.get_env().unwrap();
+    register_view_class(&mut env, VIEW_CLASS, new_view_peer);
+    iris::android::register_native_methods(&mut env, VIEW_CLASS);
+    JNI_VERSION_1_6
+}

iris/benches/message_list.rs

@@ -0,0 +1,425 @@
+//! On-demand benchmarks for iris's message-list scenario -- IRIS_TODO.md's
+//! "Benchmarks" item, and RUST.md's I3. Never run by `cargo test`; run
+//! explicitly with `cargo bench --bench message_list --release` or
+//! `./run-bench.sh`.
+//!
+//! **Why a plain `Instant`-timed binary, not criterion.** Every scenario
+//! here is really "how many `Widget::draw` calls and primitive rewrites did
+//! this frame cost," which `UiRenderState::take_counters` already answers
+//! exactly (see `iris/src/layout_tests.rs`, which this file's harness
+//! mirrors). A short loop that times itself and prints the counters
+//! alongside the wall time says everything criterion's warm-up/sampling/
+//! outlier-removal machinery would add on top, for scenarios that are
+//! fundamentally about a *count*, not a noisy microbenchmark distribution
+//! -- and it avoids a new dependency this crate does not otherwise need.
+//! Per the code rules, the plain option is also the one shorter to explain.
+//!
+//! **The list under test is `iris::widget::List` (RUST.md's I3), not a
+//! `Scroll` over a `Span` of pre-built rows.** Earlier versions of this
+//! file built their own giant `Span` and wrapped it in `Scroll`, which
+//! meant (a)/(b)/(c) below were measuring "move one big child," never the
+//! virtualised widget the app's transcript screen actually needs. `List`
+//! still needs every row's *widget* built up front by the caller (its
+//! module doc explains why: it only ever sees `&dyn Widget` through
+//! `Painter`, so it cannot construct a row lazily on its own) -- what
+//! virtualisation buys is that only the rows currently on screen are ever
+//! *drawn*, which is what the draw/rewrite/move counters below are
+//! measuring, not construction time.
+//!
+//! Scenarios (LAYOUT.md's O(1) move chain, list.rs's module doc, and
+//! IRIS_TODO.md's "Benchmarks" wording):
+//!
+//! - (a) first-frame cost of a message list of N wrapped-text rows, some
+//!   with an image, for N = 100 / 1,000 / 10,000. With a virtualised list
+//!   this is expected to stop scaling with N once N exceeds a screenful --
+//!   the draw/rewrite counters below are the number that used to grow 10x
+//!   per 10x N and should not any more.
+//! - (b) per-frame cost of scrolling that list -- must be O(1) moves, not
+//!   re-layout.
+//! - (c) the input-box case: growing a fixed-height field at the bottom of
+//!   the screen must move the message list above it, not re-lay its rows.
+//!   Reports frame time *and* the draw/rewrite/move counters LAYOUT.md
+//!   section 8 defines.
+//! - (d) insert-above-anchor: paging older history onto the front of an
+//!   already-scrolled list. `List::push_front` is an O(1) index update
+//!   (list.rs's module doc); this measures that none of the rows already
+//!   on screen are touched by it.
+//! - (e) expand-a-row-holding-its-edge: growing one row's height with a
+//!   tap recorded near one of its edges (list.rs's `note_tap`) must move
+//!   only the rows on the far side of it, never redraw the ones already
+//!   correctly placed.
+//!
+//! (f), many images with zero steady-state bind-group creation, needs a
+//! real `wgpu` device and lives in `iris/examples/bench_images.rs` instead,
+//! driven through `run-headless.sh` -- see that file's header.
+//!
+//! `UiRenderState`/`Widgets` touch no GPU or window (as `layout_tests.rs`
+//! notes), so everything here runs as an ordinary `--release` binary with
+//! no compositor. Numbers are recorded in RUST.md's I3 box, not here --
+//! this file is the rig, not the result.
+
+use iris::prelude::*;
+use std::time::Instant;
+
+/// The minimal `UiRsc` a benchmark needs -- identical in shape to
+/// `layout_tests.rs`'s `TestRsc`.
+struct BenchRsc {
+    ui: UiData,
+}
+
+impl UiRsc for BenchRsc {
+    fn ui(&self) -> &UiData {
+        &self.ui
+    }
+    fn ui_mut(&mut self) -> &mut UiData {
+        &mut self.ui
+    }
+}
+
+/// Long enough to force real wrapping at a phone-plausible column width, and
+/// varied enough (no two rows byte-identical) that nothing can special-case
+/// on repeated content.
+const BODY: &str = "The quick brown fox jumps over the lazy dog. Iris lays \
+out wrapped text by shaping once per width and caching the result, so a \
+row that is offered the same width twice does not reshape. This sentence \
+exists only to give a row enough text to wrap across several lines at a \
+typical phone column width.";
+
+/// One message row: a wrapped `Text`, and every `image_every`th row also an
+/// `Image` beneath it -- a small in-memory RGBA square rather than a file,
+/// so N=10,000 rows costs no disk I/O.
+fn build_row(rsc: &mut BenchRsc, i: usize, image_every: usize) -> StrongWidget {
+    let mut text = Text::new(format!("Message {i}: {BODY}"));
+    text.wrap = true;
+    let text = rsc.ui.widgets.add_strong(text).any();
+
+    if image_every > 0 && i.is_multiple_of(image_every) {
+        let img = image::DynamicImage::new_rgba8(64, 64);
+        let image_widget = image::<BenchRsc>(img)(rsc);
+        let image_widget = rsc.ui.widgets.add_strong(image_widget).any();
+        let mut row = Span::empty(Dir::DOWN);
+        row.push(text);
+        row.push(image_widget);
+        rsc.ui.widgets.add_strong(row).any()
+    } else {
+        text
+    }
+}
+
+/// A virtualised `List` of `n` message rows, one in `image_every` of them
+/// carrying an image (0 disables images entirely). Returns the list widget
+/// (weak, so the caller can drive it) and the erased root to render.
+fn build_message_list(
+    rsc: &mut BenchRsc,
+    n: usize,
+    image_every: usize,
+) -> (WeakWidget<List>, StrongWidget) {
+    let mut list = List::new(Axis::Y);
+    for i in 0..n {
+        let row = build_row(rsc, i, image_every);
+        list.push_back(ListRow::new(i as u64, row));
+    }
+    let list = rsc.ui.widgets.add_strong(list);
+    (list.weak(), list.any())
+}
+
+fn report(label: &str, elapsed: std::time::Duration, draws: u64, rewrites: u64, moves: u64) {
+    println!(
+        "{label}: {:.2}ms  draws={draws} rewrites={rewrites} moves={moves}",
+        elapsed.as_secs_f64() * 1000.0
+    );
+}
+
+/// (a) First-frame cost of a message list of N rows.
+fn bench_first_frame(n: usize) {
+    let mut rsc = BenchRsc {
+        ui: UiData::default(),
+    };
+    let (_list, root) = build_message_list(&mut rsc, n, 20);
+    let mut render = UiRenderState::new();
+    render.resize((1080.0, 2000.0));
+
+    let start = Instant::now();
+    render.update(&root, &mut rsc);
+    let elapsed = start.elapsed();
+    let (draws, rewrites, moves) = render.take_counters();
+    report(
+        &format!("(a) first frame, N={n}"),
+        elapsed,
+        draws,
+        rewrites,
+        moves,
+    );
+}
+
+/// (b) Per-frame cost of scrolling an already-laid-out list of N rows.
+/// Warms up (one no-op tick, matching `Scroll`'s own need for it before an
+/// ordinary Rust `layout_tests.rs` scrolling test becomes a same-size move
+/// rather than a resize), then times a run of individual scroll ticks.
+fn bench_scroll(n: usize, ticks: usize) {
+    let mut rsc = BenchRsc {
+        ui: UiData::default(),
+    };
+    let (list, root) = build_message_list(&mut rsc, n, 20);
+    let mut render = UiRenderState::new();
+    render.resize((1080.0, 2000.0));
+    render.update(&root, &mut rsc);
+    rsc.ui.widgets.get_mut(&list).unwrap().scroll(0.0);
+    render.update(&root, &mut rsc);
+    render.take_counters();
+
+    let mut total = std::time::Duration::ZERO;
+    let mut total_draws = 0u64;
+    let mut total_rewrites = 0u64;
+    let mut total_moves = 0u64;
+    for _ in 0..ticks {
+        rsc.ui.widgets.get_mut(&list).unwrap().scroll(-8.0);
+        let start = Instant::now();
+        render.update(&root, &mut rsc);
+        total += start.elapsed();
+        let (draws, rewrites, moves) = render.take_counters();
+        total_draws += draws;
+        total_rewrites += rewrites;
+        total_moves += moves;
+    }
+    report(
+        &format!("(b) scroll, N={n}, {ticks} ticks (totals; expect draws/moves independent of N)"),
+        total,
+        total_draws,
+        total_rewrites,
+        total_moves,
+    );
+    println!(
+        "    per-tick average: {:.4}ms",
+        total.as_secs_f64() * 1000.0 / ticks as f64
+    );
+}
+
+/// (c) The input-box case: a fixed-height field at the bottom of the screen
+/// growing by a line at a time, with a message list of N rows filling the
+/// rest of the screen above it. Growing the input shrinks the *offered*
+/// height of the list container (a single widget, from the outer `Span`'s
+/// point of view) without changing the width it offers its content -- so
+/// the rows underneath, which only care about width, must not redraw; the
+/// list's own re-registration of where its content sits is the one O(1)
+/// move this is checking for.
+fn bench_input_grows(n: usize, lines: usize) {
+    let mut rsc = BenchRsc {
+        ui: UiData::default(),
+    };
+    let (list, list_root) = build_message_list(&mut rsc, n, 20);
+    let list_area = rsc.ui.widgets.add_strong(Sized {
+        inner: list_root,
+        x: None,
+        y: Some(rest(1.0)),
+    });
+
+    let line_height = 24.0;
+    let input_rect = rsc.ui.widgets.add_strong(Rect::new(UiColor::WHITE));
+    let input_area = rsc.ui.widgets.add_strong(Sized {
+        inner: input_rect.any(),
+        x: None,
+        y: Some(abs(line_height)),
+    });
+
+    let input_area_weak = input_area.weak();
+    let mut root_span = Span::empty(Dir::DOWN);
+    root_span.push(list_area.any());
+    root_span.push(input_area.any());
+    let root = rsc.ui.widgets.add_strong(root_span).any();
+
+    let mut render = UiRenderState::new();
+    render.resize((1080.0, 2000.0));
+    render.update(&root, &mut rsc);
+    rsc.ui.widgets.get_mut(&list).unwrap().scroll(0.0);
+    render.update(&root, &mut rsc);
+    render.take_counters();
+
+    let mut total = std::time::Duration::ZERO;
+    let mut total_draws = 0u64;
+    let mut total_rewrites = 0u64;
+    let mut total_moves = 0u64;
+    for line in 1..=lines {
+        rsc.ui.widgets.get_mut(&input_area_weak).unwrap().y =
+            Some(abs(line_height * (line + 1) as f32));
+        let start = Instant::now();
+        render.update(&root, &mut rsc);
+        total += start.elapsed();
+        let (draws, rewrites, moves) = render.take_counters();
+        total_draws += draws;
+        total_rewrites += rewrites;
+        total_moves += moves;
+    }
+    report(
+        &format!(
+            "(c) input grows by {lines} lines above N={n} rows (totals; \
+             draws/rewrites must not scale with N)"
+        ),
+        total,
+        total_draws,
+        total_rewrites,
+        total_moves,
+    );
+    println!(
+        "    per-line average: {:.4}ms",
+        total.as_secs_f64() * 1000.0 / lines as f64
+    );
+}
+
+/// (d) Insert-above-anchor: the list is scrolled to its very first loaded
+/// row (`jump_to_start`, an O(1) re-anchor) rather than left at the default
+/// bottom, so a row prepended above it is genuinely "inserted above the
+/// anchor" rather than merely far off-screen at the far end. Each
+/// `push_front` is O(1) (list.rs's module doc: the anchor's slot is an
+/// index, bumped by one) and, since the prepended rows never enter the
+/// viewport, none of them should cost a draw either.
+fn bench_insert_above_anchor(n: usize, inserts: usize) {
+    let mut rsc = BenchRsc {
+        ui: UiData::default(),
+    };
+    let (list, root) = build_message_list(&mut rsc, n, 20);
+    let mut render = UiRenderState::new();
+    render.resize((1080.0, 2000.0));
+    render.update(&root, &mut rsc);
+    rsc.ui.widgets.get_mut(&list).unwrap().jump_to_start();
+    render.update(&root, &mut rsc);
+    render.take_counters();
+
+    let mut total = std::time::Duration::ZERO;
+    let mut total_draws = 0u64;
+    let mut total_rewrites = 0u64;
+    let mut total_moves = 0u64;
+    for i in 0..inserts {
+        // Older-history rows: distinct keys below every existing one, so a
+        // real caller's paging code (prepending an older page) is exactly
+        // what this loop does.
+        let row = build_row(&mut rsc, usize::MAX - i, 20);
+        rsc.ui
+            .widgets
+            .get_mut(&list)
+            .unwrap()
+            .push_front(ListRow::new(i as u64, row));
+        let start = Instant::now();
+        render.update(&root, &mut rsc);
+        total += start.elapsed();
+        let (draws, rewrites, moves) = render.take_counters();
+        total_draws += draws;
+        total_rewrites += rewrites;
+        total_moves += moves;
+    }
+    report(
+        &format!(
+            "(d) insert-above-anchor, N={n}, {inserts} pushes (totals; \
+             must not scale with N)"
+        ),
+        total,
+        total_draws,
+        total_rewrites,
+        total_moves,
+    );
+    println!(
+        "    per-push average: {:.4}ms",
+        total.as_secs_f64() * 1000.0 / inserts as f64
+    );
+}
+
+/// (e) Expand-a-row-holding-its-edge: one row (fixed-height, so its size is
+/// directly controllable) is grown a little at a time, each time preceded
+/// by `note_tap` aimed at its own top edge -- the exact mechanism list.rs's
+/// module doc describes and its unit tests check for correctness. This
+/// measures its *cost*: only the rows on the far side of the grown one
+/// (below it, since the top edge is held) should ever move, and nothing
+/// should be redrawn purely because the list overall got taller.
+fn bench_expand_holds_edge(n: usize, growths: usize) {
+    let mut rsc = BenchRsc {
+        ui: UiData::default(),
+    };
+    let mut list = List::new(Axis::Y);
+    // Near the end (not the very last row) so it is already on screen
+    // under the list's default bottom-anchored placement, for every N --
+    // no scrolling needed to bring it into view before measuring.
+    let growable_index = n.saturating_sub(3);
+    let mut growable = None;
+    for i in 0..n {
+        if i == growable_index {
+            let rect = rsc.ui.widgets.add_strong(Rect::new(UiColor::WHITE));
+            let sized = rsc.ui.widgets.add_strong(Sized {
+                inner: rect.any(),
+                x: None,
+                y: Some(abs(40.0)),
+            });
+            growable = Some(sized.weak());
+            list.push_back(ListRow::new(i as u64, sized.any()));
+        } else {
+            let row = build_row(&mut rsc, i, 20);
+            list.push_back(ListRow::new(i as u64, row));
+        }
+    }
+    let list = rsc.ui.widgets.add_strong(list);
+    let list_weak = list.weak();
+    let root = list.any();
+    let growable = growable.unwrap();
+
+    let mut render = UiRenderState::new();
+    render.resize((1080.0, 2000.0));
+    render.update(&root, &mut rsc);
+    render.take_counters();
+
+    let mut total = std::time::Duration::ZERO;
+    let mut total_draws = 0u64;
+    let mut total_rewrites = 0u64;
+    let mut total_moves = 0u64;
+    let mut height = 40.0f32;
+    let key = growable_index as u64;
+    for _ in 0..growths {
+        height += 10.0;
+        if let Some((top, _bottom)) = rsc.ui.widgets.get(&list_weak).unwrap().extent(key) {
+            rsc.ui
+                .widgets
+                .get_mut(&list_weak)
+                .unwrap()
+                .note_tap(top + 1.0);
+        }
+        rsc.ui.widgets.get_mut(&growable).unwrap().y = Some(abs(height));
+        let start = Instant::now();
+        render.update(&root, &mut rsc);
+        total += start.elapsed();
+        let (draws, rewrites, moves) = render.take_counters();
+        total_draws += draws;
+        total_rewrites += rewrites;
+        total_moves += moves;
+    }
+    report(
+        &format!(
+            "(e) expand-hold, N={n}, {growths} growths (totals; \
+             must not scale with N)"
+        ),
+        total,
+        total_draws,
+        total_rewrites,
+        total_moves,
+    );
+    println!(
+        "    per-growth average: {:.4}ms",
+        total.as_secs_f64() * 1000.0 / growths as f64
+    );
+}
+
+fn main() {
+    println!("iris message-list benchmark -- release build, this machine's CPU");
+    for &n in &[100usize, 1_000, 10_000] {
+        bench_first_frame(n);
+    }
+    for &n in &[100usize, 1_000, 10_000] {
+        bench_scroll(n, 200);
+    }
+    for &n in &[100usize, 1_000, 10_000] {
+        bench_input_grows(n, 40);
+    }
+    for &n in &[100usize, 1_000, 10_000] {
+        bench_insert_above_anchor(n, 200);
+    }
+    for &n in &[100usize, 1_000, 10_000] {
+        bench_expand_holds_edge(n, 40);
+    }
+}

iris/core/Cargo.toml

@@ -7,5 +7,7 @@ edition.workspace = true
 wgpu = { workspace = true }
 bytemuck ={ workspace = true }
 image = { workspace = true }
-cosmic-text = { workspace = true }
+parley = { workspace = true }
+swash = { workspace = true }
 fxhash = { workspace = true }
+accesskit = { workspace = true }

iris/core/src/event/manager.rs

@@ -135,6 +135,18 @@ impl<Rsc: HasEvents + 'static, E: Event> TypeEventManager<Rsc, E> {
         ));
     }
 
+    /// The event lists this widget was registered with (`register`'s
+    /// `event` argument, one per call), without running anything. Lets a
+    /// caller ask "would this widget's registrations match the current
+    /// state" separately from actually dispatching to it -- used by
+    /// `sense.rs` to decide whether a widget genuinely consumes a scroll
+    /// or press this frame (so a lower layer can still receive it if not)
+    /// without that decision being conflated with "the cursor happens to
+    /// be over it," which is all `run_fn` running something tells you.
+    pub fn registered(&self, id: WidgetId) -> impl Iterator<Item = &E> {
+        self.map.get(&id).into_iter().flatten().map(|(e, _)| e)
+    }
+
     pub fn run_fn<'a>(
         &mut self,
         id: impl IdLike,

iris/core/src/lib.rs

@@ -5,7 +5,6 @@
 #![feature(unboxed_closures)]
 #![feature(fn_traits)]
 #![feature(const_destruct)]
-#![feature(portable_simd)]
 #![feature(associated_type_defaults)]
 #![feature(unsize)]
 #![feature(coerce_unsized)]

iris/core/src/orientation/pos.rs

@@ -421,7 +421,7 @@ impl Display for UiRegion {
     }
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone, Copy, PartialEq)]
 pub struct PixelRegion {
     pub top_left: Vec2,
     pub bot_right: Vec2,

iris/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);

iris/core/src/primitive/layer.rs

@@ -1,7 +1,8 @@
 use std::ops::{Index, IndexMut};
 
 use crate::{
-    render::{MaskIdx, Primitive, PrimitiveHandle, PrimitiveInst, Primitives},
+    UiRegion, WidgetId,
+    render::{MaskIdx, MoveIdx, Primitive, PrimitiveHandle, PrimitiveInst, Primitives},
     util::to_mut,
 };
 
@@ -131,6 +132,18 @@ impl PrimitiveLayers {
     pub fn free(&mut self, h: &PrimitiveHandle) -> MaskIdx {
         self[h.layer].free(h)
     }
+
+    pub fn write_image(
+        &mut self,
+        layer: LayerId,
+        id: WidgetId,
+        texture_idx: u32,
+        region: UiRegion,
+        mask_idx: MaskIdx,
+        move_idx: MoveIdx,
+    ) -> PrimitiveHandle {
+        self[layer].write_image(layer, id, texture_idx, region, mask_idx, move_idx)
+    }
 }
 
 impl<T: Default> Default for Layers<T> {

iris/core/src/primitive/text.rs

@@ -1,60 +1,135 @@
-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,
+};
+use std::ops::Range;
+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::*;
-}
 
+/// 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,
 }
 
 impl Default for TextData {
     fn default() -> Self {
         Self {
-            font_system: FontSystem::new(),
-            swash_cache: SwashCache::new(),
-            glyph_cache: Default::default(),
+            font_cx: FontContext::new(),
+            layout_cx: LayoutContext::new(),
+            scale_cx: ScaleContext::new(),
+            atlas: GlyphAtlas::default(),
         }
     }
 }
 
-#[derive(Clone, Copy)]
+/// 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,
+    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),
+            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 +145,240 @@ 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>)>,
+}
 
-impl TextData {
-    pub fn draw(
-        &mut self,
-        buffer: &mut TextBuffer,
-        attrs: &TextAttrs,
-        textures: &mut Textures,
-    ) -> 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;
+impl TextBuffer {
+    pub fn new(text: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            layout: Layout::new(),
+            spans: Vec::new(),
+            shaped: None,
         }
-        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();
-            };
+    /// 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;
+    }
 
-            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);
-                    }
-                }
+    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 and
+    /// this width.
+    pub fn shape(&mut self, data: &mut TextData, attrs: &TextAttrs, width: Option<f32>) {
+        if self.shaped.as_ref() == Some(&(attrs.clone(), width)) {
+            return;
+        }
+        let mut builder = data
+            .layout_cx
+            .ranged_builder(&mut data.font_cx, &self.text, 1.0, true);
+        builder.push_default(StyleProperty::FontFamily(attrs.family.family()));
+        builder.push_default(StyleProperty::FontSize(attrs.font_size));
+        builder.push_default(StyleProperty::LineHeight(LineHeight::Absolute(
+            attrs.line_height,
+        )));
+        builder.push_default(StyleProperty::Brush(attrs.color));
+        for span in &self.spans {
+            let range = span.range.clone();
+            if let Some(color) = span.color {
+                builder.push(StyleProperty::Brush(color), range.clone());
+            }
+            if let Some(family) = &span.family {
+                builder.push(StyleProperty::FontFamily(family.family()), range.clone());
+            }
+            if let Some(size) = span.font_size {
+                builder.push(StyleProperty::FontSize(size), 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());
             }
         }
-
-        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();
-        }
-
-        RenderedText {
-            handle: textures.add(image),
-            top_left_offset: Vec2::new(min_x as f32, min_y as f32),
-            size: Vec2::new(max_width, height),
-        }
+        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));
     }
 }
 
-#[derive(Clone)]
-pub struct RenderedText {
-    pub handle: TextureHandle,
-    pub top_left_offset: Vec2,
-    pub size: Vec2,
+impl TextData {
+    /// 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
+    }
 }
 
-pub trait HasTextures {
-    fn add_texture(&mut self, image: DynamicImage) -> TextureHandle;
+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,
+}
+
+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,
+    ) -> RenderedText {
+        buffer.shape(self, attrs, width);
+        let glyphs = self.place(buffer, textures);
+        RenderedText {
+            glyphs: std::sync::Arc::new(glyphs),
+            size: buffer.size(),
+            color: attrs.color,
+        }
+    }
 }

iris/core/src/primitive/texture.rs

@@ -1,19 +1,33 @@
-use crate::{
-    render::TexturePrimitive,
-    util::{RefCounter, Vec2},
-};
+use crate::util::{RefCounter, Vec2};
 use image::{DynamicImage, GenericImageView};
 use std::{
     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,
+    },
+}
+
 #[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 +35,39 @@ pub struct TextureHandle {
 pub struct Textures {
     free: Vec<u32>,
     images: Vec<Option<DynamicImage>>,
+    /// 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 +77,99 @@ impl Textures {
         Self {
             free: Vec::new(),
             images: Vec::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.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.updates.push(Update::Push(kind, i));
             i
         }
     }
 
+    /// 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));
+    }
+
     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 +177,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 +215,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()
     }
 }
 

iris/core/src/render/atlas.rs

@@ -0,0 +1,243 @@
+//! A glyph atlas: one texture holding many rasterised glyphs, so drawing text
+//! is a quad per glyph rather than a texture per string.
+//!
+//! What this replaces is why it exists. Text used to be rasterised into its own
+//! `RgbaImage` and uploaded as a whole texture, per text widget, every time
+//! anything about it changed -- so every window resize re-rasterised and
+//! re-uploaded every visible string, which is what the TODO meant by "resizing
+//! (per frame) is really slow". Here a glyph is rasterised once for a given
+//! font, size and subpixel offset and then reused by every string that contains
+//! it, and a resize re-emits quads without touching the GPU's copy at all.
+
+use crate::{
+    PatchRect, TextureHandle, Textures, UiColor,
+    util::{HashMap, Vec2},
+};
+use image::RgbaImage;
+use swash::scale::image::{Content, Image};
+
+/// Side of one atlas page, in pixels. 1024 is 4 MB at RGBA8 -- enough for a
+/// few thousand glyphs at UI sizes, and small enough that a page nobody fills
+/// is not a big waste. Also the fixed width/height of every layer of the
+/// shared array texture in `render::texture` -- `pub(crate)` so that module
+/// can size it without a second constant to keep in sync.
+pub(crate) const PAGE: u32 = 1024;
+
+/// Transparent margin kept around every glyph, so that sampling one cannot
+/// pick up its neighbour along a shared edge.
+const PAD: u32 = 1;
+
+/// Identifies a rasterised glyph. Anything that changes the pixels has to be in
+/// here, or two different glyphs share one entry and the wrong one is drawn.
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub struct GlyphKey {
+    pub font: u64,
+    pub glyph: u32,
+    /// Font size in 1/16 px, so sizes that round to the same pixels share a
+    /// raster instead of filling the atlas with near-duplicates.
+    pub size: u32,
+    /// Horizontal subpixel phase, in 1/4 px.
+    pub subpixel: u8,
+    /// Hash of the variation coordinates; a variable font at two weights is two
+    /// different sets of pixels from one glyph id.
+    pub coords: u64,
+}
+
+#[derive(Clone, Copy)]
+pub struct GlyphEntry {
+    pub uv_min: [f32; 2],
+    pub uv_max: [f32; 2],
+    /// Offset from the glyph's pen position to the top-left of its pixels.
+    pub left: i32,
+    pub top: i32,
+    pub width: u32,
+    pub height: u32,
+    pub is_color: bool,
+    /// The atlas array layer this glyph's page occupies.
+    pub layer: u32,
+}
+
+struct Page {
+    handle: TextureHandle,
+    /// Shelf packing: glyphs are placed left to right along a shelf whose
+    /// height is the tallest glyph on it, and a new shelf starts above when the
+    /// row runs out. Chosen over a real packer because glyphs at one size are
+    /// close to the same height, which is the case shelves are good at.
+    x: u32,
+    y: u32,
+    shelf_height: u32,
+}
+
+#[derive(Default)]
+pub struct GlyphAtlas {
+    pages: Vec<Page>,
+    /// `None` for a glyph that rasterised to nothing -- a space, say. Cached
+    /// too, so it is not re-rasterised on every layout.
+    entries: HashMap<GlyphKey, Option<GlyphEntry>>,
+}
+
+impl GlyphAtlas {
+    pub fn get(&self, key: &GlyphKey) -> Option<Option<GlyphEntry>> {
+        self.entries.get(key).copied()
+    }
+
+    /// Rasterised pixels in, a place in the atlas out. `None` means the glyph
+    /// has no pixels, which is a normal answer rather than a failure.
+    pub fn insert(
+        &mut self,
+        key: GlyphKey,
+        image: &Image,
+        textures: &mut Textures,
+    ) -> Option<GlyphEntry> {
+        let w = image.placement.width;
+        let h = image.placement.height;
+        if w == 0 || h == 0 {
+            self.entries.insert(key, None);
+            return None;
+        }
+        if w + PAD * 2 > PAGE || h + PAD * 2 > PAGE {
+            // A single glyph larger than a page. Refusing is better than
+            // silently drawing a cropped one; the caller draws nothing.
+            self.entries.insert(key, None);
+            return None;
+        }
+
+        let (page_idx, x, y) = self.allocate(w, h, textures);
+        let page = &self.pages[page_idx];
+
+        let img = textures.image_mut(&page.handle);
+        let rgba = img.as_mut_rgba8().expect("atlas page is rgba8");
+        write_glyph(rgba, image, x, y);
+
+        let handle = page.handle.clone();
+        let rect = PatchRect {
+            x,
+            y,
+            width: w,
+            height: h,
+        };
+        textures.patch(&handle, rect);
+
+        let page = &self.pages[page_idx];
+        let scale = 1.0 / PAGE as f32;
+        let entry = GlyphEntry {
+            uv_min: [x as f32 * scale, y as f32 * scale],
+            uv_max: [(x + w) as f32 * scale, (y + h) as f32 * scale],
+            left: image.placement.left,
+            top: image.placement.top,
+            width: w,
+            height: h,
+            is_color: matches!(image.content, Content::Color),
+            layer: page.handle.layer(),
+        };
+        self.entries.insert(key, Some(entry));
+        Some(entry)
+    }
+
+    /// A free `w`x`h` spot, opening a shelf or a page as needed.
+    fn allocate(&mut self, w: u32, h: u32, textures: &mut Textures) -> (usize, u32, u32) {
+        let need_w = w + PAD;
+        let need_h = h + PAD;
+        if let Some(i) = self.pages.iter().position(|p| fits(p, need_w, need_h)) {
+            let page = &mut self.pages[i];
+            if page.x + need_w > PAGE {
+                page.y += page.shelf_height;
+                page.x = PAD;
+                page.shelf_height = 0;
+            }
+            let (x, y) = (page.x, page.y);
+            page.x += need_w;
+            page.shelf_height = page.shelf_height.max(need_h);
+            return (i, x, y);
+        }
+
+        let handle = textures.add_page(RgbaImage::new(PAGE, PAGE));
+        self.pages.push(Page {
+            handle,
+            x: PAD + w + PAD,
+            y: PAD,
+            shelf_height: h + PAD,
+        });
+        (self.pages.len() - 1, PAD, PAD)
+    }
+
+    /// Record that a glyph has no pixels, so it is not re-rasterised.
+    pub fn insert_empty(&mut self, key: GlyphKey) {
+        self.entries.insert(key, None);
+    }
+
+    pub fn page_count(&self) -> usize {
+        self.pages.len()
+    }
+
+    pub fn glyph_count(&self) -> usize {
+        self.entries.len()
+    }
+}
+
+fn fits(page: &Page, need_w: u32, need_h: u32) -> bool {
+    // On the current shelf, or on a new one above it.
+    (page.x + need_w <= PAGE && page.y + need_h <= PAGE)
+        || (need_w + PAD <= PAGE && page.y + page.shelf_height + need_h <= PAGE)
+}
+
+/// Copy one rasterised glyph into the page image at `(x, y)`.
+///
+/// A mask glyph keeps its coverage in alpha with the colour left to the shader,
+/// so one raster serves text of any colour; a colour glyph carries its own.
+fn write_glyph(page: &mut RgbaImage, image: &Image, x: u32, y: u32) {
+    let w = image.placement.width;
+    let h = image.placement.height;
+    match image.content {
+        Content::Mask => {
+            for row in 0..h {
+                for col in 0..w {
+                    let a = image.data[(row * w + col) as usize];
+                    page.put_pixel(x + col, y + row, image::Rgba([255, 255, 255, a]));
+                }
+            }
+        }
+        Content::Color => {
+            for row in 0..h {
+                for col in 0..w {
+                    let i = ((row * w + col) * 4) as usize;
+                    let px = [
+                        image.data[i],
+                        image.data[i + 1],
+                        image.data[i + 2],
+                        image.data[i + 3],
+                    ];
+                    page.put_pixel(x + col, y + row, image::Rgba(px));
+                }
+            }
+        }
+        Content::SubpixelMask => {
+            // Not asked for: `Format::Alpha` is what the renderer requests, so
+            // reaching here means the request changed and this needs writing.
+            // Drawn as a plain mask from the green channel rather than dropped,
+            // so the text is readable rather than absent.
+            for row in 0..h {
+                for col in 0..w {
+                    let i = ((row * w + col) * 4) as usize;
+                    let a = image.data[i + 1];
+                    page.put_pixel(x + col, y + row, image::Rgba([255, 255, 255, a]));
+                }
+            }
+        }
+    }
+}
+
+/// Where a glyph goes on screen, in pixels relative to the text's origin.
+///
+/// `color` is per-glyph (read from the parley run's own `Brush`, since
+/// `UiColor` is parley's brush type here) rather than a single colour for
+/// the whole `RenderedText`, so that a span pushed with its own
+/// `StyleProperty::Brush` (I5's inline rich text: a link, a diff of colour
+/// inside one wrapped paragraph) actually renders in that colour instead of
+/// the buffer's base one.
+#[derive(Clone, Copy)]
+pub struct PlacedGlyph {
+    pub entry: GlyphEntry,
+    pub offset: Vec2,
+    pub color: UiColor,
+}

iris/core/src/render/data.rs

@@ -15,10 +15,11 @@ pub struct PrimitiveInstance {
     pub binding: u32,
     pub idx: u32,
     pub mask_idx: MaskIdx,
+    pub move_idx: MoveIdx,
 }
 
 impl PrimitiveInstance {
-    const ATTRIBS: [VertexAttribute; 7] = vertex_attr_array![
+    const ATTRIBS: [VertexAttribute; 8] = vertex_attr_array![
         0 => Float32x2,
         1 => Float32x2,
         2 => Float32x2,
@@ -26,6 +27,7 @@ impl PrimitiveInstance {
         4 => Uint32,
         5 => Uint32,
         6 => Uint32,
+        7 => Uint32,
     ];
 
     pub fn desc() -> VertexBufferLayout<'static> {
@@ -43,8 +45,48 @@ impl MaskIdx {
     pub const NONE: Self = Self::preset(u32::MAX);
 }
 
+pub type MoveIdx = Id<u32>;
+
 #[repr(C)]
 #[derive(Debug, Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)]
 pub struct Mask {
     pub region: UiRegion,
+    /// The mask-owning widget's own move slot -- resolved in the fragment
+    /// shader against the same chain the vertex shader walks for a
+    /// primitive's own corners, so a mask and the content clipped by it
+    /// can move independently. See LAYOUT.md section 2b.
+    pub move_idx: MoveIdx,
+}
+
+/// One widget's cumulative on-screen translation, and the slot of the
+/// ancestor to add on top of it. `parent == u32::MAX` ends the chain. A
+/// pure abs-pixel delta, not a general `UiRegion` remap -- sufficient for
+/// every call site that moves a widget (`Scroll`, `Offset`) since both are
+/// translations of an already-drawn subtree. See LAYOUT.md section 2.
+///
+/// `_pad` matches WGSL's storage-buffer layout for `MoveOffset`: `delta` is
+/// a `vec2<f32>`, which gives the struct an 8-byte alignment and rounds its
+/// WGSL size up to 16 bytes even though `delta` + `parent` only total 12 --
+/// the same trap `GlyphPrimitive` documents below. `bytemuck` does not
+/// check this for us, and getting it wrong is a wgpu validation panic at
+/// draw time ("buffer bound ... with size 12 where the shader expects 16"),
+/// not a compile error.
+#[repr(C)]
+#[derive(Debug, Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)]
+pub struct MoveOffset {
+    pub delta: [f32; 2],
+    pub parent: u32,
+    _pad: u32,
+}
+
+impl MoveOffset {
+    pub const NONE_PARENT: u32 = u32::MAX;
+
+    pub fn new(delta: [f32; 2], parent: u32) -> Self {
+        Self {
+            delta,
+            parent,
+            _pad: 0,
+        }
+    }
 }

iris/core/src/render/mod.rs

@@ -1,5 +1,3 @@
-use std::num::NonZero;
-
 use crate::{
     UiData, UiRenderState,
     render::{data::PrimitiveInstance, texture::GpuTextures, util::ArrBuf},
@@ -11,12 +9,14 @@ use wgpu::{
     *,
 };
 
+mod atlas;
 mod data;
 mod primitive;
 mod texture;
 mod util;
 
-pub use data::{Mask, MaskIdx};
+pub use atlas::*;
+pub use data::{Mask, MaskIdx, MoveIdx, MoveOffset};
 pub use primitive::*;
 
 const SHAPE_SHADER: &str = include_str!("./shader.wgsl");
@@ -34,27 +34,71 @@ pub struct UiRenderNode {
     window_buffer: Buffer,
     textures: GpuTextures,
     masks: ArrBuf<Mask>,
+    move_offsets: ArrBuf<MoveOffset>,
+    /// Group 3: the masks and move-offsets storage buffers, on their own --
+    /// see IRIS_TODO.md's "Appending one image ... rebuilds every other
+    /// image's bind group". These used to live in group 2 alongside each
+    /// standalone image's own texture view, so an image's bind group named
+    /// the masks/move_offsets buffer directly; the moment either buffer
+    /// resized (which a widget getting its *first* move slot can trigger,
+    /// unrelated to any image), `ArrBuf::update` handed back a new `Buffer`
+    /// identity and every image's bind group -- one per live image -- had
+    /// to be rebuilt to reference it. Pulling both buffers into their own
+    /// group, bound once per frame rather than once per draw call, means a
+    /// buffer resize now rebuilds exactly this one group instead of N.
+    masks_layout: BindGroupLayout,
+    masks_group: BindGroup,
 }
 
 struct RenderLayer {
     instance: ArrBuf<PrimitiveInstance>,
     primitives: PrimitiveBuffers,
     primitive_group: BindGroup,
+    /// A standalone image's instances, kept apart from `instance` because
+    /// each one draws with its own bind group -- see `UiRenderNode::draw`.
+    image_instance: ArrBuf<PrimitiveInstance>,
+    /// The texture slot each entry of `image_instance` draws with, in the
+    /// same order, refreshed alongside it. Not stored in the vertex buffer
+    /// itself because it names a bind group, not shader data.
+    image_tex_indices: Vec<u32>,
 }
 
 impl UiRenderNode {
     pub fn draw<'a>(&'a self, pass: &mut RenderPass<'a>) {
         pass.set_pipeline(&self.pipeline);
         pass.set_bind_group(0, &self.uniform_group, &[]);
-        pass.set_bind_group(2, &self.rsc_group, &[]);
+        // Set once, not per layer or per image: masks/move_offsets are read
+        // by every primitive and every standalone image alike, and living
+        // in their own group (rather than folded into group 2 alongside the
+        // per-image texture view) is what keeps an image's own bind group
+        // from naming a buffer that changes size on an unrelated widget's
+        // first draw -- see the comment on `masks_group` below.
+        pass.set_bind_group(3, &self.masks_group, &[]);
         for i in &self.active {
             let layer = &self.layers[i];
-            if layer.instance.len() == 0 {
+            if layer.instance.len() == 0 && layer.image_instance.len() == 0 {
                 continue;
             }
             pass.set_bind_group(1, &layer.primitive_group, &[]);
-            pass.set_vertex_buffer(0, layer.instance.buffer.slice(..));
-            pass.draw(0..4, 0..layer.instance.len() as u32);
+            if layer.instance.len() > 0 {
+                pass.set_bind_group(2, &self.rsc_group, &[]);
+                pass.set_vertex_buffer(0, layer.instance.buffer.slice(..));
+                pass.draw(0..4, 0..layer.instance.len() as u32);
+            }
+            // Images draw after this layer's rects and glyphs, one draw call
+            // each with its own bind group. That draws every image "on top"
+            // within the layer, which loses nothing that currently exists:
+            // `Primitives::apply_free` frees with `swap_remove`, so a layer's
+            // draw order was already undefined before images had their own
+            // list -- nothing before this relied on interleaving a rect
+            // between two images at a particular position.
+            if layer.image_instance.len() > 0 {
+                pass.set_vertex_buffer(0, layer.image_instance.buffer.slice(..));
+                for (k, &tex_idx) in layer.image_tex_indices.iter().enumerate() {
+                    pass.set_bind_group(2, self.textures.image_bind_group(tex_idx), &[]);
+                    pass.draw(0..4, k as u32..k as u32 + 1);
+                }
+            }
         }
     }
 
@@ -71,7 +115,15 @@ impl UiRenderNode {
             for change in primitives.apply_free() {
                 if let Some(inst) = ui_render.active.get_mut(&change.id) {
                     for h in &mut inst.primitives {
-                        if h.layer == i && h.inst_idx == change.old {
+                        // `is_image` disambiguates: `instances` and `images`
+                        // are separate lists with independent indices, so
+                        // without it a rect's renumbering could be applied to
+                        // an image handle that happened to share the same
+                        // (layer, inst_idx).
+                        if h.layer == i
+                            && h.inst_idx == change.old
+                            && (h.binding == IMAGE_BINDING) == change.is_image
+                        {
                             h.inst_idx = change.new;
                             break;
                         }
@@ -90,6 +142,12 @@ impl UiRenderNode {
                     ),
                     primitives,
                     primitive_group,
+                    image_instance: ArrBuf::new(
+                        device,
+                        BufferUsages::VERTEX | BufferUsages::COPY_DST,
+                        "image instance",
+                    ),
+                    image_tex_indices: Vec::new(),
                 }
             });
             if primitives.updated {
@@ -102,18 +160,37 @@ impl UiRenderNode {
                     &self.primitive_layout,
                     rlayer.primitives.buffers(),
                 );
+                rlayer
+                    .image_instance
+                    .update(device, queue, primitives.image_instances());
+                rlayer.image_tex_indices = primitives
+                    .image_instances()
+                    .iter()
+                    .map(|inst| inst.idx)
+                    .collect();
                 primitives.updated = false;
             }
         }
-        let mut changed = false;
-        changed |= self.textures.update(&mut ui.textures);
-        if ui.masks.changed {
+        let masks_resized = if ui.masks.changed {
             ui.masks.changed = false;
-            self.masks.update(device, queue, &ui.masks[..]);
-            changed = true;
+            self.masks.update(device, queue, &ui.masks[..])
+        } else {
+            false
+        };
+        let moves_resized = if ui.move_offsets.changed {
+            ui.move_offsets.changed = false;
+            self.move_offsets
+                .update(device, queue, &ui.move_offsets[..])
+        } else {
+            false
+        };
+        if masks_resized || moves_resized {
+            self.masks_group =
+                Self::masks_group(device, &self.masks_layout, &self.masks, &self.move_offsets);
         }
-        if changed {
-            self.rsc_group = Self::rsc_group(device, &self.rsc_layout, &self.textures, &self.masks);
+        let rebuild_main = self.textures.update(&mut ui.textures, &self.rsc_layout);
+        if rebuild_main {
+            self.rsc_group = Self::rsc_group(device, &self.rsc_layout, &self.textures);
         }
     }
 
@@ -130,18 +207,27 @@ impl UiRenderNode {
         queue.write_buffer(&self.window_buffer, 0, bytemuck::cast_slice(slice));
     }
 
-    pub fn new(
-        device: &Device,
-        queue: &Queue,
-        config: &SurfaceConfiguration,
-        limits: UiLimits,
-    ) -> Self {
+    pub fn new(device: &Device, queue: &Queue, config: &SurfaceConfiguration) -> Self {
         let shader = device.create_shader_module(ShaderModuleDescriptor {
             label: Some("UI Shape Shader"),
             source: ShaderSource::Wgsl(SHAPE_SHADER.into()),
         });
 
-        let window_uniform = WindowUniform::default();
+        // Seeded from the surface's own size, not `WindowUniform::default()`
+        // (0, 0): the vertex shader divides by `window.dim` to reach clip
+        // space, so a window this buffer disagrees with means every
+        // primitive's position is NaN/Inf and is dropped before
+        // rasterization -- the clear colour still reaches the screen (the
+        // pass runs regardless) while nothing drawn on top of it ever does.
+        // winit's backend gets away with the old default because winit
+        // fires an initial `WindowEvent::Resized` that calls `resize()`
+        // before the first frame; android-view has no such automatic
+        // event, so `AndroidRenderer::new` built a node whose window buffer
+        // was never corrected -- this is I2's "nothing draws" bug (RUST.md).
+        let window_uniform = WindowUniform {
+            width: config.width as f32,
+            height: config.height as f32,
+        };
         let window_buffer = device.create_buffer_init(&BufferInitDescriptor {
             label: Some("window"),
             contents: bytemuck::cast_slice(&[window_uniform]),
@@ -165,17 +251,15 @@ impl UiRenderNode {
         let uniform_group = Self::bind_group_0(device, &uniform_layout, &window_buffer);
 
         let primitive_layout = device.create_bind_group_layout(&BindGroupLayoutDescriptor {
-            entries: &core::array::from_fn::<_, { PrimitiveBuffers::LEN }, _>(|i| {
-                BindGroupLayoutEntry {
-                    binding: i as u32,
-                    visibility: ShaderStages::FRAGMENT,
-                    ty: BindingType::Buffer {
-                        ty: BufferBindingType::Storage { read_only: true },
-                        has_dynamic_offset: false,
-                        min_binding_size: None,
-                    },
-                    count: None,
-                }
+            entries: &PrimitiveBuffers::BINDINGS.map(|binding| BindGroupLayoutEntry {
+                binding,
+                visibility: ShaderStages::FRAGMENT,
+                ty: BindingType::Buffer {
+                    ty: BufferBindingType::Storage { read_only: true },
+                    has_dynamic_offset: false,
+                    min_binding_size: None,
+                },
+                count: None,
             }),
             label: Some("primitive"),
         });
@@ -186,13 +270,25 @@ impl UiRenderNode {
             BufferUsages::STORAGE | BufferUsages::COPY_DST,
             "ui masks",
         );
+        let move_offsets = ArrBuf::new(
+            device,
+            BufferUsages::STORAGE | BufferUsages::COPY_DST,
+            "ui move offsets",
+        );
 
-        let rsc_layout = Self::rsc_layout(device, &limits);
-        let rsc_group = Self::rsc_group(device, &rsc_layout, &tex_manager, &masks);
+        let rsc_layout = Self::rsc_layout(device);
+        let rsc_group = Self::rsc_group(device, &rsc_layout, &tex_manager);
+        let masks_layout = Self::masks_layout(device);
+        let masks_group = Self::masks_group(device, &masks_layout, &masks, &move_offsets);
 
         let pipeline_layout = device.create_pipeline_layout(&PipelineLayoutDescriptor {
             label: Some("UI Shape Pipeline Layout"),
-            bind_group_layouts: &[&uniform_layout, &primitive_layout, &rsc_layout],
+            bind_group_layouts: &[
+                &uniform_layout,
+                &primitive_layout,
+                &rsc_layout,
+                &masks_layout,
+            ],
             immediate_size: 0,
         });
         let pipeline = device.create_render_pipeline(&RenderPipelineDescriptor {
@@ -244,6 +340,9 @@ impl UiRenderNode {
             active: Vec::new(),
             textures: tex_manager,
             masks,
+            move_offsets,
+            masks_layout,
+            masks_group,
         }
     }
 
@@ -277,7 +376,14 @@ impl UiRenderNode {
         })
     }
 
-    fn rsc_layout(device: &Device, limits: &UiLimits) -> BindGroupLayout {
+    /// Group 2: the shared atlas array and one standalone-image slot (a null
+    /// view for the main draw, a real one for each image's own bind group --
+    /// see `GpuTextures`), plus one sampler. No `count` on any entry: this
+    /// needs nothing beyond plain Vulkan 1.0 / GLES sampling, unlike the
+    /// `binding_array` layout it replaced (see TEXTURES.md's "Recommended
+    /// shape"). Masks and move_offsets are deliberately *not* here -- see
+    /// `masks_layout` below for why they get their own group.
+    fn rsc_layout(device: &Device) -> BindGroupLayout {
         device.create_bind_group_layout(&BindGroupLayoutDescriptor {
             entries: &[
                 BindGroupLayoutEntry {
@@ -285,20 +391,81 @@ impl UiRenderNode {
                     visibility: ShaderStages::FRAGMENT,
                     ty: BindingType::Texture {
                         sample_type: TextureSampleType::Float { filterable: false },
-                        view_dimension: TextureViewDimension::D2,
+                        view_dimension: TextureViewDimension::D2Array,
                         multisampled: false,
                     },
-                    count: Some(NonZero::new(limits.max_textures).unwrap()),
+                    count: None,
                 },
                 BindGroupLayoutEntry {
                     binding: 1,
                     visibility: ShaderStages::FRAGMENT,
-                    ty: BindingType::Sampler(SamplerBindingType::NonFiltering),
-                    count: Some(NonZero::new(limits.max_samplers).unwrap()),
+                    ty: BindingType::Texture {
+                        sample_type: TextureSampleType::Float { filterable: false },
+                        view_dimension: TextureViewDimension::D2,
+                        multisampled: false,
+                    },
+                    count: None,
                 },
                 BindGroupLayoutEntry {
                     binding: 2,
                     visibility: ShaderStages::FRAGMENT,
+                    ty: BindingType::Sampler(SamplerBindingType::NonFiltering),
+                    count: None,
+                },
+            ],
+            label: Some("ui rsc"),
+        })
+    }
+
+    /// The main group: rects and glyphs never sample the image slot, so it
+    /// gets a 1x1 null view rather than any live standalone image's.
+    fn rsc_group(
+        device: &Device,
+        layout: &BindGroupLayout,
+        tex_manager: &GpuTextures,
+    ) -> BindGroup {
+        device.create_bind_group(&BindGroupDescriptor {
+            layout,
+            entries: &[
+                BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(tex_manager.array_view()),
+                },
+                BindGroupEntry {
+                    binding: 1,
+                    resource: BindingResource::TextureView(tex_manager.null_view()),
+                },
+                BindGroupEntry {
+                    binding: 2,
+                    resource: BindingResource::Sampler(tex_manager.sampler()),
+                },
+            ],
+            label: Some("ui rsc"),
+        })
+    }
+
+    /// Group 3: the masks and move_offsets storage buffers, shared by the
+    /// main draw and every standalone image alike (see the field comment on
+    /// `masks_group`). Bound once per frame in `draw()` rather than folded
+    /// into group 2, so a resize of either buffer -- which an unrelated
+    /// widget's first move slot can trigger -- rebuilds this one group
+    /// instead of every image's.
+    fn masks_layout(device: &Device) -> BindGroupLayout {
+        device.create_bind_group_layout(&BindGroupLayoutDescriptor {
+            entries: &[
+                BindGroupLayoutEntry {
+                    binding: 0,
+                    visibility: ShaderStages::FRAGMENT,
+                    ty: BindingType::Buffer {
+                        ty: BufferBindingType::Storage { read_only: true },
+                        has_dynamic_offset: false,
+                        min_binding_size: None,
+                    },
+                    count: None,
+                },
+                BindGroupLayoutEntry {
+                    binding: 1,
+                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                     ty: BindingType::Buffer {
                         ty: BufferBindingType::Storage { read_only: true },
                         has_dynamic_offset: false,
@@ -307,60 +474,40 @@ impl UiRenderNode {
                     count: None,
                 },
             ],
-            label: Some("ui rsc"),
+            label: Some("ui masks"),
         })
     }
 
-    fn rsc_group(
+    fn masks_group(
         device: &Device,
         layout: &BindGroupLayout,
-        tex_manager: &GpuTextures,
         masks: &ArrBuf<Mask>,
+        move_offsets: &ArrBuf<MoveOffset>,
     ) -> BindGroup {
         device.create_bind_group(&BindGroupDescriptor {
             layout,
             entries: &[
                 BindGroupEntry {
                     binding: 0,
-                    resource: BindingResource::TextureViewArray(&tex_manager.views()),
+                    resource: masks.buffer.as_entire_binding(),
                 },
                 BindGroupEntry {
                     binding: 1,
-                    resource: BindingResource::SamplerArray(&tex_manager.samplers()),
-                },
-                BindGroupEntry {
-                    binding: 2,
-                    resource: masks.buffer.as_entire_binding(),
+                    resource: move_offsets.buffer.as_entire_binding(),
                 },
             ],
-            label: Some("ui rsc"),
+            label: Some("ui masks"),
         })
     }
 
     pub fn view_count(&self) -> usize {
         self.textures.view_count()
     }
-}
 
-pub struct UiLimits {
-    max_textures: u32,
-    max_samplers: u32,
-}
-
-impl Default for UiLimits {
-    fn default() -> Self {
-        Self {
-            max_textures: 100000,
-            max_samplers: 1000,
-        }
-    }
-}
-
-impl UiLimits {
-    pub fn max_binding_array_elements_per_shader_stage(&self) -> u32 {
-        self.max_textures + self.max_samplers
-    }
-    pub fn max_binding_array_sampler_elements_per_shader_stage(&self) -> u32 {
-        self.max_samplers
+    /// Standalone-image bind groups built since the last call -- see
+    /// `GpuTextures::take_bind_group_creates`. Call once per frame before
+    /// `update()` to measure exactly that frame.
+    pub fn take_image_bind_group_creates(&mut self) -> u64 {
+        self.textures.take_bind_group_creates()
     }
 }

iris/core/src/render/primitive.rs

@@ -4,7 +4,7 @@ use crate::{
     Color, UiRegion, WidgetId,
     render::{
         ArrBuf,
-        data::{MaskIdx, PrimitiveInstance},
+        data::{MaskIdx, MoveIdx, PrimitiveInstance},
     },
 };
 use bytemuck::Pod;
@@ -15,6 +15,18 @@ pub struct Primitives {
     assoc: Vec<WidgetId>,
     data: PrimitiveData,
     free: Vec<usize>,
+
+    /// Standalone images, kept apart from `instances` because each one draws
+    /// with its own bind group rather than sharing the layer's one instanced
+    /// draw -- see TEXTURES.md's "Recommended shape". `idx` on each
+    /// `PrimitiveInstance` here is the texture's slot in `Textures`/
+    /// `GpuTextures`, not an index into `data`; there is no per-image entry
+    /// in `data` because a bind group already picks the texture; nothing
+    /// left to look up per-instance.
+    images: Vec<PrimitiveInstance>,
+    image_assoc: Vec<WidgetId>,
+    image_free: Vec<usize>,
+
     pub updated: bool,
 }
 
@@ -25,11 +37,21 @@ impl Default for Primitives {
             assoc: Default::default(),
             data: Default::default(),
             free: Vec::new(),
+            images: Default::default(),
+            image_assoc: Default::default(),
+            image_free: Vec::new(),
             updated: true,
         }
     }
 }
 
+/// The `binding` tag `Painter` writes on an image instance. Distinct from any
+/// `Primitive::BINDING` because images have no `PrimitiveData` entry to key
+/// one from -- a bind group already selects the texture -- so this only ever
+/// has to match the shader's `TEXTURE` constant and flag "this instance lives
+/// in `Primitives::images`, not `Primitives::instances`" to the code below.
+pub const IMAGE_BINDING: u32 = 1;
+
 pub trait Primitive: Pod {
     const BINDING: u32;
     fn vec(data: &mut PrimitiveData) -> &mut PrimitiveVec<Self>;
@@ -54,6 +76,14 @@ macro_rules! primitives {
 
         impl PrimitiveBuffers {
             pub const LEN: usize = primitives!(@count $($name)*);
+            /// The group-1 binding number each primitive's storage buffer
+            /// sits at, in declaration order. Not `0..LEN`: a primitive's
+            /// `BINDING` also tags its instances for the shader's dispatch
+            /// switch, and a removed primitive (as `TEXTURE` was, once
+            /// images stopped needing a per-instance storage entry) can
+            /// leave a gap, so the pipeline layout has to ask for these
+            /// exact numbers rather than assuming they are contiguous.
+            pub const BINDINGS: [u32; Self::LEN] = [$(<$ty>::BINDING,)*];
             pub fn buffers(&self) -> [(u32, &Buffer); Self::LEN] {
                 [
                     $((<$ty>::BINDING, &self.$name.buffer),)*
@@ -93,7 +123,13 @@ macro_rules! primitives {
             }
         )*
     };
-    (@count $t1:tt $($t:tt)+) => { 1 + primitives!(@count $($t),+) };
+    // The recursion has to hand back the same shape it matches -- space
+    // separated, not comma separated. Written with `$($t),+` it re-entered
+    // with a comma as the first token and never terminated, which happened to
+    // work only because there were exactly two primitives: the first step left
+    // a single token, and a single token matches the base case whichever
+    // separator it was written with.
+    (@count $t1:tt $($t:tt)+) => { 1 + primitives!(@count $($t)+) };
     (@count $t:tt) => { 1 };
 }
 
@@ -102,6 +138,7 @@ pub struct PrimitiveInst<P> {
     pub primitive: P,
     pub region: UiRegion,
     pub mask_idx: MaskIdx,
+    pub move_idx: MoveIdx,
 }
 
 impl Primitives {
@@ -113,6 +150,7 @@ impl Primitives {
             primitive,
             region,
             mask_idx,
+            move_idx,
         }: PrimitiveInst<P>,
     ) -> PrimitiveHandle {
         self.updated = true;
@@ -122,6 +160,7 @@ impl Primitives {
             region,
             idx: i as u32,
             mask_idx,
+            move_idx,
             binding: P::BINDING,
         };
         let inst_i = if let Some(i) = self.free.pop() {
@@ -137,26 +176,105 @@ impl Primitives {
         PrimitiveHandle::new::<P>(layer, inst_i, i)
     }
 
-    /// returns (old index, new index)
-    pub fn apply_free(&mut self) -> impl Iterator<Item = PrimitiveChange> {
-        self.free.sort_by(|a, b| b.cmp(a));
-        self.free.drain(..).filter_map(|i| {
-            self.instances.swap_remove(i);
-            self.assoc.swap_remove(i);
-            if i == self.instances.len() {
-                return None;
-            }
-            let id = self.assoc[i];
-            let old = self.instances.len();
-            Some(PrimitiveChange { id, old, new: i })
-        })
+    /// Writes an image instance directly -- there is no `Primitive` impl for
+    /// it to go through `write`, since it has nowhere in `PrimitiveData` to
+    /// put a per-instance entry. `texture_idx` is the slot the bind group at
+    /// draw time is chosen from, carried in the otherwise-unused `idx` field.
+    pub fn write_image(
+        &mut self,
+        layer: usize,
+        id: WidgetId,
+        texture_idx: u32,
+        region: UiRegion,
+        mask_idx: MaskIdx,
+        move_idx: MoveIdx,
+    ) -> PrimitiveHandle {
+        self.updated = true;
+        let inst = PrimitiveInstance {
+            region,
+            idx: texture_idx,
+            mask_idx,
+            move_idx,
+            binding: IMAGE_BINDING,
+        };
+        let inst_i = if let Some(i) = self.image_free.pop() {
+            self.images[i] = inst;
+            self.image_assoc[i] = id;
+            i
+        } else {
+            let i = self.images.len();
+            self.images.push(inst);
+            self.image_assoc.push(id);
+            i
+        };
+        PrimitiveHandle {
+            layer,
+            inst_idx: inst_i,
+            data_idx: 0,
+            binding: IMAGE_BINDING,
+        }
+    }
+
+    pub fn image_instances(&self) -> &Vec<PrimitiveInstance> {
+        &self.images
+    }
+
+    /// returns (old index, new index) for both lists this layer keeps --
+    /// `PrimitiveChange::is_image` says which, since the two have separate
+    /// index spaces and `old`/`new` alone would collide between them.
+    ///
+    /// Both lists free with `swap_remove`, so a layer's draw order was
+    /// already undefined before images existed: nothing here may assume one
+    /// primitive stays adjacent to another once anything in the layer has
+    /// been freed.
+    pub fn apply_free(&mut self) -> Vec<PrimitiveChange> {
+        let mut changes =
+            Self::apply_free_list(&mut self.free, &mut self.instances, &mut self.assoc, false);
+        changes.extend(Self::apply_free_list(
+            &mut self.image_free,
+            &mut self.images,
+            &mut self.image_assoc,
+            true,
+        ));
+        changes
+    }
+
+    fn apply_free_list(
+        free: &mut Vec<usize>,
+        instances: &mut Vec<PrimitiveInstance>,
+        assoc: &mut Vec<WidgetId>,
+        is_image: bool,
+    ) -> Vec<PrimitiveChange> {
+        free.sort_by(|a, b| b.cmp(a));
+        free.drain(..)
+            .filter_map(|i| {
+                instances.swap_remove(i);
+                assoc.swap_remove(i);
+                if i == instances.len() {
+                    return None;
+                }
+                let id = assoc[i];
+                let old = instances.len();
+                Some(PrimitiveChange {
+                    id,
+                    is_image,
+                    old,
+                    new: i,
+                })
+            })
+            .collect()
     }
 
     pub fn free(&mut self, h: &PrimitiveHandle) -> MaskIdx {
         self.updated = true;
-        self.data.free(h.binding, h.data_idx);
-        self.free.push(h.inst_idx);
-        self.instances[h.inst_idx].mask_idx
+        if h.binding == IMAGE_BINDING {
+            self.image_free.push(h.inst_idx);
+            self.images[h.inst_idx].mask_idx
+        } else {
+            self.data.free(h.binding, h.data_idx);
+            self.free.push(h.inst_idx);
+            self.instances[h.inst_idx].mask_idx
+        }
     }
 
     pub fn data(&self) -> &PrimitiveData {
@@ -169,12 +287,21 @@ impl Primitives {
 
     pub fn region_mut(&mut self, h: &PrimitiveHandle) -> &mut UiRegion {
         self.updated = true;
-        &mut self.instances[h.inst_idx].region
+        if h.binding == IMAGE_BINDING {
+            &mut self.images[h.inst_idx].region
+        } else {
+            &mut self.instances[h.inst_idx].region
+        }
     }
 }
 
 pub struct PrimitiveChange {
     pub id: WidgetId,
+    /// Which of `Primitives::instances`/`Primitives::images` this change
+    /// belongs to -- their `old`/`new` indices are independent, so a
+    /// consumer matching only on `(layer, inst_idx)` could apply an image's
+    /// renumbering to a rect's handle that happens to share the same index.
+    pub is_image: bool,
     pub old: usize,
     pub new: usize,
 }
@@ -200,7 +327,7 @@ impl PrimitiveHandle {
 
 primitives!(
     rects: RectPrimitive => 0,
-    textures: TexturePrimitive => 1,
+    glyphs: GlyphPrimitive => 2,
 );
 
 #[repr(C)]
@@ -223,11 +350,48 @@ impl RectPrimitive {
     }
 }
 
+/// One glyph, drawn as a sub-rectangle of the glyph atlas array.
+///
+/// `color` is the text colour and is multiplied by the atlas's alpha for an
+/// ordinary mask glyph; a colour glyph (emoji) carries its own colour and
+/// takes the atlas texel unchanged, which is what `IS_COLOR` selects.
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
-pub struct TexturePrimitive {
-    pub view_idx: u32,
-    pub sampler_idx: u32,
+pub struct GlyphPrimitive {
+    pub uv_min: [f32; 2],
+    pub uv_max: [f32; 2],
+    /// Layer of the shared atlas array texture this glyph's page occupies --
+    /// not a bind-group or view index, since a page never gets one of its
+    /// own. See TEXTURES.md's "Recommended shape".
+    pub layer: u32,
+    pub color: Color<u8>,
+    pub flags: u32,
+    /// Pads this struct's Rust size to match WGSL's storage-buffer layout for
+    /// `GlyphInfo`: two `vec2<f32>` members give the struct an 8-byte
+    /// alignment, which rounds the WGSL size up to 32 bytes even though the
+    /// fields above only total 28. `bytemuck` does not check this for us.
+    _pad: u32,
+}
+
+impl GlyphPrimitive {
+    pub const IS_COLOR: u32 = 1;
+
+    pub fn new(
+        uv_min: [f32; 2],
+        uv_max: [f32; 2],
+        layer: u32,
+        color: Color<u8>,
+        flags: u32,
+    ) -> Self {
+        Self {
+            uv_min,
+            uv_max,
+            layer,
+            color,
+            flags,
+            _pad: 0,
+        }
+    }
 }
 
 pub struct PrimitiveVec<T> {

iris/core/src/render/shader.wgsl

@@ -1,12 +1,16 @@
 const RECT: u32 = 0u;
+// TEXTURE has no entry in group 1: a standalone image draws with its own
+// bind group (see UiRenderNode::draw), so there is nothing per-instance left
+// to look up here -- the bind group already picked the texture.
 const TEXTURE: u32 = 1u;
+const GLYPH: u32 = 2u;
 
 @group(0) @binding(0)
 var<uniform> window: WindowUniform;
 @group(1) @binding(RECT)
 var<storage> rects: array<Rect>;
-@group(1) @binding(TEXTURE)
-var<storage> textures: array<TextureInfo>;
+@group(1) @binding(GLYPH)
+var<storage> glyphs: array<GlyphInfo>;
 
 struct Rect {
     color: u32,
@@ -15,14 +19,28 @@ struct Rect {
     inner_radius: f32,
 }
 
-struct TextureInfo {
-    view_idx: u32,
-    sampler_idx: u32,
+struct GlyphInfo {
+    uv_min: vec2<f32>,
+    uv_max: vec2<f32>,
+    // Layer of the shared atlas array texture, not a view or bind-group
+    // index -- a page never gets its own bind group. See TEXTURES.md's
+    // "Recommended shape".
+    layer: u32,
+    color: u32,
+    flags: u32,
 }
 
 struct Mask {
     x: UiSpan,
     y: UiSpan,
+    move_idx: u32,
+}
+
+/// One widget's cumulative on-screen translation and the slot of the
+/// ancestor to add on top of it. Mirrors `MoveOffset` in data.rs.
+struct MoveOffset {
+    delta: vec2<f32>,
+    parent: u32,
 }
 
 struct UiSpan {
@@ -40,12 +58,50 @@ struct UiVec2 {
     abs: vec2<f32>,
 }
 
+// The shared glyph atlas: every page is one layer. Growing it recreates this
+// texture with headroom and copies the old layers across -- see
+// GpuTextures::grow_array -- rather than the binding_array<texture_2d<f32>>
+// this replaced, which needed VK_EXT_descriptor_indexing and does not survive
+// a real share of Android GPUs (see TEXTURES.md).
 @group(2) @binding(0)
-var views: binding_array<texture_2d<f32>>;
+var atlas: texture_2d_array<f32>;
+// One standalone image's texture. The main draw (rects and glyphs) binds a
+// 1x1 null texture here, since neither samples it; each image draw call
+// binds its own -- see UiRenderNode::draw.
 @group(2) @binding(1)
-var samplers: binding_array<sampler>;
+var image_texture: texture_2d<f32>;
 @group(2) @binding(2)
+var samp: sampler;
+// Their own group, bound once per frame rather than folded into group 2: see
+// UiRenderNode::masks_layout for why an image's own bind group must not name
+// either buffer.
+@group(3) @binding(0)
 var<storage> masks: array<Mask>;
+@group(3) @binding(1)
+var<storage> move_offsets: array<MoveOffset>;
+
+// A move chain more than this deep means something else is wrong (an
+// accidental cycle) -- kept in step with `MOVE_CHAIN_LIMIT` in
+// render_state.rs, which walks the identical bound on the CPU side for
+// hit-testing. Bounded so a malformed chain cannot hang the GPU.
+const MOVE_CHAIN_LIMIT: u32 = 16u;
+
+/// Sums the pixel delta along the parent chain starting at `idx`, shared by
+/// the vertex stage (a primitive's own corners) and the fragment stage (its
+/// mask's corners) so the walk is written once. See LAYOUT.md section 2b.
+fn resolve_move(idx: u32) -> vec2<f32> {
+    var total = vec2<f32>(0.0, 0.0);
+    var i = idx;
+    for (var step = 0u; step < MOVE_CHAIN_LIMIT; step++) {
+        let entry = move_offsets[i];
+        total += entry.delta;
+        if entry.parent == 4294967295u {
+            break;
+        }
+        i = entry.parent;
+    }
+    return total;
+}
 
 struct WindowUniform {
     dim: vec2<f32>,
@@ -59,6 +115,7 @@ struct InstanceInput {
     @location(4) binding: u32,
     @location(5) idx: u32,
     @location(6) mask_idx: u32,
+    @location(7) move_idx: u32,
 }
 
 struct VertexOutput {
@@ -90,8 +147,9 @@ fn vs_main(
     let bot_right_rel = vec2(in.x_end.x, in.y_end.x);
     let bot_right_abs = vec2(in.x_end.y, in.y_end.y);
 
-    let top_left = floor(top_left_rel * window.dim) + floor(top_left_abs);
-    let bot_right = floor(bot_right_rel * window.dim) + floor(bot_right_abs);
+    let move_delta = resolve_move(in.move_idx);
+    let top_left = floor(top_left_rel * window.dim) + floor(top_left_abs) + move_delta;
+    let bot_right = floor(bot_right_rel * window.dim) + floor(bot_right_abs) + move_delta;
     let size = bot_right - top_left;
 
     let uv = vec2<f32>(
@@ -123,7 +181,10 @@ fn fs_main(
             color = draw_rounded_rect(region, rects[i]);
         }
         case TEXTURE: {
-            color = draw_texture(region, textures[i]);
+            color = draw_texture(region);
+        }
+        case GLYPH: {
+            color = draw_glyph(region, glyphs[i]);
         }
         default: {
             color = vec4(1.0, 0.0, 1.0, 1.0);
@@ -131,11 +192,12 @@ fn fs_main(
     }
     if in.mask_idx != 4294967295u {
         let mask = masks[in.mask_idx];
+        let mask_delta = resolve_move(mask.move_idx);
         let tl = UiVec2(vec2(mask.x.start.rel, mask.y.start.rel), vec2(mask.x.start.abs, mask.y.start.abs));
         let br = UiVec2(vec2(mask.x.end.rel, mask.y.end.rel), vec2(mask.x.end.abs, mask.y.end.abs));
 
-        let top_left = floor(tl.rel * window.dim) + floor(tl.abs);
-        let bot_right = floor(br.rel * window.dim) + floor(br.abs);
+        let top_left = floor(tl.rel * window.dim) + floor(tl.abs) + mask_delta;
+        let bot_right = floor(br.rel * window.dim) + floor(br.abs) + mask_delta;
         if pos.x < top_left.x || pos.x > bot_right.x || pos.y < top_left.y || pos.y > bot_right.y {
             color *= 0.0;
         }
@@ -143,9 +205,19 @@ fn fs_main(
     return color;
 }
 
-// TODO: this seems really inefficient (per frag indexing)?
-fn draw_texture(region: Region, info: TextureInfo) -> vec4<f32> {
-    return textureSample(views[info.view_idx], samplers[info.sampler_idx], region.uv);
+fn draw_texture(region: Region) -> vec4<f32> {
+    return textureSample(image_texture, samp, region.uv);
+}
+
+fn draw_glyph(region: Region, g: GlyphInfo) -> vec4<f32> {
+    let uv = mix(g.uv_min, g.uv_max, region.uv);
+    let texel = textureSample(atlas, samp, uv, i32(g.layer));
+    if (g.flags & 1u) != 0u {
+        return texel;
+    }
+    var color = unpack4x8unorm(g.color);
+    color.a *= texel.a;
+    return color;
 }
 
 fn draw_rounded_rect(region: Region, rect: Rect) -> vec4<f32> {

iris/core/src/render/texture.rs

@@ -1,59 +1,295 @@
-use image::{DynamicImage, EncodableLayout};
+use image::{DynamicImage, EncodableLayout, GenericImageView};
 use wgpu::{util::DeviceExt, *};
 
-use crate::{TextureUpdate, Textures};
+use crate::{PatchRect, TextureKind, TextureUpdate, Textures};
 
+use super::atlas::PAGE;
+
+/// What one texture slot is, GPU-side. Parallel to `Textures`' own slot
+/// numbering (`TextureKind`'s `Image`/`Page`), so a slot's index means the
+/// same thing on both sides without a second map to keep in sync.
+enum Slot {
+    /// A slot that was freed, or pushed and freed within the same batch
+    /// before ever reaching here.
+    Empty,
+    Image(ImageGpu),
+    /// The array layer a page occupies. Pages are never freed (see
+    /// `Textures::free`), so this is the only variant that outlives a `Free`.
+    Page(u32),
+}
+
+struct ImageGpu {
+    /// Kept alive alongside `view`/`bind_group`, which borrow from it only in
+    /// the sense that dropping this drops the GPU resource they point to.
+    #[allow(dead_code)]
+    texture: Texture,
+    view: TextureView,
+    bind_group: BindGroup,
+}
+
+/// Owns the two kinds of texture iris draws:
+///
+/// - **The glyph atlas**, one `texture_2d_array` whose layers are pages
+///   (`Slot::Page`), grown by recreating the array with headroom and
+///   `copy_texture_to_texture`-ing the old layers across. No feature beyond
+///   Vulkan 1.0/GLES sampling is needed for this -- a layer index is an
+///   ordinary sampling operand.
+/// - **Standalone images** (`Slot::Image`), each its own `Texture` and
+///   `BindGroup`, drawn one `draw()` call at a time with that bind group
+///   bound -- see `UiRenderNode::draw`.
+///
+/// See TEXTURES.md's "Recommended shape" for why, and RUST.md's
+/// "iris's binding array does not survive real Android hardware" for what
+/// this replaced (one giant `binding_array<texture_2d<f32>>` needing
+/// `VK_EXT_descriptor_indexing`, which a real share of Android GPUs lack).
 pub struct GpuTextures {
     device: Device,
     queue: Queue,
-    views: Vec<TextureView>,
-    view_count: usize,
-    samplers: Vec<Sampler>,
+
+    slots: Vec<Slot>,
+
+    array_texture: Texture,
+    array_view: TextureView,
+    array_capacity: u32,
+    /// Layers actually written. Only grows -- see `Slot::Page`.
+    page_count: u32,
+
+    sampler: Sampler,
+    /// Bound in the image slot of the main draw's bind group, which has
+    /// nothing of its own to put there: rects and glyphs never sample it,
+    /// but the layout requires something bound regardless.
     null_view: TextureView,
-    no_views: Vec<TextureView>,
+
+    /// Standalone-image bind groups actually built (`create_image`'s own
+    /// build, or one per slot touched by `rebuild_image_bind_groups`) since
+    /// the last `take_bind_group_creates`. IRIS_TODO.md's "many images"
+    /// benchmark reads this to prove the steady-state cost of an
+    /// unchanging image list is zero, the same way `UiRenderState`'s
+    /// `draw_count`/`region_mut_count` prove the layout side.
+    bind_group_creates: u64,
 }
 
 impl GpuTextures {
-    pub fn update(&mut self, textures: &mut Textures) -> bool {
-        let mut changed = false;
+    /// Applies queued `Textures` updates, then reports whether the *main*
+    /// bind group (the one rects and glyphs draw with) needs rebuilding --
+    /// true exactly when the atlas array was recreated (its view identity
+    /// changed). Pushing or freeing a standalone image never touches that
+    /// group: it built or drops its own. Masks/move_offsets resizing is
+    /// `UiRenderNode`'s own concern now (its `masks_group`, group 3) --
+    /// see that struct's field comment for why standalone images no longer
+    /// hear about either buffer at all.
+    pub fn update(&mut self, textures: &mut Textures, rsc_layout: &BindGroupLayout) -> bool {
+        let mut rebuild_main = false;
         for update in textures.updates() {
-            changed = true;
             match update {
-                TextureUpdate::Push(image) => self.push(image),
-                TextureUpdate::Set(i, image) => self.set(i, image),
-                TextureUpdate::SetFree => self.view_count += 1,
+                TextureUpdate::Push(kind, image) => {
+                    rebuild_main |= self.push(kind, image, rsc_layout);
+                }
+                TextureUpdate::Set(kind, i, image) => {
+                    rebuild_main |= self.set(kind, i, image, rsc_layout);
+                }
+                // A patch changes texture contents, not which layer or bind
+                // group exists, so it never asks for a rebuild -- rebuilding
+                // per glyph is exactly the cost this exists to avoid.
+                TextureUpdate::Patch(i, rect, image) => self.patch(i, rect, image),
+                TextureUpdate::SetFree => {}
                 TextureUpdate::Free(i) => self.free(i),
-                TextureUpdate::PushFree => self.push_free(),
+                TextureUpdate::PushFree(_kind) => self.slots.push(Slot::Empty),
             }
         }
-        changed
-    }
-    fn set(&mut self, i: u32, image: &DynamicImage) {
-        self.view_count += 1;
-        let view = self.create_view(image);
-        self.views[i as usize] = view;
-    }
-    fn free(&mut self, i: u32) {
-        self.view_count -= 1;
-        self.views[i as usize] = self.null_view.clone();
-    }
-    fn push(&mut self, image: &DynamicImage) {
-        self.view_count += 1;
-        let view = self.create_view(image);
-        self.views.push(view);
-    }
-    fn push_free(&mut self) {
-        self.view_count += 1;
-        self.views.push(self.null_view.clone());
+        rebuild_main
     }
 
-    fn create_view(&self, image: &DynamicImage) -> TextureView {
-        let image = image.to_rgba8();
-        let (width, height) = image.dimensions();
+    fn push(
+        &mut self,
+        kind: TextureKind,
+        image: &DynamicImage,
+        rsc_layout: &BindGroupLayout,
+    ) -> bool {
+        let (slot, rebuilt) = self.make_slot(kind, image, rsc_layout);
+        self.slots.push(slot);
+        rebuilt
+    }
+
+    fn set(
+        &mut self,
+        kind: TextureKind,
+        i: u32,
+        image: &DynamicImage,
+        rsc_layout: &BindGroupLayout,
+    ) -> bool {
+        let (slot, rebuilt) = self.make_slot(kind, image, rsc_layout);
+        self.slots[i as usize] = slot;
+        rebuilt
+    }
+
+    fn make_slot(
+        &mut self,
+        kind: TextureKind,
+        image: &DynamicImage,
+        rsc_layout: &BindGroupLayout,
+    ) -> (Slot, bool) {
+        match kind {
+            TextureKind::Image => {
+                let gpu = self.create_image(image, rsc_layout);
+                (Slot::Image(gpu), false)
+            }
+            TextureKind::Page { layer } => {
+                let mut rebuilt = false;
+                if layer >= self.array_capacity {
+                    self.grow_array(rsc_layout);
+                    rebuilt = true;
+                }
+                self.write_full_layer(layer, image);
+                self.page_count = self.page_count.max(layer + 1);
+                (Slot::Page(layer), rebuilt)
+            }
+        }
+    }
+
+    fn free(&mut self, i: u32) {
+        if let Some(slot) = self.slots.get_mut(i as usize) {
+            *slot = Slot::Empty;
+        }
+        // A page's layer is not reclaimed here either -- see `Slot::Page`.
+    }
+
+    fn patch(&mut self, i: u32, rect: PatchRect, image: &DynamicImage) {
+        let Some(&Slot::Page(layer)) = self.slots.get(i as usize) else {
+            return;
+        };
+        if rect.width == 0 || rect.height == 0 {
+            return;
+        }
+        // Cropped rather than written straight from the atlas, because
+        // write_texture wants tightly packed rows and the atlas rows are as
+        // wide as the atlas. A glyph is small, so the copy is too.
+        let sub = image
+            .view(rect.x, rect.y, rect.width, rect.height)
+            .to_image();
+        self.queue.write_texture(
+            TexelCopyTextureInfo {
+                texture: &self.array_texture,
+                mip_level: 0,
+                origin: Origin3d {
+                    x: rect.x,
+                    y: rect.y,
+                    z: layer,
+                },
+                aspect: TextureAspect::All,
+            },
+            sub.as_bytes(),
+            TexelCopyBufferLayout {
+                offset: 0,
+                bytes_per_row: Some(rect.width * 4),
+                rows_per_image: Some(rect.height),
+            },
+            Extent3d {
+                width: rect.width,
+                height: rect.height,
+                depth_or_array_layers: 1,
+            },
+        );
+    }
+
+    fn write_full_layer(&self, layer: u32, image: &DynamicImage) {
+        // Every page is created as exactly PAGE x PAGE (`GlyphAtlas::allocate`),
+        // so this is always a whole-layer write, never a crop.
+        let rgba = image.to_rgba8();
+        self.queue.write_texture(
+            TexelCopyTextureInfo {
+                texture: &self.array_texture,
+                mip_level: 0,
+                origin: Origin3d {
+                    x: 0,
+                    y: 0,
+                    z: layer,
+                },
+                aspect: TextureAspect::All,
+            },
+            rgba.as_bytes(),
+            TexelCopyBufferLayout {
+                offset: 0,
+                bytes_per_row: Some(PAGE * 4),
+                rows_per_image: Some(PAGE),
+            },
+            Extent3d {
+                width: PAGE,
+                height: PAGE,
+                depth_or_array_layers: 1,
+            },
+        );
+    }
+
+    /// Doubles the array's layer capacity (headroom, so this is rare) and
+    /// copies the old layers across GPU-side -- no readback. Recreates the
+    /// array's view, which invalidates every bind group that referenced it,
+    /// so this also rebuilds all of them before returning.
+    fn grow_array(&mut self, rsc_layout: &BindGroupLayout) {
+        let new_capacity = self.array_capacity * 2;
+        let new_texture = Self::create_array_texture(&self.device, new_capacity);
+        if self.page_count > 0 {
+            let mut encoder = self
+                .device
+                .create_command_encoder(&CommandEncoderDescriptor {
+                    label: Some("atlas array grow"),
+                });
+            encoder.copy_texture_to_texture(
+                TexelCopyTextureInfo {
+                    texture: &self.array_texture,
+                    mip_level: 0,
+                    origin: Origin3d::ZERO,
+                    aspect: TextureAspect::All,
+                },
+                TexelCopyTextureInfo {
+                    texture: &new_texture,
+                    mip_level: 0,
+                    origin: Origin3d::ZERO,
+                    aspect: TextureAspect::All,
+                },
+                Extent3d {
+                    width: PAGE,
+                    height: PAGE,
+                    depth_or_array_layers: self.page_count,
+                },
+            );
+            self.queue.submit(std::iter::once(encoder.finish()));
+        }
+        self.array_texture = new_texture;
+        self.array_view = self.array_texture.create_view(&TextureViewDescriptor {
+            dimension: Some(TextureViewDimension::D2Array),
+            ..Default::default()
+        });
+        self.array_capacity = new_capacity;
+        self.rebuild_image_bind_groups(rsc_layout);
+    }
+
+    /// Called only from `grow_array`: the atlas array's view identity is the
+    /// one thing an image's bind group (group 2) still names that can
+    /// change out from under it. Masks/move_offsets resizing no longer
+    /// reaches here at all -- see `UiRenderNode::masks_group`.
+    fn rebuild_image_bind_groups(&mut self, rsc_layout: &BindGroupLayout) {
+        for slot in &mut self.slots {
+            if let Slot::Image(gpu) = slot {
+                gpu.bind_group = Self::make_image_bind_group(
+                    &self.device,
+                    rsc_layout,
+                    &self.array_view,
+                    &gpu.view,
+                    &self.sampler,
+                );
+                self.bind_group_creates += 1;
+            }
+        }
+    }
+
+    fn create_image(&mut self, image: &DynamicImage, rsc_layout: &BindGroupLayout) -> ImageGpu {
+        let rgba = image.to_rgba8();
+        let (width, height) = rgba.dimensions();
         let texture = self.device.create_texture_with_data(
             &self.queue,
             &TextureDescriptor {
-                label: None,
+                label: Some("image"),
                 size: Extent3d {
                     width,
                     height,
@@ -63,45 +299,147 @@ impl GpuTextures {
                 sample_count: 1,
                 dimension: TextureDimension::D2,
                 format: TextureFormat::Rgba8Unorm,
-                usage: TextureUsages::TEXTURE_BINDING,
+                usage: TextureUsages::TEXTURE_BINDING | TextureUsages::COPY_DST,
                 view_formats: &[],
             },
             wgt::TextureDataOrder::MipMajor,
-            image.as_bytes(),
+            rgba.as_bytes(),
         );
-        texture.create_view(&TextureViewDescriptor::default())
+        let view = texture.create_view(&TextureViewDescriptor::default());
+        let bind_group = Self::make_image_bind_group(
+            &self.device,
+            rsc_layout,
+            &self.array_view,
+            &view,
+            &self.sampler,
+        );
+        self.bind_group_creates += 1;
+        ImageGpu {
+            texture,
+            view,
+            bind_group,
+        }
+    }
+
+    /// Builds group 2 for one standalone image: the shared atlas array, this
+    /// image's own view and the shared sampler -- the same layout the main
+    /// draw uses with a null view in the image slot. Deliberately does not
+    /// touch masks/move_offsets (group 3, `UiRenderNode::masks_group`): see
+    /// that field's comment for why folding them in here was the bug.
+    fn make_image_bind_group(
+        device: &Device,
+        rsc_layout: &BindGroupLayout,
+        array_view: &TextureView,
+        image_view: &TextureView,
+        sampler: &Sampler,
+    ) -> BindGroup {
+        device.create_bind_group(&BindGroupDescriptor {
+            layout: rsc_layout,
+            entries: &[
+                BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(array_view),
+                },
+                BindGroupEntry {
+                    binding: 1,
+                    resource: BindingResource::TextureView(image_view),
+                },
+                BindGroupEntry {
+                    binding: 2,
+                    resource: BindingResource::Sampler(sampler),
+                },
+            ],
+            label: Some("ui rsc image"),
+        })
+    }
+
+    fn create_array_texture(device: &Device, capacity: u32) -> Texture {
+        device.create_texture(&TextureDescriptor {
+            label: Some("glyph atlas array"),
+            size: Extent3d {
+                width: PAGE,
+                height: PAGE,
+                depth_or_array_layers: capacity,
+            },
+            mip_level_count: 1,
+            sample_count: 1,
+            dimension: TextureDimension::D2,
+            format: TextureFormat::Rgba8Unorm,
+            usage: TextureUsages::TEXTURE_BINDING
+                | TextureUsages::COPY_DST
+                | TextureUsages::COPY_SRC,
+            view_formats: &[],
+        })
     }
 
     pub fn new(device: &Device, queue: &Queue) -> Self {
+        let sampler = default_sampler(device);
         let null_view = null_texture_view(device);
+        let array_capacity = 1;
+        let array_texture = Self::create_array_texture(device, array_capacity);
+        let array_view = array_texture.create_view(&TextureViewDescriptor {
+            dimension: Some(TextureViewDimension::D2Array),
+            ..Default::default()
+        });
         Self {
             device: device.clone(),
             queue: queue.clone(),
-            views: Vec::new(),
-            samplers: vec![default_sampler(device)],
-            no_views: vec![null_view.clone()],
+            slots: Vec::new(),
+            array_texture,
+            array_view,
+            array_capacity,
+            page_count: 0,
+            sampler,
             null_view,
-            view_count: 0,
+            bind_group_creates: 0,
         }
     }
 
-    pub fn views(&self) -> Vec<&TextureView> {
-        if self.views.is_empty() {
-            &self.no_views
-        } else {
-            &self.views
-        }
-        .iter()
-        .by_ref()
-        .collect()
+    /// Reads and zeroes the standalone-image bind-group creation counter --
+    /// call once per frame before `update()`, mirroring
+    /// `UiRenderState::take_counters`.
+    pub fn take_bind_group_creates(&mut self) -> u64 {
+        std::mem::take(&mut self.bind_group_creates)
     }
 
-    pub fn samplers(&self) -> Vec<&Sampler> {
-        self.samplers.iter().by_ref().collect()
+    pub fn array_view(&self) -> &TextureView {
+        &self.array_view
+    }
+
+    pub fn null_view(&self) -> &TextureView {
+        &self.null_view
+    }
+
+    pub fn sampler(&self) -> &Sampler {
+        &self.sampler
+    }
+
+    /// The bind group a standalone image draws with. Panics if `idx` names an
+    /// atlas page or a freed slot instead -- either is a caller bug (the
+    /// wrong kind of instance reached this draw path), not a condition to
+    /// recover from.
+    pub fn image_bind_group(&self, idx: u32) -> &BindGroup {
+        match self.slots.get(idx as usize) {
+            Some(Slot::Image(gpu)) => &gpu.bind_group,
+            other => panic!("texture slot {idx} is not a live standalone image: {other:?}"),
+        }
     }
 
     pub fn view_count(&self) -> usize {
-        self.view_count
+        self.slots
+            .iter()
+            .filter(|s| !matches!(s, Slot::Empty))
+            .count()
+    }
+}
+
+impl std::fmt::Debug for Slot {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Slot::Empty => write!(f, "Empty"),
+            Slot::Image(_) => write!(f, "Image"),
+            Slot::Page(layer) => write!(f, "Page(layer={layer})"),
+        }
     }
 }
 

iris/core/src/render/util/mod.rs

@@ -21,13 +21,18 @@ impl<T: Pod> ArrBuf<T> {
             _pd: PhantomData,
         }
     }
-    pub fn update(&mut self, device: &Device, queue: &Queue, data: &[T]) {
-        if self.len != data.len() {
+    /// Returns whether the underlying `Buffer` was recreated -- a caller that
+    /// cached a `BindGroup` referencing it (as `GpuTextures` does for the
+    /// masks buffer) needs to know to rebuild that too.
+    pub fn update(&mut self, device: &Device, queue: &Queue, data: &[T]) -> bool {
+        let resized = self.len != data.len();
+        if resized {
             self.len = data.len();
             self.buffer =
                 Self::init_buf(device, std::mem::size_of_val(data), self.usage, self.label);
         }
         queue.write_buffer(&self.buffer, 0, bytemuck::cast_slice(data));
+        resized
     }
     fn init_buf(device: &Device, size: usize, usage: BufferUsages, label: &'static str) -> Buffer {
         let mut size = size as u64;

iris/core/src/ui/access.rs

@@ -0,0 +1,152 @@
+//! I4 (RUST.md): an AccessKit tree built from iris's own widget tree,
+//! shared by both backends -- `android/view.rs` pushes its `TreeUpdate`s
+//! through `accesskit_android::Adapter`, `default/mod.rs` through
+//! `accesskit_winit::Adapter`. Kept modular the way input's sense registry
+//! is: `Widgets::named()` is a side set populated only by `.label()`, so a
+//! widget nobody named is never visited here at all, not even to decide it
+//! has no name.
+//!
+//! The tree itself is deliberately flat -- one synthetic `Role::Window`
+//! root with every named widget as a direct child, in no particular order.
+//! iris's actual widget nesting (a label three `Span`s deep inside a
+//! `Scroll`) carries no accessibility meaning of its own here: nothing
+//! upstream of a named leaf needs a node, since a screen reader's own
+//! traversal (and uiautomator's tap-by-name, the pass condition this was
+//! built for) works from each node's on-screen bounds rather than from
+//! tree structure. Mirroring the real widget tree exactly would also mean
+//! rebuilding intermediate nodes whenever *any* container above a named
+//! widget resizes, which is most frames -- the flat shape is what keeps
+//! rebuilds tied to "a name, a role or a position actually changed".
+
+use crate::{PixelRegion, UiRenderState, UiRsc, WidgetId, Widgets, util::HashMap};
+use accesskit::{Node, NodeId, Rect, Role, TreeId, TreeInfo, TreeUpdate};
+
+/// Reserved for the synthetic root; every real widget's `SlotId::as_u64`
+/// starts at 1, so this can never collide with one (see that method's
+/// doc comment).
+const WINDOW_NODE: NodeId = NodeId(0);
+
+fn node_id(id: WidgetId) -> NodeId {
+    NodeId(id.as_u64())
+}
+
+#[derive(Clone, PartialEq)]
+struct Entry {
+    name: String,
+    role: Role,
+    bounds: PixelRegion,
+}
+
+fn entry_node(entry: &Entry) -> Node {
+    let mut node = Node::new(entry.role);
+    node.set_label(entry.name.clone());
+    node.set_bounds(Rect {
+        x0: entry.bounds.top_left.x as f64,
+        y0: entry.bounds.top_left.y as f64,
+        x1: entry.bounds.bot_right.x as f64,
+        y1: entry.bounds.bot_right.y as f64,
+    });
+    node
+}
+
+/// Owns the last tree pushed out, so `update` can tell "nothing
+/// accessibility-relevant changed" from "something did" without asking
+/// the platform adapter to diff two `Node`s itself. One of these per
+/// window/view -- `default::DefaultUiState` and `android::AndroidUiState`
+/// each keep one.
+#[derive(Default)]
+pub struct AccessTree {
+    known: HashMap<WidgetId, Entry>,
+    /// `TreeUpdate`s actually produced since the last `take_rebuilds` --
+    /// the AccessKit-tree twin of `UiRenderState::take_counters`. Should
+    /// stay at 0 across an unchanged frame and move by exactly 1 when a
+    /// named widget's position, name or role changes, however many other
+    /// widgets are on screen; see `iris/src/access_tests.rs`.
+    rebuilds: u64,
+}
+
+impl AccessTree {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    fn collect(
+        widgets: &Widgets,
+        render: &UiRenderState,
+        rsc: &dyn UiRsc,
+    ) -> HashMap<WidgetId, Entry> {
+        let mut current = HashMap::default();
+        for id in widgets.named() {
+            let Some(bounds) = render.window_region(&id, rsc) else {
+                continue;
+            };
+            let Some(widget) = widgets.get_dyn(id) else {
+                continue;
+            };
+            current.insert(
+                id,
+                Entry {
+                    name: widgets.label(id).clone(),
+                    role: widget.access_role(),
+                    bounds,
+                },
+            );
+        }
+        current
+    }
+
+    /// Walks `widgets.named()`, looks up each one's current screen bounds
+    /// via `render.window_region` (which resolves the same move-chain
+    /// `resolved_region` does, so a moved subtree reports where it
+    /// actually is), and returns a full `TreeUpdate` if and only if that
+    /// set differs from the last call -- added, removed, renamed, or
+    /// moved/resized. A widget that is named but not currently active
+    /// (not drawn this frame) is left out, the same as one never named at
+    /// all.
+    pub fn update(
+        &mut self,
+        widgets: &Widgets,
+        render: &UiRenderState,
+        rsc: &dyn UiRsc,
+    ) -> Option<TreeUpdate> {
+        let current = Self::collect(widgets, render, rsc);
+        if current == self.known {
+            return None;
+        }
+        self.known = current.clone();
+        self.rebuilds += 1;
+        Some(build_update(&current))
+    }
+
+    /// The unconditional twin of `update`, for a platform adapter's
+    /// activation handler (`android/access.rs`'s `AndroidAccessSource`) --
+    /// AccessKit asks for a full tree the first time a client attaches,
+    /// which is exactly the case `update`'s diff-against-`known` is not
+    /// meant to answer (it may have already sent this same snapshot to a
+    /// client that has since detached and reattached).
+    pub fn build_full(widgets: &Widgets, render: &UiRenderState, rsc: &dyn UiRsc) -> TreeUpdate {
+        build_update(&Self::collect(widgets, render, rsc))
+    }
+
+    /// Reads and zeroes the rebuild counter, the same call shape as
+    /// `UiRenderState::take_counters`.
+    pub fn take_rebuilds(&mut self) -> u64 {
+        std::mem::take(&mut self.rebuilds)
+    }
+}
+
+fn build_update(current: &HashMap<WidgetId, Entry>) -> TreeUpdate {
+    let mut window = Node::new(Role::Window);
+    let mut nodes = Vec::with_capacity(current.len() + 1);
+    for (&id, entry) in current {
+        window.push_child(node_id(id));
+        nodes.push((node_id(id), entry_node(entry)));
+    }
+    nodes.push((WINDOW_NODE, window));
+    TreeUpdate {
+        nodes,
+        tree: Some(TreeInfo::new(WINDOW_NODE)),
+        tree_id: TreeId::ROOT,
+        focus: WINDOW_NODE,
+    }
+}

iris/core/src/ui/active.rs

@@ -1,4 +1,4 @@
-use crate::{LayerId, MaskIdx, PrimitiveHandle, TextureHandle, UiRegion, WidgetId};
+use crate::{LayerId, MaskIdx, MoveIdx, PrimitiveHandle, Size, TextureHandle, UiRegion, WidgetId};
 
 /// important non rendering data for retained drawing
 #[derive(Debug)]
@@ -11,4 +11,14 @@ pub struct ActiveData {
     pub children: Vec<WidgetId>,
     pub mask: MaskIdx,
     pub layer: LayerId,
+    /// What `Widget::draw` returned the last time this widget was actually
+    /// drawn -- read by a parent placing this widget again without
+    /// redrawing it, replacing `Cache.size`'s old role. See LAYOUT.md
+    /// section 5.
+    pub size: Size,
+    /// This widget's slot in `UiData::move_offsets`, assigned on its first
+    /// draw and kept for the rest of its life (redraws reuse it in place
+    /// so a retained child's `parent` link never goes stale). See
+    /// LAYOUT.md section 2.
+    pub move_slot: MoveIdx,
 }

iris/core/src/ui/cache.rs

@@ -1,18 +0,0 @@
-use crate::{BothAxis, Len, UiVec2, WidgetId, util::HashMap};
-
-#[derive(Default)]
-pub struct Cache {
-    pub size: BothAxis<HashMap<WidgetId, (UiVec2, Len)>>,
-}
-
-impl Cache {
-    pub fn remove(&mut self, id: WidgetId) {
-        self.size.x.remove(&id);
-        self.size.y.remove(&id);
-    }
-
-    pub fn clear(&mut self) {
-        self.size.x.clear();
-        self.size.y.clear();
-    }
-}

iris/core/src/ui/mod.rs

@@ -1,15 +1,16 @@
-use crate::{Mask, TextData, Textures, WeakWidget, WidgetId, Widgets, util::TrackedArena};
+use crate::{
+    Mask, MoveOffset, TextData, Textures, WeakWidget, WidgetId, Widgets, util::TrackedArena,
+};
 
+mod access;
 mod active;
-mod cache;
 mod painter;
 mod render_state;
-mod size;
 
+pub use access::*;
 pub use active::*;
 pub use painter::Painter;
 pub use render_state::*;
-pub use size::*;
 
 #[derive(Default)]
 pub struct UiData {
@@ -17,6 +18,12 @@ pub struct UiData {
     pub textures: Textures,
     pub text: TextData,
     pub masks: TrackedArena<Mask, u32>,
+    /// One entry per widget ever drawn, forming the parent-linked chain
+    /// `resolve_move` walks in both shader stages. Allocated once on a
+    /// widget's first draw and reused for every later redraw of the same
+    /// id (never reallocated), so a retained descendant's `parent` index
+    /// never goes stale -- see LAYOUT.md section 2.
+    pub move_offsets: TrackedArena<MoveOffset, u32>,
 }
 
 pub trait UiRsc {

iris/core/src/ui/painter.rs

@@ -1,7 +1,7 @@
 use crate::{
-    Axis, Len, RenderedText, Size, SizeCtx, StrongWidget, TextAttrs, TextBuffer, TextData,
-    TextureHandle, UiRegion, UiRenderState, UiRsc, Widget, WidgetId,
-    render::{Mask, MaskIdx, Primitive, PrimitiveHandle, PrimitiveInst},
+    RenderedText, Size, StrongWidget, TextAttrs, TextBuffer, TextData, TextureHandle, UiRegion,
+    UiRenderState, UiRsc, UiScalar, UiVec2, WidgetId,
+    render::{GlyphPrimitive, Mask, MaskIdx, MoveIdx, Primitive, PrimitiveHandle, PrimitiveInst},
     util::Vec2,
 };
 
@@ -12,6 +12,7 @@ pub struct Painter<'a> {
 
     pub(super) region: UiRegion,
     pub(super) mask: MaskIdx,
+    pub(super) move_slot: MoveIdx,
     pub(super) textures: Vec<TextureHandle>,
     pub(super) primitives: Vec<PrimitiveHandle>,
     pub(super) children: Vec<WidgetId>,
@@ -28,6 +29,7 @@ impl<'a> Painter<'a> {
                 primitive,
                 region,
                 mask_idx: self.mask,
+                move_idx: self.move_slot,
             },
         );
         if self.mask != MaskIdx::NONE {
@@ -48,69 +50,162 @@ impl<'a> Painter<'a> {
 
     pub fn set_mask(&mut self, region: UiRegion) {
         assert!(self.mask == MaskIdx::NONE);
-        self.mask = self.rsc.ui_mut().masks.push(Mask { region });
+        self.mask = self.rsc.ui_mut().masks.push(Mask {
+            region,
+            move_idx: self.move_slot,
+        });
     }
 
-    /// Draws a widget within this widget's region.
-    pub fn widget<W: ?Sized>(&mut self, id: &StrongWidget<W>) {
-        self.widget_at(id, self.region);
+    /// Draws a widget within this widget's region, returning the size it
+    /// reported using.
+    pub fn widget<W: ?Sized>(&mut self, id: &StrongWidget<W>) -> Size {
+        self.widget_at(id, self.region)
     }
 
     /// Draws a widget somewhere within this one.
     /// Useful for drawing child widgets in select areas.
-    pub fn widget_within<W: ?Sized>(&mut self, id: &StrongWidget<W>, region: UiRegion) {
-        self.widget_at(id, region.within(&self.region));
+    pub fn widget_within<W: ?Sized>(&mut self, id: &StrongWidget<W>, region: UiRegion) -> Size {
+        self.widget_at(id, region.within(&self.region))
     }
 
-    fn widget_at<W: ?Sized>(&mut self, id: &StrongWidget<W>, region: UiRegion) {
+    fn widget_at<W: ?Sized>(&mut self, id: &StrongWidget<W>, region: UiRegion) -> Size {
         self.children.push(id.id());
+        // Passed directly rather than looked up from `self.active`: this
+        // widget's own `ActiveData` (which would carry its `move_slot`) is
+        // not inserted there until *after* its own `Widget::draw` returns,
+        // so a lookup here -- for a child drawn partway through that same
+        // call -- would always find nothing. `self.move_slot` is this
+        // widget's own slot, already known, and always correct regardless
+        // of insertion order. See `UiRenderState::move_parent_of`.
         self.state.draw_inner(
             self.layer,
             id.id(),
             region,
             Some(self.id),
+            self.move_slot.idx() as u32,
             self.mask,
             None,
+            None,
             self.rsc,
         );
+        self.state
+            .active
+            .get(&id.id())
+            .map(|a| a.size)
+            .unwrap_or_default()
+    }
+
+    /// Move an already-drawn child from wherever it currently sits to
+    /// `region` (resolved against this widget's own region, matching
+    /// `widget_within`) without a second draw -- an O(1) offset write via
+    /// `UiRenderState::mov`. For a container that draws a child
+    /// provisionally to learn its size (e.g. `Aligned`) and then places it
+    /// for real. Only valid when the target keeps the child's drawn size;
+    /// if the shape actually changes, the normal `widget_within` dispatch
+    /// (which detects that from the stored region) does the right thing
+    /// instead.
+    pub fn reposition<W: ?Sized>(&mut self, id: &StrongWidget<W>, region: UiRegion) {
+        let region = region.within(&self.region);
+        self.state.reposition(id.id(), region, self.rsc);
+    }
+
+    /// Draw `child` at a provisional region to learn its size under one
+    /// axis's worth of assumption, discard everything it wrote, then draw
+    /// it again at the region that assumption produced. For the rare
+    /// parent that cannot pick an offered size without already knowing the
+    /// answer. Twice the cost of one `draw`; every other case in this file
+    /// avoids it.
+    pub fn draw_twice<W: ?Sized>(
+        &mut self,
+        id: &StrongWidget<W>,
+        first: UiRegion,
+        second: impl FnOnce(Size) -> UiRegion,
+    ) -> Size {
+        let used = self.widget_within(id, first);
+        let region = second(used);
+        self.widget_within(id, region)
     }
 
     pub fn texture_within(&mut self, handle: &TextureHandle, region: UiRegion) {
         self.textures.push(handle.clone());
-        self.primitive_at(handle.primitive(), region.within(&self.region));
+        self.write_image(handle.image_index(), region.within(&self.region));
     }
 
     pub fn texture(&mut self, handle: &TextureHandle) {
         self.textures.push(handle.clone());
-        self.primitive(handle.primitive());
+        self.write_image(handle.image_index(), self.region);
     }
 
     pub fn texture_at(&mut self, handle: &TextureHandle, region: UiRegion) {
         self.textures.push(handle.clone());
-        self.primitive_at(handle.primitive(), region);
+        self.write_image(handle.image_index(), region);
     }
 
-    /// returns (handle, offset from top left)
-    pub fn render_text(&mut self, buffer: &mut TextBuffer, attrs: &TextAttrs) -> RenderedText {
+    /// A standalone image draws with its own bind group rather than sharing
+    /// the layer's one instanced draw, so it goes through
+    /// `Primitives::write_image` instead of `primitive_at`/`Primitive::vec`.
+    fn write_image(&mut self, texture_idx: u32, region: UiRegion) {
+        let h = self.state.layers.write_image(
+            self.layer,
+            self.id,
+            texture_idx,
+            region,
+            self.mask,
+            self.move_slot,
+        );
+        if self.mask != MaskIdx::NONE {
+            self.rsc.ui_mut().masks.push_ref(self.mask);
+        }
+        self.primitives.push(h);
+    }
+
+    pub fn render_text(
+        &mut self,
+        buffer: &mut TextBuffer,
+        attrs: &TextAttrs,
+        width: Option<f32>,
+    ) -> RenderedText {
         let ui = self.rsc.ui_mut();
-        ui.text.draw(buffer, attrs, &mut ui.textures)
+        ui.text.render(buffer, attrs, width, &mut ui.textures)
+    }
+
+    /// Draw a laid-out string: one quad per glyph, all sampling the atlas.
+    ///
+    /// `origin` is where the text's top-left goes; every glyph is placed at an
+    /// absolute pixel offset from it, so re-drawing after a resize is this loop
+    /// and nothing else.
+    pub fn glyphs(&mut self, text: &RenderedText, origin: UiRegion) {
+        let flags_for = |is_color| {
+            if is_color {
+                GlyphPrimitive::IS_COLOR
+            } else {
+                0
+            }
+        };
+        for glyph in text.glyphs.iter() {
+            let mut region = origin;
+            region.x.end = region.x.start;
+            region.y.end = region.y.start;
+            let mut region = region.offset(UiVec2::abs(glyph.offset));
+            region.x.end = region.x.start + UiScalar::abs(glyph.entry.width as f32);
+            region.y.end = region.y.start + UiScalar::abs(glyph.entry.height as f32);
+            self.primitive_at(
+                GlyphPrimitive::new(
+                    glyph.entry.uv_min,
+                    glyph.entry.uv_max,
+                    glyph.entry.layer,
+                    glyph.color,
+                    flags_for(glyph.entry.is_color),
+                ),
+                region,
+            );
+        }
     }
 
     pub fn region(&self) -> UiRegion {
         self.region
     }
 
-    pub fn size<W: ?Sized + Widget>(&mut self, id: &StrongWidget<W>) -> Size {
-        self.size_ctx().size(id)
-    }
-
-    pub fn len_axis<W: ?Sized + Widget>(&mut self, id: &StrongWidget<W>, axis: Axis) -> Len {
-        match axis {
-            Axis::X => self.size_ctx().width(id),
-            Axis::Y => self.size_ctx().height(id),
-        }
-    }
-
     pub fn output_size(&self) -> Vec2 {
         self.state.output_size
     }
@@ -138,8 +233,4 @@ impl<'a> Painter<'a> {
     pub fn id(&self) -> &WidgetId {
         &self.id
     }
-
-    pub fn size_ctx(&mut self) -> SizeCtx<'_> {
-        self.state.size_ctx(self.id, self.region.size(), self.rsc)
-    }
 }

iris/core/src/ui/render_state.rs

@@ -1,34 +1,60 @@
 use crate::{
-    ActiveData, Axis, IdLike, MaskIdx, Painter, PixelRegion, PrimitiveLayers, SizeCtx,
+    ActiveData, IdLike, MaskIdx, MoveIdx, Painter, PixelRegion, PrimitiveLayers, RegionAlign,
     StrongWidget, UiRegion, UiRsc, UiVec2, WidgetId, Widgets,
-    ui::cache::Cache,
-    util::{HashMap, HashSet, Vec2, forget_ref},
+    render::MoveOffset,
+    util::{HashMap, HashSet, Id, Vec2},
 };
 
 pub struct UiRenderState {
     pub active: HashMap<WidgetId, ActiveData>,
     pub layers: PrimitiveLayers,
     pub(super) output_size: Vec2,
-    pub cache: Cache,
 
     old_root: Option<WidgetId>,
     resized: bool,
     draw_started: HashSet<WidgetId>,
+
+    /// `Widget::draw` calls and `Primitives::region_mut` rewrites since the
+    /// last `take_counters`. LAYOUT.md section 8's pass conditions are
+    /// stated in terms of these two: an unchanged frame must cost 0 of
+    /// each, and moving one widget must cost 0 draws and 0 rewrites
+    /// regardless of how many primitives are in its subtree.
+    draw_count: u64,
+    region_mut_count: u64,
+    mov_count: u64,
 }
 
+/// A move chain more than this deep would mean something else is wrong
+/// (an accidental cycle) -- see `resolve_move` in shader.wgsl, which walks
+/// the identical bound and must be kept in step with this constant.
+pub const MOVE_CHAIN_LIMIT: usize = 16;
+
 impl UiRenderState {
     pub fn new() -> Self {
         Self {
             active: Default::default(),
             layers: Default::default(),
-            cache: Default::default(),
             output_size: Vec2::ZERO,
             old_root: None,
             resized: false,
             draw_started: Default::default(),
+            draw_count: 0,
+            region_mut_count: 0,
+            mov_count: 0,
         }
     }
 
+    /// Reads and zeroes the (draws, region_mut rewrites, move_offsets
+    /// writes) counters -- call once per frame before `update()` to
+    /// measure exactly that frame, per LAYOUT.md section 8.
+    pub fn take_counters(&mut self) -> (u64, u64, u64) {
+        (
+            std::mem::take(&mut self.draw_count),
+            std::mem::take(&mut self.region_mut_count),
+            std::mem::take(&mut self.mov_count),
+        )
+    }
+
     pub fn resize(&mut self, size: impl Into<Vec2>) {
         self.output_size = size.into();
         self.resized = true;
@@ -65,10 +91,37 @@ impl UiRenderState {
         self.clear(rsc);
         // free all resources & cache
         if let Some(id) = root {
-            self.draw_inner(0, id.id(), UiRegion::FULL, None, MaskIdx::NONE, None, rsc);
+            self.draw_inner(
+                0,
+                id.id(),
+                UiRegion::FULL,
+                None,
+                MoveOffset::NONE_PARENT,
+                MaskIdx::NONE,
+                None,
+                None,
+                rsc,
+            );
         }
     }
 
+    /// The slot an *already-active* widget's `move_offsets` entry chains
+    /// to, read back from `self.active`. Only valid where the parent is
+    /// guaranteed to already be in `self.active` -- true for `redraw()`,
+    /// which targets a widget that was fully drawn on some earlier update,
+    /// but **not** for a widget being drawn as part of its own parent's
+    /// `Widget::draw` call: that parent's `ActiveData` is not inserted
+    /// until its `draw` returns (below), so a child drawn partway through
+    /// it would always read back "no parent" here. `Painter::widget_at`
+    /// avoids that trap by passing its own already-known `move_slot`
+    /// straight through instead of asking `self.active` to look it up.
+    fn move_parent_of(&self, parent: Option<WidgetId>) -> u32 {
+        parent
+            .and_then(|p| self.active.get(&p))
+            .map(|p| p.move_slot.idx() as u32)
+            .unwrap_or(MoveOffset::NONE_PARENT)
+    }
+
     // TODO: should prolly make a DrawInfo struct or smth for everything other than rsc
     #[allow(clippy::too_many_arguments)]
     pub(super) fn draw_inner(
@@ -77,11 +130,14 @@ impl UiRenderState {
         id: WidgetId,
         region: UiRegion,
         parent: Option<WidgetId>,
+        parent_move_slot: u32,
         mask: MaskIdx,
         old_children: Option<Vec<WidgetId>>,
+        old_move_slot: Option<MoveIdx>,
         rsc: &mut dyn UiRsc,
     ) {
         let mut old_children = old_children.unwrap_or_default();
+        let mut old_move_slot = old_move_slot;
         if let Some(active) = self.active.get_mut(&id)
             && !rsc.widgets().needs_redraw.contains(&id)
         {
@@ -91,21 +147,69 @@ impl UiRenderState {
             } else if active.region.size() == region.size() {
                 // TODO: epsilon?
                 let from = active.region;
-                self.mov(id, from, region);
+                self.mov(id, from, region, rsc);
+                return;
+            } else if rsc
+                .widgets()
+                .get_dyn(id)
+                .map(|w| w.is_size_independent())
+                .unwrap_or(false)
+            {
+                // The offered region changed shape, but this widget's own
+                // drawn output does not depend on it (a fixed-size leaf) --
+                // rewrite its own primitives' regions in place (O(primitives
+                // owned directly by this widget, which for a leaf is O(1))
+                // instead of redrawing. See LAYOUT.md section 3.
+                let from = active.region;
+                for h in &active.primitives {
+                    let r = self.layers[h.layer].region_mut(h);
+                    *r = r.outside(&from).within(&region);
+                    self.region_mut_count += 1;
+                }
+                active.region = region;
                 return;
             }
             // if not, then maintain resize and track old children to remove unneeded
             let active = self.remove(id, false, rsc).unwrap();
             old_children = active.children;
+            old_move_slot = Some(active.move_slot);
         }
 
         // draw widget
         self.draw_started.insert(id);
 
+        let move_slot = match old_move_slot {
+            // Reused across a real redraw of the same id: the fresh
+            // geometry this draw is about to write is placed at its
+            // correct absolute position by `region` itself, so any delta
+            // accumulated before this redraw is now stale and would
+            // double-offset it if left in place. The chain link (`parent`)
+            // is untouched -- the logical parent has not changed.
+            Some(slot) => {
+                let entry = rsc.ui_mut().move_offsets.get_mut(slot);
+                entry.delta = [0.0, 0.0];
+                slot
+            }
+            None => {
+                let slot = rsc
+                    .ui_mut()
+                    .move_offsets
+                    .push(MoveOffset::new([0.0, 0.0], parent_move_slot));
+                rsc.ui_mut().move_offsets.push_ref(slot);
+                if parent_move_slot != MoveOffset::NONE_PARENT {
+                    rsc.ui_mut()
+                        .move_offsets
+                        .push_ref(Id::preset(parent_move_slot));
+                }
+                slot
+            }
+        };
+
         let mut painter = Painter {
             state: self,
             region,
             mask,
+            move_slot,
             layer,
             id,
             textures: Vec::new(),
@@ -115,7 +219,8 @@ impl UiRenderState {
         };
 
         let mut widget = painter.rsc.widgets().get_dyn_dynamic(id);
-        widget.draw(&mut painter);
+        painter.state.draw_count += 1;
+        let size = widget.draw(&mut painter);
         drop(widget);
 
         let Painter {
@@ -123,6 +228,7 @@ impl UiRenderState {
             rsc: _,
             region,
             mask,
+            move_slot,
             textures,
             primitives,
             children,
@@ -140,6 +246,8 @@ impl UiRenderState {
             children,
             mask,
             layer,
+            size,
+            move_slot,
         };
 
         // remove old children that weren't kept
@@ -153,18 +261,66 @@ impl UiRenderState {
         self.active.insert(id, active);
     }
 
-    fn mov(&mut self, id: WidgetId, from: UiRegion, to: UiRegion) {
-        let active = self.active.get_mut(&id).unwrap();
-        for h in &active.primitives {
-            let region = self.layers[h.layer].region_mut(h);
-            *region = region.outside(&from).within(&to);
-        }
-        active.region = active.region.outside(&from).within(&to);
-        // SAFETY: children cannot be recursive
-        let children = unsafe { forget_ref(&active.children) };
-        for child in children {
-            self.mov(*child, from, to);
-        }
+    /// O(1): write the delta for this widget's own slot in
+    /// `move_offsets`. No primitive is touched and there is no recursion --
+    /// every descendant's primitive references this slot transitively
+    /// through the parent chain the shader walks (`resolve_move`), so it
+    /// picks the new delta up for free. See LAYOUT.md section 2.
+    fn mov(&mut self, id: WidgetId, from: UiRegion, to: UiRegion, rsc: &mut dyn UiRsc) {
+        let Some(active) = self.active.get_mut(&id) else {
+            return;
+        };
+        let slot = active.move_slot;
+        active.region = to;
+        let from_px = from.top_left().to_abs(self.output_size);
+        let to_px = to.top_left().to_abs(self.output_size);
+        let delta = to_px - from_px;
+        let entry = rsc.ui_mut().move_offsets.get_mut(slot);
+        entry.delta[0] += delta.x;
+        entry.delta[1] += delta.y;
+        self.mov_count += 1;
+    }
+
+    /// Move an already-active widget to `to`. Used by `Painter::reposition`,
+    /// for a parent that drew a child provisionally (at the whole region it
+    /// was offered) and now knows where the child actually belongs.
+    ///
+    /// Unlike `mov` (called by `draw_inner`'s own dispatch, where the
+    /// *offered* region really did move and `active.region` already tracks
+    /// it), the child here was not offered a smaller region -- it was
+    /// offered everything and chose, on its own, to occupy only
+    /// `active.size` of it. By convention every widget in this crate that
+    /// does that anchors its own content at the top-left of whatever it
+    /// was given (`Rect`/`Image`/`Sized`/`MaxSize` -- see their `draw`
+    /// bodies), so that is where this assumes the child was actually
+    /// painted, not `active.region` itself (which is the *offered* box,
+    /// usually bigger). A nested `Aligned` whose own child is not top-left
+    /// anchored -- i.e. `Aligned` wrapping `Aligned` -- is the one shape
+    /// this does not cover; none of iris's widgets or examples build that
+    /// today. See LAYOUT.md's "Rejected, and why" / deviations for the
+    /// full reasoning.
+    ///
+    /// The delta is overwritten, not accumulated like `mov`'s: `from` is
+    /// recomputed fresh from `active.size`/`active.region` every call, so
+    /// repeating the same `reposition` (e.g. an unrelated redraw elsewhere
+    /// re-running this widget's parent without its own layout changing)
+    /// must land on the same answer, not drift further each time.
+    pub(super) fn reposition(&mut self, id: WidgetId, to: UiRegion, rsc: &mut dyn UiRsc) {
+        let Some(active) = self.active.get(&id) else {
+            return;
+        };
+        let from = active
+            .size
+            .to_uivec2()
+            .align(RegionAlign::TOP_LEFT)
+            .within(&active.region);
+        let slot = active.move_slot;
+        let from_px = from.top_left().to_abs(self.output_size);
+        let to_px = to.top_left().to_abs(self.output_size);
+        let delta = to_px - from_px;
+        let entry = rsc.ui_mut().move_offsets.get_mut(slot);
+        entry.delta = [delta.x, delta.y];
+        self.mov_count += 1;
     }
 
     /// NOTE: instance textures are cleared and self.textures freed
@@ -180,6 +336,18 @@ impl UiRenderState {
             active.textures.clear();
             rsc.ui_mut().textures.free();
             if undraw {
+                // Permanent removal: retire this widget's own move slot
+                // (the self-ownership ref taken when it was allocated) and
+                // the up-link ref it held on its parent's slot -- read from
+                // the arena entry itself, not from `active.parent`, since
+                // the parent's own `ActiveData` may already be gone by the
+                // time a deep descendant is retired (see LAYOUT.md
+                // section 2's lifecycle note).
+                let parent_slot = rsc.ui_mut().move_offsets[active.move_slot.idx()].parent;
+                rsc.ui_mut().move_offsets.remove(active.move_slot);
+                if parent_slot != MoveOffset::NONE_PARENT {
+                    rsc.ui_mut().move_offsets.remove(Id::preset(parent_slot));
+                }
                 rsc.on_undraw(active);
             }
         }
@@ -187,7 +355,6 @@ impl UiRenderState {
     }
 
     fn remove_rec(&mut self, id: WidgetId, rsc: &mut dyn UiRsc) -> Option<ActiveData> {
-        self.cache.remove(id);
         let inst = self.remove(id, true, rsc);
         if let Some(inst) = &inst {
             for c in &inst.children {
@@ -201,7 +368,6 @@ impl UiRenderState {
         for (_, active) in self.active.drain() {
             rsc.on_undraw(&active);
         }
-        self.cache.clear();
         self.layers.clear();
         rsc.widgets_mut().needs_redraw.clear();
         rsc.free();
@@ -261,8 +427,43 @@ impl UiRenderState {
         }
     }
 
-    pub fn window_region(&self, id: &impl IdLike) -> Option<PixelRegion> {
-        let region = self.active.get(&id.id())?.region;
+    /// `active[id].region`, corrected by every `move_offsets` delta between
+    /// `id` and the root -- the CPU-side twin of the vertex shader's chain
+    /// walk, over the same arena, so the two cannot disagree about where a
+    /// widget is. O(chain depth), not O(primitives). See LAYOUT.md
+    /// section 2b.
+    pub fn resolved_region(&self, id: &impl IdLike, rsc: &dyn UiRsc) -> Option<UiRegion> {
+        let active = self.active.get(&id.id())?;
+        let delta = self.resolve_move_chain(active.move_slot, rsc);
+        Some(active.region.offset(UiVec2::abs(delta)))
+    }
+
+    /// The plain-Rust twin of `resolve_move` in shader.wgsl: sums the
+    /// pixel delta along the parent chain starting at `slot`. Both walks
+    /// share `MOVE_CHAIN_LIMIT` as their bound so the two cannot disagree
+    /// about where the chain ends.
+    fn resolve_move_chain(&self, mut slot: MoveIdx, rsc: &dyn UiRsc) -> Vec2 {
+        let offsets = &rsc.ui().move_offsets;
+        let mut delta = Vec2::ZERO;
+        for i in 0..MOVE_CHAIN_LIMIT {
+            let entry = &offsets[slot.idx()];
+            delta.x += entry.delta[0];
+            delta.y += entry.delta[1];
+            if entry.parent == MoveOffset::NONE_PARENT {
+                return delta;
+            }
+            slot = Id::preset(entry.parent);
+            debug_assert!(
+                i + 1 < MOVE_CHAIN_LIMIT,
+                "move offset chain exceeded MOVE_CHAIN_LIMIT; a widget's `parent` link is \
+                 probably cyclic"
+            );
+        }
+        delta
+    }
+
+    pub fn window_region(&self, id: &impl IdLike, rsc: &dyn UiRsc) -> Option<PixelRegion> {
+        let region = self.resolved_region(id, rsc)?;
         Some(region.to_px(self.output_size))
     }
 
@@ -270,21 +471,6 @@ impl UiRenderState {
     pub fn redraw(&mut self, id: WidgetId, rsc: &mut dyn UiRsc) {
         rsc.widgets_mut().needs_redraw.remove(&id);
         self.draw_started.remove(&id);
-        // check if parent depends on the desired size of this, if so then redraw it first
-        for axis in [Axis::X, Axis::Y] {
-            if let Some(&(outer, old)) = self.cache.size.axis_dyn(axis).get(&id)
-                && let Some(current) = self.active.get(&id)
-                && let Some(pid) = current.parent
-            {
-                self.cache.size.axis_dyn(axis).remove(&id);
-                let new = self.size_ctx(id, outer, rsc).len_axis(id, axis);
-                self.cache.size.axis_dyn(axis).insert(id, (outer, new));
-                if new != old {
-                    self.redraw(pid, rsc);
-                }
-            }
-        }
-
         if self.draw_started.contains(&id) {
             return;
         }
@@ -292,34 +478,35 @@ impl UiRenderState {
         let Some(active) = self.remove(id, false, rsc) else {
             return;
         };
+        let old_size = active.size;
+        let parent = active.parent;
+        // `old_move_slot` being `Some` below means the slot is reused in
+        // place rather than freshly parented, so this is only reached for
+        // logging/clarity's sake, never actually used to link a new slot.
+        let parent_move_slot = self.move_parent_of(parent);
 
         self.draw_inner(
             active.layer,
             id,
             active.region,
-            active.parent,
+            parent,
+            parent_move_slot,
             active.mask,
             Some(active.children),
+            Some(active.move_slot),
             rsc,
         );
-    }
 
-    pub(super) fn size_ctx<'b>(
-        &'b mut self,
-        source: WidgetId,
-        outer: UiVec2,
-        rsc: &'b mut dyn UiRsc,
-    ) -> SizeCtx<'b> {
-        let ui = rsc.ui_mut();
-        SizeCtx {
-            source,
-            cache: &mut self.cache,
-            text: &mut ui.text,
-            textures: &mut ui.textures,
-            widgets: &ui.widgets,
-            outer,
-            output_size: self.output_size,
-            id: source,
+        // If this widget's own reported size changed, its parent's layout
+        // (which placed it using the old size) is now stale and needs to
+        // relay out too. Checked after the real draw, not before it --
+        // there is no query left that answers "what size would this be"
+        // without actually drawing (LAYOUT.md section 5).
+        if let Some(pid) = parent {
+            let new_size = self.active.get(&id).map(|a| a.size);
+            if new_size != Some(old_size) {
+                self.redraw(pid, rsc);
+            }
         }
     }
 }

iris/core/src/ui/size.rs

@@ -1,86 +0,0 @@
-use crate::{
-    Axis, AxisT, IdLike, Len, RenderedText, Size, TextAttrs, TextBuffer, TextData, Textures,
-    UiVec2, WidgetAxisFns, WidgetId, Widgets, XAxis, YAxis, ui::cache::Cache, util::Vec2,
-};
-
-pub struct SizeCtx<'a> {
-    pub text: &'a mut TextData,
-    pub textures: &'a mut Textures,
-    pub(super) source: WidgetId,
-    pub(super) widgets: &'a Widgets,
-    pub(super) cache: &'a mut Cache,
-    /// TODO: should this be pub? rn used for sized
-    pub outer: UiVec2,
-    pub(super) output_size: Vec2,
-    pub(super) id: WidgetId,
-}
-
-impl SizeCtx<'_> {
-    pub fn id(&self) -> &WidgetId {
-        &self.id
-    }
-
-    pub fn source(&self) -> &WidgetId {
-        &self.source
-    }
-
-    pub(super) fn len_inner<A: const AxisT>(&mut self, id: WidgetId) -> Len {
-        if let Some((_, len)) = self.cache.size.axis::<A>().get(&id) {
-            return *len;
-        }
-        let len = self
-            .widgets
-            .get_dyn_dynamic(id)
-            .desired_len::<A>(&mut SizeCtx {
-                text: self.text,
-                textures: self.textures,
-                source: self.source,
-                widgets: self.widgets,
-                cache: self.cache,
-                outer: self.outer,
-                output_size: self.output_size,
-                id,
-            });
-        self.cache.size.axis::<A>().insert(id, (self.outer, len));
-        len
-    }
-
-    pub fn width(&mut self, id: impl IdLike) -> Len {
-        self.len_inner::<XAxis>(id.id())
-    }
-
-    pub fn height(&mut self, id: impl IdLike) -> Len {
-        self.len_inner::<YAxis>(id.id())
-    }
-
-    pub fn len_axis(&mut self, id: impl IdLike, axis: Axis) -> Len {
-        match axis {
-            Axis::X => self.width(id),
-            Axis::Y => self.height(id),
-        }
-    }
-
-    pub fn size(&mut self, id: impl IdLike) -> Size {
-        let id = id.id();
-        Size {
-            x: self.width(id),
-            y: self.height(id),
-        }
-    }
-
-    pub fn px_size(&mut self) -> Vec2 {
-        self.outer.to_abs(self.output_size)
-    }
-
-    pub fn output_size(&mut self) -> Vec2 {
-        self.output_size
-    }
-
-    pub fn draw_text(&mut self, buffer: &mut TextBuffer, attrs: &TextAttrs) -> RenderedText {
-        self.text.draw(buffer, attrs, self.textures)
-    }
-
-    pub fn label(&self, id: WidgetId) -> &String {
-        self.widgets.label(id)
-    }
-}

iris/core/src/util/arena.rs

@@ -71,6 +71,15 @@ impl<T, I: IdNum> TrackedArena<T, I> {
         self.refs[i.idx()] += 1;
     }
 
+    /// Mutable access to an existing entry, for the rare case (the move
+    /// offset chain) where an already-allocated slot is updated in place
+    /// rather than replaced. Marks the arena changed so the GPU copy is
+    /// re-uploaded.
+    pub fn get_mut(&mut self, id: Id<I>) -> &mut T {
+        self.changed = true;
+        &mut self.inner.data[id.idx()]
+    }
+
     pub fn remove(&mut self, id: Id<I>) -> T
     where
         T: Copy,

iris/core/src/util/slot.rs

@@ -4,6 +4,17 @@ pub struct SlotId {
     genr: u32,
 }
 
+impl SlotId {
+    /// A stable, collision-free `u64` encoding of this id -- for a caller
+    /// (accesskit's `NodeId`, today) that wants a flat integer key rather
+    /// than the two `u32`s. `idx` is offset by one so no real id ever
+    /// encodes to 0, which callers can then reserve for their own
+    /// out-of-band root/window node.
+    pub fn as_u64(&self) -> u64 {
+        ((self.idx as u64) + 1) << 32 | self.genr as u64
+    }
+}
+
 pub struct SlotVec<T> {
     data: Vec<(u32, Option<T>)>,
     free: Vec<u32>,

iris/core/src/widget/mod.rs

@@ -1,4 +1,4 @@
-use crate::{Axis, AxisT, Len, Painter, SizeCtx};
+use crate::{Painter, Size};
 use std::any::Any;
 
 mod data;
@@ -16,31 +16,40 @@ pub use view::*;
 pub use widgets::*;
 
 pub trait Widget: Any {
-    fn draw(&mut self, painter: &mut Painter);
-    fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len;
-    fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len;
-}
+    /// Draw within `painter.region()` (the space the parent offered) and
+    /// report how much of it was actually used, per axis.
+    fn draw(&mut self, painter: &mut Painter) -> Size;
 
-pub trait WidgetAxisFns {
-    fn desired_len<A: AxisT>(&mut self, ctx: &mut SizeCtx) -> Len;
-}
+    /// True if `draw`'s output (both the primitives it writes and the
+    /// `Size` it returns) is the same for any `painter.region()` of the
+    /// same *content* -- an icon, a fixed-size rect, an already-decoded
+    /// image at its natural size. Default `false` (redraw on any change to
+    /// the offered region) because assuming independence wrongly produces
+    /// a stale draw; a widget must opt in. See LAYOUT.md.
+    fn is_size_independent(&self) -> bool {
+        false
+    }
 
-impl<W: Widget + ?Sized> WidgetAxisFns for W {
-    fn desired_len<A: AxisT>(&mut self, ctx: &mut SizeCtx) -> Len {
-        match A::get() {
-            Axis::X => self.desired_width(ctx),
-            Axis::Y => self.desired_height(ctx),
-        }
+    /// What kind of control this is, for the AccessKit tree `ui::access`
+    /// builds (RUST.md's I4). Only consulted for a widget that also has an
+    /// explicit `.label()` -- an unnamed widget is never visited by that
+    /// tree at all, named or not, so the default here costs nothing except
+    /// at the handful of call sites that opt in. Default `Unknown` (a
+    /// generic control with no more specific semantics); a widget with a
+    /// real platform equivalent -- `TextEdit`'s `MultilineTextInput` --
+    /// overrides it.
+    fn access_role(&self) -> accesskit::Role {
+        accesskit::Role::Unknown
     }
 }
 
 impl Widget for () {
-    fn draw(&mut self, _: &mut Painter) {}
-    fn desired_width(&mut self, _: &mut SizeCtx) -> Len {
-        Len::ZERO
+    fn draw(&mut self, _: &mut Painter) -> Size {
+        Size::ZERO
     }
-    fn desired_height(&mut self, _: &mut SizeCtx) -> Len {
-        Len::ZERO
+
+    fn is_size_independent(&self) -> bool {
+        true
     }
 }
 

iris/core/src/widget/widgets.rs

@@ -11,6 +11,11 @@ pub struct Widgets {
     send: Sender<WidgetId>,
     recv: Receiver<WidgetId>,
     pub(crate) waiting: HashSet<WidgetId>,
+    /// Every widget that has ever been given an explicit `.label()` --
+    /// `ui::access::AccessTree` walks exactly this set, not the whole
+    /// arena, so a widget nobody named costs it nothing. Symmetric with
+    /// `free_next` below, which is this set's one removal path.
+    named: HashSet<WidgetId>,
 }
 
 impl Widgets {
@@ -20,6 +25,7 @@ impl Widgets {
             needs_redraw: Default::default(),
             vec: Default::default(),
             waiting: Default::default(),
+            named: Default::default(),
             send,
             recv,
         }
@@ -95,9 +101,20 @@ impl Widgets {
         &self.data(id.id()).unwrap().label
     }
 
-    /// useful for debugging
+    /// Also the one place a widget opts into `ui::access`'s AccessKit tree
+    /// (RUST.md's I4) -- see `named`'s doc comment.
     pub fn set_label(&mut self, id: impl IdLike, label: String) {
-        self.data_mut(id.id()).unwrap().label = label;
+        let id = id.id();
+        self.data_mut(id).unwrap().label = label;
+        self.named.insert(id);
+    }
+
+    /// Every widget with an explicit name, for `ui::access::AccessTree` to
+    /// walk. Order is unspecified; `AccessTree` doesn't need one; a screen
+    /// reader's own traversal is worked out by uiautomator from each
+    /// node's on-screen bounds instead.
+    pub fn named(&self) -> impl Iterator<Item = WidgetId> + '_ {
+        self.named.iter().copied()
     }
 
     pub fn data_mut(&mut self, id: impl IdLike) -> Option<&mut WidgetData> {
@@ -107,6 +124,7 @@ impl Widgets {
     pub fn free_next(&mut self) -> Option<WidgetId> {
         let next = self.recv.try_recv().ok()?;
         self.vec.free(next);
+        self.named.remove(&next);
         Some(next)
     }
 

iris/desktop-app/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "desktop-app"
+version.workspace = true
+edition.workspace = true
+
+# RUST.md's E4: the same transcript-ui screen (I5) in a winit window on the
+# desktop, beside a session list, talking to a real `ai-server` through
+# `client-core`'s REST + SSE clients. Enrolment reuses the phone's own
+# `aiapp://enroll?...` link (`client-core::config`) rather than inventing a
+# second format -- see DECISIONS.md's 2026-09-05 entry. An ordinary
+# workspace member (unlike `android-app`): nothing here needs the NDK, so
+# `cargo build --workspace --all-targets` at the host stays clean with it
+# included.
+
+[dependencies]
+iris = { path = ".." }
+transcript-ui = { path = "../transcript-ui" }
+client-core = { path = "../../client-core" }
+event-model = { path = "../../event-model" }
+# Already pulled in transitively through client-core; used directly here
+# only to persist `EnrolledServer` as the app's own tiny config file (see
+# `config.rs`) -- no new dependency.
+serde_json = { version = "1", features = ["float_roundtrip"] }
+winit = { workspace = true }
+
+[dev-dependencies]
+tempfile = "3"

iris/desktop-app/src/app.rs

@@ -0,0 +1,538 @@
+//! RUST.md's E4: a session list on the left, `transcript-ui`'s screen (I5)
+//! filling the rest, both against a real `ai-server` reached through
+//! `client-core`. The layout is the simplest thing that shows both at
+//! once -- a fixed-width column and `rest(1)` for everything else, using
+//! `iris::widget::{Span, WidgetPtr}` the way `tabs-ui` already switches
+//! panes, rather than anything desktop-specific:
+//!
+//! ```text
+//! +-----------+--------------------------------------+
+//! | session   |  transcript_ui::TranscriptScreen      |
+//! | list      |  (List of folded rows + composer)     |
+//! | (WidgetPtr|                                        |
+//! |  swapped  |  (WidgetPtr swapped whole on session   |
+//! |  on data) |   switch or a new transcript event)    |
+//! +-----------+--------------------------------------+
+//! ```
+//!
+//! **Deliberately left simple, and why**: every incoming SSE event refolds
+//! the *entire* transcript (`client_core::transcript_fold::fold_event` is
+//! already `O(items)` and a desktop session's conversation is small) and
+//! rebuilds the whole right-hand widget tree from scratch, rather than
+//! reaching for `TranscriptScreen::push_row`'s incremental append.
+//! `push_row` cannot update a row already on screen -- only append a new
+//! one -- and a streaming assistant reply is exactly a row whose *text*
+//! keeps changing after it first appears (see `transcript-ui`'s own doc on
+//! `fold_event` folding deltas into one growing item). A full rebuild
+//! shows that growth correctly at the cost of redrawing everything each
+//! time; fine for this proof, wrong for a long, fast-streaming transcript
+//! -- the incremental path that fixes it needs `transcript-ui` to expose
+//! updating a row in place, which it does not yet. The composer's
+//! in-progress text survives a rebuild (`rebuild_transcript`'s
+//! `in_progress` local) since the user typing a followup while a reply
+//! streams in is the one case a naive rebuild would otherwise lose data
+//! on.
+//!
+//! Background network I/O (`client_core::api`/`event_stream`, both
+//! blocking by design -- see `client-core`'s `Cargo.toml`) runs on plain
+//! `std::thread`s that report back through `winit`'s `EventLoopProxy`
+//! (`Proxy<AppEvent>`), rather than through iris's own `Tasks`/`task_on`:
+//! `Tasks` only requests a redraw once, after its whole async closure
+//! finishes, which fits a single request-then-update but not a live SSE
+//! loop that needs to be seen redrawing after *each* event it relays.
+//! `Proxy::send_event` wakes the window's event loop immediately, once per
+//! event, which is what a stream wants.
+
+use client_core::api::{ApiClient, SessionSummary, UreqTransport};
+use client_core::event_stream::{StreamItem, follow_session_events};
+use client_core::transcript_fold::{TranscriptItem, fold_event, group_tool_runs};
+use event_model::SeqEvent;
+use iris::prelude::*;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+/// The session list column's width -- a fixed size for the simplest
+/// layout that shows both panels at once (UI_RULES's text-truncation and
+/// no-shrink rules apply to what's drawn inside it, not to this choice of
+/// column width itself).
+const LIST_WIDTH: f32 = 260.0;
+
+/// Everything a background thread hands back to the window's event loop.
+/// `generation` on the session-scoped variants is the generation
+/// `select_session` was on when the thread started (`Client::generation`)
+/// -- compared back against the current one before being applied, so a
+/// slow response from a session the reader has since clicked away from
+/// can't overwrite what replaced it.
+enum AppEvent {
+    Sessions(Result<Vec<SessionSummary>, String>),
+    TranscriptLoaded {
+        session_id: String,
+        generation: u64,
+        result: Result<Vec<TranscriptItem>, String>,
+    },
+    StreamEvent {
+        session_id: String,
+        generation: u64,
+        event: SeqEvent,
+    },
+    StreamEnded {
+        session_id: String,
+        generation: u64,
+        message: Option<String>,
+    },
+    SendFailed(String),
+}
+
+pub fn run() {
+    DefaultApp::<Client>::run();
+}
+
+#[derive(DefaultUiState)]
+struct Client {
+    ui_state: DefaultUiState,
+    api: Arc<ApiClient<UreqTransport>>,
+    /// A second, independent `UreqTransport` to the same server, used only
+    /// by `select_session`'s live-follow loop. `ApiClient` keeps its
+    /// transport private (rightly -- nothing outside it should reach past
+    /// the typed calls), so a caller that also needs the raw
+    /// `Transport::stream` for SSE, as this one does, builds its own
+    /// rather than the crate growing a getter whose only purpose would be
+    /// letting one caller reach around its own abstraction.
+    stream_transport: Arc<UreqTransport>,
+    proxy: Proxy<AppEvent>,
+    sessions: Vec<SessionSummary>,
+    selected: Option<String>,
+    items: Vec<TranscriptItem>,
+    list_ptr: WeakWidget<WidgetPtr>,
+    transcript_ptr: WeakWidget<WidgetPtr>,
+    screen: Option<transcript_ui::TranscriptScreen>,
+    /// Bumped every time the selected session changes; see `AppEvent`'s
+    /// doc for what it guards against.
+    generation: Arc<AtomicU64>,
+}
+
+impl DefaultAppState for Client {
+    type Event = AppEvent;
+
+    fn new(
+        mut ui_state: DefaultUiState,
+        rsc: &mut DefaultRsc<Self>,
+        proxy: Proxy<AppEvent>,
+    ) -> Self {
+        // Re-validated here rather than threaded through from `main` --
+        // `DefaultApp::run()` takes no payload, so there is no other way
+        // to get `main`'s parsed CLI/config into this constructor. `main`
+        // already called this once to fail fast before a window opens;
+        // this call only fails if the filesystem changed underneath the
+        // process in between, which is not a case worth a nicer message.
+        let (server, ca_pem) = crate::load_startup_config().unwrap_or_else(|e| {
+            eprintln!("desktop-app: {e}");
+            std::process::exit(2);
+        });
+        let build_transport =
+            || UreqTransport::new(server.base_url(), server.token.clone(), &ca_pem);
+        let (rest_transport, stream_transport) = build_transport()
+            .and_then(|rest| build_transport().map(|stream| (rest, stream)))
+            .unwrap_or_else(|e| {
+                eprintln!(
+                    "desktop-app: couldn't set up TLS to {}: {e}",
+                    server.base_url()
+                );
+                std::process::exit(1);
+            });
+        let api = Arc::new(ApiClient::new(rest_transport));
+        let stream_transport = Arc::new(stream_transport);
+
+        let list_ptr = WidgetPtr::new().add(rsc);
+        let transcript_ptr = WidgetPtr::new().add(rsc);
+        let loading = placeholder(rsc, "Loading sessions...");
+        transcript_ptr(rsc).set(loading);
+
+        (list_ptr.width(LIST_WIDTH), transcript_ptr.width(rest(1)))
+            .span(Dir::RIGHT)
+            .set_root(rsc, &mut ui_state);
+
+        let client = Self {
+            ui_state,
+            api,
+            stream_transport,
+            proxy,
+            sessions: Vec::new(),
+            selected: None,
+            items: Vec::new(),
+            list_ptr,
+            transcript_ptr,
+            screen: None,
+            generation: Arc::new(AtomicU64::new(0)),
+        };
+        client.spawn_fetch_sessions();
+        client
+    }
+
+    fn event(&mut self, event: AppEvent, rsc: &mut DefaultRsc<Self>, _render: &mut UiRenderState) {
+        match event {
+            AppEvent::Sessions(Ok(sessions)) => {
+                self.sessions = sessions;
+                self.rebuild_list(rsc);
+                if self.selected.is_none() {
+                    self.show_message(rsc, "Select a session.");
+                }
+            }
+            AppEvent::Sessions(Err(message)) => {
+                self.show_message(rsc, &format!("Couldn't list sessions: {message}"));
+            }
+            AppEvent::TranscriptLoaded {
+                session_id,
+                generation,
+                result,
+            } => {
+                if self.current(&session_id, generation) {
+                    match result {
+                        Ok(items) => {
+                            self.items = items;
+                            self.rebuild_transcript(rsc);
+                        }
+                        Err(message) => {
+                            self.show_message(
+                                rsc,
+                                &format!("Couldn't load {session_id}: {message}"),
+                            );
+                        }
+                    }
+                }
+            }
+            AppEvent::StreamEvent {
+                session_id,
+                generation,
+                event,
+            } => {
+                if self.current(&session_id, generation) {
+                    self.items = fold_event(&self.items, &event);
+                    self.rebuild_transcript(rsc);
+                }
+            }
+            AppEvent::StreamEnded {
+                session_id,
+                generation,
+                message: Some(message),
+            } => {
+                if self.current(&session_id, generation) {
+                    eprintln!("desktop-app: {session_id}'s live connection ended: {message}");
+                }
+            }
+            AppEvent::StreamEnded { .. } => {}
+            AppEvent::SendFailed(message) => {
+                eprintln!("desktop-app: couldn't send: {message}");
+            }
+        }
+        self.ui_state.window.request_redraw();
+    }
+}
+
+impl Client {
+    fn current(&self, session_id: &str, generation: u64) -> bool {
+        self.selected.as_deref() == Some(session_id)
+            && self.generation.load(Ordering::SeqCst) == generation
+    }
+
+    /// Replaces the right-hand panel with a line of text -- built before
+    /// `transcript_ptr` is reached for, since building the message and
+    /// swapping it in both need `rsc` and can't overlap as one borrow.
+    fn show_message(&mut self, rsc: &mut DefaultRsc<Self>, message: &str) {
+        let widget = placeholder(rsc, message);
+        (self.transcript_ptr)(rsc).set(widget);
+    }
+
+    fn spawn_fetch_sessions(&self) {
+        let api = self.api.clone();
+        let proxy = self.proxy.clone();
+        std::thread::spawn(move || {
+            let result = api.fetch_sessions().map_err(|e| e.to_string());
+            let _ = proxy.send_event(AppEvent::Sessions(result));
+        });
+    }
+
+    fn rebuild_list(&mut self, rsc: &mut DefaultRsc<Self>) {
+        let list = Span::empty(Dir::DOWN).gap(2).add(rsc);
+        for session in &self.sessions {
+            let selected = self.selected.as_deref() == Some(session.id.as_str());
+            let row = session_row(rsc, session, selected);
+            list(rsc).push(row);
+        }
+        let tree = list
+            .background(rect(Color::rgb(24, 24, 28)))
+            .add_strong(rsc)
+            .any();
+        (self.list_ptr)(rsc).set(tree);
+    }
+
+    /// Selecting a session starts a fresh generation: any thread still
+    /// working for the previous one checks `Client::current` before
+    /// touching state, so a slow response for a session the reader has
+    /// clicked away from is silently dropped rather than overwriting what
+    /// replaced it.
+    fn select_session(&mut self, rsc: &mut DefaultRsc<Self>, session_id: String) {
+        let generation = self.generation.fetch_add(1, Ordering::SeqCst) + 1;
+        self.selected = Some(session_id.clone());
+        self.items.clear();
+        self.screen = None;
+        self.rebuild_list(rsc);
+        self.show_message(rsc, "Loading transcript...");
+
+        let api = self.api.clone();
+        let stream_transport = self.stream_transport.clone();
+        let proxy = self.proxy.clone();
+        let live_generation = self.generation.clone();
+        std::thread::spawn(move || {
+            // The most recent 200 events, coalesced -- plenty for a
+            // desktop proof; RUST.md's I3/history-paging work is what a
+            // real scrollback would reuse, out of scope here (E4 is only
+            // "the same screen runs in a window").
+            let page: Result<Vec<serde_json::Value>, String> = api
+                .fetch_transcript_page(&session_id, None, 200, true)
+                .map_err(|e| e.to_string());
+            // The raw wire `seq` of the last line fetched -- not the seq of
+            // the last *folded item*. A `TranscriptItem::AssistantMsg` keeps
+            // the seq of the first delta it accumulated (`fold_event`'s own
+            // doc: "a row whose identity changed with every delta would be
+            // a new row every frame"), so resuming the live stream from
+            // that seq re-delivers every delta already folded into it,
+            // duplicating the tail of whatever reply was mid-stream when
+            // the page was fetched. Found by screenshotting a real reply
+            // through `run-headless.sh`: the assistant's line read "You
+            // said: ... testsaid: ... test", the back half being deltas 2
+            // through N replayed onto an already-complete message.
+            let after = page
+                .as_ref()
+                .ok()
+                .and_then(|values| raw_seq(values.last()?))
+                .unwrap_or(0);
+            let result = page.and_then(|values| fold_page(&values));
+            let _ = proxy.send_event(AppEvent::TranscriptLoaded {
+                session_id: session_id.clone(),
+                generation,
+                result,
+            });
+
+            // Follows live from here in the same thread -- sequential
+            // rather than a second thread, since there is nothing to do
+            // with the stream until the page above has been sent anyway.
+            let stop = || live_generation.load(Ordering::SeqCst) != generation;
+            if stop() {
+                return;
+            }
+            let outcome =
+                follow_session_events(&*stream_transport, &session_id, after, |item| match item {
+                    StreamItem::Open | StreamItem::Reset => !stop(),
+                    StreamItem::Event { event, .. } => {
+                        if stop() {
+                            return false;
+                        }
+                        let _ = proxy.send_event(AppEvent::StreamEvent {
+                            session_id: session_id.clone(),
+                            generation,
+                            event,
+                        });
+                        true
+                    }
+                });
+            let _ = proxy.send_event(AppEvent::StreamEnded {
+                session_id,
+                generation,
+                message: outcome.err().map(|e| e.to_string()),
+            });
+        });
+    }
+
+    fn send_message(&mut self, session_id: String, text: String) {
+        let api = self.api.clone();
+        let proxy = self.proxy.clone();
+        std::thread::spawn(move || {
+            if let Err(e) = api.send_message(&session_id, &text, &[]) {
+                let _ = proxy.send_event(AppEvent::SendFailed(e.to_string()));
+            }
+        });
+    }
+
+    fn rebuild_transcript(&mut self, rsc: &mut DefaultRsc<Self>) {
+        let in_progress = self
+            .screen
+            .as_ref()
+            .map(|screen| screen.composer.field.edit(rsc).text.text().to_string())
+            .filter(|t| !t.is_empty());
+
+        let rows = group_tool_runs(&self.items);
+        let (screen, tree) = transcript_ui::build_tree(rsc, rows);
+
+        if let Some(text) = in_progress {
+            screen.composer.field.edit(rsc).set(&text);
+        }
+        if let Some(session_id) = self.selected.clone() {
+            let field = screen.composer.field;
+            rsc.register_event(field, Submit, move |ctx, rsc| {
+                let text = field.edit(rsc).take();
+                let text = text.trim().to_string();
+                if !text.is_empty() {
+                    ctx.state.send_message(session_id.clone(), text);
+                }
+            });
+        }
+
+        (self.transcript_ptr)(rsc).set(tree);
+        self.screen = Some(screen);
+    }
+}
+
+/// One row in the session list: title on top, status below, highlighted
+/// when it's the one currently shown.
+fn session_row(
+    rsc: &mut DefaultRsc<Client>,
+    session: &SessionSummary,
+    selected: bool,
+) -> StrongWidget {
+    let bg = if selected {
+        Color::rgb(58, 90, 138)
+    } else {
+        Color::rgb(38, 38, 44)
+    };
+    let id = session.id.clone();
+    let label = format!("{}\n{}", session.title, session.status);
+    wtext(label)
+        .color(Color::WHITE)
+        .wrap(true)
+        .pad(10)
+        .width(rest(1))
+        .background(rect(bg))
+        .on(
+            CursorSense::click(),
+            move |ctx, rsc: &mut DefaultRsc<Client>| {
+                ctx.state.select_session(rsc, id.clone());
+            },
+        )
+        .add_strong(rsc)
+        .any()
+}
+
+fn placeholder(rsc: &mut DefaultRsc<Client>, message: &str) -> StrongWidget {
+    wtext(message.to_string())
+        .color(Color::WHITE)
+        .wrap(true)
+        .pad(16)
+        .add_strong(rsc)
+        .any()
+}
+
+/// Folds a page of raw transcript lines (`ApiClient::fetch_transcript_page`'s
+/// `Vec<Value>`) into the flat item list `client_core::transcript_fold`
+/// works over. A line this build can't parse fails the whole page rather
+/// than being skipped -- CODE_RULES's "an enumeration must be able to say
+/// 'it broke'" -- since silently dropping one event could hide, say, the
+/// user message the composer is about to look like it never sent.
+fn fold_page(values: &[serde_json::Value]) -> Result<Vec<TranscriptItem>, String> {
+    let mut items = Vec::new();
+    for value in values {
+        let event: SeqEvent = serde_json::from_value(value.clone()).map_err(|e| {
+            format!("the server sent a transcript line this build couldn't parse: {e}")
+        })?;
+        items = fold_event(&items, &event);
+    }
+    Ok(items)
+}
+
+/// The wire `seq` a raw transcript line carries -- see `select_session`'s
+/// comment on why the live-stream cursor has to be this, not a folded
+/// item's `seq()`.
+fn raw_seq(value: &serde_json::Value) -> Option<u64> {
+    value.get("seq")?.as_u64()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn line(seq: u64, json: serde_json::Value) -> serde_json::Value {
+        let mut obj = json;
+        obj["seq"] = serde_json::json!(seq);
+        obj["ts"] = serde_json::json!(1.0);
+        obj
+    }
+
+    /// The regression for the bug a real `run-headless.sh` screenshot
+    /// found (see `select_session`'s comment): resuming the live stream
+    /// from the last *item's* seq re-delivers the deltas already folded
+    /// into a still-open assistant message, doubling its tail. `raw_seq`
+    /// of the last wire line must be the true high-water mark instead,
+    /// which for a run of deltas is higher than every item's own `seq()`.
+    #[test]
+    fn the_resume_cursor_is_the_last_wire_seq_not_the_last_items_seq() {
+        let values = vec![
+            line(1, serde_json::json!({"type": "userMessage", "text": "hi"})),
+            line(
+                2,
+                serde_json::json!({"type": "assistantText", "delta": "a"}),
+            ),
+            line(
+                3,
+                serde_json::json!({"type": "assistantText", "delta": "b"}),
+            ),
+            line(
+                4,
+                serde_json::json!({"type": "assistantText", "delta": "c"}),
+            ),
+        ];
+        let after = raw_seq(values.last().unwrap()).unwrap();
+        assert_eq!(after, 4);
+
+        let items = fold_page(&values).unwrap();
+        // The folded item keeps the *first* delta's seq (2), which is
+        // exactly the value that must not be used as the resume cursor.
+        let assistant_seq = items
+            .iter()
+            .find(|i| matches!(i, TranscriptItem::AssistantMsg { .. }))
+            .unwrap()
+            .seq();
+        assert_eq!(assistant_seq, 2);
+        assert_ne!(
+            after, assistant_seq,
+            "the fixed bug: these must differ here"
+        );
+    }
+
+    #[test]
+    fn a_page_folds_into_one_settled_assistant_message() {
+        let values = vec![
+            line(1, serde_json::json!({"type": "userMessage", "text": "hi"})),
+            line(
+                2,
+                serde_json::json!({"type": "assistantText", "delta": "hel"}),
+            ),
+            line(
+                3,
+                serde_json::json!({"type": "assistantText", "delta": "lo"}),
+            ),
+        ];
+        let items = fold_page(&values).unwrap();
+        assert_eq!(
+            items,
+            vec![
+                TranscriptItem::UserMsg {
+                    seq: 1,
+                    text: "hi".to_string(),
+                    attachments: Vec::new(),
+                },
+                TranscriptItem::AssistantMsg {
+                    seq: 2,
+                    text: "hello".to_string(),
+                    settled: false,
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn an_unparseable_line_fails_the_whole_page() {
+        let values = vec![serde_json::json!({"seq": 1, "ts": 1.0, "type": "not-a-real-type"})];
+        let err = fold_page(&values).unwrap_err();
+        assert!(err.contains("couldn't parse"));
+    }
+}

iris/desktop-app/src/config.rs

@@ -0,0 +1,134 @@
+//! Where the desktop app keeps the enrollment it should not have to be
+//! told about a second time: `client_core::config::EnrolledServer`,
+//! persisted at `$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json`,
+//! owner-only (0600) -- MACHINE.md's rule for anything holding a bearer
+//! token, and the reason `client_core::config`'s own doc comment leaves
+//! persistence and file mode to the caller.
+//!
+//! JSON rather than the project's usual RON: `wg-app-link`'s RON house
+//! rules (`format`) are for configs a person hand-edits, and this file
+//! never is one -- only this program ever writes or reads it, and
+//! `serde_json` is already in the dependency graph through `client-core`,
+//! so nothing new is added to reach for it.
+
+use client_core::config::EnrolledServer;
+use std::io;
+use std::path::{Path, PathBuf};
+
+/// `$XDG_CONFIG_HOME/ai-app-desktop`, falling back to `~/.config` the way
+/// the XDG basedir spec says to when the variable is unset -- the same
+/// fallback `wg_app_link::xdg::config_home` uses, reimplemented here
+/// rather than depended on: that helper lives in the `wg-app-link`
+/// submodule, which `server/` needs but this desktop-only crate does not,
+/// and pulling in a git submodule for one path join would cost more than
+/// it saves.
+pub fn config_dir() -> PathBuf {
+    let base = std::env::var_os("XDG_CONFIG_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            let home = std::env::var_os("HOME").expect("HOME must be set");
+            PathBuf::from(home).join(".config")
+        });
+    base.join("ai-app-desktop")
+}
+
+fn enrollment_file(dir: &Path) -> PathBuf {
+    dir.join("enrollment.json")
+}
+
+/// Persists `server` under `dir` (`config_dir()` for real use; a tempdir in
+/// the tests below), creating it if needed, and sets the file owner-only --
+/// it carries a bearer token, the same reason `server/`'s own token store
+/// is 0600.
+pub fn save_enrollment_in(dir: &Path, server: &EnrolledServer) -> io::Result<()> {
+    std::fs::create_dir_all(dir)?;
+    let path = enrollment_file(dir);
+    let json = serde_json::to_vec_pretty(server)
+        .expect("EnrolledServer holds nothing that fails to serialise");
+    std::fs::write(&path, json)?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
+    }
+    Ok(())
+}
+
+/// `Ok(None)` when nothing has been enrolled yet, rather than an error --
+/// "not enrolled" is an ordinary first-run state, not a failure (UI_RULES'
+/// "a deliberate choice is not a problem to report" applies just as well
+/// to a file that simply hasn't been written yet).
+pub fn load_enrollment_in(dir: &Path) -> io::Result<Option<EnrolledServer>> {
+    let path = enrollment_file(dir);
+    match std::fs::read(&path) {
+        Ok(bytes) => {
+            let server = serde_json::from_slice(&bytes).map_err(|e| {
+                io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    format!("{} is not a valid enrollment ({e})", path.display()),
+                )
+            })?;
+            Ok(Some(server))
+        }
+        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(None),
+        Err(e) => Err(e),
+    }
+}
+
+pub fn save_enrollment(server: &EnrolledServer) -> io::Result<()> {
+    save_enrollment_in(&config_dir(), server)
+}
+
+pub fn load_enrollment() -> io::Result<Option<EnrolledServer>> {
+    load_enrollment_in(&config_dir())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_saved_enrollment_reads_back_the_same() {
+        let dir = tempfile::tempdir().unwrap();
+        let server = EnrolledServer {
+            host: "127.0.0.1".to_string(),
+            port: 8547,
+            token: "tok".to_string(),
+        };
+        save_enrollment_in(dir.path(), &server).unwrap();
+        let read_back = load_enrollment_in(dir.path()).unwrap();
+        assert_eq!(read_back, Some(server));
+    }
+
+    #[test]
+    fn nothing_saved_yet_is_none_not_an_error() {
+        let dir = tempfile::tempdir().unwrap();
+        assert_eq!(load_enrollment_in(dir.path()).unwrap(), None);
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn the_saved_file_is_owner_only() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let server = EnrolledServer {
+            host: "h".to_string(),
+            port: 1,
+            token: "t".to_string(),
+        };
+        save_enrollment_in(dir.path(), &server).unwrap();
+        let mode = std::fs::metadata(enrollment_file(dir.path()))
+            .unwrap()
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o777, 0o600);
+    }
+
+    #[test]
+    fn a_corrupt_file_is_named_in_the_error() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(enrollment_file(dir.path()), b"not json").unwrap();
+        let err = load_enrollment_in(dir.path()).unwrap_err();
+        assert!(err.to_string().contains("enrollment.json"));
+    }
+}

iris/desktop-app/src/main.rs

@@ -0,0 +1,95 @@
+//! RUST.md's E4: the transcript screen (`transcript-ui`, I5) in a real
+//! winit window on the desktop, with a session list beside it, talking to
+//! a real `ai-server` over `client-core`'s REST + SSE clients. See
+//! `app.rs`'s module doc for the widget tree and the event flow.
+//!
+//! Usage:
+//!
+//!     desktop-app --ca /path/to/ca.pem --link 'aiapp://enroll?host=H&port=P&token=T'
+//!     desktop-app --ca /path/to/ca.pem   # after the first run above
+//!
+//! `--link` is the same text `app/ui-sandbox.sh`'s banner prints and a
+//! phone would scan as a QR (DECISIONS.md, 2026-09-05) -- pasted rather
+//! than scanned, since a desktop has no camera to assume. It is parsed and
+//! saved to `config::save_enrollment` once; later runs read it back and
+//! `--link` is only needed again to enrol against a different server. The
+//! CA is never persisted -- it is a public certificate whose path a
+//! caller is expected to already know (`AGENTS.md`'s "prefer exercising
+//! the server directly": the same `certs/ca.pem` a `curl --cacert` call
+//! uses).
+
+mod app;
+mod config;
+
+use client_core::config::EnrolledServer;
+
+struct Args {
+    ca_path: std::path::PathBuf,
+    link: Option<String>,
+}
+
+fn parse_args() -> Result<Args, String> {
+    let mut ca_path = None;
+    let mut link = None;
+    let mut args = std::env::args().skip(1);
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--ca" => {
+                ca_path = Some(std::path::PathBuf::from(
+                    args.next().ok_or("--ca needs a path")?,
+                ))
+            }
+            "--link" => link = Some(args.next().ok_or("--link needs a value")?),
+            other => return Err(format!("unrecognised argument '{other}'")),
+        }
+    }
+    Ok(Args {
+        ca_path: ca_path.ok_or(
+            "--ca PATH is required (the pinned CA's certificate, e.g. \
+                    ~/.config/ai-app/certs/ca.pem)",
+        )?,
+        link,
+    })
+}
+
+/// What `app.rs`'s `Client::new` needs to talk to the server: the enrolled
+/// server (freshly parsed from `--link`, or read back from last time) and
+/// the CA's PEM bytes. Loading is a pure function of the process's own
+/// argv and config file, so it is safe to call again from `Client::new` --
+/// see that call site's comment for why it is not threaded through some
+/// other way (`DefaultApp::run()` takes no payload).
+fn load_startup_config() -> Result<(EnrolledServer, Vec<u8>), String> {
+    let args = parse_args()?;
+    let server = match args.link {
+        Some(link) => {
+            let server = EnrolledServer::parse_link(&link)?;
+            config::save_enrollment(&server)
+                .map_err(|e| format!("couldn't save the enrollment: {e}"))?;
+            server
+        }
+        None => config::load_enrollment()
+            .map_err(|e| format!("couldn't read the saved enrollment: {e}"))?
+            .ok_or_else(|| {
+                format!(
+                    "no server enrolled yet under {} -- pass --link 'aiapp://enroll?...' \
+                     once (app/ui-sandbox.sh's start banner prints one)",
+                    config::config_dir().display()
+                )
+            })?,
+    };
+    let ca_pem = std::fs::read(&args.ca_path)
+        .map_err(|e| format!("couldn't read the CA at {}: {e}", args.ca_path.display()))?;
+    Ok((server, ca_pem))
+}
+
+fn main() {
+    // Validated once here so a bad `--ca`/`--link` is reported on stderr
+    // before any window opens; `Client::new` calls this same function
+    // again once the window exists, so this first call is a fast-fail
+    // rather than the only place the values come from.
+    if let Err(e) = load_startup_config() {
+        eprintln!("desktop-app: {e}");
+        std::process::exit(2);
+    }
+    app::run();
+}

iris/examples/bench_images.rs

@@ -0,0 +1,101 @@
+//! (d) of IRIS_TODO.md's "Benchmarks" item: 1,000 image rows, checking that
+//! standalone-image bind-group *creation* -- a real `wgpu` resource, unlike
+//! the counters in `benches/message_list.rs` -- goes to zero once every
+//! image has loaded. This needs an actual `wgpu` device (`GpuTextures`,
+//! `UiRenderNode`), so unlike the rest of the suite it cannot run as a
+//! plain binary; run it through `iris/run-headless.sh bench_images`, which
+//! gives it a real (headless, GPU-accelerated) compositor and surface. See
+//! `run-bench.sh` for the wrapper that greps its output into one line.
+//!
+//! Each `RedrawRequested` prints the frame number and
+//! `UiRenderNode::take_image_bind_group_creates()` for that frame, then
+//! requests another redraw (nothing else marks the scene dirty, so without
+//! this the app would only ever draw once). The first frame is expected to
+//! report 1,000 (one create per image, on first load); the steady state
+//! IRIS_TODO.md asks this scenario to prove is every frame after settling
+//! down to 0.
+//!
+//! After `SETTLE_FRAMES` it appends one *new* image row (a transcript
+//! receiving one more message) and keeps counting -- a chat transcript's
+//! real access pattern is "one more image arrives," not "reload the whole
+//! list," so the steady-state question that actually matters is the
+//! *incremental* cost of that one append, not just whether an untouched
+//! scene costs zero. It exits after `FRAMES`.
+
+use iris::prelude::*;
+
+const ROWS: usize = 1000;
+const SETTLE_FRAMES: usize = 4;
+const FRAMES: usize = 6;
+
+#[derive(DefaultUiState)]
+struct State {
+    ui_state: DefaultUiState,
+    span: WeakWidget<Span>,
+    frame: usize,
+    appended: bool,
+}
+
+impl DefaultAppState for State {
+    fn new(
+        mut ui_state: DefaultUiState,
+        rsc: &mut DefaultRsc<Self>,
+        _: Proxy<Self::Event>,
+    ) -> Self {
+        let mut span = Span::empty(Dir::DOWN);
+        for _ in 0..ROWS {
+            let img = image::DynamicImage::new_rgba8(32, 32);
+            let widget = image::<DefaultRsc<Self>>(img)(rsc);
+            let widget = rsc.ui.widgets.add_strong(widget);
+            span.push(widget.any());
+        }
+        let span = rsc.ui.widgets.add_strong(span);
+        let span_weak = span.weak();
+        let root = rsc.ui.widgets.add_strong(Scroll::new(span.any(), Axis::Y));
+        ui_state.set_root(root.any());
+        Self {
+            ui_state,
+            span: span_weak,
+            frame: 0,
+            appended: false,
+        }
+    }
+
+    fn window_event(
+        &mut self,
+        event: winit::event::WindowEvent,
+        rsc: &mut DefaultRsc<Self>,
+        _render: &mut UiRenderState,
+    ) {
+        if !matches!(event, winit::event::WindowEvent::RedrawRequested) {
+            return;
+        }
+        self.frame += 1;
+        let creates = self.ui_state.renderer.ui.take_image_bind_group_creates();
+        println!(
+            "BENCH_IMAGES frame={} bind_group_creates={creates}",
+            self.frame
+        );
+        if self.frame == SETTLE_FRAMES && !self.appended {
+            self.appended = true;
+            let img = image::DynamicImage::new_rgba8(32, 32);
+            let widget = image::<DefaultRsc<Self>>(img)(rsc);
+            let widget = rsc.ui.widgets.add_strong(widget);
+            rsc.ui
+                .widgets
+                .get_mut(&self.span)
+                .unwrap()
+                .push(widget.any());
+            println!("BENCH_IMAGES appended one image after settling");
+        }
+        if self.frame < FRAMES {
+            self.ui_state.window.request_redraw();
+        } else {
+            std::process::exit(0);
+        }
+    }
+}
+
+fn main() {
+    DefaultApp::<State>::run();
+}

iris/examples/message_list.rs

@@ -0,0 +1,116 @@
+//! RUST.md's I3: `iris::widget::List` with 800 rows of varied-length
+//! wrapped text, one in twelve carrying a small image, scrollable with the
+//! mouse wheel. Run headless with `iris/run-headless.sh message_list --shot
+//! /tmp/message_list.png` -- there is no display on this machine, so that
+//! is the only way to see it rendered; `run-tests.sh`/`cargo test` never
+//! touch this file.
+//!
+//! Rows alternate two background tints so a screenshot can show the
+//! boundary between adjacent rows even where the text itself wraps to a
+//! different number of lines -- exactly the "variable-height rows" I3
+//! asks for, and the thing a virtualised list gets wrong first if it is
+//! wrong at all (a gap, an overlap, a row the wrong colour). This example
+//! is also what found `List::place`'s oversized-background bug (see
+//! list.rs's module doc and its `a_fill_shaped_background_is_not_left_
+//! oversized` test) -- a plain unit test could have (and now does) catch
+//! it directly, but it was this screenshot rendering as a single blank
+//! tinted rectangle that pointed at it first.
+
+use iris::prelude::*;
+use winit::{dpi::LogicalSize, window::WindowAttributes};
+
+fn main() {
+    DefaultApp::<State>::run();
+}
+
+#[derive(DefaultUiState)]
+struct State {
+    ui_state: DefaultUiState,
+}
+
+const ROWS: usize = 800;
+const IMAGE_EVERY: usize = 12;
+
+/// Repeats a short sentence a varying number of times per row so real
+/// wrapping happens at every row height from one line to several, rather
+/// than every row being identically tall (which would render correctly
+/// even with a broken height measurement).
+fn row_text(i: usize) -> String {
+    const SENTENCE: &str =
+        "Iris lays out this row once and moves it on scroll, never re-laying it out. ";
+    let repeats = 1 + (i * 7) % 5;
+    format!("Message {i}: {}", SENTENCE.repeat(repeats))
+}
+
+/// A small solid-colour square standing in for a real decoded image --
+/// what matters for I3 is that a row can carry an `Image` widget at all,
+/// not what the picture shows.
+fn row_image(i: usize) -> image::DynamicImage {
+    let hue = ((i * 47) % 255) as u8;
+    image::RgbaImage::from_pixel(48, 48, image::Rgba([hue, 128, 255 - hue, 255])).into()
+}
+
+fn build_row<Rsc: UiRsc + 'static>(rsc: &mut Rsc, i: usize) -> StrongWidget {
+    let tint = if i.is_multiple_of(2) {
+        Color::rgb(120, 130, 170)
+    } else {
+        Color::rgb(70, 80, 140)
+    };
+    let text_color = Color::BLACK;
+    if i.is_multiple_of(IMAGE_EVERY) {
+        let text = wtext(row_text(i))
+            .wrap(true)
+            .color(text_color)
+            .add_strong(rsc)
+            .any();
+        let img = image::<Rsc>(row_image(i))(rsc);
+        let img = rsc.widgets_mut().add_strong(img).any();
+        let mut span = Span::empty(Dir::DOWN);
+        span.push(text);
+        span.push(img);
+        span.pad(8.0).background(rect(tint)).add_strong(rsc).any()
+    } else {
+        wtext(row_text(i))
+            .wrap(true)
+            .color(text_color)
+            .pad(8.0)
+            .background(rect(tint))
+            .add_strong(rsc)
+            .any()
+    }
+}
+
+impl DefaultAppState for State {
+    // A phone-plausible portrait shape (the transcript screen this is
+    // standing in for). The tiling headless compositor `run-headless.sh`
+    // uses ignores this and fills its own 1920x1200 output regardless, but
+    // it's a correct hint for any other backend (a real window manager, or
+    // android-view) and costs nothing to state.
+    fn window_attributes() -> WindowAttributes {
+        WindowAttributes::default().with_inner_size(LogicalSize::new(420.0, 900.0))
+    }
+
+    fn new(
+        mut ui_state: DefaultUiState,
+        rsc: &mut DefaultRsc<Self>,
+        _: Proxy<Self::Event>,
+    ) -> Self {
+        let mut list = List::new(Axis::Y);
+        for i in 0..ROWS {
+            let row = build_row(rsc, i);
+            list.push_back(ListRow::new(i as u64, row));
+        }
+
+        let root = list
+            .on(CursorSense::Scroll, |ctx, rsc| {
+                let delta = ctx.data.scroll_delta.y * 50.0;
+                ctx.widget(rsc).scroll(delta);
+            })
+            .masked()
+            .background(rect(Color::WHITE))
+            .add_strong(rsc);
+        ui_state.set_root(root.any());
+
+        Self { ui_state }
+    }
+}

iris/examples/tabs/main.rs

@@ -1,14 +1,14 @@
-use cosmic_text::Family;
-use std::{cell::RefCell, rc::Rc};
-use winit::event::WindowEvent;
-
 use iris::prelude::*;
-type ClientRsc = DefaultRsc<Client>;
+use winit::event::WindowEvent;
 
 fn main() {
     DefaultApp::<Client>::run();
 }
 
+/// The tabs example: five demo panes plus a message composer, built by
+/// `tabs_ui::build` and driven here through the winit backend. The same
+/// widget tree also runs on the android-view backend, through
+/// `iris-android-app` -- see RUST.md's I2.
 #[derive(DefaultUiState)]
 pub struct Client {
     ui_state: DefaultUiState,
@@ -21,189 +21,11 @@ impl DefaultAppState for Client {
         rsc: &mut DefaultRsc<Self>,
         _: Proxy<Self::Event>,
     ) -> Self {
-        let rrect = rect(Color::WHITE).radius(20);
-        let pad_test = (
-            rrect.color(Color::BLUE),
-            (
-                rrect
-                    .color(Color::RED)
-                    .sized((100, 100))
-                    .center()
-                    .width(rest(2)),
-                (
-                    rrect.color(Color::ORANGE),
-                    rrect.color(Color::LIME).pad(10.0),
-                )
-                    .span(Dir::RIGHT)
-                    .width(rest(2)),
-                rrect.color(Color::YELLOW),
-            )
-                .span(Dir::RIGHT)
-                .pad(10)
-                .width(rest(3)),
-        )
-            .span(Dir::RIGHT)
-            .add(rsc);
-
-        let span_test = (
-            rrect.color(Color::GREEN).width(100),
-            rrect.color(Color::ORANGE),
-            rrect.color(Color::CYAN),
-            rrect.color(Color::BLUE).width(rel(0.5)),
-            rrect.color(Color::MAGENTA).width(100),
-            rrect.color(Color::RED).width(100),
-        )
-            .span(Dir::LEFT)
-            .add(rsc);
-
-        let span_add = Span::empty(Dir::RIGHT).add(rsc);
-
-        let add_button = rect(Color::LIME)
-            .radius(30)
-            .on(CursorSense::click(), move |_, rsc| {
-                let child = image(include_bytes!("assets/sungals.png"))
-                    .center()
-                    .add_strong(rsc);
-                span_add(rsc).push(child);
-            })
-            .sized((150, 150))
-            .align(Align::BOT_RIGHT);
-
-        let del_button = rect(Color::RED)
-            .radius(30)
-            .on(CursorSense::click(), move |_, rsc| {
-                span_add(rsc).pop();
-            })
-            .sized((150, 150))
-            .align(Align::BOT_LEFT);
-
-        let span_add_test = (span_add, add_button, del_button).stack().add(rsc);
-
-        let btext = |content| wtext(content).size(30);
-
-        let text_test = (
-            btext("this is a").align(Align::LEFT),
-            btext("teeeeeeeest").align(Align::RIGHT),
-            btext("okkk\nokkkkkk!").align(Align::LEFT),
-            btext("hmm"),
-            btext("a"),
-            (
-                btext("'").family(Family::Monospace).align(Align::TOP),
-                btext("'").family(Family::Monospace),
-                btext(":gamer mode").family(Family::Monospace),
-                rect(Color::CYAN).sized((10, 10)).center(),
-                rect(Color::RED).sized((100, 100)).center(),
-                rect(Color::PURPLE).sized((50, 50)).align(Align::TOP),
-            )
-                .span(Dir::RIGHT)
-                .center(),
-            wtext("pretty cool right?").size(50),
-        )
-            .span(Dir::DOWN)
-            .add(rsc);
-
-        let texts = Span::empty(Dir::DOWN).gap(10).add(rsc);
-        let msg_area = texts.scrollable().masked().background(rect(Color::SKY));
-        let add_text = wtext("add")
-            .editable(EditMode::MultiLine)
-            .text_align(Align::LEFT)
-            .size(30)
-            .attr::<Selectable>(())
-            .on(Submit, move |ctx, rsc| {
-                let w = ctx.widget;
-                let content = w.edit(rsc).take();
-                let text = wtext(content)
-                    .editable(EditMode::MultiLine)
-                    .size(30)
-                    .text_align(Align::LEFT)
-                    .wrap(true)
-                    .attr::<Selectable>(());
-                let msg_box = text
-                    .background(rect(Color::WHITE.darker(0.5)))
-                    .add_strong(rsc);
-                texts(rsc).push(msg_box);
-            })
-            .add(rsc);
-
-        let text_edit_scroll = (
-            msg_area.height(rest(1)),
-            (
-                Rect::new(Color::WHITE.darker(0.9)),
-                (
-                    add_text.width(rest(1)),
-                    Rect::new(Color::GREEN)
-                        .on(CursorSense::click(), move |ctx, rsc: &mut ClientRsc| {
-                            rsc.run_event::<Submit>(add_text, (), ctx.state);
-                        })
-                        .sized((40, 40)),
-                )
-                    .span(Dir::RIGHT)
-                    .pad(10),
-            )
-                .stack()
-                .size(StackSize::Child(1))
-                .layer_offset(1)
-                .align(Align::BOT),
-        )
-            .span(Dir::DOWN)
-            .add(rsc);
-
-        let main = WidgetPtr::new().add(rsc);
-
-        let vals = Rc::new(RefCell::new((0, Vec::new())));
-        let mut switch_button = |color, to: WeakWidget, label| {
-            let to = to.upgrade(rsc);
-            let vec = &mut vals.borrow_mut().1;
-            let i = vec.len();
-            if vec.is_empty() {
-                vec.push(None);
-                main(rsc).set(to);
-            } else {
-                vec.push(Some(to));
-            }
-            let vals = vals.clone();
-            let rect = rect(color)
-                .on(CursorSense::click(), move |ctx, rsc| {
-                    let (prev, vec) = &mut *vals.borrow_mut();
-                    if let Some(h) = vec[i].take() {
-                        vec[*prev] = main(rsc).replace(h);
-                        *prev = i;
-                    }
-                    ctx.widget(rsc).color = color.darker(0.3);
-                })
-                .on(
-                    CursorSense::HoverStart | CursorSense::unclick(),
-                    move |ctx, rsc| {
-                        ctx.widget(rsc).color = color.brighter(0.2);
-                    },
-                )
-                .on(CursorSense::HoverEnd, move |ctx, rsc| {
-                    ctx.widget(rsc).color = color;
-                });
-            (rect, wtext(label).size(30).text_align(Align::CENTER)).stack()
-        };
-
-        let tabs = (
-            switch_button(Color::RED, pad_test, "pad"),
-            switch_button(Color::GREEN, span_test, "span"),
-            switch_button(Color::BLUE, span_add_test, "image span"),
-            switch_button(Color::MAGENTA, text_test, "text layout"),
-            switch_button(
-                Color::YELLOW.mul_rgb(0.5),
-                text_edit_scroll,
-                "text edit scroll",
-            ),
-        )
-            .span(Dir::RIGHT);
-
-        let info = wtext("").add(rsc);
-        let info_sect = info.pad(10).align(Align::RIGHT);
-
-        ((tabs.height(40), main.pad(10)).span(Dir::DOWN), info_sect)
-            .stack()
-            .set_root(rsc, &mut ui_state);
-
-        Self { ui_state, info }
+        let widgets = tabs_ui::build(rsc, &mut ui_state);
+        Self {
+            ui_state,
+            info: widgets.info,
+        }
     }
 
     fn window_event(

iris/run-bench.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Runs iris's on-demand benchmark suite (IRIS_TODO.md's "Benchmarks" item).
+# Never run by `cargo test`; run this by hand or before/after a layout
+# change. Always release -- see AGENTS.md's own rule against reading a
+# frame time from a debug build.
+#
+#   ./run-bench.sh            # everything
+#   ./run-bench.sh list       # just the CPU-only message-list scenarios
+#   ./run-bench.sh images     # just the GPU bind-group-creation scenario
+set -eu
+here=$(cd "$(dirname "$0")" && pwd)
+cd "$here"
+
+what="${1:-all}"
+
+if [ "$what" = "all" ] || [ "$what" = "list" ]; then
+    echo "=== message_list (CPU-only, no window) ==="
+    cargo bench --bench message_list
+fi
+
+if [ "$what" = "all" ] || [ "$what" = "images" ]; then
+    echo "=== bench_images (real wgpu device, via run-headless.sh) ==="
+    timeout 60 ./run-headless.sh bench_images --seconds 4 2>&1 | grep "^BENCH_IMAGES"
+fi

iris/run-headless.sh

@@ -4,6 +4,16 @@
 #   ./run-headless.sh tabs [-- cargo args]
 #   ./run-headless.sh tabs --shot /tmp/tabs.png --seconds 4
 #
+# `--bin` runs a real crate binary instead of an example (E4's
+# `desktop-app`, which is a window a person runs, not a demo) --
+# `cargo build --bin NAME` instead of `--example NAME`, and
+# `target/debug/NAME` instead of `target/debug/examples/NAME`. Its own
+# argv (the CLI flags a real binary takes, as opposed to `cargo build`'s
+# own flags after `--`) comes through `$RUN_HEADLESS_ARGS`, word-split on
+# purpose -- an example never needed one, so there was nowhere to plumb it
+# through positionally without disturbing the existing `-- cargo args`
+# convention above.
+#
 # The VM has a virtio-gpu render node (Vulkan 1.4 through Venus, GL 4.6
 # through virgl), so wgpu runs on the host's real GPU -- what is missing is
 # only a compositor to give winit a surface. So: a headless sway, the same
@@ -20,16 +30,18 @@ run="${XDG_RUNTIME_DIR:-/tmp}/iris-headless"
 seconds=3
 shot=""
 example=""
+kind=example
 
 while [ $# -gt 0 ]; do
     case "$1" in
         --shot) shot=$2; shift 2 ;;
         --seconds) seconds=$2; shift 2 ;;
+        --bin) kind=bin; shift ;;
         --) shift; break ;;
         *) example=$1; shift ;;
     esac
 done
-[ -n "$example" ] || { echo "usage: $0 EXAMPLE [--shot PNG] [--seconds N] [-- cargo args]" >&2; exit 2; }
+[ -n "$example" ] || { echo "usage: $0 NAME [--bin] [--shot PNG] [--seconds N] [-- cargo args]" >&2; exit 2; }
 
 mkdir -p "$run"
 export SWAYSOCK="$run/sway.sock"
@@ -67,10 +79,17 @@ export WAYLAND_DISPLAY
 echo "run-headless: $WAYLAND_DISPLAY (sway $(swaymsg -t get_version --raw | sed -n 's/.*"human_readable":"\([^"]*\)".*/\1/p'))" >&2
 
 cd "$here"
-cargo build --example "$example" "$@" >&2
-bin="$here/target/debug/examples/$example"
+if [ "$kind" = bin ]; then
+    cargo build --bin "$example" "$@" >&2
+    bin="$here/target/debug/$example"
+else
+    cargo build --example "$example" "$@" >&2
+    bin="$here/target/debug/examples/$example"
+fi
 
-"$bin" >"$run/$example.log" 2>&1 &
+# shellcheck disable=SC2086 -- deliberately word-split: this is the
+# binary's own argv, not a single path.
+"$bin" ${RUN_HEADLESS_ARGS:-} >"$run/$example.log" 2>&1 &
 pid=$!
 trap 'kill "$pid" 2>/dev/null || true' EXIT INT TERM
 

iris/src/access_tests.rs

@@ -0,0 +1,129 @@
+//! Pass conditions for RUST.md's I4, exercised the same way
+//! `layout_tests.rs` exercises LAYOUT.md's: `AccessTree` only touches
+//! `Widgets`/`UiRenderState`, neither of which needs a GPU or a window, so
+//! it can be driven directly against `layout_tests::TestRsc`.
+
+use crate::layout_tests::TestRsc;
+use crate::prelude::*;
+
+#[test]
+fn a_named_widget_reaches_the_tree_with_its_role_and_bounds() {
+    let mut rsc = TestRsc {
+        ui: UiData::default(),
+    };
+    let leaf: WeakWidget<Rect> = rect(UiColor::WHITE).label("Add task").add(&mut rsc);
+    let root = leaf.upgrade(&mut rsc).any();
+    let mut render = UiRenderState::new();
+    render.resize((800.0, 600.0));
+    render.update(&root, &mut rsc);
+
+    let mut access = AccessTree::new();
+    let update = access
+        .update(rsc.widgets(), &render, &rsc)
+        .expect("a first draw with a named widget must produce a tree");
+
+    // One node for the widget, one for the synthetic window root.
+    assert_eq!(update.nodes.len(), 2);
+    let (_, node) = update
+        .nodes
+        .iter()
+        .find(|(_, n)| n.role() != accesskit::Role::Window)
+        .expect("the named widget's own node");
+    assert_eq!(node.label(), Some("Add task"));
+    assert_eq!(node.role(), accesskit::Role::Unknown);
+    let bounds = node.bounds().expect("a drawn widget reports its bounds");
+    let region = render
+        .window_region(&leaf, &rsc)
+        .expect("the widget is active after render.update");
+    assert_eq!(bounds.x0, region.top_left.x as f64);
+    assert_eq!(bounds.y0, region.top_left.y as f64);
+    assert_eq!(bounds.x1, region.bot_right.x as f64);
+    assert_eq!(bounds.y1, region.bot_right.y as f64);
+}
+
+#[test]
+fn a_widget_with_no_label_never_reaches_the_tree() {
+    let mut rsc = TestRsc {
+        ui: UiData::default(),
+    };
+    let root = rsc.ui.widgets.add_strong(rect(UiColor::WHITE));
+    let mut render = UiRenderState::new();
+    render.resize((800.0, 600.0));
+    render.update(&root.any(), &mut rsc);
+
+    let mut access = AccessTree::new();
+    assert!(
+        access.update(rsc.widgets(), &render, &rsc).is_none(),
+        "no widget was ever `.label()`ed, so there is nothing to report -- \
+         not even an empty tree change"
+    );
+}
+
+/// LAYOUT.md's "a moved subtree" lesson applies here too: `resolved_region`
+/// (which `window_region` sits on) walks the move-offset chain, so a
+/// widget moved via `Offset` -- not redrawn from scratch -- must still
+/// report where it actually ended up.
+#[test]
+fn bounds_follow_a_moved_widget_and_updates_stay_incremental() {
+    let mut rsc = TestRsc {
+        ui: UiData::default(),
+    };
+    let leaf: WeakWidget<Rect> = rect(UiColor::WHITE).label("thing").add(&mut rsc);
+    let leaf_strong = leaf.upgrade(&mut rsc).any();
+    let offset = rsc.ui.widgets.add_strong(Offset {
+        inner: leaf_strong,
+        amt: UiVec2::ZERO,
+    });
+    let offset_id = offset.weak();
+    let root = offset.any();
+    let mut render = UiRenderState::new();
+    render.resize((800.0, 600.0));
+    render.update(&root, &mut rsc);
+
+    let mut access = AccessTree::new();
+    access
+        .update(rsc.widgets(), &render, &rsc)
+        .expect("the first draw is always a change");
+    assert_eq!(access.take_rebuilds(), 1);
+
+    // Unchanged frame: nothing moved, nothing renamed -- `update` must
+    // report no change, and the rebuild counter (I4's twin of
+    // `take_counters`) must stay at 0.
+    render.update(&root, &mut rsc);
+    assert!(access.update(rsc.widgets(), &render, &rsc).is_none());
+    assert_eq!(access.take_rebuilds(), 0);
+
+    // Move the child via `Offset` (a move-offset write, not necessarily a
+    // full redraw of the leaf -- see `resolve_move_chain`) and confirm the
+    // reported bounds shifted by exactly that amount, in exactly one more
+    // rebuild.
+    let before = render
+        .window_region(&leaf, &rsc)
+        .expect("active before the move");
+    rsc.ui.widgets.get_mut(&offset_id).unwrap().amt = UiVec2::abs(Vec2::new(50.0, 0.0));
+    render.update(&root, &mut rsc);
+    let update = access
+        .update(rsc.widgets(), &render, &rsc)
+        .expect("a moved named widget is a change");
+    assert_eq!(access.take_rebuilds(), 1);
+
+    let after = render
+        .window_region(&leaf, &rsc)
+        .expect("still active after the move");
+    // Not asserting the exact delta: `Offset`'s own `amt` -> pixel mapping
+    // is that widget's business, not this tree's. What I4 owns is that
+    // `AccessTree` reports whatever `window_region` says *now* -- so the
+    // node must have moved, and in the direction the offset moved it.
+    assert!(
+        after.top_left.x > before.top_left.x,
+        "the leaf's reported bounds must move right along with its offset"
+    );
+
+    let (_, node) = update
+        .nodes
+        .iter()
+        .find(|(_, n)| n.role() != accesskit::Role::Window)
+        .unwrap();
+    let bounds = node.bounds().unwrap();
+    assert_eq!(bounds.x0, after.top_left.x as f64);
+}

iris/src/android/access.rs

@@ -0,0 +1,86 @@
+//! I4 (RUST.md): the Android half of the AccessKit push, over
+//! `accesskit_android::Adapter` and android-view's
+//! `AccessibilityNodeProvider`. Carries E1's mitigation for the adapter's
+//! reproducible abort: `accesskit_android`'s `State` (0.4.0 and 0.8.0
+//! alike) never moves back to `Inactive` once a client attaches, so once
+//! one has, every later `QueuedEvents::raise` reaches
+//! `AccessibilityManager.sendAccessibilityEvent` -- which throws if
+//! accessibility has since been switched off (or the client detached),
+//! and android-view's `panic = "abort"` turns that Java exception into a
+//! process kill. `raise_if_enabled` is the gate: ask
+//! `AccessibilityManager.isEnabled()` immediately before every `raise`
+//! and drop the events instead of calling it when the answer is no. See
+//! RUST.md's E1 box for the full repro.
+use accesskit::{ActionHandler, ActionRequest, ActivationHandler, TreeUpdate};
+use accesskit_android::QueuedEvents;
+use android_view::{
+    View,
+    jni::{JNIEnv, objects::JObject},
+};
+use iris_core::{AccessTree, UiRenderState, UiRsc, Widgets};
+
+/// The `ActivationHandler` `accesskit_android::Adapter` asks for its
+/// initial tree from -- unlike `accesskit_winit`'s handlers (see
+/// `default/access.rs`), this one is only ever invoked synchronously from
+/// inside a JNI callback that already holds everything it needs, so it can
+/// just borrow `IrisViewPeer`'s own fields for the length of one call
+/// rather than going through a channel.
+pub(super) struct AndroidAccessSource<'a> {
+    pub widgets: &'a Widgets,
+    pub render: &'a UiRenderState,
+    pub rsc: &'a dyn UiRsc,
+}
+
+impl ActivationHandler for AndroidAccessSource<'_> {
+    fn request_initial_tree(&mut self) -> Option<TreeUpdate> {
+        Some(AccessTree::build_full(self.widgets, self.render, self.rsc))
+    }
+}
+
+/// Every AccessKit action request is inert here -- see this module's doc
+/// comment and `default/access.rs`'s matching handler for why: a screen
+/// reader's tap on a named node is a real touch delivered at that node's
+/// bounds, which the ordinary pointer path already handles once the
+/// bounds `AccessTree` reports are right.
+pub(super) struct NullActionHandler;
+impl ActionHandler for NullActionHandler {
+    fn do_action(&mut self, _request: ActionRequest) {}
+}
+
+fn is_accessibility_enabled<'local>(env: &mut JNIEnv<'local>, view: &View<'local>) -> bool {
+    let context = view.context(env);
+    let name = env.new_string("accessibility").unwrap();
+    let manager: JObject = env
+        .call_method(
+            &context.0,
+            "getSystemService",
+            "(Ljava/lang/String;)Ljava/lang/Object;",
+            &[(&name).into()],
+        )
+        .unwrap()
+        .l()
+        .unwrap();
+    if manager.is_null() {
+        return false;
+    }
+    env.call_method(&manager, "isEnabled", "()Z", &[])
+        .unwrap()
+        .z()
+        .unwrap()
+}
+
+/// The one place `QueuedEvents::raise` may be called -- see this module's
+/// doc comment. Every call site pushes this as a deferred callback rather
+/// than calling it inline, matching android-view's own demo: `raise`
+/// itself asks not to be called while the caller holds locks a framework
+/// callback might, and a deferred callback runs after the current one has
+/// returned them.
+pub(super) fn raise_if_enabled<'local>(
+    env: &mut JNIEnv<'local>,
+    view: &View<'local>,
+    events: QueuedEvents,
+) {
+    if is_accessibility_enabled(env, view) {
+        events.raise(env, &view.0);
+    }
+}

iris/src/android/attr.rs

@@ -0,0 +1,25 @@
+use crate::attr::{FocusHost, recent_click};
+use crate::prelude::*;
+
+use super::view::HasAndroidUiState;
+
+impl<T: HasAndroidUiState> FocusHost for T {
+    fn recent_click(&mut self) -> bool {
+        recent_click(&mut self.android_state_mut().last_click)
+    }
+
+    fn set_focus(&mut self, id: Option<WeakWidget<TextEdit>>) {
+        self.android_state_mut().focus = id;
+    }
+
+    fn focus_gained(&mut self, region: Option<PixelRegion>) {
+        // Showing the keyboard is a JNI call (`InputMethodManager.showSoftInput`),
+        // and this runs deep inside the platform-agnostic sensor dispatch
+        // with no `CallbackCtx` in reach -- `IrisViewPeer::after_input`
+        // (`view.rs`) is what actually makes the call, right after the
+        // sensor pass that got here returns.
+        if region.is_some() {
+            self.android_state_mut().pending_show_keyboard = true;
+        }
+    }
+}

iris/src/android/ime.rs

@@ -0,0 +1,272 @@
+//! `InputConnection`, implemented directly against a focused `TextEdit`
+//! rather than against a stand-in editor the way android-view's own demo
+//! does over its `parley::PlainEditor` -- I1 already put parley behind
+//! `TextEdit`, so this is that same bridge, just wired to iris's widget
+//! instead of a bespoke one. Follows `demo/src/lib.rs`'s
+//! `impl InputConnection for DemoViewPeer`, which is where RUST.md's E1
+//! found the shape this needs (`text_before_cursor` is what gets Gboard's
+//! suggestion strip to read real words out of the buffer).
+//!
+//! Two things the demo tracks that this does not, both noted rather than
+//! silently dropped: a real "composing region" distinct from the
+//! selection (`set_composing_region` here just moves the caret, since
+//! `TextEdit` has no third range to hold one), and batch-edit coalescing
+//! (`begin`/`end_batch_edit` are no-ops -- a redraw mid-batch costs a frame
+//! it does not need to, not correctness).
+
+use crate::prelude::*;
+use android_view::{
+    CAP_MODE_SENTENCES, CallbackCtx, EditorInfo, IME_FLAG_NO_ENTER_ACTION, IME_FLAG_NO_EXTRACT_UI,
+    IME_FLAG_NO_FULLSCREEN, INPUT_TYPE_CLASS_TEXT, INPUT_TYPE_TEXT_FLAG_AUTO_CORRECT,
+    INPUT_TYPE_TEXT_FLAG_CAP_SENTENCES, INPUT_TYPE_TEXT_FLAG_MULTI_LINE, InputConnection,
+    caps_mode,
+};
+use std::borrow::Cow;
+
+use super::view::{AndroidAppState, IrisViewPeer};
+
+/// Byte offset -> UTF-16 code unit offset, the unit every `InputConnection`
+/// method speaks in (Java strings are UTF-16). `TextEdit` is byte-indexed
+/// throughout since I1 moved it to parley -- see `edit.rs`'s doc comment on
+/// `text()` -- so every crossing of this boundary goes through here rather
+/// than through ad hoc counting at each call site.
+fn byte_to_utf16(text: &str, byte_idx: usize) -> usize {
+    text[..byte_idx].encode_utf16().count()
+}
+
+fn utf16_to_byte(text: &str, utf16_idx: usize) -> usize {
+    let mut utf16_len = 0;
+    for (byte_idx, ch) in text.char_indices() {
+        if utf16_len >= utf16_idx {
+            return byte_idx;
+        }
+        utf16_len += ch.len_utf16();
+    }
+    text.len()
+}
+
+impl<State: AndroidAppState> IrisViewPeer<State> {
+    fn focus(&self) -> Option<WeakWidget<TextEdit>> {
+        self.state.android_state().focus
+    }
+}
+
+impl<State: AndroidAppState> InputConnection for IrisViewPeer<State> {
+    fn on_create_input_connection<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        out_attrs: &EditorInfo<'local>,
+    ) {
+        // Set once per `InputConnection`, not per field -- Android calls
+        // this when the view (not a particular widget) attaches to an
+        // IME. `MULTI_LINE`/`AUTO_CORRECT`/`CAP_SENTENCES` cover both the
+        // tabs example's composer and a plain single-line field well
+        // enough that no per-field variant is worth the extra state yet.
+        out_attrs.set_input_type(
+            &mut ctx.env,
+            INPUT_TYPE_CLASS_TEXT
+                | INPUT_TYPE_TEXT_FLAG_CAP_SENTENCES
+                | INPUT_TYPE_TEXT_FLAG_AUTO_CORRECT
+                | INPUT_TYPE_TEXT_FLAG_MULTI_LINE,
+        );
+        out_attrs.set_ime_options(
+            &mut ctx.env,
+            IME_FLAG_NO_FULLSCREEN | IME_FLAG_NO_EXTRACT_UI | IME_FLAG_NO_ENTER_ACTION,
+        );
+        if let Some(focus) = self.focus() {
+            let text = &self.rsc[focus];
+            let sel = text.selection_range().unwrap_or(0..0);
+            let start = byte_to_utf16(text.text(), sel.start) as i32;
+            let end = byte_to_utf16(text.text(), sel.end) as i32;
+            out_attrs.set_initial_sel_start(&mut ctx.env, start);
+            out_attrs.set_initial_sel_end(&mut ctx.env, end);
+            let caps = caps_mode(
+                &mut ctx.env,
+                text.text(),
+                start as usize,
+                CAP_MODE_SENTENCES,
+            );
+            out_attrs.set_initial_caps_mode(&mut ctx.env, caps);
+        }
+    }
+
+    fn text_before_cursor<'slf>(
+        &'slf mut self,
+        _ctx: &mut CallbackCtx,
+        n: i32,
+    ) -> Option<Cow<'slf, str>> {
+        if n < 0 {
+            return None;
+        }
+        let focus = self.focus()?;
+        let text = &self.rsc[focus];
+        let sel = text.selection_range()?;
+        let end_16 = byte_to_utf16(text.text(), sel.start);
+        let start_16 = end_16.saturating_sub(n as usize);
+        let start = utf16_to_byte(text.text(), start_16);
+        Some(Cow::Borrowed(&text.text()[start..sel.start]))
+    }
+
+    fn text_after_cursor<'slf>(
+        &'slf mut self,
+        _ctx: &mut CallbackCtx,
+        n: i32,
+    ) -> Option<Cow<'slf, str>> {
+        if n < 0 {
+            return None;
+        }
+        let focus = self.focus()?;
+        let text = &self.rsc[focus];
+        let sel = text.selection_range()?;
+        let len_16 = byte_to_utf16(text.text(), text.text().len());
+        let start_16 = byte_to_utf16(text.text(), sel.end);
+        let end_16 = (start_16 + n as usize).min(len_16);
+        let end = utf16_to_byte(text.text(), end_16);
+        Some(Cow::Borrowed(&text.text()[sel.end..end]))
+    }
+
+    fn selected_text<'slf>(&'slf mut self, _ctx: &mut CallbackCtx) -> Option<Cow<'slf, str>> {
+        let focus = self.focus()?;
+        Some(Cow::Owned(self.rsc[focus].selected_text()?))
+    }
+
+    fn cursor_caps_mode(&mut self, ctx: &mut CallbackCtx, req_modes: u32) -> u32 {
+        let Some(focus) = self.focus() else {
+            return 0;
+        };
+        let text = &self.rsc[focus];
+        let Some(caret) = text.caret() else {
+            return 0;
+        };
+        let off = byte_to_utf16(text.text(), caret);
+        caps_mode(&mut ctx.env, text.text(), off, req_modes)
+    }
+
+    fn delete_surrounding_text(
+        &mut self,
+        ctx: &mut CallbackCtx,
+        before_length: i32,
+        after_length: i32,
+    ) -> bool {
+        let Some(focus) = self.focus() else {
+            return false;
+        };
+        let text = &self.rsc[focus];
+        let Some(sel) = text.selection_range() else {
+            return false;
+        };
+        let content = text.text();
+        let start_16 =
+            byte_to_utf16(content, sel.start).saturating_sub(before_length.max(0) as usize);
+        let len_16 = byte_to_utf16(content, content.len());
+        let end_16 = (byte_to_utf16(content, sel.end) + after_length.max(0) as usize).min(len_16);
+        let start = utf16_to_byte(content, start_16);
+        let end = utf16_to_byte(content, end_16);
+        focus.edit(&mut self.rsc).delete_byte_range(start, end);
+        self.after_input(ctx);
+        true
+    }
+
+    fn delete_surrounding_text_in_code_points(
+        &mut self,
+        ctx: &mut CallbackCtx,
+        before_length: i32,
+        after_length: i32,
+    ) -> bool {
+        // Approximated as UTF-16 units rather than Unicode scalar values --
+        // the two differ only outside the Basic Multilingual Plane, which
+        // this widget tree does not exercise today. Worth revisiting if a
+        // field ever needs to edit emoji or other astral-plane text well.
+        self.delete_surrounding_text(ctx, before_length, after_length)
+    }
+
+    fn set_composing_text(
+        &mut self,
+        ctx: &mut CallbackCtx,
+        text: &str,
+        _new_cursor_position: i32,
+    ) -> bool {
+        let Some(focus) = self.focus() else {
+            return false;
+        };
+        // The IME re-sends its whole composition on every keystroke;
+        // `compose_len` (chars, not bytes -- `TextEditCtx::replace`'s unit)
+        // is what lets `replace` remove exactly what it inserted last time.
+        // The same shape as `default::DefaultApp`'s `Ime::Preedit` handling
+        // for winit.
+        let compose_len = self.state.android_state().compose_len;
+        focus.edit(&mut self.rsc).replace(compose_len, text);
+        self.state.android_state_mut().compose_len = text.chars().count();
+        self.after_input(ctx);
+        true
+    }
+
+    fn set_composing_region(&mut self, _ctx: &mut CallbackCtx, _start: i32, _end: i32) -> bool {
+        // `TextEdit` has no separate composing range to move -- see this
+        // module's doc comment. Declining (rather than moving the caret,
+        // which would surprise a caller expecting only a style change)
+        // is the safer approximation.
+        false
+    }
+
+    fn finish_composing_text(&mut self, ctx: &mut CallbackCtx) -> bool {
+        self.state.android_state_mut().compose_len = 0;
+        self.after_input(ctx);
+        true
+    }
+
+    fn set_selection(&mut self, ctx: &mut CallbackCtx, start: i32, end: i32) -> bool {
+        let Some(focus) = self.focus() else {
+            return false;
+        };
+        let text = &self.rsc[focus];
+        let content = text.text();
+        // Collapsed to `end`: `TextEditCtx` has no range-selection setter
+        // yet (nothing before I2 needed one), so an IME-driven selection
+        // lands the caret at its focus end rather than spanning both.
+        let byte = utf16_to_byte(content, end.max(0) as usize);
+        focus.edit(&mut self.rsc).set_cursor_byte(byte);
+        let _ = start;
+        self.after_input(ctx);
+        true
+    }
+
+    fn perform_editor_action(&mut self, _ctx: &mut CallbackCtx, _editor_action: i32) -> bool {
+        // `IME_FLAG_NO_ENTER_ACTION` above asks the IME not to offer one;
+        // nothing here needs handling it yet.
+        false
+    }
+
+    fn begin_batch_edit(&mut self, _ctx: &mut CallbackCtx) -> bool {
+        true
+    }
+
+    fn end_batch_edit(&mut self, _ctx: &mut CallbackCtx) -> bool {
+        true
+    }
+
+    fn send_key_event<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        event: &android_view::KeyEvent<'local>,
+    ) -> bool {
+        let key_code = event.key_code(&mut ctx.env);
+        let handled = super::input::on_key(
+            &mut self.rsc,
+            &mut self.state,
+            &mut ctx.env,
+            key_code,
+            event,
+        );
+        if handled {
+            self.after_input(ctx);
+        }
+        handled
+    }
+
+    fn request_cursor_updates(&mut self, _ctx: &mut CallbackCtx, _cursor_update_mode: i32) -> bool {
+        // No cursor-anchor UI to feed -- see RUST.md's I2 notes on what
+        // this backend does not do yet.
+        false
+    }
+}

iris/src/android/input.rs

@@ -0,0 +1,39 @@
+use crate::prelude::*;
+use android_view::{jni::JNIEnv, ndk::event::Keycode};
+
+use super::view::{AndroidAppState, AndroidRsc};
+
+/// Hardware/synthesized key handling for the field that currently has
+/// focus. Most typing on Android goes through the IME's `InputConnection`
+/// (`android/ime.rs`) instead -- this only sees what a soft keyboard still
+/// sends as a real `KeyEvent` in "not fullscreen" mode (Backspace, Enter,
+/// the arrow keys on a physical keyboard) plus whatever `unicode_char`
+/// reports for a plain key press. Returns whether anything used the event.
+pub(super) fn on_key<'local, State: AndroidAppState>(
+    rsc: &mut AndroidRsc<State>,
+    state: &mut State,
+    env: &mut JNIEnv<'local>,
+    key_code: Keycode,
+    event: &android_view::KeyEvent<'local>,
+) -> bool {
+    let Some(focus) = state.android_state().focus else {
+        return false;
+    };
+    let mut text = focus.edit(rsc);
+    match key_code {
+        Keycode::Del => text.backspace(false),
+        Keycode::ForwardDel => text.delete(false),
+        Keycode::DpadLeft => text.motion(Motion::Left, false),
+        Keycode::DpadRight => text.motion(Motion::Right, false),
+        Keycode::DpadUp => text.motion(Motion::Up, false),
+        Keycode::DpadDown => text.motion(Motion::Down, false),
+        Keycode::MoveHome => text.motion(Motion::LineStart, false),
+        Keycode::MoveEnd => text.motion(Motion::LineEnd, false),
+        Keycode::Enter | Keycode::NumpadEnter => text.newline(),
+        _ => match event.unicode_char(env) {
+            Some(c) if !c.is_control() => text.insert(&c.to_string()),
+            _ => return false,
+        },
+    }
+    true
+}

iris/src/android/insets.rs

@@ -0,0 +1,129 @@
+//! Window insets, fed in from outside `ViewPeer`.
+//!
+//! android-view's registered native methods (`view.rs` in that crate) cover
+//! touch, keys, focus, the surface and the IME -- there is nothing for
+//! `View.onApplyWindowInsets`, because android-view's own demo does not
+//! need it. The back gesture needed no new plumbing at all: with no
+//! `OnBackPressedCallback` registered, Android still delivers it as an
+//! ordinary `KEYCODE_BACK` `KeyEvent` through the ordinary key path (see
+//! `view.rs`'s `on_key_down`), which is the legacy behaviour every app gets
+//! by default and is enough for "the back gesture as an event". Insets have
+//! no such stand-in, so this module registers one more native method by
+//! hand, on the app's own `View` subclass rather than on android-view's.
+//!
+//! The peer id android-view hands back from `register_view_peer` is opaque
+//! outside that crate (`with_peer` is `pub(crate)` there), so there is no
+//! way to reach an existing `IrisViewPeer` from a JNI entry point we define
+//! ourselves. Instead of forking android-view to add a hook, `new_peer`
+//! (`view.rs`) inserts the *same* id into this module's own map, pointing
+//! at a plain `Rc<RefCell<Shared>>` cloned into `AndroidUiState` too --
+//! so writing here is reading there, with no dependency in either
+//! direction on the other's internals.
+
+use android_view::{
+    View,
+    jni::{
+        JNIEnv, NativeMethod,
+        descriptors::Desc,
+        objects::JClass,
+        sys::{jint, jlong},
+    },
+};
+use std::{
+    cell::RefCell,
+    collections::HashMap,
+    ffi::c_void,
+    rc::Rc,
+    sync::{Mutex, OnceLock},
+};
+
+use send_wrapper::SendWrapper;
+
+#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
+pub struct Insets {
+    pub left: i32,
+    pub top: i32,
+    pub right: i32,
+    pub bottom: i32,
+    /// The keyboard's own inset (`WindowInsetsCompat.Type.ime()`), separate
+    /// from `bottom` (the system bars): a layout wants to know about the
+    /// keyboard specifically, since it usually means "make room" rather
+    /// than "stay clear of a corner".
+    pub ime_bottom: i32,
+}
+
+#[derive(Default)]
+pub struct Shared {
+    pub insets: Insets,
+}
+
+type SharedMap = HashMap<jlong, SendWrapper<Rc<RefCell<Shared>>>>;
+
+fn map() -> &'static Mutex<SharedMap> {
+    static MAP: OnceLock<Mutex<SharedMap>> = OnceLock::new();
+    MAP.get_or_init(Default::default)
+}
+
+/// Called from `view::new_peer` with the same id android-view's
+/// `register_view_peer` returned, so a later `apply_window_insets` call
+/// (keyed on that id by Java, which only ever sees the one long) reaches
+/// the same `Shared` cell `AndroidUiState` reads from.
+pub(super) fn register(id: jlong, shared: Rc<RefCell<Shared>>) {
+    map().lock().unwrap().insert(id, SendWrapper::new(shared));
+}
+
+extern "system" fn unregister_insets<'local>(
+    _env: JNIEnv<'local>,
+    _view: View<'local>,
+    peer: jlong,
+) {
+    map().lock().unwrap().remove(&peer);
+}
+
+extern "system" fn apply_window_insets<'local>(
+    mut env: JNIEnv<'local>,
+    view: View<'local>,
+    peer: jlong,
+    left: jint,
+    top: jint,
+    right: jint,
+    bottom: jint,
+    ime_bottom: jint,
+) {
+    if let Some(shared) = map().lock().unwrap().get(&peer) {
+        shared.borrow_mut().insets = Insets {
+            left,
+            top,
+            right,
+            bottom,
+            ime_bottom,
+        };
+    }
+    // Insets can change (the keyboard opening) with no resize and no
+    // touch, so nothing else here would otherwise ask for a frame.
+    view.post_frame_callback(&mut env);
+}
+
+/// Registers `applyWindowInsetsNative` on the app's own `View` subclass.
+/// Called once from `JNI_OnLoad` alongside `android_view::register_view_class`.
+pub fn register_native_methods<'local, 'other_local>(
+    env: &mut JNIEnv<'local>,
+    class: impl Desc<'local, JClass<'other_local>>,
+) {
+    env.register_native_methods(
+        class,
+        &[
+            NativeMethod {
+                name: "applyWindowInsetsNative".into(),
+                sig: "(JIIIII)V".into(),
+                fn_ptr: apply_window_insets as *mut c_void,
+            },
+            NativeMethod {
+                name: "unregisterInsetsNative".into(),
+                sig: "(J)V".into(),
+                fn_ptr: unregister_insets as *mut c_void,
+            },
+        ],
+    )
+    .unwrap();
+}

iris/src/android/mod.rs

@@ -0,0 +1,43 @@
+//! iris's second windowing backend: `android-view` (a `SurfaceView` plus a
+//! JNI `ViewPeer`) instead of winit. See RUST.md's I2 for why this exists
+//! as a second backend rather than winit's own (unfinished, and blocked on
+//! `android-activity`'s backend-feature requirement) Android support, and
+//! for the pass condition this was built against.
+//!
+//! Structured to mirror `default/` module for module: `view.rs` is that
+//! module's `app.rs` + `state.rs` combined (android-view has one harness
+//! type, `ViewPeer`, where winit splits `ApplicationHandler` from the
+//! per-window state), `render.rs` is `render.rs`, `input.rs` is `input.rs`,
+//! `attr.rs` is `attr.rs`. `ime.rs` and `insets.rs` have no winit
+//! counterpart: winit cannot drive an IME beyond `Ime::Preedit`/`Commit`
+//! (RUST.md's E1) and has no concept of Android's window insets at all.
+
+mod access;
+mod attr;
+mod ime;
+mod input;
+mod insets;
+mod render;
+mod view;
+
+pub use insets::Insets;
+pub use render::AndroidRenderer;
+pub use view::{
+    AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState, IrisViewPeer, new_peer,
+};
+
+/// Registers the extra native methods this backend needs beyond what
+/// `android_view::register_view_class` covers (window insets -- see
+/// `insets.rs`'s doc comment for why that one could not ride along on an
+/// existing android-view callback the way the back gesture does). Call
+/// from `JNI_OnLoad` alongside `register_view_class`, on the same `View`
+/// subclass.
+pub fn register_native_methods<'local, 'other_local>(
+    env: &mut android_view::jni::JNIEnv<'local>,
+    class: impl android_view::jni::descriptors::Desc<
+        'local,
+        android_view::jni::objects::JClass<'other_local>,
+    >,
+) {
+    insets::register_native_methods(env, class);
+}

iris/src/android/render.rs

@@ -0,0 +1,194 @@
+use crate::task::RequestRedraw;
+use android_view::{
+    View,
+    jni::{JavaVM, objects::GlobalRef},
+    ndk::native_window::NativeWindow,
+};
+use iris_core::{UiData, UiRenderNode, UiRenderState};
+use pollster::FutureExt;
+use wgpu::{
+    rwh::{DisplayHandle, HandleError, HasDisplayHandle, HasWindowHandle, WindowHandle},
+    *,
+};
+
+pub const CLEAR_COLOR: Color = Color::BLACK;
+
+/// `NativeWindow` (from the surface android-view hands over in
+/// `surfaceChanged`) has a window handle but not a display one -- there is
+/// exactly one display on Android and `rwh` has a unit variant for it.
+/// Mirrors android-view's own demo (`demo/src/lib.rs`'s
+/// `AndroidWindowHandle`).
+struct AndroidWindowHandle {
+    window: NativeWindow,
+}
+
+impl HasDisplayHandle for AndroidWindowHandle {
+    fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
+        Ok(DisplayHandle::android())
+    }
+}
+
+impl HasWindowHandle for AndroidWindowHandle {
+    fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError> {
+        self.window.window_handle()
+    }
+}
+
+/// The android-view surface, unlike winit's window, does not outlive a
+/// backgrounding of the activity: `surfaceDestroyed`/`surfaceCreated` (via
+/// `SurfaceHolder.Callback`) recreate it, so this holds everything that
+/// depends on that surface rather than being built once at startup --
+/// `AndroidUiState` holds it as `Option<AndroidRenderer>`, `None` exactly
+/// when there is no surface to draw into.
+pub struct AndroidRenderer {
+    surface: Surface<'static>,
+    device: Device,
+    queue: Queue,
+    config: SurfaceConfiguration,
+    encoder: CommandEncoder,
+    pub ui: UiRenderNode,
+}
+
+impl AndroidRenderer {
+    pub fn new(window: NativeWindow, width: u32, height: u32) -> Self {
+        let instance = Instance::new(&InstanceDescriptor {
+            backends: Backends::PRIMARY,
+            ..Default::default()
+        });
+
+        // SAFETY: the `NativeWindow` outlives the surface built from it --
+        // android-view drops the old renderer (and this surface with it)
+        // before handing over a new window, in `surface_changed` below.
+        let surface = instance
+            .create_surface(SurfaceTarget::from(AndroidWindowHandle { window }))
+            .expect("Could not create android surface!");
+
+        let adapter = instance
+            .request_adapter(&RequestAdapterOptions {
+                power_preference: PowerPreference::default(),
+                compatible_surface: Some(&surface),
+                force_fallback_adapter: false,
+            })
+            .block_on()
+            .expect("Could not get adapter!");
+
+        // Same request as the winit backend's `UiRenderer::new` -- no
+        // binding-array features, see TEXTURES.md's "Recommended shape".
+        let (device, queue) = adapter
+            .request_device(&DeviceDescriptor {
+                required_limits: Limits {
+                    max_buffer_size: 1 << 30,
+                    ..Default::default()
+                },
+                ..Default::default()
+            })
+            .block_on()
+            .expect("Could not get device!");
+
+        let surface_caps = surface.get_capabilities(&adapter);
+        let surface_format = surface_caps
+            .formats
+            .iter()
+            .copied()
+            .find(|f| f.is_srgb())
+            .unwrap_or(surface_caps.formats[0]);
+
+        let config = SurfaceConfiguration {
+            usage: TextureUsages::RENDER_ATTACHMENT,
+            format: surface_format,
+            width,
+            height,
+            present_mode: PresentMode::AutoVsync,
+            alpha_mode: surface_caps.alpha_modes[0],
+            desired_maximum_frame_latency: 2,
+            view_formats: vec![],
+        };
+        surface.configure(&device, &config);
+
+        let encoder = Self::create_encoder(&device);
+        let ui = UiRenderNode::new(&device, &queue, &config);
+
+        Self {
+            surface,
+            device,
+            queue,
+            config,
+            encoder,
+            ui,
+        }
+    }
+
+    fn create_encoder(device: &Device) -> CommandEncoder {
+        device.create_command_encoder(&CommandEncoderDescriptor {
+            label: Some("Render Encoder"),
+        })
+    }
+
+    pub fn update(&mut self, ui: &mut UiData, render: &mut UiRenderState) {
+        self.ui.update(&self.device, &self.queue, ui, render);
+    }
+
+    pub fn draw(&mut self) {
+        let output = self.surface.get_current_texture().unwrap();
+        let view = output
+            .texture
+            .create_view(&TextureViewDescriptor::default());
+
+        let mut encoder = std::mem::replace(&mut self.encoder, Self::create_encoder(&self.device));
+        {
+            let render_pass = &mut encoder.begin_render_pass(&RenderPassDescriptor {
+                color_attachments: &[Some(RenderPassColorAttachment {
+                    view: &view,
+                    resolve_target: None,
+                    ops: Operations {
+                        load: LoadOp::Clear(CLEAR_COLOR),
+                        store: StoreOp::Store,
+                    },
+                    depth_slice: None,
+                })],
+                ..Default::default()
+            });
+            self.ui.draw(render_pass);
+        }
+
+        self.queue.submit(std::iter::once(encoder.finish()));
+        output.present();
+    }
+
+    pub fn size(&self) -> iris_core::util::Vec2 {
+        (self.config.width, self.config.height).into()
+    }
+
+    pub fn resize(&mut self, width: u32, height: u32) {
+        self.config.width = width;
+        self.config.height = height;
+        self.surface.configure(&self.device, &self.config);
+        self.ui.resize((width, height), &self.queue);
+    }
+}
+
+/// `Tasks`' redraw handle on Android: a background task finishes on the
+/// tokio thread `Tasks::init` spawned, which is not attached to the JVM, so
+/// asking for a frame means attaching first. `post_frame_callback` needs a
+/// live `View` reference; the global ref is what survives past the JNI call
+/// that handed it to us.
+pub struct AndroidRedrawHandle {
+    vm: JavaVM,
+    view: GlobalRef,
+}
+
+impl AndroidRedrawHandle {
+    pub fn new(vm: JavaVM, view: GlobalRef) -> Self {
+        Self { vm, view }
+    }
+}
+
+impl RequestRedraw for AndroidRedrawHandle {
+    fn request_redraw(&self) {
+        let Ok(mut env) = self.vm.attach_current_thread() else {
+            return;
+        };
+        let local = env.new_local_ref(&self.view).unwrap();
+        View(local).post_frame_callback(&mut env);
+    }
+}

iris/src/android/view.rs

@@ -0,0 +1,543 @@
+use crate::prelude::*;
+use crate::task::RequestRedraw;
+use accesskit_android::Adapter as AccessAdapter;
+use android_view::{
+    AccessibilityNodeInfo, AccessibilityNodeProvider, Bundle, CallbackCtx, Context,
+    InputConnection, KeyEvent, MotionEvent, Rect, View, ViewPeer,
+    jni::{JNIEnv, sys::jint},
+    ndk::event::{Keycode, MotionAction},
+};
+// `marker::Sized` explicitly: `crate::prelude::*` below also brings in the
+// `Sized` *widget* (`widget::position::sized::Sized`), and an unqualified
+// glob import shadows the language prelude -- `default/mod.rs` has the same
+// explicit import for the same reason.
+use std::{
+    cell::RefCell,
+    marker::{PhantomData, Sized},
+    rc::Rc,
+    sync::Arc,
+    time::Instant,
+};
+
+use super::{
+    access::{AndroidAccessSource, NullActionHandler, raise_if_enabled},
+    insets::{Insets, Shared},
+    render::{AndroidRedrawHandle, AndroidRenderer},
+};
+
+/// The android-view analogue of `default::DefaultUiState`. `renderer` is an
+/// `Option` because a `SurfaceView`'s surface does not outlive backgrounding
+/// the way a winit `Window` does -- `surfaceDestroyed`/`surfaceCreated` can
+/// happen any number of times over the life of one `IrisViewPeer`.
+pub struct AndroidUiState {
+    pub root: Option<StrongWidget>,
+    pub renderer: Option<AndroidRenderer>,
+    pub focus: Option<WeakWidget<TextEdit>>,
+    pub cursor: CursorState,
+    pub last_click: Instant,
+    /// The IME preedit's previous length, in `char`s -- the same
+    /// re-send-the-whole-composition bookkeeping `default::DefaultUiState`
+    /// keeps for winit's `Ime::Preedit`, since android-view's
+    /// `setComposingText` has the identical shape (see `android/ime.rs`).
+    pub compose_len: usize,
+    /// Set by `attr::FocusHost::focus_gained` when a `TextEdit` is focused;
+    /// consumed by the touch handler after the sensor pass finishes, since
+    /// showing the keyboard is a JNI call and `focus_gained` runs deep
+    /// inside the platform-agnostic sensor dispatch with no `CallbackCtx`
+    /// in reach.
+    pub pending_show_keyboard: bool,
+    /// Window insets, filled in from outside the normal `ViewPeer` callback
+    /// path -- see `android/insets.rs` for why they need a registry of
+    /// their own.
+    shared: Rc<RefCell<Shared>>,
+    /// I4 (RUST.md): pushed from `IrisViewPeer::render` and consulted by
+    /// the `AccessibilityNodeProvider` impl below; see `android/access.rs`
+    /// for the abort mitigation every `raise` on it goes through.
+    pub access_adapter: AccessAdapter,
+    /// The AccessKit tree itself -- see `iris_core::AccessTree`'s doc
+    /// comment.
+    pub access: AccessTree,
+}
+
+impl AndroidUiState {
+    fn new(shared: Rc<RefCell<Shared>>) -> Self {
+        Self {
+            root: None,
+            renderer: None,
+            focus: None,
+            cursor: Default::default(),
+            last_click: Instant::now(),
+            compose_len: 0,
+            pending_show_keyboard: false,
+            shared,
+            access_adapter: Default::default(),
+            access: AccessTree::new(),
+        }
+    }
+
+    pub fn insets(&self) -> Insets {
+        self.shared.borrow().insets
+    }
+}
+
+impl HasRoot for AndroidUiState {
+    fn set_root(&mut self, root: StrongWidget) {
+        self.root = Some(root);
+    }
+}
+
+pub trait HasAndroidUiState: Sized + 'static {
+    fn android_state(&self) -> &AndroidUiState;
+    fn android_state_mut(&mut self) -> &mut AndroidUiState;
+}
+
+pub trait AndroidAppState: HasAndroidUiState {
+    fn new(ui_state: AndroidUiState, rsc: &mut AndroidRsc<Self>) -> Self;
+    /// The system back gesture/button. `true` means handled -- nothing
+    /// further happens; `false` lets the activity finish as it would with
+    /// no view at all. The default declines, since most screens have
+    /// nothing to intercept it for.
+    #[allow(unused_variables)]
+    fn back_pressed(&mut self, rsc: &mut AndroidRsc<Self>, render: &mut UiRenderState) -> bool {
+        false
+    }
+}
+
+/// The android-view analogue of `default::DefaultRsc` -- identical in
+/// substance, since none of `UiRsc`/`HasEvents`/`HasTasks`/`HasWidgetState`
+/// mention winit. Kept as a separate type rather than shared code because
+/// the two backends' `ViewPeer`/`ApplicationHandler` entry points hold
+/// their harness state differently (see RUST.md's I2).
+pub struct AndroidRsc<State: 'static> {
+    pub ui: UiData,
+    pub events: EventManager<Self>,
+    pub tasks: Tasks<Self>,
+    pub state: WidgetState,
+    _state: PhantomData<State>,
+}
+
+impl<State> AndroidRsc<State> {
+    pub fn create_state<T: 'static>(&mut self, id: impl IdLike, data: T) -> WeakState<T> {
+        self.state.add(id.id(), data)
+    }
+}
+
+impl<State> UiRsc for AndroidRsc<State> {
+    fn ui(&self) -> &UiData {
+        &self.ui
+    }
+    fn ui_mut(&mut self) -> &mut UiData {
+        &mut self.ui
+    }
+    fn on_draw(&mut self, active: &ActiveData) {
+        self.events.draw(active);
+    }
+    fn on_undraw(&mut self, active: &ActiveData) {
+        self.events.undraw(active);
+    }
+    fn on_remove(&mut self, id: WidgetId) {
+        self.events.remove(id);
+        self.state.remove(id);
+    }
+}
+
+impl<State: 'static> HasState for AndroidRsc<State> {
+    type State = State;
+}
+
+impl<State: 'static> HasEvents for AndroidRsc<State> {
+    fn events(&self) -> &EventManager<Self> {
+        &self.events
+    }
+    fn events_mut(&mut self) -> &mut EventManager<Self> {
+        &mut self.events
+    }
+}
+
+impl<State: 'static> HasTasks for AndroidRsc<State> {
+    fn tasks_mut(&mut self) -> &mut Tasks<Self> {
+        &mut self.tasks
+    }
+}
+
+impl<State: 'static> HasWidgetState for AndroidRsc<State> {
+    fn widget_state(&self) -> &WidgetState {
+        &self.state
+    }
+    fn widget_state_mut(&mut self) -> &mut WidgetState {
+        &mut self.state
+    }
+}
+
+/// The `ViewPeer` android-view dispatches every callback to. One per
+/// `RustView` instance; `new_peer` (below) builds it and hands the id to
+/// Java the same way android-view's own demo does.
+pub struct IrisViewPeer<State: AndroidAppState> {
+    pub(super) rsc: AndroidRsc<State>,
+    pub(super) render: UiRenderState,
+    pub(super) state: State,
+    task_recv: TaskMsgReceiver<AndroidRsc<State>>,
+}
+
+impl<State: 'static, I: RscIdx<AndroidRsc<State>>> std::ops::Index<I> for AndroidRsc<State> {
+    type Output = I::Output;
+
+    fn index(&self, index: I) -> &Self::Output {
+        index.get(self)
+    }
+}
+
+impl<State: 'static, I: RscIdx<AndroidRsc<State>>> std::ops::IndexMut<I> for AndroidRsc<State> {
+    fn index_mut(&mut self, index: I) -> &mut Self::Output {
+        index.get_mut(self)
+    }
+}
+
+impl<State: AndroidAppState> IrisViewPeer<State> {
+    fn drain_tasks(&mut self) {
+        while let Ok(update) = self.task_recv.try_recv() {
+            update(&mut self.state, &mut self.rsc);
+        }
+    }
+
+    /// Common tail for every callback that might have changed the cursor,
+    /// the text focus, or the widget tree: run the sensors that touch
+    /// input feeds, then ask for a frame if the result needs drawing.
+    /// Mirrors `default::DefaultApp::window_event`'s tail, split across
+    /// android-view's several entry points instead of winit's one.
+    pub(super) fn after_input(&mut self, ctx: &mut CallbackCtx) {
+        let window_size = self.window_size();
+        let ui_state = self.state.android_state_mut();
+        let cursor = ui_state.cursor.clone();
+        let old_focus = ui_state.focus;
+        self.render
+            .run_sensors(&mut self.rsc, &mut self.state, cursor, window_size);
+
+        let ui_state = self.state.android_state_mut();
+        if old_focus != ui_state.focus
+            && let Some(old) = old_focus
+        {
+            old.edit(&mut self.rsc).deselect();
+        }
+        if std::mem::take(&mut ui_state.pending_show_keyboard) {
+            show_soft_input(&mut ctx.env, &ctx.view);
+        }
+
+        let ui_state = self.state.android_state_mut();
+        ui_state.cursor.end_frame();
+        if self.render.needs_redraw(&ui_state.root, self.rsc.widgets()) {
+            ctx.view.post_frame_callback(&mut ctx.env);
+        }
+    }
+
+    fn window_size(&self) -> Vec2 {
+        let ui_state = self.state.android_state();
+        match &ui_state.renderer {
+            Some(r) => r.size(),
+            None => Vec2::ZERO,
+        }
+    }
+
+    /// The `log::debug!` calls here are a live diagnostic for a still-open
+    /// finding (RUST.md's I2): layout runs and reports the right pixel
+    /// region for the root (confirmed via `window_region`, logged below),
+    /// and the clear colour reaches the screen (confirmed by swapping it to
+    /// magenta and screenshotting), but no primitive ever appears on top of
+    /// it -- on both the Vulkan/SwiftShader and GLES/virgl backends. Leave
+    /// these in until that is root-caused; removing them loses the exact
+    /// evidence a `logcat` capture needs to reproduce the state.
+    fn render(&mut self, ctx: &mut CallbackCtx) {
+        let ui_state = self.state.android_state();
+        if ui_state.renderer.is_none() {
+            return;
+        }
+        log::debug!(
+            "render(): root={:?} widgets={} active={} root_px={:?} out_size={:?}",
+            ui_state.root.is_some(),
+            self.rsc.widgets().len(),
+            self.render.active_widgets(),
+            ui_state
+                .root
+                .as_ref()
+                .and_then(|r| self.render.window_region(r, &self.rsc)),
+            self.window_size(),
+        );
+        let ui_state = self.state.android_state_mut();
+        self.render.update(&ui_state.root, &mut self.rsc);
+        let ui_state = self.state.android_state_mut();
+        let Some(renderer) = &mut ui_state.renderer else {
+            return;
+        };
+        renderer.update(&mut self.rsc.ui, &mut self.render);
+        renderer.draw();
+        let ui_state = self.state.android_state();
+        log::debug!(
+            "render(): after update active={} root_px={:?}",
+            self.render.active_widgets(),
+            ui_state
+                .root
+                .as_ref()
+                .and_then(|r| self.render.window_region(r, &self.rsc)),
+        );
+
+        // I4 (RUST.md): only produces a `TreeUpdate` -- and so only queues
+        // anything to raise -- when the named set actually changed this
+        // frame; see `AccessTree`'s doc comment. Deferred rather than
+        // raised inline so it runs after this callback releases whatever
+        // it's holding, matching android-view's own demo and `raise`'s own
+        // contract.
+        let ui_state = self.state.android_state_mut();
+        if let Some(tree_update) =
+            ui_state
+                .access
+                .update(self.rsc.widgets(), &self.render, &self.rsc)
+        {
+            let ui_state = self.state.android_state_mut();
+            if let Some(events) = ui_state.access_adapter.update_if_active(|| tree_update) {
+                ctx.push_dynamic_deferred_callback(move |env, view| {
+                    raise_if_enabled(env, view, events);
+                });
+            }
+        }
+    }
+}
+
+fn show_soft_input<'local>(env: &mut JNIEnv<'local>, view: &View<'local>) {
+    let imm = view.input_method_manager(env);
+    imm.show_soft_input(env, view, 0);
+}
+
+impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
+    fn on_key_down<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        key_code: Keycode,
+        event: &KeyEvent<'local>,
+    ) -> bool {
+        self.drain_tasks();
+        // With no `OnBackPressedCallback` registered on the Java side, the
+        // system still delivers the back gesture as a synthetic
+        // `KEYCODE_BACK` through this same path -- the legacy behaviour
+        // every view-based app gets by default, and enough for "the back
+        // gesture as an event" without a second JNI registry. See
+        // `android/insets.rs`'s doc comment for why insets could not take
+        // the same shortcut.
+        if key_code == Keycode::Back {
+            let handled = self.state.back_pressed(&mut self.rsc, &mut self.render);
+            if handled {
+                self.after_input(ctx);
+            }
+            return handled;
+        }
+        let handled = super::input::on_key(
+            &mut self.rsc,
+            &mut self.state,
+            &mut ctx.env,
+            key_code,
+            event,
+        );
+        if handled {
+            self.after_input(ctx);
+        }
+        handled
+    }
+
+    fn on_touch_event<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        event: &MotionEvent<'local>,
+    ) -> bool {
+        self.drain_tasks();
+        let action = event.action_masked(&mut ctx.env);
+        let x = event.x(&mut ctx.env);
+        let y = event.y(&mut ctx.env);
+        let ui_state = self.state.android_state_mut();
+        match action {
+            MotionAction::Down => {
+                ui_state.cursor.pos = vec2(x, y);
+                ui_state.cursor.exists = true;
+                ui_state.cursor.buttons.left.update(true);
+            }
+            MotionAction::Move => {
+                ui_state.cursor.pos = vec2(x, y);
+            }
+            MotionAction::Up | MotionAction::Cancel => {
+                ui_state.cursor.pos = vec2(x, y);
+                ui_state.cursor.buttons.left.update(false);
+            }
+            _ => return false,
+        }
+        self.after_input(ctx);
+        true
+    }
+
+    fn on_focus_changed<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        gain_focus: bool,
+        _direction: i32,
+        _previously_focused_rect: Option<&Rect<'local>>,
+    ) {
+        self.drain_tasks();
+        if !gain_focus {
+            let ui_state = self.state.android_state_mut();
+            if let Some(focus) = ui_state.focus.take() {
+                focus.edit(&mut self.rsc).deselect();
+            }
+        }
+        self.after_input(ctx);
+    }
+
+    fn on_attached_to_window(&mut self, _ctx: &mut CallbackCtx) {
+        self.drain_tasks();
+    }
+
+    fn surface_changed<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        holder: &android_view::SurfaceHolder<'local>,
+        _format: i32,
+        width: i32,
+        height: i32,
+    ) {
+        self.drain_tasks();
+        let window = holder.surface(&mut ctx.env).to_native_window(&mut ctx.env);
+        // The layout engine's own notion of the canvas size is separate
+        // from the wgpu surface's -- winit's backend sets it from
+        // `WindowEvent::Resized`, and there is no equivalent automatic
+        // trigger here, so this is the one place android-view's surface
+        // size has to be told to `UiRenderState` too. Missing this drew
+        // nothing but the clear colour: the widget tree laid out against
+        // whatever size `UiRenderState::new` starts at instead of the
+        // surface's real one.
+        self.render.resize((width as u32, height as u32));
+        // Drop the old renderer (and the surface it owns) before building
+        // one from the new window -- see `AndroidRenderer`'s doc comment.
+        let ui_state = self.state.android_state_mut();
+        ui_state.renderer = None;
+        ui_state.renderer = Some(AndroidRenderer::new(window, width as u32, height as u32));
+        self.render(ctx);
+    }
+
+    fn surface_destroyed<'local>(
+        &mut self,
+        _ctx: &mut CallbackCtx<'local>,
+        _holder: &android_view::SurfaceHolder<'local>,
+    ) {
+        self.state.android_state_mut().renderer = None;
+    }
+
+    fn do_frame(&mut self, ctx: &mut CallbackCtx, _frame_time_nanos: i64) {
+        self.drain_tasks();
+        self.render(ctx);
+    }
+
+    fn as_input_connection(&mut self) -> Option<&mut dyn InputConnection> {
+        Some(self)
+    }
+
+    fn as_accessibility_node_provider(&mut self) -> Option<&mut dyn AccessibilityNodeProvider> {
+        Some(self)
+    }
+}
+
+impl<State: AndroidAppState> AccessibilityNodeProvider for IrisViewPeer<State> {
+    fn create_accessibility_node_info<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        virtual_view_id: jint,
+    ) -> AccessibilityNodeInfo<'local> {
+        let mut source = AndroidAccessSource {
+            widgets: self.rsc.widgets(),
+            render: &self.render,
+            rsc: &self.rsc,
+        };
+        let ui_state = self.state.android_state_mut();
+        AccessibilityNodeInfo(ui_state.access_adapter.create_accessibility_node_info(
+            &mut source,
+            &mut ctx.env,
+            &ctx.view.0,
+            virtual_view_id,
+        ))
+    }
+
+    fn find_focus<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        focus_type: jint,
+    ) -> AccessibilityNodeInfo<'local> {
+        let mut source = AndroidAccessSource {
+            widgets: self.rsc.widgets(),
+            render: &self.render,
+            rsc: &self.rsc,
+        };
+        let ui_state = self.state.android_state_mut();
+        AccessibilityNodeInfo(ui_state.access_adapter.find_focus(
+            &mut source,
+            &mut ctx.env,
+            &ctx.view.0,
+            focus_type,
+        ))
+    }
+
+    fn perform_action<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        virtual_view_id: jint,
+        action: jint,
+        arguments: &Bundle<'local>,
+    ) -> bool {
+        let Some(action) =
+            accesskit_android::PlatformAction::from_java(&mut ctx.env, action, &arguments.0)
+        else {
+            return false;
+        };
+        let ui_state = self.state.android_state_mut();
+        let Some(events) = ui_state.access_adapter.perform_action(
+            &mut NullActionHandler,
+            virtual_view_id,
+            &action,
+        ) else {
+            return false;
+        };
+        ctx.push_dynamic_deferred_callback(move |env, view| {
+            raise_if_enabled(env, view, events);
+        });
+        true
+    }
+}
+
+/// Registers `IrisViewPeer<State>`'s native methods and builds one on every
+/// `newViewPeer` call from Java. `State`'s app crate wraps this in a
+/// concrete `extern "system" fn` (a generic function cannot be handed to
+/// `register_view_class`, which wants a plain function pointer) -- see
+/// `iris/android-app/src/lib.rs`.
+pub fn new_peer<'local, State: AndroidAppState>(
+    env: JNIEnv<'local>,
+    view: View<'local>,
+    _context: Context<'local>,
+) -> android_view::jni::sys::jlong {
+    let vm = env.get_java_vm().unwrap();
+    let global_view = env.new_global_ref(&view.0).unwrap();
+    let redraw: Arc<dyn RequestRedraw> = Arc::new(AndroidRedrawHandle::new(vm, global_view));
+    let (tasks, task_recv) = Tasks::init(redraw);
+    let mut rsc = AndroidRsc {
+        ui: Default::default(),
+        events: Default::default(),
+        tasks,
+        state: Default::default(),
+        _state: PhantomData,
+    };
+    let shared = Rc::new(RefCell::new(Shared::default()));
+    let ui_state = AndroidUiState::new(shared.clone());
+    let state = State::new(ui_state, &mut rsc);
+    let peer = IrisViewPeer {
+        rsc,
+        render: UiRenderState::new(),
+        state,
+        task_recv,
+    };
+    let id = android_view::register_view_peer(peer);
+    super::insets::register(id, shared);
+    id
+}

iris/src/attr.rs

@@ -0,0 +1,105 @@
+use crate::prelude::*;
+use std::time::{Duration, Instant};
+
+/// What focusing a text field takes from whichever backend is running --
+/// tracked here rather than duplicated per backend, since `Selector` and
+/// `Selectable` (below) are the *only* thing that decides which `TextEdit`
+/// is the IME's target, and both platforms need the same double-click
+/// timing and the same "remember which one" bookkeeping. What differs is
+/// what happens *after* the focus record is set: winit tells the
+/// compositor an IME area (`focus_gained`, in `default/attr.rs`); on
+/// android-view a keyboard has to be asked for explicitly, and only from a
+/// JNI call this crate cannot make outside a view callback -- so
+/// `focus_gained` there (`android/attr.rs`) just raises a flag the next
+/// touch callback consumes. See RUST.md's I2.
+pub trait FocusHost {
+    /// True on a click close enough in time to the previous one to grow a
+    /// selection instead of starting a new one, updating the clock as a
+    /// side effect the way a real double-click timer does.
+    fn recent_click(&mut self) -> bool;
+    fn set_focus(&mut self, id: Option<WeakWidget<TextEdit>>);
+    /// Called after a `TextEdit` becomes the focus target, with the region
+    /// it was hit in (`None` when the widget could not be located, which
+    /// happens for one it was just deselected from).
+    fn focus_gained(&mut self, region: Option<PixelRegion>);
+}
+
+/// Helper shared by every `FocusHost` impl, so the double-click window is
+/// one constant rather than one per backend.
+pub fn recent_click(last_click: &mut Instant) -> bool {
+    let now = Instant::now();
+    let recent = (now - *last_click) < Duration::from_millis(300);
+    *last_click = now;
+    recent
+}
+
+pub struct Selector;
+
+impl<Rsc: HasEvents, W: Widget + 'static> WidgetAttr<Rsc, W> for Selector
+where
+    Rsc::State: FocusHost,
+{
+    type Input = WeakWidget<TextEdit>;
+
+    fn run(rsc: &mut Rsc, container: WeakWidget<W>, id: Self::Input) {
+        rsc.register_event(container, CursorSense::click_or_drag(), move |ctx, rsc| {
+            let region = ctx.data.render.window_region(&id, &*rsc).unwrap();
+            let id_pos = region.top_left;
+            let container_pos = ctx
+                .data
+                .render
+                .window_region(&container, &*rsc)
+                .unwrap()
+                .top_left;
+            let pos = ctx.data.pos + container_pos - id_pos;
+            let size = region.size();
+            select(
+                rsc,
+                ctx.data.render,
+                ctx.state,
+                id,
+                pos,
+                size,
+                ctx.data.sense.is_dragging(),
+            );
+        });
+    }
+}
+
+pub struct Selectable;
+
+impl<Rsc: HasEvents> WidgetAttr<Rsc, TextEdit> for Selectable
+where
+    Rsc::State: FocusHost,
+{
+    type Input = ();
+
+    fn run(rsc: &mut Rsc, id: WeakWidget<TextEdit>, _: Self::Input) {
+        rsc.register_event(id, CursorSense::click_or_drag(), move |ctx, rsc| {
+            select(
+                rsc,
+                ctx.data.render,
+                ctx.state,
+                id,
+                ctx.data.pos,
+                ctx.data.size,
+                ctx.data.sense.is_dragging(),
+            );
+        });
+    }
+}
+
+fn select(
+    rsc: &mut impl UiRsc,
+    render: &UiRenderState,
+    state: &mut impl FocusHost,
+    id: WeakWidget<TextEdit>,
+    pos: Vec2,
+    size: Vec2,
+    dragging: bool,
+) {
+    let recent = state.recent_click();
+    id.edit(rsc).select(pos, size, dragging, recent);
+    state.set_focus(Some(id));
+    state.focus_gained(render.window_region(&id, &*rsc));
+}

iris/src/default/access.rs

@@ -0,0 +1,28 @@
+//! I4 (RUST.md): the desktop half of the AccessKit push, over
+//! `accesskit_winit`. `bench-lib.sh`'s tap-by-name goes through the
+//! platform's real accessibility tree, so this crate only has to keep that
+//! tree in sync with `ui::access::AccessTree`'s output -- nothing here
+//! reacts to an AccessKit action request, which is why the three handlers
+//! below are inert. See RUST.md's I4 box for why: on Android (and, by the
+//! same platform convention, everywhere else) a screen reader's element tap
+//! is a real touch delivered at the node's own bounds, not an action
+//! request synthesised in-process -- so the ordinary pointer path already
+//! handles it once the bounds are right.
+use accesskit::{ActionHandler, ActionRequest, ActivationHandler, DeactivationHandler, TreeUpdate};
+
+pub struct NullActivationHandler;
+impl ActivationHandler for NullActivationHandler {
+    fn request_initial_tree(&mut self) -> Option<TreeUpdate> {
+        None
+    }
+}
+
+pub struct NullActionHandler;
+impl ActionHandler for NullActionHandler {
+    fn do_action(&mut self, _request: ActionRequest) {}
+}
+
+pub struct NullDeactivationHandler;
+impl DeactivationHandler for NullDeactivationHandler {
+    fn deactivate_accessibility(&mut self) {}
+}