client-core: an unasked page is not an empty one, and two guarded invariants

Review of 73251d6's port of TranscriptSource/joinPages.

`TranscriptSource::page` answered `before == 0` with an empty `Vec`, which
is the same value it answers "this conversation has no more history" with.
That is the state the Kotlin keeps apart: `loadOlderPage` returns false at
`oldestSeq == 0` *without* touching `moreHistory`, and returns false on an
empty page *by latching it*. Collapsing the two moved AGENTS.md's paging
bug one layer down rather than fixing it. `page` returns `OlderPage` now --
`Events(vec![])` is the start of the conversation, `NothingLoaded` is not
an answer about the conversation at all.

`join_pages`' `debug_assert!` on seq ordering across the boundary is not a
true invariant: a peer note carries the seq its turn began at, which can be
older than the page it arrived in, so an ordinary transcript would have
panicked a debug build there. Replaced with the one the function exists to
enforce -- no tool id surviving in both halves.

`fetch_transcript_lines` stores `RawValue`'s exact server bytes, so the
"neither source can produce a newline" comment in `SessionCache::append`
now rests on the server's serializer staying compact rather than on a
local normalization. Checked with a `debug_assert!` in `append` and
`store_page` rather than trusted.

Tests for the failure half, which the port had none of: a 500 mid-page, a
cached line this build cannot read, and the `after` bound in the case that
actually carries one (the existing test asserted only the case with no
bound). `cargo fmt`, `cargo clippy --all-targets`, `cargo test` (112) clean
in client-core; `cargo check -p desktop-app` clean.

.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).
@@ -21,3 +29,14 @@ certs/
 config.ron
 config.json
 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/

AGENTS.md

@@ -5,19 +5,14 @@ replacing the Claude app for daily use. Rust/Axum backend on the desktop,
 Kotlin/Compose Android app, WireGuard + pinned self-signed TLS + bearer token
 between them.
 
-**`PLAN.md` is the design source of truth** — every decision with its date,
-its rationale, and what was rejected. Read it before changing anything
+**`docs/PLAN.md` is the design source of truth** — every decision with its
+date, its rationale, and what was rejected. Read it before changing anything
 structural, and update it in place when a decision changes rather than
 letting this file and the plan become two versions of the truth. This file is
-the working notes layer: layout, commands, and things that have bitten.
-
-**The rigs are the `ai-app-rigs` skill** — the sandbox and bench scripts, the
-rule that no UI-driving script may tap a coordinate, how to test llama.cpp and
-ssh here, how importing behaves, and the measurements not worth re-taking.
-They moved there on 2026-09-04 because they are 12 KB that only matter once
-you are actually running one, and this file is sent with every request. Read
-it before writing or running a benchmark, driving the UI from a script, or
-touching the import screen.
+the working notes layer: layout, commands, rigs, and things that have bitten.
+The design and working documents live under `docs/` — everything except this
+file and `CLAUDE.md`, which stay at the root because that is where Claude
+Code and other agent harnesses look for them.
 
 The central design point, worth not undoing by accident: **a session is a
 child process, translated into one common event model.** A new session type
@@ -30,23 +25,10 @@ Mirrors `../dev-updater` deliberately: same stack (axum 0.8 +
 axum-server/rustls, tokio, clap; Kotlin 2.4.x + Compose Multiplatform, single
 `:androidApp` module), same cert scheme, same registry pattern. Read
 dev-updater's `README.md` and `AGENTS.md` before diverging from them.
-Module-by-module intent is in PLAN.md's "Backend layout".
+Module-by-module intent is in `docs/PLAN.md`'s "Backend layout".
 
 - `server/` — the Rust backend (`ai-server`). `routes.rs`'s module doc
   comment is the HTTP table and the surface's source of truth.
-  **A llama.cpp session runs on whatever machine its setup names** (built
-  2026-09-04, the last of phase 5): `Transport::reserve_port` returns the
-  port the server binds *there* and the port that reaches it *here*, and
-  `Launch::reaching` puts the `-L` tunnel on the connection already carrying
-  the command. Three things fell out of it and are easy to get wrong again —
-  a forwarded launch gets a pty (`-tt`) and every other one keeps `-T`,
-  because `llama-server` never reads the stdin whose closing ends a CLI and
-  the same kill left it loaded on the far machine; the model is looked for on
-  the machine that will serve it, so the spawn screen offers
-  `GET /setups/{id}/models` rather than the backend's own downloads; and the
-  readiness poll watches the process as well as the port, since a model that
-  will not load exits in a second and was being reported as "gave up after
-  300s". See PLAN.md's "Transport" and "llama-server management".
 - `app/` — the Compose app, package `com.example.aiapp`, label "AI Sessions".
   `AppRoot.kt` is the navigation `when`; `MainScreen.kt` the root's four tabs
   (sessions, import, models, setups); `Api.kt`/`EventStream.kt` the REST + SSE
@@ -61,16 +43,23 @@ Module-by-module intent is in PLAN.md's "Backend layout".
   projects version-locked to the commit this repo pins. What deliberately did
   **not** move is the API surface and the config *schema*: routes, drivers,
   sessions and setups are what makes this project itself.
-- `SUBAGENTS.md` — a session's subagents as transcripts of their own
-  (`server/src/session/subagent.rs`, the subcards in `SessionListScreen.kt`
-  and the read-only form of `SessionScreen.kt`); `DECISIONS.md` holds the
-  choices made there that are still awaiting review.
-- `EXPLORER.md` — the file explorer's design (`server/src/files.rs` and
-  `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
-- `TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent. Read it
-  before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or the opening
-  and stream effects in `SessionScreen.kt`.
-- `TODO.md` — the working list.
+- `docs/` — every design and working document except this file and
+  `CLAUDE.md`:
+  - `docs/EXPLORER.md` — the file explorer's design (`server/src/files.rs`
+    and `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
+  - `docs/TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent.
+    Read it before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or
+    the opening and stream effects in `SessionScreen.kt`.
+  - `docs/TODO.md` — the working list.
+  - `docs/RUST.md` — the plan for moving the app to Rust (on the `rustify`
+    branch of the `ai-app-2` clone): what has to be reproduced, the
+    framework decision, and the ordered experiments with their pass
+    conditions. Read it before touching anything under that branch.
+  - `docs/IRIS.md`, `docs/IRIS_TODO.md`, `docs/DECISIONS.md`,
+    `docs/LAYOUT.md`, `docs/TEXTURES.md`, `docs/CLIENT_CORE.md` — iris's
+    own public API log, working list, decisions log, layout/render design,
+    and texture-atlas design, and the client-core crate's design,
+    respectively.
 - `.dev-updater.ron` — what Dev Updater builds here: the server (run as
   `service: Managed(…)`, supervised by Dev Updater's own implementation
   rather than a script kept here) and the APK, in parallel. It points at
@@ -107,7 +96,11 @@ two icon buttons the same width without either being given one — and why
   :androidApp:compileDebugKotlin :androidApp:lintDebug
   :androidApp:testDebugUnitTest`. The unit tests are JVM-only and cover the
   syntax highlighter, the ANSI parser and the transcript cache — the app's
-  pure logic with no Android in it.
+  pure logic with no Android in it. Touching anything under `BenchFixture.kt`,
+  `BenchNetwork.kt`, `BenchRun.kt` or the `bench` build type also needs
+  `:androidApp:compileBenchKotlin :androidApp:lintBench` — a second build
+  type compiles separately and lint has caught real bugs debug alone never
+  would (see "Android Lint" below).
 - **Android Lint is not optional and is not run by a build.** It found a
   crash that had been shipping (`java.time` on a minSdk-24 app with
   desugaring off) and later a permission check that silently dropped every
@@ -163,6 +156,181 @@ two icon buttons the same width without either being given one — and why
   genuine handshake against 10.66.0.1 with pinned TLS, no router or phone
   involved. That is how to verify the wg0-only posture.
 
+## The rigs
+
+Each exists because something was invisible without it.
+
+- **The `bench` build type and `app/bench-fixture/`** exist for P0 (RUST.md
+  and DECISIONS.md's 2026-09-05 entries), the phone benchmark gate Iris
+  asked for before porting continues: a deterministic, checked-in synthetic
+  transcript (`app/bench-fixture/generate.py`, never a real one) that both
+  this app and iris open with no server, so a frame-time comparison
+  measures the renderer rather than the data. `./build-apk.sh bench` builds
+  it — own application id (`com.example.aiapp.bench`) and label ("AI
+  Sessions bench") so it installs beside a real enrollment rather than
+  replacing it. Opening it goes straight to a session screen holding the
+  fixture (no enrollment, no permission prompts) with a "Run benchmark"
+  control beside "Copy" in session settings: it drives the same scroll loop
+  and streaming phase `transcript-bench.sh`/`stream-bench.sh` drive over
+  `ui-trace`, but in-process, since a real phone has no usable system
+  tracing and no agent can drive one (this-machine-android's skill).
+  `BenchFixture.kt`/`BenchNetwork.kt` fake the backend by installing a
+  `URLStreamHandlerFactory` that answers `TranscriptSource`/`EventStream`'s
+  requests from an in-memory copy of the fixture instead of opening a
+  socket — so the fold, the paging and `uniqueItems` under test are the
+  screen's real ones, never a shortcut built just for this. The report
+  gains a `bench:` section (process CPU time, peak RSS, battery current) on
+  every build, empty except when `BenchRun.kt` filled it in.
+- **`app/ui-sandbox.sh`** — a second `ai-server` with its own `$HOME`, config
+  and data directory, holding eight invented Claude Code transcripts and a
+  `claude` that is two lines of shell. **That isolation is the point**: the
+  import screen lists whatever is in `~/.claude/projects`, which in this VM is
+  real agent transcripts, so exercising *delete* against the ordinary server
+  deletes somebody's conversation and exercising *import* starts a real
+  `--resume` on the owner's account.
+  Its port and root derive from the checkout's name, so two checkouts'
+  sandboxes cannot reach each other, and its token is generated once into
+  `~/.config/ai-app/sandbox-token` and carried across restarts along with any
+  the enrolment flow appended — so the emulator app is enrolled **once** (the
+  start banner prints the command) and stays enrolled. It shares the real TLS
+  certificates, because the installed APK pins that CA.
+  Driving verbs, so none of this is re-derived per session:
+  `./ui-sandbox.sh spawn [title]` (an echo session, prints its id),
+  `./ui-sandbox.sh send SID text|@file`, and
+  `./ui-sandbox.sh api /path [curl args]`.
+  `./ui-sandbox.sh keep` restarts the server without wiping the sessions and
+  enrolment already there — for when the fixture under test was expensive to
+  build; plain `start` wipes them, which is right for the list-screen
+  fixtures and wrong for that.
+  It passes `--delay` by default, and `AI_SANDBOX_BIG_MB` puts one large
+  transcript among the small ones while `AI_SANDBOX_SPAWN_DELAY` makes the
+  fake CLI slow to start. Both exist because operations that finish in
+  milliseconds have states on the way that nothing can observe, and an
+  unobservable state is one where broken and working look identical.
+  It also builds a fixture tree at the sandbox home's `~/files` for the
+  explorer, holding the states otherwise only reachable by finding a real
+  machine in one: an empty directory, a name with a tab and one with an
+  apostrophe, a binary file, one over `FILE_LIMIT`, one `chmod 000`, a
+  symlink to a directory and a broken one, a source file per language, and
+  the three sizes the limits were measured against (`edit-32k.rs`,
+  `edit-128k.rs`, `big-source.rs`). Point a session at it with
+  `./ui-sandbox.sh api /sessions/<id>/cwd -X POST -H 'content-type: application/json' -d '{"cwd":"~/files"}'`.
+  The explorer's 409 is produced by editing the file on the machine
+  (`printf … > file`) between pressing the pencil and pressing save.
+- **`app/debug-transcript.sh`** — a real conversation on the emulator. The
+  echo driver is the right rig for most things and the wrong one for anything
+  whose cost scales with what was actually written: a real reply is longer,
+  is real markdown, and carries tool calls whose input and output are
+  kilobytes. Two faults were invisible until a real transcript was loaded — a
+  page of history landing mid-fling threw the reader back to the newest end,
+  and parsing one real reply took 51ms against 4.6ms for a synthetic one.
+  `-b` takes the biggest conversation on the machine rather than the newest,
+  which is what a scrolling test wants; `--stop` takes it down.
+  It copies the transcript into `/tmp` and gives the server a `HOME` of its
+  own, so the import can only see the copy — importing spawns `claude
+  --resume`, and against the real file that is a second CLI writing to a
+  conversation somebody may still be in. **A transcript never goes in this
+  repository**: they hold whatever was said, read and written in that
+  session, and `~/repos` is shared with the host besides.
+- **A fake CLI exercises the process lifecycle without a token.** Point a
+  `claude_cli` provider's `command` at a two-line script — `#!/bin/sh` and
+  `cat > /dev/null` — and it behaves the way the lifecycle code cares about:
+  it holds the fifo open, records a real pid, writes nothing, and dies on a
+  signal. So adopt, stop, restart and start are all drivable without a real
+  `--resume` and without spending a turn on somebody's account. Reach for
+  this when what is under test is *whether a process is running*, and for
+  `debug-transcript.sh` when it is *what the transcript draws*.
+- **`app/transcript-bench.sh`** is the standard scroll measurement: it opens
+  the first session (or `-k` keeps the current screen), scrolls a fixed
+  gesture loop, and prints the app's render report — the same one the in-app
+  copy button produces, whose `on screen:` line names what the viewport was
+  holding. Compare two runs with the same gestures; the emulator's absolute
+  frame times transfer nothing, the report's accounting does. Run it either
+  side of any change under `Markdown*.kt`, `Transcript*.kt` or
+  `SessionScreen.kt`'s list, and put the report in the commit. The numbers
+  that move first are the worst `record: one block`, the reparse mean while
+  streaming, and the draw phase's accounting line.
+- **`app/stream-bench.sh [-k] FILE`** is that measurement for a reply still
+  arriving. It taps "Jump to latest" so the list is pinned to the newest end,
+  resets the report, sends FILE, waits for the transcript to stop growing,
+  and prints. Both of those are corrections to a first version that measured
+  nothing: a transcript parked further back never redraws while a reply
+  streams into it, and a session is idle at *both* ends of a turn, so polling
+  for idle answers before the turn has started.
+- **`app/trace-draw.sh`** names what a scrolling frame spends inside the
+  framework, from `atrace` text output with no trace processor needed. It is
+  how the cost of a layout node per link was attributed to the framework
+  rather than guessed at.
+- **`iris/android-app/build-apk.sh [debug|release] [--abi ...] [--features
+  ...]`** builds iris-android-app's cdylib (`cargo ndk`) and its APK
+  (Gradle) in one step and verifies the result (`aapt2`/`apksigner`), and
+  **`iris/android-app/run-bench.sh [--apk PATH]`** installs it on this
+  checkout's own emulator, taps "Run benchmark" by label, and prints the
+  report -- written so the P0 build/install/tap/read-report cycle stops
+  being retyped by hand each time (docs/RUST.md's P0 box).
+
+### Driving the UI
+
+**No script that drives this app's UI presses a coordinate.** Every control
+is found by the name it already carries for assistive technology —
+`ui-trace record --do "tap 'Session settings'"` — which resolves the label
+against the screen at the moment of the gesture and fails the whole run when
+it is not there. `app/bench-lib.sh` is what the bench scripts share for it. A
+coordinate is a position measured once by hand, and anything that moves the
+control makes the tap land on whatever now sits there — the bench then
+reports a number that was never measured, which reads exactly like a result.
+Both bench scripts pressed the render report at `tap 723 205` until that
+button moved into the session settings dialog on 2026-09-03. The check that
+none has crept back:
+
+    grep -n "tap [0-9]" app/*.sh
+
+Swipes are still coordinates, deliberately: a gesture across a scrolling area
+is a distance rather than a control.
+
+**Two traps in the emulator bench loop**, each of which cost a run.
+`adb shell pm clear` removes the enrolment and the notification permission
+along with the saved anchors, so the next run measures a permission dialog —
+re-enrol with the command `ui-sandbox.sh` prints, and
+`pm grant … POST_NOTIFICATIONS`. And a saved scroll anchor is per session id,
+so the only way two builds start a scroll from the same place is a *fresh
+session for each*.
+
+**The emulator is `~/repos/emulator-tools`' business, not this repo's.**
+`emu up` creates and boots the AVD named after this checkout — whatever `emu
+name` prints, never a name typed out here, since this file is the same in
+every clone. `run-android.sh` is that plus a build and an install. The `adb`
+on `PATH` after sourcing `android-env.sh` is that repo's wrapper, which fills
+in `-s` from the same rule. Gradle does not go through it, so a Gradle init
+script from `emulator-tools` runs `emu check` before `installDebug`,
+`uninstallDebug` and `connectedAndroidTest` and fails rather than fanning out
+to every attached device; when it refuses, say which device you mean at the
+moment you use it — `ANDROID_SERIAL=$(emu serial) ./gradlew …`.
+
+### Testing llama.cpp and ssh here
+
+The prebuilt CPU llama.cpp lives outside the repo at
+`~/.local/opt/llama.cpp` (the 15 MB `ubuntu-x64` release asset). It needs its
+own directory on `LD_LIBRARY_PATH`, so start the server as
+`LD_LIBRARY_PATH=~/.local/opt/llama.cpp ai-server …` and point a provider's
+`command` at `~/.local/opt/llama.cpp/llama-server`. A 0.6B Q8_0 answers at
+usable speed on this VM's 8 cores. **Do not test with a 2-bit quant**: the
+IQ2_XXS of that model produces fluent nonsense, which reads exactly like a
+broken driver — `llama-cli` produces the same from the file directly, which
+is how to tell the two apart in a hurry.
+
+There is no second machine, so **ssh this VM to itself**: generate a
+throwaway key, append the public half to `~/.ssh/authorized_keys`, and
+configure a host of `bob@127.0.0.1` with `identityFile` pointing at it plus
+`options: ["StrictHostKeyChecking=no", "UserKnownHostsFile=…"]` so it touches
+nothing real. Point a provider's `command` at something harmless like
+`/bin/echo` rather than at `claude`: the transport is what is under test, the
+process exiting immediately is the signal, and it costs no tokens. **Take the
+key back out afterwards.** The remote login shell here is **fish**; the
+remote script and `ssh.rs`'s POSIX quoting happen to mean the same thing in
+both, but that is luck rather than design, and a shell that is neither is the
+thing to suspect first if a remote spawn ever mangles an argument.
+
 ## Where things run (host vs this VM)
 
 The machine itself — the two boxes, the shared `~/repos` mount, and why the
@@ -186,7 +354,7 @@ means here:
 ## Sessions outlive the backend
 
 Since 2026-08-29 a session's process is deliberately left running when
-`ai-server` stops, and adopted again when it starts. PLAN.md has the design;
+`ai-server` stops, and adopted again when it starts. docs/PLAN.md has the design;
 day to day:
 
 - **Stopping the server no longer stops the sessions.** After `pkill
@@ -209,24 +377,42 @@ day to day:
   in `process.json`; removing either by hand while the session is live loses
   output or replays it.
 
-## Auto-resume
+## Importing
 
-**A session switched to it sends itself a message once the account's usage
-limit lifts** — off by default, per session, in the session settings dialog.
-PLAN.md's "Auto-resume" is the design; day to day:
+The import list reports each session's **size as well as its line count**,
+because the two disagree in the way that matters: these transcripts embed
+screenshots as base64, so one line can be a megabyte. On this machine a 69 MB
+session has 3,427 lines and a 44 MB one has 6,792 — nothing about a line
+count tells you what continuing a session will cost. Shown, not warned about;
+importing a large session is a choice somebody is entitled to make.
 
-- **The schedule is a plan to ask.** `resume.rs` wakes at the scheduled time,
-  asks `GET /usage`'s meter for that machine and provider, and only sends when
-  it answers `ok` with nothing at 100%. Anything else — still spent, logged
-  out, unreachable — is a longer wait, and a still-spent window reschedules to
-  the reset time the *meter* now gives.
-- **Test it with echo, never with a real account.** `/limit [minutes]` reports
-  the same `limitReached` event a real driver does, and `/usage 100 5` sets
-  what the meter answers. They are deliberately separate: the two disagreeing
-  is the case the design exists for. `/usage 20` is the limit lifting.
-- The wait is on the session in `config.ron` (`resume`), so it survives a
-  backend restart. A day after the limit was hit it gives up and says so in
-  the transcript.
+**Never import a Claude Code session that is open in a terminal.** The app
+refuses it — see docs/PLAN.md for the incident that made that a refusal rather
+than a warning.
+
+**One Claude Code session id can name two files, and the listing offers it
+once.** Resuming from a different working directory makes the CLI write a
+second transcript with the same id under that directory's project folder — an
+ordinary state of a machine, not corruption. Everything downstream addresses
+a session by id, and the phone keyed its list on it, so two rows sharing one
+**closed the app** on a Compose duplicate-key throw. `parse_listing` keeps
+the copy with the most lines, because the other is usually a few-hundred-byte
+stub and is often the *newer* of the two, so recency is the wrong key.
+Deleting removes every copy rather than the first, or the row came back after
+a delete that reported success. The phone's half is `uniqueItems`, which
+every list keyed on a server-chosen id goes through: a repeat there must
+never be able to close the app, whatever produced it.
+
+**Deleting a session offers to take the machine's own transcript with it** —
+`DELETE /sessions/{id}?deleteForeign=true`, behind a switch in the
+confirmation, and only where the driver keeps a record of its own
+(`keepsOwnTranscript`, which today means Claude Code). Off by default,
+because leaving that copy is what makes an ordinary delete recoverable — and
+the dialog's paragraph is rewritten when it is on rather than appended to,
+since the sentence promising the conversation "should still be there to
+import again" is exactly the one the switch makes false. The server deletes
+the machine's copy *first*, so a machine it cannot reach leaves the session
+where it was instead of half-deleted.
 
 ## Shared appearance
 
@@ -239,17 +425,6 @@ PLAN.md's "Auto-resume" is the design; day to day:
   swallowed the drag along with the tap, so a list could not be scrolled
   while anything in it was busy.
 
-- **A rate-limit bar belongs to a session's provider, not to its machine.**
-  One machine offers echo, the Claude CLI and a local model at once and only
-  the CLI spends anything, so a session says which meter reports on it
-  (`usageProvider`, from `DriverKind::usage_provider`, which
-  `usage::providers_for` reads too so the two lists cannot disagree) and the
-  phone matches a snapshot on machine *and* provider. Nothing meters a llama
-  or echo session, and the phone draws **nothing** for one — not a zero, and
-  not "unknown". Nothing while the first fetch is out either: "checking"
-  under a session that turns out to meter nothing is a row the screen then
-  has to withdraw.
-
 ## Things that have bitten
 
 Project-specific only — a lesson that would bite any project on this machine
@@ -355,3 +530,37 @@ belongs in `~/.claude/TOOLCHAIN.md` or `~/.claude/MACHINE.md` instead.
   hop to `Dispatchers.Default`. The shape to watch for is a `withContext`
   that wraps the *fetch* and leaves the work done with the result outside it.
 
+## Measurements worth not re-taking
+
+- **What the transcript screen costs to scroll.** Taken 2026-08-30 on the GPU
+  emulator against a real imported transcript with the server at
+  `--delay 120`. Settled and flinging fast, both into fresh history and back
+  through rows already drawn: **5.2–5.9% janky frames, 99th percentile
+  29–32ms, 0–2 slow UI-thread frames.** The stock Settings app on the same
+  device is 3.3% and 38ms, so this is at the platform floor. The number that
+  is *not* at the floor is the first few seconds after opening a session,
+  where every row on the way is being composed for the first time; that is
+  inherent to a lazy list and it is why a measurement taken before the screen
+  settles reads three times worse. **Settle first, then reset `gfxinfo`.**
+- **The reset path is not reachable by reopening a session.** Measured
+  2026-09-04 against a session streaming at 20 events a second: reopening one
+  with an anchor 1,800 events back connects **87–119 events behind**, well
+  under `CATCH_UP_LIMIT`'s 200, because the restore is two requests — the
+  opening page, then one span covering the whole distance. To exercise the
+  reset at all you have to lower `CATCH_UP_LIMIT` in a throwaway build; at 5
+  the app takes the reset on a live connection, clears, refills and carries
+  on without reconnecting.
+- **The session screen's stream survives backgrounding here** — 20 seconds at
+  the launcher while 415 events were produced brought no reconnect at all,
+  which is not what the comment above that loop expects, and is most likely
+  this emulator being headless rather than the phone's behaviour.
+- **Reopening a cached session costs one request for one event** (the probe),
+  and scrolling the whole conversation back costs nothing more; a cold open
+  of the same 500-event session is two pages, 100 events. Measured
+  2026-09-04 on the emulator against the sandbox.
+- **Reading is cheap and editing is not.** The viewer handles a 1 MiB,
+  28,000-line file because it draws one row per line; the editor is one
+  `BasicTextField`, which costs two seconds a frame at 128 kB and stops the
+  app at 1 MiB, so `EDIT_LIMIT` caps it at 32 kB with the reason said on
+  screen. If you make the editor faster, that number is what to move.
+  docs/EXPLORER.md's "What the measurements said" has the rest.

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/androidApp/build.gradle.kts

@@ -102,6 +102,16 @@ android {
         targetSdk = 37
         versionCode = 1
         versionName = "1.0"
+        // Read by MainActivity to decide, at startup, whether this is the P0 benchmark build
+        // (docs/RUST.md's P0 box) rather than the app somebody enrolled. False everywhere except
+        // the `bench` build type below, which overrides it.
+        buildConfigField("boolean", "FIXTURE_MODE", "false")
+    }
+    buildFeatures {
+        // Only for FIXTURE_MODE above; nothing else here reaches for generated BuildConfig fields.
+        buildConfig = true
+        // Only for the bench build type's resValue("string", "app_name", ...) below.
+        resValues = true
     }
     packaging {
         resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" }
@@ -131,6 +141,35 @@ android {
             isMinifyEnabled = false
             if (keystore != null) signingConfig = signingConfigs.getByName("release")
         }
+        // P0's benchmark build (docs/RUST.md, docs/DECISIONS.md's 2026-09-05 entry): release
+        // optimisations so a frame time measured here means what release means everywhere else in
+        // this project, its own application id so it installs beside a real enrollment rather than
+        // replacing it, and FIXTURE_MODE so MainActivity opens straight onto the fixture session
+        // instead of asking to be enrolled. Signed with the same key as release -- it never talks
+        // to a real backend, so there is no CA of its own to mismatch, and a second keystore would
+        // be one more secret to keep off this machine's shared mount for no benefit.
+        create("bench") {
+            initWith(getByName("release"))
+            // :link (wg-app-link) has no "bench" build type of its own -- it is a library shared
+            // with dev-updater and has no reason to know this project invented one -- so this says
+            // which of its build types to link against instead.
+            matchingFallbacks += listOf("release")
+            applicationIdSuffix = ".bench"
+            // "AI Sessions bench" everywhere the OS shows the app's name (launcher, recents,
+            // Settings): this resValue overrides res/values/strings.xml's app_name for this
+            // build type alone, and AndroidManifest.xml's android:label reads @string/app_name
+            // rather than a literal so a build type can override it without touching the
+            // manifest.
+            resValue("string", "app_name", "AI Sessions bench")
+            buildConfigField("boolean", "FIXTURE_MODE", "true")
+            if (keystore != null) signingConfig = signingConfigs.getByName("release")
+        }
+    }
+    sourceSets {
+        // The fixture both bench builds (this one and iris's) open with; see
+        // app/bench-fixture/README.md. Read directly from its own directory rather than copied
+        // into androidApp/src -- one file to keep in sync with the generator, not two.
+        getByName("bench").assets.directories.add("../bench-fixture/assets")
     }
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_21

app/androidApp/src/main/AndroidManifest.xml

@@ -25,7 +25,7 @@
          the fix is a judgement about how this app should look. Drop this
          suppression when a real icon lands. -->
     <application
-        android:label="AI Sessions"
+        android:label="@string/app_name"
         android:allowBackup="true"
         android:theme="@android:style/Theme.Material.Light.NoActionBar"
         tools:ignore="MissingApplicationIcon">

app/androidApp/src/main/kotlin/com/example/aiapp/BenchFixture.kt

@@ -0,0 +1,108 @@
+package com.example.aiapp
+
+import android.content.Context
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * P0's benchmark gate (see docs/RUST.md and docs/DECISIONS.md's 2026-09-05 entry): an in-process
+ * fake of the backend, so the `bench` build type can drive a real session screen -- the real
+ * [TranscriptSource], the real fold, the real paging -- with no server and no network permission.
+ *
+ * Only ever installed when [BuildConfig.FIXTURE_MODE] is true (see [MainActivity]); everything else
+ * in this build compiles it in but never calls it, since Kotlin has no per-build-type source set
+ * that both [MainActivity] (which every variant compiles) and this can share without one.
+ *
+ * The design: [requestFromServer] and [Sse] talk to `https://$FIXTURE_HOST:$FIXTURE_PORT` through
+ * ordinary `java.net.URL`, exactly as they would talk to a real server. A
+ * [java.net.URLStreamHandlerFactory] registered once for the whole process intercepts every
+ * `https://` connection to that host and answers from this object's in-memory event log instead of
+ * opening a socket -- see BenchNetwork.kt. Everything above that (TranscriptSource, SessionScreen,
+ * the fold, uniqueItems) never learns the difference.
+ */
+object BenchFixture {
+    const val FIXTURE_HOST = "bench.fixture.invalid"
+    const val FIXTURE_PORT = 1
+
+    /** How many of the fixture's events are the opening backlog; see bench-fixture/README.md. */
+    private const val BACKLOG_COUNT = 3200
+
+    val settings = ServerSettings(FIXTURE_HOST, FIXTURE_PORT, "bench")
+
+    /** The session id every bench run opens; nothing else in this build ever mints one. */
+    const val SESSION_ID = "bench-fixture-session"
+
+    /**
+     * The whole transcript, seq order, growing as [pushLive] is called during the streaming phase.
+     * Read by both the REST page handler and the SSE handler, so a page requested mid- stream and a
+     * live frame agree on what has "already happened" -- the same thing a real server's own
+     * transcript file guarantees.
+     */
+    private val log = CopyOnWriteArrayList<Pair<String, SeqEvent>>()
+
+    /** The events not yet appended to [log] -- the streaming phase's own source. */
+    private var streamTail: List<Pair<String, SeqEvent>> = emptyList()
+
+    private val images = mutableMapOf<String, ByteArray>()
+
+    @Volatile private var loaded = false
+
+    /**
+     * Parses the bundled fixture once. Safe to call more than once; only the first does anything.
+     */
+    @Synchronized
+    fun ensureLoaded(context: Context) {
+        if (loaded) return
+        val lines =
+            context.assets.open("transcript.jsonl").bufferedReader().readLines().filter {
+                it.isNotBlank()
+            }
+        val parsed = lines.map { it to parseSeqEvent(it) }
+        log.addAll(parsed.take(BACKLOG_COUNT))
+        streamTail = parsed.drop(BACKLOG_COUNT)
+        for (name in listOf("bench1.png", "bench2.png")) {
+            images[name] = context.assets.open(name).readBytes()
+        }
+        loaded = true
+    }
+
+    /** The events the streaming phase has left to send. */
+    fun remainingStreamEvents(): Int = streamTail.size
+
+    /** Sends the next fixture event onto the live log, as a real SSE frame would arrive. */
+    fun pushNextLiveEvent(): Boolean {
+        val next = streamTail.firstOrNull() ?: return false
+        streamTail = streamTail.drop(1)
+        log.add(next)
+        return true
+    }
+
+    /** Undoes [pushNextLiveEvent] and reloads the opening backlog, for running the bench twice. */
+    @Synchronized
+    fun resetToBacklog(context: Context) {
+        loaded = false
+        log.clear()
+        ensureLoaded(context)
+    }
+
+    fun fileBytes(name: String): ByteArray? = images[name]
+
+    /**
+     * Raw JSON lines with seq > [after], in order -- what an `/events?after=` connection replays.
+     */
+    fun linesAfter(after: Long): List<String> =
+        log.filter { it.second.seq > after }.map { it.first }
+
+    /**
+     * One REST page: [fetchTranscript]'s `before`/`limit`/`after`, against the growing log. Ignores
+     * `coalesce` -- the fixture's own deltas are already split the way a real reply streams, and
+     * what the benchmark exercises is the fold and the paging, not the server's row-joining, which
+     * client-core's own port tracks separately (CLIENT_CORE.md).
+     */
+    fun page(before: Long?, limit: Int, after: Long?): List<String> {
+        val upper = before ?: (log.lastOrNull()?.second?.seq?.plus(1) ?: 1L)
+        val candidates = log.filter {
+            it.second.seq < upper && (after == null || it.second.seq > after)
+        }
+        return candidates.takeLast(limit).map { it.first }
+    }
+}

app/androidApp/src/main/kotlin/com/example/aiapp/BenchNetwork.kt

@@ -0,0 +1,181 @@
+package com.example.aiapp
+
+import java.io.ByteArrayInputStream
+import java.io.IOException
+import java.io.InputStream
+import java.io.PipedInputStream
+import java.io.PipedOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.net.URLStreamHandler
+import java.net.URLStreamHandlerFactory
+import java.security.Principal
+import java.security.cert.Certificate
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLPeerUnverifiedException
+import org.json.JSONArray
+
+/**
+ * Installs the process-wide interception [BenchFixture] needs. Idempotent and safe to call more
+ * than once; the JDK only allows [URL.setURLStreamHandlerFactory] to be called successfully once
+ * per process, and a second real call throws -- so this guards it rather than relying on every
+ * caller to remember.
+ *
+ * Scoped to [BenchFixture.FIXTURE_HOST]: any other `https://` URL falls through to the platform's
+ * ordinary handler, so this only ever changes behaviour for the one host the bench build invents.
+ */
+@Synchronized
+fun installFixtureNetworkOnce() {
+    if (installed) return
+    installed = true
+    URL.setURLStreamHandlerFactory(
+        URLStreamHandlerFactory { protocol ->
+            if (protocol != "https") null
+            else
+                object : URLStreamHandler() {
+                    override fun openConnection(url: URL): HttpURLConnection =
+                        if (url.host == BenchFixture.FIXTURE_HOST) FixtureConnection(url)
+                        else
+                        // The bench build makes no other https call -- this factory is
+                        // installed only in FIXTURE_MODE (MainActivity) -- so there is
+                        // deliberately no delegate to a platform handler here: once a
+                        // URLStreamHandlerFactory is installed there is no supported way to
+                        // ask the JDK for its own default handler back, and re-entering this
+                        // same factory for the fallback would recurse forever rather than
+                        // reach one.
+                        throw java.io.IOException(
+                                "bench build's fixture network has no route to https host " +
+                                    "${url.host} -- only ${BenchFixture.FIXTURE_HOST} is served"
+                            )
+                }
+        }
+    )
+}
+
+private var installed = false
+
+/**
+ * Answers one request against [BenchFixture] instead of opening a socket. Implements just enough of
+ * [HttpsURLConnection] for [requestFromServer] and [Sse] to work unmodified: both only call
+ * `connect`/`disconnect`, set a handful of request properties they never need answered, and read
+ * `responseCode` and `inputStream`.
+ */
+private class FixtureConnection(url: URL) : HttpsURLConnection(url) {
+    private var input: InputStream? = null
+    private var writer: Thread? = null
+
+    override fun connect() {
+        if (input != null) return
+        input = route(url.path, url.query)
+    }
+
+    override fun disconnect() {
+        writer?.interrupt()
+        try {
+            input?.close()
+        } catch (_: IOException) {}
+    }
+
+    override fun usingProxy() = false
+
+    override fun getResponseCode(): Int {
+        connect()
+        return 200
+    }
+
+    override fun getInputStream(): InputStream {
+        connect()
+        return input!!
+    }
+
+    override fun getErrorStream(): InputStream? = null
+
+    // Nothing here reads any of these; implemented only because HttpsURLConnection declares them
+    // abstract. A fixture never negotiates real TLS, so each says exactly that rather than
+    // fabricating a plausible-looking certificate.
+    override fun getCipherSuite() = "none (bench fixture, no TLS)"
+
+    override fun getLocalCertificates(): Array<Certificate>? = null
+
+    override fun getServerCertificates(): Array<Certificate> =
+        throw SSLPeerUnverifiedException("bench fixture connection presents no certificate")
+
+    override fun getPeerPrincipal(): Principal =
+        throw SSLPeerUnverifiedException("bench fixture connection presents no certificate")
+
+    override fun getLocalPrincipal(): Principal? = null
+
+    /**
+     * [path] is `/sessions/{id}/...`; everything else this build's fixture is asked for is a bug.
+     */
+    private fun route(path: String, query: String?): InputStream {
+        val params =
+            (query ?: "")
+                .split("&")
+                .filter { it.contains('=') }
+                .associate {
+                    val (k, v) = it.split("=", limit = 2)
+                    k to java.net.URLDecoder.decode(v, "UTF-8")
+                }
+        return when {
+            path.endsWith("/transcript") -> {
+                val lines =
+                    BenchFixture.page(
+                        before = params["before"]?.toLongOrNull(),
+                        limit = params["limit"]?.toIntOrNull() ?: 80,
+                        after = params["after"]?.toLongOrNull(),
+                    )
+                val body = JSONArray(lines.map { org.json.JSONObject(it) })
+                ByteArrayInputStream(body.toString().toByteArray())
+            }
+            path.endsWith("/events") -> openEventsStream(params["after"]?.toLongOrNull() ?: 0L)
+            path.contains("/files/") -> {
+                val name = path.substringAfterLast("/files/")
+                val bytes =
+                    BenchFixture.fileBytes(name)
+                        ?: throw IOException("bench fixture has no file named $name")
+                ByteArrayInputStream(bytes)
+            }
+            else -> throw IOException("bench fixture has no route for $path")
+        }
+    }
+
+    /**
+     * A live SSE body: [BenchFixture.linesAfter] replayed immediately, then polled every 50ms for
+     * anything [BenchFixture.pushNextLiveEvent] has added since -- the same shape a real backend's
+     * backlog-then-follow gives [Sse], just polled instead of woken, which is a fixture's business
+     * rather than something worth a condition variable for.
+     */
+    private fun openEventsStream(after: Long): InputStream {
+        val pipeIn = PipedInputStream(1 shl 16)
+        val pipeOut = PipedOutputStream(pipeIn)
+        var sent = after
+        val thread = Thread {
+            try {
+                while (!Thread.currentThread().isInterrupted) {
+                    val fresh = BenchFixture.linesAfter(sent)
+                    for (line in fresh) {
+                        pipeOut.write("data: $line\n\n".toByteArray())
+                        pipeOut.flush()
+                        sent = org.json.JSONObject(line).getLong("seq")
+                    }
+                    Thread.sleep(50)
+                }
+            } catch (_: InterruptedException) {
+                // disconnect() -- the ordinary way this ends.
+            } catch (_: IOException) {
+                // The reader side (Sse) closed its end.
+            } finally {
+                try {
+                    pipeOut.close()
+                } catch (_: IOException) {}
+            }
+        }
+            .also {
+                it.isDaemon = true
+                it.start()
+            }
+        writer = thread
+        return pipeIn
+    }
+}

app/androidApp/src/main/kotlin/com/example/aiapp/BenchRun.kt

@@ -0,0 +1,325 @@
+package com.example.aiapp
+
+import android.content.Context
+import android.os.BatteryManager
+import android.os.Process
+import android.view.View
+import androidx.compose.foundation.gestures.FlingBehavior
+import androidx.compose.foundation.lazy.LazyListState
+import androidx.compose.ui.focus.FocusRequester
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import java.io.File
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+
+/**
+ * P0's scripted benchmark, run in-process instead of by a shell script: the phone has no usable
+ * system tracing (this-machine-android's skill) and no agent can drive it, so the same scroll loop
+ * and streaming phase `transcript-bench.sh`/`stream-bench.sh` drive over `ui-trace` are reproduced
+ * here against [LazyListState] and [BenchFixture] directly. Only reachable from the `bench` build
+ * (see [SessionSettingsDialog]'s `onRunBenchmark`), but compiled into every build for the reason
+ * [BenchFixture]'s doc comment gives.
+ *
+ * **v2 (2026-09-06)**, asked for by Iris because the v1 fling was too gentle to stress-test the
+ * scroll path and said nothing about typing or the keyboard. Four phases now, each a slice of the
+ * same [FrameStats] recording ([FrameStats.markPhase]/[FrameStats.phaseLines] -- one recorder, not
+ * two): **fling** (real `FlingBehavior`, not `animateScrollBy`), **stream** (unchanged from v1),
+ * **type** (600 fixed characters into the real composer `TextFieldValue`, then deleted), and
+ * **keyboard** (five show/hide cycles). The exact constants below are also written into
+ * `docs/RUST.md`'s P0 box, "Benchmark v2 (2026-09-06)", so the iris half implements the identical
+ * spec -- changing a number here without updating that box makes the two apps measure different
+ * things while looking like the same benchmark.
+ */
+object BenchRun {
+    /** transcript-bench.sh's default: 6 cycles of 4 swipes each, kept as the pre-v2 comparison. */
+    private const val CYCLES = 6
+    private const val SWIPE_PX = 900f
+    private const val SWIPE_MS = 200
+    private const val SWIPE_PAUSE_MS = 500L
+
+    /**
+     * Fling phase (v2): a real fling through the list's own [FlingBehavior], not `animateScrollBy`
+     * -- Iris's ask was that it "travel way faster" than the old tween-based swipe, and a tween can
+     * never exceed the distance it is told to cover in the time it is given, while a real fling
+     * decays from an initial velocity the way a finger flick does. 12,000 px/s is roughly a hard,
+     * fast flick on a ~420dp/in device (about 30 dp/ms-equivalent initial speed); chosen well above
+     * the ~4,500 px/s a moderate `animateScrollBy` swipe implies, so this phase exercises the fast
+     * end of what the platform's fling decay produces rather than the gentle one v1 measured.
+     */
+    private const val FLING_VELOCITY_PX_S = 12_000f
+
+    private const val FLING_COUNT = 8
+    private const val FLING_SETTLE_CAP_MS = 3_000L
+    private const val FLING_PAUSE_MS = 300L
+
+    /** stream-bench.sh's shape: a real reply arrives as many small deltas, not one big write. */
+    private const val STREAM_EVENTS_PER_SEC = 20
+    private const val STREAM_SECONDS = 20
+
+    /**
+     * Type phase (v2): sentences built from long, multisyllabic words so the composer actually
+     * wraps across lines rather than fitting one, and long enough (600 chars) that the composer's
+     * own height grows over several frames, pushing the transcript above it upward the same way a
+     * real long message does. Exactly this string is also in `docs/RUST.md`'s P0 box so the iris
+     * half types the identical content.
+     */
+    const val TYPE_TEXT =
+        "Benchmarking this transcript screen requires unusually long, multisyllabic words so " +
+            "wrapping and reflow are properly exercised: internationalization, " +
+            "counterproductiveness, disproportionately, incomprehensibility, " +
+            "deinstitutionalization, uncharacteristically, overenthusiastically, " +
+            "misunderstanding, straightforwardness, telecommunications, and interdisciplinary " +
+            "collaboration all push a narrow composer field to wrap across several lines while " +
+            "the transcript above is pushed upward by the growing keyboard-adjacent box, which " +
+            "is exactly what a real reader typing a long message sees happening now!!!"
+
+    private const val TYPE_CHAR_DELAY_MS = 50L
+
+    /**
+     * Keyboard phase (v2): five show/hide cycles, a second apart, is enough to see whether the
+     * transition is ever actually observed rather than being a one-off fluke either way.
+     */
+    private const val KEYBOARD_CYCLES = 5
+    private const val KEYBOARD_SHOW_WAIT_MS = 1_000L
+    private const val KEYBOARD_HIDE_WAIT_MS = 1_000L
+
+    /**
+     * Scrolls, flings, streams, types and toggles the keyboard, then returns the extra report lines
+     * P0 asked for (per-phase travel/typing/keyboard counts, plus CPU time, peak RSS, battery
+     * current) -- [FrameStats] and [DebugStats] are reset first, exactly as `copyRenderReport`
+     * resets them, so the two accountings cover the same stretch of work.
+     */
+    suspend fun run(
+        context: Context,
+        scope: CoroutineScope,
+        listState: LazyListState,
+        flingBehavior: FlingBehavior,
+        composerFocus: FocusRequester,
+        setComposerText: (String) -> Unit,
+        view: View,
+    ): List<String> {
+        FrameStats.reset()
+        DebugStats.reset()
+        val cpuStartMs = Process.getElapsedCpuTime()
+
+        val battery = BatterySampler(context)
+        // Launched in the caller's scope rather than a fresh coroutineScope{} here, which would
+        // suspend this function until the sampler job ended -- and it only ends when told to.
+        val samplerJob = scope.launch {
+            while (isActive) {
+                battery.sample()
+                delay(1000)
+            }
+        }
+
+        val travel = runFlingPhase(listState, flingBehavior)
+        val sent = runStreamPhase()
+        runTypePhase(listState, composerFocus, setComposerText, view)
+        val keyboard = runKeyboardPhase(context, view)
+
+        samplerJob.cancel()
+        val cpuMs = Process.getElapsedCpuTime() - cpuStartMs
+        val rssLine = peakRssLine()
+        val batteryLine = battery.finish()
+
+        return listOf(
+            "  fling: $FLING_COUNT flings out + $FLING_COUNT back at" +
+                " ${FLING_VELOCITY_PX_S.toInt()}px/s, travel $travel",
+            "  scroll: $CYCLES cycles (${CYCLES * 4} swipes, legacy tween), " +
+                "streamed $sent/${STREAM_EVENTS_PER_SEC * STREAM_SECONDS} fixture events",
+            "  type: ${TYPE_TEXT.length} characters inserted then deleted, one per" +
+                " ${TYPE_CHAR_DELAY_MS}ms",
+            keyboard,
+            "  process CPU time over this run: ${cpuMs}ms",
+            rssLine,
+            batteryLine,
+        )
+    }
+
+    /**
+     * Phase 1: starting pinned at the newest end, [FLING_COUNT] flings away from it (toward older
+     * messages) through the list's real fling path, then [FLING_COUNT] back. Positive velocity here
+     * matches this list's existing scroll-offset convention (`TranscriptList`'s `reverseLayout`
+     * pins index 0 -- the newest item -- at the bottom; a positive scroll offset moves the viewport
+     * toward higher indices, i.e. away from the newest end and toward older content), the same sign
+     * the pre-v2 swipe loop below already used for its first two swipes.
+     */
+    private suspend fun runFlingPhase(
+        listState: LazyListState,
+        flingBehavior: FlingBehavior,
+    ): String {
+        FrameStats.markPhase("fling")
+        listState.scrollToItem(0)
+        val start = position(listState)
+        repeat(FLING_COUNT) {
+            listState.scroll { with(flingBehavior) { performFling(FLING_VELOCITY_PX_S) } }
+            waitForSettle(listState)
+            delay(FLING_PAUSE_MS)
+        }
+        val outward = position(listState)
+        repeat(FLING_COUNT) {
+            listState.scroll { with(flingBehavior) { performFling(-FLING_VELOCITY_PX_S) } }
+            waitForSettle(listState)
+            delay(FLING_PAUSE_MS)
+        }
+        val back = position(listState)
+        return "start=$start outward=$outward end=$back"
+    }
+
+    private fun position(listState: LazyListState) =
+        "idx=${listState.firstVisibleItemIndex}/off=${listState.firstVisibleItemScrollOffset}px"
+
+    /** Belt-and-suspenders on top of `performFling` already suspending until its own decay ends. */
+    private suspend fun waitForSettle(listState: LazyListState) {
+        val startedAt = System.currentTimeMillis()
+        while (
+            listState.isScrollInProgress &&
+                System.currentTimeMillis() - startedAt < FLING_SETTLE_CAP_MS
+        ) {
+            delay(16)
+        }
+    }
+
+    /**
+     * Phase 2 (unchanged from v1): pinned to the newest end before streaming starts, the way
+     * stream-bench.sh's "Jump to latest" tap is -- a reply streamed into a list parked further back
+     * arrives off-screen and the report would show nothing happened.
+     */
+    private suspend fun runStreamPhase(): Int {
+        FrameStats.markPhase("stream")
+        var sent = 0
+        val total = STREAM_EVENTS_PER_SEC * STREAM_SECONDS
+        while (sent < total && BenchFixture.remainingStreamEvents() > 0) {
+            BenchFixture.pushNextLiveEvent()
+            sent++
+            delay(1000L / STREAM_EVENTS_PER_SEC)
+        }
+        // Lets the last few deltas land and draw before the next phase starts.
+        delay(300)
+        return sent
+    }
+
+    /**
+     * Phase 3: focuses the real composer, shows the keyboard if the platform allows it, then types
+     * [TYPE_TEXT] one character at a time through the same `TextFieldValue` state a real keystroke
+     * updates, and deletes it the same way -- this is what exercises wrapping and the transcript
+     * being pushed upward, not a single big write.
+     */
+    private suspend fun runTypePhase(
+        listState: LazyListState,
+        composerFocus: FocusRequester,
+        setComposerText: (String) -> Unit,
+        view: View,
+    ) {
+        FrameStats.markPhase("type")
+        listState.scrollToItem(0)
+        composerFocus.requestFocus()
+        showIme(view.context, view)
+        // Lets focus and the keyboard's opening animation land before typing starts, so the frames
+        // this phase records are the wrap/reflow it is measuring, not the keyboard opening.
+        delay(300)
+        var typed = ""
+        for (ch in TYPE_TEXT) {
+            typed += ch
+            setComposerText(typed)
+            delay(TYPE_CHAR_DELAY_MS)
+        }
+        delay(200)
+        while (typed.isNotEmpty()) {
+            typed = typed.dropLast(1)
+            setComposerText(typed)
+            delay(TYPE_CHAR_DELAY_MS)
+        }
+    }
+
+    /**
+     * Phase 4: [KEYBOARD_CYCLES] show/hide cycles through the same [WindowInsetsControllerCompat]
+     * path a real IME toggle goes through, reporting how many of each were actually confirmed by
+     * [android.view.WindowInsets.isVisible] rather than assumed from having asked -- UI_RULES:
+     * never present an inferred value as a measured one. If the platform never shows it even once,
+     * this says so in words rather than reporting a phase with no keyboard in it.
+     */
+    private suspend fun runKeyboardPhase(context: Context, view: View): String {
+        FrameStats.markPhase("keyboard")
+        var shown = 0
+        var hidden = 0
+        repeat(KEYBOARD_CYCLES) {
+            showIme(context, view)
+            delay(KEYBOARD_SHOW_WAIT_MS)
+            if (imeVisible(view)) shown++
+            hideIme(context, view)
+            delay(KEYBOARD_HIDE_WAIT_MS)
+            if (!imeVisible(view)) hidden++
+        }
+        return if (shown == 0) {
+            "  keyboard: could not be shown ($KEYBOARD_CYCLES attempts, 0 confirmed visible)"
+        } else {
+            "  keyboard: shown $shown/$KEYBOARD_CYCLES, hidden $hidden/$KEYBOARD_CYCLES" +
+                " (confirmed via isImeVisible)"
+        }
+    }
+
+    private fun controller(context: Context, view: View): WindowInsetsControllerCompat? {
+        val window = context.activity()?.window ?: return null
+        return WindowInsetsControllerCompat(window, view)
+    }
+
+    private fun showIme(context: Context, view: View) {
+        controller(context, view)?.show(WindowInsetsCompat.Type.ime())
+    }
+
+    private fun hideIme(context: Context, view: View) {
+        controller(context, view)?.hide(WindowInsetsCompat.Type.ime())
+    }
+
+    private fun imeVisible(view: View): Boolean =
+        ViewCompat.getRootWindowInsets(view)?.isVisible(WindowInsetsCompat.Type.ime()) ?: false
+
+    /** VmHWM from /proc/self/status: the process's high-water mark, in kB, since it started. */
+    private fun peakRssLine(): String {
+        val kb =
+            try {
+                File("/proc/self/status")
+                    .readLines()
+                    .firstOrNull { it.startsWith("VmHWM:") }
+                    ?.trim()
+                    ?.removePrefix("VmHWM:")
+                    ?.trim()
+                    ?.removeSuffix("kB")
+                    ?.trim()
+                    ?.toLongOrNull()
+            } catch (_: Exception) {
+                null
+            }
+        return "  peak RSS: " +
+            (kb?.let { "${it}kB" } ?: "unavailable (/proc/self/status unreadable)")
+    }
+}
+
+/**
+ * Samples [BatteryManager.BATTERY_PROPERTY_CURRENT_NOW] (microamps) once a second for the length of
+ * a run. The property returns `Int.MIN_VALUE` on hardware that does not support it -- most
+ * emulators -- and that is reported as "unavailable" rather than folded into an average with the
+ * real samples, which would silently understate every number after it. See UI_RULES: never present
+ * an inferred value as a measured one.
+ */
+private class BatterySampler(context: Context) {
+    private val manager = context.getSystemService(BatteryManager::class.java)
+    private val samples = mutableListOf<Int>()
+
+    fun sample() {
+        val value = manager?.getIntProperty(BatteryManager.BATTERY_PROPERTY_CURRENT_NOW)
+        if (value != null && value != Int.MIN_VALUE) samples.add(value)
+    }
+
+    fun finish(): String {
+        if (samples.isEmpty()) return "  battery current: unavailable on this device"
+        val meanUa = samples.sum() / samples.size
+        return "  battery current: mean ${meanUa}µA over ${samples.size} samples" +
+            " (min ${samples.min()}, max ${samples.max()})"
+    }
+}

app/androidApp/src/main/kotlin/com/example/aiapp/DebugStats.kt

@@ -127,6 +127,20 @@ fun debugReport(
     frames: List<String>,
     accounting: List<String>,
     crash: String?,
+    /**
+     * P0's benchmark-only measurements (process CPU time, peak RSS, battery current) -- empty on
+     * every path but [BenchRun.runP0Benchmark], which is the only caller that has them. A section
+     * heading only appears when there is something to put under it, so an ordinary copy from the
+     * render-report button reads exactly as it did before this existed.
+     */
+    extra: List<String> = emptyList(),
+    /**
+     * Bench v2's per-phase frame accounting ([FrameStats.phaseLines]) --
+     * fling/stream/type/keyboard, each a slice of the same frames the whole-run sections below
+     * still cover in full. Empty on every path but the scripted bench run, same reasoning as
+     * [extra].
+     */
+    phaseFrames: List<String> = emptyList(),
 ): String = buildString {
     appendLine("ai-app render report")
     appendLine(device)
@@ -141,6 +155,11 @@ fun debugReport(
     appendLine("transcript:")
     transcript.forEach { appendLine(it) }
     appendLine()
+    if (phaseFrames.isNotEmpty()) {
+        appendLine("per phase:")
+        phaseFrames.forEach { appendLine(it) }
+        appendLine()
+    }
     appendLine("frames:")
     frames.forEach { appendLine(it) }
     appendLine()
@@ -152,6 +171,11 @@ fun debugReport(
     appendLine("work since this was last copied:")
     val work = DebugStats.lines()
     if (work.isEmpty()) appendLine("  nothing recorded") else work.forEach { appendLine(it) }
+    if (extra.isNotEmpty()) {
+        appendLine()
+        appendLine("bench:")
+        extra.forEach { appendLine(it) }
+    }
 }
 
 /** Puts [text] on the clipboard under [label], which is what the system offers as its name. */

app/androidApp/src/main/kotlin/com/example/aiapp/FrameStats.kt

@@ -42,6 +42,21 @@ object FrameStats {
     private val gpu = ArrayList<Long>()
     private var since = System.currentTimeMillis()
 
+    /**
+     * Where a named phase of a scripted run (bench v2's fling/stream/type/keyboard) started, as an
+     * index into [total] and a wall-clock time -- not a second recorder, just a mark on this one,
+     * so a phase's frames are the same [FrameMetrics] the whole-run report already has, sliced.
+     */
+    private data class PhaseMark(val name: String, val startIndex: Int, val startMs: Long)
+
+    private val phaseMarks = ArrayList<PhaseMark>()
+
+    /** Call at the start of each named phase of a scripted run; see [BenchRun]. */
+    @Synchronized
+    fun markPhase(name: String) {
+        phaseMarks += PhaseMark(name, total.size, System.currentTimeMillis())
+    }
+
     @Synchronized
     fun add(metrics: FrameMetrics) {
         // The first frame after a window opens includes inflating it and is nobody's scroll.
@@ -69,6 +84,7 @@ object FrameStats {
         listOf(total, waited, input, animation, layout, draw, sync, issue, swap, gpu).forEach {
             it.clear()
         }
+        phaseMarks.clear()
         since = System.currentTimeMillis()
     }
 
@@ -95,6 +111,38 @@ object FrameStats {
         ) + if (gpu.isEmpty()) emptyList() else listOf(phase("gpu   ", gpu))
     }
 
+    /**
+     * One block per [markPhase] call: how many frames landed between that mark and the next (or the
+     * end of the run, for the last one), how many were late, the total/p50/p90/p99, the worst
+     * single frame, and how long the phase actually ran. Marks with no frames between them (a phase
+     * that finished before a frame was drawn) still get a line rather than being silently dropped
+     * -- UI_RULES' "say what you don't know" applies to a phase as much as to a single number.
+     */
+    @Synchronized
+    fun phaseLines(refreshHz: Float): List<String> {
+        if (phaseMarks.isEmpty()) return emptyList()
+        val budget = if (refreshHz > 0) 1000.0 / refreshHz else 16.7
+        val lines = ArrayList<String>()
+        phaseMarks.forEachIndexed { i, mark ->
+            val endIndex = if (i + 1 < phaseMarks.size) phaseMarks[i + 1].startIndex else total.size
+            val endMs =
+                if (i + 1 < phaseMarks.size) phaseMarks[i + 1].startMs
+                else System.currentTimeMillis()
+            val samples = total.subList(mark.startIndex, endIndex)
+            val seconds = (endMs - mark.startMs) / 1000.0
+            lines += "  ${mark.name}: ${samples.size} frames over ${"%.1f".format(seconds)}s"
+            if (samples.isEmpty()) {
+                lines += "    no frames recorded in this phase"
+            } else {
+                val late = samples.count { it / 1_000_000.0 > budget }
+                lines += "    late: $late (${percent(late, samples.size)})"
+                lines += "    " + phase("total ", samples)
+                lines += "    worst ${"%.1fms".format(samples.max() / 1_000_000.0)}"
+            }
+        }
+        return lines
+    }
+
     /** How long the frames recorded here spent in their draw phase, and how many there were. */
     @Synchronized fun drawPhase(): Pair<Long, Int> = draw.sum() to draw.size
 

app/androidApp/src/main/kotlin/com/example/aiapp/MainActivity.kt

@@ -66,6 +66,35 @@ class MainActivity : ComponentActivity() {
         // Transparent status bar on every version; the Surface below paints through underneath it
         // and content insets itself. Same reasoning as dev-updater's MainActivity.
         enableEdgeToEdge()
+
+        // The `bench` build's entire purpose (P0, docs/RUST.md): open straight onto the session
+        // screen against BenchFixture's in-process fake backend, with no enrollment, no network
+        // permission, and no notification prompt -- none of them mean anything with no server and
+        // no real device to notify. See BenchFixture.kt and BenchNetwork.kt for how a screen built
+        // to talk to a real backend is made to talk to this instead. Still needs the same
+        // status/navigation-bar padding the ordinary flow below applies: edge-to-edge is the
+        // platform's own default from Android 15 on this app's targetSdk, with or without the call
+        // above, so skipping the padding here put the header's own buttons under the status bar --
+        // there to look at, but not there for `ui-trace`'s tap-by-label to land on.
+        if (BuildConfig.FIXTURE_MODE) {
+            installFixtureNetworkOnce()
+            BenchFixture.ensureLoaded(this)
+            setContent {
+                MaterialTheme(colorScheme = AiAppColors) {
+                    Surface(modifier = Modifier.fillMaxSize()) {
+                        Box(Modifier.fillMaxSize().statusBarsPadding().navigationBarsPadding()) {
+                            SessionScreen(
+                                settings = BenchFixture.settings,
+                                summary = benchSessionSummary(),
+                                onBack = { finish() },
+                                onFiles = {},
+                            )
+                        }
+                    }
+                }
+            }
+            return
+        }
         // Dark status-bar icons only over a light background, decided from the scheme rather than
         // fixed. It was hardcoded to `true`, which was right against the default light surface and
         // became unreadable the moment the app wore Catppuccin Mocha.
@@ -147,6 +176,33 @@ class MainActivity : ComponentActivity() {
         }
     }
 
+    /** The one session the `bench` build ever shows -- BenchFixture's session id, nothing else. */
+    private fun benchSessionSummary() =
+        SessionSummary(
+            id = BenchFixture.SESSION_ID,
+            setup = "bench",
+            setupName = "bench",
+            provider = "bench",
+            title = "P0 benchmark",
+            model = null,
+            keepsOwnTranscript = false,
+            permissionMode = null,
+            effort = null,
+            takesEffort = false,
+            imported = false,
+            notify = false,
+            autoResume = false,
+            autoResumeMessage = "",
+            resumeAt = null,
+            cwd = null,
+            contextTokens = null,
+            maxImageEdge = null,
+            usageProvider = null,
+            status = "idle",
+            lastActivity = 0.0,
+            subagents = 0,
+        )
+
     // launchMode="singleTop": an enrollment scan, or a notification tapped while the app is open,
     // lands here rather than in a second activity instance.
     override fun onNewIntent(intent: Intent) {

app/androidApp/src/main/kotlin/com/example/aiapp/SessionScreen.kt

@@ -12,6 +12,7 @@ import androidx.activity.result.PickVisualMediaRequest
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
+import androidx.compose.foundation.gestures.ScrollableDefaults
 import androidx.compose.foundation.gestures.awaitEachGesture
 import androidx.compose.foundation.gestures.awaitFirstDown
 import androidx.compose.foundation.layout.Box
@@ -64,12 +65,15 @@ import androidx.compose.runtime.snapshots.Snapshot
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.drawWithContent
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.input.pointer.PointerEventPass
 import androidx.compose.ui.input.pointer.pointerInput
 import androidx.compose.ui.layout.onSizeChanged
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.platform.LocalView
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.semantics
 import androidx.compose.ui.text.TextRange
@@ -354,6 +358,17 @@ fun SessionScreen(
     // `rememberSaveable`, and this screen restores by its own anchor instead -- two restores would
     // fight over the first frame.
     val listState = remember(address) { LazyListState() }
+    // The list's own fling path -- what a real flick decays through -- captured here so BenchRun's
+    // fling phase can drive `LazyListState.scroll` through exactly the `FlingBehavior` this
+    // screen's
+    // `TranscriptList` already uses by not overriding it (its `LazyColumn` takes no `flingBehavior`
+    // argument, so this is the same default it gets).
+    val flingBehavior = ScrollableDefaults.flingBehavior()
+    // Where BenchRun's type phase focuses before it types, and the view it toggles the keyboard on
+    // -- both bench-only, but cheap enough (a remembered object, a CompositionLocal read) to hold
+    // unconditionally rather than behind a second code path only the bench build compiles.
+    val composerFocus = remember { FocusRequester() }
+    val view = LocalView.current
     // Whether the newest message is on screen right now. The list is reversed, so the newest end is
     // the scrolling start: nothing behind you is exactly being at the bottom. Asked of the scroll
     // state rather than of item indices, because a zero-height first item makes an index ambiguous.
@@ -1228,7 +1243,12 @@ fun SessionScreen(
     // the bench scripts keep working when this moves again. They pressed it at a hand-measured
     // coordinate until 2026-09-03, and anything that moved the header made that tap land on
     // whatever now sat there -- reporting a number that was never measured.
-    val copyRenderReport = {
+    // Shared by the ordinary "Copy" button and (bench build only) "Run benchmark": what differs
+    // between them is only whether there is a [extra] section, built by BenchRun.run beforehand --
+    // everything about assembling, copying and logging the report is exactly the same act either
+    // way, and a second copy of it beside `onRunBenchmark` below would be the two silently
+    // disagreeing about what "the report" contains the first time either one changed.
+    fun buildAndCopyReport(extra: List<String> = emptyList()) {
         val report =
             debugReport(
                 device =
@@ -1250,6 +1270,11 @@ fun SessionScreen(
                 accounting =
                     FrameStats.drawPhase().let { (nanos, count) -> drawAccounting(nanos, count) },
                 crash = lastCrash(context),
+                extra = extra,
+                // Empty outside a BenchRun.run pass -- copyRenderReport's own reset below clears
+                // the
+                // marks along with everything else, so an ordinary copy never has any to show.
+                phaseFrames = FrameStats.phaseLines(context.refreshHz()),
             )
         context.copyToClipboard("ai-app render report", report)
         // Also to the log, so a session driving the app over adb can read the same report the
@@ -1263,6 +1288,29 @@ fun SessionScreen(
         DebugStats.reset()
         Toast.makeText(context, "Copied render report", Toast.LENGTH_SHORT).show()
     }
+    val copyRenderReport = { buildAndCopyReport() }
+    // Bench build only: P0's scripted fling/stream/type/keyboard benchmark (BenchRun.kt), against
+    // the fixture session opened below instead of a real server. Null everywhere else -- see
+    // [SessionSettingsDialog]'s onRunBenchmark.
+    val runBenchmark: (() -> Unit)? =
+        if (BuildConfig.FIXTURE_MODE) {
+            {
+                settingsOpen = false
+                scope.launch {
+                    val extra =
+                        BenchRun.run(
+                            context = context,
+                            scope = scope,
+                            listState = listState,
+                            flingBehavior = flingBehavior,
+                            composerFocus = composerFocus,
+                            setComposerText = { text -> input = atEnd(text) },
+                            view = view,
+                        )
+                    buildAndCopyReport(extra)
+                }
+            }
+        } else null
     Box(Modifier.fillMaxSize()) {
         Column(Modifier.fillMaxSize()) {
             Row(
@@ -1757,7 +1805,10 @@ fun SessionScreen(
                             input = it
                             saveDraft(context, summary.id, it.text)
                         },
-                        modifier = Modifier.fillMaxWidth(),
+                        // BenchRun's type phase requests focus on this exact field
+                        // (`composerFocus`)
+                        // so it types through the real composer rather than a stand-in.
+                        modifier = Modifier.fillMaxWidth().focusRequester(composerFocus),
                         // No longer "(+image)": the images are on screen above this, and a
                         // placeholder saying so said it in words beside the thing itself.
                         placeholder = { Text("Message") },
@@ -1952,6 +2003,7 @@ fun SessionScreen(
             },
             onDismiss = { settingsOpen = false },
             onCopyRenderReport = copyRenderReport,
+            onRunBenchmark = runBenchmark,
         )
     }
 }

app/androidApp/src/main/kotlin/com/example/aiapp/SessionSettingsDialog.kt

@@ -82,6 +82,13 @@ fun SessionSettingsDialog(
      * measures is that screen's own state.
      */
     onCopyRenderReport: () -> Unit,
+    /**
+     * Runs P0's scripted scroll-and-stream benchmark and copies the extended report, or null on
+     * every build but `bench` -- see [BuildConfig.FIXTURE_MODE] and BenchRun.kt. Null rather than
+     * always-present-but-disabled: this has no meaning at all outside the bench build, and a
+     * control with nothing behind it on every other build is not a state worth drawing.
+     */
+    onRunBenchmark: (() -> Unit)? = null,
 ) {
     val scope = rememberCoroutineScope()
     var name by remember(sessionId) { mutableStateOf(title) }
@@ -508,6 +515,21 @@ fun SessionSettingsDialog(
                     Text("Render timings", modifier = Modifier.weight(1f))
                     TextButton(onClick = onCopyRenderReport) { Text("Copy") }
                 }
+                // Bench-build only: see [onRunBenchmark]. Named exactly "Run benchmark" because
+                // ui-trace and the emulator smoke run find it by that label, the same way every
+                // other control here is found -- see AGENTS.md's "Driving the UI".
+                onRunBenchmark?.let { run ->
+                    Spacer(Modifier.height(8.dp))
+                    Row(
+                        verticalAlignment = Alignment.CenterVertically,
+                        modifier = Modifier.fillMaxWidth(),
+                    ) {
+                        Glyph(SPEED_GLYPH, colour = MaterialTheme.colorScheme.onSurface)
+                        Spacer(Modifier.width(8.dp))
+                        Text("P0 benchmark", modifier = Modifier.weight(1f))
+                        TextButton(onClick = run) { Text("Run benchmark") }
+                    }
+                }
             }
         },
         // Disabled rather than absent while there is nothing to save: a button that comes and goes

app/androidApp/src/main/res/values/strings.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Overridden by the `bench` build type's resValue (build.gradle.kts) to "AI Sessions bench",
+         so the two are never mistaken for each other in the launcher or in Settings. -->
+    <string name="app_name">AI Sessions</string>
+</resources>

app/bench-fixture/README.md

@@ -0,0 +1,28 @@
+# The P0 benchmark fixture
+
+`transcript.jsonl` is a synthetic transcript in the app's own event model (the JSON lines
+`GET /sessions/{id}/transcript` returns; see `Events.kt`'s `parseSeqEvent` and
+`server/src/session/driver.rs`) -- never a real one. It is what both the Compose `bench` build
+and iris's bench build open with no server, so the two apps draw exactly the same content and a
+frame-time comparison is measuring the renderer rather than the data.
+
+Generated by `./generate.py` (Python stdlib only, seeded -- `SEED = 20260905` -- so re-running it
+reproduces the same file byte for byte). It writes into `assets/` -- a separate directory from this
+script and README, because the Compose `bench` build type points its own asset source set straight
+at `assets/` (`app/androidApp/build.gradle.kts`'s `sourceSets { getByName("bench") }`), and a Python
+script and a markdown file have no business inside an APK:
+
+- `transcript.jsonl` -- 3,601 events. The first 3,200 (`BACKLOG_COUNT`) are the scrolled-back
+  history the benchmark opens with: user turns, tool calls with kilobyte-scale input/output,
+  assistant replies built from headings, bold/italic/inline code, a link, fenced code blocks that
+  rotate through rust/kotlin/python/sh/json/toml, a markdown table, two embedded images, and
+  periodic `usageDelta`/`compacted` events. The remaining 400 (`STREAM_COUNT`) are not part of the
+  opening window -- both bench harnesses replay them at a fixed rate (20/s) through the same live
+  fold path a real SSE reply arrives on, which is P0's "streaming phase."
+- `bench1.png`, `bench2.png` -- tiny (8x8) flat-colour PNGs, base64-free on disk but served the
+  same way a real attachment is (`GET /sessions/{id}/files/{name}`), referenced by the two
+  `"type":"image"` events in the transcript.
+
+Regenerate after changing the shape (a new event type, a different backlog/stream split) with
+`./generate.py`, and commit the result -- it is checked in rather than generated at build time so
+both apps' bench builds embed the identical bytes without needing this script at build time.

app/bench-fixture/generate.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Generates transcript.jsonl -- the synthetic fixture P0's benchmark opens in both apps.
+
+Deterministic (fixed seed), so a Compose bench APK and an iris bench APK draw byte-identical
+content: the point of the fixture is a like-for-like comparison, not a realistic one.
+
+Never a real transcript -- see AGENTS.md's ui-sandbox.sh, which this borrows its vocabulary
+style from (headings, code fences, a table, a link) rather than reusing its Claude-Code JSONL
+shape. This file's shape is the *app's own event model* instead: one JSON object per line,
+matching what GET /sessions/{id}/transcript returns and what Events.kt's parseSeqEvent reads
+(server/src/session/driver.rs is the source of truth for the field names).
+
+    ./generate.py                      writes transcript.jsonl and bench1.png/bench2.png here
+
+BACKLOG_COUNT events (seq 1..BACKLOG_COUNT) are the scrolled-back history the benchmark opens
+with. A further STREAM_COUNT events (seq BACKLOG_COUNT+1..) are not part of the opening window;
+both bench harnesses replay them at a fixed rate as the "streaming reply" phase, appended through
+the same live path a real SSE reply arrives on. Keeping both halves in one file means one
+generator and one seed to keep in sync, rather than two fixtures that can drift apart.
+"""
+import base64
+import json
+import random
+import struct
+import zlib
+from pathlib import Path
+
+SEED = 20260905
+BACKLOG_COUNT = 3200
+STREAM_COUNT = 400
+HERE = Path(__file__).resolve().parent / "assets"
+
+random.seed(SEED)
+
+LANGUAGES = ["rust", "kotlin", "python", "sh", "json", "toml"]
+
+CODE_SNIPPETS = {
+    "rust": '''fn fold_event(items: Vec<Item>, seq: u64) -> Vec<Item> {
+    // a comment worth keeping: this is the fold the app's own screen runs
+    let mut out = items;
+    out.push(Item::new(seq));
+    out
+}''',
+    "kotlin": '''fun foldEvent(items: List<TranscriptItem>, entry: SeqEvent): List<TranscriptItem> {
+    // mirrors the server's own event model, one item per line
+    return items + TranscriptItem.from(entry)
+}''',
+    "python": '''def render_report(frames, cpu_ms, rss_kb):
+    # printed for a human to paste back, so every number carries its unit
+    return f"{frames} frames, {cpu_ms}ms cpu, {rss_kb}kb peak rss"''',
+    "sh": '''#!/bin/sh
+# scripted scroll loop, the shape transcript-bench.sh drives on a phone
+for i in $(seq 1 24); do
+    ui-trace record --do "swipe 540 700 540 1600 200"
+done''',
+    "json": '{"seq": 1, "type": "status", "state": "running"}',
+    "toml": '''[package]
+name = "bench-fixture"
+version = "0.1.0"''',
+}
+
+HEADINGS = [
+    "## Plan",
+    "## What changed",
+    "## Why this approach",
+    "### Open questions",
+    "## Results",
+]
+
+WORDS = (
+    "session render report frame budget scroll transcript fold event cache "
+    "cursor probe stream backlog swipe fixture bench compose iris widget layout "
+    "measure place draw tool call token context window anchor"
+).split()
+
+
+def paragraph(n=24):
+    words = [random.choice(WORDS) for _ in range(n)]
+    words[0] = words[0].capitalize()
+    text = " ".join(words) + "."
+    # Sprinkle markdown inline spans so the syntax highlighter/markdown parser sees a real mix.
+    text = text.replace(" fold ", " **fold** ", 1)
+    text = text.replace(" cursor ", " *cursor* ", 1)
+    text = text.replace(" cache ", " `cache` ", 1)
+    if "bench" in text:
+        text = text.replace(
+            " bench ", " [bench](https://example.com/bench) ", 1
+        )
+    return text
+
+
+def make_png(rgb, size=8):
+    """A tiny, valid PNG -- flat colour, no external dependency."""
+
+    def chunk(tag, data):
+        c = tag + data
+        return struct.pack(">I", len(data)) + c + struct.pack(">I", zlib.crc32(c))
+
+    sig = b"\x89PNG\r\n\x1a\n"
+    ihdr = struct.pack(">IIBBBBB", size, size, 8, 2, 0, 0, 0)
+    raw = b""
+    for _ in range(size):
+        raw += b"\x00" + bytes(rgb) * size
+    idat = zlib.compress(raw)
+    return sig + chunk(b"IHDR", ihdr) + chunk(b"IDAT", idat) + chunk(b"IEND", b"")
+
+
+def main():
+    HERE.mkdir(exist_ok=True)
+    lines = []
+    seq = 1
+    ts = 1_788_000_000.0
+
+    def emit(type_, **fields):
+        nonlocal seq, ts
+        obj = {"seq": seq, "ts": round(ts, 3), "type": type_}
+        obj.update(fields)
+        lines.append(json.dumps(obj, separators=(",", ":")))
+        seq += 1
+        ts += random.uniform(0.05, 2.0)
+
+    emit("status", state="running")
+    emit("settings", model="bench-model", permissionMode="auto")
+
+    image_refs = []
+    turn = 0
+    while seq <= BACKLOG_COUNT:
+        turn += 1
+        emit("userMessage", text=f"Turn {turn}: {paragraph(12)}", id=None, attachments=[])
+
+        # A tool call with kilobyte-scale input/output every few turns.
+        if turn % 3 == 0:
+            tool_id = f"tool-{turn}"
+            big_input = json.dumps({"path": f"/repo/file_{turn}.rs", "content": paragraph(400)})
+            emit("toolStart", id=tool_id, tool="Edit", input=big_input)
+            big_output = "\n".join(paragraph(60) for _ in range(20))
+            emit("toolUpdate", id=tool_id, output=big_output[: len(big_output) // 2])
+            emit("toolEnd", id=tool_id, output=big_output)
+
+        # A reply: a heading, prose, a fenced block in a rotating language, a table, then deltas.
+        emit("assistantText", delta=f"{random.choice(HEADINGS)}\n\n")
+        emit("assistantText", delta=paragraph(30) + "\n\n")
+        lang = LANGUAGES[turn % len(LANGUAGES)]
+        emit("assistantText", delta=f"```{lang}\n{CODE_SNIPPETS[lang]}\n```\n\n")
+        if turn % 5 == 0:
+            emit(
+                "assistantText",
+                delta="| column | value |\n|---|---|\n| a | " + paragraph(3) + " |\n\n",
+            )
+        # A run of small deltas -- the shape a live reply actually streams in.
+        for _ in range(random.randint(3, 8)):
+            emit("assistantText", delta=paragraph(6) + " ")
+
+        # A couple of images, base64 PNGs, the way a real transcript embeds a screenshot.
+        if turn in (10, 40):
+            ref = f"bench{len(image_refs) + 1}.png"
+            image_refs.append(ref)
+            emit("image", ref=ref, about=None)
+
+        emit("usageDelta", tokens=random.randint(200, 4000), context=random.randint(2000, 180000))
+
+        if turn % 15 == 0:
+            emit(
+                "compacted",
+                preTokens=180000,
+                postTokens=20000,
+                trigger="auto",
+            )
+
+    # The streaming-phase tail: one long reply, built entirely from text deltas, the shape a
+    # bench harness replays at a fixed events/sec through the live fold path.
+    emit("userMessage", text="One more, streamed live for the benchmark's timing phase.", id=None, attachments=[])
+    while seq <= BACKLOG_COUNT + STREAM_COUNT:
+        emit("assistantText", delta=paragraph(5) + " ")
+    emit("status", state="idle")
+
+    (HERE / "transcript.jsonl").write_text("\n".join(lines) + "\n")
+
+    (HERE / "bench1.png").write_bytes(make_png((220, 90, 90)))
+    (HERE / "bench2.png").write_bytes(make_png((90, 150, 220)))
+
+    print(f"wrote {len(lines)} events ({BACKLOG_COUNT} backlog + {STREAM_COUNT} stream) to transcript.jsonl")
+
+
+if __name__ == "__main__":
+    main()

app/build-apk.sh

@@ -4,6 +4,11 @@
 #   ./build-apk.sh            the release build, signed (what the phone runs)
 #   ./build-apk.sh debug      the debug build, for reproducing something the
 #                             emulator scripts would build anyway
+#   ./build-apk.sh bench      P0's benchmark build (own app id, "AI Sessions
+#                             bench" label, opens straight onto the fixture
+#                             session -- see docs/RUST.md's P0 box and
+#                             app/bench-fixture/README.md). Signed the same
+#                             as release; never touches the CA it pins.
 #
 # Dev Updater's `.dev-updater.ron` at the checkout root spells these out as
 # build modes, one command line each; it passes nothing else, so the word
@@ -25,8 +30,9 @@ VARIANT=${1:-release}
 case "$VARIANT" in
 release) TASK=assembleRelease ;;
 debug) TASK=assembleDebug ;;
+bench) TASK=assembleBench ;;
 *)
-    echo "build-apk.sh: unknown variant '$VARIANT' (release, debug)" >&2
+    echo "build-apk.sh: unknown variant '$VARIANT' (release, debug, bench)" >&2
     exit 2
     ;;
 esac
@@ -81,7 +87,7 @@ fi
 # uninstalling it first: the signatures differ, and Android refuses to
 # update across them.
 KEYSTORE="${AI_APP_KEYSTORE:-${XDG_CONFIG_HOME:-$HOME/.config}/ai-app/release.jks}"
-if [ "$VARIANT" = release ] && [ ! -f "$KEYSTORE" ]; then
+if { [ "$VARIANT" = release ] || [ "$VARIANT" = bench ]; } && [ ! -f "$KEYSTORE" ]; then
     KEYTOOL="${JAVA_HOME:+$JAVA_HOME/bin/keytool}"
     KEYTOOL="${KEYTOOL:-keytool}"
     if ! command -v "$KEYTOOL" >/dev/null 2>&1; then
@@ -97,7 +103,7 @@ if [ "$VARIANT" = release ] && [ ! -f "$KEYSTORE" ]; then
         -keyalg RSA -keysize 2048 -validity 10000 \
         -storepass "$PASSWORD" -keypass "$PASSWORD" -dname "CN=ai-app" >/dev/null 2>&1)
 fi
-if [ "$VARIANT" = release ]; then
+if [ "$VARIANT" = release ] || [ "$VARIANT" = bench ]; then
     AI_APP_KEYSTORE="$KEYSTORE"
     AI_APP_KEYSTORE_PASSWORD=$(cat "$KEYSTORE.password")
     export AI_APP_KEYSTORE AI_APP_KEYSTORE_PASSWORD

app/iris-scroll.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+# RUST.md's I5 "Where iris's frame time goes" pass (2026-09-05). The same
+# 24-swipe/6-cycle loop as transcript-bench.sh's, extracted for iris's own
+# demo app -- transcript-bench.sh itself is Compose-specific (opens by
+# session title through the Compose app's own UI) and cannot be called
+# directly against dev.iris.android.demo.
+#
+# MUST be run from inside this checkout (not /tmp): ui-trace/adb pick which
+# emulator to target from the current directory's basename (the
+# per-checkout-AVD rule), and a previous pass lost two attempts to a `cd`
+# into /tmp that made this resolve to a nonexistent "tmp" checkout.
+set -eu
+cd "$(dirname "$0")"
+. ./android-env.sh >/dev/null 2>&1
+
+cycles=${1:-6}
+
+ui-trace record -d 3000 --do "tap 'Reset frame report'" -o /tmp/iris-bench-reset.txt >/dev/null
+adb logcat -c
+
+DO=""
+i=0
+while [ "$i" -lt "$cycles" ]; do
+    DO="$DO --do 'swipe 540 700 540 1600 200' --do 'wait 500'"
+    DO="$DO --do 'swipe 540 700 540 1600 200' --do 'wait 500'"
+    DO="$DO --do 'swipe 540 1600 540 700 200' --do 'wait 500'"
+    DO="$DO --do 'swipe 540 1600 540 700 200' --do 'wait 500'"
+    i=$((i + 1))
+done
+eval ui-trace record -d $((cycles * 16000 + 20000)) $DO -o /tmp/iris-bench-scroll.txt >/dev/null
+
+ui-trace record -d 3000 --do "tap 'Frame report'" -o /tmp/iris-bench-report.txt >/dev/null
+sleep 1
+adb logcat -d -s iris-android-app:I | grep "iris frame report:"

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,37 @@
+[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 `docs/CLIENT_CORE.md` 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"] }
+# "raw_value" is `fetch_transcript_lines`'s reason -- it needs the exact
+# bytes the server sent, not this crate's own re-serialization of a parsed
+# `Value`, so a cached line and a live SSE frame for the same event agree
+# byte-for-byte (see that method's doc). "float_roundtrip" is why they
+# agree on a `ts` at all -- see server/Cargo.toml's identical comment.
+serde_json = { version = "1", features = ["float_roundtrip", "raw_value"] }
+# 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,609 @@
+//! 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 event_model::SeqEvent;
+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 }
+    }
+
+    /// The transport underneath, for a caller that needs the raw SSE
+    /// stream (`event_stream::follow_session_events`) rather than one of
+    /// this client's typed REST calls -- `transcript_source::TranscriptSource`
+    /// is the one that does.
+    pub fn transport(&self) -> &T {
+        &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> {
+        self.json_request(
+            "GET",
+            &transcript_path(session_id, before, limit, coalesce, None),
+            None,
+        )
+    }
+
+    /// A page of transcript history, each line handed back paired with the
+    /// exact text it came from, and bounded below by `after` -- the shape
+    /// `crate::transcript_source::TranscriptSource` needs to store what it
+    /// fetched in the transcript cache without a second round trip to fetch
+    /// the raw text separately. Ported from `Api.kt`'s `fetchTranscript`.
+    ///
+    /// Uses [`serde_json::value::RawValue`] rather than re-serializing a
+    /// parsed [`Value`], so the stored line is the exact bytes the server
+    /// sent (key order and float literal included) rather than this
+    /// crate's own idea of how to write them back out -- the cache and a
+    /// live SSE frame must agree byte-for-byte on the same event, which is
+    /// exactly what caught the `serde_json` float-rounding bug this
+    /// project's `AGENTS.md` records.
+    pub fn fetch_transcript_lines(
+        &self,
+        session_id: &str,
+        before: Option<u64>,
+        limit: u32,
+        coalesce: bool,
+        after: Option<u64>,
+    ) -> Result<Vec<(String, SeqEvent)>, ApiError> {
+        let path = transcript_path(session_id, before, limit, coalesce, after);
+        let raw: Vec<Box<serde_json::value::RawValue>> = self.json_request("GET", &path, None)?;
+        raw.into_iter()
+            .map(|value| {
+                let line = value.get().to_string();
+                let event: SeqEvent = serde_json::from_str(&line).map_err(|e| ApiError {
+                    message: format!(
+                        "the server sent a transcript line this build couldn't parse: {e}"
+                    ),
+                    status: None,
+                })?;
+                Ok((line, event))
+            })
+            .collect()
+    }
+}
+
+/// The query string shared by [`ApiClient::fetch_transcript_page`] and
+/// [`ApiClient::fetch_transcript_lines`], so the two agree on how each
+/// parameter is written rather than keeping two copies to drift.
+fn transcript_path(
+    session_id: &str,
+    before: Option<u64>,
+    limit: u32,
+    coalesce: bool,
+    after: Option<u64>,
+) -> String {
+    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");
+    }
+    if let Some(after) = after {
+        path.push_str(&format!("&after={after}"));
+    }
+    path
+}
+
+/// 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()
+            && 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,16 @@
+//! The app's pure logic, shared between the server and any Rust client --
+//! see `docs/CLIENT_CORE.md` 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 mod transcript_source;
+
+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_source.rs

@@ -0,0 +1,588 @@
+//! Where a session screen gets a transcript from: this phone's copy first,
+//! the server for the rest. Ported from `app/.../TranscriptSource.kt`; see
+//! `docs/TRANSCRIPT_CACHE.md` for the design this implements and
+//! `docs/CLIENT_CORE.md` for how this file corresponds to the Kotlin.
+//!
+//! One seam rather than a cache the screen has to remember to consult.
+//! Everything fetched before is asked of this, and everything the server
+//! sends is written into the cache on the way past, so a caller never
+//! learns which side answered. The one rule worth keeping in mind: the
+//! cache is never load-bearing. Every read here has a network path beside
+//! it producing the same result.
+//!
+//! **Not ported**: `EventStream.kt`'s reconnect-with-backoff loop and the
+//! ability to close a live stream from another thread. Both are wall-clock
+//! and thread-lifetime concerns that belong to whatever runtime the caller
+//! embeds this crate in (a Tokio task, an iris timer, a Kotlin coroutine
+//! scope) rather than to this pure logic -- `follow` below is the same
+//! decorator shape `iris/desktop-app/src/app.rs` and
+//! `iris/android-app/src/transcript_client.rs` already hand-wrote around
+//! `event_stream::follow_session_events`, just with the cache write built
+//! in so a future caller does not have to repeat it a third time.
+
+use event_model::SeqEvent;
+
+use crate::api::{ApiClient, ApiError, Transport};
+use crate::event_stream::{self, StreamItem};
+use crate::transcript_cache::SessionCache;
+
+/// How many events a session screen opens with, cached or fetched.
+///
+/// The server's own default page size, named here because the cached
+/// opening has to be the same size as the fetched one -- a reader must not
+/// get a shorter first screen for having been here before (`OPENING_WINDOW`
+/// in the Kotlin original).
+pub const OPENING_WINDOW: u32 = 80;
+
+/// A transcript-line parse failure, told apart from [`ApiError`] so a
+/// caller can tell "the server is unreachable" from "the server (or this
+/// phone's own disk) sent something this build cannot read" -- the two
+/// mean different things to a reader (retry, versus a build that is
+/// behind).
+#[derive(Debug, Clone)]
+pub struct ParseError(pub String);
+
+impl std::fmt::Display for ParseError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+impl std::error::Error for ParseError {}
+
+/// Either half of what can go wrong asking for a page: the network, or a
+/// line neither the cache's nor the server's copy of `parseSeqEvent` could
+/// read.
+#[derive(Debug, Clone)]
+pub enum PageError {
+    Api(ApiError),
+    Parse(ParseError),
+}
+
+impl From<ApiError> for PageError {
+    fn from(e: ApiError) -> Self {
+        Self::Api(e)
+    }
+}
+
+impl From<ParseError> for PageError {
+    fn from(e: ParseError) -> Self {
+        Self::Parse(e)
+    }
+}
+
+/// What [`TranscriptSource::page`] found, kept as two states rather than
+/// one possibly-empty list.
+///
+/// The difference is the whole of AGENTS.md's `loadOlderPage` incident: an
+/// empty [`Self::Events`] means "this conversation has no more history",
+/// which a caller is meant to latch, and [`Self::NothingLoaded`] means the
+/// question could not be asked yet, which it must not. Collapsing the two
+/// into an empty `Vec` puts the bug back, because the caller cannot tell
+/// them apart -- and `unwrap_or_default()` on an `Option` would do the
+/// same silently.
+#[derive(Debug, Clone, PartialEq)]
+pub enum OlderPage {
+    /// The events before the cursor, oldest first. Empty means the start
+    /// of the conversation has been reached.
+    Events(Vec<SeqEvent>),
+    /// Nothing is loaded, so there was no cursor to page back from
+    /// (`before == 0`). Not an answer about the conversation at all.
+    NothingLoaded,
+}
+
+fn parse_line(line: &str) -> Result<SeqEvent, ParseError> {
+    serde_json::from_str(line).map_err(|e| ParseError(format!("{e}")))
+}
+
+/// This phone's copy of one session's transcript, plus the server it
+/// falls back to. Ported from the Kotlin `TranscriptSource` class.
+pub struct TranscriptSource<T: Transport> {
+    api: ApiClient<T>,
+    session_id: String,
+    pub cache: SessionCache,
+}
+
+impl<T: Transport> TranscriptSource<T> {
+    pub fn new(api: ApiClient<T>, session_id: impl Into<String>, cache: SessionCache) -> Self {
+        Self {
+            api,
+            session_id: session_id.into(),
+            cache,
+        }
+    }
+
+    /// The cached opening window, or `None` when there is nothing usable
+    /// to draw.
+    ///
+    /// Meant to be drawn *before* [`Self::probe`] returns, which is the
+    /// whole point of the feature: the rows are on screen while the check
+    /// that they are still the server's rows is in flight, and a failed
+    /// check replaces them exactly as a reset does.
+    pub fn cached_opening(&self, limit: usize) -> Option<Vec<SeqEvent>> {
+        self.cache.tail()?;
+        let lines = self.cache.newest(limit);
+        if lines.is_empty() {
+            return None;
+        }
+        match lines.iter().map(|l| parse_line(l)).collect() {
+            Ok(events) => Some(events),
+            // A line this build cannot read at all, which the cache's own checks cannot
+            // see: it reads a seq off a line, not an event. Nothing to serve, so a cold
+            // open.
+            Err(ParseError(_)) => {
+                self.cache.purge();
+                None
+            }
+        }
+    }
+
+    /// Whether the server's event at the cached cursor is still the cached
+    /// one.
+    ///
+    /// A caller must not resume a live stream from a cached seq unless it
+    /// is the same conversation: a transcript is append-only in ordinary
+    /// use, but the file backing it can be replaced or truncated (a
+    /// sandbox re-seeded with the same ids, a backup restored, a session
+    /// re-imported), and the server's catch-up on such a file would hand
+    /// this phone a continuation of a *different* conversation, spliced
+    /// onto the cached one with no seam. Caught with one request of a few
+    /// hundred bytes.
+    ///
+    /// `Ok(false)` purges the cache and means "open cold". `Err` is the
+    /// server not being askable, which is neither: the cached rows stay
+    /// on screen and the caller tries again on its own reconnect schedule.
+    ///
+    /// What this cannot see is a line changed in the middle of the file
+    /// with the tail intact -- that is what a full reload is for.
+    pub fn probe(&self) -> Result<bool, ApiError> {
+        let Some(tail) = self.cache.tail() else {
+            return Ok(false);
+        };
+        // `before = seq + 1` is the newest event with seq <= the cursor, which is the
+        // event *at* the cursor when the server still has one there.
+        let page = self.api.fetch_transcript_lines(
+            &self.session_id,
+            Some(tail.seq + 1),
+            1,
+            false,
+            None,
+        )?;
+        let matches = page.len() == 1
+            && parse_line(&tail.line)
+                .map(|cached| cached == page[0].1)
+                .unwrap_or(false);
+        if !matches {
+            self.cache.purge();
+        }
+        Ok(matches)
+    }
+
+    /// Today's opening fetch, kept as the start of the live run. Only
+    /// called when the cache has nothing to open with, or when
+    /// [`Self::probe`] said what it had was not the server's.
+    pub fn fetch_opening(&self) -> Result<Vec<SeqEvent>, ApiError> {
+        let page =
+            self.api
+                .fetch_transcript_lines(&self.session_id, None, OPENING_WINDOW, false, None)?;
+        for (line, event) in &page {
+            self.cache.append(line, event.seq);
+        }
+        self.cache.flush();
+        Ok(page.into_iter().map(|(_, event)| event).collect())
+    }
+
+    /// The page before `before`: from the cache when it holds it,
+    /// otherwise from the server bounded by what the cache already has.
+    ///
+    /// The server bound (`after`) is what keeps the cache worth having. A
+    /// coalesced page reaches back as far as its row count takes it -- a
+    /// single reply is hundreds of lines -- so a page fetched after the
+    /// reader has been away could run straight past the cached run and
+    /// overlap it, and an overlapping page cannot be stored. Told where
+    /// this phone's copy starts, the server stops there instead.
+    ///
+    /// `before == 0` answers [`OlderPage::NothingLoaded`] without asking
+    /// the cache or the server anything -- see AGENTS.md's "things that
+    /// have bitten": there is no event before the first one, so the
+    /// request is not a harmless no-op, and its empty answer is
+    /// indistinguishable from having reached the start of history.
+    /// Guarded here rather than left to every caller, because it is a fact
+    /// about the question, not about who is asking it.
+    pub fn page(&self, before: u64, limit: u32, coalesce: bool) -> Result<OlderPage, PageError> {
+        if before == 0 {
+            return Ok(OlderPage::NothingLoaded);
+        }
+        if let Some(lines) = self.cache.page(before, limit as usize, coalesce) {
+            let events: Vec<SeqEvent> = lines
+                .iter()
+                .map(|l| parse_line(l).map_err(PageError::from))
+                .collect::<Result<_, _>>()?;
+            return Ok(OlderPage::Events(events));
+        }
+        let after = self.cache.covered_up_to(before).map(|v| v - 1);
+        let page = self.api.fetch_transcript_lines(
+            &self.session_id,
+            Some(before),
+            limit,
+            coalesce,
+            after,
+        )?;
+        if let Some((_, first_event)) = page.first() {
+            // `before` rather than the newest line's seq: a coalesced page covers
+            // everything up to the cursor it was asked with, and nothing in its lines
+            // says so.
+            let lines: Vec<String> = page.iter().map(|(line, _)| line.clone()).collect();
+            self.cache
+                .store_page(&lines, first_event.seq, before, coalesce);
+        }
+        Ok(OlderPage::Events(
+            page.into_iter().map(|(_, event)| event).collect(),
+        ))
+    }
+
+    /// [`event_stream::follow_session_events`], with every frame written to
+    /// the cache before `on_item` sees it.
+    ///
+    /// Before, so that an event held back for a reader who is scrolled
+    /// away is already on disk -- what the cache holds is what the server
+    /// sent, not what a screen has got round to drawing. Flushed on each
+    /// status change, which is a turn's boundary and the granularity a
+    /// crash may as well lose, and once more when the stream ends.
+    pub fn follow(
+        &self,
+        after: u64,
+        mut on_item: impl FnMut(StreamItem) -> bool,
+    ) -> Result<(), ApiError> {
+        let cache = &self.cache;
+        let result = event_stream::follow_session_events(
+            self.api.transport(),
+            &self.session_id,
+            after,
+            |item| {
+                if let StreamItem::Event { raw, event } = &item {
+                    cache.append(raw, event.seq);
+                    if matches!(event.event, event_model::Event::Status { .. }) {
+                        cache.flush();
+                    }
+                }
+                on_item(item)
+            },
+        );
+        cache.flush();
+        result
+    }
+
+    /// Leaves the cache with everything it was given -- called once a
+    /// caller is done with this source, mirroring the Kotlin `close`'s
+    /// final flush (that method's stream cancellation itself is the
+    /// runtime concern the module doc says is not ported here).
+    pub fn close(&self) {
+        self.cache.flush();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::{Body, RawResponse};
+    use std::collections::VecDeque;
+    use std::io::Read;
+    use std::sync::Mutex;
+
+    /// A transport that answers fixed bodies in call order, and records
+    /// every path it was asked for -- so a test can assert *how many*
+    /// requests a method made, which is the point for the `before == 0`
+    /// guard (AGENTS.md's regression: the guard must stop the request
+    /// before it happens, not merely tolerate the empty answer).
+    #[derive(Default)]
+    struct ScriptedTransport {
+        responses: Mutex<VecDeque<(u16, String)>>,
+        calls: Mutex<Vec<String>>,
+    }
+
+    impl ScriptedTransport {
+        fn respond(&self, status: u16, body: impl Into<String>) {
+            self.responses
+                .lock()
+                .unwrap()
+                .push_back((status, body.into()));
+        }
+
+        fn call_count(&self) -> usize {
+            self.calls.lock().unwrap().len()
+        }
+    }
+
+    impl Transport for ScriptedTransport {
+        fn request(
+            &self,
+            _method: &str,
+            path: &str,
+            _body: Option<Body>,
+        ) -> Result<RawResponse, ApiError> {
+            self.calls.lock().unwrap().push(path.to_string());
+            let (status, body) = self
+                .responses
+                .lock()
+                .unwrap()
+                .pop_front()
+                .unwrap_or_else(|| panic!("ScriptedTransport got an unscripted request: {path}"));
+            Ok(RawResponse {
+                status,
+                body: body.into_bytes(),
+            })
+        }
+
+        fn stream(&self, path: &str) -> Result<Box<dyn Read + Send>, ApiError> {
+            self.calls.lock().unwrap().push(path.to_string());
+            let (_, body) = self
+                .responses
+                .lock()
+                .unwrap()
+                .pop_front()
+                .unwrap_or_else(|| {
+                    panic!("ScriptedTransport got an unscripted stream request: {path}")
+                });
+            Ok(Box::new(std::io::Cursor::new(body.into_bytes())))
+        }
+    }
+
+    fn source(
+        transport: ScriptedTransport,
+        cache_root: &std::path::Path,
+    ) -> TranscriptSource<ScriptedTransport> {
+        let api = ApiClient::new(transport);
+        let cache = crate::transcript_cache::TranscriptCache::new(cache_root).session("s1");
+        TranscriptSource::new(api, "s1", cache)
+    }
+
+    fn status_line(seq: u64) -> String {
+        format!(r#"{{"seq":{seq},"ts":1.0,"type":"status","state":"idle"}}"#)
+    }
+
+    #[test]
+    fn a_cold_cache_has_no_opening_and_fetches_from_the_server() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(1)));
+        let source = source(transport, dir.path());
+
+        assert_eq!(source.cached_opening(80), None);
+        let opening = source.fetch_opening().unwrap();
+        assert_eq!(opening.len(), 1);
+        assert_eq!(opening[0].seq, 1);
+        // The fetch wrote through: reopening the same cache now has something to show.
+        assert!(source.cache.tail().is_some());
+    }
+
+    #[test]
+    fn probe_matching_the_cached_tail_leaves_the_cache_alone() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(1)));
+        let source = source(transport, dir.path());
+        source.fetch_opening().unwrap();
+
+        let transport2 = ScriptedTransport::default();
+        transport2.respond(200, format!("[{}]", status_line(1)));
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        let source2 = TranscriptSource::new(ApiClient::new(transport2), "s1", cache);
+        assert!(source2.probe().unwrap());
+        assert!(source2.cache.tail().is_some());
+    }
+
+    #[test]
+    fn probe_mismatching_the_cached_tail_purges_the_cache() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(1)));
+        let source = source(transport, dir.path());
+        source.fetch_opening().unwrap();
+
+        // The server now answers with a different event at the same seq -- the file
+        // behind this session was replaced.
+        let transport2 = ScriptedTransport::default();
+        let different = r#"{"seq":1,"ts":1.0,"type":"status","state":"running"}"#.to_string();
+        transport2.respond(200, format!("[{different}]"));
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        let source2 = TranscriptSource::new(ApiClient::new(transport2), "s1", cache);
+        assert!(!source2.probe().unwrap());
+        assert!(source2.cache.tail().is_none());
+    }
+
+    #[test]
+    fn probe_finding_no_server_leaves_the_cache_untouched() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(1)));
+        let source = source(transport, dir.path());
+        source.fetch_opening().unwrap();
+
+        let transport2 = ScriptedTransport::default();
+        transport2.respond(500, "server on fire");
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        let source2 = TranscriptSource::new(ApiClient::new(transport2), "s1", cache);
+        assert!(source2.probe().is_err());
+        assert!(
+            source2.cache.tail().is_some(),
+            "an unreachable server must not be treated as a mismatch"
+        );
+    }
+
+    /// The regression this module exists to close: `before == 0` must
+    /// never reach the network or the cache, because an empty answer there
+    /// is indistinguishable from "there is genuinely no more history" --
+    /// AGENTS.md's `loadOlderPage` incident.
+    #[test]
+    fn paging_before_the_first_event_makes_no_request_at_all() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        let source = source(transport, dir.path());
+        assert_eq!(source.page(0, 80, true).unwrap(), OlderPage::NothingLoaded);
+        assert_eq!(source.api.transport().call_count(), 0);
+    }
+
+    #[test]
+    fn a_page_already_covered_by_the_cache_never_reaches_the_server() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{},{}]", status_line(1), status_line(2)));
+        let source = source(transport, dir.path());
+        source.fetch_opening().unwrap();
+
+        let calls_before = source.api.transport().call_count();
+        let OlderPage::Events(page) = source.page(2, 10, true).unwrap() else {
+            panic!("a cursor of 2 is a real question about the conversation");
+        };
+        assert_eq!(page.len(), 1);
+        assert_eq!(page[0].seq, 1);
+        assert_eq!(
+            source.api.transport().call_count(),
+            calls_before,
+            "a cache hit must not touch the network"
+        );
+    }
+
+    /// With nothing older cached there is no floor to give the server, so
+    /// the request carries no `after` at all.
+    #[test]
+    fn a_server_page_with_nothing_older_cached_carries_no_bound() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(5)));
+        let source = source(transport, dir.path());
+        source.fetch_opening().unwrap();
+
+        let transport2 = ScriptedTransport::default();
+        transport2.respond(200, format!("[{}]", status_line(3)));
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        let source2 = TranscriptSource::new(ApiClient::new(transport2), "s1", cache);
+        source2.page(5, 10, true).unwrap();
+        assert_eq!(
+            source2.api.transport().calls.lock().unwrap()[0],
+            "/sessions/s1/transcript?limit=10&before=5&coalesce=true"
+        );
+    }
+
+    /// The half the test above cannot show: when the cache *does* hold an
+    /// older run, the fetch is floored at its end, or the page would run
+    /// straight past it and overlap -- which `store_page` then refuses,
+    /// silently costing the phone the page it just paid for.
+    #[test]
+    fn a_server_page_is_floored_at_the_end_of_the_cached_run() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        // A stored page covering [3, 6) and two live events above it, so the run this
+        // phone holds is [3, 8) -- the newest chunk has to be an appended one, or the
+        // cache reads the directory as damaged and discards it.
+        let lines: Vec<String> = (3..6).map(status_line).collect();
+        assert!(cache.store_page(&lines, 3, 6, true));
+        cache.append(&status_line(6), 6);
+        cache.append(&status_line(7), 7);
+        cache.flush();
+
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("[{}]", status_line(9)));
+        let source = TranscriptSource::new(ApiClient::new(transport), "s1", cache);
+        source.page(10, 10, true).unwrap();
+        assert_eq!(
+            source.api.transport().calls.lock().unwrap()[0],
+            "/sessions/s1/transcript?limit=10&before=10&coalesce=true&after=7",
+            "the fetch must stop one seq below where this phone's copy ends"
+        );
+    }
+
+    /// A page the server could not answer is an error, never an empty
+    /// page: the caller would read the second as "this conversation has no
+    /// more history" and stop paging for good.
+    #[test]
+    fn a_failing_server_page_is_an_error_rather_than_an_empty_one() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(500, "server on fire");
+        let source = source(transport, dir.path());
+        assert!(matches!(source.page(9, 10, true), Err(PageError::Api(_)),));
+    }
+
+    /// A cached line this build cannot read is told apart from the network
+    /// failing, for the same reason: neither is "no more history".
+    #[test]
+    fn an_unreadable_cached_page_is_a_parse_error_rather_than_an_empty_one() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        cache.store_page(
+            &[r#"{"seq":3,"but":"not an event"}"#.to_string()],
+            3,
+            4,
+            true,
+        );
+        cache.append(&status_line(4), 4);
+        cache.flush();
+        let transport = ScriptedTransport::default();
+        let source = TranscriptSource::new(ApiClient::new(transport), "s1", cache);
+        assert!(matches!(source.page(4, 10, true), Err(PageError::Parse(_)),));
+        assert_eq!(
+            source.api.transport().call_count(),
+            0,
+            "a cache hit that cannot be read must not fall through to the server unnoticed"
+        );
+    }
+
+    #[test]
+    fn a_bad_cached_opening_line_purges_rather_than_panicking() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = crate::transcript_cache::TranscriptCache::new(dir.path()).session("s1");
+        cache.append("not json at all", 1);
+        cache.flush();
+        let transport = ScriptedTransport::default();
+        let source = TranscriptSource::new(ApiClient::new(transport), "s1", cache);
+        assert_eq!(source.cached_opening(80), None);
+        assert!(
+            source.cache.tail().is_none(),
+            "a damaged line purges the cache"
+        );
+    }
+
+    #[test]
+    fn follow_writes_events_to_the_cache_before_the_caller_sees_them() {
+        let dir = tempfile::tempdir().unwrap();
+        let transport = ScriptedTransport::default();
+        transport.respond(200, format!("{}\n\n", sse_frame(&status_line(1))));
+        let source = source(transport, dir.path());
+        let mut seen = Vec::new();
+        source
+            .follow(0, |item| {
+                if let StreamItem::Event { event, .. } = item {
+                    seen.push(event.seq);
+                }
+                true
+            })
+            .unwrap();
+        assert_eq!(seen, vec![1]);
+        assert_eq!(source.cache.tail().unwrap().seq, 1);
+    }
+
+    fn sse_frame(data: &str) -> String {
+        format!("data:{data}")
+    }
+}

docs/CLIENT_CORE.md

@@ -0,0 +1,213 @@
+# 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`       | Done -- see below |
+| `config.rs`                                | `ServerConfig.kt`'s `handleEnrollment`   | New, desktop-only so far -- see below |
+| `transcript_source.rs`                    | `TranscriptSource.kt`                     | Done -- see below |
+| *(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`,
+`transcript_source.rs` -- the Kotlin `TranscriptSource.kt`/`TranscriptItems.kt`
+had no JVM unit tests of their own, so these were written fresh against the
+Kotlin source and AGENTS.md's paging incidents as the spec). Test count by
+crate as of this writing: **109 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`.
+
+`join_pages` (with `heal_split_message` and `adopt_run`, both private) is
+now ported too, 2026-09-06 -- the page-boundary healing that merges a tool
+call split across two fetched pages, rejoins a message a boundary cut
+through, and renames a run of tool calls onto whichever name is already on
+screen. Ported with AGENTS.md's "things that have bitten" incidents as the
+spec rather than a JVM test file (`TranscriptItems.kt` had none of its
+own): `a_clean_boundary_between_two_finished_runs_is_still_healed_into_one_run`
+is the regression test for the bug that shipped -- `adopt_run` must run on
+*every* join, not only the one where a split call was found, or a boundary
+landing cleanly between two already-finished calls (most of them) leaves
+one run drawn as two. `a_call_split_across_the_boundary_merges_into_one_row`,
+`a_message_split_across_the_boundary_is_rejoined_with_the_newer_halfs_identity`,
+and `adopt_run_never_renames_into_a_question_row` cover the other three
+edges the Kotlin doc calls out. `join_pages` ends in a `debug_assert!`
+that no tool id survives in both halves -- the duplicate row it exists to
+prevent, checked rather than assumed. What it deliberately does *not*
+assert is seq ordering across the boundary: a peer note carries the seq
+its turn began at (`place_peer_note`), which can be older than the page
+it arrived in, so the two pages' seqs legitimately interleave there. An
+earlier draft asserted it and would have panicked in debug builds on an
+ordinary transcript.
+
+**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 `transcript_source.rs` covers, and what it does not
+
+`TranscriptSource<T: Transport>` is the seam a session screen asks for a
+page, ported test-for-test against the Kotlin doc rather than a JVM test
+file (there wasn't one): `cached_opening`, `probe`, `fetch_opening`,
+`page` and `follow`, each matching its Kotlin namesake's contract --
+including `probe`'s three-way outcome (matches / cache purged /
+unreachable, told apart so a caller never treats "couldn't ask" as "was
+wrong") and `page`'s cache-vs-server split bounded by `covered_up_to`.
+
+Two additions beyond a literal port, both load-bearing:
+
+- **`page(before, ..)` refuses `before == 0` before touching the cache or
+  the network**, answering `OlderPage::NothingLoaded`. This is AGENTS.md's
+  `loadOlderPage` incident (`before = 0` is "no event before the first
+  one," indistinguishable from "reached the start of history" if a caller
+  ever asks it) moved out of the Kotlin screen and into this layer, so
+  every future caller gets the guard rather than having to remember it.
+  **The return type is `OlderPage`, not a `Vec`, and that is the guard.**
+  The Kotlin's two falses are different answers -- `oldestSeq == 0`
+  returns without touching `moreHistory`, an empty page latches it false
+  -- so a port that answered both with an empty list would have moved the
+  bug rather than fixed it, one layer down and out of sight of the screen
+  that used to hold the check. `OlderPage::Events(vec![])` means the start
+  of the conversation; `OlderPage::NothingLoaded` is not an answer about
+  the conversation at all. Reviewed 2026-09-06.
+  `paging_before_the_first_event_makes_no_request_at_all` asserts zero
+  transport calls, not just the variant, since a request that happens to
+  answer empty is exactly what caused the original bug, and
+  `a_failing_server_page_is_an_error_rather_than_an_empty_one` plus
+  `an_unreadable_cached_page_is_a_parse_error_rather_than_an_empty_one`
+  are the same rule for the two ways a page can fail.
+- **`fetch_transcript_lines`** (new in `api.rs`) hands back each line
+  paired with the exact server bytes it came from, via
+  `serde_json::value::RawValue` rather than re-serializing a parsed
+  `Value` -- the cache and a live SSE frame for the same event have to
+  agree byte-for-byte, which is exactly what the `serde_json`
+  float-rounding bug (AGENTS.md) was about. The existing
+  `fetch_transcript_page` is untouched (other callers under `iris/`
+  depend on its signature); the two share a `transcript_path` helper so
+  the query string is written in one place.
+
+**Not ported:** `EventStream.kt`'s reconnect-with-backoff loop, and
+`TranscriptSource.close`'s ability to cancel a live stream from another
+thread. Both are wall-clock/thread-lifetime policy that belongs to
+whichever runtime embeds this crate (iris's own timers, a Tokio task, a
+Kotlin coroutine scope), not to this pure logic -- `follow` is the same
+"write to the cache, then hand the frame to the caller" decorator
+`iris/desktop-app/src/app.rs` and `iris/android-app/src/transcript_client.rs`
+already hand-wrote around `event_stream::follow_session_events` before this
+existed; the cache write moved into one shared place so a third caller
+does not repeat it again by hand.
+
+## What is not started at all
+
+- **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`
+(109 tests), `cargo clippy --all-targets`, `cargo fmt` -- all clean as of
+this writing (2026-09-06).

docs/DECISIONS.md

@@ -0,0 +1,293 @@
+# 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
+
+- **iris no longer asks every device for compute-shader limits it never
+  uses.** `adapter.request_device` (both `iris/src/android/render.rs` and
+  `iris/src/default/render.rs`) used `Limits::default()` plus an override
+  for `max_buffer_size`, and `Limits::default()` unconditionally requests
+  desktop-tier compute limits (`max_compute_workgroups_per_dimension:
+  65535`, per `wgpu_types`) even though nothing in `iris`/`iris-core`
+  creates a `ComputePipeline` or writes a `@compute` shader stage —
+  confirmed by grepping the whole tree, not assumed. That crashed
+  `request_device` outright on the Android emulator's software GL path
+  (`EMU_GPU=software`, `--features force-gles`): SwiftShader's GL reports
+  itself as OpenGL ES 3.0, which has no compute shaders at all, so the
+  adapter's real limit is 0 against the unconditional request for 65535 —
+  `RUST.md`'s "Software mode ... crashes for a third, different reason,"
+  2026-09-05, earlier today. The same would happen on any real
+  GLES-3.0-only Android device, not just the emulator. Fixed by a new
+  `iris_core::device_limits()` (`iris/core/src/render/mod.rs`), shared by
+  both platform backends so the two requests cannot drift, that zeros the
+  six `max_compute_*` fields explicitly rather than switching to a
+  downlevel `Limits` preset — `Limits::downlevel_webgl2_defaults()` was
+  considered and rejected: it also zeros
+  `max_storage_buffers_per_shader_stage`, and `shader.wgsl`'s vertex stage
+  reads four `var<storage>` buffers (rects, glyphs, masks, move_offsets),
+  so that preset would trade the compute crash for a bind-group-layout
+  one on the same downlevel hardware this is meant to support. No
+  capability check or fallback path was needed since nothing is being
+  disabled — the request is simply narrowed to what the pipeline actually
+  uses. `rigs/gpu-probe`'s own mirrored limits (it is deliberately its own
+  crate, not a workspace member, so it cannot call `device_limits()`
+  directly) were updated to match, and confirm `IRIS DEVICE: ok` against
+  this VM's own Vulkan and GL adapters. **Not verified this pass**: the
+  specific SwiftShader-ES-3.0 crash this fixes, on-device — the
+  `EMU_GPU=software` cold boot this needs would have force-restarted this
+  checkout's emulator while another session was actively running its own
+  app on it (`com.example.aiapp` had window focus at the time), so it was
+  left for a pass when the emulator is free rather than disrupting that
+  session. Everything reachable without the emulator is clean: `cargo
+  fmt`/`clippy --workspace --all-targets`/`test --workspace`, `cargo ndk
+  build`/`clippy` for `iris-android-app` with `force-gles`, and
+  `gpu-probe` against this VM's own Vulkan and GL(ES 3.2, which still has
+  compute and so would not have reproduced the crash even before this
+  fix — not a substitute for the real ES-3.0 test).
+
+- **P0's Compose half is built and smoke-tested on the emulator** — the
+  `bench` build type, the shared `app/bench-fixture/` transcript, and an
+  in-process fake backend (`BenchFixture.kt`/`BenchNetwork.kt`) that
+  answers `TranscriptSource`/`EventStream` from an in-memory event log
+  instead of a real server, so the fold and paging under test are the real
+  ones. Full account, the smoke run's report, and what is deliberately
+  left (the iris half, the real on-phone runs) are in RUST.md's P0 box.
+  Not a decision to review so much as the gate itself now being runnable —
+  flagged here because it is the first half of something Iris explicitly
+  asked to see before P1.
+
+- **P0's iris half is also built and smoke-tested on the emulator,
+  2026-09-05.** A new `bench` Cargo feature on `iris-android-app`, on top
+  of `transcript-screen`: the same checked-in fixture (`include_str!`, no
+  asset pipeline needed), the same 24-swipe scroll loop animated through
+  `List::scroll` and the same 400-event/20s streaming phase through
+  `fold_event`, "Run benchmark"/"Copy report" as named accessible
+  controls, and the same three added report fields (process CPU time,
+  peak RSS, battery current) via direct JNI calls
+  (`bench_jni.rs::PlatformHandle`) since `android_view` has no
+  `BatteryManager`/`ClipboardManager` wrapper of its own. One small public
+  API addition to get there: `AndroidAppState::platform_ready` (`IRIS.md`),
+  a default-no-op lifecycle hook handing an implementor a `JavaVM` +
+  `GlobalRef` it can call Java through from any thread. Packaged with a
+  new `release` build type on `iris-android-app`'s own Gradle project
+  (there was previously only `debug`), signed with the same key
+  `app/build-apk.sh` generates. Smoke run and the full report are in
+  RUST.md's P0 box; not attempted this pass: the real on-phone runs and
+  Iris's pass/fail call, which is the actual gate.
+
+- **The intermittent touch-scroll dropout is root-caused and fixed: a
+  missed `ACTION_DOWN` hit-test, not the previously-suspected coalesced
+  first `ACTION_MOVE`.** Diagnosed by temporary logcat tracing of every
+  touch event, `DragArbiter` state transition and `Selection::drag`
+  dispatch (removed once confirmed), reproduced on this checkout's own
+  emulator against a real sandbox session. The trace showed the actual
+  mechanism: a gesture's `ACTION_DOWN` lands wherever the finger actually
+  is, which is not guaranteed to fall inside the same row-local sensor
+  region a later `ACTION_MOVE` in the same gesture lands in (a row's own
+  padding/gap, or its non-selectable sender-name header, is
+  pointer-transparent to `iris::sense::CursorSense`). When that happens,
+  the widget that ends up handling the gesture never saw `PressStart`, so
+  `DragArbiter` sits in `Idle` — which answers every subsequent frame with
+  `Undecided` and has no way to tell "no press is happening" from "a press
+  is happening but I missed its start," so it never recovers on its own
+  for the rest of that gesture. One real trace showed exactly this: touch
+  `Down`/`Move`/`Up` all delivered correctly, but zero `PressStart`
+  reaching the arbiter, `state=Idle` unchanged from first frame to last.
+  Fixed at the call site that has the context to recover
+  (`iris::transcript_ui::selection::Selection::drag`,
+  `iris/transcript-ui/src/selection.rs`): a new `DragArbiter::is_idle()`
+  (`iris/src/sense.rs`) lets it notice a `Pressing` frame arriving with the
+  arbiter still `Idle` — which can only mean a missed `PressStart`, since a
+  `Pressing` sense requires the button to genuinely be down — and start the
+  press there instead of where it was missed. Three new unit tests in
+  `sense.rs`'s `drag_arbiter_tests` and one in `transcript-ui`'s
+  `selection::tests` (the latter fails on the code before this fix).
+  Commit follows. Not the same failure the earlier pass's `DECISIONS.md`
+  DEFERRED item speculated about (a coalesced first `ACTION_MOVE` skipping
+  slop detection) — that hypothesis is now ruled out; the arbiter's own
+  slop/long-press logic was never wrong. RUST.md's I5 box,
+  "Touch-scroll dropout root-caused, 2026-09-05" has the full trace.
+- **P0, a phone benchmark gate before any porting, asked for by Iris
+  2026-09-05**: "before P1 I'd like to see benchmarks & also maybe stress
+  test on my own phone ... If it doesn't match compose reasonably well then
+  I don't think I'd wanna continue." Design (RUST.md's P0 box has the
+  detail): the same embedded synthetic fixture in both apps with no server
+  needed; the same scripted scroll loop then a streaming phase, run
+  programmatically since the phone has no usable system tracing and no
+  agent can drive it; the same report from both (frames, janky %, p50/p90/
+  p99, process CPU time, peak RSS, battery current where readable) with a
+  copy button; the iris app under its own id and the Compose one as a new
+  `bench` build type with an id suffix, so neither replaces her production
+  install; two arm64 APKs plus instructions delivered under `~/host/bench/`.
+  The gate is hers: iris within a reasonable margin of Compose release on
+  p50, p99 and CPU time, no crashes, no visible stutter. If it fails, the
+  port stops.
+- **The rest of the port is one UI crate, `iris/app-ui`, grown out of
+  `iris/transcript-ui` rather than started beside it.** It holds a
+  `Screen` enum plus a back stack — the Rust equivalent of `AppRoot.kt`'s
+  `when` — and `iris/desktop-app`/`iris/android-app` become thin entry
+  points over it. Chosen over a fresh crate because `transcript-ui`
+  already has the right generic shape (`Rsc: HasEvents` +
+  `Rsc::State: FocusHost`) and the `client-core`/`event-model` path
+  dependencies every later screen needs, so growing it in place is the
+  smaller diff. Platform-only code (notification service, share target,
+  QR scanner, Keystore token, deep-link enrolment) stays in the E3/E5
+  Java shell (`android-shell/` + `app/shellApp`) rather than moving into
+  this crate, since none of it is a screen. The Android APK is built by
+  `cargo xtask apk` (E5), merging the app-ui cdylib into the E3 shell so
+  there is one app rather than a demo shell plus a service shell.
+  `app/androidApp` (the Compose app) stays untouched and is the baseline
+  every step is measured against, until parity is reached (P7 decides
+  the switch, and is itself a load-bearing decision left to Iris). Order
+  is by risk to the daily-use path: session screen first (P1, where
+  every hard behaviour already lives), then the shell merge and a real
+  phone install (P2), then root tabs (P3), the explorer (P4),
+  settings/enrolment (P5), desktop parity (P6), and the cutover itself
+  (P7). Full plan: RUST.md's "The port, in order (decided 2026-09-05)".
+- **iris gets its own measured frame report, rather than waiting on a
+  `dumpsys`/`gfxinfo` answer that cannot see a `SurfaceView`'s GPU-drawn
+  frames.** `iris_core::FrameReport` (`iris/core/src/render/frame_report.rs`)
+  times each frame's wall clock from the same point `render()`'s redraw
+  starts to just after `queue.submit` + `present()` — the span Compose's
+  own render report and `gfxinfo` both count — into a fixed 4096-entry
+  ring (no allocation per frame; `report()` is the only place that
+  allocates, and only on a button tap). The report gives total frames,
+  janky % over the same 16.7ms budget `gfxinfo` uses, P50/P90/P99 and the
+  worst, plus a reset. Exposed the way the Compose app's copy-button
+  report already is: two named controls ("Frame report", "Reset frame
+  report") on the transcript screen, tappable by accessibility name via
+  `ui-trace`, logging under this crate's fixed `android_logger` tag
+  (`iris-android-app`) so a script can grep `"iris frame report"` the way
+  `transcript-bench.sh` greps `"ai-app render report"`. The report's own
+  `Display` line says plainly that it measures up to the `present()` call
+  returning, not GPU/compositor completion — wgpu's `present()` is not
+  fenced against either, so presenting that span as "time to reach the
+  screen" would be a measured-looking number that is actually inferred,
+  which the standing UI rule forbids.
+- **`ui-trace` gains a hold-then-drag gesture, additive, in
+  `emulator-tools`.** Neither of its two existing actions can produce
+  "hold stationary for `LONG_PRESS`, then move without lifting" — `tap`
+  has no hold and `swipe X1 Y1 X2 Y2 MS` interpolates motion across its
+  whole duration from t=0. A new action presses, waits, then moves to a
+  second point and releases as one continuous touch (raw
+  `sendevent`/`MotionEvent` injection, extending whatever mechanism the
+  existing `swipe` already uses), so `DragArbiter`'s pan-vs-select rule
+  (`iris/src/sense.rs`, already covered by 8 unit tests against a
+  synthetic clock) can finally be driven on a real device instead of only
+  in a test harness.
+- **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.
+- **I5's Android integration extends `iris-android-app` (I2's shell)
+  behind a Cargo feature (`transcript-screen`), rather than a third
+  shell crate.** That project already has the Gradle module, the
+  `IrisView`/`MainActivity` Java, and the JNI registration; the only
+  thing a second screen needs on top is a different `AndroidAppState`,
+  the same axis `tabs_ui::build`/`transcript_ui::build` already vary
+  along on the winit side. `tabs-screen`/`transcript-screen` are
+  mutually exclusive and each pulls in only its own deps, so the plain
+  tabs build (I2/I4) is untouched.
+- **Order of remaining work, updated 2026-09-05**: the two in-flight
+  pieces and I5's Android integration are all done; next is giving iris
+  its own frame-timing report so item 3 below can be decided by a number.
+- **DECIDED by Iris, 2026-09-05: iris is the app's framework; Masonry was
+  the calibration.** Her words: "I think iris definitely makes more sense
+  based on the limitations we've found." The limitations: Masonry has no
+  touch scroll on Android (E2), no per-span rich text and no cross-row
+  selection on the pinned commit (E2), and its keyboard bridge is a TODO
+  (E1); iris carries the same screen under the Compose baseline on the
+  host GPU (p50 15.0 ms against Compose's 20.0 ms, RUST.md's I5 box). What
+  follows: the E-steps are closed as calibration, and the port proceeds
+  on iris — screens, the shell (E3/E5), and `client-core` underneath.
+  The item below is kept as the record of what she decided from.
+- **Was DEFERRED — whether to commit to iris over Masonry for `ai-app`.**
+  Updated 2026-09-05 with the clean comparison the recommendation wanted:
+  same sandbox session content, same emulator, `EMU_GPU=software`, one
+  session. Headline numbers (RUST.md's I5 box, "Clean scroll comparison,
+  2026-09-05," has the full table and every caveat):
+
+  | app | build | frames | janky % | p50 | p90 | p99 | worst |
+  |---|---|---|---|---|---|---|---|
+  | Compose (in-app report) | debug | 1102 | 99.0% late | 33.8ms | 50.6ms | 79.5ms | -- |
+  | Compose (`dumpsys gfxinfo`) | debug | 1499 | 21.15% (95.66% legacy) | 32ms | 48ms | 150ms (p99) | -- |
+  | iris (`FrameReport`) | **release** | 299 | 94.65% | 79.1ms | 98.6ms | 117.8ms | 212.6ms |
+  | iris (`FrameReport`, repeat) | **release** | 233 | 94.42% | 109.3ms | 130.8ms | 147.1ms | 150.5ms |
+
+  **Not a clean apples-to-apples reading, stated plainly rather than
+  smoothed over**: iris had to be built **release** (debug `SIGSEGV`s on
+  this emulator's Vulkan loader, I4's finding) against Compose's mandated
+  **debug** build, so this asymmetry likely *understates* iris's gap
+  rather than the reverse; the three frame-time sources measure different
+  things (Compose's own phase accounting vs. Android's HWUI deadline-miss
+  definition vs. iris's redraw-start-to-present window, the last of which
+  `dumpsys gfxinfo` cannot see at all for iris's `SurfaceView`); and both
+  figures are emulator numbers under software rasterisation, which
+  Compose's *own* in-app report shows already costs 20-34ms/frame in
+  `swap`+`gpu` alone under this GPU mode, so a same-mode iris number well
+  above 16.7ms was expected going in for either app. A second pair under
+  `-gpu host` was not taken this pass. The earlier session's suspected
+  intermittent touch-delivery dropout was **not reproduced** this pass —
+  the zero-frame results this time traced to this pass's own script bug
+  (a `cd` that changed which emulator `ui-trace` targeted), not the
+  emulator; a CPU-load rise during the gesture was observed by a sampler
+  running throughout, but did not correlate with any failure, so the
+  original candidate is neither confirmed nor ruled out.
+  The choice in front of Iris, updated: decide now on the
+  structural-plus-functional case already made (iris works end-to-end
+  where Masonry's scroll gesture doesn't exist at all on Android) plus
+  this table — reading the two build profiles and three jank definitions
+  with the caveats above rather than as a single number — or ask for a
+  same-profile, same-GPU-mode rerun first. RUST.md's I5 box has the full
+  account.
+
+  **Updated 2026-09-05, the `-gpu host` pair taken.** Real GPU rendering
+  (`force-gles` -- the default Vulkan backend has no adapter at all under
+  plain host-GPU boot, confirmed by the exact `wgpu` error) reverses the
+  software-mode shape:
+
+  | app | build | GPU mode | frames | janky % | p50 | p90 | p99 | worst | cpu p50 | gpu-wait p50 |
+  |---|---|---|---|---|---|---|---|---|---|---|
+  | Compose (in-app report) | debug | host (virgl) | 1268 | 96.4% late | 20.0ms | 28.4ms | 37.7ms | -- | -- | -- |
+  | iris (`FrameReport`), **best of three, 2026-09-05** | release, `force-gles` | host (virgl) | 439 | 46.24% | 15.7ms | 23.3ms | 31.2ms | 57.4ms | 1.2ms | 13.2ms |
+
+  Under real GPU rendering iris's median frame is *faster* than
+  Compose's, not the 2-3x-slower shape the software-mode table shows. A
+  new split inside `FrameReport` (redraw-to-submit vs. submit-to-present,
+  commit `e2a1fad`) says why: iris's own CPU work per frame is a median
+  ~1ms -- almost the entire frame is time spent handing the frame to the
+  driver, not in iris's layout/text/primitive code. This is consistent
+  with the earlier software-mode gap being mostly SwiftShader's CPU
+  rasterisation cost rather than an iris-specific slowness. **Still not
+  proof, and now closed as unanswerable rather than merely untaken**: a
+  same-mode software `force-gles` run to isolate the backend was retried
+  2026-09-05 after fixing the compute-limit crash the first attempt hit,
+  and hit a second, structural wall instead — SwiftShader's ES 3.0 GL
+  path has no storage-buffer capacity at all, and `shader.wgsl` reads
+  `var<storage>` buffers unconditionally, so reaching that path needs a
+  shader rewrite, not a limits fix (RUST.md's I5 box, "The three
+  remaining I5 verifications, closed 2026-09-05," item 2). The
+  intermittent touch-scroll dropout this pass also reproduced is
+  root-caused and fixed as of the same date (a missed `ACTION_DOWN` on a
+  row's padding/header left `DragArbiter` stuck in `Idle`); three clean
+  `iris-scroll.sh` runs post-fix each scrolled all 24/24 swipes, replacing
+  the single-attempt 62-frame reading this table used to carry. RUST.md's
+  I5 box, "Where iris's frame time goes, 2026-09-05, the `-gpu host`
+  pass," and "The three remaining I5 verifications, closed 2026-09-05,"
+  have the full account. The iris-vs-Masonry choice itself is still
+  Iris's to make.

docs/IRIS.md

@@ -0,0 +1,682 @@
+# 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-06: `List::anchor_position_display`, `FrameReport::mark_phase`/`phase_stats`/`late_at_hz` (RUST.md's "Benchmark v2")
+
+`List` gained `anchor_position_display(&self) -> String`, reporting the
+anchor's own row index and pixel offset (`idx=N/off=Mpx`, or
+`idx=more-before`/`idx=more-after`/`idx=none`) -- what a scripted
+benchmark reads to report fling travel. Note the anchor does not
+necessarily change *slot* over a long scroll (this widget's own documented
+design: the anchor is a stable identity, not re-derived from what's on
+screen each frame), so this is not the same measurement as a Compose
+`LazyListState.firstVisibleItemIndex`, which does track the true topmost
+visible row -- the `off` half is what actually reflects how far a fling
+travelled.
+
+`iris_core::render::frame_report::FrameReport` gained three methods for
+per-phase benchmark reporting: `mark_phase(name)` records a named phase
+boundary at the current frame/instant; `phase_stats(now, refresh_hz)`
+returns one `PhaseStats` (frames, wall duration, late count/percent,
+p50/p90/p99, worst) per marked phase, sliced from the existing ring by a
+new parallel `index_ring`; `late_at_hz(refresh_hz)` gives the whole run's
+late count/percent judged against an arbitrary refresh rate rather than
+the fixed 60Hz `JANK_THRESHOLD` every existing caller still uses (a
+separate method, not a parameter on `report()`, so nothing else changes
+behaviour). `RING_CAPACITY` grew 4096->16384 to hold a full multi-phase
+run without evicting earlier phases' samples.
+
+## 2026-09-06: `List::fling`, `VelocityTracker`, `FlingCalculator` (IRIS_TODO.md's "swiping has no momentum")
+
+`iris::widget::List` gained a real fling: `fling(velocity_px_per_s)` starts
+one (cancelled by the next touch-down via `cancel_fling`, or automatically
+once it settles or reaches loaded content's start/end), `is_scrolling()`
+reports whether one is running, and `tick_fling(now: Instant) -> bool`
+advances it and returns whether it is still going -- a caller that owns a
+`RequestRedraw` handle can hand it to the list once via the new
+`set_redraw_handle`, after which `List` re-arms its own next frame while
+flinging with no further polling needed; a caller driving a scripted
+benchmark instead calls `tick_fling` itself in a loop, same as it already
+drives `scroll`.
+
+The physics is `iris::sense::FlingCalculator` + `VelocityTracker`
+(`sense.rs`, beside `DragArbiter`): a port of AOSP `SplineOverScroller`'s
+deceleration curve (the same one Compose's own `ScrollableDefaults.
+flingBehavior()` uses), cited at the definition, so a fling here travels
+the same distance a Compose `LazyColumn` would for the same initial
+velocity. `VelocityTracker` estimates that velocity from the drag's last
+~100ms of samples rather than one frame's last delta. Unit-tested:
+velocity from known samples, fling distance/duration against the closed-
+form spline result (within 1%), cancel-on-touch, and the start/end clamp
+(a fling stops rather than scrolling into content that was never loaded).
+
+Before: a touch-drag panned exactly as far as the finger moved and stopped
+dead on release. After: releasing mid-drag continues scrolling and
+decelerates, matching the muscle memory every other Android scroll view
+already trained. `transcript_ui::selection::Selection::drag` wires this in
+-- a release only flings if the gesture had committed to panning
+(`DragArbiter::is_panning`, new), never a selection or an undecided tap.
+
+## 2026-09-06: `UiRenderNode::new` returns `Result`, not `Self` (RUST.md's P0 box, phone-crash fix)
+
+`iris_core::UiRenderNode::new(device, queue, config)` now returns
+`Result<Self, String>` instead of `Self`. Why: it used to let a bind-group-
+layout validation failure reach wgpu's default error handler, which panics
+with no way for a caller to intervene -- exactly what aborted the P0 bench
+APK on Iris's phone with the crash report truncated to "wgpu error:
+Validation Error" and nothing else recoverable. It now runs its creation
+calls inside wgpu error scopes and returns the full error text (wgpu's own
+"Caused by" chain) as `Err` instead.
+
+Both callers changed to match: `android::render::AndroidRenderer::new`
+itself now returns `Result<Self, String>` too, building a fuller report
+(adapter identity, the limits/downlevel flags a layout validates against,
+then wgpu's text) on failure -- its caller,
+`android::view::IrisViewPeer::surface_changed`, logs that report as one
+logcat line and shows it on screen (a new `IrisView.showRendererError`,
+called via an ordinary JNI method call rather than a new `native fn`)
+instead of letting the process abort. `default::render::UiRenderer::new`
+(the winit/desktop backend) still panics on failure -- there is no
+on-screen fallback there -- but the panic message is now the same full
+text rather than whatever wgpu's own handler would have printed.
+
+No change for an app that never constructs a `UiRenderNode` directly (every
+current one goes through `AndroidRenderer`/`UiRenderer`), but anyone who
+does needs an `?`/`.expect()`/`match` at the call site now. Full audit and
+the named hypothesis for what actually failed on the phone are in
+RUST.md's P0 box, "iris bench crash on the phone, 2026-09-06."
+
+## 2026-09-05: `AndroidAppState::platform_ready` (RUST.md's P0 box, iris half)
+
+Added a second, optional lifecycle method to `iris::android::AndroidAppState`
+(`iris/src/android/view.rs`), called once from `new_peer` right after `new`:
+
+```rust
+fn platform_ready(&mut self, rsc: &mut AndroidRsc<Self>, vm: JavaVM, view: GlobalRef) {}
+```
+
+Default does nothing, so every existing implementor (`Client`,
+`TranscriptClient`) is unaffected. It exists for a caller that needs to call
+into Java itself beyond what a `RequestRedraw` handle already covers --
+P0's bench build (`iris-android-app`'s new `bench` feature,
+`bench_client.rs`/`bench_jni.rs`) uses it to hold a `JavaVM` + `GlobalRef`
+to the view so its "Copy report" control and once-a-second battery sampler
+can call `BatteryManager`/`ClipboardManager` through the view's own
+`Context`, from a background tokio task as well as the UI thread. `new`
+itself was not extended with these two parameters: most implementors need
+nothing here, and `new`'s job is building the widget tree, not holding a
+platform handle. `vm`/`view` are independent handles from the ones
+`new_peer` keeps for its own `RequestRedraw` (a fresh `get_java_vm`/
+`new_global_ref` each), so storing them has no effect on that mechanism.
+
+## 2026-09-05 (later still): `iris_core::device_limits()`, and iris no longer requests compute-shader limits
+
+New public function, `iris_core::device_limits() -> wgpu::Limits`. Why:
+`adapter.request_device`'s `required_limits` was `Limits::default()` plus
+a `max_buffer_size` override in both platform backends, and
+`Limits::default()` requests desktop-tier compute-shader limits
+unconditionally (`max_compute_workgroups_per_dimension: 65535`) even
+though nothing in `iris`/`iris-core` uses a `ComputePipeline` — that
+crashed device creation outright on a downlevel GL adapter reporting
+OpenGL ES 3.0 (no compute shaders at all: the Android emulator's
+`EMU_GPU=software` path, and any real GLES-3.0-only Android device).
+`device_limits()` is what both `android::render::AndroidRenderer::new`
+and `default::render::UiRenderer::new` now build their `required_limits`
+from, so the request cannot drift between the two backends.
+
+Before: `Limits { max_buffer_size: 1 << 30, ..Default::default() }`
+inlined in each backend. After: `iris_core::device_limits()`, which is
+the same thing with the six `max_compute_*` fields additionally zeroed.
+A caller building its own `DeviceDescriptor` outside these two backends
+(there are none today, but a third platform backend would want this)
+should call `device_limits()` rather than reaching for
+`Limits::default()` directly, unless it genuinely adds a compute pass —
+in which case it wants the specific compute limits that pass needs, not
+the desktop-tier default for everything.
+
+## 2026-09-05 (later the same day): `iris_core::FrameReport` (RUST.md's I5 box)
+
+New public type, `iris_core::FrameReport` (re-exported from `iris_core`'s
+`render` module alongside `FrameStats` and `JANK_THRESHOLD`). Why: `dumpsys
+gfxinfo` cannot see a `SurfaceView`'s own GPU-drawn frames at all, so a
+`wgpu`-rendered iris screen had no way to ask "was this smooth" the way
+Compose's own in-app render report already can -- item 3 of RUST.md's
+recommendation was stuck on a one-sided number for exactly this reason.
+
+`FrameReport::record(elapsed: Duration)` is called once per frame (wired
+into `android/view.rs`'s `render()`, wrapping the same span from redraw
+start to after `queue.submit`+`present()` that Compose's report and
+`gfxinfo` both count) and writes into a fixed 4096-entry ring -- no
+allocation on the hot path. `FrameReport::report() -> Option<FrameStats>`
+gives total frames, janky % (over `JANK_THRESHOLD`, the same 16.7ms 60Hz
+budget `gfxinfo` uses), P50/P90/P99 and the worst; `None` if nothing has
+been recorded since the last `reset()`, not a zeroed report that would
+read as a real measurement. `FrameStats`'s `Display` line says plainly
+that it measures up to `present()` being called, not GPU/compositor
+completion, since wgpu's `present()` isn't fenced against either.
+
+`AndroidUiState` gained a `pub frame_report: FrameReport` field --
+anything with `HasAndroidUiState` can now read or reset it. Before this,
+there was no way to ask iris's own render path how long a frame took at
+all, on any backend.
+
+Before/after, for a caller that already has `ui_state: &AndroidUiState`:
+
+```rust
+// before: no such question could be asked
+// after:
+match ui_state.frame_report.report() {
+    Some(stats) => log::info!("iris frame report: {stats}"),
+    None => log::info!("iris frame report: no frames recorded yet"),
+}
+ui_state.frame_report.reset(); // via android_state_mut()
+```
+
+`iris-android-app`'s transcript screen exposes this as two named,
+tappable controls ("Frame report", "Reset frame report") rather than
+requiring a caller to wire its own UI -- see `transcript_client.rs`'s
+`frame_report_controls`.
+
+## 2026-09-05: `Tasks::redraw_handle` (RUST.md's I5 Android integration)
+
+New public method on `iris::task::Tasks`, `redraw_handle(&self) ->
+Arc<dyn RequestRedraw>`. Why: a caller running its own long-lived loop
+*inside* one spawned task (a live SSE follow, the Android transcript
+client's `select_session`) has no other way to ask for a frame after each
+`TaskCtx::update` -- `Tasks::spawn`'s own wrapper only requests one, after
+the whole async closure finishes, which fits a single request-then-update
+but not a stream that needs to be seen redrawing after *each* event. This
+is the same gap `iris/desktop-app`'s module doc names for why it uses
+winit's `Proxy<AppEvent>` instead of `Tasks` -- android-view has no
+`Proxy`, so this is what closes it there.
+
+**A real bug this uncovered, not a hypothetical**: calling the returned
+handle's `request_redraw()` from the background thread crashed the process
+(`SIGABRT`, `Result::unwrap() on an Err value: JavaException`) the first
+time an Android transcript fetch called it a second time. `android/render.rs`'s
+`AndroidRedrawHandle` was already attaching the calling thread to the JVM
+correctly, but its `request_redraw` called `View::post_frame_callback`,
+whose Java side calls `Choreographer.getInstance()` -- which throws unless
+the *calling* thread already has a `Looper`, and a tokio worker thread,
+even freshly JNI-attached, has none. Fixed by routing through
+`View::post_delayed(0)` instead (Android's own thread-safe "queue work onto
+this View's UI thread" primitive, needing no caller-side `Looper`), landing
+on a new `IrisViewPeer::delayed_callback` override that drains tasks and
+renders -- same body as `do_frame`, on the UI thread where
+`post_frame_callback` is safe again. Any future caller of `redraw_handle()`
+from a background thread gets this for free; nothing about the fix is
+specific to the transcript screen.
+
+## 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, later: `DragArbiter::is_idle()`, recovering a missed `press_start`
+
+Follow-up to the above, from a real touch-scroll dropout: a gesture's
+`ACTION_DOWN` can land on a caller's own dead space (a row's padding, a
+gap, a header with no handler) that never calls `press_start`, so the
+first frame the arbiter actually sees is a `Pressing`-shaped `update`
+with no matching start. Before this, `update`'s `Idle` arm had no way to
+tell that apart from "nothing is happening" and answered `Undecided`
+forever for the rest of that gesture. `is_idle(&self) -> bool` lets a
+caller notice the gap and recover: if `is_idle()` is true on a frame the
+caller knows a press is genuinely down (its own `Pressing`/equivalent
+sense fired), call `press_start` right there instead of assuming one
+already happened. `transcript-ui`'s `Selection::drag` is the reference
+caller — one new match arm, checked before the ordinary `update`-only
+case. Any other `DragArbiter` caller with the same "one sensor per
+sub-region, no fallback for dead space" shape has the same gap and wants
+the same recovery.
+
+## 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.
+
+## 2026-09-05: `FrameReport` splits each frame at `queue.submit`
+
+`FrameStats` gains two fields, and `FrameReport` gains a second recording
+method, to answer "is a slow frame iris's own CPU work or the driver/GPU"
+with a number instead of a guess (RUST.md's I5 box).
+
+- **`FrameReport::record_split(total, submit_to_present)`** is a second way
+  to record a frame, alongside the existing `record(total)` (unchanged,
+  and still what a caller with no split should use — it now reads as
+  `cpu_p50 == total`, `gpu_wait_p50 == 0`, rather than fabricating a
+  number for a half it never measured).
+- **`FrameStats` gains `cpu_p50` and `gpu_wait_p50`**: medians of
+  redraw-start-to-submit and submit-to-after-`present()` respectively,
+  independent of each other and of the existing `p50`/`p90`/`p99`/`worst`
+  (which are unchanged, and still over the whole frame). The Android
+  renderer's `draw()` now returns the `submit_to_present` `Duration` it
+  measured, which `android::view::render()` passes to `record_split`.
+- **Caveat carried in both doc comments**: `submit_to_present` is not
+  fenced against the GPU actually finishing — it is "how long the CPU was
+  blocked handing the frame to the driver," not a confirmed GPU-completion
+  time. Enough to separate "iris is slow building the frame" from "iris is
+  slow handing it off," not enough to claim an exact GPU budget.
+
+## 2026-09-05: `List::replace_back`/`List::clear`, and `TranscriptScreen::apply`
+
+Fixes the "every client refolds and rebuilds the whole widget tree per
+streamed event" cost RUST.md's P0 box measured (20 events/second against a
+~3,200-row transcript). Two small additions to `iris::widget::List`
+(`iris/src/widget/list.rs`), plus one new method on `transcript-ui`'s
+`TranscriptScreen`.
+
+- **`List::replace_back(row: ListRow) -> Option<ListRow>`**: swaps the
+  *last* row's widget for a new one without moving it — same slot index,
+  so an anchor already pinned there (in particular a list flush with its
+  own end) stays pinned, and a `List` scrolled elsewhere is untouched.
+  `None` if the list is empty. `RowKey` may differ between the old and new
+  row; only `heights`/`extents` care, and both are invalidated for the
+  evicted key the same way `pop_back` already does.
+- **`List::clear()`**: drops every loaded row and resets to `List::new`'s
+  state (`more_before`/`more_after` untouched — a caller that wants those
+  cleared too calls `set_more_before(None)`/`set_more_after(None)` itself).
+  The fallback path for a change that touches more than the tail.
+- **`transcript_ui::TranscriptScreen::apply(&self, rsc, old: &[TranscriptItem], new: &[TranscriptItem])`**:
+  the incremental alternative to rebuilding the whole screen from
+  `transcript_ui::build_tree` on every folded event. Diffs the two
+  `group_tool_runs` outputs and picks the cheapest update: nothing changed
+  (no-op), a pure append (`push_row`, unchanged cost), or — the common
+  streaming case, a delta into a still-open assistant message — a rebuild
+  of just the one changed row via `List::replace_back`, with any further
+  new rows appended after it. A row changing *before* the tail (only
+  `group_tool_runs` retroactively grouping tool calls into a run does
+  this) falls back to `List::clear` plus a full rebuild, counted in
+  `TranscriptScreen::take_rebuilds()`. `bench_client.rs`, `transcript_client.rs`
+  and `desktop-app/app.rs` all call this now instead of rebuilding on every
+  event; only the opening page (and `apply`'s own fallback) still calls
+  `build_tree`.
+- **`TextEditCtx::set_with_spans(text, spans)`**: `set()` plus a fresh
+  `Vec<SpanStyle>` in one call, needed because a streamed row's markdown
+  re-renders to both a new string and a new span list on every delta and
+  the two have to land together — a stale span list drawn against new
+  text can point past its end. `set()` itself is unchanged (still clears
+  spans to none, as before).
+
+Measured on this checkout's emulator (`iris/android-app/run-bench.sh`,
+release, x86_64, `force-gles`): worst-frame and p99 during the streaming
+phase dropped from 369.3ms/284.5ms (full rebuild per event, prior pass) to
+~101–130ms/~76–103ms across three runs (this fix) — see RUST.md's P0 box
+for the full numbers and the comparison's caveats (different AVD
+instances, not a controlled A/B on identical hardware state).
+
+## 2026-09-06: bundled fonts, `content_scale`, `AndroidAppState::on_insets_changed`
+
+From RUST.md's P0 box, working Iris's first real-phone report (font/scale/
+inset bugs the emulator never showed).
+
+- **`TextData` now bundles Noto Sans + Noto Sans Mono** (regular/bold/
+  italic/bold-italic static faces, OFL) and registers them ahead of the
+  platform's own fonts in the `SansSerif`/`Monospace` generic-family
+  lists, rather than relying on the platform's font enumeration alone.
+  `TextData::font_diagnostics() -> FontDiagnostics` reports what was found
+  and what each style axis resolved to — logged once at startup and shown
+  on a screen's Diagnostics page if it has one. Adds ~3.6 MB uncompressed
+  to any binary linking `iris-core`; `build-apk.sh`'s own output says the
+  delivered (compressed) number.
+- **`UiRenderNode::new`/`resize` now take the window size explicitly**
+  (`window_size: impl Into<Vec2>`) instead of deriving it from the
+  surface's physical `SurfaceConfiguration`. Existing callers pass a
+  *logical* size (physical ÷ density/scale-factor) now; this is what makes
+  a `font_size: 16.0` 16 dp instead of 16 raw device pixels on a
+  high-density phone. Before this, `scale_factor` did not exist anywhere
+  in the crate, on either platform.
+- **`AndroidUiState::content_scale: f32`** (`DisplayMetrics.density`, read
+  once in `new_peer`) and the desktop equivalent (`window.scale_factor()`)
+  now divide every physical-pixel number before it reaches layout or
+  touch handling — see `content_scale`'s own field doc for the full list
+  of what depends on it.
+- **New: `AndroidAppState::on_insets_changed(&mut self, rsc, LogicalInsets)`**,
+  a default-no-op hook called from `render()` exactly when
+  `AndroidUiState::insets()` changes. Nothing previously consumed
+  `insets().top` at all; a screen with chrome under the status bar
+  implements this to pad it, in the same logical units `content_scale`
+  converts everything else to.
+- **New: `iris_core::WgpuErrorLog`**, installed via `Device::
+  on_uncaptured_error` on the Android device (wgpu's default handler is an
+  unconditional panic outside `UiRenderNode::new`'s own error scopes).
+  Explicit `Arc`-backed value passed to the callback and kept on
+  `AndroidRenderer`, not a global — a caller wanting one on desktop builds
+  its own the same way.
+
+## 2026-09-06: `Len::dp`, physical pixels throughout, the keyboard glyph wipe
+
+Iris's phone report on build a9232ac (screenshots): text now the right
+size but blurry; the keyboard still wipes every glyph; the header buttons
+have nothing behind them. All three are fixed; this entry is the public
+API side. docs/LAYOUT.md has the layout-side writeup, docs/RUST.md's P0
+box has the full investigation and the phone verification still to do.
+
+- **The keyboard wipe was `surface_changed` rebuilding the whole renderer
+  on every resize**, including an IME-driven one — a fresh, empty glyph
+  atlas while the CPU-side glyph cache kept UV coordinates from the old
+  one. `surface_changed` now calls `AndroidRenderer::resize` (reconfigures
+  the surface and window uniform only) when a renderer is already live,
+  and only builds a new one when there genuinely isn't one yet.
+- **`Len` has a third field, `dp`** (Android's dp / CSS's reference pixel,
+  1/160in), beside the existing `abs` (now explicitly *physical* pixels)
+  and `rel`/`rest`. `len_fns::dp`/`Len::dp` construct one, used exactly
+  like `abs`/`rel`/`rest` — `dp(16)` instead of a bare `16` wherever a
+  size should look the same physical size on any density. This is the
+  unit IRIS_TODO.md's "density-independent length unit" item asked for;
+  it replaces the previous stopgap (the whole rendered scene divided by
+  `content_scale` then implicitly stretched back up), which is also what
+  made text blurry — a glyph rasterised at the small, pre-stretch size and
+  then upscaled onto the real framebuffer.
+- **`UiRenderState`/`Painter` gained `density()`/`set_density()`** (physical
+  pixels per dp). Every place a length resolves (`Len::apply_rest`,
+  `Size::to_uivec2`) now takes it; `Span::gap` and `Padding`'s four sides
+  moved from a bare `f32` to `Len` so they take `dp(...)` too. A bare
+  number anywhere is unaffected — still `abs`, physical pixels.
+- **Text is rasterised at physical resolution now.** `TextBuffer::shape`
+  takes `density` and multiplies `font_size`/`line_height` (and any span
+  override) by it before handing them to parley, so the atlas holds a
+  bitmap at the size it is actually shown at rather than a low-resolution
+  one stretched afterward.
+- **Everything at the Android boundary is physical pixels now** — window
+  size, touch coordinates, insets (`LogicalInsets` renamed
+  `WindowInsets`). The previous "logical" division by `content_scale` is
+  gone; `content_scale` now feeds `set_density` instead.
+- Not yet verified on Iris's actual phone (this pass had no device) —
+  built and checked on this checkout's emulator only. RUST.md's P0 box
+  says what she should check for: crisp text at two densities, the
+  keyboard no longer wiping, and the header's background.
+
+## 2026-09-06: composing text, focus-on-tap, and atlas invalidation on a new renderer
+
+Three small but public API changes, from the same phone-report pass as the
+entry above (RUST.md's P0 box has the full account, including a real bug
+still not root-caused).
+
+- **`FocusHost` gained `is_focused(&self, id) -> bool`** (both platform
+  impls). `attr.rs`'s `Selector`/`Selectable` used to grant focus (and so
+  request the IME) on the very first frame of *any* press, before it was
+  known whether the gesture was a tap or a drag — a swipe over a text
+  field wrongly summoned the keyboard. They now wait for a completed tap
+  (press and release with no frame crossing `sense::DRAG_SLOP`) unless the
+  field is already focused, in which case dragging inside it to select
+  text is unchanged. `TextEdit` gained one new `pub(crate)` field
+  (`press_origin`) to track this; no public surface change there.
+- **`android::ime`'s `InputConnection` now calls `InputMethodManager::
+  updateSelection` after every edit** (`IrisViewPeer::update_ime_selection`,
+  called from `after_input`). Gboard was holding keystrokes back because
+  nothing ever told it where the app's own selection/composing region had
+  moved to — this is what android-view's own demo does in its `render()`
+  and this bridge never did.
+- **`GlyphAtlas::clear()` and `Textures::reset()`** (`iris_core`). Called
+  together, once, from `android::view`'s `surface_changed` exactly when a
+  *genuinely new* `AndroidRenderer` is built (backgrounding and returning,
+  not a keyboard-triggered resize, which already reuses the renderer) —
+  both CPU-side caches otherwise kept pointing at the old, now-destroyed
+  device's textures, which is why text used to vanish again after leaving
+  and returning to the app.

docs/IRIS_TODO.md

@@ -0,0 +1,545 @@
+# 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] **`request_device` asked for compute-shader limits it never uses
+  (2026-09-05).** `Limits::default()` (both `iris/src/android/render.rs`
+  and `iris/src/default/render.rs`) requests desktop-tier compute limits
+  unconditionally, even though nothing in `iris`/`iris-core` creates a
+  `ComputePipeline` or writes a `@compute` shader stage — confirmed by
+  grepping the whole tree, not assumed. That crashed device creation
+  outright on the Android emulator's software GL path (`EMU_GPU=software`,
+  `--features force-gles`): SwiftShader's GL reports itself as OpenGL ES
+  3.0, which has no compute shaders, so the adapter's real limit is 0
+  against the unconditional request for 65535 — the same would happen on
+  any real GLES-3.0-only Android device. Fixed by a new, shared
+  `iris_core::device_limits()` (`iris/core/src/render/mod.rs`) that zeros
+  exactly the six `max_compute_*` fields rather than switching to a
+  downlevel `Limits` preset — `downlevel_webgl2_defaults()` also zeros
+  `max_storage_buffers_per_shader_stage`, which `shader.wgsl`'s vertex
+  stage needs (four `var<storage>` buffers), so that preset would trade
+  this crash for a bind-group-layout one on the same hardware.
+  `rigs/gpu-probe`'s own hand-mirrored `Limits` (it is deliberately its
+  own crate, not able to call `device_limits()` directly) was updated to
+  match. See `DECISIONS.md` and RUST.md's I5 box for the account,
+  including what could not be re-verified on-device this pass (the
+  emulator was in concurrent use by another session).
+
+- [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.
+
+- [ ] **A read-only text display has no widget of its own — P0's bench
+  report area is a `TextEdit` standing in for one (2026-09-05).** The only
+  way to get selectable text on screen today is `.editable(...)` plus
+  `.attr::<Selectable>(())` (`Selectable` is only implemented for
+  `TextEdit`, `iris/src/attr.rs`), which also makes the field focusable —
+  tapping the bench report opens the soft keyboard over text nothing lets
+  you type into. Harmless for a bench-only debug screen (not fixed this
+  pass), but a real "selectable, not editable" text primitive would
+  remove the keyboard side effect and is worth having before another
+  screen wants the same thing (P1's own transcript rows already read
+  their content from a `TextEdit` for the same reason).
+
+## From the phone, 2026-09-06
+
+Found on Iris's own phone while working RUST.md's P0 box's phone-report
+follow-ups. Recorded here rather than fixed in that pass, so a follow-up
+agent takes them without colliding with that pass's `bench_client.rs`/
+`android/view.rs`/`android/sense.rs` changes.
+
+- [x] **Swiping has no momentum, fixed 2026-09-06.** `List::fling`/
+  `VelocityTracker`/`FlingCalculator` (`iris/src/widget/list.rs`,
+  `iris/src/sense.rs`) -- IRIS.md's 2026-09-06 entry has the full account.
+  Wired through `Selection::drag`'s release path, cancelled by the next
+  touch-down, clamped at the loaded content's start/end. Verified by unit
+  test (fling distance against the closed-form spline result, cancel-on-
+  touch, the clamp), not yet by an on-device or emulator feel-check --
+  that is still open.
+- [x] **Scrolling down sometimes jitters the text, fixed 2026-09-06.**
+  Root-caused by reading `DragArbiter::update`'s `Undecided`-to-`Panning`
+  transition rather than by an on-device trace (no emulator was used this
+  pass): it was the first named suspect, not the second. `self.last` stays
+  at the press origin for every `Undecided` frame (nothing pans while the
+  gesture might still be a selection), so the frame that finally crosses
+  `DRAG_SLOP` returned `Pan(dy)` with `dy` measured from `press_start` --
+  the *whole* pre-threshold drag, applied to the list in one step, however
+  many frames it had taken to get there. Fixed by applying only the
+  excess past `DRAG_SLOP` on that one frame (`dy - DRAG_SLOP.copysign
+  (dy)`), the same "consume the slop, don't replay it" rule Android's own
+  touch handling follows. New regression test,
+  `crossing_the_slop_by_a_little_pans_by_a_little` (`iris/src/sense.rs`).
+  **Not yet done**: an emulator trace of the real per-frame offset
+  confirming this was the whole story on real touch input rather than
+  only the arbiter's own unit tests -- worth a follow-up pass before
+  calling it fully closed.
+- [x] **Composing text held back until a space, caret not moving, fixed
+  2026-09-06.** `InputMethodManager.updateSelection` was never called --
+  see IRIS.md's 2026-09-06 entry and RUST.md's P0 box, item 1, for the
+  full account and the emulator evidence.
+- [x] **Swipe over the composer summons the keyboard, fixed 2026-09-06.**
+  `Selector`/`Selectable` now wait for a completed tap -- see IRIS.md's
+  2026-09-06 entry and RUST.md's P0 box, item 5. Verified via `dumpsys
+  input_method`'s `mInputShown` on the emulator, not yet on the phone.
+- [x] **Text disappears again after leaving and returning to the app,
+  fixed 2026-09-06.** `GlyphAtlas::clear`/`Textures::reset` on a
+  genuinely new renderer -- see IRIS.md's 2026-09-06 entry and RUST.md's
+  P0 box, item 4. Verified on the emulator (home, reopen, screenshot);
+  not yet on the phone.
+- [ ] **Composed/typed text never becomes visible at all -- found
+  2026-09-06, not fixed.** The composer bar stays empty even once the
+  buffer genuinely holds the typed text (confirmed indirectly: Gboard's
+  own suggestion strip reacts correctly to each keystroke). A new unit
+  test proves the widget tree's own layout math resolves the field's
+  region correctly across a keyboard resize, so the bug is downstream of
+  that -- most likely `UiRenderState::redraw`'s single-widget redraw path,
+  or specific to this emulator's forced `force-gles` backend (untested on
+  Vulkan or the real phone). RUST.md's P0 box, item 2, has the full
+  writeup, what was ruled out, and where to look next. **Also unverified
+  because of this**: item 3's composer rebuild (one `Stack`-based widget,
+  a capped/scrollable height, bottom padding tied to the IME/nav-bar
+  inset) -- structurally in place and unit-tested, but its own visual
+  correctness cannot be screenshotted until text actually renders.
+- [ ] **The composer has no touch-drag scroll for overflowing text.** The
+  2026-09-06 rebuild caps the field at ~6 lines and wraps it in
+  `.scrollable()` for a wheel/trackpad scroll, but a real finger drag over
+  text that has overflowed the cap does not scroll it -- `Scroll`'s touch
+  handling is a follow-up, the same shape `List`'s own touch-drag pan
+  needed before I3/I5.
+
+## From the phone, 2026-09-06, 11:39 (build delivered 02:07, commit 543f6d9)
+
+Iris's report on the build with the composing-text, tap-vs-swipe and
+atlas-reset fixes, with a screenshot, verbatim. Each is open until an
+agent ticks it here with the evidence.
+
+- [ ] **"The app definitely does not start with keyboard spacing
+  correct. This is how it looks without me doing anything initially."**
+  The screenshot shows the composer bar (the grey band) sitting about
+  two thirds of the way down a 704x1568 screen, with black below it to
+  the bottom, and the transcript ending at "Claude / Results" just above
+  it -- at launch, no keyboard. So the composer's bottom padding, which
+  the 2026-09-06 rebuild tied to the IME/nav-bar inset, is being fed a
+  large value at start on the phone. Suspects, in order: the initial
+  inset delivery on the phone (GrapheneOS, gesture navigation) versus
+  the emulator; `ime_bottom` now carrying a `1`/`0` boolean through a
+  field the composer may still read as pixels or dp; a stale value from
+  before the first `on_insets_changed`. Reproduce with the phone's
+  screen size and density on the emulator before guessing.
+- [ ] **"Swiping still gets caught by the grey bar but keeps working
+  after I go past it."** A pan that starts on the composer is held by
+  the composer until the finger leaves its region, then the list takes
+  over. The tap-vs-swipe fix in `attr.rs` stops the *focus*, but the
+  press frames are still being handled by the field rather than passed
+  to the list from the first slop-crossing frame. The `DragGesture`
+  merge (RUST.md's plan box) should make this one mechanism: once a
+  gesture commits to a pan, the list captures it wherever it began.
+- [ ] **"Flinging still does not work."** Expected on this build: finger
+  flings are dropped by per-widget hit testing, which `DragGesture`'s
+  pointer capture (commit `e12c708`, not yet merged at 02:07) targets.
+  Stays open until verified on her phone, not the emulator.
+- [ ] **"Text still disappears if I leave and come back to the app."**
+  The `GlyphAtlas::clear`/`Textures::reset` fix was verified on the
+  emulator under `force-gles` only; the phone runs Vulkan. So either the
+  reset is not reached on the phone's path (a different surface-
+  lifecycle sequence -- `surface_destroyed`/`surface_created` ordering,
+  or the renderer not being rebuilt but its textures lost), or the CPU
+  glyph cache and the GPU atlas still disagree after it. Needs logging
+  of the renderer lifecycle on the phone build, readable from `adb
+  logcat` when Iris next runs it, since no emulator here has a Vulkan
+  adapter under host GPU.
+
+## 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).**
+  - [x] **Android integration for this screen — done, 2026-09-05.**
+    `iris-android-app`'s `transcript-screen` Cargo feature
+    (`transcript_client.rs`) runs this screen against a real `ai-server`
+    through `client-core`, confirmed on-device: real scrolling, real
+    touch-drag panning, tap-by-name on the composer. Two real bugs found
+    and fixed along the way (a missing `INTERNET` permission; a
+    background-thread redraw request that crashed via a `Looper`
+    requirement, fixed by routing through `View::post_delayed` — see
+    `IRIS.md`'s `Tasks::redraw_handle` entry). See RUST.md's I5 box,
+    "The Android integration, done 2026-09-05" for the full account.
+  - [x] **A render-time number for iris, comparable to Compose's
+    `transcript-bench.sh` report — instrumentation done and a real number
+    obtained, 2026-09-05 (later the same day); the clean comparable loop
+    is not.** `iris_core::FrameReport` (`iris/core/src/render/
+    frame_report.rs`, `IRIS.md`'s new entry) times every frame from
+    `render()`'s redraw start to after `queue.submit`+`present()`, exposed
+    as two named on-screen controls ("Frame report", "Reset frame
+    report"). Driven against a real on-device touch-drag it read
+    `frames=34 janky%=61.76 p50=26.5ms p90=48.0ms p99=98.1ms
+    worst=98.1ms` — real, not inferred, but accumulated across several
+    gestures rather than one clean 24-swipe loop, because of the new
+    finding below. See RUST.md's I5 box, "Update, 2026-09-05, later the
+    same day" for the full account.
+  - [ ] **New, 2026-09-05: intermittent touch delivery to iris's
+    `SurfaceView` under this checkout's `EMU_GPU=software` emulator.**
+    The same swipe coordinates, confirmed (by scanning a screenshot
+    column for the first non-black pixel) to sit over real row text,
+    sometimes produced 30+ real frames and a screenshot diff and
+    sometimes produced zero of either, across otherwise-identical
+    `ui-trace` invocations. Not the already-understood "already at that
+    scroll edge" case (reproduced with content confirmed taller than the
+    viewport, in both directions). Leading candidate, not yet confirmed:
+    this checkout's emulator was independently observed at ~78% of one
+    CPU core, continuously, while idle on-screen — SwiftShader's software
+    rasterisation is CPU-bound by design, and a synthetic touch competing
+    with that load for delivery is plausible but unmeasured *during* a
+    failing gesture (the standing rule against diagnosing from
+    after-the-fact measurements applies here). Needs a sampler (load,
+    `dumpsys input`, a `-i 0` `ui-trace` capture) running while a failing
+    gesture is driven, and ideally a comparison under `-gpu host` (real
+    Vulkan) to see whether it is specific to software rendering. This is
+    what blocks the clean, comparable 24-swipe loop above.
+  - [x] **Long-press-then-drag-to-select — confirmed on-device, 2026-09-05
+    (later the same day).** `ui-trace` gained a `holddrag X1 Y1 X2 Y2
+    HOLD_MS MOVE_MS` action (`emulator-tools`, additive, extends the same
+    `MotionEvent`/`injectInputEvent` mechanism `swipe` already used):
+    press, hold past `LONG_PRESS`, move, release, as one continuous touch.
+    Driven against a real row (`holddrag 300 1850 300 2050 600 300`) it
+    produced `iris selection: begin at row ...` then a sequence of
+    `iris selection: extend to row ...` log lines
+    (`transcript-ui/src/selection.rs`, a new small `log` dependency since
+    selection has no accessibility label of its own yet — see the next
+    item), and a screenshot taken right after shows the expected
+    highlighted selection spanning multiple rows. `DragArbiter`'s own
+    unit tests already covered this sequence against a synthetic clock;
+    this is the first time it has been driven by a real device touch.
+  - [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".
+  - [x] **Intermittent touch-scroll dropout — root-caused and fixed,
+    2026-09-05.** Not the coalesced-`ACTION_MOVE` hypothesis the earlier
+    pass suspected (ruled out): a gesture's `ACTION_DOWN` can land on a
+    row's own padding/gap or its header, which no `CursorSense` covers,
+    so `DragArbiter` never gets `press_start` and sits in `Idle`
+    (answers `Undecided` forever) for that whole gesture. Fixed via a new
+    `DragArbiter::is_idle()` that `Selection::drag`
+    (`transcript-ui/src/selection.rs`) checks to recover a missed press
+    on the next `Pressing` frame. Four new unit tests. See RUST.md's I5
+    box, "Touch-scroll dropout root-caused, 2026-09-05", for the trace and
+    what a peer session sharing this checkout's emulator mid-pass
+    prevented from being re-verified end-to-end (the aggregate
+    `iris-scroll.sh` three-run confirmation and a re-taken FrameReport
+    row) — a future pass should finish that once the emulator is free.
+  - [ ] **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.
+
+## Build (for the port)
+
+Widgets `RUST.md`'s "The port, in order (decided 2026-09-05)" needs and
+iris does not have yet, one entry per gap, named against the P-step that
+first needs it. Move an entry up to "Fix" or tick it in place once built;
+do not duplicate it there.
+
+- [ ] **A history-paging cushion measured in on-screen viewports, not a
+  row count.** (**P1**.) `iris::widget::List` has no equivalent of the
+  Compose app's `HISTORY_SCREENS` — AGENTS.md's "Things that have
+  bitten" is explicit that a fixed row count under-fills a screen on a
+  tool-heavy transcript and over-fills one on a text-heavy one, so
+  whatever loads the next page has to ask the list how many viewports
+  are actually on screen, not assume a constant.
+- [ ] **A scaled thumbnail/image widget for an in-transcript image.**
+  (**P1**.) `SessionImage.kt`'s bitmap decode-and-downscale has no iris
+  counterpart; iris's own image widget (used by `bench_images.rs`) draws
+  a loaded texture but does nothing about sourcing or scaling one from a
+  server-produced attachment.
+- [ ] **A modal/dialog primitive.** (**P1**, reused by **P3** and
+  **P5**.) Needed for the session settings dialog, `UsageDialog`'s
+  equivalent, and the delete-with-`deleteForeign` confirmation with its
+  toggle switch. Build once, wherever it is first needed, rather than
+  once per screen that wants one.
+- [ ] **A horizontal gauge/bar widget.** (**P1**.) For
+  `SessionUsageBar`'s equivalent — a bounded fill reflecting a fraction,
+  nothing fancier.
+- [ ] **A `BusyItem` equivalent: a dimmed row carrying an operation
+  label that does not block its list's own scroll/drag.** (**P3**.) The
+  Compose version tried an overlay first and it swallowed the drag along
+  with the tap (AGENTS.md's "Shared appearance") — worth not repeating
+  that attempt in iris before building the row-level version directly.
+- [ ] **A toggle switch.** (**P3**.) For the delete dialog's
+  `deleteForeign` control; iris has no switch/checkbox widget yet as far
+  as this pass found.
+
+## 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.
+
+## Build (asked for by Iris, 2026-09-06): a density-independent length unit
+
+- [x] **A third length kind beside relative and pixels, so display scales
+  "just work".** Done 2026-09-06 — `Len::dp`/`len_fns::dp`, resolved
+  against `UiRenderState`/`Painter::density()` at `apply_rest` time; text
+  additionally rasterises at the resolved (physical) size instead of
+  scaling a low-resolution bitmap afterward, which was making text blurry.
+  `Span::gap`/`Padding` moved from `f32` to `Len` so they take `dp(...)`
+  too; transcript-ui's row/composer padding and one example migrated.
+  `em` was not added — nothing in this pass needed a text-relative unit,
+  and `dp`'s own doc says why it and physical pixels are kept as separate
+  fields rather than one the caller pre-multiplies. Not yet verified on
+  Iris's own phone at two densities (this pass had no device) — see
+  docs/RUST.md's P0 box and docs/IRIS.md's 2026-09-06 entry for what to
+  check. Iris's words: "another length type similar to absolute &
+  relative, so instead there would be relative, pixels, and another unit
+  like em or whatever is standard. That way different display scales
+  should just work." Today a length is either a fraction of the parent
+  (`rest`/relative) or physical pixels, and the phone drew 16 px text at
+  roughly a third of its intended size until the P0 fixes applied the
+  display's scale factor globally. That global scale is a stopgap for the
+  benchmark; the real shape is a unit resolved against the display's
+  density at layout time — Android's `dp` / CSS's reference pixel is the
+  standard (1 unit = 1/160 in), with `em` as the text-relative option —
+  so a widget author writes `16.dp()` once and never sees the scale.
+  Done when: `Length` (or whatever the enum is called) has the third
+  variant; every place that resolves a length takes the density; the
+  examples and `transcript-ui` use the new unit for text sizes, padding
+  and control sizes; the emulator at two densities and the phone draw the
+  same layout at the same physical size. After the bench setup is
+  finished, before P1 draws any new screen.
+
+## From the phone, bench v2 (2026-09-06): streaming re-lays out the whole message
+
+- [ ] **Streaming a delta into a long message costs a full text layout of
+  that message.** Iris's phone report (`docs/bench/iris-phone-v2-2026-09-06.md`):
+  the stream phase is the one place iris is behind Compose (p50 18.2 ms vs
+  13.4 ms; p99 level at ~43 ms). `TranscriptScreen::apply` replaces only
+  the last row, but that row is the growing message, and replacing it
+  re-renders its markdown and re-shapes the entire paragraph run through
+  parley on every event. Compose pays a reparse (8.6 ms mean) for the
+  same event. What "done" looks like: a streamed delta re-lays out only
+  the block it lands in (the last paragraph or code block), with earlier
+  blocks' layouts kept -- which needs a row to be a column of per-block
+  `Text`s rather than one `TextEdit` for the whole message, or parley's
+  layout to be split at block boundaries; measured by the stream phase's
+  p50 dropping below Compose's on the phone. Do this after the four bench
+  v2 defects (stale primitives, finger fling, decay curve, IME show) are
+  closed, since they are what make the run unrepresentative today.

docs/LAYOUT.md

@@ -0,0 +1,949 @@
+# 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.
+
+## Density: `Len::dp`, resolved at `apply_rest` time (2026-09-06)
+
+Iris asked for a third length kind beside `abs` (physical pixels) and
+`rel`/`rest` (a fraction of the parent) — IRIS_TODO.md's "density-
+independent length unit" — after the P0 phone pass found 16px text
+drawing at roughly a third size on a real phone. The fix that shipped
+first (RUST.md's P0 box) was a global stopgap: divide the whole window
+into a "logical" coordinate space (physical ÷ `content_scale`) and let
+the shader's NDC mapping stretch it back up onto the real framebuffer.
+That fixed the *size* but not the *sharpness* — a glyph rasterised at the
+small, pre-stretch size and then stretched onto more physical pixels than
+it has texels for is blurry, which is exactly what Iris's next report
+said.
+
+**The fix**: `Len` gained a `dp` field, resolved against a `density: f32`
+(physical pixels per dp) at the one place a `Len` becomes a `UiScalar`
+(`Len::apply_rest`) — `abs + dp * density`. `density` lives on
+`UiRenderState` (`set_density`/`density()`) and `Painter` (`density()`),
+set once from `DisplayMetrics.density` in `android::view::new_peer`; the
+desktop backend has no per-monitor density wired up yet and stays at
+`1.0`. Every layout call site that used to call `.apply_rest()`/
+`.to_uivec2()` now passes `painter.density()` (nine call sites — `Span`,
+`Sized`, `MaxSize`, `Aligned`, `Scroll`, `List::place`, and
+`UiRenderState::reposition` itself). This also meant the Android
+boundary's global logical-space stopgap could come out entirely: window
+size, touch coordinates and insets are physical pixels again, matching
+`AndroidRenderer`'s own swapchain resolution, with `dp` doing the
+per-length work the global divide used to do for everything at once.
+
+**Text is the case that needed more than the `Len` plumbing.** A widget's
+`font_size`/`line_height` are plain `f32`, not routed through `Len` at
+all (there is no sensible `rel`/`rest` for a font size). `TextBuffer::
+shape` now takes `density` directly and multiplies `font_size`/
+`line_height` (and any span override) by it before handing them to
+parley — so the size that reaches both the line-breaker and the
+rasteriser (`TextData::place`, which reads back whatever `shape` set) is
+the display's *physical* size, and the glyph atlas holds a bitmap at the
+resolution it is actually shown at. `GlyphKey.size` already keys on the
+resolved size, so a cache entry is naturally per-physical-size with no
+further change. The one caller with no `Painter` to read density from
+(`TextEditCtx::layout`, cursor movement and hit-testing) reads a second
+copy kept directly on `TextData` (`TextData::density`) instead — an
+accepted duplication rather than threading a `Painter` into every input
+handler for one field, the same tradeoff `AndroidRenderer::content_scale`
+already makes for the Diagnostics page.
+
+**What did not change**: `rel`/`rest` are unaffected (already
+resolution-independent, a fraction of the parent). `Span::gap` and
+`Padding`'s four sides moved from bare `f32` to `Len` so `dp(...)` works
+on them the same as any other size; a bare number is still `abs`,
+physical pixels, unchanged.
+
+## 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.

docs/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.

docs/bench/compose-phone-2026-09-06.md

@@ -0,0 +1,73 @@
+# Compose bench report from Iris's phone, 2026-09-06
+
+The Compose half of P0 (RUST.md), run by Iris on her own phone and pasted
+back verbatim. The iris half's report goes beside it in this directory
+when it exists. Her caveat, worth keeping with the numbers: "I don't think
+this is entirely fair because the UI for iris is more minimal" -- the
+Compose screen also draws the usage bar, the status row and tool cards,
+which the iris bench screen does not yet. Her impression of the iris build
+before its first-touch bug: "it already feels very smooth so far".
+
+What to read first: the phone runs at 120 Hz, so the budget is 8.3 ms;
+`late` is measured against that. Compose's tail is the streaming phase --
+`markdown reparsed while streaming: 396, 8.5ms mean, 25.8ms worst` and
+`record: one block: 398, 6.3ms mean, 19.9ms worst` -- which is exactly the
+path iris's `TranscriptScreen::apply` (replace the last row only) is meant
+to beat. Process CPU over the run is 20.9 s of a 38.5 s run; peak RSS
+587 MB; battery current mean 419 mA.
+
+```
+ai-app render report
+device: Pixel 9 Pro XL (Google), Android 17
+build: release
+
+transcript:
+  43 events, 41 rows, 93 units loaded
+  viewport 1333px, 2 units visible
+  on screen: the list's own 0px, AssistantMsg 24520px
+  0 tool calls and 0 groups open
+
+frames:
+  1613 frames over 38.5s at 120Hz (8.3ms budget)
+  late: 742 (46.0%)
+  total  p50 7.7ms  p90 29.2ms  p99 41.1ms
+  waited p50 0.5ms  p90 12.9ms  p99 27.2ms
+  input  p50 0.0ms  p90 0.0ms  p99 0.0ms
+  anim   p50 1.1ms  p90 5.8ms  p99 9.5ms
+  layout p50 0.0ms  p90 0.1ms  p99 0.2ms
+  draw   p50 0.4ms  p90 15.9ms  p99 27.9ms
+  sync   p50 0.1ms  p90 0.5ms  p99 1.0ms
+  issue  p50 1.1ms  p90 1.7ms  p99 3.0ms
+  swap   p50 0.4ms  p90 0.5ms  p99 0.7ms
+  gpu    p50 1.8ms  p90 2.1ms  p99 6.6ms
+
+where the draw phase went:
+  draw phase 3.83ms per frame, of which:
+    the transcript: 0.25ms (measure 0.15, place 0.10, record 0.00)
+    everything else: 3.58ms (93%)
+
+work since this was last copied:
+  draw: the whole transcript: 12, 0.2ms total, 0.0ms mean, 0.0ms worst
+  grouped tool runs: 398, 10.3ms total, 0.0ms mean, 0.1ms worst
+  markdown cut into pieces: 1, 0.0ms total, 0.0ms mean, 0.0ms worst
+  markdown parsed while composing: 7, 3.0ms total, 0.4ms mean, 0.5ms worst
+  markdown ready: 46
+  markdown reparsed while streaming: 396, 3384.6ms total, 8.5ms mean, 25.8ms worst
+  markdown warmed: 1, 1.4ms total, 1.4ms mean, 1.4ms worst
+  measure: the whole transcript: 957, 248.7ms total, 0.3ms mean, 15.7ms worst
+  message composed: 403
+  message cut into parts: 1, 0.1ms total, 0.1ms mean, 0.1ms worst
+  place: the whole transcript: 1319, 162.4ms total, 0.1ms mean, 1.3ms worst
+  record: one block: 398, 2498.7ms total, 6.3ms mean, 19.9ms worst
+  session screen recomposed: 413
+  status row recomposed: 1
+  unit composed: 538
+  units flattened: 399, 44.3ms total, 0.1ms mean, 0.5ms worst
+  usage bar recomposed: 413
+
+bench:
+  scroll: 6 cycles (24 swipes), streamed 400/400 fixture events
+  process CPU time over this run: 20907ms
+  peak RSS: 587356kB
+  battery current: mean -418509µA over 39 samples (min -1988281, max -107812)
+```

docs/bench/compose-phone-v2-2026-09-06.md

@@ -0,0 +1,93 @@
+# Compose bench v2 report from Iris's phone, 2026-09-06
+
+Bench v2 (fling / stream / type / keyboard, RUST.md's P0 box) on the
+Compose `bench` build, run by Iris on her Pixel 9 Pro XL, verbatim. Note
+the display was at **60 Hz** for this run (16.7 ms budget) where the v1
+run was at 120 Hz -- the phone's adaptive refresh rate decides, and
+`late` is judged against whichever it was, so compare a run with a run at
+the same rate. The iris v2 report goes beside this when it exists.
+
+What it says: fling, type and keyboard are all essentially clean on
+Compose (0.1%, 0.9% and 0% late; fling p50 5.5 ms, p99 11.6 ms). The
+whole tail is the streaming phase again -- 41.9% late, p99 42.5 ms,
+driven by `markdown reparsed while streaming` (8.6 ms mean, 30.3 ms
+worst) and `record: one block` (6.3 ms mean, 25.5 ms worst). Process CPU
+69.6 s over the 125.5 s run; peak RSS 577 MB; battery current mean
+571 mA over 126 samples.
+
+```
+ai-app render report
+device: Pixel 9 Pro XL (Google), Android 17
+build: release
+
+transcript:
+  108 events, 26 rows, 58 units loaded
+  viewport 1531px, 2 units visible
+  on screen: the list's own 0px, AssistantMsg 24520px
+  0 tool calls and 0 groups open
+
+per phase:
+  fling: 3278 frames over 32.7s
+    late: 4 (0.1%)
+      total  p50 5.5ms  p90 8.7ms  p99 11.6ms
+    worst 49.0ms
+  stream: 1041 frames over 21.3s
+    late: 436 (41.9%)
+      total  p50 13.4ms  p90 31.7ms  p99 42.5ms
+    worst 52.5ms
+  type: 2446 frames over 61.5s
+    late: 23 (0.9%)
+      total  p50 7.3ms  p90 13.2ms  p99 16.5ms
+    worst 38.9ms
+  keyboard: 358 frames over 10.0s
+    late: 0 (0.0%)
+      total  p50 6.3ms  p90 8.6ms  p99 11.1ms
+    worst 12.0ms
+
+frames:
+  7122 frames over 125.5s at 60Hz (16.7ms budget)
+  late: 463 (6.5%)
+  total  p50 6.0ms  p90 13.8ms  p99 34.0ms
+  waited p50 0.5ms  p90 1.1ms  p99 19.9ms
+  input  p50 0.0ms  p90 0.0ms  p99 0.0ms
+  anim   p50 0.7ms  p90 4.5ms  p99 7.6ms
+  layout p50 0.1ms  p90 0.1ms  p99 0.2ms
+  draw   p50 0.7ms  p90 2.9ms  p99 21.9ms
+  sync   p50 0.1ms  p90 0.2ms  p99 0.6ms
+  issue  p50 1.4ms  p90 2.4ms  p99 3.2ms
+  swap   p50 0.4ms  p90 0.8ms  p99 1.2ms
+  gpu    p50 1.5ms  p90 2.1ms  p99 6.6ms
+
+where the draw phase went:
+  draw phase 1.74ms per frame, of which:
+    the transcript: 0.24ms (measure 0.10, place 0.14, record 0.00)
+    everything else: 1.51ms (86%)
+
+work since this was last copied:
+  draw: the whole transcript: 280, 1.9ms total, 0.0ms mean, 0.0ms worst
+  grouped tool runs: 407, 18.6ms total, 0.0ms mean, 0.2ms worst
+  markdown cut into pieces: 40, 0.4ms total, 0.0ms mean, 0.0ms worst
+  markdown parsed while composing: 2, 1.6ms total, 0.8ms mean, 1.1ms worst
+  markdown ready: 323
+  markdown reparsed while streaming: 395, 3406.9ms total, 8.6ms mean, 30.3ms worst
+  markdown warmed: 40, 38.2ms total, 1.0ms mean, 4.3ms worst
+  measure: the whole transcript: 1978, 683.9ms total, 0.3ms mean, 15.9ms worst
+  message composed: 397
+  message cut into parts: 40, 2.9ms total, 0.1ms mean, 0.2ms worst
+  place: the whole transcript: 4308, 996.0ms total, 0.2ms mean, 2.4ms worst
+  record: one block: 394, 2472.7ms total, 6.3ms mean, 25.5ms worst
+  session screen recomposed: 1630
+  status row recomposed: 1
+  transcript page from server: 10
+  unit composed: 927
+  units flattened: 408, 85.5ms total, 0.2ms mean, 1.8ms worst
+
+bench:
+  fling: 8 flings out + 8 back at 12000px/s, travel start=idx=0/off=0px outward=idx=188/off=182px end=idx=0/off=0px
+  scroll: 6 cycles (24 swipes, legacy tween), streamed 400/400 fixture events
+  type: 600 characters inserted then deleted, one per 50ms
+  keyboard: shown 5/5, hidden 5/5 (confirmed via isImeVisible)
+  process CPU time over this run: 69564ms
+  peak RSS: 577452kB
+  battery current: mean -571483µA over 126 samples (min -2361718, max -99218)
+```

docs/bench/iris-phone-2026-09-06-before-fixes.md

@@ -0,0 +1,31 @@
+# iris bench report from Iris's phone, 2026-09-06, before the phone fixes
+
+Build 46246ea (Vulkan, bench v1: 24-swipe scroll loop then 400 streamed
+events), run by Iris on her Pixel 9 Pro XL before the first-touch wipe,
+the missing bold faces, the density scale and the status-bar inset were
+fixed -- so the rows were drawn at roughly a third of their intended size
+and the run may have included frames after the wipe. Preliminary, kept
+because it is the first iris number from real hardware. Compare with
+`compose-phone-2026-09-06.md`, taken on the same phone with the same
+fixture and gesture loop.
+
+Reading it: the phone is 120 Hz (8.3 ms budget). `janky%` here counts
+frames over 16.7 ms, so it is not Compose's `late` (over 8.3 ms). Like for
+like: iris p50 6.2 ms vs Compose 7.7 ms; p90 32.0 vs 29.2; p99 42.1 vs
+41.1. `cpu_p50=4.7ms` is iris's own per-frame CPU work on the phone,
+against 0.2-0.4 ms on the emulator's x86 cores. Process CPU 15.6 s vs
+20.9 s, but over a shorter run (692 frames vs 1613 -- iris only renders on
+change and had no fling settle time), so per-second CPU is not directly
+comparable; peak RSS 365 MB vs 587 MB. Battery current mean 563 mA vs
+419 mA is the one figure that reads worse, and it is the least
+comparable: 22 samples vs 39, over runs of different length and different
+idle share. Bench v2's per-phase accounting is what makes these comparable.
+
+```
+iris bench report
+frames=692 janky%=32.37 p50=6.2ms p90=32.0ms p99=42.1ms worst=52.6ms (measures redraw-start to after present() is called, not GPU/compositor completion) cpu_p50=4.7ms gpu_wait_p50=1.3ms (redraw-start-to-submit vs. submit-to-after-present)
+  scroll: 6 cycles (24 swipes), streamed 400/400 fixture events
+  process CPU time over this run: 15554ms
+  peak RSS: 365328kB
+  battery current: mean -563493µA over 22 samples (min -1807812, max -132812)
+```

docs/bench/iris-phone-v2-2026-09-06.md

@@ -0,0 +1,58 @@
+# iris bench v2 report from Iris's phone, 2026-09-06
+
+Build 2e3f4ad (bench v2, fling physics, keyboard-wipe fix, dp unit), run
+by Iris on her Pixel 9 Pro XL, verbatim. The display was at **120 Hz**
+(8.3 ms budget) where `compose-phone-v2-2026-09-06.md` ran at 60 Hz, so
+compare the millisecond percentiles, not `late`.
+
+Side by side (Compose 60 Hz / iris 120 Hz, p50 / p90 / p99 ms): fling
+5.5/8.7/11.6 vs 3.8/6.9/12.6; stream 13.4/31.7/42.5 vs 18.2/35.8/43.1;
+type 7.3/13.2/16.5 vs 7.2/9.2/11.2; keyboard: iris could not show the IME
+(phase invalid). Process CPU 69.6 s over 125 s vs 40.6 s over 150 s; peak
+RSS 577 MB vs 379 MB; battery current mean 571 mA vs 452 mA.
+
+Iris's observations on the same run: "the scrolling is not similar at
+all. It does not fling for me yet [with a finger], and the test also seems
+to give it a constant velocity and abruptly stop it at some point. Also
+unsure what's going on in that image with the compaction" -- her
+screenshot shows the `Compacted: 180000 -> 20000 tokens.` row drawn twice
+overlapping, and once more below the composer bar: primitives of a
+replaced/removed row surviving in the GPU buffers, the same shape as the
+header drawn twice after a keyboard resize.
+
+```
+iris bench report
+per phase:
+  fling: 1783 frames over 53.2s
+    late: 104 (5.8%)
+      total  p50 3.8ms  p90 6.9ms  p99 12.6ms
+    worst 29.1ms
+  stream: 401 frames over 21.3s
+    late: 306 (76.3%)
+      total  p50 18.2ms  p90 35.8ms  p99 43.1ms
+    worst 43.8ms
+  type: 1202 frames over 65.7s
+    late: 309 (25.7%)
+      total  p50 7.2ms  p90 9.2ms  p99 11.2ms
+    worst 15.3ms
+  keyboard: 9 frames over 9.7s
+    late: 9 (100.0%)
+      total  p50 12.0ms  p90 12.9ms  p99 12.9ms
+    worst 12.9ms
+
+frames:
+  3395 frames over 149.9s at 120Hz (8.3ms budget)
+  late: 728 (21.4%)
+  total  p50 5.0ms  p90 10.9ms  p99 36.6ms
+  worst 43.8ms
+  cpu_p50 2.0ms  gpu_wait_p50 2.6ms
+
+bench:
+  fling: 8 flings out + 8 back at 12000px/s, travel start=idx=651/off=1217px outward=idx=651/off=101536px end=idx=651/off=1022px
+  scroll: 6 cycles (24 swipes, legacy tween), streamed 400/400 fixture events
+  type: 600 characters inserted then deleted, one per 50ms
+  keyboard: could not be shown (5 attempts, 0 confirmed visible)
+  process CPU time over this run: 40603ms
+  peak RSS: 379156kB
+  battery current: mean -452353µA over 149 samples (min -1753125, max -204687)
+```

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,396 @@
+//! 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,
+    /// The account behind this session has no quota left, so the turn stopped
+    /// without finishing.
+    ///
+    /// Its own event rather than an [`Event::Error`] carrying the dialect's
+    /// sentence, because two things act on it that cannot read English: the
+    /// transcript draws it as a state the session is in rather than as a
+    /// failure of something it did, and `crate::resume` schedules the message
+    /// that picks the work back up. Recognising it belongs to the driver, which
+    /// is the only layer that knows its dialect's wording -- above here nothing
+    /// matches on strings.
+    ///
+    /// `resets_at` is epoch seconds, and `None` is a real state: the dialect
+    /// said the limit was hit without saying when it lifts. Nothing here
+    /// invents one -- what the wait is actually decided against is the usage
+    /// endpoint, and this is the hint that starts the waiting.
+    LimitReached {
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        resets_at: Option<f64>,
+    },
+    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/.gitignore

@@ -0,0 +1,2 @@
+/target
+perf.data*

iris/Cargo.toml

@@ -0,0 +1,117 @@
+[package]
+name = "iris"
+version.workspace = true
+edition.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+iris-core = { workspace = true }
+iris-macro = { workspace = true }
+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"
+
+[features]
+# RUST.md's I5 "Where iris's frame time goes" diagnosis: forces the Android
+# `wgpu::Instance` to `Backends::GL` instead of `Backends::PRIMARY`, so the
+# same build can be measured against SwiftShader's software Vulkan ICD (the
+# default) or virgl's GLES path, without a second env-var plumbing path that
+# nothing on this machine can hand to an already-launched Android process
+# (there is no `am start` environment and no system-property reader here to
+# add one). Android-only; `android/render.rs` is the only reader.
+force-gles = []
+
+[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", "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"
+edition = "2024"
+
+[workspace.dependencies]
+pollster = "0.4.0"
+winit = "0.30.12"
+wgpu = "28.0.0"
+bytemuck = "1.23.1"
+image = "0.25.6"
+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/TODO

@@ -0,0 +1,40 @@
+images
+    settings (sampler)
+
+text
+    figure out ways to speed up / what costs the most
+    resizing (per frame) is really slow (assuming painter isn't griefing)
+    j is weird / fix x offset
+
+masks r just made to bare minimum work
+
+scaling
+    could be just a simple scaling factor that multiplies abs
+    and need to ensure text uses raw abs and not scaled abs
+    naming? (pt, px)
+    want to keep (drawn) regions using px? or should I add another field to UiScalar/Vec
+    field could be best solution so redrawing stuff isn't needed & you can specify both as user
+
+WidgetRef<W> or smth instead of Id
+    enum that's either an Id or an actual concrete instance of W
+    painter takes them in instead of (or in addition to) id
+    then type wrapper widgets to contain them
+    allows for compile time optimization if a widget wrapper's inner is known at compile time
+        and the id of inner is not needed anywhere
+    maybe introduce InnerWidget trait to allow for editors to expose & modify inner type
+    maybe could also store a parent widget and keep using InnerWidget trait? unsure if possible
+
+really weird limitation:
+    I don't think you can currently remove an element from a parent and put it in a child of the same parent
+    because it removes the unused children after the entire parent redraw
+    but the child gets drawn during that, so it will think the child is still active !!!
+    or something like that idk, maybe I need a special enum for parent that includes a undecided state where it may or may not get redrawn by the parent
+    or just do ref counting and ensure all drawn things == 1 afterwards (seems like best way)
+    ok so I'm removing the limit for now
+
+don't forget I'm streaming
+
+tags
+vecs for each widget type?
+
+POTENTIAL BUG: closures that store IDs will not decrement the id!!! need to not increment id if moved into closure somehow??? wait no, need to decrement ID every time an event fn is added...... only if the id is used in it..??

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,74 @@
+[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 = "../" }
+android-view = { git = "https://github.com/rust-mobile/android-view.git", rev = "bec6c62a96cef8239b0fd7fedeef9b184d02e3a1" }
+android_logger = "0.15.0"
+log = "0.4.28"
+# `tabs-screen` (default, I2/I4's demo) and `transcript-screen` (I5's
+# Android integration) are mutually exclusive -- one `ActiveClient` type is
+# compiled in, never both (`lib.rs`'s doc comment) -- so both sets of deps
+# are optional and each screen's feature pulls in only its own. Without
+# this, building `--features transcript-screen` alone (default features
+# still on) left `tabs-ui` linked but never referenced under that cfg,
+# which Cargo's `unused_dependencies` lint (on by default) correctly flags.
+tabs-ui = { path = "../tabs-ui", optional = true }
+transcript-ui = { path = "../transcript-ui", optional = true }
+client-core = { path = "../../client-core", optional = true }
+event-model = { path = "../../event-model", optional = true }
+serde_json = { version = "1", features = ["float_roundtrip"], optional = true }
+# P0's bench build only (docs/RUST.md): `getrusage(RUSAGE_SELF)` for
+# process CPU time, matching `libc::getrusage`'s mention in that box over
+# parsing `/proc/self/stat` by hand and assuming `USER_HZ`. Already in the
+# workspace's own dependency tree transitively (`iris/Cargo.lock`, pinned
+# at 0.2.179) -- this makes it a direct dependency at the same version
+# rather than a second, possibly-drifting resolution.
+libc = { version = "0.2.179", optional = true }
+# P0's bench build only: the scroll animation and the streaming phase are
+# both a sequence of `sleep`s inside the async task `rsc.spawn_task` already
+# runs on iris's own tokio runtime (`iris/src/task.rs`'s `Tasks::init`), and
+# the battery sampler is a second, concurrent task on that same runtime
+# (`tokio::spawn`) -- so this crate needs `tokio` directly rather than only
+# through `iris`. `rt`+`time` only: no I/O, no macros, nothing this crate
+# doesn't call. Version matches the one `iris`'s own dependency tree already
+# resolves to (`iris/Cargo.lock`), so there is one copy of the runtime, not
+# two.
+tokio = { version = "1.53.1", features = ["rt", "time"], optional = true }
+
+[features]
+default = ["tabs-screen"]
+tabs-screen = ["dep:tabs-ui"]
+transcript-screen = ["dep:transcript-ui", "dep:client-core", "dep:event-model", "dep:serde_json"]
+# RUST.md's I5 "Where iris's frame time goes": forces the GLES backend
+# instead of SwiftShader's software Vulkan. See `iris/Cargo.toml`'s own doc
+# on the feature this forwards to.
+force-gles = ["iris/force-gles"]
+# P0's iris half (docs/RUST.md, docs/AGENTS.md's "The rigs"): the same
+# checked-in fixture, scroll loop and streaming phase the Compose `bench`
+# build type drives, run here against `transcript-ui`'s real screen with no
+# server. Depends on `transcript-screen` for `transcript-ui`/`client-core`/
+# `event-model` -- `lib.rs`'s `ActiveClient` selection gives this feature
+# priority over `transcript-screen`'s own `TranscriptClient` when both are
+# listed, which is how this crate's build command names both explicitly.
+bench = ["transcript-screen", "dep:libc", "dep:tokio"]
+
+[profile.release]
+panic = "abort"
+
+[profile.dev]
+panic = "abort"

iris/android-app/app/build.gradle

@@ -0,0 +1,61 @@
+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"
+    }
+
+    // A release build must be signed, and the key is per machine rather than per repo -- same
+    // reasoning and the same key as `app/build-apk.sh` (the Compose app): it is what a phone
+    // recognises the app by, and a secret never lives in a checkout (the mount is shared with an
+    // untrusted VM). `build-apk.sh` generates this key once and points at it through the
+    // environment; without it a release build here is unsigned, which is fine for everything
+    // except installing.
+    def keystore = System.getenv("AI_APP_KEYSTORE")
+    signingConfigs {
+        if (keystore != null) {
+            release {
+                storeFile = file(keystore)
+                storePassword = System.getenv("AI_APP_KEYSTORE_PASSWORD")
+                keyAlias = "ai-app"
+                keyPassword = storePassword
+            }
+        }
+    }
+
+    buildTypes {
+        debug {
+        }
+        // P0's iris half (docs/RUST.md's P0 box): the build a phone actually runs. The `.so`
+        // itself is built separately with `cargo ndk --release --features "transcript-screen
+        // force-gles bench"` straight into src/main/jniLibs/ (this crate's own Cargo.toml) --
+        // Gradle here only packages and signs whatever is already there, the same division as the
+        // debug/tabs-screen build this project started with. `applicationIdSuffix` keeps it
+        // installable beside a debug build of the tabs demo rather than replacing it.
+        release {
+            applicationIdSuffix ".bench"
+            if (keystore != null) {
+                signingConfig = signingConfigs.release
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}

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

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Only needed by the transcript-screen feature (RUST.md's I5),
+         which talks to a real ai-server; the plain tabs demo (I2/I4) makes
+         no network call and never noticed this was missing. Absent,
+         UreqTransport::new's connect failed with EPERM (Operation not
+         permitted), not the ECONNREFUSED/ENETUNREACH a firewall or a dead
+         server would give: a seccomp-level socket denial reads nothing
+         like a network problem, which is what made it worth a comment. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <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,155 @@
+package dev.iris.android.demo;
+
+import android.app.Activity;
+import android.content.ClipData;
+import android.content.ClipboardManager;
+import android.content.Context;
+import android.view.Gravity;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.Button;
+import android.widget.FrameLayout;
+import android.widget.LinearLayout;
+import android.widget.ScrollView;
+import android.widget.TextView;
+
+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();
+    }
+
+    /**
+     * Called from the Rust side (iris/src/android/view.rs's
+     * `show_renderer_error`) when `AndroidRenderer::new` fails instead of
+     * drawing -- an ordinary instance method rather than a `native` one,
+     * since this call is Rust reaching into Java rather than the other
+     * direction. Replaces the whole activity content with plain,
+     * selectable, scrollable text rather than leaving the last frame (or a
+     * blank surface) on screen with no way to report what happened:
+     * UI_RULES.md's "a failure is reported where it happened, and says
+     * what to do next." No dialog and no styling beyond what is needed to
+     * read and copy the text -- this path exists for exactly the crash it
+     * replaces, so it must not depend on anything that could itself fail
+     * to render.
+     */
+    void showRendererError(String report) {
+        Context context = getContext();
+        if (!(context instanceof Activity)) {
+            return;
+        }
+        Activity activity = (Activity) context;
+        TextView text = new TextView(activity);
+        text.setText(report);
+        text.setTextIsSelectable(true);
+        text.setGravity(Gravity.TOP | Gravity.START);
+        int pad = (int) (16 * activity.getResources().getDisplayMetrics().density);
+        text.setPadding(pad, pad, pad, pad);
+        ScrollView scroll = new ScrollView(activity);
+        scroll.addView(text);
+        activity.setContentView(scroll);
+    }
+
+    private static final String DIAGNOSTICS_OVERLAY_TAG = "iris-diagnostics-overlay";
+
+    /**
+     * The bench build's keyboard diagnostics capture
+     * (`bench_client.rs`'s `on_insets_changed` /
+     * `capture_keyboard_diagnostics`, via `bench_jni.rs`'s
+     * `PlatformHandle::show_diagnostics_overlay`): unlike
+     * `showRendererError` above, this adds a panel *over* this view
+     * (`MainActivity`'s `FrameLayout` still holds `IrisView` underneath,
+     * running) rather than replacing the activity's content, and gives it
+     * a Copy button and a Close that removes the panel -- so it draws
+     * (and can be read) whether or not iris itself is still putting
+     * anything on screen, without abandoning the session that produced
+     * it. Runs on the UI thread regardless of which thread calls it,
+     * since the call comes from a background task (a delayed capture
+     * after the keyboard opens), and touching the view tree off the UI
+     * thread is undefined.
+     */
+    void showDiagnosticsOverlay(String report) {
+        Context context = getContext();
+        if (!(context instanceof Activity)) {
+            return;
+        }
+        Activity activity = (Activity) context;
+        activity.runOnUiThread(() -> {
+            ViewGroup parent = (ViewGroup) getParent();
+            if (parent == null) {
+                return;
+            }
+            View existing = parent.findViewWithTag(DIAGNOSTICS_OVERLAY_TAG);
+            if (existing != null) {
+                parent.removeView(existing);
+            }
+
+            float density = activity.getResources().getDisplayMetrics().density;
+            int pad = (int) (16 * density);
+
+            LinearLayout overlay = new LinearLayout(activity);
+            overlay.setTag(DIAGNOSTICS_OVERLAY_TAG);
+            overlay.setOrientation(LinearLayout.VERTICAL);
+            overlay.setBackgroundColor(0xEE000000);
+            overlay.setPadding(pad, pad, pad, pad);
+
+            TextView text = new TextView(activity);
+            text.setText(report);
+            text.setTextIsSelectable(true);
+            text.setTextColor(0xFFFFFFFF);
+            ScrollView scroll = new ScrollView(activity);
+            scroll.addView(text);
+            overlay.addView(scroll, new LinearLayout.LayoutParams(
+                    LinearLayout.LayoutParams.MATCH_PARENT, 0, 1f));
+
+            LinearLayout buttonRow = new LinearLayout(activity);
+            buttonRow.setOrientation(LinearLayout.HORIZONTAL);
+            buttonRow.setPadding(0, pad, 0, 0);
+
+            Button copy = new Button(activity);
+            copy.setText("Copy");
+            copy.setOnClickListener(v -> {
+                ClipboardManager clipboard =
+                        (ClipboardManager) activity.getSystemService(Context.CLIPBOARD_SERVICE);
+                if (clipboard != null) {
+                    clipboard.setPrimaryClip(ClipData.newPlainText("iris diagnostics", report));
+                }
+            });
+            Button close = new Button(activity);
+            close.setText("Close");
+            close.setOnClickListener(v -> parent.removeView(overlay));
+            buttonRow.addView(copy);
+            buttonRow.addView(close);
+            overlay.addView(buttonRow);
+
+            parent.addView(overlay, new FrameLayout.LayoutParams(
+                    FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT));
+        });
+    }
+}

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

@@ -0,0 +1,85 @@
+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();
+
+        // RUST.md's P0 box, defect 4 ("keyboard: could not be shown"):
+        // `logcat` showed the platform's own IME open/resize happening
+        // while `setOnApplyWindowInsetsListener` fired only once, at
+        // attach, and never again for a pure keyboard toggle -- a plain
+        // (non-edge-to-edge) window is only guaranteed that one initial
+        // dispatch; `adjustResize` handling the IME entirely by resizing
+        // the window is not itself a trigger for a fresh one. Opting into
+        // edge-to-edge (a platform call, API 30+, no new dependency) is
+        // what makes the system redeliver insets on every change,
+        // including the ones this activity actually cares about --
+        // `getSystemWindowInset*` below is unaffected by this (it has
+        // always reported the raw system-bar/IME overlap regardless of
+        // who consumes it), so the on-screen bars and the padding Rust
+        // already derives from those four numbers are unchanged; only the
+        // callback's firing became reliable.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            getWindow().setDecorFitsSystemWindows(false);
+        }
+
+        view.setOnApplyWindowInsetsListener((v, insets) -> {
+            int left = insets.getSystemWindowInsetLeft();
+            int top = insets.getSystemWindowInsetTop();
+            int right = insets.getSystemWindowInsetRight();
+            int bottom = insets.getSystemWindowInsetBottom();
+            // The manifest declares adjustResize (AGENTS.md: without it the
+            // keyboard pans the whole window instead of resizing it), and
+            // under adjustResize the window itself shrinks to make room for
+            // the keyboard -- which is exactly the condition under which
+            // WindowInsets.Type.ime()'s own *inset amount* reports zero: it
+            // measures how much of the window the keyboard overlaps, and
+            // resize already made that overlap zero by construction. That
+            // numeric inset is not a usable "is the keyboard open" signal
+            // here (found while root-causing why bench_client.rs's keyboard
+            // phase and auto-diagnostics never fired on the emulator despite
+            // the keyboard visibly opening -- RUST.md's P0 box). What does
+            // survive adjustResize is the boolean isVisible() answer, set
+            // from the platform's own start/end of the transition over a
+            // different path than the inset amount -- the same fact
+            // AGENTS.md's "Things that have bitten" already names for the
+            // Compose side's identical trap. Passed through as a 0/1 stand-
+            // in for the ime_bottom pixel amount, since nothing on the Rust
+            // side reads it as a real pixel value -- only `> 0.0`.
+            int imeBottom = 0;
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
+                    && insets.isVisible(WindowInsets.Type.ime())) {
+                imeBottom = 1;
+            }
+            ((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-apk.sh

@@ -0,0 +1,90 @@
+#!/bin/sh
+# Builds iris-android-app end to end: the cdylib (cargo ndk, straight into
+# app/src/main/jniLibs/) then the APK (Gradle). Written to stop re-typing
+# the same incantation by hand every time (ANDROID_HOME/NDK exports, the
+# cargo ndk invocation, the keystore env for a release build, apksigner/
+# aapt2 verification) -- see docs/RUST.md's P0 box. Same shape as `app/
+# build-apk.sh` (the Compose app's own build script) and `app/
+# iris-scroll.sh` (no coordinates, set -eu, exit 0 on success).
+#
+# Usage: ./build-apk.sh [debug|release] [--abi arm64-v8a|x86_64] [--features "a b c"]
+#   debug/release default to debug (matches this-machine-android's "the
+#   emulator stays on debug" rule -- pass `release` explicitly for a phone
+#   build). --abi defaults to arm64-v8a (a phone/real device); pass
+#   x86_64 for this checkout's own AVD. --features defaults to
+#   "transcript-screen bench" -- deliberately *without* `force-gles`, unlike
+#   an earlier version of this default. `force-gles` (`iris/Cargo.toml`'s
+#   own doc) exists only to force the emulator off its default software
+#   Vulkan and onto GLES for one specific measurement (RUST.md's I5, "Where
+#   iris's frame time goes") -- it was never meant to reach a real device,
+#   but this script's old default put it in every arm64 build regardless,
+#   so the P0 bench APK delivered to Iris's phone forced GLES there too.
+#   That is the named hypothesis in RUST.md's P0 box ("iris bench crash on
+#   the phone, 2026-09-06"): a real Vulkan driver is what a phone should
+#   run, and GLES is the backend the same box's own SwiftShader finding
+#   already flagged as the fragile one for this shader's storage buffers.
+#   Pass `--features "transcript-screen force-gles bench"` explicitly for
+#   an emulator backend-isolation run; never for a build meant for a phone.
+set -eu
+cd "$(dirname "$0")"
+
+BUILD_TYPE="debug"
+ABI="arm64-v8a"
+FEATURES="transcript-screen bench"
+case "${1:-}" in
+    debug|release) BUILD_TYPE="$1"; shift ;;
+esac
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --abi) ABI="$2"; shift 2 ;;
+        --features) FEATURES="$2"; shift 2 ;;
+        *) echo "build-apk.sh: unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+SDK_ROOT="$HOME/Android/Sdk"
+export ANDROID_HOME="$SDK_ROOT"
+export ANDROID_SDK_ROOT="$SDK_ROOT"
+NDK_DIR=$(ls -d "$SDK_ROOT"/ndk/*/ 2>/dev/null | sort -V | tail -1)
+if [ -z "$NDK_DIR" ]; then
+    echo "build-apk.sh: no NDK found under $SDK_ROOT/ndk" >&2
+    exit 1
+fi
+export ANDROID_NDK_HOME="$NDK_DIR"
+
+echo "build-apk.sh: cargo ndk -t $ABI build ${BUILD_TYPE:+(${BUILD_TYPE})} --features \"$FEATURES\""
+if [ "$BUILD_TYPE" = "release" ]; then
+    cargo ndk -t "$ABI" -P 26 -o app/src/main/jniLibs/ build --release --features "$FEATURES"
+else
+    cargo ndk -t "$ABI" -P 26 -o app/src/main/jniLibs/ build --features "$FEATURES"
+fi
+
+GRADLE_TASK="assembleDebug"
+APK_DIR="app/build/outputs/apk/debug"
+APK_NAME="app-debug.apk"
+if [ "$BUILD_TYPE" = "release" ]; then
+    GRADLE_TASK="assembleRelease"
+    APK_DIR="app/build/outputs/apk/release"
+    APK_NAME="app-release.apk"
+    # Same key `app/build-apk.sh` (the Compose app) generates once under
+    # ~/.config/ai-app/release.jks -- see AGENTS.md's "Checking your work".
+    export AI_APP_KEYSTORE="$HOME/.config/ai-app/release.jks"
+    if [ ! -f "$AI_APP_KEYSTORE" ]; then
+        echo "build-apk.sh: no release key at $AI_APP_KEYSTORE -- run app/build-apk.sh once first" >&2
+        exit 1
+    fi
+    export AI_APP_KEYSTORE_PASSWORD
+    AI_APP_KEYSTORE_PASSWORD=$(cat "$AI_APP_KEYSTORE.password")
+fi
+
+gradle ":app:$GRADLE_TASK" --console=plain
+
+APK_PATH="$(pwd)/$APK_DIR/$APK_NAME"
+BUILD_TOOLS=$(ls -d "$SDK_ROOT"/build-tools/*/ | sort -V | tail -1)
+echo "--- aapt2 dump badging ---"
+"${BUILD_TOOLS}aapt2" dump badging "$APK_PATH" | head -5
+if [ "$BUILD_TYPE" = "release" ]; then
+    echo "--- apksigner verify ---"
+    "${BUILD_TOOLS}apksigner" verify --print-certs "$APK_PATH"
+fi
+echo "$APK_PATH"

iris/android-app/build.gradle

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

iris/android-app/build.rs

@@ -0,0 +1,100 @@
+// Only does anything under the `transcript-screen` feature (RUST.md's I5
+// Android integration) -- the plain tabs build (I2/I4) needs none of this
+// and stays untouched, same reasoning as the feature gate in Cargo.toml.
+//
+// Bakes the sandbox server's host, port, token and pinned CA in at build
+// time, the same way `app/androidApp/build.gradle.kts`'s
+// `GeneratePinnedCert` task bakes the CA for the Compose app -- see that
+// file's comment for why reading the machine's own certificate at build
+// time is the right trust boundary. This build additionally bakes the
+// host/port/token, which the Compose app does not: that app enrolls at
+// runtime from a scanned QR/deep link, and a from-scratch enrollment UI
+// (Keystore-sealed token storage, a QR/link scanner) is real, separate
+// scope this integration does not need to build to answer RUST.md's
+// question -- there is nothing here yet resembling `ServerConfig.kt`. So
+// this is a **deliberate simplification for this rig only**: an APK built
+// this way is good for exactly the emulator/server pair that built it, and
+// must never be treated as a template for a real enrollment flow. Recorded
+// in RUST.md's I5 box rather than left to be rediscovered.
+use std::path::PathBuf;
+
+fn main() {
+    if std::env::var_os("CARGO_FEATURE_TRANSCRIPT_SCREEN").is_none() {
+        return;
+    }
+    // P0's bench build (docs/RUST.md) opens the checked-in fixture with no
+    // server at all -- `bench_client.rs` never references the `pinned`
+    // module this generates, so requiring a live server's host/port/token/
+    // CA to build it (as plain `transcript-screen` does, below) would be a
+    // pointless requirement for a build that talks to nothing.
+    if std::env::var_os("CARGO_FEATURE_BENCH").is_some() {
+        return;
+    }
+    println!("cargo:rerun-if-env-changed=AI_APP_TRANSCRIPT_HOST");
+    println!("cargo:rerun-if-env-changed=AI_APP_TRANSCRIPT_PORT");
+    println!("cargo:rerun-if-env-changed=AI_APP_TRANSCRIPT_TOKEN");
+    println!("cargo:rerun-if-env-changed=AI_APP_CA");
+    println!("cargo:rerun-if-env-changed=XDG_CONFIG_HOME");
+
+    let host = require_env(
+        "AI_APP_TRANSCRIPT_HOST",
+        "the sandbox server's host as the emulator reaches it, e.g. 10.0.2.2",
+    );
+    let port = require_env(
+        "AI_APP_TRANSCRIPT_PORT",
+        "the sandbox server's port -- app/ui-sandbox.sh's start banner prints it",
+    );
+    let token = require_env(
+        "AI_APP_TRANSCRIPT_TOKEN",
+        "the bearer token -- ~/.config/ai-app/sandbox-token, or the start banner's enrollment link",
+    );
+
+    let ca_path = std::env::var_os("AI_APP_CA")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            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").join("certs").join("ca.pem")
+        });
+    let ca_pem = std::fs::read_to_string(&ca_path).unwrap_or_else(|e| {
+        panic!(
+            "no CA certificate at {} ({e}).\n\
+             Start ai-server (or app/ui-sandbox.sh) once on this machine first -- it \
+             generates the CA this build pins. Set AI_APP_CA=/path/to/ca.pem to build \
+             against a different one.",
+            ca_path.display()
+        )
+    });
+    let ca_pem = ca_pem.trim();
+    if !ca_pem.starts_with("-----BEGIN CERTIFICATE-----") {
+        panic!("{} is not a PEM certificate.", ca_path.display());
+    }
+
+    let out_dir = PathBuf::from(std::env::var_os("OUT_DIR").unwrap());
+    let generated = format!(
+        "// Generated by build.rs from {host}:{port} and {ca}. Do not edit.\n\
+         pub const HOST: &str = {host_lit:?};\n\
+         pub const PORT: u16 = {port};\n\
+         pub const TOKEN: &str = {token_lit:?};\n\
+         pub const CA_PEM: &str = {ca_lit:?};\n",
+        host = host,
+        port = port
+            .parse::<u16>()
+            .unwrap_or_else(|e| panic!("AI_APP_TRANSCRIPT_PORT={port:?} is not a u16: {e}")),
+        ca = ca_path.display(),
+        host_lit = host,
+        token_lit = token,
+        ca_lit = ca_pem,
+    );
+    std::fs::write(out_dir.join("pinned_config.rs"), generated).unwrap();
+}
+
+fn require_env(name: &str, what: &str) -> String {
+    std::env::var(name).unwrap_or_else(|_| {
+        panic!("{name} must be set to build the transcript-screen feature -- {what}")
+    })
+}

iris/android-app/run-bench.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+# Installs and runs the iris `bench` build on this checkout's own emulator
+# (per this-machine-android's per-checkout-AVD rule; `emu serial` picks it)
+# and prints the report -- the iris half of `app/transcript-bench.sh`'s
+# job. No coordinates: the button is found by its accessibility label
+# through `ui-trace`, per AGENTS.md's "Driving the UI".
+#
+# Usage: ./run-bench.sh [--apk PATH]
+#   Defaults to this checkout's own release APK
+#   (app/build/outputs/apk/release/app-release.apk) if it exists, else the
+#   debug one -- build one first with ./build-apk.sh.
+set -eu
+cd "$(dirname "$0")"
+
+APK=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --apk) APK="$2"; shift 2 ;;
+        *) echo "run-bench.sh: unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+if [ -z "$APK" ]; then
+    if [ -f app/build/outputs/apk/release/app-release.apk ]; then
+        APK=app/build/outputs/apk/release/app-release.apk
+    else
+        APK=app/build/outputs/apk/debug/app-debug.apk
+    fi
+fi
+if [ ! -f "$APK" ]; then
+    echo "run-bench.sh: no APK at $APK -- run ./build-apk.sh first" >&2
+    exit 1
+fi
+
+SERIAL=$(emu serial)
+PKG=$(aapt2 dump badging "$APK" 2>/dev/null | sed -n "s/^package: name='\\([^']*\\)'.*/\\1/p")
+if [ -z "$PKG" ]; then
+    BUILD_TOOLS=$(ls -d "$HOME"/Android/Sdk/build-tools/*/ | sort -V | tail -1)
+    PKG=$("${BUILD_TOOLS}aapt2" dump badging "$APK" | sed -n "s/^package: name='\\([^']*\\)'.*/\\1/p")
+fi
+
+echo "run-bench.sh: installing $APK ($PKG) on $SERIAL"
+adb -s "$SERIAL" install -r "$APK" >/dev/null
+adb -s "$SERIAL" shell am force-stop "$PKG"
+adb -s "$SERIAL" logcat -c
+adb -s "$SERIAL" shell am start -n "$PKG/dev.iris.android.demo.MainActivity" >/dev/null
+
+ui-trace record -s "$SERIAL" -d 3000 --do "tap 'Run benchmark'" -o /tmp/run-bench-tap.txt >/dev/null
+
+# Poll for the report line rather than a fixed sleep -- the run itself is
+# a fixed script (RUST.md's "Benchmark v2": 16 flings, a 20s streaming
+# phase, ~61s of typing, 10s of keyboard toggles, roughly 2.5 minutes end
+# to end) but device speed varies. 260s cap rather than v1's 90s -- v2 is
+# a longer script than v1's swipe-loop-only run.
+i=0
+while [ "$i" -lt 260 ]; do
+    LINE=$(adb -s "$SERIAL" logcat -d -s iris-android-app:I 2>/dev/null | grep "iris bench report:" || true)
+    if [ -n "$LINE" ]; then
+        break
+    fi
+    i=$((i + 1))
+    sleep 1
+done
+if [ -z "$LINE" ]; then
+    echo "run-bench.sh: no report after 260s -- check logcat by hand" >&2
+    exit 1
+fi
+# -A 60 rather than v1's -A 6 -- v2's report has a per-phase block (four
+# phases, four lines each) on top of the frames/bench sections v1 had.
+adb -s "$SERIAL" logcat -d -s iris-android-app:I | grep -A 60 "iris bench report:"

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

@@ -0,0 +1,1000 @@
+//! P0's iris half (docs/RUST.md's P0 box, docs/AGENTS.md's "The rigs"):
+//! the same fixture, scroll loop and streaming phase the Compose `bench`
+//! build type's `BenchRun.kt`/`BenchFixture.kt` drive, run here against
+//! `transcript-ui`'s real screen with no server -- a frame-time comparison
+//! that measures the renderer rather than the data or the network.
+//!
+//! **Reuses `transcript_client.rs`'s shape** (folded items, the same
+//! `TranscriptScreen::apply` incremental update on every event) with the
+//! network half replaced by the checked-in fixture, embedded with
+//! `include_str!` -- `app/bench-fixture/assets/transcript.jsonl`,
+//! 1,915,760 bytes, generated by `app/bench-fixture/generate.py` and never
+//! a real transcript (that file's own README). The first 3,200 lines are
+//! the opening backlog, folded once through
+//! `client_core::transcript_fold::fold_page` exactly as a real
+//! `/transcript` page would be (then a full `transcript_ui::build_tree`,
+//! same as any first load); the remaining ~400 are the streaming tail,
+//! replayed one at a time through `fold_event` -- the same fold path a
+//! live SSE reply arrives on -- by the "Run benchmark" control below.
+//! Streaming through `apply` rather than a full rebuild per event is what
+//! this file exists to measure -- see docs/RUST.md's P0 box for the
+//! before/after report.
+
+use crate::bench_jni::PlatformHandle;
+use android_view::jni::{JavaVM, objects::GlobalRef};
+use client_core::transcript_fold::{TranscriptItem, fold_event, fold_page, group_tool_runs};
+use event_model::SeqEvent;
+use iris::android::{AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState};
+use iris::prelude::*;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+/// bench-fixture/README.md: the first `BACKLOG_COUNT` non-blank lines are
+/// the opening window; the rest are the streaming tail. Kept in sync with
+/// `BenchFixture.kt`'s identical constant by hand -- both read the same
+/// checked-in file, so a mismatch would only mean the two apps' bench
+/// builds open a different split of it, not a wrong-vs-right answer.
+const BACKLOG_COUNT: usize = 3200;
+
+/// RUST.md's "Benchmark v2" spec, written once so both apps' bench clients
+/// implement the identical four phases -- see that box before changing any
+/// constant here, since a mismatch would make the two reports stop
+/// measuring the same thing while still looking like they do.
+const STREAM_EVENTS_PER_SEC: u64 = 20;
+const STREAM_SECONDS: u64 = 20;
+
+/// Kept only so this phase's own label text still reads "scroll: 6 cycles
+/// (24 swipes, legacy tween)" the way `BenchRun.kt`'s v2 report does --
+/// `docs/bench/compose-phone-v2-2026-09-06.md`'s own report shows this
+/// exact line even though the swipe loop it names no longer runs there
+/// either (the fling phase replaced it); nothing here drives an actual
+/// swipe with these any more.
+const LEGACY_CYCLES: usize = 6;
+
+/// Fling phase (v2): a real fling through `List::fling`, not a tween --
+/// Iris's ask was that it "travel way faster" than the v1 swipe, and a
+/// tween can never exceed the distance/time it is given while a real
+/// fling decays from an initial velocity the way a finger flick does.
+/// 12,000 px/s matches `BenchRun.kt`'s own constant exactly.
+const FLING_VELOCITY_PX_S: f32 = 12_000.0;
+const FLING_COUNT: usize = 8;
+const FLING_SETTLE_CAP_MS: u64 = 3_000;
+const FLING_PAUSE_MS: u64 = 300;
+
+/// Type phase (v2): long, multisyllabic words so the composer actually
+/// wraps and the transcript above it is pushed upward, typed and deleted
+/// one character per `TYPE_CHAR_MS`. Exactly `BenchRun.TYPE_TEXT` --
+/// verified 600 characters by `type_text_is_exactly_600_characters` below.
+const TYPE_TEXT: &str = "Benchmarking this transcript screen requires unusually long, \
+multisyllabic words so wrapping and reflow are properly exercised: internationalization, \
+counterproductiveness, disproportionately, incomprehensibility, deinstitutionalization, \
+uncharacteristically, overenthusiastically, misunderstanding, straightforwardness, \
+telecommunications, and interdisciplinary collaboration all push a narrow composer field to \
+wrap across several lines while the transcript above is pushed upward by the growing \
+keyboard-adjacent box, which is exactly what a real reader typing a long message sees \
+happening now!!!";
+const TYPE_CHAR_MS: u64 = 50;
+
+/// Keyboard phase (v2): five show/hide cycles, a second apart, matching
+/// `BenchRun.kt`'s `KEYBOARD_CYCLES`/`KEYBOARD_SHOW_WAIT_MS`/
+/// `KEYBOARD_HIDE_WAIT_MS`.
+const KEYBOARD_CYCLES: usize = 5;
+const KEYBOARD_WAIT_MS: u64 = 1_000;
+
+/// One animation step's target cadence -- close enough to 60Hz that a
+/// fling/scroll is many small moves rather than one jump, so frames are
+/// actually rendered along the way, and close enough that a `ctx.update`
+/// closure's effect (only applied once the next frame callback drains the
+/// task channel -- `IrisViewPeer::drain_tasks`) is visible again quickly
+/// when a later step in the same phase needs to read state back.
+const ANIM_STEP_MS: u64 = 16;
+
+const FIXTURE_JSONL: &str = include_str!("../../../app/bench-fixture/assets/transcript.jsonl");
+
+pub struct BenchClient {
+    ui_state: AndroidUiState,
+    content: WeakWidget<WidgetPtr>,
+    report_display: WeakWidget<TextEdit>,
+    /// The top button row, in a `WidgetPtr` slot rather than added
+    /// directly (like `content`) so `on_insets_changed` can swap in a
+    /// version padded for the status bar once insets are known -- RUST.md's
+    /// P0 box, "the status-bar inset is not applied," found the row sitting
+    /// directly under it because nothing here read `insets().top` at all.
+    top_bar: WeakWidget<WidgetPtr>,
+    screen: Option<transcript_ui::TranscriptScreen>,
+    items: Vec<TranscriptItem>,
+    /// The events not yet streamed -- consumed by `start_benchmark`'s own
+    /// clone, kept here only as the source a second run would need (the
+    /// button can be pressed more than once; `running` just stops overlap,
+    /// not repeat).
+    stream_tail: Vec<SeqEvent>,
+    platform: Option<Arc<PlatformHandle>>,
+    last_report: Option<String>,
+    running: bool,
+    /// The keyboard phase's own confirmation channel -- updated from
+    /// `on_insets_changed` (the platform's own answer for whether the IME
+    /// is actually visible, per `WindowInsets::ime_bottom`), read from the
+    /// benchmark's spawned task via the shared `Arc<Mutex<_>>` rather than
+    /// `ctx.update`, since neither side needs the widget tree for this.
+    ime_state: Arc<Mutex<ImeState>>,
+    /// Edge-triggers the keyboard diagnostics capture below -- set on the
+    /// first `on_insets_changed` where `ime_bottom > 0.0`, cleared on the
+    /// first where it is not, so opening the keyboard fires this once
+    /// rather than on every insets update while it stays open (a rotation
+    /// or a status-bar change with the keyboard already up would otherwise
+    /// re-fire it).
+    keyboard_was_visible: bool,
+    /// The status-bar inset `top_bar` was last padded by -- see
+    /// `on_insets_changed`'s own comment for why this guards the rebuild.
+    last_top_pad: f32,
+}
+
+/// See `BenchClient::ime_state`'s doc. `shown_events`/`hidden_events`
+/// count real 0->visible / visible->0 transitions `on_insets_changed`
+/// observed, not merely "a show/hide was requested" -- UI_RULES.md: never
+/// present an inferred value as a measured one. `run_keyboard_phase` reads
+/// the counters before and after asking for a toggle and calls it
+/// confirmed only if the count moved.
+#[derive(Default)]
+struct ImeState {
+    visible: bool,
+    shown_events: u32,
+    hidden_events: u32,
+}
+
+impl HasAndroidUiState for BenchClient {
+    fn android_state(&self) -> &AndroidUiState {
+        &self.ui_state
+    }
+    fn android_state_mut(&mut self) -> &mut AndroidUiState {
+        &mut self.ui_state
+    }
+}
+
+/// Parses the fixture once: `serde_json::Value`s for the backlog
+/// (`fold_page` takes a page of raw wire JSON, same as a real
+/// `/transcript` response) and folded `SeqEvent`s for the tail (`fold_event`
+/// takes one live wire event at a time, same as a real SSE frame).
+fn parse_fixture() -> (Vec<serde_json::Value>, Vec<SeqEvent>) {
+    let lines: Vec<&str> = FIXTURE_JSONL
+        .lines()
+        .filter(|line| !line.trim().is_empty())
+        .collect();
+    let mut backlog = Vec::with_capacity(BACKLOG_COUNT.min(lines.len()));
+    let mut stream_tail = Vec::new();
+    for (i, line) in lines.iter().enumerate() {
+        let value: serde_json::Value =
+            serde_json::from_str(line).expect("bench fixture is generated JSON, always valid");
+        if i < BACKLOG_COUNT {
+            backlog.push(value);
+        } else {
+            let event: SeqEvent = serde_json::from_value(value)
+                .expect("bench fixture event matches event-model's SeqEvent");
+            stream_tail.push(event);
+        }
+    }
+    (backlog, stream_tail)
+}
+
+fn placeholder<Rsc: HasEvents>(rsc: &mut Rsc, message: &str) -> StrongWidget {
+    wtext(message.to_string())
+        .color(Color::WHITE)
+        .wrap(true)
+        .pad(16)
+        .add_strong(rsc)
+        .any()
+}
+
+/// `getrusage(RUSAGE_SELF)`'s user+system time, in ms -- `None` only if
+/// the syscall itself fails, which UI_RULES.md's "never present an
+/// inferred value as a measured one" says to keep apart from a real (and
+/// here, impossible) zero.
+fn process_cpu_ms() -> Option<u64> {
+    // SAFETY: `rusage` is a plain-old-data struct `getrusage` fully
+    // initialises on success; on failure it is never read.
+    unsafe {
+        let mut usage: libc::rusage = std::mem::zeroed();
+        if libc::getrusage(libc::RUSAGE_SELF, &mut usage) != 0 {
+            return None;
+        }
+        let user_ms = usage.ru_utime.tv_sec as u64 * 1000 + usage.ru_utime.tv_usec as u64 / 1000;
+        let sys_ms = usage.ru_stime.tv_sec as u64 * 1000 + usage.ru_stime.tv_usec as u64 / 1000;
+        Some(user_ms + sys_ms)
+    }
+}
+
+/// `VmHWM` from `/proc/self/status` -- the process's peak RSS since it
+/// started, in kB. Same source `BenchRun.kt`'s `peakRssLine` reads, so the
+/// two reports' numbers mean the same thing.
+fn peak_rss_kb() -> Option<u64> {
+    std::fs::read_to_string("/proc/self/status")
+        .ok()?
+        .lines()
+        .find_map(|line| line.strip_prefix("VmHWM:"))
+        .and_then(|rest| rest.trim().strip_suffix("kB"))
+        .and_then(|n| n.trim().parse().ok())
+}
+
+fn battery_line(samples: &[i32]) -> String {
+    if samples.is_empty() {
+        return "  battery current: unavailable on this device".to_string();
+    }
+    let mean = samples.iter().map(|&v| v as i64).sum::<i64>() / samples.len() as i64;
+    let min = samples.iter().min().unwrap();
+    let max = samples.iter().max().unwrap();
+    format!(
+        "  battery current: mean {mean}\u{b5}A over {} samples (min {min}, max {max})",
+        samples.len()
+    )
+}
+
+impl AndroidAppState for BenchClient {
+    fn new(mut ui_state: AndroidUiState, rsc: &mut AndroidRsc<Self>) -> Self {
+        let content = WidgetPtr::new().add(rsc);
+        let loading = placeholder(rsc, "Loading fixture...");
+        content(rsc).set(loading);
+
+        let report_display = wtext("")
+            .editable(EditMode::MultiLine)
+            .text_align(Align::LEFT)
+            .wrap(true)
+            .size(14)
+            .color(Color::WHITE)
+            .attr::<Selectable>(())
+            .label("Benchmark report")
+            .add(rsc);
+
+        let top_bar = WidgetPtr::new().add(rsc);
+        let controls = bench_controls(rsc, 0.0);
+        top_bar(rsc).set(controls);
+        let tree = (
+            top_bar,
+            content.height(rest(2)),
+            report_display.height(rest(1)).pad(dp(8)),
+        )
+            .span(Dir::DOWN)
+            .add_strong(rsc)
+            .any();
+        ui_state.set_root(tree);
+
+        // Startup log line (RUST.md's P0 box, "log once at startup ... the
+        // number of font families found, the default family resolved"):
+        // what font discovery actually found on this device, before
+        // anything is drawn.
+        let font = rsc.ui.text.font_diagnostics();
+        log::info!(
+            "iris fonts: {} families found, default={:?} mono={:?}, resolved regular={:?} \
+             bold={:?} italic={:?} mono={:?}",
+            font.families_found,
+            font.default_family,
+            font.default_mono_family,
+            font.regular_resolved,
+            font.bold_resolved,
+            font.italic_resolved,
+            font.mono_resolved,
+        );
+
+        let mut client = Self {
+            ui_state,
+            content,
+            report_display,
+            top_bar,
+            screen: None,
+            items: Vec::new(),
+            stream_tail: Vec::new(),
+            platform: None,
+            last_report: None,
+            running: false,
+            ime_state: Arc::new(Mutex::new(ImeState::default())),
+            keyboard_was_visible: false,
+            last_top_pad: 0.0,
+        };
+
+        let (backlog, stream_tail) = parse_fixture();
+        client.stream_tail = stream_tail;
+        match fold_page(&backlog) {
+            Ok(items) => {
+                client.items = items;
+                client.rebuild_transcript(rsc);
+            }
+            Err(message) => {
+                client.show_message(rsc, &format!("Couldn't fold the bench fixture: {message}"))
+            }
+        }
+        client
+    }
+
+    fn platform_ready(&mut self, _rsc: &mut AndroidRsc<Self>, vm: JavaVM, view: GlobalRef) {
+        self.platform = Some(Arc::new(PlatformHandle::new(vm, view)));
+    }
+
+    fn back_pressed(&mut self, _rsc: &mut AndroidRsc<Self>, _render: &mut UiRenderState) -> bool {
+        false
+    }
+
+    /// Pads the top button row by the status-bar inset -- see `top_bar`'s
+    /// field comment. Rebuilds the row rather than mutating a stored
+    /// `Padding` in place, since nothing here holds a handle to one --
+    /// but **only when `insets.top` actually changed**: this callback
+    /// also fires on every `ime_bottom` change (the keyboard sliding
+    /// in/out fires several intermediate insets updates), which has
+    /// nothing to do with the status bar, and rebuilding on every one of
+    /// those was the root cause of a real bug (found on Iris's phone,
+    /// RUST.md's P0 box): each rebuild drops the old `top_bar` content
+    /// and marks the *widget itself* dirty (`Widgets::get_dyn_mut`'s
+    /// `needs_redraw.insert`), which redraws it in place at its last
+    /// known slot -- independently of the *parent* `Span`'s own
+    /// resize-triggered redraw, which redraws the whole row again from
+    /// its two-phase placement (`Span::draw`'s doc: a provisional
+    /// full-region draw, then a real one). A `.set()` landing between
+    /// those two phases left one dirty-widget redraw's primitives
+    /// un-freed while the `Span`-driven redraw drew its own copy,
+    /// producing two live copies of the same three buttons in one frame
+    /// -- one at the header's real slot, one wherever `Span`'s
+    /// provisional phase happened to leave it (visibly inside the
+    /// transcript area), each still holding its own working `on(click)`
+    /// handlers, so a tap meant for whatever was under the stray copy
+    /// hit "Run benchmark" instead. Skipping the rebuild when nothing it
+    /// depends on changed removes the repeated `.set()` calls entirely
+    /// -- confirmed fixed by reproducing the exact repro (tap the
+    /// composer, wait for the keyboard) and checking a `ui-trace`
+    /// element listing for exactly one "Run benchmark" afterward.
+    ///
+    /// Also two things downstream of the same `ime_bottom` transition:
+    /// **the keyboard phase's own confirmation signal** (`ime_state`'s
+    /// doc -- the platform's own answer for whether the IME actually
+    /// opened or closed, rather than assumed from having called
+    /// `show_ime`/`hide_ime`), and **the trigger for the keyboard
+    /// diagnostics capture** (RUST.md's P0 box): the IME resizing the
+    /// surface is exactly the case a previous commit found wiped text,
+    /// and Iris needs a way to get a report off the phone even if that
+    /// (or some other keyboard-triggered regression) is still happening
+    /// on the build she is holding -- `capture_keyboard_diagnostics`
+    /// below fires ~500ms after the keyboard becomes visible, once per
+    /// keyboard opening, and shows its report in a plain overlay view
+    /// that draws independently of whatever iris itself is doing.
+    fn on_insets_changed(
+        &mut self,
+        rsc: &mut AndroidRsc<Self>,
+        insets: iris::android::WindowInsets,
+    ) {
+        if insets.top != self.last_top_pad {
+            self.last_top_pad = insets.top;
+            let controls = bench_controls(rsc, insets.top);
+            (self.top_bar)(rsc).set(controls);
+        }
+
+        // The composer bar sits directly on whichever of the IME or the
+        // navigation bar is currently the bottom of usable space -- see
+        // `transcript_ui::composer::Composer::set_bottom_inset`'s doc.
+        // `ime_bottom` already exceeds the plain nav-bar inset whenever the
+        // keyboard covers it, so the larger of the two is always the right
+        // answer without needing to know which is currently showing.
+        if let Some(screen) = &self.screen {
+            screen
+                .composer
+                .set_bottom_inset(rsc, insets.bottom.max(insets.ime_bottom));
+        }
+
+        let ime_visible = insets.ime_bottom > 0.0;
+
+        let mut ime = self.ime_state.lock().unwrap();
+        if ime_visible && !ime.visible {
+            ime.shown_events += 1;
+        }
+        if !ime_visible && ime.visible {
+            ime.hidden_events += 1;
+        }
+        ime.visible = ime_visible;
+        drop(ime);
+
+        if ime_visible && !self.keyboard_was_visible {
+            self.keyboard_was_visible = true;
+            let redraw = rsc.tasks.redraw_handle();
+            rsc.spawn_task(async move |mut ctx| {
+                tokio::time::sleep(Duration::from_millis(KEYBOARD_DIAGNOSTICS_DELAY_MS)).await;
+                ctx.update(|state: &mut BenchClient, rsc| {
+                    state.capture_keyboard_diagnostics(rsc);
+                });
+                redraw.request_redraw();
+            });
+        } else if !ime_visible {
+            self.keyboard_was_visible = false;
+        }
+    }
+}
+
+/// How long to wait after the keyboard becomes visible before capturing
+/// diagnostics -- long enough that the resize, the reported wipe (if it is
+/// still happening) and a couple of frames have all had time to land, per
+/// AGENTS.md's "so that operations that finish in milliseconds have states
+/// on the way that nothing can observe" reasoning applied the other way:
+/// this wants to observe the state *after* the transition settles, not
+/// mid-flight.
+const KEYBOARD_DIAGNOSTICS_DELAY_MS: u64 = 500;
+
+type Rsc = AndroidRsc<BenchClient>;
+
+/// The header row's own backdrop -- see `bench_controls`'s doc comment on
+/// why it needs one at all. A dark neutral rather than pure black
+/// (`android::render::CLEAR_COLOR`) so the row reads as a distinct panel
+/// instead of a hole in the background the buttons happen to float in.
+const HEADER_SURFACE: UiColor = UiColor::new(28, 28, 34, 255);
+
+/// `top_pad` is the status-bar inset in physical pixels (0.0 until
+/// `on_insets_changed` has run once) -- folded in here, rather than
+/// exposing the unadded builder for a caller to `.pad()` itself, because
+/// naming that builder's type at each call site is more machinery than a
+/// top-of-screen padding number is worth.
+///
+/// **Backed by an opaque rect the full size of the row, not just the three
+/// buttons.** Iris's phone report (docs/RUST.md's P0 box, screenshots on
+/// build a9232ac): "the header buttons have nothing behind them and
+/// overlap the transcript text" -- before this, only each button's own
+/// `rect(...)` painted anything, so the gaps between and around them (and
+/// the status-bar strip above them) showed whatever was one layer back
+/// (`CLEAR_COLOR`, black), and the row's true height was three
+/// physical-pixel-sized (`abs`, not `dp`) button boxes rather than the
+/// density-correct size the transcript below was already using post-P0 --
+/// exactly what reads as "overlap" once the two disagree. Fixed two ways
+/// together: a `HEADER_SURFACE` rect stacked behind the whole row (this
+/// function), and every size below moved from a bare number (physical
+/// pixels) to `dp(...)` (IRIS_TODO.md's density-independent length unit),
+/// so the row's reserved height in the outer `Span::DOWN`
+/// (`AndroidAppState::new`) matches what is actually painted.
+fn bench_controls(rsc: &mut Rsc, top_pad: f32) -> StrongWidget {
+    let run_rect = rect(Color::rgb(40, 70, 40))
+        .on(
+            CursorSense::click(),
+            |ctx: EventIdCtx<'_, Rsc, _, _>, rsc: &mut Rsc| {
+                ctx.state.start_benchmark(rsc);
+            },
+        )
+        .label("Run benchmark");
+    let run = (
+        run_rect,
+        wtext("Run benchmark").size(18).text_align(Align::CENTER),
+    )
+        .stack()
+        .pad(dp(8))
+        .add(rsc);
+
+    let copy_rect = rect(Color::rgb(50, 50, 60))
+        .on(
+            CursorSense::click(),
+            |ctx: EventIdCtx<'_, Rsc, _, _>, _rsc: &mut Rsc| {
+                ctx.state.copy_report();
+            },
+        )
+        .label("Copy report");
+    let copy = (
+        copy_rect,
+        wtext("Copy report").size(18).text_align(Align::CENTER),
+    )
+        .stack()
+        .pad(dp(8))
+        .add(rsc);
+
+    let diag_rect = rect(Color::rgb(60, 45, 70))
+        .on(
+            CursorSense::click(),
+            |ctx: EventIdCtx<'_, Rsc, _, _>, rsc: &mut Rsc| {
+                ctx.state.show_diagnostics(rsc);
+            },
+        )
+        .label("Diagnostics");
+    let diagnostics = (
+        diag_rect,
+        wtext("Diagnostics").size(18).text_align(Align::CENTER),
+    )
+        .stack()
+        .pad(dp(8))
+        .add(rsc);
+
+    let buttons = (run, copy, diagnostics).span(Dir::RIGHT).add(rsc);
+
+    (rect(HEADER_SURFACE), buttons)
+        .stack()
+        .height(dp(56))
+        .pad(Padding::top(top_pad))
+        .add_strong(rsc)
+        .any()
+}
+
+impl BenchClient {
+    fn show_message(&mut self, rsc: &mut Rsc, message: &str) {
+        let widget = placeholder(rsc, message);
+        (self.content)(rsc).set(widget);
+        self.screen = None;
+    }
+
+    fn rebuild_transcript(&mut self, rsc: &mut Rsc) {
+        let rows = group_tool_runs(&self.items);
+        let (screen, tree) = transcript_ui::build_tree(rsc, rows);
+        (self.content)(rsc).set(tree);
+        self.screen = Some(screen);
+    }
+
+    /// RUST.md's P0 box: "a named `Diagnostics` control ... with 'copy this
+    /// and send it to Iris'." Fills `report_display` (the same TextEdit the
+    /// benchmark report uses) rather than a separate widget, so the
+    /// existing "Copy report" button and clipboard path work on whichever
+    /// text is currently shown -- `last_report` is what `copy_report` reads,
+    /// so it's set here too rather than adding a second copy path.
+    fn show_diagnostics(&mut self, rsc: &mut Rsc) {
+        let font = rsc.ui.text.font_diagnostics();
+        let frame_report = match self.android_state().frame_report.report() {
+            Some(stats) => format!("{stats}"),
+            None => "no frames recorded yet".to_string(),
+        };
+        let report = match &self.android_state().renderer {
+            Some(renderer) => renderer.diagnostics_report(&font, &frame_report),
+            None => "iris diagnostics: no renderer yet (no surface)".to_string(),
+        };
+        self.report_display.edit(rsc).set(&report);
+        self.last_report = Some(report);
+    }
+
+    /// The keyboard's own diagnostics capture -- see `on_insets_changed`'s
+    /// doc comment. Reuses `show_diagnostics`'s exact report (so it is the
+    /// same text the on-screen `Diagnostics` button produces, plus the
+    /// per-frame log `FrameReport` already keeps around the resize --
+    /// `frame_report.report()` above covers "the frames around the
+    /// resize" without a second accounting mechanism), then does three
+    /// things the button does not: logs it (so a `logcat` pull gets it
+    /// even if nothing on screen does), copies it to the clipboard
+    /// unprompted, and shows it in the shell's plain overlay view, which
+    /// draws independently of iris's own renderer -- the whole point,
+    /// since the renderer is exactly what might be in the wiped state
+    /// this exists to report on.
+    fn capture_keyboard_diagnostics(&mut self, rsc: &mut Rsc) {
+        self.show_diagnostics(rsc);
+        let Some(report) = self.last_report.clone() else {
+            return;
+        };
+        log::info!("iris keyboard diagnostics:\n{report}");
+        let Some(platform) = &self.platform else {
+            log::info!("iris keyboard diagnostics: no platform handle, can't reach the shell");
+            return;
+        };
+        if platform.copy_to_clipboard("iris keyboard diagnostics", &report) {
+            log::info!("iris keyboard diagnostics: copied to clipboard");
+        } else {
+            log::info!("iris keyboard diagnostics: clipboard copy failed");
+        }
+        platform.show_diagnostics_overlay(&report);
+    }
+
+    fn copy_report(&mut self) {
+        let Some(report) = &self.last_report else {
+            log::info!("iris bench report: nothing to copy -- run the benchmark first");
+            return;
+        };
+        let Some(platform) = &self.platform else {
+            log::info!("iris bench report: no platform handle, can't reach the clipboard");
+            return;
+        };
+        if platform.copy_to_clipboard("iris bench report", report) {
+            log::info!("iris bench report: copied to clipboard");
+        } else {
+            log::info!("iris bench report: clipboard copy failed");
+        }
+    }
+
+    /// RUST.md's "Benchmark v2": fling, then stream (unchanged from v1),
+    /// then type, then keyboard, then the report -- run in-process for the
+    /// same reason `BenchRun.kt`'s own doc gives (no usable system tracing
+    /// on a real phone, no agent that can drive one).
+    fn start_benchmark(&mut self, rsc: &mut Rsc) {
+        if self.running {
+            log::info!("iris bench report: already running");
+            return;
+        }
+        self.running = true;
+        self.android_state_mut().frame_report.reset();
+        self.report_display.edit(rsc).set("Running benchmark...");
+
+        let redraw = rsc.tasks.redraw_handle();
+        let platform = self.platform.clone();
+        let stream_tail = self.stream_tail.clone();
+        let ime_state = self.ime_state.clone();
+        let refresh_hz = platform
+            .as_ref()
+            .and_then(|p| p.refresh_rate_hz())
+            .unwrap_or(60.0);
+        let cpu_start = process_cpu_ms();
+        let run_started_at = Instant::now();
+
+        rsc.spawn_task(async move |mut ctx| {
+            // The battery sampler runs for the whole run, once a second,
+            // the same cadence `BatterySampler` uses on the Compose side
+            // -- via its own JNI-attached thread, not `ctx.update`, since
+            // a sample needs no widget-tree access.
+            let sampler_done = Arc::new(AtomicBool::new(false));
+            let samples = Arc::new(Mutex::new(Vec::<i32>::new()));
+            let sampler = platform.clone().map(|platform| {
+                let done = sampler_done.clone();
+                let samples = samples.clone();
+                tokio::spawn(async move {
+                    while !done.load(Ordering::Relaxed) {
+                        if let Some(value) = platform.battery_current_ua() {
+                            samples.lock().unwrap().push(value);
+                        }
+                        tokio::time::sleep(Duration::from_secs(1)).await;
+                    }
+                })
+            });
+
+            let travel = run_fling_phase(&mut ctx, &redraw).await;
+            let (sent, total) = run_stream_phase(&mut ctx, &redraw, stream_tail).await;
+            run_type_phase(&mut ctx, &redraw, &platform).await;
+            let keyboard = run_keyboard_phase(&mut ctx, &platform, &ime_state).await;
+
+            sampler_done.store(true, Ordering::Relaxed);
+            if let Some(sampler) = sampler {
+                let _ = sampler.await;
+            }
+            let battery = battery_line(&samples.lock().unwrap());
+            let cpu_line = match (cpu_start, process_cpu_ms()) {
+                (Some(start), Some(end)) => {
+                    format!(
+                        "  process CPU time over this run: {}ms",
+                        end.saturating_sub(start)
+                    )
+                }
+                _ => "  process CPU time over this run: unavailable".to_string(),
+            };
+            let rss_line = match peak_rss_kb() {
+                Some(kb) => format!("  peak RSS: {kb}kB"),
+                None => "  peak RSS: unavailable (/proc/self/status unreadable)".to_string(),
+            };
+            let total_seconds = run_started_at.elapsed().as_secs_f64();
+
+            ctx.update(move |state: &mut BenchClient, rsc| {
+                state.running = false;
+                let now = Instant::now();
+                let phase_lines: String = state
+                    .android_state()
+                    .frame_report
+                    .phase_stats(now, refresh_hz)
+                    .iter()
+                    .map(|p| format!("{p}\n"))
+                    .collect();
+                let per_phase = if phase_lines.is_empty() {
+                    String::new()
+                } else {
+                    format!("per phase:\n{phase_lines}\n")
+                };
+                let frames_block = match state.android_state().frame_report.report() {
+                    Some(stats) => {
+                        let (late, late_pct) =
+                            state.android_state().frame_report.late_at_hz(refresh_hz);
+                        format!(
+                            "frames:\n  {} frames over {:.1}s at {:.0}Hz ({:.1}ms budget)\n  \
+                             late: {late} ({late_pct:.1}%)\n  total  p50 {:.1}ms  p90 {:.1}ms  \
+                             p99 {:.1}ms\n  worst {:.1}ms\n  cpu_p50 {:.1}ms  gpu_wait_p50 {:.1}ms",
+                            stats.total_frames,
+                            total_seconds,
+                            refresh_hz,
+                            1000.0 / refresh_hz as f64,
+                            stats.p50.as_secs_f64() * 1000.0,
+                            stats.p90.as_secs_f64() * 1000.0,
+                            stats.p99.as_secs_f64() * 1000.0,
+                            stats.worst.as_secs_f64() * 1000.0,
+                            stats.cpu_p50.as_secs_f64() * 1000.0,
+                            stats.gpu_wait_p50.as_secs_f64() * 1000.0,
+                        )
+                    }
+                    None => "frames:\n  no frames recorded".to_string(),
+                };
+                let scroll_line = format!(
+                    "  scroll: {LEGACY_CYCLES} cycles ({} swipes, legacy tween), streamed \
+                     {sent}/{total} fixture events",
+                    LEGACY_CYCLES * 4
+                );
+                let fling_line = format!(
+                    "  fling: {FLING_COUNT} flings out + {FLING_COUNT} back at \
+                     {FLING_VELOCITY_PX_S}px/s, travel {travel}"
+                );
+                let type_line = format!(
+                    "  type: {} characters inserted then deleted, one per {TYPE_CHAR_MS}ms",
+                    TYPE_TEXT.chars().count()
+                );
+                let report = format!(
+                    "iris bench report\n{per_phase}{frames_block}\n\nbench:\n{fling_line}\n\
+                     {scroll_line}\n{type_line}\n{keyboard}\n{cpu_line}\n{rss_line}\n{battery}"
+                );
+                log::info!("iris bench report: {report}");
+                state.report_display.edit(rsc).set(&report);
+                state.last_report = Some(report);
+            });
+            redraw.request_redraw();
+        });
+    }
+}
+
+/// Runs `f` against the real `BenchClient`/`Rsc` on the main thread (the
+/// same `ctx.update` every other mutation here goes through) and returns
+/// its result to the caller's async task -- `ctx.update` alone has no way
+/// to hand a value back, since the closure only actually runs once the
+/// next frame callback drains `IrisViewPeer`'s task channel
+/// (`drain_tasks`). **Must call `redraw.request_redraw()` itself, right
+/// after enqueueing** -- `ctx.update` only ever pushes onto a channel;
+/// nothing drains it until something schedules the frame callback that
+/// calls `drain_tasks`, and a caller relying on some *earlier*,
+/// already-in-flight `request_redraw()` to cover a *later* `ctx.update`
+/// deadlocks the moment that earlier callback has already fired and
+/// drained everything queued before this call existed. Cost a real hang
+/// in this file's first version of the fling phase: every loop iteration
+/// after the first sat forever with nothing scheduled to drain it.
+/// Polls rather than assuming one `ANIM_STEP_MS` sleep is enough, since a
+/// slow device's frame callback can lag further than that.
+async fn read_from_state<T, F>(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+    f: F,
+) -> T
+where
+    T: Send + 'static,
+    F: FnOnce(&mut BenchClient, &mut Rsc) -> T + Send + 'static,
+{
+    let (tx, rx) = std::sync::mpsc::channel();
+    ctx.update(move |state: &mut BenchClient, rsc| {
+        let _ = tx.send(f(state, rsc));
+    });
+    redraw.request_redraw();
+    loop {
+        if let Ok(value) = rx.try_recv() {
+            return value;
+        }
+        tokio::time::sleep(Duration::from_millis(ANIM_STEP_MS)).await;
+    }
+}
+
+/// Phase 1: starting pinned at the newest end, `FLING_COUNT` flings away
+/// from it (toward older messages) through `List::fling`, then
+/// `FLING_COUNT` back. Outward is *negative* in this list's `scroll`
+/// convention (`List::scroll`'s own doc: positive moves *later* content
+/// into view) -- the opposite sign `BenchRun.kt`'s `runFlingPhase` uses,
+/// since `TranscriptList`'s `LazyColumn` and this list define "positive"
+/// the other way around; the two apps' *travel* is still directly
+/// comparable because both report it as a row index + pixel offset, not a
+/// signed distance.
+async fn run_fling_phase(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+) -> String {
+    ctx.update(|state: &mut BenchClient, _rsc| {
+        state.android_state_mut().frame_report.mark_phase("fling");
+    });
+    ctx.update(|state: &mut BenchClient, rsc| {
+        if let Some(screen) = &state.screen {
+            (screen.list)(rsc).jump_to_end();
+        }
+    });
+    redraw.request_redraw();
+    // Lets the next frame's `repair_anchor` resolve `jump_to_end`'s
+    // `anchor = None` into a real slot before `start` is read.
+    tokio::time::sleep(Duration::from_millis(ANIM_STEP_MS * 2)).await;
+    let start = read_anchor_position(ctx, redraw).await;
+
+    for _ in 0..FLING_COUNT {
+        ctx.update(|state: &mut BenchClient, rsc| {
+            if let Some(screen) = &state.screen {
+                (screen.list)(rsc).fling(-FLING_VELOCITY_PX_S);
+            }
+        });
+        redraw.request_redraw();
+        wait_for_fling_settle(ctx, redraw).await;
+        tokio::time::sleep(Duration::from_millis(FLING_PAUSE_MS)).await;
+    }
+    let outward = read_anchor_position(ctx, redraw).await;
+
+    for _ in 0..FLING_COUNT {
+        ctx.update(|state: &mut BenchClient, rsc| {
+            if let Some(screen) = &state.screen {
+                (screen.list)(rsc).fling(FLING_VELOCITY_PX_S);
+            }
+        });
+        redraw.request_redraw();
+        wait_for_fling_settle(ctx, redraw).await;
+        tokio::time::sleep(Duration::from_millis(FLING_PAUSE_MS)).await;
+    }
+    let end = read_anchor_position(ctx, redraw).await;
+
+    format!("start={start} outward={outward} end={end}")
+}
+
+async fn read_anchor_position(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+) -> String {
+    read_from_state(ctx, redraw, |state, rsc| match &state.screen {
+        Some(screen) => (screen.list)(rsc).anchor_position_display(),
+        None => "idx=none".to_string(),
+    })
+    .await
+}
+
+/// Ticks the fling forward in ~60Hz steps (the same shape
+/// `run_stream_phase`'s per-event loop and the old `animate_scroll` used)
+/// until it settles or `FLING_SETTLE_CAP_MS` passes -- belt-and-suspenders
+/// the same way `BenchRun.kt`'s own `waitForSettle` is, since a fling's
+/// own spline-decided `duration()` already caps how long it can run.
+async fn wait_for_fling_settle(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+) {
+    let cap = Duration::from_millis(FLING_SETTLE_CAP_MS);
+    let started = Instant::now();
+    while started.elapsed() < cap {
+        let still_scrolling = read_from_state(ctx, redraw, |state, rsc| match &state.screen {
+            Some(screen) => (screen.list)(rsc).tick_fling(Instant::now()),
+            None => false,
+        })
+        .await;
+        if !still_scrolling {
+            return;
+        }
+        tokio::time::sleep(Duration::from_millis(ANIM_STEP_MS)).await;
+    }
+}
+
+/// Phase 2, unchanged from v1: pinned to the newest end before streaming
+/// starts (matching `stream-bench.sh`'s "Jump to latest" tap), then
+/// `STREAM_EVENTS_PER_SEC * STREAM_SECONDS` fixture events replayed
+/// through the real `fold_event`/`TranscriptScreen::apply` path. Returns
+/// `(sent, total)`.
+async fn run_stream_phase(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+    stream_tail: Vec<SeqEvent>,
+) -> (usize, usize) {
+    ctx.update(|state: &mut BenchClient, _rsc| {
+        state.android_state_mut().frame_report.mark_phase("stream");
+    });
+    ctx.update(|state: &mut BenchClient, rsc| {
+        if let Some(screen) = &state.screen {
+            (screen.list)(rsc).jump_to_end();
+        }
+    });
+    redraw.request_redraw();
+
+    let total = (STREAM_EVENTS_PER_SEC * STREAM_SECONDS) as usize;
+    let mut sent = 0usize;
+    for event in stream_tail.into_iter().take(total) {
+        ctx.update(move |state: &mut BenchClient, rsc| {
+            let old_items = state.items.clone();
+            state.items = fold_event(&state.items, &event);
+            match &state.screen {
+                Some(screen) => screen.apply(rsc, &old_items, &state.items),
+                None => state.rebuild_transcript(rsc),
+            }
+        });
+        redraw.request_redraw();
+        sent += 1;
+        tokio::time::sleep(Duration::from_millis(1000 / STREAM_EVENTS_PER_SEC)).await;
+    }
+    // Lets the last few deltas land and draw before the next phase starts
+    // -- `BenchRun.kt`'s own closing delay.
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    (sent, total)
+}
+
+/// Phase 3: focuses the real composer, shows the keyboard, then types
+/// `TYPE_TEXT` one character at a time through the composer `TextEdit`'s
+/// real edit path (`set`, the same call a real keystroke's `onValueChange`
+/// makes -- `Composer::build_composer`'s `field`), and deletes it the same
+/// way.
+async fn run_type_phase(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    redraw: &Arc<dyn RequestRedraw>,
+    platform: &Option<Arc<PlatformHandle>>,
+) {
+    ctx.update(|state: &mut BenchClient, _rsc| {
+        state.android_state_mut().frame_report.mark_phase("type");
+    });
+    ctx.update(|state: &mut BenchClient, rsc| {
+        if let Some(screen) = &state.screen {
+            (screen.list)(rsc).jump_to_end();
+            state.set_focus(Some(screen.composer.field));
+        }
+    });
+    redraw.request_redraw();
+    if let Some(p) = platform {
+        p.show_ime();
+    }
+    // Lets focus and the keyboard's opening animation land before typing
+    // starts, so the frames this phase records are the wrap/reflow it is
+    // measuring, not the keyboard opening -- `BenchRun.kt`'s own delay.
+    tokio::time::sleep(Duration::from_millis(300)).await;
+
+    let mut typed = String::new();
+    for ch in TYPE_TEXT.chars() {
+        typed.push(ch);
+        let text = typed.clone();
+        ctx.update(move |state: &mut BenchClient, rsc| {
+            if let Some(screen) = &state.screen {
+                screen.composer.field.edit(rsc).set(&text);
+            }
+        });
+        redraw.request_redraw();
+        tokio::time::sleep(Duration::from_millis(TYPE_CHAR_MS)).await;
+    }
+    tokio::time::sleep(Duration::from_millis(200)).await;
+    while !typed.is_empty() {
+        typed.pop();
+        let text = typed.clone();
+        ctx.update(move |state: &mut BenchClient, rsc| {
+            if let Some(screen) = &state.screen {
+                screen.composer.field.edit(rsc).set(&text);
+            }
+        });
+        redraw.request_redraw();
+        tokio::time::sleep(Duration::from_millis(TYPE_CHAR_MS)).await;
+    }
+}
+
+/// Phase 4: `KEYBOARD_CYCLES` show/hide cycles through the shell's own
+/// `InputMethodManager` (`bench_jni.rs`'s `show_ime`/`hide_ime`), each
+/// confirmed by `on_insets_changed`'s real `ime_bottom` transition rather
+/// than assumed from the JNI call having returned -- `ImeState`'s doc.
+/// "keyboard: could not be shown" if the platform never confirms it even
+/// once, per UI_RULES.md ("design the unknown/failed state before the
+/// answer's").
+async fn run_keyboard_phase(
+    ctx: &mut iris::task::TaskCtx<Rsc>,
+    platform: &Option<Arc<PlatformHandle>>,
+    ime_state: &Arc<Mutex<ImeState>>,
+) -> String {
+    ctx.update(|state: &mut BenchClient, _rsc| {
+        state
+            .android_state_mut()
+            .frame_report
+            .mark_phase("keyboard");
+    });
+    let mut shown = 0;
+    let mut hidden = 0;
+    for _ in 0..KEYBOARD_CYCLES {
+        let before_shown = ime_state.lock().unwrap().shown_events;
+        if let Some(p) = platform {
+            p.show_ime();
+        }
+        tokio::time::sleep(Duration::from_millis(KEYBOARD_WAIT_MS)).await;
+        if ime_state.lock().unwrap().shown_events > before_shown {
+            shown += 1;
+        }
+
+        let before_hidden = ime_state.lock().unwrap().hidden_events;
+        if let Some(p) = platform {
+            p.hide_ime();
+        }
+        tokio::time::sleep(Duration::from_millis(KEYBOARD_WAIT_MS)).await;
+        if ime_state.lock().unwrap().hidden_events > before_hidden {
+            hidden += 1;
+        }
+    }
+    if shown == 0 {
+        format!("  keyboard: could not be shown ({KEYBOARD_CYCLES} attempts, 0 confirmed visible)")
+    } else {
+        format!(
+            "  keyboard: shown {shown}/{KEYBOARD_CYCLES}, hidden {hidden}/{KEYBOARD_CYCLES} \
+             (confirmed via on_insets_changed)"
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::TYPE_TEXT;
+
+    /// `BenchRun.kt`'s own `TYPE_TEXT` is verified `.length == 600`; this
+    /// is the same string, so it has to match exactly or the two apps'
+    /// type phases stop typing the same content -- RUST.md's "Benchmark
+    /// v2" spec is one shared string for both.
+    #[test]
+    fn type_text_is_exactly_600_characters() {
+        assert_eq!(TYPE_TEXT.chars().count(), 600);
+    }
+}

iris/android-app/src/bench_jni.rs

@@ -0,0 +1,252 @@
+//! JNI calls the `bench` feature needs that go through the shell's own
+//! Java side rather than anything `iris`/`android-view` already wraps:
+//! `BatteryManager.getIntProperty(BATTERY_PROPERTY_CURRENT_NOW)` for the
+//! per-second battery sample, `ClipboardManager.setPrimaryClip` for the
+//! "Copy report" control (P0's iris half, docs/RUST.md), and -- added for
+//! RUST.md's "Benchmark v2" -- `Display.getRefreshRate()` for the phase
+//! report's real late-frame budget and `InputMethodManager.
+//! showSoftInput`/`hideSoftInputFromWindow` for the keyboard phase. None
+//! of these are part of `android_view::context`'s own `Context`/
+//! `Resources` wrappers (that file's own `// TODO: more methods?`), so
+//! this calls them directly rather than growing that crate's wrapper for
+//! calls this crate alone needs.
+//!
+//! Holds its own `JavaVM` + `GlobalRef` to the view (handed in through
+//! [`iris::android::AndroidAppState::platform_ready`]) so it can attach
+//! whichever thread calls it -- the battery sampler runs on a background
+//! tokio task, not the UI thread the rest of `IrisViewPeer`'s JNI calls
+//! run on. `JavaVM::attach_current_thread` is safe to call from a thread
+//! already attached (the `jni` crate detects it and does not double
+//! attach), so no caller here needs to know or care which thread it is.
+
+use android_view::jni::{
+    JNIEnv, JavaVM,
+    objects::{GlobalRef, JObject, JValue},
+};
+
+/// `android.os.BatteryManager.BATTERY_PROPERTY_CURRENT_NOW` -- not exposed
+/// as a constant anywhere reachable without the Android SDK jar, so named
+/// here with its source rather than left as a bare `2`.
+const BATTERY_PROPERTY_CURRENT_NOW: i32 = 2;
+
+pub struct PlatformHandle {
+    vm: JavaVM,
+    view: GlobalRef,
+}
+
+impl PlatformHandle {
+    pub fn new(vm: JavaVM, view: GlobalRef) -> Self {
+        Self { vm, view }
+    }
+
+    fn context<'e>(&self, env: &mut JNIEnv<'e>) -> Option<JObject<'e>> {
+        env.call_method(
+            self.view.as_obj(),
+            "getContext",
+            "()Landroid/content/Context;",
+            &[],
+        )
+        .ok()?
+        .l()
+        .ok()
+    }
+
+    fn system_service<'e>(
+        &self,
+        env: &mut JNIEnv<'e>,
+        context: &JObject<'e>,
+        name: &str,
+    ) -> Option<JObject<'e>> {
+        let jname = env.new_string(name).ok()?;
+        env.call_method(
+            context,
+            "getSystemService",
+            "(Ljava/lang/String;)Ljava/lang/Object;",
+            &[JValue::Object(jname.as_ref())],
+        )
+        .ok()?
+        .l()
+        .ok()
+    }
+
+    /// One sample of `BATTERY_PROPERTY_CURRENT_NOW`, in microamps. `None`
+    /// on any JNI failure, on a device with no `BatteryManager` service,
+    /// or when the platform itself answers "not supported" -- `0` or
+    /// `Integer.MIN_VALUE` are both documented SDK answers for that, and
+    /// both would read as a real (and wrong) measurement if folded into an
+    /// average rather than named apart. UI_RULES.md: never present an
+    /// inferred value as a measured one.
+    pub fn battery_current_ua(&self) -> Option<i32> {
+        let mut guard = self.vm.attach_current_thread().ok()?;
+        let env: &mut JNIEnv = &mut guard;
+        let context = self.context(env)?;
+        let battery_manager = self.system_service(env, &context, "batterymanager")?;
+        let value = env
+            .call_method(
+                &battery_manager,
+                "getIntProperty",
+                "(I)I",
+                &[JValue::Int(BATTERY_PROPERTY_CURRENT_NOW)],
+            )
+            .ok()?
+            .i()
+            .ok()?;
+        if value == 0 || value == i32::MIN {
+            None
+        } else {
+            Some(value)
+        }
+    }
+
+    /// Puts `text` on the system clipboard through `ClipboardManager` --
+    /// `true` only if the whole JNI chain (service lookup, `ClipData`,
+    /// `setPrimaryClip`) succeeded.
+    pub fn copy_to_clipboard(&self, label: &str, text: &str) -> bool {
+        self.try_copy_to_clipboard(label, text).is_some()
+    }
+
+    fn try_copy_to_clipboard(&self, label: &str, text: &str) -> Option<()> {
+        let mut guard = self.vm.attach_current_thread().ok()?;
+        let env: &mut JNIEnv = &mut guard;
+        let context = self.context(env)?;
+        let clipboard = self.system_service(env, &context, "clipboard")?;
+        let jlabel = env.new_string(label).ok()?;
+        let jtext = env.new_string(text).ok()?;
+        let clip = env
+            .call_static_method(
+                "android/content/ClipData",
+                "newPlainText",
+                "(Ljava/lang/CharSequence;Ljava/lang/CharSequence;)Landroid/content/ClipData;",
+                &[
+                    JValue::Object(jlabel.as_ref()),
+                    JValue::Object(jtext.as_ref()),
+                ],
+            )
+            .ok()?
+            .l()
+            .ok()?;
+        env.call_method(
+            &clipboard,
+            "setPrimaryClip",
+            "(Landroid/content/ClipData;)V",
+            &[JValue::Object(&clip)],
+        )
+        .ok()?;
+        Some(())
+    }
+
+    /// The display's own refresh rate in Hz (`View::getDisplay()` ->
+    /// `Display::getRefreshRate()`), for RUST.md's "Benchmark v2": late
+    /// frames are judged against *this* device's real budget, not an
+    /// assumed 60Hz -- a 90Hz or 120Hz phone would otherwise call frames
+    /// "late" that met their own faster deadline. `None` if the view is
+    /// not yet attached to a window (`getDisplay` returns `null`) or the
+    /// platform reports a non-positive rate, which is not a real answer
+    /// either.
+    pub fn refresh_rate_hz(&self) -> Option<f32> {
+        let mut guard = self.vm.attach_current_thread().ok()?;
+        let env: &mut JNIEnv = &mut guard;
+        let display = env
+            .call_method(
+                self.view.as_obj(),
+                "getDisplay",
+                "()Landroid/view/Display;",
+                &[],
+            )
+            .ok()?
+            .l()
+            .ok()?;
+        if display.is_null() {
+            return None;
+        }
+        let rate = env
+            .call_method(&display, "getRefreshRate", "()F", &[])
+            .ok()?
+            .f()
+            .ok()?;
+        if rate > 0.0 { Some(rate) } else { None }
+    }
+
+    /// `InputMethodManager.showSoftInput(view, 0)` -- the keyboard phase's
+    /// own show, called directly rather than through the focus-driven
+    /// `pending_show_keyboard` path `android/view.rs` uses for a real tap,
+    /// since RUST.md's "Benchmark v2" spec asks for this "through the
+    /// shell's InputMethodManager" independent of focus state. `true` only
+    /// if the platform itself reports the request succeeded -- whether the
+    /// IME actually became visible is confirmed separately, from
+    /// `on_insets_changed`, per UI_RULES.md ("never present an inferred
+    /// value as a measured one").
+    pub fn show_ime(&self) -> bool {
+        self.try_toggle_ime(true).unwrap_or(false)
+    }
+
+    /// `InputMethodManager.hideSoftInputFromWindow(windowToken, 0)`.
+    pub fn hide_ime(&self) -> bool {
+        self.try_toggle_ime(false).unwrap_or(false)
+    }
+
+    fn try_toggle_ime(&self, show: bool) -> Option<bool> {
+        let mut guard = self.vm.attach_current_thread().ok()?;
+        let env: &mut JNIEnv = &mut guard;
+        let context = self.context(env)?;
+        let imm = self.system_service(env, &context, "input_method")?;
+        if show {
+            env.call_method(
+                &imm,
+                "showSoftInput",
+                "(Landroid/view/View;I)Z",
+                &[JValue::Object(self.view.as_obj()), JValue::Int(0)],
+            )
+            .ok()?
+            .z()
+            .ok()
+        } else {
+            let token = env
+                .call_method(
+                    self.view.as_obj(),
+                    "getWindowToken",
+                    "()Landroid/os/IBinder;",
+                    &[],
+                )
+                .ok()?
+                .l()
+                .ok()?;
+            env.call_method(
+                &imm,
+                "hideSoftInputFromWindow",
+                "(Landroid/os/IBinder;I)Z",
+                &[JValue::Object(&token), JValue::Int(0)],
+            )
+            .ok()?
+            .z()
+            .ok()
+        }
+    }
+
+    /// Shows `report` in the shell's plain-view diagnostics overlay
+    /// (`IrisView.showDiagnosticsOverlay`) -- a real `TextView` plus Copy
+    /// and Close controls, added over whatever iris itself is drawing
+    /// rather than replacing it (unlike `android::view::show_renderer_error`,
+    /// which exists for the case the renderer can never recover from and
+    /// intentionally never returns). Called from a background task after
+    /// the keyboard-open delay (`bench_client.rs`'s `on_insets_changed`),
+    /// so the Java side hops onto the UI thread itself before touching the
+    /// view tree -- see that method's own comment.
+    pub fn show_diagnostics_overlay(&self, report: &str) -> bool {
+        self.try_show_diagnostics_overlay(report).is_some()
+    }
+
+    fn try_show_diagnostics_overlay(&self, report: &str) -> Option<()> {
+        let mut guard = self.vm.attach_current_thread().ok()?;
+        let env: &mut JNIEnv = &mut guard;
+        let jreport = env.new_string(report).ok()?;
+        env.call_method(
+            self.view.as_obj(),
+            "showDiagnosticsOverlay",
+            "(Ljava/lang/String;)V",
+            &[JValue::Object(jreport.as_ref())],
+        )
+        .ok()?;
+        Some(())
+    }
+}

iris/android-app/src/lib.rs

@@ -0,0 +1,132 @@
+//! The android-view demo app: by default, 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.
+//!
+//! **`transcript-screen` feature (RUST.md's I5 Android integration):** with
+//! `--features transcript-screen`, `new_view_peer` instantiates
+//! `transcript_client::TranscriptClient` instead of the tabs `Client`
+//! below, against a real `ai-server` (see that module's doc). Chosen over a
+//! third shell crate: this one already has the Gradle project, the
+//! `IrisView`/`MainActivity` Java, and the JNI registration I2 built and
+//! measured against, and the only thing a transcript screen needs on top
+//! is a different `AndroidAppState` -- the same axis `tabs_ui::build` vs.
+//! `transcript_ui::build` already varies along on the winit side (compare
+//! `iris/examples/tabs.rs` and `iris/transcript-ui/examples/transcript.rs`).
+//! A build picks one screen or the other, never both, so `Client` and
+//! `TranscriptClient` are cfg-gated apart rather than switched at runtime --
+//! there is no in-app navigation to switch *to* on either side yet.
+//!
+//! **`bench` feature (P0's iris half, docs/RUST.md):** a third
+//! `AndroidAppState`, `bench_client::BenchClient`, on the same axis --
+//! `transcript_ui::build_tree` again, this time against the checked-in
+//! fixture (`app/bench-fixture/assets/transcript.jsonl`) instead of a real
+//! server, with a "Run benchmark" control that drives the same scroll loop
+//! and streaming phase the Compose `bench` build type's `BenchRun.kt`
+//! does. `bench` depends on `transcript-screen` (Cargo.toml) for
+//! `transcript-ui`/`client-core`/`event-model`, so both features end up
+//! enabled together -- `ActiveClient` below gives `bench` priority in that
+//! case, the same way `transcript-screen` already takes priority over the
+//! default `tabs-screen`.
+
+use android_view::{
+    Context, View,
+    jni::{
+        JNIEnv, JavaVM,
+        sys::{JNI_VERSION_1_6, JavaVM as RawJavaVM, jint, jlong},
+    },
+    register_view_class,
+};
+#[cfg(not(feature = "transcript-screen"))]
+use iris::android::{AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState};
+#[cfg(not(feature = "transcript-screen"))]
+use iris::prelude::*;
+use log::LevelFilter;
+use std::ffi::c_void;
+
+#[cfg(feature = "bench")]
+mod bench_client;
+#[cfg(feature = "bench")]
+mod bench_jni;
+#[cfg(all(feature = "transcript-screen", not(feature = "bench")))]
+mod transcript_client;
+
+/// 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";
+
+#[cfg(not(feature = "transcript-screen"))]
+pub struct Client {
+    ui_state: AndroidUiState,
+}
+
+#[cfg(not(feature = "transcript-screen"))]
+impl HasAndroidUiState for Client {
+    fn android_state(&self) -> &AndroidUiState {
+        &self.ui_state
+    }
+    fn android_state_mut(&mut self) -> &mut AndroidUiState {
+        &mut self.ui_state
+    }
+}
+
+#[cfg(not(feature = "transcript-screen"))]
+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
+    }
+}
+
+#[cfg(not(feature = "transcript-screen"))]
+type ActiveClient = Client;
+#[cfg(all(feature = "transcript-screen", not(feature = "bench")))]
+type ActiveClient = transcript_client::TranscriptClient;
+#[cfg(feature = "bench")]
+type ActiveClient = bench_client::BenchClient;
+
+extern "system" fn new_view_peer<'local>(
+    env: JNIEnv<'local>,
+    view: View<'local>,
+    context: Context<'local>,
+) -> jlong {
+    iris::android::new_peer::<ActiveClient>(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/android-app/src/transcript_client.rs

@@ -0,0 +1,392 @@
+//! RUST.md's I5 Android integration: `transcript-ui`'s screen filling the
+//! whole window on android-view, against a real `ai-server` through
+//! `client-core` -- the missing half `iris-android-app` (I2) only had for
+//! `tabs-ui` until now. Behind the `transcript-screen` Cargo feature so the
+//! plain build (`cargo ndk build`, no `--features`) stays exactly the tabs
+//! demo I2/I4 already measured against.
+//!
+//! **Deliberate simplification, recorded rather than left to be
+//! rediscovered (RUST.md's I5 box has the full account)**: there is no
+//! session list and no enrollment UI here. The server, port, token and
+//! pinned CA are baked in at build time (`build.rs`'s
+//! `AI_APP_TRANSCRIPT_HOST`/`_PORT`/`_TOKEN`/`AI_APP_CA`), and the first
+//! session `ApiClient::fetch_sessions` returns is opened automatically --
+//! there is nothing to tap to get there, which is what `transcript-bench.sh`
+//! and `ui-trace` need to land straight on the screen under test. A real
+//! app needs `desktop-app`'s `EnrolledServer`/QR-link flow or E3's
+//! Keystore-sealed `ServerConfig.kt`; building a second one of those was
+//! not this pass's job.
+//!
+//! **Reuses `iris/desktop-app`'s `app.rs` shape almost exactly** --
+//! `fold_event`/`group_tool_runs`/`fold_page`/`raw_seq` from
+//! `client_core::transcript_fold`, a `generation` counter guarding against
+//! a stale background response. What differs is only the redraw
+//! mechanism: android-view has no `winit::EventLoopProxy`, so this uses
+//! `iris::task::Tasks::redraw_handle` (new, added alongside this box) to
+//! request a frame after each `TaskCtx::update` instead of relying on
+//! `Tasks::spawn`'s single end-of-future redraw -- see that method's own
+//! doc for why.
+//!
+//! **Streaming no longer costs a full rebuild** (fixed after the P0 gate
+//! showed why it mattered -- 20 events/second means 20 rebuilds/second of
+//! a ~3,200-row transcript otherwise): `apply_event` calls
+//! `transcript_ui::TranscriptScreen::apply` with the item list before and
+//! after `fold_event`, which updates only the row(s) that actually
+//! changed (almost always just the one open assistant message) instead of
+//! refolding and rebuilding every row. `rebuild_transcript` still runs
+//! the whole widget tree once, for the opening page and for `apply`'s own
+//! rare regroup fallback.
+
+use client_core::api::{ApiClient, UreqTransport};
+use client_core::event_stream::{StreamItem, follow_session_events};
+use client_core::transcript_fold::{TranscriptItem, fold_event, fold_page, group_tool_runs};
+use event_model::SeqEvent;
+use iris::android::{AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState};
+use iris::prelude::*;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+mod pinned {
+    include!(concat!(env!("OUT_DIR"), "/pinned_config.rs"));
+}
+
+pub struct TranscriptClient {
+    ui_state: AndroidUiState,
+    /// The screen's own content -- everything under the fixed
+    /// [`frame_report_controls`] bar, which is built once (`new`, below)
+    /// and never touched by `show_message`/`rebuild_transcript`'s own
+    /// `set` calls the way `desktop-app`'s `transcript_ptr` isn't touched
+    /// by rebuilding the session list beside it.
+    content: WeakWidget<WidgetPtr>,
+    screen: Option<transcript_ui::TranscriptScreen>,
+    /// The folded transcript as of the last rebuild -- kept here (not
+    /// re-derived) for the same reason `desktop-app`'s `Client::items`
+    /// exists: a live `StreamEvent` only carries one new wire event, and
+    /// `fold_event` needs everything folded so far to fold it in.
+    items: Vec<TranscriptItem>,
+    /// The session currently open -- `None` only before the first fetch
+    /// resolves. Read back by `apply_event`'s rebuild, which has no session
+    /// id of its own (a live `SeqEvent` doesn't carry one).
+    session_id: Option<String>,
+    /// Bumped every time a new session load starts; a background response
+    /// checks it before touching state, so a slow reply for a session this
+    /// screen has moved on from can't overwrite what replaced it. There is
+    /// only ever one session here (no list to switch away to), but the
+    /// guard still matters for the *first* fetch racing a `stop`/`start`.
+    generation: Arc<AtomicU64>,
+}
+
+impl HasAndroidUiState for TranscriptClient {
+    fn android_state(&self) -> &AndroidUiState {
+        &self.ui_state
+    }
+    fn android_state_mut(&mut self) -> &mut AndroidUiState {
+        &mut self.ui_state
+    }
+}
+
+/// Builds one `UreqTransport` from the config `build.rs` baked in. Called
+/// twice per session load, same as `desktop-app`'s `build_transport`
+/// closure -- `ApiClient` and the live-stream follow each need their own,
+/// since `UreqTransport` holds its own `ureq::Agent`.
+fn build_transport() -> Result<UreqTransport, String> {
+    let base_url = format!("https://{}:{}", pinned::HOST, pinned::PORT);
+    UreqTransport::new(
+        base_url,
+        pinned::TOKEN.to_string(),
+        pinned::CA_PEM.as_bytes(),
+    )
+    .map_err(|e| e.to_string())
+}
+
+fn placeholder<Rsc: HasEvents>(rsc: &mut Rsc, message: &str) -> StrongWidget {
+    wtext(message.to_string())
+        .color(Color::WHITE)
+        .wrap(true)
+        .pad(16)
+        .add_strong(rsc)
+        .any()
+}
+
+/// The two named controls RUST.md's I5 box ("Measurements taken" (b))
+/// drives by name over `ui-trace`, e.g. `ui-trace record --do "tap 'Frame
+/// report'"`. `dumpsys gfxinfo` cannot see this screen's own GPU-drawn
+/// frames at all -- this is the screen's own equivalent of the Compose
+/// app's "Copy render timings" control, logged rather than clipboarded
+/// (no clipboard wiring exists here) under this crate's own fixed
+/// `android_logger` tag (`iris-android-app`, `lib.rs`'s `JNI_OnLoad`),
+/// grep-able on the fixed string `"iris frame report"` the way
+/// `transcript-bench.sh` greps `"ai-app render report"`.
+fn frame_report_controls(rsc: &mut AndroidRsc<TranscriptClient>) -> WeakWidget {
+    type Rsc = AndroidRsc<TranscriptClient>;
+    let report_rect = rect(Color::rgb(50, 50, 60))
+        .on(
+            CursorSense::click(),
+            |ctx: EventIdCtx<'_, Rsc, _, _>, _rsc: &mut Rsc| match ctx
+                .state
+                .android_state()
+                .frame_report
+                .report()
+            {
+                Some(stats) => log::info!("iris frame report: {stats}"),
+                None => log::info!(
+                    "iris frame report: no frames recorded -- scroll first, then press this"
+                ),
+            },
+        )
+        .label("Frame report");
+    let report = (
+        report_rect,
+        wtext("Frame report").size(18).text_align(Align::CENTER),
+    )
+        .stack()
+        .pad(8)
+        .add(rsc);
+
+    let reset_rect = rect(Color::rgb(70, 40, 40))
+        .on(
+            CursorSense::click(),
+            |ctx: EventIdCtx<'_, Rsc, _, _>, _rsc: &mut Rsc| {
+                ctx.state.android_state_mut().frame_report.reset();
+                log::info!("iris frame report: reset");
+            },
+        )
+        .label("Reset frame report");
+    let reset = (
+        reset_rect,
+        wtext("Reset").size(18).text_align(Align::CENTER),
+    )
+        .stack()
+        .pad(8)
+        .add(rsc);
+
+    (report, reset).span(Dir::RIGHT).height(56).add(rsc)
+}
+
+impl AndroidAppState for TranscriptClient {
+    fn new(mut ui_state: AndroidUiState, rsc: &mut AndroidRsc<Self>) -> Self {
+        let content = WidgetPtr::new().add(rsc);
+        let loading = placeholder(rsc, "Loading sessions...");
+        content(rsc).set(loading);
+
+        let tree = (frame_report_controls(rsc), content.height(rest(1)))
+            .span(Dir::DOWN)
+            .add_strong(rsc)
+            .any();
+        ui_state.set_root(tree);
+
+        let mut client = Self {
+            ui_state,
+            content,
+            screen: None,
+            items: Vec::new(),
+            session_id: None,
+            generation: Arc::new(AtomicU64::new(0)),
+        };
+        client.spawn_fetch_sessions(rsc);
+        client
+    }
+
+    fn back_pressed(&mut self, _rsc: &mut AndroidRsc<Self>, _render: &mut UiRenderState) -> bool {
+        // No screen stack of its own -- same "let the activity finish"
+        // answer `iris-android-app`'s tabs `Client` already gives.
+        false
+    }
+}
+
+impl TranscriptClient {
+    fn show_message(&mut self, rsc: &mut AndroidRsc<Self>, message: &str) {
+        let widget = placeholder(rsc, message);
+        (self.content)(rsc).set(widget);
+        self.screen = None;
+    }
+
+    fn spawn_fetch_sessions(&mut self, rsc: &mut AndroidRsc<Self>) {
+        let redraw = rsc.tasks.redraw_handle();
+        let my_generation = self.generation.load(Ordering::SeqCst);
+        let generation = self.generation.clone();
+        rsc.spawn_task(async move |mut ctx| {
+            let outcome = match build_transport() {
+                Ok(transport) => ApiClient::new(transport)
+                    .fetch_sessions()
+                    .map_err(|e| e.to_string()),
+                Err(e) => Err(format!("couldn't set up TLS: {e}")),
+            };
+            ctx.update(move |state: &mut TranscriptClient, rsc| {
+                if generation.load(Ordering::SeqCst) != my_generation {
+                    return;
+                }
+                match outcome {
+                    Ok(sessions) => match sessions.into_iter().next() {
+                        Some(session) => state.select_session(rsc, session.id),
+                        None => state.show_message(rsc, "No sessions on the sandbox server."),
+                    },
+                    Err(message) => {
+                        state.show_message(rsc, &format!("Couldn't list sessions: {message}"))
+                    }
+                }
+            });
+            redraw.request_redraw();
+        });
+    }
+
+    /// Loads the opening page, then follows the live SSE stream for the
+    /// rest of this session's life -- `desktop-app`'s `select_session`
+    /// almost verbatim, with `Proxy::send_event` replaced by `ctx.update` +
+    /// `redraw.request_redraw()` (see this module's doc).
+    fn select_session(&mut self, rsc: &mut AndroidRsc<Self>, session_id: String) {
+        let my_generation = self.generation.fetch_add(1, Ordering::SeqCst) + 1;
+        self.items.clear();
+        self.session_id = Some(session_id.clone());
+        self.show_message(rsc, "Loading transcript...");
+
+        let redraw = rsc.tasks.redraw_handle();
+        let live_generation = self.generation.clone();
+        rsc.spawn_task(async move |mut ctx| {
+            let transports =
+                build_transport().and_then(|rest| build_transport().map(|stream| (rest, stream)));
+            let (rest, stream_transport) = match transports {
+                Ok(pair) => pair,
+                Err(e) => {
+                    let message = format!("couldn't set up TLS: {e}");
+                    ctx.update(move |state: &mut TranscriptClient, rsc| {
+                        if live_generation.load(Ordering::SeqCst) == my_generation {
+                            state.show_message(rsc, &message);
+                        }
+                    });
+                    redraw.request_redraw();
+                    return;
+                }
+            };
+            let api = ApiClient::new(rest);
+
+            // The most recent 200 events, coalesced -- the same page size
+            // `desktop-app` uses; RUST.md's I3/history-paging work is what
+            // a real scrollback would reuse (out of scope here, same as
+            // E4).
+            let page: Result<Vec<serde_json::Value>, String> = api
+                .fetch_transcript_page(&session_id, None, 200, true)
+                .map_err(|e| e.to_string());
+            // The wire `seq` of the last line, not a folded item's `seq()`
+            // -- see `client_core::transcript_fold::raw_seq`'s doc for why
+            // resuming from the latter re-delivers deltas already folded
+            // into an in-progress reply.
+            let after = page
+                .as_ref()
+                .ok()
+                .and_then(|values| values.last())
+                .and_then(client_core::transcript_fold::raw_seq)
+                .unwrap_or(0);
+            let result = page.and_then(|values| fold_page(&values));
+
+            {
+                let live_generation = live_generation.clone();
+                ctx.update(move |state: &mut TranscriptClient, rsc| {
+                    if live_generation.load(Ordering::SeqCst) != my_generation {
+                        return;
+                    }
+                    match result {
+                        Ok(items) => {
+                            state.items = items;
+                            state.rebuild_transcript(rsc);
+                        }
+                        Err(message) => {
+                            state.show_message(rsc, &format!("Couldn't load transcript: {message}"))
+                        }
+                    }
+                });
+            }
+            redraw.request_redraw();
+
+            if live_generation.load(Ordering::SeqCst) != my_generation {
+                return;
+            }
+            // The outer closure here is an `FnMut` -- `follow_session_events`
+            // calls it once per line -- so it captures `live_generation` by
+            // move and re-clones it for each inner `ctx.update` closure
+            // rather than moving a shared `stop`-style helper into itself:
+            // a value moved out of an `FnMut`'s captures on one call leaves
+            // nothing there for the next.
+            let _ =
+                follow_session_events(
+                    &stream_transport,
+                    &session_id,
+                    after,
+                    move |item| match item {
+                        StreamItem::Open | StreamItem::Reset => {
+                            live_generation.load(Ordering::SeqCst) == my_generation
+                        }
+                        StreamItem::Event { event, .. } => {
+                            if live_generation.load(Ordering::SeqCst) != my_generation {
+                                return false;
+                            }
+                            let live_generation = live_generation.clone();
+                            ctx.update(move |state: &mut TranscriptClient, rsc| {
+                                if live_generation.load(Ordering::SeqCst) != my_generation {
+                                    return;
+                                }
+                                state.apply_event(rsc, &event);
+                            });
+                            redraw.request_redraw();
+                            true
+                        }
+                    },
+                );
+        });
+    }
+
+    /// Rebuilds the whole widget tree from `self.items` -- same tradeoff as
+    /// `desktop-app`'s `rebuild_transcript` (this module's doc comment).
+    /// Reads `self.session_id` rather than taking one, since every caller
+    /// (the opening page, and every live event) already has it set there.
+    fn rebuild_transcript(&mut self, rsc: &mut AndroidRsc<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.session_id.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.content)(rsc).set(tree);
+        self.screen = Some(screen);
+    }
+
+    fn apply_event(&mut self, rsc: &mut AndroidRsc<Self>, event: &SeqEvent) {
+        let old_items = self.items.clone();
+        self.items = fold_event(&self.items, event);
+        match &self.screen {
+            // The common path: update only the row(s) that actually
+            // changed instead of refolding and rebuilding all ~3,200 of
+            // them per event (RUST.md's P0 streaming-phase fix).
+            Some(screen) => screen.apply(rsc, &old_items, &self.items),
+            // No screen yet (the opening page hasn't landed) -- build one
+            // the ordinary way once it has.
+            None => self.rebuild_transcript(rsc),
+        }
+    }
+
+    fn send_message(&mut self, session_id: String, text: String) {
+        std::thread::spawn(move || {
+            if let Ok(transport) = build_transport() {
+                let api = ApiClient::new(transport);
+                let _ = api.send_message(&session_id, &text, &[]);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,19 @@
+[package]
+name = "iris-core"
+version.workspace = true
+edition.workspace = true
+
+[dependencies]
+wgpu = { workspace = true }
+# Only for `UiRenderNode::new`'s `push_error_scope`/`pop_error_scope` pair
+# (renderer-creation error reporting, RUST.md's P0 phone-crash box) --
+# `block_on` turns that one async pop into the same synchronous call shape
+# `device_limits()`'s two callers already use for `request_adapter`/
+# `request_device`, rather than making this crate's one entry point async.
+pollster = { workspace = true }
+bytemuck ={ workspace = true }
+image = { workspace = true }
+parley = { workspace = true }
+swash = { workspace = true }
+fxhash = { workspace = true }
+accesskit = { workspace = true }

iris/core/assets/fonts/OFL.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

iris/core/src/attr.rs

@@ -0,0 +1,23 @@
+use crate::{UiRsc, WeakWidget, WidgetIdFn, WidgetLike};
+
+pub trait WidgetAttr<Rsc, W: ?Sized> {
+    type Input;
+    fn run(rsc: &mut Rsc, id: WeakWidget<W>, input: Self::Input);
+}
+
+pub trait Attrable<Rsc, W: ?Sized, Tag> {
+    fn attr<A: WidgetAttr<Rsc, W>>(self, input: A::Input) -> impl WidgetIdFn<Rsc, W>;
+}
+
+impl<Rsc: UiRsc, WL: WidgetLike<Rsc, Tag>, Tag> Attrable<Rsc, WL::Widget, Tag> for WL {
+    fn attr<A: WidgetAttr<Rsc, WL::Widget>>(
+        self,
+        input: A::Input,
+    ) -> impl WidgetIdFn<Rsc, WL::Widget> {
+        |rsc| {
+            let id = self.add(rsc);
+            A::run(rsc, id, input);
+            id
+        }
+    }
+}

iris/core/src/event/ctx.rs

@@ -0,0 +1,18 @@
+use crate::{HasEvents, WeakWidget, Widget};
+
+pub struct EventCtx<'a, Rsc: HasEvents, Data> {
+    pub state: &'a mut Rsc::State,
+    pub data: Data,
+}
+
+pub struct EventIdCtx<'a, Rsc: HasEvents, Data, W: ?Sized> {
+    pub widget: WeakWidget<W>,
+    pub state: &'a mut Rsc::State,
+    pub data: Data,
+}
+
+impl<Rsc: HasEvents, Data, W: Widget> EventIdCtx<'_, Rsc, Data, W> {
+    pub fn widget<'a>(&self, rsc: &'a mut Rsc) -> &'a mut W {
+        &mut rsc.ui_mut().widgets[self.widget]
+    }
+}