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

# Conflicts: # docs/IRIS.md # docs/RUST.md
iris: the fling curve was the identity function, and the keyboard was a targetSdk
2026-09-07 15:33:25 -04:00 · 2026-09-07 12:44:01 -04:00 · 2026-09-07 12:39:53 -04:00 · 2026-09-07 12:38:55 -04:00 · 2026-09-07 12:38:19 -04:00 · 2026-09-07 12:35:20 -04:00
188 changed files with 36263 additions and 4350 deletions
@@ -0,0 +1,244 @@
 ---
 name: ai-app-rigs
 description: ai-app's test rigs, harness scripts and reference measurements - ui-sandbox.sh, debug-transcript.sh, transcript-bench.sh, stream-bench.sh, trace-draw.sh, the /usage fixture vocabulary, the fake CLI, the rule that no UI-driving script may tap a coordinate, how to test llama.cpp and ssh on this machine, how importing behaves, and the scroll/stream/explorer numbers not worth re-measuring. Read before running or writing a benchmark, driving the app's UI from a script, exercising the session lifecycle, testing a llama or remote session, or touching the import screen.
 ---
 # ai-app: rigs, harnesses and measurements
 Moved out of `AGENTS.md` on 2026-09-04 so it is read when it is relevant
 rather than sent with every request in this repo -- it was 12 KB of the 35 KB
 that file cost on every one. Unchanged in the move, and still the only copy.
 ## The rigs
 Each exists because something was invisible without it.
 - **`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.
 - **`/usage` in an echo session puts up an invented meter**, which is how the
  rate-limit screens' states are reached without spending quota: `/usage 42`,
  `/usage 95 20` (minutes left), `/usage 42 never` (the between-blocks window
  with no reset time), `/usage 42 unreadable`, `/usage notloggedin`,
  `/usage unreachable`, `/usage failed`, `/usage off`. The vocabulary is
  `usage::Fixture`'s, since those are its states. With none set an echo
  session meters nothing, which is the ordinary case and draws no bar.
 - **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.
 ### 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
 **Both are set up here as of 2026-09-04** and need nothing typed. The
 prebuilt CPU llama.cpp lives outside the repo at `~/.local/opt/llama.cpp`
 (the 15 MB `ubuntu-x64` release asset) and is symlinked as
 `/usr/local/bin/llama-server`, which is what makes **discovery find it over
 ssh**: `~/.local/bin` is not on the PATH a non-interactive ssh session gets.
 It resolves its own libraries through `$ORIGIN`, so no `LD_LIBRARY_PATH` is
 needed. One model is downloaded — `unsloth/Qwen3-0.6B-GGUF/Qwen3-0.6B-Q8_0.gguf`,
 639 MB under `~/.local/share/ai-app/models` — and 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**. That is set up
 too: the key is `~/.config/ai-app/ssh-self` (its public half is in
 `~/.ssh/authorized_keys`, labelled removable), and the real config carries a
 setup called **"this vm over ssh"** — `bob@127.0.0.1` with that
 `identityFile` plus
 `options: ["StrictHostKeyChecking=no", "UserKnownHostsFile=/tmp/ai-app-known-hosts"]`
 so it touches nothing real — offering `claude-cli` and `llama-cpp`. It is the
 whole rig for "does a remote llama session work", since the far machine is
 this one and the model file is the same file. For a throwaway setup of your
 own, 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. 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.
 ## Importing
 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.
 **Never import a Claude Code session that is open in a terminal.** The app
 refuses it — see 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.
 ## 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.
  EXPLORER.md's "What the measurements said" has the rest.
@@ -5,24 +5,42 @@ 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,
+**`docs/PLAN.md` is the design source of truth** — every decision with its
-its rationale, and what was rejected. Read it before changing anything
+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, 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
 is a new driver — never a session-type branch in shared code (routes,
 transcript, app screens).
 The second one, for the Rust port on the `rustify` branch: **the phone app
 and a planned desktop app share almost all of their code.** Screens, widgets,
 folding, paging, config and the network client live in the shared crates
 (`iris`, `client-core`, `transcript-ui`, `tabs-ui`); `android-app` and
 `desktop-app` are thin entry points that own only what the platform forces
 (JNI and the IME on one side, winit and argv on the other). The two
 *layouts* will differ, to suit a phone's screen and a finger against a
 desktop's screen and a mouse -- but the widgets a layout is made of (a
 button, a text field, a list, a card) and the styling (colours, spacing,
 type) are one implementation with no per-platform copy. Anything that could
 work on both goes in a shared crate the first time it is written, and a
 platform crate growing a widget or a colour is a defect to move, not a
 convenience to keep. Iris said this on 2026-09-07; docs/RUST.md carries the
 details.
 ## Layout
 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.
@@ -40,16 +58,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.
- `EXPLORER.md` — the file explorer's design (`server/src/files.rs` and
+- `docs/` — every design and working document except this file and
-  `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
+  `CLAUDE.md`:
- `TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent. Read it
+  - `docs/EXPLORER.md` — the file explorer's design (`server/src/files.rs`
-  before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or the opening
+    and `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
-  and stream effects in `SessionScreen.kt`.
+  - `docs/TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent.
- `TODO.md` — the working list.
+    Read it before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or
- `RUST.md` — the plan for moving the app to Rust (on the `rustify`
+    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
@@ -86,7 +111,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
@@ -146,6 +175,27 @@ two icon buttons the same width without either being given one — and why
 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
@@ -226,6 +276,27 @@ Each exists because something was invisible without it.
  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).
 - **iris's three test layers** (docs/RUST.md's "Three test layers" has
  the commands and what each cannot answer): test at the cheapest one
  that can answer the question. `cargo test -p transcript-fixture` runs
  the real transcript screen over the bench fixture with **no window, no
  compositor and no GPU** (`iris::harness`), on a clock the test owns and
  a gesture replayed from a `t_ms action x y` file under
  `iris/transcript-fixture/touch/` -- which is how the batched 120Hz
  flick a finger actually makes is testable at all, since a `ui-trace`
  swipe is many evenly-spaced events. `iris/run-headless.sh phone --phone
  --shot …` opens the same screen in a window at the phone's own size and
  density for looking at, and `--replay FILE` drives the same recording
  into it. The emulator is for JNI, the IME, insets, the surface
  lifecycle and one verification run before a build goes to the phone --
  not for iterating on layout.
 ### Driving the UI
@@ -312,7 +383,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
@@ -345,7 +416,7 @@ 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.
 **Never import a Claude Code session that is open in a terminal.** The app
-refuses it — see PLAN.md for the incident that made that a refusal rather
+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
@@ -521,4 +592,4 @@ belongs in `~/.claude/TOOLCHAIN.md` or `~/.claude/MACHINE.md` instead.
  `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.
-  EXPLORER.md's "What the measurements said" has the rest.
+  docs/EXPLORER.md's "What the measurements said" has the rest.
@@ -1,30 +1,44 @@
-# Decisions taken for Iris to review
+# Decisions awaiting review
-Short list of design choices made by the design agent without asking, so
+Choices made while working autonomously, for Bryan to keep or change. Each
-they can be judged and reversed later. Detail lives in RUST.md (and IRIS.md
+says what was picked and why; the detail is in the design doc it names.
-for iris API changes); this file is only the summary. Newest first. Items
+Delete an entry once it has been looked at.
 marked **DEFERRED** are ones the agent chose not to decide alone.
-## 2026-09-05
+## Subagent views (2026-09-05, `SUBAGENTS.md`)
- **Touch drag on a transcript row follows Android's own rule**: a vertical
+Made on my own judgement, limited blast radius:
-  drag pans the list immediately; a stationary press held 500 ms starts a
+
-  text selection which further dragging extends; a horizontal drag while
+1. **A subagent is a transcript, not a session.** It has no process,
-  something is already selected extends that selection without the wait.
+   controls or settings; it is addressed as `/sessions/{id}/subagents/{sub}`
-  One `DragArbiter` per list decides it (`iris/src/sense.rs`). Chosen over a
+   and stored under the session's directory, so deleting the session takes
-  "text layer always wins" or "list always wins" rule because either loses
+   it. Alternative rejected: registering it as a session of its own, which
-  one of the two gestures a reader expects.
+   would give it a card in the main list and a driver that can do nothing.
- **E4's desktop shape is a new `iris/desktop-app` crate**: a winit window
+2. **Read-only view is the session screen minus its controls**, rather than
-  holding `transcript-ui`'s screen beside a session list, talking to a real
+   a second, simpler transcript screen. Keeps paging, caching, selection
-  `ai-server` through `client-core`. It enrols by pasting the same
+   and rendering in one place. Cost: a `readOnly` mode threaded through
-  `aiapp://enroll?…` link a phone scans (`client-core::config::EnrolledServer`)
+   `SessionScreen`.
-  and keeps it owner-only under `$XDG_CONFIG_HOME/ai-app-desktop/`. The
+3. **The list only carries a count.** Each session row says how many
-  pinned CA is a path given on the command line, not baked in. Chosen so
+   subagents it has; their titles and statuses are fetched when the card is
-  the phone and desktop share one enrolment format and no second one is
+   expanded. Keeps `GET /sessions` from reading every subagent transcript.
-  invented.
+   Consequence: an expanded card's statuses refresh with the list, not live.
- **Order of remaining work**: finish the two in-flight pieces above, then
+4. **Expanded/collapsed is remembered per session on the phone**, not on
-  the transcript screen's Android integration and the `transcript-bench.sh`
+   the server. Collapsed by default, per the transcript convention that new
-  comparison against Compose — the numbers the recommendation still lacks.
+   things arrive collapsed.
- **DEFERRED — whether to commit to iris over Masonry for `ai-app`.** Waits
+5. **Subagents of imported sessions are not shown.** The import path still
-  on the bench numbers above; RUST.md's recommendation says what the
+   skips `isSidechain` records; the CLI's own `subagents/agent-*.jsonl` files
-  measurements must show.
+   are not read. Only subagents run while this backend was watching exist.
 6. **Echo grows `/subagent [n]`** as the test rig, so nothing here needs a
   paid turn to exercise.
 Deferred, because they reach further than this feature:
 - **Live status on the list.** Whether the session list should follow a
  stream at all (it refreshes on demand today) decides whether subagent
  status can ever be live there. Not changed.
 - **Nested subagents.** A subagent's own Task calls are shown as tool calls
  in its transcript and are not given transcripts of their own. Supporting
  that is the same mechanism one level down, but the UI would need nested
  expanders.
 - **The subagent status row says "context unknown".** Nothing measures a
  subagent's context; the row could leave it out rather than admit it.
@@ -1,277 +0,0 @@
 # iris: notable public API changes
 For Iris to read on her own time. Each entry is a change to iris's public
 surface that a widget author or app author would notice: a trait method
 added, removed or re-shaped; a type that callers construct differently; a
 capability that moved. Small and trivial changes do not go here.
 An entry gives the date, what changed, why, and a short before/after where
 it helps judge the change without the session that made it. Newest first.
 ## 2026-09-05: `transcript_ui::build_tree` (RUST.md's E4)
 `transcript_ui::build` claimed the whole window (`ui_state.set_root(tree)`)
 as its last step, which is right for a window that *is* the transcript
 screen (the winit example, an eventual Android cdylib) and wrong for the
 desktop app, which puts a session list beside it. `build_tree` is `build`
 minus that last step: it returns `(TranscriptScreen, StrongWidget)` instead
 of just `TranscriptScreen`, and the caller decides where the tree goes —
 into `ui_state.set_root`, or into a `WidgetPtr` alongside something else
 (`iris/desktop-app`'s `rebuild_transcript`). `build` is now one line calling
 `build_tree` and doing the `set_root` itself, so existing callers are
 unaffected.
 ```rust
 // before, and still available, for a caller that wants to *be* the window:
 let screen = transcript_ui::build(rsc, &mut ui_state, rows);
 // new, for a caller embedding the screen beside something else:
 let (screen, tree) = transcript_ui::build_tree(rsc, rows);
 some_widget_ptr(rsc).set(tree);
 ```
 ## 2026-09-05: `DragArbiter`, pan-vs-select for one shared touch gesture (RUST.md's I5)
 New public type, `iris::sense::DragArbiter`. Why: a widget author who
 registers both a list-level pan and a row-level drag-to-select on the same
 touch gesture has no way to arbitrate between them — `core/src/sense.rs`'s
 `run_sensors` always gives the innermost layer first refusal, so the inner
 one wins every frame it is pressed, not just the frame the press started
 (this is exactly what left transcript-ui's touch-drag panning unreachable
 until now). `DragArbiter` is one small state machine, one instance per
 gesture surface (a whole list, not per row), that a caller drives with its
 own `press_start`/`update`/`release` calls and a caller-supplied `Instant`
 (so it is unit-testable without a real clock or a render harness). It
 decides the way Android itself does: an ordinary vertical drag pans
 immediately; a stationary press held `LONG_PRESS` (500ms) starts a
 selection, which any further drag then extends; a horizontal drag while
 something is already selected extends it immediately, skipping the wait.
 ```rust
 // One per list, held alongside whatever state coordinates the rows:
 let mut arbiter = DragArbiter::new();
 // On press-down:
 arbiter.press_start(pos, Instant::now(), already_selected);
 // Every frame the button/finger stays down:
 match arbiter.update(pos, Instant::now()) {
    DragOutcome::Pan(dy) => list.scroll(-dy),
    DragOutcome::SelectStart => selection.begin(...),
    DragOutcome::SelectExtend => selection.extend(...),
    DragOutcome::Undecided => {}
 }
 // On release:
 arbiter.release();
 ```
 `transcript-ui`'s `Selection::drag` (`transcript-ui/src/selection.rs`) is
 the reference caller: every row's `CursorSense::click_or_drag() |
 CursorSense::unclick()` handler routes through one `Selection`-owned
 arbiter instead of calling `begin`/`extend` directly, so a drag that starts
 on a row's own rendered text now pans the list correctly instead of
 always starting a selection. 8 new unit tests in `iris/src/sense.rs`'s
 `drag_arbiter_tests` module.
 ## 2026-09-05: `SpanStyle`, per-range text styling (RUST.md's I5)
 A `TextBuffer` used to have exactly one style (`TextAttrs`: colour, size,
 family, ...) for its whole string, applied via `push_default` into parley's
 ranged builder. `SpanStyle` is a second, optional layer: a byte range plus
 whichever of colour/family/font size/bold/italic/underline it overrides,
 pushed with parley's own `push(property, range)` instead. Why: a transcript
 row's markdown (a heading, **bold**, `inline code`, a link) all inside one
 wrapped paragraph needs each to carry its own look while the paragraph
 still wraps and selects as a single buffer — the thing `masonry`'s
 `TextArea` cannot do (`StyleSet` is one style for the whole editor,
 `text_area.rs:43-44`'s `// TODO: RichTextInput`), and the reason this
 existed at all.
 ```rust
 let (text, spans) = transcript_ui::markdown::render_markdown(src, 16.0);
 wtext(text)
    .spans(spans)   // new: TextBuilder::spans, on both Text and TextEdit
    .editable(EditMode::MultiLine)
    .add(rsc);
 ```
 Two things a widget author should know before reaching for it:
 - **Call `.spans()` before or after `.editable()`, both work** — the field
  lives on `TextBuilder` itself, not either output type, and both
  `TextOutput::run` and `TextEditOutput::run` apply it to the buffer via
  `TextBuffer::set_spans`. **These two call sites are a pair**: adding a
  third `TextBuilderOutput` impl without also calling `set_spans` there
  reproduces the exact bug this box shipped once already (spans silently
  dropped for `TextEdit`, found only by screenshotting, not by any test —
  `markdown.rs`'s own unit tests check string/range logic, which is
  correct in isolation and proves nothing about whether the render path
  ever sees it).
 - **Colour is now per-glyph, not per-buffer.** `PlacedGlyph` gained a
  `color: UiColor` field (from parley's own per-run `Style::brush`), and
  `Painter::glyphs` draws each glyph in its own colour instead of
  `RenderedText::color` uniformly. `RenderedText::color` still exists (the
  buffer's *base* colour, for a caller that wants it as a whole, e.g. to
  tint a cursor) but no longer drives what a glyph actually renders as.
 ## 2026-09-05: accessibility names via AccessKit (RUST.md's I4)
 `.label()` (already in `trait_fns.rs`, previously unused anywhere in-tree)
 is now load-bearing: it's the one thing that puts a widget in the AccessKit
 tree `iris_core::ui::access::AccessTree` builds and both backends push
 out. A widget author who wants a control to be findable by name (and
 tappable by name, through `ui-trace`/a real screen reader) calls `.label()`
 on it; nothing else is required, and a widget nobody labels is invisible
 to this system at zero cost, not just zero UI.
 ```rust
 let button = rect(Color::LIME)
    .on(CursorSense::click(), move |_, rsc| { ... })
    .label("Add task");   // now findable by uiautomator/AccessKit as "Add task"
 ```
 Two new things a widget author might touch directly:
 - **`Widget::access_role(&self) -> accesskit::Role`**, default `Unknown`.
  Override it if your widget has a real platform equivalent —
  `TextEdit` now returns `TextInput`/`MultilineTextInput` by `EditMode`.
  Only consulted for a widget that also has a `.label()`; an unlabelled
  widget's `access_role` is never called.
 - **`Widgets::named() -> impl Iterator<Item = WidgetId>`** — every widget
  with an explicit label, for anything else that wants to walk the same
  set `AccessTree` does.
 Nothing about `Painter`, `draw`, or the layout/move machinery changed —
 this sits entirely beside them, reading `resolved_region`'s output rather
 than participating in producing it.
 ## 2026-09-05: `List`, a virtualised bottom-anchored list (RUST.md's I3)
 A new widget, `iris::widget::List` (`iris/src/widget/list.rs` -- read its
 module doc first), for the transcript's kind of screen: variable-height
 rows, keyed by a `u64`, composed only while visible, moved rather than
 re-laid-out on scroll, a scroll anchor that survives a row inserted above
 it, "more" sentinels at each end, and "hold the edge nearest the tap" when
 a row's height changes (`note_tap`, resolved in the layout pass).
 ```rust
 let mut list = List::new(Axis::Y);
 list.push_back(ListRow::new(key, row_widget));   // O(1)
 list.push_front(ListRow::new(older_key, row));   // O(1), anchor unaffected
 list.set_more_before(Some(spinner_widget));      // sentinel, drawn at the edge
 list.note_tap(viewport_y);                       // before mutating a row's height
 let (top, bottom) = list.extent(key).unwrap();   // last frame's on-screen box, if visible
 ```
 Built entirely out of existing primitives (`Painter::widget`/`widget_within`/
 `reposition`/`draw_twice`, and `draw_inner`'s own old-children diffing) --
 no new mechanism was added to the render core for it. One correctness
 lesson worth reading even for other widgets: a row that fills whatever
 region it is offered (`Rect`, `is_size_independent`) cannot be measured at
 a throwaway oversized region and then merely `reposition`ed into place --
 `reposition` only ever writes an offset, never a size, so the oversized
 primitive stays oversized. `List` fixes this by caching each row's real
 height once measured and placing an already-known row directly at its
 exact box; see `list.rs`'s `place` for the full reasoning and
 `a_fill_shaped_background_is_not_left_oversized` for the regression test.
 ## 2026-09-05: a second backend (android-view), and what moved to make room for it
 RUST.md's I2. Three changes a widget or app author would notice, all in
 service of the same thing: `default` (winit) and the new `android`
 (android-view) backends sharing what does not depend on windowing.
 - **`Selector`/`Selectable`'s bound changed from `Rsc::State:
  HasDefaultUiState` to `Rsc::State: FocusHost`** (new trait, `attr.rs`).
  `HasDefaultUiState` still exists and still works — `default/attr.rs` now
  implements `FocusHost` for anything that has it — so a winit app's
  existing code is unaffected. An Android app implements `FocusHost` via
  `HasAndroidUiState` instead. Affects only an app that referenced
  `HasDefaultUiState` directly at a `Selectable`/`Selector` call site
  rather than through `.attr::<Selectable>(())`, which nothing in-tree
  does.
 - **`Tasks::init` takes `Arc<dyn RequestRedraw>` instead of
  `Arc<winit::window::Window>`.** `RequestRedraw` (`task.rs`) is one method,
  `fn request_redraw(&self)`; `winit::window::Window` implements it
  (`default/render.rs`), so `Tasks::init(window)` at a call site is
  unchanged by inference. Only matters if something constructed a `Tasks`
  directly rather than through `DefaultRsc`/`AndroidRsc`.
 - **`TextEdit::apply_event`/`TextInputResult` are `#[cfg(not(target_os =
  "android"))]`** — they take a `winit::event::KeyEvent`, which does not
  exist on Android; `android/input.rs` drives the same primitives
  (`backspace`/`delete`/`motion`/`insert`, all still unconditional) from
  `ndk::event::Keycode` directly instead. New unconditional getters on the
  way: `TextEdit::text()`/`selection_range()`/`caret()`, and
  `TextEditCtx::delete_byte_range`/`set_cursor_byte` — the primitives
  `android/ime.rs`'s `InputConnection` bridge needed and that were not
  previously exposed publicly.
 ## 2026-09-04: `Widget::draw` reports the size it used; `desired_width`/`desired_height` are gone
 A widget used to implement three methods (`draw`, `desired_width`,
 `desired_height`); it now implements one, `fn draw(&mut self, painter: &mut
 Painter) -> Size`, which draws into `painter.region()` and returns how much
 of it was used. Why: the two extra methods routinely re-simulated what
 `draw` was about to do anyway (`Span::desired_ortho` copied its own draw
 loop to get cross-axis sizing right) — one visit per widget per frame
 instead of up to three. A container that needs a child's size before
 placing it (alignment, centering) draws the child once at a provisional
 region, reads the returned `Size`, and calls the new `Painter::reposition`
 to move it into its final spot — an O(1) offset write, not a second draw. A
 widget whose drawn output never depends on the size it's given (a
 fixed-size `Rect`, a decoded `Image`) overrides the new `fn
 is_size_independent(&self) -> bool { false }` to `true`, which skips
 redrawing it when only its offered region changes shape.
 ```rust
 // before
 fn draw(&mut self, painter: &mut Painter) { /* ... */ }
 fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
 fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len { /* ... */ }
 // after
 fn draw(&mut self, painter: &mut Painter) -> Size { /* ... */ }
 ```
 `SizeCtx` and `Cache` are gone with it — see `LAYOUT.md` for the full
 design, the move-offset mechanism this shipped alongside, and the file
 list.
 ## 2026-09-04: texture pipeline rebuilt off the binding array
 `Textures`/`TextureHandle`, `GlyphPrimitive`, and `UiRenderNode::new` all
 changed shape. Why: the old pipeline bound every texture ever drawn in one
 `binding_array<texture_2d<f32>>` and asked every device, unconditionally,
 for `VK_EXT_descriptor_indexing` — a real share of Android GPUs lack it,
 and it failed outright on the Android emulator's software Vulkan. See
 TEXTURES.md's "Recommended shape" and "Implemented, 2026-09-04".
 - **`UiRenderNode::new` drops its `limits: UiLimits` parameter, and
  `UiLimits` is gone.** Before: `UiRenderNode::new(&device, &queue,
  &config, UiLimits::default())`. After: `UiRenderNode::new(&device,
  &queue, &config)`. Nothing replaces it — there are no more
  binding-array limits to size.
 - **`src/default/render.rs`'s device request asks for no features and no
  binding-array limits.** Before: `required_features:
  Features::TEXTURE_BINDING_ARRAY | Features::PARTIALLY_BOUND_BINDING_ARRAY
  | Features::SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`
  plus two `max_binding_array_*` limits. After: `Features::empty()` (the
  `DeviceDescriptor` default) and only `max_buffer_size` set, which was
  never about the binding array.
 - **`TextureHandle` has no `primitive()` method any more**; a caller
  outside `iris` shouldn't have been calling it (it fed the old renderer's
  internals), but if something did: use `image_index()` for a standalone
  image's bind-group index. There is no equivalent for a page — a page has
  no bind group of its own now, see below.
 - **`GlyphPrimitive` has no public constructor from a struct literal.**
  Before: `GlyphPrimitive { uv_min, uv_max, view_idx, sampler_idx, color,
  flags }`. After: `GlyphPrimitive::new(uv_min, uv_max, layer, color,
  flags)` — one `layer` (the shared atlas array's layer) instead of a
  `view_idx`/`sampler_idx` pair, since a page is now a layer of one array
  texture rather than its own bound texture.
 - **A widget author drawing images is unaffected**: `Painter::texture`/
  `texture_at`/`texture_within` and `Textures::add` keep their signatures.
  What changed underneath is that each standalone image now gets its own
  `wgpu::BindGroup` and draw call instead of a slot in the shared array —
  invisible from the widget API, visible only in `UiRenderNode`'s internals
  and in `iris`'s device requirements.
@@ -1,254 +0,0 @@
 # iris: known problems and things still to build
 Iris's own list for the library, recorded 2026-09-04 in her words where it
 matters, so the agents working through RUST.md pick these up in a sensible
 order rather than rediscovering them. Each item says where it sits in the
 order and what "done" looks like. Tick and date them in place.
 ## Fix
 - [x] **Input does not fall through by input type (2026-09-04).**
  `SensorUi::run_sensors` (`src/default/sense.rs`) used to set "consumed,
  stop checking lower layers" from mere hover — a widget registered for
  nothing but `click()` blocked a `Scroll` meant for whatever was behind
  it, since "the cursor is over this widget" and "this widget handled the
  event" were the same check. Fixed by judging consumption per input
  kind: with no button transition and no scroll happening this frame
  ("momentary" activity), the topmost hovered widget still wins, same as
  before; when something momentary *is* happening, only a widget whose
  registered senses actually include a matching non-hover one (checked
  via a new `TypeEventManager::registered`, which lists what a widget
  registered without running anything) consumes it, so a widget with only
  `Hovering`/click handlers can no longer block a scroll from reaching a
  list underneath. `iris/src/sense_tests.rs` builds a button-over-a-list
  `Stack` with a plain `HasEvents` impl (no GPU or window) and checks both
  directions: a scroll over the button reaches the list, and a real click
  still reaches the button — confirmed to fail on the pre-fix code and
  pass after.
 - [x] **Appending one image to an already-loaded list rebuilds every other
  image's bind group (2026-09-05, fixed 2026-09-05).** Found by the
  benchmark below: `GpuTextures::update` (`core/src/render/texture.rs`)
  triggered `rebuild_image_bind_groups` — a loop over *every live
  standalone image*, rebuilding its `BindGroup` — whenever the shared
  `masks` or `move_offsets` GPU buffer was resized (`masks_resized ||
  moves_resized` in `UiRenderNode::update`, `core/src/render/mod.rs`), and
  a widget getting its *first* move-offset slot (LAYOUT.md section 2 —
  every widget gets one on first draw) could be exactly what grows that
  buffer. So one new message with one new image, appended to a transcript
  that already has N images loaded, did not cost O(1): it cost one
  `create_image` for the new image plus one `make_image_bind_group` per
  *existing* image, because the new widget's own move slot pushed the
  arena past its capacity. Measured directly in
  `iris/examples/bench_images.rs`: appending a 1,001st image to 1,000
  already-settled ones reported **1,001** bind-group creates for that one
  frame, not 1 (`./run-bench.sh images`, frame 5 in the transcript below).
  **Fix**: `masks`/`move_offsets` never belonged in a standalone image's own
  bind group (group 2) in the first place — the group also holds that
  image's own texture view, which is the only thing that is genuinely
  per-image, so a buffer shared by *everything* forced a rebuild of
  *every* group the moment it moved. Gave masks/move_offsets their own
  bind group (group 3 in `shader.wgsl` and `UiRenderNode`: `masks_layout`/
  `masks_group`), bound once per frame in `UiRenderNode::draw` rather than
  once per draw call, instead of duplicating them into every per-image
  group. `GpuTextures` and its image bind groups now know nothing about
  either buffer — `rebuild_image_bind_groups` is called only from
  `grow_array` (the atlas array texture growing, which genuinely does
  change what every image's own bind group must reference) — so a
  masks/move_offsets resize now touches exactly one bind group, ever,
  regardless of how many images are live. Numbers after the fix, same
  benchmark and command:
      ./run-bench.sh images
      frame=1 bind_group_creates=1000   (cold load, unchanged)
      frame=2 bind_group_creates=0      (was 1000 -- see the item below)
      frame=3 bind_group_creates=0
      frame=4 bind_group_creates=0
      (append one image here)
      frame=5 bind_group_creates=1      (was 1001)
      frame=6 bind_group_creates=0
  `run-headless.sh tabs --shot` still 27266 bytes, byte-for-byte unchanged,
  confirming the bind-group restructuring changed nothing about what is
  drawn.
 - [x] **Bind-group creation takes two frames to reach the steady state, not
  one (2026-09-05, closed by the fix above, 2026-09-05).** Same benchmark:
  loading 1,000 images cold used to report 1,000 creates on frame 1
  (expected — `create_image`, one per new image) *and again* 1,000 on
  frame 2, before settling to 0 from frame 3. This was `rebuild_image_bind_groups`
  firing a second time for the same masks/move-offsets buffer-growth
  reason as the item above, confirming the guess recorded here — the two
  were exactly the same root cause measured two different ways. Frame 2
  now reports 0 (see the numbers above); not a separate fix.
 ## Build
 - [x] **Benchmarks**, not unit tests, run on demand (2026-09-05; a
  `benches/` or a script under `iris/`, never in `cargo test`). The
  scenario that matters most is a **message list** — chat apps and this
  app's transcript alike — stressed with many messages and many images.
  One case in particular: **resizing an input box** (typing enough text to
  grow it) that pushes a long list of messages above it must stay very
  fast and recalculate almost nothing — a move of everything above, not a
  re-layout. That is exactly the O(1) move chain in LAYOUT.md; the
  benchmark is what proves it. Done when the numbers are in this file with
  the command, and the input-box case reports draws re-run, not just frame
  time.
  **Built as two rigs**, chosen per scenario by whether a real `wgpu`
  device is needed (`UiRenderState`/`Widgets` touch no GPU or window, so
  most of this runs as an ordinary binary — the same property
  `layout_tests.rs` relies on):
  - `iris/benches/message_list.rs` — a plain `Instant`-timed binary
    (`[[bench]] harness = false` in `iris/Cargo.toml`), not criterion: see
    the file's own header for why (short version — every scenario here
    reduces to a *count* `UiRenderState::take_counters` already produces,
    which criterion's statistical machinery adds nothing to and which a
    new dependency is not worth pulling in for). Covers (a) first-frame
    cost of a message list of N wrapped-text rows (one in 20 also carrying
    a small in-memory image) for N = 100/1,000/10,000; (b) per-frame cost
    of scrolling that list, 200 ticks; (c) the input-box case — a
    fixed-height field at the bottom of the screen growing by a line 40
    times, with the message list above it filling the rest of the screen.
    Run: `cd iris && cargo bench --bench message_list` (always release —
    `cargo bench` builds the `bench` profile, which is optimized).
  - `iris/examples/bench_images.rs` — needs a real device, so it runs
    through `iris/run-headless.sh bench_images`, printing
    `UiRenderNode::take_image_bind_group_creates()` (a new counter, added
    in `core/src/render/texture.rs` and `core/src/render/mod.rs`,
    mirroring `UiRenderState::take_counters`) each frame. Covers (d): 1,000
    image rows, checked both cold (does bind-group creation reach zero
    once loaded) and after appending one more image once settled (does
    *that* stay cheap) — the second question is what actually matters for
    a live transcript and is what turned up the two Fix items above.
  - `iris/run-bench.sh [list|images]` runs either or both and is what to
    run before/after touching `Scroll`, `Span`, `Sized`, the move-offset
    chain, or `GpuTextures`.
  **Numbers (2026-09-05, release, `cargo bench`/`run-headless.sh`, this
  VM: AMD Ryzen 7 3800X, 8 cores, rustc 1.98.0 nightly-2026-09-03):**
      cd iris && cargo bench --bench message_list
      (a) first frame, N=100:    30.30ms  draws=227   rewrites=15   moves=0
      (a) first frame, N=1000:  186.04ms  draws=2252  rewrites=150  moves=0
      (a) first frame, N=10000:1770.36ms  draws=22502 rewrites=1500 moves=0
      (b) scroll, N=100/1000/10000, 200 ticks each:
          draws=200 rewrites=0 moves=200 (identical at every N)
          per-tick average: 0.0002ms (identical at every N)
      (c) input grows 40 lines, N=100/1000/10000 rows above it:
          draws=320 rewrites=40 moves=160 (identical at every N)
          per-line average: 0.0012-0.0013ms (identical at every N)
      cd iris && ./run-bench.sh images        (2026-09-05, before the fix)
      frame=1 bind_group_creates=1000   (cold load)
      frame=2 bind_group_creates=1000   (see Fix item above)
      frame=3 bind_group_creates=0
      frame=4 bind_group_creates=0
      (append one image here)
      frame=5 bind_group_creates=1001   (see Fix item above)
      frame=6 bind_group_creates=0
      cd iris && ./run-bench.sh images        (2026-09-05, after the fix)
      frame=1 bind_group_creates=1000   (cold load, unchanged -- genuine work)
      frame=2 bind_group_creates=0
      frame=3 bind_group_creates=0
      frame=4 bind_group_creates=0
      (append one image here)
      frame=5 bind_group_creates=1      (one image's own create_image, O(1))
      frame=6 bind_group_creates=0
  **Reading it**: (a) is real, necessary work — shaping and laying out N
  never-before-seen text rows — and scales with N as it must, ~10x cost
  per 10x N. (b) and (c) are the pass conditions that matter: both are
  **exactly flat across N = 100 to 10,000**, confirming LAYOUT.md's O(1)
  move chain holds for both scrolling and for a growing input box pushing
  the message list — draws/moves per tick or per line do not grow with
  list size, and the per-operation cost (a fraction of a microsecond) is
  nowhere near a frame budget. (d)'s cold-load and steady-state halves
  behave as designed; its *append* half did not, until the fix above moved
  masks/move_offsets out of the per-image bind group — now flat at O(1)
  the same way (b) and (c) are.
 - **I5's transcript screen (`iris/transcript-ui/`, 2026-09-05) — what it
  left, each recorded at the point in the code it would go rather than
  silently dropped. See RUST.md's I5 box for the full account of what
  *was* built (the screen, `SpanStyle`, cross-row selection, the growing
  composer).**
  - [ ] **Android integration for this screen does not exist yet.** No
    cdylib/Gradle shell the way `iris-android-app` wraps `tabs-ui` (I2),
    so `transcript-bench.sh`'s render-number pass condition against the
    Compose baseline cannot be run. Needs: real `client-core::ApiClient`/
    `event_stream::follow_session_events` wiring against
    `app/ui-sandbox.sh --delay` (this crate deliberately fetches nothing
    itself, `transcript-ui/src/lib.rs`'s doc), a new cdylib + Gradle
    module, then the bench script pointed at it.
  - [x] **Touch-drag panning over a row's own rendered text — done,
    2026-09-05.** `row.rs` used to register `CursorSense::click_or_drag()`
    on each row's `TextEdit` for cross-row selection; `TextEdit::draw`'s
    `painter.child_layer()` (`iris/src/widget/text/edit.rs:87`) meant that
    registration won `core/src/sense.rs::run_sensors`'s per-layer
    arbitration on every frame it was pressed, not just the frame the
    press started, so a list pan gesture registered on `List` itself never
    got a turn while a row was under the finger. Fixed with
    `iris::sense::DragArbiter` (recorded in `IRIS.md`), one small state
    machine per list deciding pan vs. select the way Android does (a
    vertical drag pans immediately; a stationary press held `LONG_PRESS`
    (500ms) starts a selection which further drag extends; a horizontal
    drag while something is already selected extends immediately) —
    `transcript-ui/src/selection.rs`'s `Selection::drag` is the one place
    every row's drag now routes through. 8 new unit tests
    (`iris/src/sense.rs`'s `drag_arbiter_tests`); `cargo fmt/clippy/test
    --workspace` and `cargo ndk` (both `iris` and `transcript-ui`) all
    clean; `run-headless.sh` screenshot byte-identical to before the
    change (38578 bytes). See RUST.md's I5 box, "Gap closed, 2026-09-05".
  - [ ] **Row-level accessibility names.** The composer carries
    `.label("Message")`; transcript rows do not carry a `.label()` of
    their own yet, so `Widgets::named()` (I4) does not include them —
    `row.rs`'s `build_text_row` is where one would go, keyed to something
    stable per row (its sender + a short excerpt, matching what a screen
    reader announcing a chat message would say).
  - [ ] **A tappable link and a background chip behind inline code.**
    Both need per-range glyph geometry that `TextEditCtx` does not expose
    outside `iris::widget::text` (`edit.rs`'s `layout()` helper is
    private) — see `markdown.rs`'s module doc for the exact shape the fix
    would take (the same primitive `TextEdit::draw`'s own selection
    highlight already uses internally,
    `iris/src/widget/text/edit.rs:99`).
  - [ ] **`Selection`'s anchor-row shortcut.** The row a drag started in
    is selected in full (`select_all`) the moment the drag leaves it,
    rather than "from the click point to whichever edge points away from
    the drag" — needs the same private `layout()` access as the item
    above. `selection.rs`'s module doc has the exact reasoning.
  - [ ] **No syntax highlighting inside a fenced code block.**
    `client_core::highlight` exists (built for the file explorer) and
    could feed per-token `SpanStyle`s into a code block's span; wiring it
    in was not attempted this pass.
 - [ ] **Masks defined relative to each other.** Wanted: mask A multiplies
  by something *and also* applies mask B — a mask can reference a parent
  mask, the way the move chain references a parent offset. Today masks
  are independent regions. Design it beside the move chain (same shape:
  a parent index and a bounded walk in the shader); do it when a real
  widget needs it, not before.
 - [ ] **Positions as a single float per scroll.** Iris raised, and half
  rejected, letting a scroll update one float rather than positions:
  input handling cares about most elements in a list, so absolute
  positions must be computed on the CPU anyway. LAYOUT.md's design
  already lands here (GPU walks the chain, CPU resolves on demand for
  hit tests). Keep the CPU resolution lazy and per query; do not
  materialise every row's absolute position per frame.
 - [ ] **Animations, last.** Cosmetic, so after everything above. Must be
  **modular — a piece of the library rather than a core part forced into
  everything, the same way input is**. Whatever the mechanism, a widget
  that does not animate must pay nothing and import nothing for it.
 ## Reconsider
 - [ ] **`WidgetView`.** Iris is unsure of it: what she wants is an easy way
  to compose a widget from others (a button is the main case). With
  sizing folded into `draw`, composing may be easy enough that `View` is
  redundant. Decide after the layout change lands, by writing a button
  both ways and keeping the one that is shorter to explain; delete the
  other rather than keeping two ways.
@@ -0,0 +1,141 @@
 # Subagents
 A session's subagents -- the helpers a Claude Code session starts through its
 Task tool -- each get a transcript of their own, listed under the session's
 card and readable in the same transcript view the session has. Designed
 2026-09-05; the decisions Bryan has not yet reviewed are in `DECISIONS.md`.
 ## What a subagent is here
 **A subagent is a second transcript owned by a session, in the same event
 model, with no process and no controls.** It is not a session: it cannot be
 messaged, stopped or started, and it has no setup, model or usage of its
 own. Everything it shares with a session -- the transcript file format, the
 paging routes, the SSE stream, the phone's cache and rendering -- is reused
 by addressing, not by copying.
 The CLI reports a subagent's messages on the parent's own stream-json
 output, each carrying `parent_tool_use_id` = the id of the Task `tool_use`
 that started it. Before this the translator dropped those lines
 (`subagent_events_are_not_duplicated_into_the_transcript`); now it routes
 them to that subagent's own translator and transcript. The parent's
 transcript still shows only the Task call itself.
 ## Storage
 Under the session directory:
 ```
 <session>/subagents/<tool_use_id>/meta.json        {title, created}
 <session>/subagents/<tool_use_id>/transcript.jsonl same SeqEvent lines as the session's
 ```
 The id is the Task tool_use id (`toolu_…`), which is unique, stable across a
 backend restart, and already the key everything on the parent side uses.
 Only ids matching `[A-Za-z0-9_-]+` are ever created or looked up, since the
 id becomes a path.
 The transcript's sequence numbers are its own, starting at 1. `Transcript`,
 `read_window`, `catch_up` and `read_after` work on it unchanged.
 Its path out: deleting the session deletes its directory, subagents included.
 There is no separate delete.
 ## Lifecycle, as events in the subagent's transcript
 1. Created on the first child line for an unseen parent id (or, when the
   parent Task call was seen, at that call). First lines written:
   `Status Running`, then `UserMessage { text: <the Task's prompt> }` when
   the prompt is known -- it genuinely is the subagent's first user turn.
 2. Every child line is translated by that subagent's own `Translator`
   (one per subagent: tool ids are unique but streaming deltas are by
   content-block index, and parallel subagents interleave).
 3. **The parent's `tool_result` never finishes a subagent.** The Task tool
   runs in the background by default: the `tool_result` -- "Async agent
   launched..." -- arrives the moment it *starts*, while the subagent goes
   on working for however long its own turn takes, sometimes minutes. What
   ends it is its own turn ending: the raw API's `message_delta` on its
   stream carrying `stop_reason: "end_turn"` (a `stop_reason` of `tool_use`
   is the model about to call one, not an end), or a `result` line for its
   own turn if a future CLI version ever sends one. Either maps to
   `Status Exited`; the subagent's vocabulary has no `Idle`, so the
   equivalent event `dispatch` produces for an ordinary session is dropped
   rather than written. A shipped version of this finished on the
   `tool_result` instead, which read a running background agent as
   "finished" with its transcript truncated at the moment it launched.
 4. **A child line for a subagent that already finished reopens it**
   (`Status Running`) rather than being dropped: a background Task can be
   sent another message long after its first turn ended, and that is
   exactly what a further line for it means. Same transcript, same child
   `Translator`, just picking back up.
 5. When the parent session's process exits (`Status Exited` on the
   session), every subagent still `Running` gets `Status Exited` too: its
   process was the parent's.
 A subagent that was mid-flight when the backend restarted keeps working:
 the registry reopens the existing transcript on the next child line, and
 the file continues its sequence -- the same reopening #4 describes, whether
 what closed it was a restart or its own `end_turn`. If its turn ended while
 the backend was down nothing recorded that until the next line arrives, so
 its last status stays `Running`, which the list reports as **unknown**
 rather than as running (see the wire shape) until then.
 Title: the Task call's `description` input, then ` (<subagent_type>)` when
 one is given; falling back to the tool's name when the child arrives before
 (or without) the parent call being seen.
 ## Server layout
 - `session/subagent.rs` -- the registry: `Subagents` (per session, in
  `Shared`), `Subagent` (its `Transcript` behind a mutex plus a
  `broadcast::Sender<SeqEvent>`), `record(id, event)`, `start(id, title,
  prompt)`, `finish(id)`, `reopen(id)`, `finish_all()`, `list()` from disk. Drivers get an
  `Arc<Subagents>` beside their `EventSink`; llama ignores it.
 - `session/claude/translate.rs` -- routes child lines by parent id, holds
  one child `Translator` per subagent, remembers pending Task calls'
  description/prompt/subagent_type.
 - `session/echo.rs` -- `/subagent [n]`: the test rig. Starts *n* (default 1)
  subagents at once, each named "helper k". Each writes the prompt as its
  user message, streams a few words of text, runs one `Bash` tool call, then
  finishes about three seconds after starting, and the parent's Task calls
  end when their subagent does. Three seconds so the running state can be
  seen on the phone.
 - `routes.rs` -- three routes, in the doc table.
 ## Wire shape
 ```
 GET /sessions/{id}                       SessionInfo gains `subagents: N` (count, 0 when none)
 GET /sessions                            same field on each row
 GET /sessions/{id}/subagents             [{id, title, status, created, lastActivity}], oldest first
 GET /sessions/{id}/subagents/{sub}/transcript   exactly the session transcript's query and answer
 GET /sessions/{id}/subagents/{sub}/events?after=N  exactly the session events stream
 ```
 `status` is the transcript's last `Status` event, serialised like a session's
 (`running`, `exited`), except that a subagent whose session is not itself
 running cannot be running: the list answers `unknown` for that one. The
 phone words these as *running*, *finished* and *unknown* on the subcard.
 The count on `SessionInfo` is a directory listing, so the list stays cheap.
 The per-subagent status is only read when the list route is asked for.
 ## Phone
 - `SessionSummary.subagents: Int`. A card with a non-zero count ends in an
  expander row -- a full-width `Chevron(Pointing.Down)` row that flips to
  `Pointing.Up` -- collapsed by default. Expanding fetches
  `/sessions/{id}/subagents` and draws one `OutlinedCard` per subagent,
  indented inside the session card, the way dev-updater draws a project's
  components: title, then the status word and a relative time. The
  expansion state is per session id and survives a refresh of the list.
 - Tapping a subcard opens `Screen.Subagent`, which is `SessionScreen` in
  **read-only** form: the same transcript, paging, cache, selection,
  images and status row, with the composer, the process button, the model
  picker, the files button, the settings cog and the usage bar left out.
  The header shows the subagent's title with the session's title beneath
  it. Back returns to the list.
 - Addressing: `fetchTranscript`, `EventStream`, `TranscriptSource` and the
  cache take a transcript address rather than a session id --
  `sessions/{id}` or `sessions/{id}/subagents/{sub}` -- so the cache nests a
  subagent's copy under its session's and the same code serves both.
@@ -50,6 +50,12 @@ 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"
@@ -77,6 +83,7 @@ name = "client-core"
 version = "0.1.0"
 dependencies = [
 "event-model",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
@@ -206,6 +213,15 @@ dependencies = [
 "percent-encoding",
 ]
 [[package]]
 name = "getopts"
 version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
 dependencies = [
 "unicode-width",
 ]
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -490,6 +506,25 @@ dependencies = [
 "unicode-ident",
 ]
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9f068eba8e7071c5f9511831b44f32c740d5adf574e990f946ddb53db2f314e"
 dependencies = [
 "bitflags",
 "getopts",
 "memchr",
 "pulldown-cmark-escape",
 "unicase",
 ]
 [[package]]
 name = "pulldown-cmark-escape"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -783,12 +818,24 @@ dependencies = [
 "zerovec",
 ]
 [[package]]
 name = "unicase"
 version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -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
@@ -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">
@@ -142,6 +142,20 @@ data class SessionSummary(
    val keepsOwnTranscript: Boolean,
    /** How much the session asks before acting; null when it was never set. */
    val permissionMode: String?,
    /**
     * How hard the model thinks, or null for the CLI's own default.
     *
     * Null is a level somebody can choose, not only one to start in -- see [EFFORT_LEVELS]. It is
     * reported rather than assumed for the same reason [permissionMode] is.
     */
    val effort: String?,
    /**
     * Whether a thinking level does anything here -- a Claude CLI session, not a llama or echo one.
     *
     * Asked of the server rather than worked out from the provider's name, because this is a
     * property of the driver's *kind* and the phone only has the name.
     */
    val takesEffort: Boolean,
    /**
     * Whether this continues a session the machine already had, which changes what deleting means.
     */
@@ -153,6 +167,24 @@ data class SessionSummary(
     * itself from a default is one you can turn off while believing you are reading it.
     */
    val notify: Boolean,
    /**
     * Whether this session sends itself a message once its account's usage limit lifts, and what
     * that message says.
     *
     * The message is what the server would actually send, with its own default already filled in,
     * so the field shows the words rather than an empty box standing for them.
     */
    val autoResume: Boolean,
    val autoResumeMessage: String,
    /**
     * When the server next intends to check whether the limit has lifted, in epoch seconds, or null
     * when nothing is waiting.
     *
     * A time to *ask*, not a time to resume: the server checks the meter at that moment and waits
     * again if the limit is still on. Worded that way wherever it is shown, because a promise this
     * app cannot keep is worse than no time at all.
     */
    val resumeAt: Double?,
    /**
     * The directory the session works in, or null where it was never given one.
     *
@@ -178,8 +210,27 @@ data class SessionSummary(
     * server because that is where a provider's kind is known.
     */
    val maxImageEdge: Int?,
    /**
     * Which of `GET /usage`'s snapshots is about this session, and null where nothing meters it.
     *
     * The rate-limit bar answers a question about an *account*, and what decides which account --
     * if any -- is the provider this session runs, not the machine it runs on. Pairing by machine
     * alone drew the Claude CLI's five-hour window under every echo session on a machine that also
     * has the CLI: a quota that session cannot spend and could never run down. Decided by the
     * server for the same reason [maxImageEdge] is -- it is a fact about the provider's kind, and
     * this app has only its name.
     */
    val usageProvider: String?,
    val status: String,
    val lastActivity: Double,
    /**
     * How many subagents this session has, however their own status now reads.
     *
     * A directory listing on the server rather than a status read per subagent, so the list stays
     * cheap; the per-subagent state is only fetched when the card is expanded. Zero on a server
     * that predates subagents, so this app still opens against one.
     */
    val subagents: Int,
 )
 private fun parseSession(session: JSONObject) =
@@ -192,14 +243,24 @@ private fun parseSession(session: JSONObject) =
        title = session.getString("title"),
        model = session.optString("model").ifEmpty { null },
        permissionMode = session.optString("permissionMode").ifEmpty { null },
        effort = session.optString("effort").ifEmpty { null },
        takesEffort = session.optBoolean("takesEffort", false),
        imported = session.optBoolean("imported", false),
        notify = session.optBoolean("notify", true),
        autoResume = session.optBoolean("autoResume", false),
        // The server sends its own default rather than nothing, so an empty answer means an older
        // server -- and this app's word for it is the same word.
        autoResumeMessage =
            session.optString("autoResumeMessage").ifEmpty { DEFAULT_RESUME_MESSAGE },
        resumeAt = if (session.has("resumeAt")) session.getDouble("resumeAt") else null,
        cwd = session.optString("cwd").ifEmpty { null },
        contextTokens =
            if (session.has("contextTokens")) session.getLong("contextTokens") else null,
        maxImageEdge = session.optInt("maxImageEdge", 0).takeIf { it > 0 },
        usageProvider = session.optString("usageProvider").ifEmpty { null },
        status = session.getString("status"),
        lastActivity = session.getDouble("lastActivity"),
        subagents = session.optInt("subagents", 0),
    )
 fun fetchSessions(settings: ServerSettings): List<SessionSummary> =
@@ -215,6 +276,35 @@ fun fetchSessions(settings: ServerSettings): List<SessionSummary> =
 fun fetchSession(settings: ServerSettings, sessionId: String): SessionSummary =
    requestFromServer(settings, "/sessions/$sessionId") { parseSession(it.jsonObject()) }
 /**
 * One row of `GET /sessions/{id}/subagents`, oldest first.
 *
 * A subagent is a second transcript owned by a session -- no process, no controls of its own -- so
 * this carries only what a card needs to draw and to open it; see SUBAGENTS.md. [status] is
 * "running", "exited" or "unknown": a subagent whose session is not itself running cannot be
 * running, and the list says so rather than reporting a state that cannot hold.
 */
 data class SubagentSummary(
    val id: String,
    val title: String,
    val status: String,
    val created: Double,
    val lastActivity: Double,
 )
 fun fetchSubagents(settings: ServerSettings, sessionId: String): List<SubagentSummary> =
    requestFromServer(settings, "/sessions/$sessionId/subagents") {
        it.jsonObjects { row ->
            SubagentSummary(
                id = row.getString("id"),
                title = row.getString("title"),
                status = row.getString("status"),
                created = row.getDouble("created"),
                lastActivity = row.getDouble("lastActivity"),
            )
        }
    }
 // What the server offers, so the spawn screen has no hardcoded lists: a setup added to the server's
 // config.ron appears here with no app rebuild.
 //
@@ -375,6 +465,12 @@ data class SshDetails(
     * Where files attached from here land on that machine; null for the session's own directory.
     */
    val attachmentsDir: String? = null,
    /**
     * Where that machine keeps its GGUF models; null for the same place the backend keeps its own
     * (`~/.local/share/ai-app/models`, read on that machine). A llama.cpp session serves the file
     * from the machine it runs on, so this is where its models are looked for and listed.
     */
    val modelsDir: String? = null,
 )
 private fun SshDetails.toJson() =
@@ -382,6 +478,7 @@ private fun SshDetails.toJson() =
        if (port != null) put("port", port)
        if (!identityFile.isNullOrBlank()) put("identityFile", identityFile)
        if (!attachmentsDir.isNullOrBlank()) put("attachmentsDir", attachmentsDir)
        if (!modelsDir.isNullOrBlank()) put("modelsDir", modelsDir)
    }
 /** What a machine turns out to have, without saving anything. */
@@ -450,6 +547,8 @@ fun spawnSession(
    model: String? = null,
    cwd: String? = null,
    permissionMode: String? = null,
    /** Null for whatever the server's default is; see [fetchDefaultEffort]. */
    effort: String? = null,
    params: Map<String, String> = emptyMap(),
    /** Continue this Claude Code session instead of starting an empty one. */
    import: String? = null,
@@ -467,6 +566,7 @@ fun spawnSession(
                    if (!model.isNullOrBlank()) put("model", model)
                    if (!cwd.isNullOrBlank()) put("cwd", cwd)
                    if (!permissionMode.isNullOrBlank()) put("permissionMode", permissionMode)
                    if (!effort.isNullOrBlank()) put("effort", effort)
                    if (!import.isNullOrBlank()) put("import", import)
                    if (params.isNotEmpty()) {
                        put("params", JSONObject(params.toMap<String, Any>()))
@@ -906,7 +1006,7 @@ fun startImport(
 */
 fun fetchTranscript(
    settings: ServerSettings,
-    sessionId: String,
+    address: TranscriptAddress,
    before: Long? = null,
    limit: Int = 80,
    // Count [limit] in rows, not events, joining a reply's streamed deltas into one -- so a page of
@@ -925,7 +1025,7 @@ fun fetchTranscript(
        if (coalesce) append("&coalesce=true")
        if (after != null) append("&after=").append(after)
    }
-    return requestFromServer(settings, "/sessions/$sessionId/transcript$query") { connection ->
+    return requestFromServer(settings, "/${address.urlPath}/transcript$query") { connection ->
        val body = JSONArray(connection.inputStream.bufferedReader().readText())
        // The text as well as the event: the transcript cache stores the one and the fold needs the
        // other, and they have to be the same line.
@@ -973,6 +1073,56 @@ fun setSessionModel(settings: ServerSettings, sessionId: String, model: String)
 */
 val PERMISSION_MODES = listOf("manual", "acceptEdits", "auto", "bypassPermissions", "plan")
 /**
 * What a new session's thinking level is when nothing chose one, or null for the CLI's own.
 *
 * Held by the server rather than by this phone, because a second device would otherwise spawn
 * sessions at a level the first one's owner never picked.
 */
 fun fetchDefaultEffort(settings: ServerSettings): String? =
    requestFromServer(settings, "/defaults") {
        it.jsonObject().optString("effort").ifEmpty { null }
    }
 /** Sets what new sessions start at. Nothing already running changes. */
 fun setDefaultEffort(settings: ServerSettings, level: String?) {
    requestFromServer(
        settings,
        "/defaults",
        method = "POST",
        jsonBody = JSONObject().put("effort", level ?: JSONObject.NULL).toString(),
    ) {}
 }
 /**
 * How hard the model thinks, as `claude --effort` takes them, cheapest first.
 *
 * Not offered alongside the model and the permission mode on the session's own bar, because it does
 * not behave like them: the CLI has a control request for those two and none for this (checked
 * against 2.1.258), so a level is settled when the process is launched. Changing it therefore stops
 * the process, which is what the working directory beside it in this dialog does, and why it is
 * here rather than on a bar whose other controls take effect mid-turn.
 */
 val EFFORT_LEVELS = listOf("low", "medium", "high", "xhigh", "max")
 /** What the picker shows, and sends as null, for a session that has chosen no level. */
 const val DEFAULT_EFFORT = "default"
 /**
 * Records how hard a session thinks and **stops its process**, since the level is read when the
 * process is launched. The next message, or Start, runs one that has it.
 *
 * [level] is null for the CLI's own default.
 */
 fun setSessionEffort(settings: ServerSettings, sessionId: String, level: String?) {
    requestFromServer(
        settings,
        "/sessions/$sessionId/effort",
        method = "POST",
        jsonBody = JSONObject().put("effort", level ?: JSONObject.NULL).toString(),
    ) {}
 }
 /** Switches how much a running session asks before acting, also in place. */
 fun setSessionPermissionMode(settings: ServerSettings, sessionId: String, mode: String) {
    requestFromServer(
@@ -984,6 +1134,36 @@ fun setSessionPermissionMode(settings: ServerSettings, sessionId: String, mode:
 }
 /** Turns this session's notifications on or off. Stored on the backend -- see `SessionConfig`. */
 /**
 * What an auto-resume says when nothing else was typed. Mirrors the server's own default, so a
 * cleared field shows the word that would actually be sent instead of going blank.
 */
 const val DEFAULT_RESUME_MESSAGE = "continue"
 /**
 * Turns auto-resume on or off and sets what it would say, in one request because they are one
 * decision -- see the server's `/sessions/{id}/auto-resume`.
 */
 fun setSessionAutoResume(
    settings: ServerSettings,
    sessionId: String,
    autoResume: Boolean,
    message: String?,
 ) {
    requestFromServer(
        settings,
        "/sessions/$sessionId/auto-resume",
        method = "POST",
        jsonBody =
            JSONObject()
                .put("autoResume", autoResume)
                // Empty means the server's default rather than a session poked with nothing to
                // read, which is the same rule the server applies to the field.
                .put("message", message?.trim()?.ifEmpty { null } ?: JSONObject.NULL)
                .toString(),
    ) {}
 }
 fun setSessionNotify(settings: ServerSettings, sessionId: String, notify: Boolean) {
    requestFromServer(
        settings,
@@ -1074,6 +1254,26 @@ private fun parseDownload(o: JSONObject) =
        error = if (o.has("error")) o.getString("error") else null,
    )
 /**
 * The models on one machine, which is the list a llama.cpp session there can choose from.
 *
 * Not [fetchModels], which is what the *backend* has downloaded. A session serves its model from
 * the machine it runs on, so for a machine reached over ssh those are two different lists -- and
 * offering the backend's would name files that are not there, turning a choice that cannot work
 * into a session that fails when it tries to load one.
 */
 fun fetchSetupModels(settings: ServerSettings, setupId: String): List<LocalModel> =
    requestFromServer(settings, "/setups/${setupId.urlEncoded()}/models") { connection ->
        JSONArray(connection.inputStream.bufferedReader().readText()).mapObjects { m ->
            LocalModel(
                key = m.getString("key"),
                repo = m.getString("repo"),
                file = m.getString("file"),
                bytes = m.getLong("bytes"),
            )
        }
    }
 fun fetchModels(settings: ServerSettings): Models =
    requestFromServer(settings, "/models") { connection ->
        val body = JSONObject(connection.inputStream.bufferedReader().readText())
@@ -1,7 +1,9 @@
 package com.example.aiapp
 import androidx.activity.compose.BackHandler
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.imePadding
 import androidx.compose.foundation.layout.padding
 import androidx.compose.material3.AlertDialog
@@ -34,7 +36,23 @@ import kotlinx.coroutines.withContext
 * session, spawning one, and settings.
 */
 private sealed class Screen {
-    data object Main : Screen()
+    /**
     * The session list, with a subagent's own transcript over it when [subagent] is set.
     *
     * A layer on this screen rather than a screen of its own, for the same reason [Session.files]
     * is: [SessionListScreen] owns which cards are expanded and what each expansion fetched, kept
     * in `remember`, and a subagent is opened from a card's expander. As a sibling `Screen` it was
     * disposed and recreated on every return, which lost that state -- an expanded card collapsed
     * itself the moment its own subagent's view was closed.
     */
    data class Main(val subagent: SubagentTarget? = null) : Screen()
    /**
     * One subagent's own transcript, read-only. See [SessionScreen]'s `subagent` parameter and
     * SUBAGENTS.md's "Phone". Closing it returns to [Main] under it, not to [Session]: a subagent
     * is opened from the session list's card rather than from inside the session it belongs to.
     */
    data class SubagentTarget(val summary: SessionSummary, val subagent: SubagentSummary)
    /**
     * One session, with the file explorer over it when [files] is set.
@@ -81,7 +99,7 @@ fun AppRoot(
    val context = LocalContext.current
    val scope = rememberCoroutineScope()
    var settings by remember(settingsVersion) { mutableStateOf(loadServerSettings(context)) }
-    var screen by remember { mutableStateOf<Screen>(Screen.Main) }
+    var screen by remember { mutableStateOf<Screen>(Screen.Main()) }
    // A notification tap this could not follow, and why. Null both before one is asked for and
    // after one succeeds, since success is a screen rather than a message.
    var failedOpen by remember { mutableStateOf<FailedOpen?>(null) }
@@ -96,7 +114,7 @@ fun AppRoot(
            share = shareRequest
            // A session already open takes it. Otherwise the list is where the choice is made,
            // whatever screen was showing: Spawn and Settings have nowhere to put a file.
-            if (screen !is Screen.Session) screen = Screen.Main
+            if (screen !is Screen.Session) screen = Screen.Main()
        }
    }
@@ -123,7 +141,7 @@ fun AppRoot(
                existing = null,
                onSaved = { saved ->
                    settings = saved
-                    screen = Screen.Main
+                    screen = Screen.Main()
                },
                onBack = null,
            )
@@ -136,7 +154,7 @@ fun AppRoot(
    // shows, so it always refetches.
    val goToMain = {
        reloadToken++
-        screen = Screen.Main
+        screen = Screen.Main()
    }
    if (screen !is Screen.Main) {
        BackHandler(onBack = goToMain)
@@ -185,6 +203,9 @@ fun AppRoot(
                    reloadToken = reloadToken,
                    share = share,
                    onOpen = { screen = Screen.Session(it) },
                    onOpenSubagent = { summary, subagent ->
                        screen = here.copy(subagent = Screen.SubagentTarget(summary, subagent))
                    },
                    onSpawn = { screen = Screen.Spawn },
                    onImported = { imported ->
                        reloadToken++
@@ -192,6 +213,27 @@ fun AppRoot(
                    },
                    onSettings = { screen = Screen.Settings },
                )
                // Its own back handler is registered after MainScreen's, so it is the one the
                // platform asks first while a subagent is open -- the same rule the files
                // explorer's handler follows over its session, below.
                here.subagent?.let { target ->
                    BackHandler { screen = here.copy(subagent = null) }
                    // Its own opaque background: this screen was always the sole content under
                    // the theme's own Surface before, so it never had to paint one -- stacked over
                    // the list here, the space between its own cards let the list underneath show
                    // through without this. The same fix FilesScreen needed over its session.
                    Box(Modifier.fillMaxSize().background(MaterialTheme.colorScheme.background)) {
                        key(target.summary.id, target.subagent.id) {
                            SessionScreen(
                                settings = current,
                                summary = target.summary,
                                onBack = { screen = here.copy(subagent = null) },
                                onFiles = {},
                                subagent = target.subagent,
                            )
                        }
                    }
                }
            }
        is Screen.Session ->
            // Keyed on the id, because a different session is a different screen rather than this
@@ -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 }
    }
 }
@@ -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
    }
 }
@@ -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()})"
    }
 }
@@ -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. */
@@ -12,6 +12,10 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
 import java.time.Instant
 import java.time.ZoneId
 import java.time.format.DateTimeFormatter
 import java.time.format.FormatStyle
 /**
 * A line across the transcript saying what left the session's context.
@@ -47,3 +51,40 @@ fun TranscriptDivider(text: String, color: Color, modifier: Modifier = Modifier)
 fun ClearedRow(modifier: Modifier = Modifier) {
    TranscriptDivider("Context cleared", clearedColor, modifier)
 }
 /**
 * The mark running out of quota leaves.
 *
 * The same red the usage bar takes when a window is spent, because it is the same fact in a second
 * place: colour by consequence, so "there is nothing left to spend" is learned once.
 *
 * A time rather than a countdown. The row is folded once and never re-measured, so a span would go
 * stale on screen the moment it was drawn; and this is when the *account* said it would reset,
 * which is not a promise about when the session picks back up. A limit the session was told no
 * reset time for says nothing about one -- that state has its own words rather than a plausible
 * number.
 */
@Composable
 fun LimitRow(item: TranscriptItem.LimitNote, modifier: Modifier = Modifier) {
    TranscriptDivider(limitSummary(item.resetsAt, ZoneId.systemDefault()), overLimitColor, modifier)
 }
 /**
 * What the row says. Split out so the wording is testable without a screen, since the two states it
 * has to keep apart -- a reset time that arrived and one that never did -- are exactly the pair
 * that reads the same when it goes wrong.
 *
 * [zone] is a parameter rather than read here so a test says the same thing wherever it runs.
 */
 fun limitSummary(resetsAt: Double?, zone: ZoneId): String {
    val at = resetsAt?.let {
        try {
            DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT)
                .withZone(zone)
                .format(Instant.ofEpochSecond(it.toLong()))
        } catch (_: Exception) {
            null
        }
    }
    return if (at == null) "Usage limit reached" else "Usage limit reached • resets $at"
 }
@@ -14,7 +14,7 @@ private const val RESET_EVENT = "reset"
 * mean. [close] from any thread ends it, and the caller owns reconnecting -- with the last seq it
 * saw as the new cursor.
 */
-class EventStream(settings: ServerSettings, private val sessionId: String) {
+class EventStream(settings: ServerSettings, private val address: TranscriptAddress) {
    private val stream = Sse(settings)
    fun close() = stream.close()
@@ -35,7 +35,7 @@ class EventStream(settings: ServerSettings, private val sessionId: String) {
        // one and the screen folds the other, and they have to be the same line.
        onEvent: (raw: String, event: SeqEvent) -> Unit,
    ) {
-        stream.run("/sessions/$sessionId/events?after=$after", onOpen) { name, data ->
+        stream.run("/${address.urlPath}/events?after=$after", onOpen) { name, data ->
            // A named frame carries no payload and a data frame has no name.
            if (name == RESET_EVENT) onReset()
            else if (data.isNotEmpty()) onEvent(data, parseSeqEvent(data))
@@ -157,6 +157,18 @@ sealed class SessionEvent {
     */
    data object Cleared : SessionEvent()
    /**
     * The session stopped because its account's usage limit was reached.
     *
     * Its own event rather than an [Error] carrying the CLI's sentence, because it is a state
     * rather than something that went wrong -- and because the raw sentence is `Claude AI usage
     * limit reached|1788546972`, which is not readable by the person it is shown to.
     *
     * [resetsAt] is epoch seconds and null where the session was told nothing. Only the server acts
     * on it; what this draws it as is a time, not a countdown, because nothing here re-measures it.
     */
    data class LimitReached(val resetsAt: Double?) : SessionEvent()
    data class Error(val message: String) : SessionEvent()
    /**
@@ -261,6 +273,10 @@ fun parseSeqEvent(json: String): SeqEvent {
                    trigger = body.optString("trigger").ifEmpty { null },
                )
            "cleared" -> SessionEvent.Cleared
            "limitReached" ->
                SessionEvent.LimitReached(
                    if (body.has("resetsAt")) body.getDouble("resetsAt") else null
                )
            "error" -> SessionEvent.Error(body.getString("message"))
            else -> SessionEvent.Unknown(type)
        }
@@ -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
@@ -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) {
@@ -48,6 +48,8 @@ fun MainScreen(
    /** What another app shared in and no session has taken yet; see [ShareRequest]. */
    share: ShareRequest? = null,
    onOpen: (SessionSummary) -> Unit,
    /** Opens one session's subagent, from the expander under its card. */
    onOpenSubagent: (SessionSummary, SubagentSummary) -> Unit,
    onSpawn: () -> Unit,
    onImported: (SessionSummary) -> Unit,
    onSettings: () -> Unit,
@@ -139,6 +141,7 @@ fun MainScreen(
                    settings = settings,
                    reloadToken = token,
                    onOpen = onOpen,
                    onOpenSubagent = onOpenSubagent,
                    onSpawn = onSpawn,
                )
            MainTab.Import ->
@@ -1,7 +1,9 @@
 package com.example.aiapp
 import androidx.compose.foundation.ExperimentalFoundationApi
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.combinedClickable
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
@@ -9,6 +11,7 @@ import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.heightIn
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.lazy.LazyColumn
@@ -17,6 +20,7 @@ import androidx.compose.material3.Card
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.FloatingActionButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedCard
 import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
@@ -30,6 +34,8 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.semantics
 import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -47,12 +53,40 @@ fun SessionListScreen(
    settings: ServerSettings,
    reloadToken: Int,
    onOpen: (SessionSummary) -> Unit,
    /** Opens one session's subagent, from the expander under its card. */
    onOpenSubagent: (SessionSummary, SubagentSummary) -> Unit,
    onSpawn: () -> Unit,
 ) {
    val scope = rememberCoroutineScope()
    var listState by remember { mutableStateOf<LoadState<List<SessionSummary>>>(LoadState.Loading) }
    var confirmingDelete by remember { mutableStateOf<SessionSummary?>(null) }
    // Which session cards are expanded to show their subagents, and what each expansion fetched.
    // Ids rather than a flag on the row for the same reason `deleting` is: the rows are rebuilt
    // from
    // whatever the server last said, and this belongs to the reader's own choice, which survives a
    // refresh.
    var expandedSessions by remember { mutableStateOf(setOf<String>()) }
    var subagentLoads by remember {
        mutableStateOf(mapOf<String, LoadState<List<SubagentSummary>>>())
    }
    fun loadSubagents(sessionId: String) {
        subagentLoads = subagentLoads + (sessionId to LoadState.Loading)
        scope.launch {
            subagentLoads =
                subagentLoads +
                    (sessionId to
                        try {
                            LoadState.Loaded(
                                withContext(Dispatchers.IO) { fetchSubagents(settings, sessionId) }
                            )
                        } catch (e: ApiException) {
                            LoadState.failed(e)
                        })
        }
    }
    // Failures that belong to one session rather than to the list, keyed by its id and shown on its
    // own card. The two scopes are decided by whether the server answered: it answered and refused,
    // so this says nothing about the other rows.
@@ -84,6 +118,14 @@ fun SessionListScreen(
                    withContext(Dispatchers.IO) {
                        transcriptCache.retainOnly(loaded.value.map { it.id }.toSet())
                    }
                    // A session gone from this answer cannot still be expanded, and an expanded one
                    // that is still here asks again -- its subagents may have changed since the
                    // last
                    // fetch.
                    val ids = loaded.value.map { it.id }.toSet()
                    expandedSessions = expandedSessions intersect ids
                    subagentLoads = subagentLoads.filterKeys { it in ids }
                    expandedSessions.forEach(::loadSubagents)
                    loaded
                } catch (e: ApiException) {
                    LoadState.failed(e)
@@ -127,6 +169,17 @@ fun SessionListScreen(
                                deleting = session.id in deleting,
                                onOpen = { onOpen(session) },
                                onLongPress = { confirmingDelete = session },
                                expanded = session.id in expandedSessions,
                                subagents = subagentLoads[session.id],
                                onToggleSubagents = {
                                    if (session.id in expandedSessions) {
                                        expandedSessions = expandedSessions - session.id
                                    } else {
                                        expandedSessions = expandedSessions + session.id
                                        loadSubagents(session.id)
                                    }
                                },
                                onOpenSubagent = { subagent -> onOpenSubagent(session, subagent) },
                            )
                            Spacer(Modifier.height(12.dp))
                        }
@@ -225,7 +278,7 @@ fun SessionListScreen(
                                    deleteSession(settings, session.id, alsoDeleteForeign)
                                    // After it succeeded, not before: a refused delete leaves the
                                    // session exactly as it was, and its transcript with it.
-                                    transcriptCache.session(session.id).purge()
+                                    transcriptCache.session(TranscriptAddress(session.id)).purge()
                                }
                                // Only this row, and only what changed. Refetching the list instead
                                // put every other session back through loading and handed the
@@ -276,6 +329,12 @@ private fun SessionCard(
    deleting: Boolean,
    onOpen: () -> Unit,
    onLongPress: () -> Unit,
    /** Whether the expander below is open. Collapsed by default; see [SessionListScreen]. */
    expanded: Boolean,
    /** What the expander's own fetch answered, or null before it has been asked. */
    subagents: LoadState<List<SubagentSummary>>?,
    onToggleSubagents: () -> Unit,
    onOpenSubagent: (SubagentSummary) -> Unit,
 ) {
    BusyItem(label = if (deleting) "deleting" else null) {
        Card(
@@ -332,11 +391,105 @@ private fun SessionCard(
                        color = MaterialTheme.colorScheme.error,
                    )
                }
                // Nothing at all for a card with no subagents: a disabled expander here would be
                // noise on every ordinary session's card. Its own row at the bottom rather than
                // beside the title or the machine line, so opening it never displaces text that was
                // already on screen -- see UI_RULES on a control not displacing the text beside it.
                if (session.subagents > 0) {
                    Spacer(Modifier.height(8.dp))
                    // The platform's minimum touch height, not the chevron's own ten or so dp:
                    // at the chevron's height a tap meant for it landed on the first subcard
                    // beneath and opened a subagent instead.
                    Row(
                        horizontalArrangement = Arrangement.Center,
                        verticalAlignment = Alignment.CenterVertically,
                        modifier =
                            Modifier.fillMaxWidth()
                                .heightIn(min = 48.dp)
                                .clickable(enabled = !deleting, onClick = onToggleSubagents)
                                .semantics {
                                    contentDescription =
                                        if (expanded) "Collapse subagents" else "Expand subagents"
                                },
                    ) {
                        Chevron(if (expanded) Pointing.Up else Pointing.Down)
                    }
                    if (expanded) {
                        Spacer(Modifier.height(4.dp))
                        Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
                            when (subagents) {
                                null,
                                is LoadState.Loading ->
                                    CircularProgressIndicator(
                                        modifier = Modifier.width(20.dp).height(20.dp),
                                        strokeWidth = 2.dp,
                                    )
                                is LoadState.Error ->
                                    // Said here rather than left silent: a fetch that failed and an
                                    // expander that simply found nothing must not look the same --
                                    // see UI_RULES on designing the unknown state first.
                                    Text(
                                        subagents.message,
                                        style = MaterialTheme.typography.bodySmall,
                                        color = MaterialTheme.colorScheme.error,
                                    )
                                is LoadState.Loaded ->
                                    subagents.value.forEach { subagent ->
                                        SubagentCard(
                                            subagent,
                                            onClick = { onOpenSubagent(subagent) },
                                        )
                                    }
                            }
                        }
                    }
                }
            }
        }
    }
 }
 /**
 * One subagent, indented inside its session's card -- the way dev-updater draws a project's
 * components (`ComponentCard`, `UpdaterScreen.kt`): an outlined card, not the session card's own
 * filled one, so the nesting reads as one step rather than as another session.
 */
@Composable
 private fun SubagentCard(subagent: SubagentSummary, onClick: () -> Unit) {
    OutlinedCard(Modifier.fillMaxWidth().clickable(onClick = onClick)) {
        Column(Modifier.padding(horizontal = 12.dp, vertical = 8.dp)) {
            Text(subagent.title, style = MaterialTheme.typography.titleSmall)
            Spacer(Modifier.height(2.dp))
            Row(modifier = Modifier.fillMaxWidth()) {
                Text(
                    subagentStatusLabel(subagent.status),
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                    modifier = Modifier.weight(1f),
                )
                Text(
                    relativeTime(subagent.lastActivity),
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        }
    }
 }
 /**
 * The subcard's word for a subagent's status -- see SUBAGENTS.md's "Wire shape". Its own function
 * rather than a branch inside [StatusText], because a subagent's three states are not that
 * composable's five: "exited" reads as "finished" here, since its process was always its parent's
 * and never something of its own to have merely stopped.
 */
 private fun subagentStatusLabel(status: String) =
    when (status) {
        "running" -> "running"
        "exited" -> "finished"
        else -> "unknown"
    }
@Composable
 fun StatusText(status: String) {
    val (label, color) =
@@ -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
@@ -216,16 +220,33 @@ fun SessionScreen(
    share: ShareRequest? = null,
    /** Said once [share] has been attached here, so it is not attached again. */
    onShareTaken: () -> Unit = {},
    /**
     * Draws this screen read-only, on a subagent's own transcript instead of the session's.
     *
     * A subagent has no process and no controls of its own -- see SUBAGENTS.md's "Phone" -- so
     * every gate below keyed on this switches off the composer, the files button, the settings cog,
     * the usage bar and notifications, while everything that draws a transcript (paging, cache,
     * selection, images, the status row, stream reconnects) is reused unchanged, pointed at
     * [address] instead of the session's own.
     */
    subagent: SubagentSummary? = null,
 ) {
    DebugStats.count("session screen recomposed")
    val isSubagent = subagent != null
    val address = TranscriptAddress(summary.id, subagent?.id)
    val scope = rememberCoroutineScope()
    val topEdgeHeld = remember { TopEdgeHold() }
    var items by remember { mutableStateOf(listOf<TranscriptItem>()) }
-    var status by remember { mutableStateOf(summary.status) }
+    var status by remember { mutableStateOf(subagent?.status ?: summary.status) }
    // Seeded from the row this screen was opened from, so a conversation already under way says how
    // much it is holding before any turn happens here. Null is "nobody has measured it", which is a
    // different answer from an empty context and is drawn differently.
-    var contextTokens by remember(summary.id) { mutableStateOf(summary.contextTokens) }
+    //
    // A subagent has no context measurement of its own, so it always starts unmeasured rather than
    // borrowing the parent session's figure -- see UI_RULES on not showing an inferred value as one
    // that was measured.
    var contextTokens by
        remember(address) { mutableStateOf(if (isSubagent) null else summary.contextTokens) }
    // When the current compaction started. The moment comes off the `compacting` status event
    // itself -- the server timestamps every transcript line -- rather than off this device noticing
    // one, which is what makes it survive leaving the session and reopening it.
@@ -241,7 +262,13 @@ fun SessionScreen(
    val context = LocalContext.current
    // Seeded from what was left in the box last time and written back on every keystroke, so
    // leaving the screen does not throw away a half-typed message. See `Drafts.kt`.
-    var input by remember(summary.id) { mutableStateOf(atEnd(loadDraft(context, summary.id))) }
+    //
    // A subagent has no box to type into, so it never touches a draft at all -- not this session's,
    // which is what reading one keyed only by `summary.id` would do here.
    var input by
        remember(summary.id) {
            mutableStateOf(if (isSubagent) atEnd("") else atEnd(loadDraft(context, summary.id)))
        }
    // A model the reader has chosen and not yet confirmed. See [ModelSwitchWarning]: switching
    // makes the session re-read the whole conversation.
    var pendingModel by remember { mutableStateOf<String?>(null) }
@@ -294,27 +321,26 @@ fun SessionScreen(
    // Reload throws away what it was reading from.
    val cache = remember(settings) { TranscriptCache(cacheRoot(context, settings)) }
    val source =
-        remember(summary.id, epoch) {
+        remember(address, epoch) { TranscriptSource(settings, address, cache.session(address)) }
            TranscriptSource(settings, summary.id, cache.session(summary.id))
        }
    // Whether the cached tail has been shown to still be the server's own line. Nothing is resumed
    // from a cached cursor until it has, and a probe that could not be made leaves this false for
    // the stream loop to try again.
-    var probePassed by remember(summary.id, epoch) { mutableStateOf(false) }
+    var probePassed by remember(address, epoch) { mutableStateOf(false) }
    // Whether the opening effect is still settling that question. It draws the cached rows and
    // lifts [ready] before the answer arrives, which is the point of the cache -- so the stream
    // below waits for this rather than for `ready`, or it asks the same question twice.
-    var probing by remember(summary.id, epoch) { mutableStateOf(true) }
+    var probing by remember(address, epoch) { mutableStateOf(true) }
    // The oldest sequence number loaded, and whether there is more behind it. Paging backwards is
    // what keeps opening a long session cheap.
    var oldestSeq by remember { mutableLongStateOf(0L) }
-    // Where this session was last being read, from this device's own store. Read once, because the
+    // Where this transcript was last being read, from this device's own store, keyed by the address
-    // answer stops being interesting the moment the list is on screen.
+    // rather than the session id so a subagent's saved position cannot collide with its session's.
-    val savedAnchor = remember(summary.id, epoch) { loadScrollAnchor(context, summary.id) }
+    // Read once, because the answer stops being interesting the moment the list is on screen.
    val savedAnchor = remember(address, epoch) { loadScrollAnchor(context, address.cachePath) }
    // Whether the saved position is still being put back. Nothing is drawn while it is: opening at
    // the newest end and then travelling to the anchor is exactly the journey a reader must never
    // see.
-    var restoring by remember(summary.id, epoch) { mutableStateOf(savedAnchor != null) }
+    var restoring by remember(address, epoch) { mutableStateOf(savedAnchor != null) }
    // Messages the server has taken and the session has not read yet, by the id that will resolve
    // them. From the event stream rather than from what this screen sent, so they survive leaving
    // the session -- and a message sent from another device is drawn waiting on this one too.
@@ -327,11 +353,22 @@ fun SessionScreen(
    var loadingHistory by remember { mutableStateOf(false) }
    var ready by remember { mutableStateOf(false) }
    // Replies parsed ahead of the rows that draw them; see [ParsedReplies].
-    val replies = remember(summary.id) { ParsedReplies() }
+    val replies = remember(address) { ParsedReplies() }
-    // Keyed like everything else describing one session's transcript. `rememberLazyListState` saves
+    // Keyed like everything else describing one transcript. `rememberLazyListState` saves through
-    // through `rememberSaveable`, and this screen restores by its own anchor instead -- two
+    // `rememberSaveable`, and this screen restores by its own anchor instead -- two restores would
-    // restores would fight over the first frame.
+    // fight over the first frame.
-    val listState = remember(summary.id) { LazyListState() }
+    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.
@@ -637,7 +674,7 @@ fun SessionScreen(
    // ended and carries live events only. The window comes from this phone's own copy when there is
    // one, and then costs a single request to check that the server's transcript is still the one
    // it came from. See TRANSCRIPT_CACHE.md.
-    LaunchedEffect(summary.id, epoch) {
+    LaunchedEffect(address, epoch) {
        /**
         * One opening window onto the screen, whichever side it came from.
         *
@@ -667,11 +704,16 @@ fun SessionScreen(
                // A replay is as old as the last visit; the row this screen was opened from was
                // fetched moments ago. So the transcript comes from the cache and everything that
                // is not the transcript comes from the summary -- otherwise a session that finished
-                // an hour ago opens saying "working" until the stream connects.
+                // an hour ago opens saying "working" until the stream connects. A subagent's status
-                status = summary.status
+                // comes from its own summary, never the parent session's: they are two different
                // things running or not, and the parent's model and permission mode do not apply to
                // it at all.
                status = subagent?.status ?: summary.status
                if (!isSubagent) {
                    model = summary.model
                    permissionMode = summary.permissionMode ?: "auto"
-                if (summary.status != "compacting") compactingSince = null
+                }
                if (status != "compacting") compactingSince = null
                // Nothing to put back, so these rows are the screen and the probe can return under
                // them. A restore still has history to fetch and is gated below.
                if (savedAnchor == null) ready = true
@@ -798,7 +840,7 @@ fun SessionScreen(
    // at the top on their return. Switching apps is a choice somebody made, not a fault to report.
    // Stopping the stream deliberately makes the drop a close rather than an error, and resuming
    // reconnects from the same cursor.
-    LaunchedEffect(summary.id, ready, epoch, lifecycleOwner) {
+    LaunchedEffect(address, ready, epoch, lifecycleOwner) {
        if (!ready) return@LaunchedEffect
        // The opening effect draws cached rows and lifts `ready` *before* it has checked that the
        // cursor under them is still the server's, so `ready` is no longer the whole gate. Without
@@ -868,10 +910,14 @@ fun SessionScreen(
    // The screen going away entirely, which the lifecycle scope above does not cover: a composable
    // can leave the composition while the activity stays started. Keyed on the epoch as well, so
    // Reload's replacement source is the one a later disposal closes.
-    DisposableEffect(summary.id, epoch) { onDispose { source.close() } }
+    DisposableEffect(address, epoch) { onDispose { source.close() } }
    // Nothing gets announced about the session somebody is reading; see NotificationService.
    // RESUMED rather than STARTED because "looking at it" means the foreground.
    //
    // Not for a subagent: it has no notifications of its own, and it is not the session this would
    // otherwise mark as being read.
    if (!isSubagent) {
        LaunchedEffect(summary.id, lifecycleOwner) {
            lifecycleOwner.repeatOnLifecycle(Lifecycle.State.RESUMED) {
                NotificationService.showing(context, summary.id)
@@ -882,6 +928,7 @@ fun SessionScreen(
                }
            }
        }
    }
    // Back at the newest end, so the backlog [apply] held can land. Everything at once rather than
    // paced out: they are at the bottom, which is the one place the list is allowed to follow new
@@ -924,7 +971,7 @@ fun SessionScreen(
                val (index, offset, awayFromNewest) = settled
                saveScrollAnchor(
                    context,
-                    summary.id,
+                    address.cachePath,
                    // Nothing to restore at the newest end, which is where a session with no anchor
                    // opens anyway. One *before* the index, because item zero is the "below" slot.
                    if (!awayFromNewest) null
@@ -947,7 +994,7 @@ fun SessionScreen(
    //
    // There is no correction beside this one. Following the newest message is not an effect: the
    // list is reversed, so an arriving message extends the end the viewport is pinned to.
-    val unitSizes = remember(summary.id) { HashMap<Any, Int>() }
+    val unitSizes = remember(address) { HashMap<Any, Int>() }
    LaunchedEffect(listState, moreHistory) {
        snapshotFlow { listState.layoutInfo }
            .collect { info ->
@@ -983,6 +1030,8 @@ fun SessionScreen(
            }
    }
    // Only for the model picker, which a subagent does not have.
    if (!isSubagent) {
        LaunchedEffect(summary.setupName, summary.provider) {
            offeredModels =
                try {
@@ -995,10 +1044,12 @@ fun SessionScreen(
                            .orEmpty()
                    }
                } catch (_: Exception) {
-                // Not worth reporting: the picker simply has nothing to offer, which is visible.
+                    // Not worth reporting: the picker simply has nothing to offer, which is
                    // visible.
                    emptyList()
                }
        }
    }
    /**
     * Asks the server to take back a message the session has not read yet.
@@ -1148,8 +1199,9 @@ fun SessionScreen(
    }
    // One poll for the machines' limits, read by everything on this screen that reports them.
-    val usageFeed = rememberUsageFeed(settings)
+    // Nothing meters a subagent -- it has no account of its own -- so it never starts this poll.
-    val usage = usageFeed.forSetup(summary.setup)
+    val usageFeed = if (isSubagent) null else rememberUsageFeed(settings)
    val usage = usageFeed?.forSession(summary) ?: SessionUsage.NotMetered
    RecordFrames()
    var usageOpen by remember { mutableStateOf(false) }
    var settingsOpen by remember { mutableStateOf(false) }
@@ -1191,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 =
@@ -1213,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
@@ -1226,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(
@@ -1236,20 +1321,35 @@ fun SessionScreen(
                // A ring's worth, which is what the arrow already keeps on its other three sides.
                Spacer(Modifier.width(GLYPH_BUTTON_MARGIN))
                Column(Modifier.weight(1f)) {
                    // A subagent's own title, with the session's beneath it in a smaller style --
                    // the header says whose conversation this is as well as what it is. Otherwise
                    // just the session's title, as before.
                    if (subagent != null) {
                        Text(subagent.title, style = MaterialTheme.typography.titleMedium)
                        Text(
                            title,
                            style = MaterialTheme.typography.bodySmall,
                            color = MaterialTheme.colorScheme.onSurfaceVariant,
                        )
                    } else {
                        Text(title, style = MaterialTheme.typography.titleMedium)
-                    // Machine first, then what runs on it -- the same order and the same wording
+                        // Machine first, then what runs on it -- the same order and the same
-                    // everywhere this pair appears, so it reads as one fact rather than two
+                        // wording everywhere this pair appears, so it reads as one fact rather than
-                    // sentences with different grammar.
+                        // two sentences with different grammar.
                        //
-                    // No model. The picker in the footer already shows what this session is set to,
+                        // No model. The picker in the footer already shows what this session is set
-                    // and showing it twice means two things to keep in step -- they disagreed for a
+                        // to, and showing it twice means two things to keep in step -- they
-                    // moment on every model change.
+                        // disagreed for a moment on every model change.
                        Text(
                            "${summary.setupName} · ${summary.provider}",
                            style = MaterialTheme.typography.bodySmall,
                            color = MaterialTheme.colorScheme.onSurfaceVariant,
                        )
                    }
                }
                // None of this is a subagent's: it has no files of its own to browse, no settings,
                // and nothing meters it -- see SUBAGENTS.md's "Phone".
                //
                // Beside the provider it reports on, which is the line directly to its left. Its
                // real home is this provider's settings, which do not exist yet. A session on a
                // provider with no such service gets an honest "unavailable" rather than a hidden
@@ -1264,6 +1364,7 @@ fun SessionScreen(
                // Usage, files, settings -- widest scope first, narrowing to the right, so the cog
                // stays at the end where every other screen keeps it. Asked for in this order by
                // Iris on 2026-09-03.
                if (!isSubagent) {
                    Row {
                        GlyphButton(
                            USAGE_GLYPH,
@@ -1281,25 +1382,29 @@ fun SessionScreen(
                                    FilesTarget(
                                        setup = summary.setup,
                                        setupName = summary.setupName,
-                                    // Where this session works, and the machine's own home when it
+                                        // Where this session works, and the machine's own home when
-                                    // was never given a directory -- resolved there rather than
+                                        // it was never given a directory -- resolved there rather
-                                    // guessed at here, since this app does not know that home.
+                                        // than guessed at here, since this app does not know that
                                        // home.
                                        start = summary.cwd?.takeIf { it.isNotBlank() } ?: "~",
                                    )
                                )
                            },
                        )
-                    // What it opens is about this session, so it sits at the end of the session's
+                        // What it opens is about this session, so it sits at the end of the
-                    // own row. A cog and not a word because there will be more, and a bar of words
+                        // session's own row. A cog and not a word because there will be more, and a
-                    // has nowhere to put it.
+                        // bar of words has nowhere to put it.
                        GlyphButton(SETTINGS_GLYPH, "Session settings", { settingsOpen = true })
                    }
                }
            }
            // Under the header, above everything the session itself says: it is a fact about the
            // machine rather than a turn in the conversation, and it is the number that decides
-            // whether to keep going.
+            // whether to keep going. Nothing meters a subagent.
            if (!isSubagent) {
                SessionUsageBar(usage)
            }
            (streamError ?: actionError)?.let { message ->
                Text(
@@ -1545,6 +1650,7 @@ fun SessionScreen(
                                                is TranscriptItem.ClearedNote -> ClearedRow()
                                                is TranscriptItem.CompactedNote ->
                                                    CompactedRow(item)
                                                is TranscriptItem.LimitNote -> LimitRow(item)
                                                // Never reached: a peer message is flattened into
                                                // its own units. Here because a `when` over the
                                                // item kinds has to stay exhaustive.
@@ -1643,24 +1749,34 @@ fun SessionScreen(
                )
            }
            // Kept for a subagent -- see SUBAGENTS.md's "Phone" -- with the wording that turns
            // "exited" into "finished" for one, since it has no process to leave running or stop.
            SessionStatusRow(
                status = status,
                compactingFor = compactingFor,
                contextTokens = contextTokens,
                subagent = isSubagent,
            )
-            // Between the transcript and the box: above what is being typed, so the list does not
+            // Everything from here down is the composer: a subagent cannot be messaged, so none of
-            // cover the thing the command is about, and below everything that explains it.
+            // it applies -- see SUBAGENTS.md's "Phone".
            if (!isSubagent) {
                // Between the transcript and the box: above what is being typed, so the list does
                // not cover the thing the command is about, and below everything that explains it.
                CommandSuggestions(
-                // Nothing to suggest about a suggestion that was just taken. `/compact` is a whole
+                    // Nothing to suggest about a suggestion that was just taken. `/compact` is a
-                // command *and* a prefix of itself, so picking it left the list standing there with
+                    // whole command *and* a prefix of itself, so picking it left the list standing
-                // the one row already chosen. Held by what was picked rather than by a flag, so
+                    // there with the one row already chosen. Held by what was picked rather than by
-                // typing anything else brings the list back without a second thing to reset.
+                    // a flag, so typing anything else brings the list back without a second thing
-                commands = if (input.text == picked) emptyList() else suggestedCommands(input.text),
+                    // to
                    // reset.
                    commands =
                        if (input.text == picked) emptyList() else suggestedCommands(input.text),
                    onPick = { command ->
-                    // At the end of what was inserted, which is where the reader carries on typing:
+                        // At the end of what was inserted, which is where the reader carries on
-                    // a command with an argument is put in the box half-written, and a cursor left
+                        // typing: a command with an argument is put in the box half-written, and a
-                    // at the front makes the next keystroke the first character of "/rename".
+                        // cursor left at the front makes the next keystroke the first character of
                        // "/rename".
                        input = atEnd(command.typed())
                        picked = command.typed()
                    },
@@ -1669,11 +1785,14 @@ fun SessionScreen(
                // Always enabled -- a send while the session is running becomes a steering message
                // injected at the next tool boundary, which is the point of the whole app.
                //
-            // The field gets a row of its own, above the buttons: sharing one put the full width
+                // The field gets a row of its own, above the buttons: sharing one put the full
-            // behind three controls, so the thing being typed into was the narrowest on the row.
+                // width
                // behind three controls, so the thing being typed into was the narrowest on the
                // row.
                Column(Modifier.fillMaxWidth().padding(8.dp)) {
                    // Directly above the box they will be sent from, so what is attached is visible
-                // rather than counted: the "+2" on the button below said how many and never which.
+                    // rather than counted: the "+2" on the button below said how many and never
                    // which.
                    PendingAttachments(
                        settings = settings,
                        sessionId = summary.id,
@@ -1686,9 +1805,12 @@ fun SessionScreen(
                            input = it
                            saveDraft(context, summary.id, it.text)
                        },
-                    modifier = Modifier.fillMaxWidth(),
+                        // BenchRun's type phase requests focus on this exact field
-                    // No longer "(+image)": the images are on screen above this, and a placeholder
+                        // (`composerFocus`)
-                    // saying so said it in words beside the thing itself.
+                        // 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") },
                        maxLines = 4,
                    )
@@ -1696,17 +1818,19 @@ fun SessionScreen(
                        verticalAlignment = Alignment.CenterVertically,
                        modifier = Modifier.fillMaxWidth(),
                    ) {
-                    // Photo or file, asked here rather than by two buttons: the row is full, and
+                        // Photo or file, asked here rather than by two buttons: the row is full,
                        // and
                        // attaching is one action whichever picker answers it.
                        var attaching by remember { mutableStateOf(false) }
                        Box {
-                        // Just "+". The count it used to carry was standing in for showing them.
+                            // Just "+". The count it used to carry was standing in for showing
                            // them.
                            BubbleButton(onClick = { attaching = true }) { Text("+") }
                            DropdownMenu(
                                expanded = attaching,
                                onDismissRequest = { attaching = false },
-                            // See PickerButton: without this the menu opens a status bar's height
+                                // See PickerButton: without this the menu opens a status bar's
-                            // away from the button in an edge-to-edge activity.
+                                // height away from the button in an edge-to-edge activity.
                                properties = PopupProperties(clippingEnabled = false),
                                shape = BubbleMenuShape,
                            ) {
@@ -1730,11 +1854,11 @@ fun SessionScreen(
                                )
                            }
                        }
-                    // The settings share what is left after the actions have taken what they need.
+                        // The settings share what is left after the actions have taken what they
-                    // A Row hands out intrinsic widths in order and clips whatever runs past the
+                        // need. A Row hands out intrinsic widths in order and clips whatever runs
-                    // edge, so with these laid out first the arrival of Stop pushed Send off the
+                        // past the edge, so with these laid out first the arrival of Stop pushed
-                    // screen entirely -- the app's central control, gone at the moment it is most
+                        // Send off the screen entirely -- the app's central control, gone at the
-                    // in use.
+                        // moment it is most in use.
                        Row(
                            verticalAlignment = Alignment.CenterVertically,
                            modifier = Modifier.weight(1f),
@@ -1742,16 +1866,18 @@ fun SessionScreen(
                            if (offeredModels.isNotEmpty()) {
                                PickerButton(
                                    current = modelLabel(model),
-                                // What the machine offers, plus the state a session is in when it
+                                    // What the machine offers, plus the state a session is in when
-                                // has chosen none of them. The button has always been able to say
+                                    // it has chosen none of them. The button has always been able
-                                // "default"; until this the list could not, so leaving it was a
+                                    // to
-                                // one-way trip.
+                                    // say "default"; until this the list could not, so leaving it
                                    // was a one-way trip.
                                    options = listOf(DEFAULT_MODEL) + offeredModels,
-                                // Not set here. The button follows what the session reports it is
+                                    // Not set here. The button follows what the session reports it
-                                // set to, which arrives a moment later and is sometimes a different
+                                    // is set to, which arrives a moment later and is sometimes a
-                                // answer -- a name the CLI resolved, or no change at all on a
+                                    // different answer -- a name the CLI resolved, or no change at
-                                // provider whose model is fixed. Asked about first, unless there is
+                                    // all on a provider whose model is fixed. Asked about first,
-                                // nothing to lose by it -- see [ModelSwitchWarning].
+                                    // unless there is nothing to lose by it -- see
                                    // [ModelSwitchWarning].
                                    onPick = { chosen ->
                                        if (
                                            modelLabel(chosen) == modelLabel(model) ||
@@ -1772,14 +1898,16 @@ fun SessionScreen(
                                },
                            )
                        }
-                    // The same filled shape as the button beside it, not an outlined one: these are
+                        // The same filled shape as the button beside it, not an outlined one: these
-                    // two things you can do about the session, and weighting one as secondary said
+                        // are two things you can do about the session, and weighting one as
-                    // they were a primary action and its qualifier. What separates them is the
+                        // secondary said they were a primary action and its qualifier. What
-                    // colour and the mark, which is what they mean.
+                        // separates them is the colour and the mark, which is what they mean.
                        //
-                    // Always here, rather than arriving with the turn as it used to. A control that
+                        // Always here, rather than arriving with the turn as it used to. A control
-                    // comes and goes makes its own presence the signal, and a button always in the
+                        // that comes and goes makes its own presence the signal, and a button
-                    // same place also cannot push Send off the end of the row by turning up.
+                        // always
                        // in the same place also cannot push Send off the end of the row by turning
                        // up.
                        val process =
                            when {
                                running -> ProcessAction.Pause
@@ -1799,18 +1927,21 @@ fun SessionScreen(
                            Glyph(
                                process.glyph,
                                colour = LocalContentColor.current,
-                            modifier = Modifier.semantics { contentDescription = process.label },
+                                modifier =
                                    Modifier.semantics { contentDescription = process.label },
                            )
                        }
                        Spacer(Modifier.width(8.dp))
-                    // The paper plane, with a clock on it while a turn is in flight: sending then
+                        // The paper plane, with a clock on it while a turn is in flight: sending
-                    // queues the message for the next tool boundary rather than starting a turn of
+                        // then queues the message for the next tool boundary rather than starting a
-                    // its own, and the two have to be told apart at a glance. The label says the
+                        // turn of its own, and the two have to be told apart at a glance. The label
-                    // same thing to a screen reader.
+                        // says the same thing to a screen reader.
                        //
-                    // Disabled while there is nothing to send, rather than pressable and silent:
+                        // Disabled while there is nothing to send, rather than pressable and
-                    // `send` has always returned early on an empty composer, so the button promised
+                        // silent:
-                    // something it would not do. Disabled and not hidden, for the reason above.
+                        // `send` has always returned early on an empty composer, so the button
                        // promised something it would not do. Disabled and not hidden, for the
                        // reason above.
                        Button(
                            onClick = { send() },
                            enabled = input.text.isNotBlank() || pendingAttachments.isNotEmpty(),
@@ -1827,12 +1958,13 @@ fun SessionScreen(
                }
            }
        }
    }
    // Beside the other two dialogs, and outside the list for the same reason as them: what is open
    // is the screen's business rather than any row's. See [SessionImageViewer].
    fullImage?.let { ref -> SessionImageViewer(settings, summary.id, ref) { fullImage = null } }
    if (usageOpen) {
-        UsageDialog(feed = usageFeed, onDismiss = { usageOpen = false })
+        usageFeed?.let { UsageDialog(feed = it, onDismiss = { usageOpen = false }) }
    }
    if (settingsOpen) {
        // Measured when the dialog opens rather than kept up to date: what the reader is being told
@@ -1846,6 +1978,8 @@ fun SessionScreen(
            settings = settings,
            sessionId = summary.id,
            title = title,
            effort = summary.effort.takeIf { summary.takesEffort },
            takesEffort = summary.takesEffort,
            cachedBytes = cachedBytes,
            // The purge finishes before the epoch moves, because the relaunched opening effect
            // reads the same directory and would otherwise draw what is about to be deleted. The
@@ -1869,6 +2003,7 @@ fun SessionScreen(
            },
            onDismiss = { settingsOpen = false },
            onCopyRenderReport = copyRenderReport,
            onRunBenchmark = runBenchmark,
        )
    }
 }
@@ -2122,6 +2257,13 @@ private fun SessionStatusRow(
    /** Context the session is holding, or null where nothing has measured it. */
    contextTokens: Long?,
    modifier: Modifier = Modifier,
    /**
     * Whether this row is for a subagent rather than a session, which changes only one word:
     * "exited" reads as "finished" there too, the same as the subagent list's own card -- a
     * subagent's process was always its parent's, so "exited" would read as a fault rather than the
     * ordinary way one of these ends.
     */
    subagent: Boolean = false,
 ) {
    DebugStats.count("status row recomposed")
    Row(
@@ -2178,7 +2320,7 @@ private fun SessionStatusRow(
                Text(
                    when (status) {
                        "idle" -> "idle"
-                        "exited" -> "exited"
+                        "exited" -> if (subagent) "finished" else "exited"
                        "awaitingInput" -> "your turn"
                        "unknown" -> "can't tell"
                        else -> status
@@ -2249,7 +2391,7 @@ private const val ONE_TAP_MS = 250L
 * session is set to without spending a second line on saying it.
 */
@Composable
-private fun PickerButton(current: String, options: List<String>, onPick: (String) -> Unit) {
+fun PickerButton(current: String, options: List<String>, onPick: (String) -> Unit) {
    var open by remember { mutableStateOf(false) }
    // When an outside touch last closed the menu.
    //
@@ -6,8 +6,10 @@ import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.MaterialTheme
@@ -26,6 +28,10 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.text.input.ImeAction
 import androidx.compose.ui.unit.dp
 import java.time.Instant
 import java.time.ZoneId
 import java.time.format.DateTimeFormatter
 import java.time.format.FormatStyle
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
@@ -54,6 +60,16 @@ fun SessionSettingsDialog(
     */
    title: String,
    onRenamed: (String) -> Unit,
    /**
     * How hard the model thinks, as the session reports it, or null for the CLI's own default.
     *
     * Taken from the row this dialog was opened over rather than fetched, because unlike the
     * notification switch there is nothing else that changes it: the level is this app's to set and
     * the server does not resolve it into something else.
     */
    effort: String?,
    /** Whether a level does anything here; the row is left out entirely where it does not. */
    takesEffort: Boolean,
    /**
     * What this phone is holding of the conversation, or null while that is being measured -- see
     * the Reload row below, which is what would discard it.
@@ -66,9 +82,18 @@ 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) }
    var level by remember(sessionId) { mutableStateOf(effort) }
    var effortError by remember { mutableStateOf<String?>(null) }
    var saving by remember { mutableStateOf(false) }
    var error by remember { mutableStateOf<String?>(null) }
    // Null until the server has been asked. The row this dialog was opened over is a snapshot of
@@ -77,6 +102,16 @@ fun SessionSettingsDialog(
    // and a spinner sits beside it, which is what not knowing looks like.
    var notify by remember(sessionId) { mutableStateOf<Boolean?>(null) }
    var notifyError by remember { mutableStateOf<String?>(null) }
    // The same three-state shape the notification switch has, for the same reason: until the
    // server has answered, the switch is disabled rather than showing a position nothing confirmed.
    var autoResume by remember(sessionId) { mutableStateOf<Boolean?>(null) }
    var resumeMessage by remember(sessionId) { mutableStateOf(DEFAULT_RESUME_MESSAGE) }
    // When the server next intends to ask whether the limit has lifted, or null when nothing is
    // waiting. Read once with everything else: it moves on the server's schedule, not this
    // screen's, and a figure that redrew itself here would be this app re-measuring what it was
    // told.
    var resumeAt by remember(sessionId) { mutableStateOf<Double?>(null) }
    var resumeError by remember { mutableStateOf<String?>(null) }
    // Where the session works. Null until the server has been asked, for the same reason the switch
    // above is. An empty answer is a session that was never given a directory, which is not the
    // same as one whose directory is unknown -- the field is only enabled once one of those is
@@ -90,6 +125,9 @@ fun SessionSettingsDialog(
        try {
            val fresh = withContext(Dispatchers.IO) { fetchSession(settings, sessionId) }
            notify = fresh.notify
            autoResume = fresh.autoResume
            resumeMessage = fresh.autoResumeMessage
            resumeAt = fresh.resumeAt
            cwd = fresh.cwd.orEmpty()
            typedCwd = fresh.cwd.orEmpty()
        } catch (e: ApiException) {
@@ -97,6 +135,8 @@ fun SessionSettingsDialog(
            // instead of offering a position nothing confirmed.
            notifyError = e.message
            notify = null
            resumeError = e.message
            autoResume = null
        }
    }
@@ -125,6 +165,26 @@ fun SessionSettingsDialog(
        }
    }
    /**
     * Chooses a thinking level, which ends the process the old level was launched with.
     *
     * Put back if the request is refused, for the reason the notification switch below gives: a
     * control that stays where it was put after a refusal is stating something untrue.
     */
    fun setEffort(chosen: String?) {
        val was = level
        level = chosen
        effortError = null
        scope.launch {
            try {
                withContext(Dispatchers.IO) { setSessionEffort(settings, sessionId, chosen) }
            } catch (e: ApiException) {
                level = was
                effortError = e.message
            }
        }
    }
    // Moved optimistically so the switch answers the finger that moved it, and put back if the
    // request is refused -- a switch that waits for a round trip reads as broken on a slow tunnel,
    // and one that stays moved after a refusal lies.
@@ -142,6 +202,39 @@ fun SessionSettingsDialog(
        }
    }
    /**
     * Turns auto-resume on or off, or changes what it would say.
     *
     * One request for both, because the server takes one: switching it on and typing the message
     * are two halves of the same decision, and sending them separately would leave a moment where
     * the session is armed with the old words.
     *
     * Put back if refused, like the notification switch. Turning it off also clears what was
     * scheduled -- said here rather than only on the server, or the row would go on naming a time
     * that no longer exists.
     */
    fun setAutoResume(on: Boolean, message: String) {
        val wasOn = autoResume
        val wasMessage = resumeMessage
        val wasAt = resumeAt
        autoResume = on
        resumeMessage = message
        if (!on) resumeAt = null
        resumeError = null
        scope.launch {
            try {
                withContext(Dispatchers.IO) {
                    setSessionAutoResume(settings, sessionId, on, message)
                }
            } catch (e: ApiException) {
                autoResume = wasOn
                resumeMessage = wasMessage
                resumeAt = wasAt
                resumeError = e.message
            }
        }
    }
    // Nothing to do when the name has not changed, so the button says so rather than sending a
    // request whose success would look exactly like the failure of having typed nothing.
    val changed = name.trim().isNotEmpty() && name.trim() != title
@@ -168,7 +261,10 @@ fun SessionSettingsDialog(
        onDismissRequest = onDismiss,
        title = { Text("Session settings") },
        text = {
-            Column {
+            // Scrollable, because this dialog grew past a screenful: a Material dialog constrains
            // its own height and clips what does not fit, so the last control on the list is one
            // large system font away from being unreachable with nothing on screen to say so.
            Column(Modifier.verticalScroll(rememberScrollState())) {
                OutlinedTextField(
                    value = name,
                    onValueChange = { name = it },
@@ -212,6 +308,70 @@ fun SessionSettingsDialog(
                    )
                }
                Spacer(Modifier.height(8.dp))
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.fillMaxWidth(),
                ) {
                    Text("Resume after a usage limit", modifier = Modifier.weight(1f))
                    if (autoResume == null && resumeError == null) {
                        CircularProgressIndicator(
                            modifier = Modifier.width(16.dp).height(16.dp),
                            strokeWidth = 2.dp,
                        )
                        Spacer(Modifier.width(8.dp))
                    }
                    Switch(
                        checked = autoResume == true,
                        onCheckedChange = { setAutoResume(it, resumeMessage) },
                        enabled = autoResume != null,
                    )
                }
                // Disabled rather than hidden while the switch is off: a field that comes and goes
                // makes its own presence the signal, and a visible one teaches what the switch will
                // do. Committed on the keyboard's Done rather than on every keystroke, so typing a
                // sentence is one request instead of one per letter.
                OutlinedTextField(
                    value = resumeMessage,
                    onValueChange = { resumeMessage = it },
                    label = { Text("Message to send") },
                    // What an empty field means, in the field: the server's own word rather than a
                    // session poked with nothing to read.
                    placeholder = { Text(DEFAULT_RESUME_MESSAGE) },
                    singleLine = true,
                    enabled = autoResume == true,
                    modifier = Modifier.fillMaxWidth(),
                    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
                    keyboardActions =
                        KeyboardActions(onDone = { setAutoResume(true, resumeMessage) }),
                )
                // What it does and what it costs, in the order it happens. The last sentence is the
                // one that matters: the time below is when the server will *ask*, not a promise
                // about when the session speaks.
                Text(
                    "When this session stops because the account is out of quota, the server " +
                        "checks the limit and sends this message once it has lifted. It checks " +
                        "again if the limit is still on.",
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
                // Only where something is actually waiting. Absent is not a state worth a row: a
                // session that has not hit a limit has nothing scheduled, which the reader can see
                // from the switch.
                resumeAt?.let { at ->
                    Text(
                        "Waiting now -- next check ${formatCheckTime(at)}.",
                        style = MaterialTheme.typography.bodySmall,
                        color = MaterialTheme.colorScheme.onSurfaceVariant,
                    )
                }
                resumeError?.let {
                    Text(
                        it,
                        color = MaterialTheme.colorScheme.error,
                        style = MaterialTheme.typography.bodySmall,
                    )
                }
                Spacer(Modifier.height(8.dp))
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.fillMaxWidth(),
@@ -257,6 +417,44 @@ fun SessionSettingsDialog(
                        style = MaterialTheme.typography.bodySmall,
                    )
                }
                // Left out rather than disabled, the one place this dialog does that: a disabled
                // control teaches what the thing can do, and a llama session cannot do this at all
                // -- the row would be teaching something false about it.
                if (takesEffort) {
                    Spacer(Modifier.height(8.dp))
                    Row(
                        verticalAlignment = Alignment.CenterVertically,
                        modifier = Modifier.fillMaxWidth(),
                    ) {
                        Text("Thinking", modifier = Modifier.weight(1f))
                        PickerButton(
                            current = level ?: DEFAULT_EFFORT,
                            // The level the CLI picks for itself is in the list as well as in the
                            // button, so leaving a level is not a one-way trip -- the same
                            // correction the model picker carries.
                            options = listOf(DEFAULT_EFFORT) + EFFORT_LEVELS,
                            onPick = { chosen ->
                                setEffort(chosen.takeIf { it != DEFAULT_EFFORT })
                            },
                        )
                    }
                    // What it costs, said where it is about to be pressed, like Move above: the
                    // CLI reads the level when it launches and has no control request for
                    // changing one.
                    Text(
                        "Changing this stops the session's process. It starts again with the " +
                            "next message, or with Start.",
                        style = MaterialTheme.typography.bodySmall,
                        color = MaterialTheme.colorScheme.onSurfaceVariant,
                    )
                    effortError?.let {
                        Text(
                            it,
                            color = MaterialTheme.colorScheme.error,
                            style = MaterialTheme.typography.bodySmall,
                        )
                    }
                }
                Spacer(Modifier.height(8.dp))
                Row(
                    verticalAlignment = Alignment.CenterVertically,
@@ -317,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
@@ -329,3 +542,21 @@ fun SessionSettingsDialog(
        dismissButton = { TextButton(onClick = onDismiss) { Text("Close") } },
    )
 }
 /**
 * When the server will next look, as a local time.
 *
 * A time rather than a countdown, for the reason the transcript's own limit row gives: this screen
 * reads the figure once, and a span drawn from a value nothing refreshes goes stale while somebody
 * is looking at it.
 */
 private fun formatCheckTime(epochSeconds: Double): String =
    try {
        DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT)
            .withZone(ZoneId.systemDefault())
            .format(Instant.ofEpochSecond(epochSeconds.toLong()))
    } catch (_: Exception) {
        // A time that cannot be read is not a time to show: the sentence above still says a check
        // is coming, which is the part the reader can act on.
        "soon"
    }
@@ -70,12 +70,21 @@ class UsageFeed(
    /** Ask the backend again now. The dialog's refresh button; the poll does it on its own. */
    val refresh: () -> Unit,
 ) {
-    /** What [setup]'s own limits came back as. See [usageFor] for why the states are these. */
+    /**
-    fun forSetup(setup: String): SessionUsage =
+     * What meters [session], and what that meter came back as. See [usageFor] for the states.
-        when (val state = snapshots) {
+     *
     * A session rather than a machine, because a machine is not what is metered: one machine runs
     * the Claude CLI and an echo session side by side, and only the first of them spends anything.
     */
    fun forSession(session: SessionSummary): SessionUsage {
        // Settled without asking anybody: a session nothing meters has nothing to check, and
        // "checking" is what the fetch's own states would say about it for as long as one is out.
        val provider = session.usageProvider ?: return SessionUsage.NotMetered
        return when (val state = snapshots) {
            is LoadState.Loading -> SessionUsage.Waiting
            is LoadState.Error -> SessionUsage.Unavailable(state.message)
-            is LoadState.Loaded -> usageFor(state.value, setup)
+            is LoadState.Loaded -> usageFor(state.value, session.setup, provider)
        }
    }
 }
@@ -158,9 +167,15 @@ fun SessionUsageBar(usage: SessionUsage, modifier: Modifier = Modifier) {
        }
    }
-    // Nothing at all for a machine that meters nothing: a row saying "unknown" there would report a
+    // Nothing at all for a session that meters nothing: a row saying "unknown" there would report
-    // problem about a setup somebody chose, on every screen, forever.
+    // a problem about a setup somebody chose, on every screen, forever.
-    if (usage is SessionUsage.NotMetered) {
+    //
    // And nothing while the first fetch is out, which is a different silence. A request in flight
    // is not a state to report -- and the session that meters nothing is exactly the one this
    // cannot yet tell apart, so "5-hour usage: checking" appeared under an echo session for half a
    // second and was then taken away. A row that has to be withdrawn is worse than one that
    // arrives late.
    if (usage is SessionUsage.NotMetered || usage is SessionUsage.Waiting) {
        return
    }
@@ -171,9 +186,10 @@ fun SessionUsageBar(usage: SessionUsage, modifier: Modifier = Modifier) {
        // Words, not a colour and not an empty bar: every one of these is a different kind of
        // answer from "this much is used", and only words carry a difference in kind.
        when (val state = usage) {
-            SessionUsage.NotMetered -> Unit
+            // Both handled above, before the row exists at all.
            SessionUsage.NotMetered,
            SessionUsage.Waiting -> Unit
            is SessionUsage.Unavailable -> UsageNote("5-hour usage unknown -- ${state.why}")
            SessionUsage.Waiting -> UsageNote("5-hour usage: checking")
            is SessionUsage.Known -> {
                val window = state.windows.firstOrNull { it.kind == "session" }
                if (window == null) {
@@ -234,16 +250,22 @@ private fun fiveHourLabel(window: UsageWindow, now: OffsetDateTime): String {
 }
 /**
- * One machine's snapshot, out of every machine's.
+ * One meter's snapshot, out of every machine's: [setup]'s row for [provider].
 *
 * Both halves are needed to pick it. A machine can hold more than one meter -- the Claude CLI's
 * account and, while a test has one set, an echo session's invented one -- and a snapshot is one
 * service on one machine.
 *
 * Every way of having *failed* to get numbers is [SessionUsage.Unavailable] with the reason in it.
 * None of them may look like zero, and none may look like [SessionUsage.NotMetered], which is the
 * machine having no quota rather than the question going unanswered.
 */
-fun usageFor(snapshots: List<UsageSnapshot>, setup: String): SessionUsage {
+fun usageFor(snapshots: List<UsageSnapshot>, setup: String, provider: String): SessionUsage {
-    // No snapshot at all means the backend never asked, which it only does for a machine with
+    // No snapshot at all means the backend never asked, which it only does where there is nothing
-    // nothing metered on it. That is a different answer from having asked and failed.
+    // to ask about. That is a different answer from having asked and failed.
-    val mine = snapshots.firstOrNull { it.setup == setup } ?: return SessionUsage.NotMetered
+    val mine =
        snapshots.firstOrNull { it.setup == setup && it.provider == provider }
            ?: return SessionUsage.NotMetered
    if (mine.state != "ok") {
        return SessionUsage.Unavailable(mine.detail ?: mine.state)
    }
@@ -236,6 +236,7 @@ private fun AddSetupDialog(
    var address by remember { mutableStateOf("") }
    var identity by remember { mutableStateOf("") }
    var attachmentsDir by remember { mutableStateOf("") }
    var modelsDir by remember { mutableStateOf("") }
    var tested by remember { mutableStateOf<String?>(null) }
    var testing by remember { mutableStateOf(false) }
@@ -250,6 +251,7 @@ private fun AddSetupDialog(
                    port = typedPort,
                    identityFile = identity.trim().ifEmpty { null },
                    attachmentsDir = attachmentsDir.trim().ifEmpty { null },
                    modelsDir = modelsDir.trim().ifEmpty { null },
                )
            }
@@ -293,6 +295,14 @@ private fun AddSetupDialog(
                    label = { Text("Folder for attached files (optional)") },
                    singleLine = true,
                )
                // Where that machine's GGUFs are, for a llama.cpp session on it. Blank means
                // the same place this backend keeps its own downloads, read on that machine.
                OutlinedTextField(
                    value = modelsDir,
                    onValueChange = { modelsDir = it },
                    label = { Text("Folder for models (optional)") },
                    singleLine = true,
                )
                tested?.let {
                    Spacer(Modifier.height(8.dp))
                    Text(it, style = MaterialTheme.typography.bodySmall)
@@ -61,18 +61,31 @@ fun SpawnScreen(
    // "auto" rather than "manual": on a phone every ask is a round trip to a question card, and
    // answering "allow Bash?" dozens of times per task is what this app exists to avoid.
    var permissionMode by remember { mutableStateOf("auto") }
    // Null until the server has been asked, and null again if it answers "no level chosen" -- the
    // two are told apart by [defaultsAsked], because a picker that shows a level before the answer
    // arrives is one you can spawn at without having chosen it.
    var effort by remember { mutableStateOf<String?>(null) }
    var defaultsAsked by remember { mutableStateOf(false) }
    var busy by remember { mutableStateOf(false) }
    // Only the spawn's own failure. The fetch's lives in `options`: this one leaves a filled-in
    // form worth keeping, and that one leaves nothing to fill in.
    var spawnError by remember { mutableStateOf<String?>(null) }
-    // Downloaded models, for a llama provider to choose between. Kept separate from the setups: a
+    // The models on the *chosen machine*, for a llama provider to choose between. Kept separate
-    // Claude session needs none, so failing to list them must not stop the screen rendering.
+    // from the setups: a Claude session needs none, so failing to list them must not stop the
    // screen rendering. Refetched when the machine changes, because a model is a file on one
    // machine -- see [fetchSetupModels].
    var models by remember { mutableStateOf<List<LocalModel>>(emptyList()) }
    var modelKey by remember { mutableStateOf<String?>(null) }
    var contextSize by remember { mutableStateOf("") }
    var temperature by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        // Separate from the setups fetch below and deliberately not fatal: failing to learn the
        // default must leave a screen you can still spawn from, so the picker stays on "default"
        // and says so rather than the whole form refusing to draw.
        runCatching { withContext(Dispatchers.IO) { fetchDefaultEffort(settings) } }
            .onSuccess { effort = it }
        defaultsAsked = true
        options =
            try {
                val fetched = withContext(Dispatchers.IO) { fetchSetups(settings) }
@@ -83,9 +96,6 @@ fun SpawnScreen(
            } catch (e: ApiException) {
                LoadState.failed(e)
            }
        models =
            runCatching { withContext(Dispatchers.IO) { fetchModels(settings).local } }
                .getOrDefault(emptyList())
    }
    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(16.dp)) {
@@ -115,6 +125,17 @@ fun SpawnScreen(
                is LoadState.Loaded -> state.value
            }
        val setup = setups.firstOrNull { it.name == setupName }
        // Whichever machine is chosen now, asked again when that changes. The old machine's list
        // is dropped first rather than left on screen: a file name from another machine looks
        // exactly like one from this one.
        LaunchedEffect(setup?.id) {
            models = emptyList()
            modelKey = null
            val id = setup?.id ?: return@LaunchedEffect
            models =
                runCatching { withContext(Dispatchers.IO) { fetchSetupModels(settings, id) } }
                    .getOrDefault(emptyList())
        }
        val current = setup?.providers?.firstOrNull { it.name == providerName }
        // Only the Claude CLI has models, a working directory and permission modes; keying the
        // extra fields on the kind rather than the provider name keeps a second Claude provider
@@ -175,12 +196,13 @@ fun SpawnScreen(
        )
        if (isLlama) {
-            // A llama session names one of the models this backend has downloaded, so the choice is
+            // A llama session names one of the models on the machine it will run on, so the
-            // that list rather than free text -- a name that is not on disk is a session that
+            // choice is that list rather than free text -- a name that is not on that machine's
-            // cannot start.
+            // disk is a session that cannot start.
            if (models.isEmpty()) {
                Text(
-                    "No models downloaded yet. Get one from the Models screen first.",
+                    "No models on ${setup?.name ?: "this machine"}. The Models screen downloads " +
                        "to the backend; another machine needs the file put there itself.",
                    style = MaterialTheme.typography.bodyMedium,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
@@ -251,6 +273,19 @@ fun SpawnScreen(
                selected = permissionMode,
                onSelect = { permissionMode = it },
            )
            Spacer(Modifier.height(16.dp))
            // Says what it does to *later* spawns as well, because it does: the level chosen here
            // is stored as the default, which is the whole way that default is set. A picker that
            // quietly changed a global would be the same control with the fact left out.
            ChipGroup(
                label = "Thinking (kept as the default for new sessions)",
                options = listOf(DEFAULT_EFFORT) + EFFORT_LEVELS,
                // The CLI's own default is a level in the list, so this cannot be a one-way trip.
                // Disabled-looking until the server has answered, for the reason above.
                selected = if (defaultsAsked) effort ?: DEFAULT_EFFORT else null,
                onSelect = { chosen -> effort = chosen.takeIf { it != DEFAULT_EFFORT } },
            )
        }
        Spacer(Modifier.height(24.dp))
@@ -268,6 +303,13 @@ fun SpawnScreen(
                    try {
                        val spawned =
                            withContext(Dispatchers.IO) {
                                // Stored before the spawn and not after it: choosing a level is
                                // an intent about new sessions in general, so a spawn that then
                                // fails must not also lose the choice. Non-fatal for the same
                                // reason the fetch above is -- the session is what was asked for.
                                if (isClaude) {
                                    runCatching { setDefaultEffort(settings, effort) }
                                }
                                spawnSession(
                                    settings,
                                    // The id, not the label: labels are editable and the server
@@ -280,6 +322,7 @@ fun SpawnScreen(
                                        if (isLlama) modelKey else model.trim().takeIf { isClaude },
                                    cwd = cwd.trim().takeIf { isClaude },
                                    permissionMode = permissionMode.takeIf { isClaude },
                                    effort = effort.takeIf { isClaude },
                                    // Sent only when set, so blank means "whatever llama.cpp does
                                    // by default" rather than a zero.
                                    params =
@@ -0,0 +1,27 @@
 package com.example.aiapp
 /**
 * Where one transcript lives: a session's own, or one of its subagents'.
 *
 * The single mechanism [fetchTranscript], [EventStream], [TranscriptSource] and
 * [TranscriptCache.session] all take, rather than each growing its own branch between a session and
 * a subagent -- see SUBAGENTS.md's "Phone" and "Wire shape". A caller that has only a session id
 * builds one with the one-argument constructor; a subagent's screen supplies both ids.
 */
 data class TranscriptAddress(val sessionId: String, val subagentId: String? = null) {
    /** The URL segment naming this transcript, before `/transcript` or `/events`. */
    val urlPath: String
        get() =
            if (subagentId == null) "sessions/$sessionId"
            else "sessions/$sessionId/subagents/$subagentId"
    /**
     * Where this transcript's cache lives on the phone, relative to the cache root.
     *
     * A subagent's nests under its session's directory rather than sitting beside it, so deleting a
     * session's cache directory takes its subagents' with it -- the same one-way door the server's
     * own storage describes.
     */
    val cachePath: String
        get() = if (subagentId == null) sessionId else "$sessionId/subagents/$subagentId"
 }
@@ -35,8 +35,15 @@ class TranscriptCache(
    private val root: File,
    private val warn: (String) -> Unit = { Log.w("ai-app", it) },
 ) {
-    /** The cache for one session, whether or not anything has been stored for it yet. */
+    /**
-    fun session(id: String): SessionCache = SessionCache(File(root, id), warn)
+     * The cache for one transcript, whether or not anything has been stored for it yet.
     *
     * A subagent's [TranscriptAddress.cachePath] nests it under its session's directory, so
     * deleting the session (below) takes its subagents' caches with it -- there is no separate
     * purge for one.
     */
    fun session(address: TranscriptAddress): SessionCache =
        SessionCache(File(root, address.cachePath), warn)
    /**
     * Deletes every session directory not in [ids], called after a successful list fetch. The path
@@ -175,6 +175,18 @@ sealed class TranscriptItem {
        val preTokens: Long?,
        val postTokens: Long?,
    ) : TranscriptItem()
    /**
     * The account ran out of quota, so the turn stopped here.
     *
     * A divider rather than an error: nothing failed, and what a reader scrolling back needs from
     * it is the same thing a clear or a compaction gives them -- why the conversation stops at this
     * line.
     *
     * [resetsAt] is epoch seconds and null where the session was told nothing, which is a state the
     * row has words for rather than a time it invents.
     */
    data class LimitNote(override val seq: Long, val resetsAt: Double?) : TranscriptItem()
 }
 /**
@@ -458,6 +470,7 @@ fun foldEvent(items: List<TranscriptItem>, entry: SeqEvent): List<TranscriptItem
            } else {
                items + TranscriptItem.ImageItem(entry.seq, event.ref)
            }
        is SessionEvent.LimitReached -> items + TranscriptItem.LimitNote(entry.seq, event.resetsAt)
        is SessionEvent.Cleared -> items + TranscriptItem.ClearedNote(entry.seq)
        is SessionEvent.Compacted ->
            items + TranscriptItem.CompactedNote(entry.seq, event.preTokens, event.postTokens)
@@ -18,7 +18,7 @@ import java.util.concurrent.atomic.AtomicReference
 */
 class TranscriptSource(
    private val settings: ServerSettings,
-    private val sessionId: String,
+    private val address: TranscriptAddress,
    val cache: SessionCache,
 ) {
    private val stream = AtomicReference<EventStream?>(null)
@@ -65,7 +65,7 @@ class TranscriptSource(
        val tail = cache.tail() ?: return 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.
-        val answer = fetchTranscript(settings, sessionId, before = tail.seq + 1, limit = 1)
+        val answer = fetchTranscript(settings, address, before = tail.seq + 1, limit = 1)
        val matches =
            answer.size == 1 &&
                try {
@@ -83,7 +83,7 @@ class TranscriptSource(
     */
    suspend fun fetchOpening(): List<SeqEvent> {
        DebugStats.count("transcript page from server")
-        val page = fetchTranscript(settings, sessionId, limit = OPENING_WINDOW)
+        val page = fetchTranscript(settings, address, limit = OPENING_WINDOW)
        page.forEach { (line, entry) -> cache.append(line, entry.seq) }
        cache.flush()
        return page.map { it.second }
@@ -108,7 +108,7 @@ class TranscriptSource(
        val page =
            fetchTranscript(
                settings,
-                sessionId,
+                address,
                before = before,
                limit = limit,
                coalesce = coalesce,
@@ -131,7 +131,7 @@ class TranscriptSource(
     * well lose.
     */
    fun follow(after: Long, onOpen: () -> Unit, onReset: () -> Unit, onEvent: (SeqEvent) -> Unit) {
-        val opened = EventStream(settings, sessionId)
+        val opened = EventStream(settings, address)
        stream.getAndSet(opened)?.close()
        try {
            opened.run(after, onOpen, onReset) { raw, entry ->
@@ -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>
@@ -0,0 +1,32 @@
 package com.example.aiapp
 import java.time.ZoneId
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertTrue
 /**
 * What the transcript says where a session ran out of quota.
 *
 * The pair worth a test is the one that reads the same when it goes wrong: a reset time that
 * arrived and one that never did. The second must not turn into a plausible-looking time, because a
 * reader has no way of telling an invented one from a reported one.
 */
 class LimitRowTest {
    private val utc = ZoneId.of("UTC")
    @Test
    fun `a reported reset time is shown as a time`() {
        // 2026-09-05T12:00:00Z. Asserted as a prefix and the clock reading rather than as the
        // whole string: the platform's own short-time format is what this asks for, and it
        // differs by JDK and locale down to which space character separates the meridiem.
        val summary = limitSummary(1_788_609_600.0, utc)
        assertTrue(summary.startsWith("Usage limit reached • resets "), summary)
        assertTrue(summary.contains("12:00"), summary)
    }
    @Test
    fun `a limit with no reset time says only what is known`() {
        assertEquals("Usage limit reached", limitSummary(null, utc))
    }
 }
@@ -23,7 +23,7 @@ class TranscriptCacheTest {
    private fun cache() = TranscriptCache(File(temp, "v1/host_8443")) { said += it }
-    private fun session(id: String = "s") = cache().session(id)
+    private fun session(id: String = "s") = cache().session(TranscriptAddress(id))
    private fun line(seq: Long, type: String = "toolStart") =
        """{"seq":$seq,"ts":1.5,"type":"$type","id":"x"}"""
@@ -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.
@@ -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()
@@ -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
@@ -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:"
@@ -47,6 +47,7 @@ name = "client-core"
 version = "0.1.0"
 dependencies = [
 "event-model",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "tempfile",
@@ -173,6 +174,15 @@ dependencies = [
 "percent-encoding",
 ]
 [[package]]
 name = "getopts"
 version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
 dependencies = [
 "unicode-width",
 ]
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -425,6 +435,25 @@ dependencies = [
 "unicode-ident",
 ]
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9f068eba8e7071c5f9511831b44f32c740d5adf574e990f946ddb53db2f314e"
 dependencies = [
 "bitflags",
 "getopts",
 "memchr",
 "pulldown-cmark-escape",
 "unicase",
 ]
 [[package]]
 name = "pulldown-cmark-escape"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -661,12 +690,24 @@ dependencies = [
 "zerovec",
 ]
 [[package]]
 name = "unicase"
 version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -7,7 +7,7 @@ edition = "2024"
 # with `server/` via `event-model`), the REST + SSE clients for its HTTP
 # surface (see `server/src/routes.rs`'s module doc for the table), the
 # transcript fold and cache, the markdown block model, the syntax
-# highlighter and the ANSI parser. See CLIENT_CORE.md at the repo root for
+# 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.
 #
@@ -17,7 +17,12 @@ edition = "2024"
 [dependencies]
 event-model = { path = "../event-model" }
 serde = { version = "1", features = ["derive"] }
-serde_json = { version = "1", features = ["float_roundtrip"] }
+# "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
@@ -27,6 +32,12 @@ serde_json = { version = "1", features = ["float_roundtrip"] }
 # no need of an async runtime, and RUST.md's brief for this port is
 # "lightweight" throughout.
 ureq = { version = "3", features = ["json"] }
 # The markdown block split (`markdown_blocks`), which has to agree with the
 # renderer in `iris/transcript-ui` about where a block begins -- so it is
 # the same parser at the same version, rather than a hand-written splitter
 # that would drift from it.
 pulldown-cmark = "0.13.4"
 [dev-dependencies]
 tempfile = "3"
@@ -10,6 +10,7 @@
 use std::io::Read;
 use event_model::SeqEvent;
 use serde::Deserialize;
 use serde_json::Value;
@@ -116,6 +117,14 @@ impl<T: Transport> ApiClient<T> {
        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,
@@ -266,6 +275,61 @@ impl<T: Transport> ApiClient<T> {
        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}"));
@@ -273,8 +337,10 @@ impl<T: Transport> ApiClient<T> {
    if coalesce {
        path.push_str("&coalesce=true");
    }
-        self.json_request("GET", &path, None)
+    if let Some(after) = after {
        path.push_str(&format!("&after={after}"));
    }
    path
 }
 /// The blocking [`Transport`] backed by `ureq`, the same crate `server/`
@@ -78,15 +78,15 @@ fn percent_decode(s: &str) -> String {
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
-        if bytes[i] == b'%' && i + 2 < bytes.len() {
+        if bytes[i] == b'%'
-            if let Ok(byte) =
+            && 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;
    }
@@ -0,0 +1,100 @@
 //! A span of milliseconds, written the way somebody reads it -- the port
 //! of `Durations.kt`'s `formatMillis`/`formatMillisText`, with its tests.
 //!
 //! Only the tool-timeout half is here. `formatSpan` (the usage
 //! countdown's rounding-up rule) belongs with whatever draws the usage
 //! bar, and nothing in this crate needs it yet.
 /// A span of milliseconds, written the way somebody reads it.
 ///
 /// A tool's timeout arrives as `480000`, which nobody reads as eight
 /// minutes. The rule has two halves, because a short span and a long one
 /// are read for different things. Under a minute the question is "roughly
 /// how long", so only the largest unit is shown and a fraction carries the
 /// rest -- `2.5s`. At a minute or more the question is "how long exactly",
 /// so every unit with something in it is written out -- `5d 12h 4m`. Empty
 /// units are left out rather than written as zero.
 ///
 /// Sub-second precision is dropped past a minute: nothing that takes days
 /// is measured in milliseconds.
 pub fn format_millis(ms: i64) -> String {
    if ms < 0 {
        return format!("-{}", format_millis(-ms));
    }
    if ms < 1000 {
        return format!("{ms}ms");
    }
    if ms < 60_000 {
        let tenths = (ms + 50) / 100;
        let (whole, rest) = (tenths / 10, tenths % 10);
        return if rest == 0 {
            format!("{whole}s")
        } else {
            format!("{whole}.{rest}s")
        };
    }
    let seconds = ms / 1000;
    [
        ("d", seconds / 86_400),
        ("h", seconds / 3600 % 24),
        ("m", seconds / 60 % 60),
        ("s", seconds % 60),
    ]
    .iter()
    .filter(|(_, n)| *n > 0)
    .map(|(unit, n)| format!("{n}{unit}"))
    .collect::<Vec<_>>()
    .join(" ")
 }
 /// `text` as a span when it is a whole number of milliseconds, and
 /// unchanged when it is not.
 pub fn format_millis_text(text: &str) -> String {
    match text.trim().parse::<i64>() {
        Ok(ms) => format_millis(ms),
        Err(_) => text.to_string(),
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    /// The two ways a span of time is written here, and the rule each of
    /// them follows -- ported from `DurationsTest.kt`, whose doc says why:
    /// both are read off a screen to make a decision, so what matters is
    /// that the shortest form that answers the question is what appears.
    #[test]
    fn under_a_minute_is_the_largest_unit_alone() {
        assert_eq!(format_millis(30), "30ms");
        assert_eq!(format_millis(999), "999ms");
        assert_eq!(format_millis(1000), "1s");
        assert_eq!(format_millis(2500), "2.5s");
        // One decimal, rounded rather than cut: 2.46s is nearer two and a
        // half than two and four.
        assert_eq!(format_millis(2460), "2.5s");
        assert_eq!(format_millis(59_900), "59.9s");
    }
    #[test]
    fn a_minute_or_more_is_every_unit_that_has_something_in_it() {
        // The figure this rule was written for: a tool timeout, which
        // arrives as milliseconds and is unreadable as 480000.
        assert_eq!(format_millis(480_000), "8m");
        assert_eq!(format_millis(60_000), "1m");
        assert_eq!(format_millis(90_000), "1m 30s");
        assert_eq!(format_millis(475_440_000), "5d 12h 4m");
        // Empty units are left out rather than written as zero: the labels
        // say which is which, and "5d 0h 4m" is only longer.
        assert_eq!(format_millis(432_240_000), "5d 4m");
    }
    #[test]
    fn only_a_whole_number_of_milliseconds_is_rewritten() {
        assert_eq!(format_millis_text(" 480000 "), "8m");
        // A timeout a tool expressed some other way is its own words,
        // passed through rather than guessed at.
        assert_eq!(format_millis_text("2 minutes"), "2 minutes");
        assert_eq!(format_millis_text(""), "");
    }
 }
@@ -1,15 +1,19 @@
 //! The app's pure logic, shared between the server and any Rust client --
-//! see `CLIENT_CORE.md` at the repo root for what lives here and what does
+//! 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 durations;
 pub mod event_stream;
 pub mod highlight;
 pub mod markdown_blocks;
 pub mod notifications;
 pub mod sse;
 pub mod tool_summary;
 pub mod transcript_cache;
 pub mod transcript_fold;
 pub mod transcript_source;
 pub use event_model::*;
@@ -0,0 +1,325 @@
 //! Split a markdown message into its top-level **blocks** -- one
 //! paragraph, heading, fenced code block, list, table or quote each, as a
 //! byte slice of the original source.
 //!
 //! This exists for streaming. A transcript row used to be one text widget
 //! holding the whole message, so a single streamed delta re-shaped every
 //! paragraph of it through the text engine again; the phone's bench v2 put
 //! the stream phase at p50 18.2ms against Compose's 13.4ms for exactly
 //! that reason (docs/IRIS_TODO.md). A row is a column of one widget per
 //! block now, and a delta that lands in the last block leaves every
 //! earlier block's layout alone. `docs/DECISIONS.md`'s 2026-09-06 entry has
 //! what that rejected and why the split lives here rather than in the UI
 //! crate: `docs/CLIENT_CORE.md` already wanted a block model for P1, and
 //! keeping it here means iris stays a text renderer that knows nothing
 //! about markdown.
 //!
 //! **Blocks only.** Inline styling (bold, links, inline code) is still the
 //! renderer's own job, per block -- this deliberately does not build a
 //! full AST, because nothing needs one yet.
 //!
 //! ## Appending is not guaranteed to leave earlier blocks alone
 //!
 //! It nearly always does, which is what makes the fast path worth having,
 //! but markdown has no such rule: appending a "```" line can turn text
 //! that was three paragraphs into one fenced block, and appending "---"
 //! under a paragraph turns that paragraph into a heading. So a caller
 //! taking the O(last block) path **must compare the prefix it is about to
 //! keep** rather than assume it. [`common_prefix`] is that comparison, and
 //! it is cheap next to laying the text out again.
 use pulldown_cmark::{Event, Options, Parser, Tag};
 /// What a block is, for a renderer that wants to style or space blocks
 /// differently. `Other` is deliberately present rather than a panic or a
 /// silent fallback to `Paragraph`: markdown has more block kinds than this
 /// list and more get added, and a renderer treating an unknown one as
 /// prose is right, but it should be able to *tell* that is what it is
 /// doing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BlockKind {
    Paragraph,
    Heading,
    /// A fenced or indented code block.
    Code,
    List,
    Table,
    Quote,
    /// A thematic break, raw HTML, a footnote -- anything with no
    /// distinguished treatment here.
    Other,
 }
 /// One top-level block: its kind and the exact source that produced it.
 /// `source` is a slice of the input with trailing whitespace removed, so
 /// two splits of the same prefix compare equal even when one of them had a
 /// delta arriving after it.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Block {
    pub kind: BlockKind,
    pub source: String,
 }
 fn kind_of(tag: &Tag) -> BlockKind {
    match tag {
        Tag::Paragraph => BlockKind::Paragraph,
        Tag::Heading { .. } => BlockKind::Heading,
        Tag::CodeBlock(_) => BlockKind::Code,
        Tag::List(_) => BlockKind::List,
        Tag::Table(_) => BlockKind::Table,
        Tag::BlockQuote(_) => BlockKind::Quote,
        _ => BlockKind::Other,
    }
 }
 fn options() -> Options {
    // The same set `transcript-ui`'s renderer parses with, so a block
    // boundary here and the styling there cannot disagree about what the
    // source means.
    Options::ENABLE_STRIKETHROUGH | Options::ENABLE_TABLES | Options::ENABLE_TASKLISTS
 }
 /// Split `src` into its top-level blocks, in source order. An empty or
 /// whitespace-only input gives no blocks; text the parser does not put
 /// inside any block (a stray fence marker mid-stream) still comes back,
 /// as `Other`, rather than being dropped.
 pub fn split_blocks(src: &str) -> Vec<Block> {
    let mut out: Vec<Block> = Vec::new();
    let mut depth = 0usize;
    let mut kind = BlockKind::Other;
    for (event, range) in Parser::new_ext(src, options()).into_offset_iter() {
        match event {
            Event::Start(tag) => {
                if depth == 0 {
                    kind = kind_of(&tag);
                }
                depth += 1;
            }
            Event::End(_) => {
                depth -= 1;
                if depth == 0 {
                    push(&mut out, kind, &src[range]);
                }
            }
            // A top-level event that is not part of any block -- a
            // thematic break, a block of raw HTML. Inside one, it is the
            // enclosing block's business and this does nothing.
            _ => {
                if depth == 0 {
                    push(&mut out, BlockKind::Other, &src[range]);
                }
            }
        }
    }
    out
 }
 fn push(out: &mut Vec<Block>, kind: BlockKind, source: &str) {
    let source = source.trim_end();
    if source.is_empty() {
        return;
    }
    out.push(Block {
        kind,
        source: source.to_string(),
    });
 }
 /// How many leading blocks of `old` and `new` are identical -- what a
 /// caller may keep the laid-out widgets for. See the module doc for why
 /// this is a comparison rather than an assumption.
 pub fn common_prefix(old: &[Block], new: &[Block]) -> usize {
    old.iter().zip(new).take_while(|(a, b)| a == b).count()
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    fn kinds(src: &str) -> Vec<BlockKind> {
        split_blocks(src).into_iter().map(|b| b.kind).collect()
    }
    #[test]
    fn a_message_splits_into_its_top_level_blocks() {
        let src = "# Title\n\nFirst para.\n\n```rust\nfn main() {}\n```\n\n- a\n- b\n";
        assert_eq!(
            kinds(src),
            vec![
                BlockKind::Heading,
                BlockKind::Paragraph,
                BlockKind::Code,
                BlockKind::List
            ]
        );
        let blocks = split_blocks(src);
        assert_eq!(blocks[1].source, "First para.");
        assert_eq!(blocks[2].source, "```rust\nfn main() {}\n```");
    }
    #[test]
    fn blank_input_has_no_blocks() {
        assert!(split_blocks("").is_empty());
        assert!(split_blocks("   \n\n  ").is_empty());
    }
    /// The property the streaming fast path rests on, in its ordinary
    /// shape: a delta landing in the last paragraph must leave every
    /// earlier block byte-identical.
    #[test]
    fn a_delta_into_the_last_paragraph_leaves_earlier_blocks_untouched() {
        let before = split_blocks("# Title\n\nFirst para.\n\nSecond par");
        let after = split_blocks("# Title\n\nFirst para.\n\nSecond paragraph now.");
        assert_eq!(common_prefix(&before, &after), 2);
        assert_eq!(before.len(), 3);
        assert_eq!(after.len(), 3);
        assert_ne!(before[2], after[2]);
    }
    /// A delta that starts a *new* block keeps every old block, including
    /// the one that was last -- so the fast path appends rather than
    /// replacing.
    #[test]
    fn a_delta_that_starts_a_new_block_keeps_every_old_one() {
        let before = split_blocks("First para.\n\nSecond para.");
        let after = split_blocks("First para.\n\nSecond para.\n\nThird");
        assert_eq!(common_prefix(&before, &after), 2);
        assert_eq!(after.len(), 3);
    }
    /// A code fence arrives one delta at a time and is unterminated for
    /// most of its life. It must still be *one* block the whole way, or
    /// every delta would re-split the message into a different number of
    /// pieces.
    #[test]
    fn an_unterminated_fence_is_one_block_while_it_streams() {
        for src in [
            "Here:\n\n```rust\n",
            "Here:\n\n```rust\nfn main() {\n",
            "Here:\n\n```rust\nfn main() {\n    println!(\"hi\");\n",
        ] {
            assert_eq!(
                kinds(src),
                vec![BlockKind::Paragraph, BlockKind::Code],
                "{src:?}"
            );
        }
    }
    /// The half the fast path had no reason to touch, and the reason
    /// `common_prefix` is a comparison rather than an assumption:
    /// appending can rewrite what came before. `---` under a paragraph
    /// turns that paragraph into a setext heading, so the block that was
    /// already laid out is not the block it is now.
    #[test]
    fn appending_can_rewrite_an_earlier_block_and_the_prefix_says_so() {
        let before = split_blocks("Not a heading\n\nsecond");
        let after = split_blocks("Not a heading\n\nsecond\n---");
        assert_eq!(before[1].kind, BlockKind::Paragraph);
        assert_eq!(after[1].kind, BlockKind::Heading);
        assert_eq!(
            common_prefix(&before, &after),
            1,
            "the rewritten block must not be reported as keepable"
        );
    }
    #[test]
    fn a_thematic_break_is_its_own_block() {
        assert_eq!(
            kinds("one\n\n---\n\ntwo"),
            vec![BlockKind::Paragraph, BlockKind::Other, BlockKind::Paragraph]
        );
    }
    /// The shapes a real transcript actually contains, each checked for
    /// the one property the streaming fast path needs: the *number* of
    /// blocks and every earlier block's source stay put while the message
    /// grows. A fence's own blank lines, a `---` inside one, a nested
    /// list and a table are all places where a naive line-based split
    /// would break the message into more pieces than there are blocks.
    #[test]
    fn the_transcripts_own_block_shapes_survive_a_split() {
        let fence_with_blanks = "Intro.\n\n```rust\nfn a() {}\n\nfn b() {}\n```\n\nAfter.";
        assert_eq!(
            kinds(fence_with_blanks),
            vec![BlockKind::Paragraph, BlockKind::Code, BlockKind::Paragraph],
            "a blank line inside a fence is not a block boundary"
        );
        assert_eq!(
            kinds("```\n---\n```"),
            vec![BlockKind::Code],
            "a thematic break inside a fence is code, not a break"
        );
        assert_eq!(
            kinds("- a\n  - a1\n  - a2\n- b"),
            vec![BlockKind::List],
            "a nested list is one top-level block"
        );
        assert_eq!(
            kinds("## Heading\n```sh\nls\n```"),
            vec![BlockKind::Heading, BlockKind::Code],
            "a fence directly under a heading, with no blank line"
        );
        assert_eq!(
            kinds("| a | b |\n|---|---|\n| 1 | 2 |"),
            vec![BlockKind::Table]
        );
        assert_eq!(
            kinds("> quoted\n> more\n\nplain"),
            vec![BlockKind::Quote, BlockKind::Paragraph]
        );
    }
    /// `apply_delta`'s precondition, stated as the property rather than
    /// the arithmetic: for every prefix of a realistic streamed message,
    /// the blocks before the last one must be exactly the blocks the
    /// previous prefix had. Where markdown breaks that (the `---` case
    /// above), `common_prefix` has to *say* so -- which is what the
    /// `>= len - 1` assertion below checks: the split may rewrite the
    /// last block, never an earlier one, or `RowBlocks::apply_delta`
    /// would keep a widget whose text is no longer what it holds.
    #[test]
    fn every_prefix_of_a_streamed_message_keeps_all_but_its_last_block() {
        let full = "# Report\n\nFirst finding, at some length.\n\n```rust\nfn main() {\n\n                        println!(\"hi\");\n}\n```\n\n- one\n  - nested\n- two\n\n| a | b |\n                    |---|---|\n| 1 | 2 |\n\n> and a closing quote.";
        // Every character boundary, so a delta landing mid-word and one
        // landing exactly on a fence's closing backtick are both covered.
        let mut prev = Vec::new();
        for end in full.char_indices().map(|(i, _)| i).chain([full.len()]) {
            let now = split_blocks(&full[..end]);
            let common = common_prefix(&prev, &now);
            assert!(
                prev.is_empty() || common + 1 >= prev.len(),
                "at {end} bytes the split rewrote block {common} of {}, not just the last one:\n                 before={prev:#?}\nafter={now:#?}",
                prev.len()
            );
            prev = now;
        }
    }
    /// The half a growing message cannot show: a fence that never closes.
    /// The stream ends there and the block must still be the code block
    /// it has been all along, not re-split into paragraphs.
    #[test]
    fn a_stream_that_ends_inside_a_fence_still_ends_with_one_code_block() {
        let src = "Here is the patch:\n\n```diff\n- old line\n+ new line";
        let blocks = split_blocks(src);
        assert_eq!(
            blocks.iter().map(|b| b.kind).collect::<Vec<_>>(),
            vec![BlockKind::Paragraph, BlockKind::Code]
        );
        assert_eq!(blocks[1].source, "```diff\n- old line\n+ new line");
    }
    /// A delta that closes a fence changes the *last* block only, so the
    /// fast path takes it -- the case the module doc says is the reason
    /// `common_prefix` is a comparison.
    #[test]
    fn the_delta_that_closes_a_fence_changes_only_the_last_block() {
        let before = split_blocks("Text.\n\n```\ncode\n");
        let after = split_blocks("Text.\n\n```\ncode\n```");
        assert_eq!(before.len(), after.len());
        assert_eq!(common_prefix(&before, &after), 1);
        assert_ne!(before[1], after[1]);
    }
 }
@@ -0,0 +1,244 @@
 //! A tool call's input, read rather than dumped -- the port of
 //! `ToolInput.kt`'s `parseToolInput`, which is what both the collapsed
 //! card's one-line summary and the expanded card's key/value list are
 //! derived from.
 //!
 //! Every tool's input arrives as JSON, and showing it raw makes the reader
 //! parse `{"command":"…","timeout":120000}` themselves to find the one
 //! line they care about. So the fields that carry the meaning are pulled
 //! out, and anything left over is still shown, because dropping a field
 //! would be claiming the tool has no other input when it might.
 //!
 //! Pure, and here rather than in the widget crate, for the reason the rest
 //! of this crate exists: the derivation is the same on a phone and on a
 //! desktop, and it is testable without a renderer.
 use crate::durations::format_millis_text;
 use crate::highlight::Language;
 use serde_json::{Map, Value};
 /// A tool call's input, split into the parts a card draws separately.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct ToolInput {
    /// The thing that will actually be run or read, if this tool has one.
    pub subject: Option<String>,
    /// The language [`ToolInput::subject`] is written in, for
    /// highlighting.
    pub language: Option<Language>,
    /// The tool's own one-line summary, when it wrote one.
    pub description: Option<String>,
    /// How long the call may take, in the largest units it fits. Shown
    /// apart because it is a limit on the call rather than part of what
    /// the call does.
    pub timeout: Option<String>,
    /// Everything else, as `name: value` lines. Never dropped.
    pub rest: Vec<String>,
 }
 impl ToolInput {
    /// The one line to show when there is only room for one: what this
    /// call is for.
    pub fn title(&self) -> Option<&str> {
        self.description
            .as_deref()
            .or(self.subject.as_deref())
            // A subject that is only whitespace would draw as an empty
            // summary line, which reads as a tool with nothing to say
            // rather than as one whose subject was blank.
            .filter(|t| !t.trim().is_empty())
    }
 }
 /// Which field of which tool is the subject.
 ///
 /// A table rather than a chain of `if`s: adding a tool is a row, and the
 /// shape stops any of them from being the special case that gets its own
 /// code path. Unknown tools fall through to "no subject, everything is
 /// rest".
 const SUBJECTS: &[(&str, &str, Option<Language>)] = &[
    ("Bash", "command", Some(Language::Shell)),
    ("Read", "file_path", None),
    ("Write", "file_path", None),
    ("Edit", "file_path", None),
    ("Glob", "pattern", None),
    ("Grep", "pattern", None),
    ("WebFetch", "url", None),
 ];
 /// Fields that are the tool's own prose about itself rather than input to
 /// it.
 const DESCRIPTIONS: &[&str] = &["description", "prompt"];
 /// One JSON value as the Kotlin's `JSONObject.optString`/`get` wrote it: a
 /// string is its own characters, anything else is its JSON form.
 ///
 /// One function rather than two, because the same coercion decides both
 /// what a subject reads as and what a leftover field's value reads as, and
 /// two copies would eventually disagree about a number.
 fn as_text(value: &Value) -> String {
    match value {
        Value::String(s) => s.clone(),
        other => other.to_string(),
    }
 }
 fn non_blank(value: Option<&Value>) -> Option<String> {
    let text = as_text(value?);
    (!text.trim().is_empty()).then_some(text)
 }
 /// Split `input` (a tool call's JSON) into the parts a card draws.
 ///
 /// Input that is not a JSON object -- older transcripts and some tools
 /// send a bare string -- is still the input, so it is still shown, as the
 /// whole of `rest`.
 pub fn parse_tool_input(tool: &str, input: &str) -> ToolInput {
    let Ok(Value::Object(json)) = serde_json::from_str::<Value>(input) else {
        return ToolInput {
            rest: match input.trim().is_empty() {
                true => Vec::new(),
                false => vec![input.to_string()],
            },
            ..ToolInput::default()
        };
    };
    parse_object(tool, &json)
 }
 fn parse_object(tool: &str, json: &Map<String, Value>) -> ToolInput {
    let (subject_key, language) = SUBJECTS
        .iter()
        .find(|(name, ..)| *name == tool)
        .map(|(_, key, language)| (Some(*key), *language))
        .unwrap_or((None, None));
    let subject = subject_key.and_then(|key| non_blank(json.get(key)));
    let description = DESCRIPTIONS
        .iter()
        .find_map(|key| non_blank(json.get(*key)));
    let timeout = non_blank(json.get("timeout")).map(|t| format_millis_text(&t));
    // Sorted, so the leftovers are in the same order every time this call
    // is drawn rather than in whatever order the JSON happened to arrive
    // in. A field is left out only when it is already drawn somewhere
    // else on the card.
    let mut keys: Vec<&String> = json
        .keys()
        .filter(|k| Some(k.as_str()) != subject_key || subject.is_none())
        .filter(|k| !DESCRIPTIONS.contains(&k.as_str()) || description.is_none())
        .filter(|k| k.as_str() != "timeout" || timeout.is_none())
        .collect();
    keys.sort();
    let rest = keys
        .into_iter()
        .map(|key| format!("{key}: {}", as_text(&json[key])))
        .collect();
    ToolInput {
        subject,
        language,
        description,
        timeout,
        rest,
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn each_tool_in_the_table_has_its_own_subject() {
        // One assertion per row of `SUBJECTS`, because the table is the
        // whole of the rule and a row lost in an edit would otherwise
        // only show up as a card with no summary line.
        let cases = [
            ("Bash", r#"{"command":"ls -la"}"#, "ls -la"),
            ("Read", r#"{"file_path":"/tmp/x.rs"}"#, "/tmp/x.rs"),
            ("Write", r#"{"file_path":"/tmp/y.rs"}"#, "/tmp/y.rs"),
            ("Edit", r#"{"file_path":"/tmp/z.rs"}"#, "/tmp/z.rs"),
            ("Glob", r#"{"pattern":"**/*.rs"}"#, "**/*.rs"),
            ("Grep", r#"{"pattern":"fn main"}"#, "fn main"),
            ("WebFetch", r#"{"url":"https://x/y"}"#, "https://x/y"),
        ];
        for (tool, input, expected) in cases {
            let parsed = parse_tool_input(tool, input);
            assert_eq!(parsed.subject.as_deref(), Some(expected), "{tool}");
            assert_eq!(parsed.title(), Some(expected), "{tool}");
            assert!(parsed.rest.is_empty(), "{tool}: {:?}", parsed.rest);
        }
        assert_eq!(
            parse_tool_input("Bash", r#"{"command":"ls"}"#).language,
            Some(Language::Shell),
            "a Bash command is shell, and is the one row that names a language"
        );
    }
    #[test]
    fn a_tools_own_description_is_what_the_one_line_says() {
        // The description wins over the subject: it is the tool's own
        // prose about what this call is for, which is what a reader
        // scanning a collapsed run is looking for.
        let parsed = parse_tool_input(
            "Bash",
            r#"{"command":"cargo test -p iris","description":"Run the iris tests"}"#,
        );
        assert_eq!(parsed.title(), Some("Run the iris tests"));
        assert_eq!(parsed.subject.as_deref(), Some("cargo test -p iris"));
        assert!(parsed.rest.is_empty(), "{:?}", parsed.rest);
    }
    #[test]
    fn a_timeout_is_read_as_a_span_and_kept_apart_from_the_rest() {
        let parsed = parse_tool_input("Bash", r#"{"command":"sleep 500","timeout":480000}"#);
        assert_eq!(parsed.timeout.as_deref(), Some("8m"));
        assert!(parsed.rest.is_empty(), "{:?}", parsed.rest);
    }
    #[test]
    fn every_field_not_drawn_elsewhere_is_still_shown() {
        // The half the "never dropped" promise is about: a tool this
        // build has never heard of has no subject, so *everything* is
        // rest -- and a known tool's extra fields are too.
        let parsed = parse_tool_input(
            "Edit",
            r#"{"file_path":"/a.rs","old_string":"x","new_string":"y","replace_all":true}"#,
        );
        assert_eq!(
            parsed.rest,
            vec![
                "new_string: y".to_string(),
                "old_string: x".to_string(),
                "replace_all: true".to_string(),
            ],
            "sorted, and a non-string value written as JSON"
        );
        let unknown = parse_tool_input("SomeNewTool", r#"{"b":2,"a":"one"}"#);
        assert_eq!(unknown.subject, None);
        assert_eq!(unknown.rest, vec!["a: one".to_string(), "b: 2".to_string()]);
    }
    #[test]
    fn input_that_is_not_an_object_is_still_the_input() {
        // Older transcripts and some tools send a bare string; a card
        // that dropped it would claim the call had no input at all.
        assert_eq!(
            parse_tool_input("Bash", "just a string").rest,
            vec!["just a string".to_string()]
        );
        assert_eq!(parse_tool_input("Bash", "   ").rest, Vec::<String>::new());
        assert_eq!(parse_tool_input("Bash", "").title(), None);
    }
    #[test]
    fn a_blank_subject_is_no_subject_rather_than_an_empty_summary_line() {
        let parsed = parse_tool_input("Bash", r#"{"command":"   ","other":1}"#);
        assert_eq!(parsed.subject, None);
        assert_eq!(parsed.title(), None);
        // Not dropped just because it was blank -- it is still a field
        // the call carried.
        assert_eq!(
            parsed.rest,
            vec!["command:    ".to_string(), "other: 1".to_string()]
        );
    }
 }
@@ -1,7 +1,7 @@
 //! This phone's copy of the transcripts it has already been sent, so
 //! reopening a session does not download it again. Ported from
-//! `app/.../TranscriptCache.kt`; see `TRANSCRIPT_CACHE.md` at the repo root
+//! `app/.../TranscriptCache.kt`; see `docs/TRANSCRIPT_CACHE.md`
-//! for the design and `CLIENT_CORE.md` for how this file corresponds to it.
+//! for the design and `docs/CLIENT_CORE.md` for how this file corresponds to it.
 //!
 //! What is stored is the server's own JSON for one event per line, in
 //! transcript order. Reading the cache means running the same [`seq_of`]
@@ -361,6 +361,10 @@ impl SessionCache {
            {
                return Ok(false);
            }
            debug_assert!(
                lines.iter().all(|l| !l.contains('\n')),
                "a stored page's lines must each be one line"
            );
            fs::create_dir_all(&this.dir)?;
            let kind = if rows { "rows" } else { "raw" };
            let mut content = lines.join("\n");
@@ -389,8 +393,16 @@ impl SessionCache {
                return Ok(());
            };
            // Written as it arrived. A newline inside it would split one
-            // event into two unreadable halves, but neither source can
+            // event into two unreadable halves. No source here can produce
-            // produce one.
+            // one -- an SSE `data:` field cannot hold a raw newline, and a
            // fetched line is one element of a compact JSON array -- but
            // that is a fact about the *server's* serializer rather than
            // anything this file controls, so it is checked rather than
            // trusted.
            debug_assert!(
                !line.contains('\n'),
                "a cached transcript line must be one line: {line}"
            );
            use std::io::Write;
            writer.write_all(line.as_bytes())?;
            writer.write_all(b"\n")?;
@@ -78,6 +78,11 @@ pub enum TranscriptItem {
        input: String,
        output: String,
        done: bool,
        /// Whether the result that arrived said the call failed
        /// ([`Event::ToolEnd`]'s `is_error`). Meaningless while `done` is
        /// false, and [`ToolState::of`] is the only thing that reads the
        /// pair, so the two cannot be combined wrongly at a call site.
        failed: bool,
        asks: Vec<QuestionCard>,
        images: Vec<String>,
    },
@@ -112,6 +117,13 @@ pub enum TranscriptItem {
    ClearedNote {
        seq: u64,
    },
    /// The account's usage limit stopped the turn; `resets_at` is epoch
    /// seconds when the dialect said when it lifts (`LimitNote` in
    /// `TranscriptItems.kt`).
    LimitNote {
        seq: u64,
        resets_at: Option<f64>,
    },
    CompactedNote {
        seq: u64,
        pre_tokens: Option<u64>,
@@ -131,6 +143,7 @@ impl TranscriptItem {
            | Self::CommandRow { seq, .. }
            | Self::Note { seq, .. }
            | Self::ClearedNote { seq }
            | Self::LimitNote { seq, .. }
            | Self::CompactedNote { seq, .. } => *seq,
            Self::QuestionCard(card) => card.seq,
        }
@@ -286,6 +299,201 @@ fn split_run(tail: &[TranscriptItem], behind: Option<&str>) -> Vec<TranscriptIte
    out
 }
 /// Puts a page of older items in front of the ones already loaded, healing
 /// whatever the page boundary cut in two. Ported from `TranscriptItems.kt`'s
 /// `joinPages`.
 ///
 /// Two things straddle a boundary: a tool call separated from its result,
 /// and a message separated from the rest of itself. Both were one thing
 /// before the transcript was cut into pages.
 ///
 /// A boundary lands wherever it lands, and roughly half the time that is
 /// between a call and its result. The newer page then holds a `ToolEnd`
 /// whose start it never saw, which `fold_event` draws as a row of its own
 /// -- correctly, because a call that renders as nothing is indistinguishable
 /// from one that never happened. When the older page arrives it brings the
 /// real `ToolStart`, and concatenating the two lists left *both*: the same
 /// call twice.
 ///
 /// Merged by the call's own id rather than by position, because position is
 /// exactly what a page boundary destroys. The older row wins on what a
 /// start knows and the newer on what an end knows, which is the only way
 /// round that loses nothing.
 ///
 /// The third thing is the *run*, and it is the one the Kotlin original used
 /// to miss (AGENTS.md's "things that have bitten"): every page ends up
 /// here, but `adopt_run` must run on *every* join, not only the one where a
 /// split call was found -- a boundary landing cleanly between two finished
 /// calls, which is most of them, would otherwise leave the older page's
 /// calls under the run name they were folded with. On screen: one run of
 /// tool calls drawn as two groups, with the seam wherever the reader
 /// happened to have paged.
 pub fn join_pages(earlier: &[TranscriptItem], later: &[TranscriptItem]) -> Vec<TranscriptItem> {
    let (older, newer) = heal_split_message(earlier, later);
    let started_earlier: std::collections::HashSet<&str> = older
        .iter()
        .filter_map(TranscriptItem::as_tool_run)
        .collect();
    // Owned rather than borrowed from `newer`: `kept` below needs to consume `newer` by
    // value, and a map borrowing it would keep that alive.
    let ended_later: std::collections::HashMap<String, TranscriptItem> = newer
        .iter()
        .filter_map(|item| item.as_tool_run().map(|id| (id.to_string(), item.clone())))
        .filter(|(id, _)| started_earlier.contains(id.as_str()))
        .collect();
    let healed: Vec<TranscriptItem> = older
        .into_iter()
        .map(|row| match row {
            TranscriptItem::ToolRun {
                seq,
                id,
                run_id,
                tool,
                input,
                asks: row_asks,
                images: row_images,
                ..
            } if ended_later.contains_key(id.as_str()) => {
                let &TranscriptItem::ToolRun {
                    ref output,
                    done,
                    failed,
                    asks: ref half_asks,
                    images: ref half_images,
                    ..
                } = &ended_later[id.as_str()]
                else {
                    unreachable!("filtered to ToolRun above");
                };
                TranscriptItem::ToolRun {
                    seq,
                    id,
                    run_id,
                    tool,
                    input,
                    output: output.clone(),
                    done,
                    failed,
                    // Kept from both halves: a question or an image can be
                    // attached to either, depending on which side of the
                    // boundary its event fell.
                    asks: row_asks.into_iter().chain(half_asks.clone()).collect(),
                    images: row_images.into_iter().chain(half_images.clone()).collect(),
                }
            }
            other => other,
        })
        .collect();
    let kept: Vec<TranscriptItem> = newer
        .into_iter()
        .filter(|item| match item.as_tool_run() {
            Some(id) => !ended_later.contains_key(id),
            None => true,
        })
        .collect();
    let mut out = adopt_run(&healed, &kept);
    out.extend(kept);
    // What this function exists to prevent, checked rather than assumed: the same
    // call drawn twice, once from the page that saw its start and once from the page
    // that saw its end. Not a seq-ordering check -- a peer note is stamped with the
    // seq its turn began at, which can be older than the page it arrived in, so the
    // two pages' seqs legitimately interleave at the boundary.
    debug_assert!(
        {
            let mut ids: Vec<&str> = out.iter().filter_map(TranscriptItem::as_tool_run).collect();
            let before = ids.len();
            ids.sort_unstable();
            ids.dedup();
            ids.len() == before
        },
        "join_pages left the same tool call in both halves"
    );
    out
 }
 /// Rejoins a message the page boundary cut, and hands back the two pages to
 /// concatenate. Ported from `TranscriptItems.kt`'s `healSplitMessage`.
 ///
 /// `fold_event` never leaves two assistant messages next to each other
 /// inside one page, so two meeting at a join are always the two halves of
 /// one reply, and leaving them apart drew a single answer as two with a
 /// paragraph break through the middle of a sentence.
 ///
 /// The newer half keeps its identity, for the reason `adopt_run`'s doc
 /// gives. It grows by what the older half brings, which is safe here and
 /// nowhere else -- the join is at the oldest end of what is loaded, so the
 /// growth extends off the top of the screen.
 fn heal_split_message(
    earlier: &[TranscriptItem],
    later: &[TranscriptItem],
 ) -> (Vec<TranscriptItem>, Vec<TranscriptItem>) {
    let (
        Some(TranscriptItem::AssistantMsg {
            text: head_text, ..
        }),
        Some(TranscriptItem::AssistantMsg {
            seq: tail_seq,
            text: tail_text,
            settled: tail_settled,
        }),
    ) = (earlier.last(), later.first())
    else {
        return (earlier.to_vec(), later.to_vec());
    };
    let merged = TranscriptItem::AssistantMsg {
        seq: *tail_seq,
        text: format!("{head_text}{tail_text}"),
        settled: *tail_settled,
    };
    let mut newer = vec![merged];
    newer.extend(later[1..].iter().cloned());
    (earlier[..earlier.len() - 1].to_vec(), newer)
 }
 /// Hands the older calls at the join the name of the run they are joining.
 /// Ported from `TranscriptItems.kt`'s `adoptRun`.
 ///
 /// The two pages were folded separately, so a run split by the boundary
 /// came back as two runs with two names. Naming the joined run after the
 /// *older* half would be the obvious way round and is wrong: the newer half
 /// is the part already on screen, and renaming it is renaming the row the
 /// reader is looking at, which is how a list loses its anchor.
 fn adopt_run(earlier: &[TranscriptItem], later: &[TranscriptItem]) -> Vec<TranscriptItem> {
    let Some(TranscriptItem::ToolRun { run_id, tool, .. }) = later.first() else {
        return earlier.to_vec();
    };
    // A question is in a run of its own on both sides of the join, the same as it would be
    // had the two pages been folded as one. Without this the heal would merge a group
    // straight through the row the reader was asked something on.
    if tool == ASK_USER_QUESTION {
        return earlier.to_vec();
    }
    let joining = run_id.clone();
    let tail_len = earlier
        .iter()
        .rev()
        .take_while(|item| matches!(item, TranscriptItem::ToolRun { tool, .. } if tool != ASK_USER_QUESTION))
        .count();
    if tail_len == 0 {
        return earlier.to_vec();
    }
    let split = earlier.len() - tail_len;
    let mut out = earlier[..split].to_vec();
    out.extend(earlier[split..].iter().cloned().map(|mut item| {
        // `take_while` above already restricted this slice to non-question tool calls;
        // this just guards the invariant rather than trusting it silently.
        debug_assert!(
            matches!(&item, TranscriptItem::ToolRun { tool, .. } if tool != ASK_USER_QUESTION),
            "adopt_run must never rename a question's own run"
        );
        if let TranscriptItem::ToolRun { run_id, .. } = &mut item {
            *run_id = joining.clone();
        }
        item
    }));
    out
 }
 /// Folds one transcript event onto `items`, the way `foldEvent` does in
 /// `TranscriptItems.kt`. Every wire event has a case; see the module doc
 /// for the one difference from the Kotlin original (no `Unknown` fallback
@@ -361,6 +569,7 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
                input: input.to_string(),
                output: String::new(),
                done: false,
                failed: false,
                asks: Vec::new(),
                images: Vec::new(),
            });
@@ -371,15 +580,23 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
                *out = output.clone();
            }
        }),
-        Event::ToolEnd { id, output } => {
+        Event::ToolEnd {
            id,
            output,
            is_error,
        } => {
            if items.iter().any(|i| i.as_tool_run() == Some(id.as_str())) {
                update_tool(items, id, |item| {
                    if let TranscriptItem::ToolRun {
-                        output: out, done, ..
+                        output: out,
                        done,
                        failed,
                        ..
                    } = item
                    {
                        *out = output.clone();
                        *done = true;
                        *failed = *is_error;
                    }
                })
            } else {
@@ -393,6 +610,7 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
                    input: String::new(),
                    output: output.clone(),
                    done: true,
                    failed: *is_error,
                    asks: Vec::new(),
                    images: Vec::new(),
                });
@@ -449,6 +667,7 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
                    input,
                    output,
                    done,
                    failed,
                    images,
                } if asks.iter().any(|a| &a.id == id) => {
                    for ask in asks.iter_mut() {
@@ -464,6 +683,7 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
                        input,
                        output,
                        done,
                        failed,
                        asks,
                        images,
                    }
@@ -525,6 +745,14 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
            items.push(TranscriptItem::ClearedNote { seq });
            items
        }
        Event::LimitReached { resets_at } => {
            let mut items = items.to_vec();
            items.push(TranscriptItem::LimitNote {
                seq,
                resets_at: *resets_at,
            });
            items
        }
        Event::Compacted {
            pre_tokens,
            post_tokens,
@@ -541,6 +769,74 @@ pub fn fold_event(items: &[TranscriptItem], entry: &SeqEvent) -> Vec<TranscriptI
    }
 }
 /// What became of one tool call -- every state a card has to be able to
 /// draw, including the two that are not answers.
 ///
 /// The pair this enum exists for is [`ToolState::Succeeded`] against
 /// [`ToolState::NoResult`]. A call that finished having printed nothing
 /// and a call whose result never arrived both leave an empty `output`,
 /// and drawing them the same way states a verdict nobody reached: "it
 /// worked and said nothing" reads as a fact, where the truth is that the
 /// turn ended before anything came back.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ToolState {
    /// Started, no result yet, and the session is still working -- the
    /// ordinary state of a call in flight.
    Running,
    /// Stopped on the reader: a permission or question this call carries
    /// has not been answered, so nothing is happening until somebody
    /// answers it. Distinct from [`Self::Running`] because whose move it
    /// is differs, which is the Compose card's "your turn".
    Deciding,
    /// A result arrived and the tool did not report a failure.
    Succeeded,
    /// A result arrived and the tool reported that the call failed
    /// (`is_error`).
    Failed,
    /// No result ever arrived and the session is not working any more --
    /// the turn was interrupted, or the process went away. Not a verdict
    /// on the call: it says only that nobody found out.
    NoResult,
 }
 impl ToolState {
    /// The state of one call. `session_working` is
    /// [`session_working`]'s answer for the session this call is in --
    /// the only thing here that is not a property of the call itself, and
    /// what separates "still running" from "never came back".
    ///
    /// Written once, over the fields rather than per call site, because
    /// the five states are decided by four conditions and every place
    /// that re-derived a subset of them got a different subset.
    pub fn of(item: &TranscriptItem, session_working: bool) -> Option<Self> {
        let TranscriptItem::ToolRun {
            done, failed, asks, ..
        } = item
        else {
            return None;
        };
        debug_assert!(
            !failed || *done,
            "a call cannot have failed before its result arrived"
        );
        Some(if asks.iter().any(|ask| ask.answers.is_empty()) {
            // Ahead of `done`: a call waiting on permission has not
            // finished either, and which of the two the reader is being
            // told about is the one they can act on.
            Self::Deciding
        } else if !*done {
            match session_working {
                true => Self::Running,
                false => Self::NoResult,
            }
        } else if *failed {
            Self::Failed
        } else {
            Self::Succeeded
        })
    }
 }
 /// One row as the transcript draws it: a run of consecutive tool calls, or
 /// anything else. Ported from `ToolRows.kt`'s `TranscriptRow` and
 /// `groupToolRuns` -- the Compose card rendering in that file is not part
@@ -606,6 +902,37 @@ pub fn group_tool_runs(items: &[TranscriptItem]) -> Vec<TranscriptRow> {
    rows
 }
 /// Folds a page of raw transcript lines (`ApiClient::fetch_transcript_page`'s
 /// `Vec<Value>`) into the flat item list this module works over. A line
 /// this build can't parse fails the whole page rather than being skipped --
 /// CODE_RULES's "an enumeration must be able to say 'it broke'" -- since
 /// silently dropping one event could hide, say, a user message that then
 /// looks like it was never sent. Moved here from `desktop-app`'s `app.rs`
 /// (RUST.md's E4) when the Android transcript client (I5) needed the same
 /// fold: "write the logic once" applies to any caller embedding
 /// `transcript-ui` against a live server, not just the first one.
 pub fn fold_page(values: &[serde_json::Value]) -> Result<Vec<TranscriptItem>, String> {
    let mut items = Vec::new();
    for value in values {
        let event: SeqEvent = serde_json::from_value(value.clone()).map_err(|e| {
            format!("the server sent a transcript line this build couldn't parse: {e}")
        })?;
        items = fold_event(&items, &event);
    }
    Ok(items)
 }
 /// The wire `seq` a raw transcript line carries -- the live-stream resume
 /// cursor after loading a page must be this, not a folded item's `seq()`.
 /// A folded `AssistantMsg` keeps the seq of the *first* delta it
 /// accumulated (`fold_event`'s own doc), so resuming from that seq would
 /// re-deliver every delta already folded into it, duplicating the tail of
 /// a reply that was mid-stream when the page was fetched -- found via a
 /// real screenshot in E4 (RUST.md), where the assistant's line doubled.
 pub fn raw_seq(value: &serde_json::Value) -> Option<u64> {
    value.get("seq")?.as_u64()
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -749,6 +1076,7 @@ mod tests {
            Event::ToolEnd {
                id: "x".to_string(),
                output: "done".to_string(),
                is_error: false,
            },
        )]);
        assert_eq!(
@@ -761,6 +1089,7 @@ mod tests {
                input: String::new(),
                output: "done".to_string(),
                done: true,
                failed: false,
                asks: Vec::new(),
                images: Vec::new(),
            }]
@@ -824,4 +1153,368 @@ mod tests {
            other => panic!("expected a QuestionCard, got {other:?}"),
        }
    }
    fn line(seq: u64, json: serde_json::Value) -> serde_json::Value {
        let mut obj = json;
        obj["seq"] = serde_json::json!(seq);
        obj["ts"] = serde_json::json!(1.0);
        obj
    }
    /// The regression for a bug a real `run-headless.sh` screenshot found
    /// in `desktop-app` (E4, RUST.md): resuming the live stream from the
    /// last *item's* seq re-delivers the deltas already folded into a
    /// still-open assistant message, doubling its tail. `raw_seq` of the
    /// last wire line must be the true high-water mark instead, which for a
    /// run of deltas is higher than every item's own `seq()`.
    #[test]
    fn the_resume_cursor_is_the_last_wire_seq_not_the_last_items_seq() {
        let values = vec![
            line(1, serde_json::json!({"type": "userMessage", "text": "hi"})),
            line(
                2,
                serde_json::json!({"type": "assistantText", "delta": "a"}),
            ),
            line(
                3,
                serde_json::json!({"type": "assistantText", "delta": "b"}),
            ),
            line(
                4,
                serde_json::json!({"type": "assistantText", "delta": "c"}),
            ),
        ];
        let after = raw_seq(values.last().unwrap()).unwrap();
        assert_eq!(after, 4);
        let items = fold_page(&values).unwrap();
        let assistant_seq = items
            .iter()
            .find(|i| matches!(i, TranscriptItem::AssistantMsg { .. }))
            .unwrap()
            .seq();
        assert_eq!(assistant_seq, 2);
        assert_ne!(
            after, assistant_seq,
            "the fixed bug: these must differ here"
        );
    }
    #[test]
    fn a_page_folds_into_one_settled_assistant_message() {
        let values = vec![
            line(1, serde_json::json!({"type": "userMessage", "text": "hi"})),
            line(
                2,
                serde_json::json!({"type": "assistantText", "delta": "hel"}),
            ),
            line(
                3,
                serde_json::json!({"type": "assistantText", "delta": "lo"}),
            ),
        ];
        let items = fold_page(&values).unwrap();
        assert_eq!(
            items,
            vec![
                TranscriptItem::UserMsg {
                    seq: 1,
                    text: "hi".to_string(),
                    attachments: Vec::new(),
                },
                TranscriptItem::AssistantMsg {
                    seq: 2,
                    text: "hello".to_string(),
                    settled: false,
                },
            ]
        );
    }
    #[test]
    fn an_unparseable_line_fails_the_whole_page() {
        let values = vec![serde_json::json!({"seq": 1, "ts": 1.0, "type": "not-a-real-type"})];
        let err = fold_page(&values).unwrap_err();
        assert!(err.contains("couldn't parse"));
    }
    fn tool_start(seq: u64, id: &str, tool: &str) -> SeqEvent {
        event(
            seq,
            Event::ToolStart {
                id: id.to_string(),
                tool: tool.to_string(),
                input: serde_json::json!({}),
            },
        )
    }
    fn tool_end(seq: u64, id: &str, output: &str) -> SeqEvent {
        event(
            seq,
            Event::ToolEnd {
                id: id.to_string(),
                output: output.to_string(),
                is_error: false,
            },
        )
    }
    /// AGENTS.md's "things that have bitten": `joinPages` used to run
    /// `adoptRun` only on the path where a *split* call was found, so a
    /// boundary landing cleanly between two already-finished calls -- most
    /// of them -- left the older page's calls under the run name they were
    /// folded with, drawing one run of tool calls as two groups. Two
    /// finished, unrelated calls (no id in common) must still end up under
    /// one run name after the join.
    #[test]
    fn a_clean_boundary_between_two_finished_runs_is_still_healed_into_one_run() {
        let older = fold_all(&[tool_start(1, "a", "Bash"), tool_end(2, "a", "old output")]);
        let newer = fold_all(&[tool_start(3, "b", "Bash"), tool_end(4, "b", "new output")]);
        let joined = join_pages(&older, &newer);
        let run_ids: Vec<_> = joined
            .iter()
            .map(|item| match item {
                TranscriptItem::ToolRun { run_id, .. } => run_id.as_str(),
                other => panic!("expected only ToolRun items, got {other:?}"),
            })
            .collect();
        assert_eq!(
            run_ids,
            vec!["b", "b"],
            "the older call must adopt the newer, already-on-screen run's name"
        );
    }
    #[test]
    fn a_call_split_across_the_boundary_merges_into_one_row() {
        let older = fold_all(&[tool_start(1, "x", "Bash")]);
        let newer = fold_all(&[tool_end(2, "x", "the result")]);
        let joined = join_pages(&older, &newer);
        assert_eq!(
            joined,
            vec![TranscriptItem::ToolRun {
                seq: 1,
                id: "x".to_string(),
                run_id: "x".to_string(),
                tool: "Bash".to_string(),
                input: "{}".to_string(),
                output: "the result".to_string(),
                done: true,
                failed: false,
                asks: Vec::new(),
                images: Vec::new(),
            }],
            "the older half's tool/input and the newer half's output/done must both survive"
        );
    }
    #[test]
    fn a_message_split_across_the_boundary_is_rejoined_with_the_newer_halfs_identity() {
        let older = vec![TranscriptItem::AssistantMsg {
            seq: 1,
            text: "Hel".to_string(),
            settled: false,
        }];
        let newer = vec![
            TranscriptItem::AssistantMsg {
                seq: 2,
                text: "lo".to_string(),
                settled: true,
            },
            TranscriptItem::UserMsg {
                seq: 3,
                text: "next".to_string(),
                attachments: Vec::new(),
            },
        ];
        let joined = join_pages(&older, &newer);
        assert_eq!(
            joined,
            vec![
                TranscriptItem::AssistantMsg {
                    seq: 2,
                    text: "Hello".to_string(),
                    settled: true,
                },
                TranscriptItem::UserMsg {
                    seq: 3,
                    text: "next".to_string(),
                    attachments: Vec::new(),
                },
            ]
        );
    }
    /// A question is in a run of its own on both sides of a join -- healing
    /// must never rename the run of calls the reader was asked something
    /// on, the same rule `splitRun` enforces for a live turn boundary.
    #[test]
    fn adopt_run_never_renames_into_a_question_row() {
        let older = fold_all(&[tool_start(1, "a", "Bash"), tool_end(2, "a", "done")]);
        let newer = vec![TranscriptItem::ToolRun {
            seq: 3,
            id: "q".to_string(),
            run_id: "q".to_string(),
            tool: ASK_USER_QUESTION.to_string(),
            input: "{}".to_string(),
            output: String::new(),
            done: false,
            failed: false,
            asks: Vec::new(),
            images: Vec::new(),
        }];
        let joined = join_pages(&older, &newer);
        match &joined[0] {
            TranscriptItem::ToolRun { run_id, .. } => assert_eq!(run_id, "a"),
            other => panic!("expected a ToolRun, got {other:?}"),
        }
    }
 }
 /// [`ToolState`] is what a card colours itself by, so each of its five
 /// states is asserted from the events that actually produce it rather than
 /// from a hand-built item -- a mapping that agreed with a fixture and
 /// disagreed with the fold would be invisible until it was on screen.
 #[cfg(test)]
 mod tool_state_tests {
    use super::*;
    fn event(seq: u64, e: Event) -> SeqEvent {
        SeqEvent {
            seq,
            ts: 0.0,
            event: e,
        }
    }
    fn fold_all(events: &[SeqEvent]) -> Vec<TranscriptItem> {
        events
            .iter()
            .fold(Vec::new(), |items, e| fold_event(&items, e))
    }
    fn start(id: &str) -> SeqEvent {
        event(
            1,
            Event::ToolStart {
                id: id.to_string(),
                tool: "Bash".to_string(),
                input: serde_json::json!({"command": "ls"}),
            },
        )
    }
    fn end(id: &str, output: &str, is_error: bool) -> SeqEvent {
        event(
            2,
            Event::ToolEnd {
                id: id.to_string(),
                output: output.to_string(),
                is_error,
            },
        )
    }
    fn state_of(events: &[SeqEvent], session_working: bool) -> ToolState {
        let items = fold_all(events);
        ToolState::of(&items[0], session_working).expect("the fixture's first item is a tool call")
    }
    #[test]
    fn a_result_that_arrived_is_read_from_is_error() {
        assert_eq!(
            state_of(&[start("a"), end("a", "ok", false)], false),
            ToolState::Succeeded
        );
        assert_eq!(
            state_of(&[start("a"), end("a", "No such file", true)], false),
            ToolState::Failed
        );
    }
    /// The pair this enum exists for. Both calls have an empty `output`
    /// and nothing else distinguishes them, so a card that only looked at
    /// the text would draw the interrupted one as a call that ran fine and
    /// printed nothing.
    #[test]
    fn a_call_that_printed_nothing_is_not_a_call_that_never_answered() {
        assert_eq!(
            state_of(&[start("a"), end("a", "", false)], false),
            ToolState::Succeeded,
            "a result arrived; it was empty"
        );
        assert_eq!(
            state_of(&[start("a")], false),
            ToolState::NoResult,
            "no result, and the session is not working any more"
        );
    }
    /// The same call, mid-turn: still running rather than abandoned. The
    /// only thing separating the two is the session's own status, which is
    /// why `of` takes it.
    #[test]
    fn no_result_while_the_session_works_is_still_running() {
        assert_eq!(state_of(&[start("a")], true), ToolState::Running);
    }
    #[test]
    fn an_unanswered_ask_is_the_readers_move_whatever_else_is_true() {
        let asking = event(
            3,
            Event::Question {
                id: "q1".to_string(),
                prompt: "Allow?".to_string(),
                header: None,
                options: vec![QuestionOption {
                    label: "Allow".to_string(),
                    description: None,
                    preview: None,
                }],
                multi_select: false,
                about: Some("a".to_string()),
            },
        );
        let answered = event(
            4,
            Event::Answered {
                id: "q1".to_string(),
                answers: vec!["Allow".to_string()],
            },
        );
        // Ahead of both "still running" and "no result": the reader can
        // act on this one, and cannot act on either of those.
        assert_eq!(
            state_of(&[start("a"), asking.clone()], true),
            ToolState::Deciding
        );
        assert_eq!(
            state_of(&[start("a"), asking.clone()], false),
            ToolState::Deciding
        );
        assert_eq!(
            state_of(
                &[start("a"), asking, answered, end("a", "ok", false)],
                false
            ),
            ToolState::Succeeded,
            "once it is answered the call is an ordinary one again"
        );
    }
    #[test]
    fn nothing_but_a_tool_call_has_a_tool_state() {
        assert_eq!(
            ToolState::of(
                &TranscriptItem::UserMsg {
                    seq: 1,
                    text: "hi".to_string(),
                    attachments: Vec::new(),
                },
                true
            ),
            None
        );
    }
 }
@@ -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}")
    }
 }
@@ -25,16 +25,19 @@ next (a Masonry or iris transcript screen, most likely).
 | `sse.rs`                                  | `Sse.kt` (the framing half)               | Done, new tests (Kotlin had none of its own beyond integration) |
 | `api.rs`                                  | `Api.kt`                                  | Partial -- see below |
 | `event_stream.rs`                         | `EventStream.kt`                          | Done |
-| `transcript_fold.rs`                      | `TranscriptItems.kt`, `ToolRows.kt`       | Partial -- see below |
+| `transcript_fold.rs`                      | `TranscriptItems.kt`, `ToolRows.kt`       | Done -- see below |
 | `config.rs`                                | `ServerConfig.kt`'s `handleEnrollment`   | New, desktop-only so far -- see below |
-| *(not started)*                           | `TranscriptSource.kt`                     | Not started |
+| `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`). Test count by
+(`sse.rs`, `api.rs`, `event_stream.rs`, `transcript_fold.rs`,
-crate as of this writing: **85 in `client-core`**, 0 in `event-model` (its
+`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).
@@ -88,13 +91,27 @@ the full table to work from when one of these is next.
 including tool-call/question/image attachment and peer-message placement.
 `group_tool_runs` groups adjacent calls into `TranscriptRow::Tools`.
-**Not ported:** `TranscriptItems.kt`'s `joinPages` (and its
+`join_pages` (with `heal_split_message` and `adopt_run`, both private) is
-`healSplitMessage`/`adoptRun` helpers) -- the page-boundary healing that
+now ported too, 2026-09-06 -- the page-boundary healing that merges a tool
-merges a tool call split across two fetched pages and re-merges a run a
+call split across two fetched pages, rejoins a message a boundary cut
-boundary cut through. This matters the moment paging backward through
+through, and renames a run of tool calls onto whichever name is already on
-history is exercised; it is deliberately left rather than rushed, since
+screen. Ported with AGENTS.md's "things that have bitten" incidents as the
-it is exactly the kind of boundary logic this project's own "things that
+spec rather than a JVM test file (`TranscriptItems.kt` had none of its
-have bitten" section warns reads fine and is wrong at the edges.
+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.
@@ -119,20 +136,72 @@ 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
- **`TranscriptSource.kt`** -- the layer that decides whether a page comes
+- **A full markdown AST.** `markdown_blocks` (2026-09-06) splits a message
-  from the transcript cache or the server, and stitches the two. Needs
+  into its *top-level* blocks -- heading, paragraph, fence, list, table,
-  `transcript_cache.rs` and `api.rs`'s transcript-page method, both of
+  quote -- with each block's own source, which is what a renderer needs to
-  which exist now, so this is unblocked whenever picked up.
+  lay out prose versus code and what lets a streamed delta re-lay out one
- **The markdown *block* model beyond syntax spans** -- `highlight/markdown.rs`
+  block instead of the message (docs/RUST.md's Task B). What it
-  colours a `.md` file or fence for the highlighter, but does not build the
+  deliberately does **not** build is the tree below that: nested list
-  block tree (headings, lists, tables, fences as distinct nodes) that a
+  items, table cells, inline spans. Inline styling is still the renderer's
-  renderer walks to lay out prose versus code versus a table.
+  own job per block (`iris/transcript-ui/src/markdown.rs`), and nothing
-  `CodeFence.kt`'s use of `org.intellij.markdown` for that full CommonMark
+  has needed the rest yet. `CodeFence.kt`'s use of `org.intellij.markdown`
-  AST is Compose rendering plumbing, not something to port as-is; a Rust
+  for a full CommonMark AST is Compose rendering plumbing, not something
-  UI layer will want its own block parser or a crate for it, decided
+  to port as-is.
  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
@@ -142,5 +211,6 @@ be a second one, not a reason to move the type.
 `./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`,
+same way it always has). From `client-core/` directly: `cargo test`
-`cargo clippy --all-targets`, `cargo fmt` -- all clean as of this writing.
+(119 tests), `cargo clippy --all-targets`, `cargo fmt` -- all clean as of
 this writing (2026-09-06).
@@ -0,0 +1,444 @@
 # 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-06 (how a tool call looks, P1b)
 - **A card that never got a result says "no result", in yellow, and it is
  a state Compose cannot say.** A call that finished having printed
  nothing and a call whose turn was interrupted before anything came back
  both leave an empty output. Compose draws both as an ordinary finished
  call, which reads as a fact somebody established. There are five states
  now, each with a word and a colour: nothing at all for a call that
  worked, "running" (grey), "your turn" (peach, Compose's own wording and
  colour), "failed" (red), "no result" (yellow).
 - **A failed call is drawn as failed, which needed a field on the wire.**
  `is_error` is on the CLI's `tool_result` and was being dropped; the
  server now carries it to the phone. Reversible, but the alternative is a
  card that says a call succeeded because it cannot tell.
 - **A group's cards do not each carry their own surface.** Compose gives
  each card a fill and squares the corners where it faces a neighbour, so
  a run reads as one object broken into parts. iris has no per-corner
  radius, and -- more to the point -- a group built the way Compose builds
  it hit a framework layout defect that drew every card's text a card
  below its own box. So a group is one surface with its cards on it,
  separated by a small gap, and the 4dp inset Compose holds them off the
  edge by is gone. Worth revisiting once the layout defect is fixed
  (docs/IRIS_TODO.md).
 - **A long tool output is capped at 80 lines or 4 kB with a "Show all N
  lines".** Compose draws the whole thing, and gets away with it because
  its `Text` inside a `LazyColumn` lays out lazily; here the output is one
  text widget and shaping a hundred kilobytes of it costs what the file
  editor's 32 kB limit was measured against. If iris's text gets cheaper,
  this is the number to move.
 - **A card's command is clipped, not pannable, and its summary line is
  clipped rather than ellipsised.** Both are framework gaps rather than
  choices (`scrollable_on` on a non-editable text draws nothing; there is
  no overflow ellipsis), and both are worse than Compose today. Named here
  because they are visible.
 ## 2026-09-06 (how a markdown block looks, P1a)
 - **A table is drawn as padded monospace columns, not as a grid.** Your
  call to reverse. Compose draws a real grid: cells on a tint, each
  column with a 136dp floor, scrolling sideways when there are too many.
  iris has no grid widget, and building one would be a widget per
  markdown feature -- which is the thing the block model exists to avoid.
  In a monospace face a character count *is* a pixel width, so padding
  each cell to its column's width is alignment, the widths are still
  measured from the cells, and a table that is too wide pans sideways
  through the same mechanism a code fence already uses. The header is
  bold with a rule under it, and a long cell wraps inside its column
  (capped at 28 characters, which is what fits three columns across a
  phone). **What it trades:** no cell borders, and a table looks like
  code rather than like a table. If you want the grid, it is a new widget
  and it is a day's work.
 - **Three block frames, and only three.** A heading, paragraph and list
  are plain text with spans; a fence and a table are a rounded panel that
  does not wrap; a quote is a bar with the text padded past it.
  Everything else markdown says is expressed in span styles, which cost
  no widgets and no layout nodes. So a new markdown feature is a span,
  not a widget.
 - **A list's marker is part of the text, so a wrapped item's second line
  returns to the left margin.** Compose keeps it indented by giving the
  marker its own column. Doing the same here needs per-line indent in
  iris's text attributes; it is written down rather than done, because
  the list items in a real reply are usually one line.
 - **A link opens on a tap and not on the end of a drag.** A press that
  panned the transcript past a link, or that held long enough to start a
  selection, does not follow it -- decided by the same gesture machine
  that decides pan-versus-select, so there is one rule rather than two
  that can disagree.
 ## 2026-09-06 (composer scroll and the streaming block model)
 - **A streamed message becomes a column of per-block widgets.** Decided by
  the design agent; recorded here because it is the shape of every message
  on screen. A transcript row is one `TextEdit` today, so a streamed delta
  re-shapes the entire message through parley on every event -- the stream
  phase is the one place iris is behind Compose on your phone (p50 18.2ms
  vs 13.4ms). A row becomes a column of one widget per markdown block
  (paragraph, heading, fence, list, table) and a delta replaces only the
  last block, keeping every earlier block's layout. **Rejected:** splitting
  parley's layout at block boundaries inside one text widget (couples
  iris's text widget to markdown structure, and parley has no incremental
  API), and caching shaped runs per paragraph inside `TextEdit` (a second
  cache with its own invalidation beside the glyph cache). Chosen because
  P1's markdown block model is needed anyway, so the split happens once, in
  `client-core`, and iris stays a text renderer. **Status: designed, not
  built** -- this pass spent its budget on the composer's three layout
  defects; docs/RUST.md has the design and the pass conditions.
 - **The composer's overflowing text now scrolls on a finger**, capped at
  six lines and clipped to the bar. Reverses the "still does not scroll"
  item below.
 - **A widget may not report a `dp` length** (see IRIS.md). A rule for
  widget authors, enforced by a `debug_assert!`; nothing changes for app
  code.
 ## 2026-09-06 (stale-primitives and touch-scroll pass)
 - **A vertical drag inside a focused composer now scrolls rather than
  selects.** Android's own `EditText` does this -- a vertical drag scrolls
  the field, and only a long press starts a selection -- so the platform
  decided it. What it costs: you can no longer drag straight down inside
  the composer to select several lines of what you typed; use a long press
  and then drag, or drag sideways. Say if that trade is wrong for you.
 - **`Scroll` gets a finger pan but no fling.** `List` flings; a scroll area
  does not, because it has no per-frame tick to animate one and the areas
  it wraps are at most a screenful (Android does not fling a six-line text
  box either). Easy to add later if a scroll area ever wraps something long.
 - **The composer still does not scroll its overflowed text**, though the
  mechanism it needs is now in place. Wrapping the field in `.scrollable()`
  was tried and reverted the same day: `Scroll` measures its content and
  container against the *window*, so inside the `MaxSize` that caps the
  composer at six lines the two are in different spaces and the field pans
  itself entirely out of the bar (measured on the emulator with 474
  characters in it -- the bar collapsed to its padding). Fixing that means
  `Scroll` measuring against its own offered box, which is a change to a
  widget the transcript and the bench shell both use, so it is its own
  piece of work rather than a rider on this one.
 ## 2026-09-06 (defect pass)
 - **The keyboard-open diagnostics overlay is gone; the capture only
  logs now.** It was added when `on_insets_changed` was not firing at all
  and there was no way to get a report off the phone. It fires reliably
  since the activity went edge-to-edge -- and what that looks like in
  use is a full-screen report covering the app **every time the keyboard
  opens**, with its own Copy/Close buttons sitting underneath the
  keyboard, so it cannot be dismissed (reproduced on the emulator this
  pass: two `tap 'CLOSE'` runs left it up). An interruption for something
  nobody asked for, over the app you are trying to type into. The named
  `Diagnostics` button still shows the same text on demand, and the new
  `iris surface:`/`iris insets:` log lines carry the lifecycle a `logcat`
  pull needs. Reversible: `capture_keyboard_diagnostics` is still the one
  place this is decided, and `PlatformHandle::show_diagnostics_overlay`
  is still there.
 - **The bench shell's report pane is sized to its report, not to a share
  of the window.** It held `.height(rest(1))` beside the transcript's
  `rest(2)`, so an *empty* `TextEdit` reserved a third of every screen --
  which is what Iris's "the app does not start with keyboard spacing
  correct" screenshot was showing, with the composer two thirds down and
  black below it. It is `.max_height(dp(260))` now and sits above the
  transcript rather than under the composer, where it was eating the
  navigation-bar clearance. Cost: a filled report is clipped at 260dp
  rather than scrolling (a `Scroll` there drew itself off the top of the
  screen, since `Scroll` pins to the end of its content and reports its
  content's full length to the parent -- worth fixing in `Scroll`, not
  worked around here). "Copy report" and `logcat` still have the whole
  thing.
 ## 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.
@@ -0,0 +1,957 @@
 # 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.
 - [x] **Composed/typed text never becomes visible at all -- root-caused
  and fixed 2026-09-06.** Not the renderer at all: **the composer's buffer
  was empty the whole time.** `TextEditCtx::select` (`iris/src/widget/
  text/edit.rs`) compared the tap against the *laid-out text's* box and
  set `selection = None` for anything outside it -- and an empty field's
  layout is a zero-width box, so tapping an empty composer granted focus
  and opened the keyboard while leaving no caret; `insert_str` returns
  early with no caret, so every keystroke after that was dropped in
  silence. Gboard's suggestion strip is its own composing state, not a
  read of our buffer, which is what made the earlier pass conclude the
  buffer held the text. Fixed by letting parley clamp a tap outside the
  layout to the nearest cursor position (a press that reaches `select`
  has already been hit-tested to the widget, so there is no "outside"),
  plus a `debug_assert!` in `insert_str` so an insert with no caret fails
  at the mistake instead of dropping input -- it immediately caught
  `layout_tests::composing_text_after_a_keyboard_resize_...` typing into
  an unfocused field. Three new tests in `edit.rs`
  (`tapping_an_empty_field_places_a_caret_so_typing_lands`,
  `tapping_past_the_end_of_the_text_clamps_to_the_end`,
  `dragging_without_a_previous_selection_selects_nothing`); the first
  fails on the pre-fix code. Emulator evidence: `adb shell input text`
  after `tap 'Message'` now shows the text in the bar
  (`/tmp/final-typing.png`) and logs `iris text render: chars=5 ...
  glyphs=5`, against `glyphs=0` on every keystroke before.
  **The old, superseded diagnosis, kept because it was wrong in an
  instructive way:** 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.
 - [x] **The composer has no touch-drag scroll for overflowing text.**
  **Done 2026-09-06.** `field.scrollable().masked()` in
  `transcript-ui/src/composer.rs`: a finger drag inside the bar pans the
  message, the bar stays capped at six lines, and a vertical drag in the
  focused field no longer extends a selection (Android `EditText`'s own
  behaviour). Verified on this checkout's emulator with the
  `transcript-screen bench force-gles` debug build -- six repetitions of a
  13-word sentence typed in, then
  `ui-trace record --do "swipe 540 1200 540 1460 300"`: the field's
  `Message` box moved `31,1041..1048,1509` -> `31,1131..1048,1651` (the
  content panned down with the finger) with its **height unchanged at
  468px** (the bar did not grow), and the two screenshots either side show
  different text in the same band.
  Three real defects had to be fixed first, each with a headless
  regression test in `iris/src/layout_tests.rs` and each confirmed to fail
  without its fix (docs/RUST.md's plan box has the measurements):
  a `MaxSize` reporting its cap as an unresolved `dp` (`Len::fold_dp`), a
  `Masked` allocating a fresh mask slot per draw (`ActiveData::own_mask`),
  and a panned widget's own hit box moving twice (`move_applied`).
  `Scroll` itself turned out to measure the right number by a misleading
  route -- it is written against `painter.px_size()` now, and the claim
  below that it "measures against the window" was wrong.
  **The grey background was not missing** -- that note (written here on
  2026-09-06 and repeated as still open) is withdrawn. Re-measured the
  same day on the same AVD by decoding the screencap rather than reading
  it: the bar is `rgb(41,40,49)`, the declared `UiColor::new(40, 40, 46)`
  after sRGB rounding, **full width and y2245..y2365** on 1080x2424, with
  the field at `31,2277..1048,2329` and the 63px nav strip below it. It
  is dark by design and sits on black, which is very likely what the
  earlier reading was: at a glance the band and the background are hard
  to tell apart. If it should read as a bar rather than as a slightly
  different black, the colour is the thing to change, not the tree.
 ## 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.
 - [x] **"The app definitely does not start with keyboard spacing
  correct. This is how it looks without me doing anything initially."**
  **Not an inset bug at all -- fixed 2026-09-06.** The black third is the
  bench shell's own empty *benchmark report* pane: `bench_client.rs`'s
  root tree gave it `.height(rest(1))` beside `content.height(rest(2))`,
  so an empty `TextEdit` reserved a third of the window at every launch
  and pushed the composer up by exactly that. Measured on this checkout's
  emulator at the phone's own size (1080x2424, density 420, gesture nav),
  which reproduced Iris's screenshot exactly: new `iris insets:` log line
  reported `bottom=63 ime_bottom=0` at launch (a nav bar, no keyboard --
  so the inset the composer was fed was never large), while `ui-trace
  show -m Message --field box` put the field at `31,1488..1048,1540` on a
  2282px-tall surface, 789px clear of the bottom -- that pane's third.
  **Unit mixing checked explicitly and cleared**: `set_bottom_inset` takes
  physical px and stores `Len::abs`, `MainActivity.java`'s `1`/`0`
  `ime_bottom` only ever reaches `insets.bottom.max(ime_bottom)` and
  `> 0.0`, and every `dp` in the composer resolves at layout time. Fix:
  the report pane is sized to its content (`.max_height(dp(260))
  .scrollable()`), and moved above the transcript so it cannot eat the
  composer's nav-bar clearance. After: field box `31,2277..1048,2329`,
  grey bar ending at device y2361 with the 63px nav strip below it
  (`/tmp/fix1.png` this pass).
  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."** Improved 2026-09-06 by the focused-field rule
  below, still needs her phone to close. `attr.rs`'s `on_press` treated an
  already-focused composer as the plain drag-to-select case, so a swipe
  starting inside it dragged a highlight through the typed text for the
  whole gesture; it now abandons that the moment the press passes
  `DRAG_SLOP` vertically (Android `EditText`'s own rule), which removes one
  of the two things that made the bar feel like it caught the swipe. The
  residual `DRAG_SLOP` measured from the boundary crossing, described
  below, is unchanged. Original note follows.
  Not closeable from the emulator, annotated
  2026-09-06 after the `DragGesture` merge. `attr.rs`'s `on_press` never
  calls `capture_pointer` and never consumes a `Pressing` frame past
  `DRAG_SLOP` (it just stops watching), so once the finger's *current*
  position leaves the composer's box and enters the list's, `List`
  starts receiving ordinary hit-tested `Pressing` frames there --
  `DragArbiter::is_idle()`'s 2026-09-05 recovery (a missed `PressStart`)
  picks it up rather than leaving it stuck. What this does **not** do is
  what "wherever it began" implies literally: `DragArbiter::press_start`
  restarts from the *boundary-crossing* position, not from the original
  touch-down inside the composer, so the pan still needs a fresh
  `DRAG_SLOP` of travel measured from the boundary rather than from the
  start of the gesture -- composer and list are adjacent, non-overlapping
  widgets (`lib.rs`'s `(list, composer_bar).span(Dir::DOWN)`), and only
  the composer forwarding its own drag to the list would remove that
  residual slop entirely, which is more than this pass's merge changes.
  RUST.md's merge-pass box has the reasoning in full and an emulator
  swipe confirming the composer's own box never moves/resizes during it;
  whether the residual slop is still perceptible as "caught" needs Iris's
  phone, since the emulator's per-widget boundary is a few dp wide and
  easy to cross without noticing on a real screen too.
 - [ ] **"Flinging still does not work."** No longer expected to reproduce
  after the `DragGesture` merge (`e12c708`, pointer capture +
  `CursorSense::Drop`), 2026-09-06. Emulator evidence (RUST.md's
  merge-pass box, check (b)): a real `ui-trace` finger swipe followed by
  screenshot-hash sampling caught a post-release frame distinct from the
  drag's own last frame in one run, and every run showed 28-32
  `render()` frames per gesture against an idle baseline of 0 and ~8
  expected from the drag alone -- redraw kept being requested well past
  the finger lifting, which only happens while a fling is still
  animating. Left unticked in spirit until Iris's phone confirms it,
  since only she can say whether it *feels* like a fling now; the
  emulator's screenshot timing could not always catch the tail of a
  fast-settling one visually (same caveat noted in RUST.md).
 - [~] **"Text still disappears if I leave and come back to the app."**
  **Instrumented 2026-09-06 so the phone can answer it**, since no
  emulator here has a Vulkan adapter. `iris/src/android/view.rs` now logs
  one `log::info!` line per surface event with the glyph/atlas counts:
  `iris surface: surface_destroyed, tearing the renderer down
  (glyphs_cached=387 atlas_pages=1)`, `iris surface: surface_changed
  1080x2424 already_live=false glyphs_cached=387 atlas_pages=1`, `iris
  surface: new renderer built (Gl), clearing glyph atlas: glyphs=387
  pages=1`, plus `iris insets: ... window=(1080, 2424)` on every insets
  change. That is the emulator's own healthy app-switch cycle, verified
  this pass (home, reopen, screenshot: all text intact,
  `/tmp/appswitch.png`). **The one line to look for on the phone is
  `already_live=`**: `true` on the return from backgrounding would mean
  the surface came back *without* a `surface_destroyed`, so
  `surface_changed` reconfigured a renderer whose Vulkan swapchain and
  atlas textures belong to a window that is gone -- the reuse branch
  never clears the atlas, by design. `false` with no `new renderer built`
  line after it would mean the renderer failed to rebuild. Either answer
  names the fix; guessing between them from here does not.
  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.
 ## From the phone, 2026-09-06, 22:16 (build from 20303e0, delivered via ai-app-bench 95e25fe)
 Iris's report, verbatim, with a screenshot. Phone: Mali-G715 (Vulkan),
 `content_scale: 2.55`, 120Hz. Open until ticked with phone-side evidence.
 - [ ] **"Fling still doesn't work."** -> on `ed04d4c`, 2026-09-07:
  *"flinging now does technically do something, but it seems to just be
  linear velocity with an abrupt stop."* **It was exactly that, and the
  arithmetic said so.** `distance_fraction(t)` returned `t` for every `t`
  -- a constant-speed slide for the whole duration, then a stop at full
  distance -- because two halves of AOSP's spline build loop were
  transposed, which made `SPLINE_POSITION` and `SPLINE_TIME` identical, and
  the lookup bracketed `t` between `SPLINE_TIME` entries rather than
  between even time steps. The two cancelled to the identity. Ported
  exactly now from `OverScroller.java` and
  `androidx.compose.animation:animation:1.12.0`'s `SplineBasedDecay.kt`
  (they agree line for line), with `iris/benches/fling_spline_reference.py`
  as an independent transcription supplying the numbers the tests assert
  on. Emulator, 2026-09-07: a released `v=3750` decelerates
  `3746 -> 2624 -> 1834 -> 1144 -> 752 -> 449 -> 243 -> 83px/s` across 32
  frames; a flick into the end of the list stops there in one tick with no
  overshoot; a tap 200ms into a fling ends it at 11 ticks instead of 32.
  **Open until the phone says so** -- a flick should now visibly slow
  before it stops. Its earlier three defects (the velocity, the missing
  animation registration, the 56x coefficient) are all still fixed and were
  never the linear part.* Second report; the emulator's
  `ui-trace` swipe flings (verified 2026-09-06 with `render()` counts),
  a finger on the phone does not. What differs: a real flick at 120Hz is
  batched by Android into few `MotionEvent`s with *historical* samples
  (`getHistoricalX/Y/EventTime`), and can be DOWN, one or two MOVEs, UP
  inside `DRAG_SLOP`'s worth of frames; a `ui-trace` swipe is many
  evenly-spaced MOVEs. Suspects, in order: `android/sense.rs` reading
  only each event's final position (the velocity tracker sees two
  samples, or one); the release path starting a fling only from a
  gesture already in `Panning`, so a flick that crosses the slop on its
  last sample is treated as a tap; `ACTION_CANCEL`/pointer-capture
  delivering no `Drop`. Log the release decision (samples, span,
  velocity, outcome) at `info` so the next logcat settles it.
 - [x] **"I can't reopen keyboard by tapping on message box after it
  already happened once."** *(Fixed 2026-09-07: `attr.rs`'s already-
  focused branch calls `focus_gained` on a tap inside `DRAG_SLOP`.
  Emulator: first tap `mInputShown=true`, back gesture, second tap
  `mInputShown=true`. Negative control with that one call removed leaves
  the second tap at `false`; a horizontal and a vertical swipe over the
  focused field both leave it at `false`, so the earlier "swiping over
  the input bar brings up the keyboard" has not returned.)* The field stays focused after the keyboard
  is dismissed (back gesture, or the IME's own hide), so `on_press`'s
  already-focused branch never requests the IME again. Android's
  `EditText` shows the IME on every tap of a focused field; do the same
  (`FocusHost`: a tap on a focused field requests the IME, idempotent
  when it is already shown).
 - [ ] **"Message box does not push up the scroll area."**
  **Reopened by the phone on 2026-09-07** -- *"similarly, the keyboard
  raising up does not push things upwards"* -- after being ticked on
  emulator evidence the day before (`ime_bottom=883`, composer box
  `31,2277..1048,2329` -> `31,1457..1048,1509`). The JNI half was right;
  what was wrong is one line of `iris/android-app/app/build.gradle`:
  **`targetSdk = 34`** against `compileSdk = 37`, while the Compose app in
  `app/` targets 37 and *does* push up on her phone. Below target 35 the
  window keeps the legacy behaviour, where `adjustResize` shrinks it for
  the IME and `getInsets(ime()).bottom` therefore measures zero;
  `setDecorFitsSystemWindows(false)` opts out of that and still takes on
  the API 36 emulator here, which is why every test run passed. Now
  `targetSdk = 37`, plus a `WindowInsetsAnimation.Callback` for the devices
  where only the animation path carries the height -- which also makes the
  push-up animate (`ime_bottom=509, 663, 833, 881, 883` instead of one
  jump). **This is a reading, not a measurement**: no Android 17 device is
  reachable from here. So the Diagnostics pane now prints
  `insets: dispatches=N left=… ime_bottom=… ime_visible=…` --
  **screenshot that line with the keyboard open.** `ime_bottom` in the
  hundreds and the composer risen means fixed; `dispatches` climbing with
  `ime_bottom=0` means the reading was wrong and the window is still being
  resized; `dispatches=0` means the listener is not firing at all, which is
  a third thing again.* Since
  `MainActivity` went edge-to-edge (`e12c708`), `adjustResize` no
  longer resizes the window, so the app owns the IME inset -- but
  `ime_bottom` is passed through JNI as the boolean `1`/`0` (the
  2026-09-06 "(b)" fix), so nothing has the inset's *height* to pad the
  transcript and composer with. Pass both: `isVisible(ime())` and
  `getInsets(ime()).bottom` in px; the list's bottom padding and the
  composer's position follow the height, the visibility drives the
  boolean the `imePadding` rule in AGENTS.md's "Things that have bitten"
  describes.
 - [x] **"Picture is what happens if I leave the app and come back,
  which completely removes text, and then I tap on the debug info. The
  textures are definitely getting cooked for some reason after leaving
  the app and resuming."** Screenshot: every glyph drawn *before* the
  resume is fragments; the diagnostics text drawn *after* is perfect;
  the report says `atlas format: Rgba8Unorm, views live: 0`. Reading:
  `Textures::reset`/`GlyphAtlas::clear` on the new renderer emptied the
  GPU atlas, but the per-widget cached text primitives (`TextView`'s
  render cache -- the one `c3cfc67`'s shape counter is keyed on) still
  carry the old atlas coordinates and are re-submitted as-is; only
  widgets drawn fresh after the resume shape and upload again. Fix: a
  renderer rebuild invalidates every cached text render (one
  generation counter on the atlas, checked at `TextView::render`, or
  a full-tree redraw with caches dropped), with a `debug_assert!` that
  no submitted glyph quad references an atlas generation older than the
  live one. Reproducible on the emulator by forcing a renderer rebuild
  (home + return, or `surface_destroyed`/`surface_created`) on a screen
  with text already drawn -- the earlier "verified" home/reopen check
  screenshotted the emulator's GLES path, where a resume may not
  destroy the surface at all.
  **Fixed in `ba2afba` and confirmed on the phone (Iris, 2026-09-07:
  "the resume glyph corruption is fixed").** Closed. The emulator could
  never have settled it -- no Vulkan adapter here, and the GLES path may
  not destroy the surface at all -- so the phone was the only place this
  could be answered, and it has been. `clearing_the_atlas_re_renders_
  cached_text_instead_of_reusing_it` is what keeps it.
  The reading above is right and the mechanism is one step narrower than
  "cached text primitives". `IrisViewPeer::surface_changed`
  (`iris/src/android/view.rs`) *does* already force a full-tree redraw
  after a rebuild: it calls `render.resize(...)` unconditionally, which
  sets `UiRenderState::resized`, which makes the next `update` take
  `redraw_all` rather than `redraw_updates`. So every widget's `draw`
  really does run again after the resume. What survives it is one cache
  further in: `TextView::render` (`iris/src/widget/text/mod.rs`) returns
  its cached `RenderedText` whenever the wrap width, buffer and attrs are
  unchanged -- true of every pre-resume row -- so `TextData::place` is
  never reached, nothing is re-rasterised into the fresh atlas, and the
  *old* atlas's `uv_min`/`uv_max`/`layer` are re-submitted verbatim. Only
  text whose content changed after the resume (the diagnostics pane Iris
  tapped) re-shapes, which is exactly the split in her screenshot.
  `Painter::glyphs` has one call site in the whole workspace, that one,
  so there is no second holder of a `RenderedText` to fix.
  The fix, in `ba2afba`: `GlyphAtlas::generation`, bumped by
  `GlyphAtlas::clear`; `RenderedText::generation` recording which atlas
  its glyphs were placed against; `Painter::atlas_generation()`;
  `TextView::render`'s cache key gains it; and a `debug_assert_eq!` in
  `Painter::glyphs` that a submitted quad's generation is the live one.
  Headless test
  `clearing_the_atlas_re_renders_cached_text_instead_of_reusing_it`
  (`iris/src/widget/text/mod.rs`): draw, `atlas.clear()`, `resize`, draw
  again, and assert the atlas holds the same glyph count again -- it
  stays at 0 without the fix, because the cache short-circuits before
  `place`.
 ## 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).
  - [x] **A tappable link** — done 2026-09-06 (P1a). `TextEditCtx::
    byte_at(pos, size)` answers which byte a tap landed on without
    handing out the parley layout, `GestureOutcome::Tapped` says the
    press committed to neither a pan nor a selection, and
    `iris::platform::OpenUrl` is the capability each backend implements
    (`xdg-open`/`open`/`start`; an `ACTION_VIEW` intent on Android,
    deferred to `after_input` the way `pending_show_keyboard` is).
  - [ ] **A background chip behind inline code.** Still needs per-range
    glyph *geometry* — a run's boxes, not one offset — which
    `TextEditCtx` does not expose outside `iris::widget::text`
    (`edit.rs`'s `layout()` helper is private). The same primitive
    `TextEdit::draw`'s own selection highlight uses internally,
    `iris/src/widget/text/edit.rs:99`. `byte_at` above deliberately did
    not open that up: a tap needs one offset and a chip needs the run.
  - [ ] **`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.
  - [x] **Syntax highlighting inside a fenced code block** — done
    2026-09-06 (P1a). `client_core::highlight::spans_of` by language,
    converted from its char indices to `SpanStyle`'s byte offsets, in
    the same Catppuccin palette `Theme.kt` uses. A language the scanner
    has no rules for stays plain rather than being coloured by the
    nearest one's.
 - [ ] **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.
 ## Found by P1a (2026-09-06)
 - [x] **`Rect` claimed to be size-independent, and it is not.** A `Rect`
  fills whatever region it is handed, so `draw_inner`'s size-independent
  fast path -- which rewrites primitives with
  `r.outside(&from).within(&region)` rather than redrawing -- could not
  reproduce its `draw`, and a `.background(rect(..))` kept the size of
  the *provisional* full-region pass `Span` does in phase 1. One fenced
  code block's panel covered every block below it and every row below
  that. Fixed in `iris/src/widget/rect.rs`; the reason is written at the
  definition. Suspect the same cause for anything else tinted with a
  background rect.
 - [x] **A wrapped transcript row tripped `reposition`'s debug assert.**
  Settled 2026-09-06 by giving the move slot one owner instead of two.
  `mov` accumulates a delta on it, `reposition` overwrote it, and both
  legitimately land on one widget in one frame: `List::place`'s
  Bottom-known branch offers a row a same-size box that has *moved*
  (`mov`), then corrects the placement inside it when the row's cached
  height no longer matches what the row reports (`reposition`). The
  slot now always means `move_applied + repositioned`
  (`ActiveData::repositioned`, `iris/core/src/ui/render_state.rs`), so
  `reposition` adds the move rather than dropping it -- the assert is
  gone and the arithmetic is right. Test:
  `a_widget_moved_by_its_parent_and_then_placed_inside_it_lands_at_the_placement`
  in `layout_tests.rs`, which lands the child at the *offered* position
  (-100px) instead of the placement (100px) without the fix, and a
  `debug_assert_eq!` in `reposition` that nothing but those two ever
  writes the slot. Verified with the `.wrap(true)` repro (draws, no
  panic) and an emulator bench run with assertions live.
 - [ ] **Desktop colours are washed out: the winit surface is sRGB and
  the shader writes the palette's bytes as linear.** Mocha Crust
  (17,17,27) is drawn as (73,73,91), measured off
  `run-headless.sh --shot`. Android is correct, so this is the surface
  format rather than the palette -- but it makes the desktop build
  useless as a colour reference, which is exactly what P1a needed it for
  when the emulator could not draw glyphs.
 - [x] **Every glyph was a solid box on the GLES backend -- iris's bug,
  not the emulator's.** Fixed 2026-09-06. The atlas is one
  `texture_2d_array` and `GpuTextures::new` created it with **one
  layer**; wgpu-hal picks the GL target from the descriptor
  (`(false, 1) => TEXTURE_2D`), so under GLES that array was a
  `GL_TEXTURE_2D` bound to the shader's `sampler2DArray`, the unit was
  incomplete, every `textureSample` returned (0,0,0,1), and
  `draw_glyph`'s `color.a *= texel.a` filled the quad. `MIN_ARRAY_LAYERS
  = 2` in `iris/core/src/render/texture.rs`, with a `debug_assert!` at
  `create_array_texture`. Vulkan (the phone, the desktop's default
  backend) was never affected. Reproduce the class in seconds without an
  emulator: `iris`'s `force-gles` feature now switches the **desktop**
  backend too -- `./run-headless.sh transcript --shot /tmp/x.png -- -p
  transcript-ui --features iris/force-gles`.
 - [ ] **The bench report pane draws over the transcript rows instead of
  replacing them.** Visible on the emulator for the first time now that
  glyphs render there (`/tmp/emu-final.png`, 2026-09-06): after a bench
  run the report's lines and the transcript's occupy the same rows in the
  top third of the screen, both legible, neither on top. Pre-existing --
  the same overlap is in a screenshot taken before the move-slot fix -- so
  it is its own item, most likely the report pane not masking or not
  claiming its region.
 ## Found by P1b (2026-09-06), all with a headless repro
 Each was found by looking at `iris/run-headless.sh transcript -- -p
 transcript-ui` rather than at a diff, and each is worked around in
 `transcript-ui/src/tool.rs` rather than fixed here. docs/RUST.md's P1b box
 has the fuller account.
 - [ ] **A `Span` of `Pad`ded children inside another `Span` places those
  children a slot out of step.** Each child drew its content one sibling's
  height below its own box. Repro: `IRIS_TOOLS_EXPANDED=1
  iris/run-headless.sh transcript --shot /tmp/x.png -- -p transcript-ui`
  with `tool.rs`'s group built as `Span(DOWN)[header, Pad(Span(DOWN)
  [cards]), bar]` instead of the single `Span` it uses now. Bisected:
  removing the inner `Span` fixes it, and so does removing the children's
  own `Pad`; the background `Stack`, the `Sized` wrappers and the
  `WidgetPtr` per child make no difference. **Not** the `mov`-vs-
  `reposition` fault f5b8893 fixed -- it survives that commit. The
  workaround costs the group the 4dp inset its Compose counterpart holds
  its cards off the edge by, so this is worth fixing.
 - [ ] **`scrollable_on(Axis::X)` on a non-editable `Text` draws nothing.**
  The panel is drawn and the text inside it is not. A markdown fence does
  the same to a `TextEdit` and is fine, so it is the widget kind rather
  than the chain. `tool.rs`'s `raw_block` is `masked()` only until this is
  fixed, which means a long command is clipped rather than pannable.
 - [ ] **No overflow ellipsis.** `TextAttrs` can wrap or not wrap; there is
  no "one line, ellipsised" the way `maxLines = 1` + `TextOverflow.
  Ellipsis` gives Compose. A tool card's summary is clipped instead, so
  nothing on screen says it was cut. Whichever end is cut has to be a
  choice when this lands: a path is identified by its tail, a command by
  its head.
 - [ ] **A drawn chevron.** `Chevron.kt` draws its own strokes precisely
  because a chevron from a font is a glyph a system font may not have --
  and the bundled `NotoSans-Regular.ttf` indeed has no U+25B8/25BE/25B4,
  while `NotoSansMono-Regular.ttf` does. `tool.rs` sets the mark in the
  monospace face as a result. A real fix needs a line/path primitive;
  iris has rects, text and textures only.
 - [ ] **A tool card's text is not selectable.** `Selection` is keyed
  `(RowKey, block index)` and a card has no markdown blocks, so nothing in
  a card registers. Compose's `SelectionContainer` covers tool output,
  which is the text people most want to copy. Needs a key for "the nth
  text of this row" that a card can mint without colliding with a
  message's blocks.
 ## 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
 - [x] **Streaming a delta into a long message costs a full text layout of
  that message.** **Done 2026-09-06** -- a row is a column of one
  `TextEdit` per markdown block (`client_core::markdown_blocks`,
  `row::RowBlocks::apply_delta`), so a delta re-shapes the last block and
  keeps every earlier block's layout. A block is the selection unit now
  (`Selection`'s `SelKey`); selection across blocks and rows still works,
  checked on the emulator with a real long-press drag. Pass condition met
  in `a_delta_into_a_long_reply_redraws_the_same_widgets_as_a_short_one`:
  a delta into a 100-paragraph reply redraws the same widget count as one
  into a one-paragraph reply (30 either way). Emulator stream phase, same
  AVD before and after: **p50 61.5 -> 54.5ms, p90 211.7 -> 113.1ms, p99
  342.6 -> 137.4ms, worst 403.6 -> 143.0ms**, 202 -> 293 frames in the same
  21 seconds. docs/RUST.md's Task B box has the detail and the two dead
  ends. **The phone is the measurement that decides it** -- these are
  emulator numbers and only the ratio transfers.
  The original entry, for the record: 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.
 ## From the phone, 2026-09-07 (build from ed04d4c)
 - [ ] **"Some transcript blocks will be hidden until I uncover enough of
  them."** Two screenshots of the bench app's transcript at the top
  edge, both wrong in opposite directions: in one, rows scrolled above
  the viewport are still drawn and bleed *through* the header bar
  (`version = "0.1.0"` and a paragraph visible behind "Run benchmark /
  Copy report / Diagnostics"), so the list's mask is not clipping at
  the header's bottom edge; in the other, scrolled a little further,
  the row that straddles the top edge is not drawn at all -- black from
  the header down to "You", where the previous shot showed a paragraph
  -- so a row is culled as soon as its *top* leaves the viewport rather
  than when its *bottom* does. Suspects: the list's visible-range test
  (`iris/src/widget/list.rs`) comparing a row's top against the
  viewport top; the mask region for the transcript set from the
  window rather than from the area under the header; and the two-phase
  provisional/real draw noted in `03c6be8`'s header-duplicate
  investigation, which was never root-caused and has the same shape.
  Reproduce at layer 1 of the test rig: a headless screen with a row
  straddling the top edge must place that row, and a primitive above
  the header's bottom must be masked. Fix both with one rule: a row is
  drawn if any part of it intersects the viewport, and the viewport is
  the list's own region.
@@ -861,6 +861,58 @@ unspecified rather than getting them wrong:
  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):
@@ -895,3 +947,95 @@ When this lands, copy this entry into `IRIS.md` (newest first):
 > `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.
 ## Masks with a shape (decided 2026-09-07, not yet built)
 Iris, on the code block's scrolling: "the code block scrolling currently
 masks in an inner rectangle. Ideally masks should have a shape
 associated with them, rounded rectangle being one of them, and/or
 another widget you can select, so that the mask becomes the parent
 container with rounded edges. Make sure alpha works properly with it,
 eg. on the corners where alpha should be decreased / multiplied."
 **What exists.** `Mask` in `shader.wgsl`/`data.rs` is two `UiSpan`s and
 a `move_idx`; `fs_main` resolves it and does `color *= 0.0` outside the
 rectangle -- a hard cut on a pixel boundary. `Masked` (`widget/mask.rs`)
 sets the painter's mask to its own region. Separately, `draw_rounded_rect`
 already produces an anti-aliased rounded edge from
 `distance_from_rect(pos, center, corner, radius)` with a half-pixel
 `smoothstep`, and the border variant multiplies a second coverage in.
 **Design** (revised the same day on Iris's two corrections: hit-testing
 applies the shape too, and a mask should reference a primitive rather
 than carry a copy of its shape).
 1. **A mask is a reference to a primitive already drawn, plus how to
   use it.** `Mask { kind, idx, flags, parent }`: the primitive's
   binding (`RECT`, `TEXTURE`, `GLYPH`) and slot, flags (today one:
   *alpha only* -- take the primitive's coverage and ignore its colour,
   which is the default and the only mode until a need for another
   appears), and the enclosing mask's slot for nesting. The fragment
   stage evaluates the referenced primitive *at the masked pixel* --
   for a `Rect`, the same `draw_rounded_rect` coverage from the same
   SDF; for a texture or glyph, the sampled alpha -- and does
   `color.a *= coverage`. Nothing about the shape is copied: a rounded
   container's corner and its children's clipped corner are the same
   primitive's arithmetic, and a texture mask (an alpha image as the
   clip) works with no new shader path.
   What this needs from the data layout: evaluating a primitive at an
   arbitrary pixel means its placement (its spans and `move_idx`, today
   vertex attributes) has to be readable from a storage buffer in the
   fragment stage. If it is not already there, put it there once, for
   every primitive, rather than keeping a second copy for masks -- the
   vertex stage can read the same buffer. Textures: the shader binds one
   image at a time (see `masks_layout`'s comment on why an image's own
   bind group must not name the masks buffer), so a texture mask is
   limited to what the fragment can sample without a bind-group switch:
   the atlas, and the primitive's own bound image when the masked
   primitive is drawn in the same image's batch. Say so at the flag.
 2. **Nested masks chain and multiply, like moves.** `parent` walks up
   the chain, bounded like `resolve_move` (`MOVE_CHAIN_LIMIT`'s sibling;
   debug-assert on overflow and print the chain); coverages multiply,
   so a pixel inside two feathered corners is dimmed by both, which is
   what a compositor does and what "alpha should be multiplied" asks.
 3. **`.masked()` points the mask at the current widget's own
   primitives.** `Masked` stops describing a region: it records which
   primitive(s) the wrapping widget drew this frame (the painter knows
   -- it just allocated the slots) and sets the mask to reference them.
   So a rounded `Rect` widget's `.masked()` clips its children to
   itself by pointing at the rect it already draws; an image widget's
   `.masked()` clips to its alpha. No radius or shape argument exists to
   fall out of sync. When a widget draws more than one primitive (a
   bordered rect is one primitive; a card with a stripe is two), the
   mask references the *first* and the doc says so; a widget that wants
   another names it.
 4. **Hit-testing applies the shape.** A press is inside a masked
   subtree only if the mask's coverage at that point is above one half.
   For a `Rect` that is the same rounded-rect SDF evaluated on the CPU
   -- one function in the shared crate, with the WGSL a transliteration
   of it and a test that compares the two at a grid of points
   (`headless` renders to a buffer and reads back, or the Rust version
   is checked against the values the shader produced once and recorded).
   For a texture, the CPU needs the alpha: keep the alpha channel of an
   image used as a mask readable on the CPU (it was uploaded from CPU
   memory; keeping the alpha plane is a quarter of the image), and read
   it at the point. A masked corner that cannot be tapped and a masked
   corner that is not drawn are then the same corner.
 **Rejected.** A stencil buffer (a second pass per mask level and no
 anti-aliasing); the scissor rectangle (rectangles only, no alpha);
 rendering a masked subtree to an offscreen texture and compositing
 (a texture allocation per mask, every frame it scrolls, on the phone).
 **Pass conditions.** A headless test draws a rounded container with a
 masked child that overhangs all four sides and asserts the child's
 coverage at a corner pixel equals the container's own coverage there
 (same primitive evaluated, so exactly equal, not approximately); a
 nested-mask test asserts the product at a pixel inside both feathers; a
 texture-mask test clips a rect to an alpha image and asserts a
 transparent texel masks fully; a hit-test asserts a press in a
 container's clipped corner misses and one just inside the curve hits,
 and that the CPU SDF and the shader agree at a grid of points; a
 `run-headless.sh --phone` screenshot of a scrolled code block shows
 rounded corners with no square pixels poking out at the top and bottom
 of the scrolled content. Record the commands in RUST.md when it lands.
@@ -147,12 +147,37 @@ turn.
 Spawn: `claude -p --verbose --input-format stream-json --output-format
 stream-json --permission-mode <mode>` in the chosen working directory, plus
-`--model`. Wire-format notes are pinned against CLI 2.1.237 in
+`--model` and, where one has been chosen, `--effort`. Wire-format notes are
-`session/claude.rs`'s module doc: permissions need the hidden
+pinned against CLI 2.1.237 in `session/claude.rs`'s module doc: permissions
-`--permission-prompt-tool stdio` flag, AskUserQuestion answers ride
+need the hidden `--permission-prompt-tool stdio` flag, AskUserQuestion answers
-`updatedInput.answers` keyed by question text, and `set_model`/`interrupt`
+ride `updatedInput.answers` keyed by question text, and `set_model`/`interrupt`
 are control requests.
 **The thinking level is settled at launch** (added 2026-09-04, because it is
 the largest saving available on a long session: output is about an eighth of
 what a session costs and thinking is the bulk of output, against the ~1.5% that
 is prose). The CLI's only two setting control requests are `set_model` and
 `set_permission_mode` -- checked against the 2.1.258 binary -- so there is no
 way to ask a running process to think differently. `set_session_effort` is
 therefore shaped like `set_session_cwd` rather than like `set_session_model`:
 it records the level and **stops the process**, and the next message or Start
 launches one that has it. It lives in the session settings dialog beside the
 working directory for that reason, not on the session bar beside the model and
 the mode, which do take effect mid-turn. `None` is a level in its own right --
 the CLI's own default -- so the picker can return to it; a level this app named
 as the default instead would be this app choosing one.
 **What a new session starts at is `Config::default_effort`**, applied in
 `spawn_session` rather than filled in by the spawn screen, so it holds for an
 import and a bare API call as well. It is set by the spawn screen's own
 picker, whose label says so: one control, where new sessions are made, rather
 than a settings page for a single value. It is not on a provider, because
 providers are discovered and the next rediscovery would erase it, and not on
 the phone, because a second device would then spawn at a level nobody there
 chose. `GET`/`POST /defaults` carry it, as a struct rather than a bare value
 so the permission mode -- still hardcoded to `auto` on the spawn screen -- can
 move there without a second route.
 **`--resume` only ever runs when nothing else has that session open.** That
 is the rule behind the import refusal, the single `ClaudeDriver::launch`
 entry point, and the `Exited` correction below; two CLIs on one session file
@@ -169,10 +194,33 @@ deliberate and easy to undo by accident:
  when the process restarts. That leaves the Claude driver as the odd one
  out rather than this one — the CLI's memory is a cache in front of the same
  transcript. Resolve any inconsistency in this direction.
- **A llama session on an ssh host is refused.** The model is reached over
+- **A llama session runs on whatever machine its setup names** (2026-09-04,
-  HTTP and forwarding that port is not built, so refusing beats silently
+  the last of phase 5). A transport is "run this" plus "reach this port", and
-  talking to the wrong machine. A transport is "run this" plus "reach this
+  the second half is `Transport::reserve_port` — the port the server binds
-  port", and only the first half exists.
+  *there* and the port that reaches it *here*, the same number locally —
  carried by `Launch::reaching` onto the connection that already runs the
  command. `llama-server` binds loopback on the far machine, so nothing is
  served to its network. The far port is a guess from a range below the
  ephemeral one, because no portable way to ask a machine for a free port
  avoids racing the bind anyway; a collision is not silent, since the server
  fails to bind and the readiness poll reports what its log said.
 - **The model file lives on the machine that serves it** (2026-09-04). Each
  setup names its own models directory (`SshConfig::models_dir`, default
  `~/.local/share/ai-app/models` expanded *there*), and a spawn resolves the
  key on that machine — one round trip answering "at /abs/path" or "missing",
  so a model that is not there is refused at the spawn rather than becoming a
  server that never becomes ready. The spawn screen offers
  `GET /setups/{id}/models`, that machine's list, rather than `GET /models`,
  which is this backend's downloads. Downloading *to* another machine is
  deliberately not built: a multi-gigabyte transfer with no progress
  anywhere, and the file gets there however anything else on that machine
  did.
 - **The readiness poll watches the process, not only the port.** A model that
  will not load, a port already taken, a flag an older build does not know:
  all exit within a second and none will ever answer `/health`, so waiting
  out the 300s timeout turned the server's own account of the problem into
  "gave up". The failure carries the tail of `llama-server.log`, which on a
  remote session is the only copy anybody reading the phone can see.
 ### Models (2026-08-28)
@@ -203,6 +251,13 @@ deliberate and easy to undo by accident:
  A driver says what to run; something above it turns that into a process.
  Otherwise transport knowledge sits inside a translator whose job is a wire
  format, and every future driver has to remember to do the same.
 - **A forwarded launch gets a pty and every other one does not** (measured
  2026-09-04). Killing the ssh client ends a CLI because it closes the stdin
  that CLI is reading; `llama-server` never reads its stdin, so the same kill
  left it running on the far machine with the model loaded — one orphan per
  stopped session. With `-tt` the far side takes SIGHUP when the connection
  goes. Its log then arrives through a line discipline, which nothing parses.
  `-T` stays everywhere else, where a pty would rewrite the JSONL.
 - **`command -v` follows ssh's non-login PATH**, which is narrower than an
  interactive shell's, so a binary somewhere unusual is invisible to
  discovery. Point `command` at an absolute path.
@@ -499,6 +554,25 @@ rate-limited bucket). Poll at ≥180 s, only while a Claude session exists or
 the usage screen is open, and cache the last answer. It is undocumented, so
 `usage.rs` treats every field as optional and degrades rather than erroring.
 **Per provider, not per machine (2026-09-04).** A machine is not what is
 metered; the provider a session runs is. One machine offers echo, the Claude
 CLI and a local model side by side, and only the second spends anything — so
 pairing a session with a snapshot by machine alone drew the CLI's five-hour
 window under every echo session on it, a quota that session cannot spend. A
 session now names its meter (`usageProvider`, from
 `DriverKind::usage_provider`, which `usage::providers_for` reads too, so the
 two lists cannot disagree) and `GET /usage` is matched on machine *and*
 provider. `None` is a session that meters nothing, and the phone draws
 nothing at all for it — not a zero, and not "unknown".
 `DriverKind::Echo` names a meter of its own that exists only when a test has
 asked for one: `/usage` in an echo session sets an invented answer
 (`usage::Fixture`), and with none set there is no snapshot and no bar. That
 is what makes those screens' states reachable — a number near the top, a
 window between blocks with no reset time, a machine nobody logged into, one
 that could not be reached — without spending real quota to arrange them,
 which is why none of them had ever been looked at.
 **Per machine, not per backend (2026-08-29).** The credential store that
 matters is the one on the machine the session runs on, because that is the
 account being billed — and in the layout this aims at, `ai-server` is on the
@@ -522,6 +596,68 @@ always running. So absent means **not running**, and only a timestamp that
 arrives and cannot be parsed is unknown. `WindowEnd` in `ResetCountdown.kt`
 is the one rule both readers go through.
 ### Auto-resume (2026-09-05)
 **A session may pick itself back up when the account's usage limit lifts.**
 Off unless somebody switched that session to it, because it spends quota the
 moment quota exists and does so with nobody looking — that is not a thing a
 default may decide. It sends one message, `continue` unless another was
 typed, and then it is done; there is no retry loop around the conversation
 itself.
 **Running out of quota is a state, not an error.** `Event::LimitReached`
 carries the dialect's reset time where it gave one, and recognising it
 belongs to the driver — the Claude CLI ends the turn with `is_error` and
 `Claude AI usage limit reached|1788546972`, and nothing above the driver
 matches on a string. The transcript draws it as a divider, like a clear or a
 compaction: what a reader scrolling back wants from it is why the
 conversation stops at that line.
 **The schedule is a plan to ask, never a plan to send.** Every reset time
 available here is untrustworthy in the direction that matters: the dialect's
 is written when the turn fails, and the endpoint's moves when the window
 does. So the wait ends in a question to `usage.rs`, and only `ok` with no
 window at 100% sends anything. A window still spent reschedules to *its own*
 reset time — which is what makes a limit that lifts later than promised wait
 longer, and one that lifts sooner resume sooner. A meter that cannot be
 asked at all is a longer wait too, never a send: "we could not find out"
 must not be able to produce the same action as "there is room".
 Bounded, because something has to be: a day after the limit was hit the wait
 stops and says so in the session's own transcript. A machine that can never
 be asked would otherwise be retried for ever with nothing on screen saying
 so.
 The schedule is persisted on the session (`resume: Some(ScheduledResume)`),
 not held in memory: a five-hour window routinely outlasts a backend restart,
 and a wait forgotten across one is a session that silently never comes back.
 `resume.rs` is the top layer — it holds the manager and the monitor and
 neither holds it — which is what lets the decision be a pure function of a
 snapshot and a clock. The pump reports limits downward on a broadcast, for
 the reason `Shared` exists: the pump runs underneath the manager.
 **Exercised with echo, never with a real account.** `/limit [minutes]` in an
 echo session reports the same event a real driver does, and `/usage` sets
 what the meter answers — deliberately two commands, because the two
 disagreeing is the state the whole design is about. The loop was driven end
 to end that way on 2026-09-05: the wait moved from the dialect's two minutes
 to the meter's seven when the meter changed its mind, and the message went
 out on the first check after the meter came back under the limit.
 ### Subagents (2026-09-05)
 **A subagent is a second transcript owned by a session, in the same event
 model, with no process and no controls of its own.** Full design and wire
 shape in `SUBAGENTS.md`, kept separate because the app half is being built
 against it in parallel and it is the shared contract between the two. The
 one-paragraph reason: a session's Task-tool helpers already speak the common
 event model on the parent's own stdout (each line carrying
 `parent_tool_use_id`), so giving each one its own small transcript — same
 file format, same paging routes, same SSE stream, reused by addressing rather
 than by copying — costs a routing step in the translator and a registry
 (`session/subagent.rs`) rather than a second session type with a driver, a
 process and a config entry it does not need.
 ### HTTP surface
 **`routes.rs`'s module doc comment is the table.** REST for actions, one SSE
@@ -800,8 +936,9 @@ Noticed and deliberately not fixed, so they are not re-found from scratch.
 Phases 1–3 (the skeleton pipe, the full Claude driver, the usage screen) done
 2026-08-24. Phase 4 (llama.cpp: model browsing, downloads, and `llama-server`
-through its OpenAI-compatible endpoint) and phase 5 (ssh) done 2026-08-28.
+through its OpenAI-compatible endpoint) and phase 5 (ssh) done 2026-08-28,
-The file explorer and the transcript cache followed in September. What is
+except for the remote `llama-server` and its port forward, which landed
 2026-09-04. The file explorer and the transcript cache followed in September. What is
 left is real-phone/WireGuard bring-up, which is operational rather than code.
 Each phase ended runnable and verified against the real thing. The backend
@@ -0,0 +1,214 @@
 # Review: iris changes since 0e46293
 Scope: `git diff 0e46293..HEAD -- iris/ client-core/` (58 files, +5224/-226).
 Read-only review; no source changed. Ordered likely-bug, then invariant
 guards, then rules, then tests/docs.
 ## Likely bugs
 1. **`iris/transcript-ui/src/lib.rs:152-160` (`RowDiff::Rebuild` arm of
   `TranscriptScreen::apply`) never unregisters the rows it drops from
   `Selection`, so a stale `WeakWidget<TextEdit>` outlives the widget it
   points to and the next touch on *any* row panics.**
   `Selection::rows: BTreeMap<RowKey, WeakWidget<TextEdit>>` documents its
   own contract at `selection.rs:69-71`: "every addition here needs its
   removal ... called when `List` evicts the row." The `ReplaceLast` arm
   above it honours this (`lib.rs:143-145`, `self.selection.borrow_mut()
   .unregister(old_key)` when the key changes). The `Rebuild` arm calls
   `(self.list)(rsc).clear()` and rebuilds every row from `new_rows`, but
   never touches `self.selection` — any key present in `old_rows` and
   *absent* from `new_rows` (exactly what `group_tool_runs` regrouping two
   separate tool-call rows into one produces — see `diff_tests::
   a_tool_run_closing_and_joining_an_earlier_call_is_a_regroup_fallback`,
   which tests the diff decision but not `apply` itself) is left in
   `self.rows` pointing at a widget `List::clear()` just freed.
   `TextEditable::edit` (`iris/src/widget/text/edit.rs:582-587`) resolves
   that handle with `ui.widgets.get_mut(self).unwrap()` — an unconditional
   panic on the freed slot. `Selection::begin` (`selection.rs:88-101`)
   iterates *every* registered row (`w.edit(ui).deselect()`) on an
   ordinary fresh press, so the crash fires on the next tap anywhere in
   the transcript after a regroup, not only on a tap targeting the
   orphaned row.
   Fix: give `Selection` a way to reconcile against the row set that
   survived a rebuild (e.g. `Selection::retain(&self, keys: &BTreeSet<RowKey>)`
   removing everything else, called from the `Rebuild` arm before
   rebuilding), or simplest — call `self.selection.borrow_mut()` cleared
   the same way `List::clear()` clears the list, then let the rebuild's
   `push_row` calls re-`register` everything as they already do.
 ## Guarded invariants missing
 2. **`iris/src/widget/list.rs:751` (`List::place`) indexes/expects on
   `slot` with no assertion that it exists.** `slot_widget` (`:563-575`)
   panics via `.expect(...)` for a sentinel with no widget set, and does
   an unchecked `&self.items[s as usize]` for a real index — a bare
   "index out of bounds" with no context if `place` is ever reached with a
   stale slot. Every current caller happens to derive `slot` from
   `repair_anchor`/`prev_slot`/`next_slot`, which already check existence,
   but that invariant is enforced by convention across three call sites,
   not by the function that depends on it. Add
   `debug_assert!(self.slot_exists(slot), "place() called with a slot that doesn't exist: {slot:?}");`
   at the top of `place`.
 3. **`iris/src/widget/list.rs:426` (`List::fling`) and `sense.rs`'s
   `FlingCalculator::distance`/`duration`/`position_at` never check that
   the incoming velocity is finite.** A `NaN`/`inf` velocity (a
   `VelocityTracker::velocity()` divide-by-near-zero span, or a caller
   passing a raw device value straight through) propagates through
   `deceleration_for`'s `.ln()` silently — the fling either never settles
   (`settled_on_schedule` compares against a `NaN` `duration()`, which is
   always `false`) or jumps to `NaN` positions with nothing on screen
   saying why. Add `debug_assert!(velocity_px_per_s.is_finite())` in
   `List::fling` and `FlingCalculator::new`/`distance`.
 4. **`iris/src/sense.rs:592-604` (`VelocityTracker::velocity`) has no
   assertion that samples are chronological.** `add_sample` trusts its
   caller's `Instant` ordering; a caller that samples out of order (a
   restored/replayed gesture, a test) would silently produce a negative
   `span` handled only by the `span <= 0.0 => 0.0` catch-all, masking the
   bug that produced it rather than surfacing it. Add
   `debug_assert!(self.samples.back().is_none_or(|&(last, _)| at >= last))`
   in `add_sample`.
 5. **`iris/core/src/render/frame_report.rs:247-252` (`mark_phase`) has no
   assertion that phases are pushed in non-decreasing `start_index`
   order.** `phase_stats`'s slicing (`:274`, `idx >= phase.start_index &&
   idx < end_index`) silently produces an empty or nonsensical slice for
   an out-of-order phase rather than surfacing the misuse — cheap to add
   given `self.phases.last()` is already in scope:
   `debug_assert!(self.phases.last().is_none_or(|p| self.total_frames >= p.start_index));`
 ## Rules
 6. **Two mechanisms answer "what row selection points at, still valid?"**
   `Selection` relies on callers remembering to `unregister` (finding 1);
   `List` relies on callers deriving slots only from already-checked
   sources (finding 2). Both are the same class of problem — a derived
   handle that silently outlives what it points to — solved ad hoc twice
   rather than once. Not asking for a shared abstraction here, but the two
   should at minimum cross-reference each other's doc comment so the next
   caller who adds a third handle-into-`List`-rows type (the code rules'
   "a rule that governs a set belongs to the set") finds both existing
   examples.
 7. **`iris/android-app/src/bench_client.rs:224-225` (`battery_line`)
   calls `.min().unwrap()`/`.max().unwrap()` on `samples` guarded three
   lines above by `if samples.is_empty()`, which is fine — but the guard
   and the two unwraps are two statements apart with a `let mean = ...`
   in between reading the same slice; a future edit reordering those
   lines loses the guard's protection silently.** Low severity (this is
   the bench tool, not the app), but worth a one-line comment tying the
   unwraps back to the guard, or restructuring as
   `let (Some(min), Some(max)) = (samples.iter().min(), samples.iter().max())`
   pattern so the empty case can't be separated from the check by a future
   edit.
 ## Tests
 8. **No test exercises `TranscriptScreen::apply`'s `Rebuild` arm through
   `Selection`.** `lib.rs`'s `diff_tests` module (`:284-379`) tests only
   the pure `diff_rows` decision function, never `apply` itself wired to a
   real `Selection`; `selection.rs`'s own tests (`a_missed_press_start_
   recovers_on_the_next_pressing_frame`, `unregister_forgets_the_row_and_
   clears_a_matching_anchor`) never go through `apply`/`List::clear`
   either. This is exactly the gap that let finding 1 through: the two
   pieces (`apply`'s fallback, `Selection`'s registration contract) are
   each tested in isolation and never together. Add: build a
   `TranscriptScreen`, force a `RowDiff::Rebuild` (two adjacent tool-call
   rows regrouping, per the existing `diff_tests` case), then call
   `selected_text`/simulate a fresh press on a surviving row and assert no
   panic.
 9. **`iris/src/widget/list.rs`'s fling tests check total distance and the
   start/end clamp but not the speed profile in between.**
   `fling_moves_the_list_and_then_settles`/`fling_distance_is_positive_
   toward_the_end` only assert the fling started, moved in the right
   direction, and eventually stopped — none checks that
   `tick_fling`'s per-tick delta is *monotonically decreasing* once past
   the fling's peak (the property `fling_calculator_tests::position_at_
   is_monotonic_and_clamped_past_the_end` already checks one level down,
   for `FlingCalculator` alone, but never through `List::tick_fling`'s own
   `scroll`/`anchor.offset` accumulation). A regression that made
   `tick_fling` apply the *total* distance every tick instead of the
   incremental one, for instance, would still pass both existing tests
   (final position and direction are unaffected by how the interior ticks
   split it up) while being wildly wrong every intermediate frame.
 10. **`iris/src/widget/list.rs::replacing_the_last_row_stays_pinned_to_
    the_bottom` and its sibling test `replace_back`'s effect on the
    displayed row, never that the row it evicted is actually gone from
    `heights`/`extents`.** Both tests assert the *new* row's position;
    neither asserts `old.key` is absent from `list_ref.heights`/`extents`
    after the replace (the "stale primitive" class finding 1 is a
    production instance of). A cheap addition: assert
    `!list_ref.heights.contains_key(&old.key)` after `replace_back` in the
    existing test, since `old.key` is already returned to the test as
    `evicted`... (`lib.rs` calls it that way; the `list.rs` test would need
    to capture the key from `old` similarly.)
 ## Docs
 No missing `IRIS.md` entry found for a *public* API change in this diff —
 `List::fling`/`VelocityTracker`/`FlingCalculator`, `List::
 anchor_position_display`, `FrameReport::mark_phase`/`phase_stats`/
 `late_at_hz`, `UiRenderNode::new`'s `Result` change, `Len::dp`, and
 `List::replace_back`/`clear`/`TranscriptScreen::apply` all have entries.
 The `List::replace_back`/`clear`/`TranscriptScreen::apply` entry
 (`docs/IRIS.md:526`) predates this review's finding 1 and does not mention
 `Selection`'s registration contract at all — once finding 1 is fixed,
 that entry should gain a line noting what the fix requires of a caller
 that keeps its own row-keyed side table (the same shape `Selection` is),
 so the next such table doesn't reproduce the same gap.
 ## Fixed, 2026-09-06
 All ten findings addressed after the `DragGesture` merge (`selection.rs`
 was rewritten by that merge, but finding 1's shape and location were
 unchanged — `TranscriptScreen::apply`'s `Rebuild` arm, `iris/transcript-ui/
 src/lib.rs`).
 1. **Fixed.** `Selection::clear()` (`selection.rs`) drops `rows` and
   `anchor`, called from `apply`'s `Rebuild` arm right before
   `List::clear()` — `push_row` re-`register`s whatever survives as it
   rebuilds each row, the "simplest" fix option the finding named.
 2. **Fixed.** `debug_assert!(self.slot_exists(slot), ...)` at the top of
   `List::place` (`iris/src/widget/list.rs`).
 3. **Fixed.** `debug_assert!(velocity_px_per_s.is_finite())` in
   `List::fling`, and `debug_assert!(velocity.is_finite())` in
   `FlingCalculator::distance`/`duration` (`iris/src/sense.rs`).
   `position_at` calls both, so it inherits the guard rather than needing
   its own.
 4. **Fixed.** `debug_assert!` on chronological sample order in
   `VelocityTracker::add_sample` (`iris/src/sense.rs`).
 5. **Fixed.** `debug_assert!` on non-decreasing `start_index` in
   `FrameReport::mark_phase` (`iris/core/src/render/frame_report.rs`).
 6. **Fixed (doc cross-reference only, as asked).** `Selection::register`'s
   doc now points at `List::place`'s `slot_exists` assertion and vice
   versa isn't needed since finding 2's fix already cites this file in
   its own comment; both are grep-able on "docs/REVIEW-2026-09-06.md" and
   on each other's type names.
 7. **Fixed.** `bench_client.rs::battery_line` restructured to
   `let (Some(min), Some(max)) = (samples.iter().min(), samples.iter().max())`,
   so the empty-guard and the two lookups can no longer be separated by a
   future edit.
 8. **Fixed.** `transcript-ui`'s new `apply_tests::
   a_row_dropped_by_a_regroup_does_not_outlive_itself_in_selection`
   (`lib.rs`) builds a real `TranscriptScreen`, forces the same regroup
   shape `diff_tests` already covers at the pure-diff level, calls `apply`,
   and then `Selection::begin` on a surviving row — which panicked before
   fix 1, resolving a `WeakWidget` `List::clear()` had just freed.
 9. **Fixed.** `list.rs`'s new `tick_fling_applies_shrinking_incremental_
   deltas` flings toward the end from `jump_to_start` and asserts each
   tick's `extents[&0]` delta is no larger than the previous one — would
   fail against a `tick_fling` that applied the total spline distance
   every tick instead of the incremental slice, which the two pre-existing
   fling tests cannot catch.
 10. **Fixed.** `list.rs`'s new `replace_back_forgets_the_evicted_keys_own_
    height` replaces row 4 with a row keyed `100` (the two existing
    `replace_back` tests always reuse the same key, so neither actually
    exercises the removal) and asserts `heights` no longer contains the
    evicted key.
 Docs: `docs/IRIS.md`'s 2026-09-05 `List::replace_back`/`clear`/
 `TranscriptScreen::apply` entry now has a line on what the fix requires of
 a caller with its own row-keyed side table, naming `Selection` as the
 example and dating the fix.
 Verification run alongside the rest of this pass's checks: `cargo fmt
 --all`, `cargo clippy --workspace --all-targets`, `cargo test --workspace`
 from `iris/` — see docs/RUST.md's plan box for the pass/fail and any
 caveats from this same session.
@@ -33,3 +33,14 @@ one in place when it turns out to need a decision.
      that would work today, for Claude sessions, and it is the option that was
      not chosen.
 ## From Iris's phone log export, 2026-09-07 (Compose app)
 - [ ] **Crash on 2026-09-03 11:40, `IllegalArgumentException: Reversed
  range is not supported`** at `ToolInput.kt:200` (`highlighted`, inside
  `ToolInputView` -> `RawBlock` -> `ToolCard`). An `AnnotatedString`
  range was built with end before start while highlighting a tool
  input. Found in the per-package system log she exported; the tool
  input that triggered it is not in the log. Reproduce by fuzzing
  `highlighted` with inputs whose token boundaries collapse, and guard
  the range construction.
@@ -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)
 ```
@@ -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)
 ```
@@ -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)
 ```
@@ -0,0 +1,66 @@
 # 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.
 **Root-caused and fixed 2026-09-06** (commit `76b1f99`): the diagnosis in
 that sentence was right and the location was not -- `UiRenderState::
 draw_inner` read the `needs_redraw` mark without consuming it and skipped
 the branch that frees a redrawn widget's old primitives. docs/RUST.md's
 "Stale primitives, the phone's half" box has the full account, the guard
 (`orphaned_primitives`, `debug_assert`ed every frame) and the emulator run
 that exercises it.
 ```
 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)
 ```
@@ -150,6 +150,19 @@ pub enum Event {
    ToolEnd {
        id: String,
        output: String,
        /// Whether the tool reported that the call *failed*, from the
        /// CLI's own `is_error` on the `tool_result`.
        ///
        /// Added 2026-09-06 with the tool-call cards (RUST.md's P1b),
        /// because without it a result is the only thing a card has and a
        /// failed call is drawn as confidently as a successful one -- the
        /// missing state, not a wrong one. `#[serde(default)]` so a
        /// transcript written before this field, or a peer on an older
        /// build, reads back as "not reported to have failed" rather than
        /// failing to parse; that is the same claim the field's absence
        /// used to make implicitly.
        #[serde(default)]
        is_error: bool,
    },
    /// An image the session produced or was sent, saved under the session
    /// dir and referenced by id; the phone fetches it by URL.
@@ -305,6 +318,25 @@ pub enum Event {
    /// 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,
    },
@@ -721,6 +721,7 @@ name = "client-core"
 version = "0.1.0"
 dependencies = [
 "event-model",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
@@ -964,9 +965,9 @@ dependencies = [
 [[package]]
 name = "dlib"
-version = "0.5.2"
+version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "330c60081dcc4c72131f8eb70510f1ac07223e5d4163db481a04a0befcffa412"
+checksum = "ab8ecd87370524b461f8557c119c405552c396ed91fc0a8eec68679eab26f94a"
 dependencies = [
 "libloading",
 ]
@@ -1757,6 +1758,7 @@ dependencies = [
 "fxhash",
 "image",
 "parley",
 "pollster",
 "swash",
 "wgpu",
 ]
@@ -2873,9 +2875,9 @@ checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
 [[package]]
 name = "quick-xml"
-version = "0.38.4"
+version = "0.41.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b66c2058c55a409d601666cffe35f04333cf1013010882cec174a7467cd4e21c"
+checksum = "e660451e55124f798a69a5af3f49ccfbefbd41910eefd25caf2393e1f3473ec1"
 dependencies = [
 "memchr",
 ]
@@ -3056,6 +3058,15 @@ version = "0.8.52"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c6a884d2998352bb4daf0183589aec883f16a6da1f4dde84d8e2e9a5409a1ce"
 [[package]]
 name = "rig-input"
 version = "0.1.0"
 dependencies = [
 "iris",
 "wayland-client",
 "wayland-protocols-wlr",
 ]
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -3644,6 +3655,18 @@ dependencies = [
 "once_cell",
 ]
 [[package]]
 name = "transcript-fixture"
 version = "0.1.0"
 dependencies = [
 "client-core",
 "event-model",
 "iris",
 "serde_json",
 "transcript-ui",
 "winit",
 ]
 [[package]]
 name = "transcript-ui"
 version = "0.1.0"
@@ -3651,6 +3674,7 @@ dependencies = [
 "client-core",
 "event-model",
 "iris",
 "log",
 "pulldown-cmark",
 ]
@@ -3891,9 +3915,9 @@ dependencies = [
 [[package]]
 name = "wayland-backend"
-version = "0.3.12"
+version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fee64194ccd96bf648f42a65a7e589547096dfa702f7cadef84347b66ad164f9"
+checksum = "38a91b4eaddff87b1cd1074985e3713da4af2c49742d1b356b2c01670a67a078"
 dependencies = [
 "cc",
 "downcast-rs",
@@ -3905,9 +3929,9 @@ dependencies = [
 [[package]]
 name = "wayland-client"
-version = "0.31.12"
+version = "0.31.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8e6faa537fbb6c186cb9f1d41f2f811a4120d1b57ec61f50da451a0c5122bec"
+checksum = "e3c36a0f861ad76d0901f2800b46321410d9f73f2ea88aac0650d86c32688073"
 dependencies = [
 "bitflags 2.10.0",
 "rustix 1.1.3",
@@ -3939,9 +3963,9 @@ dependencies = [
 [[package]]
 name = "wayland-protocols"
-version = "0.32.10"
+version = "0.32.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baeda9ffbcfc8cd6ddaade385eaf2393bd2115a69523c735f12242353c3df4f3"
+checksum = "23d0c813de3daa2ed6520af85a3bd49b0e722a3078506899aa9686fea58dc4b6"
 dependencies = [
 "bitflags 2.10.0",
 "wayland-backend",
@@ -3964,9 +3988,9 @@ dependencies = [
 [[package]]
 name = "wayland-protocols-wlr"
-version = "0.3.10"
+version = "0.3.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e9597cdf02cf0c34cd5823786dce6b5ae8598f05c2daf5621b6e178d4f7345f3"
+checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234"
 dependencies = [
 "bitflags 2.10.0",
 "wayland-backend",
@@ -3977,9 +4001,9 @@ dependencies = [
 [[package]]
 name = "wayland-scanner"
-version = "0.31.8"
+version = "0.31.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5423e94b6a63e68e439803a3e153a9252d5ead12fd853334e2ad33997e3889e3"
+checksum = "338e30461b3a2b67d70eb30a6d89f8e0c93a833e07d2ae89085cd070c4a00ac0"
 dependencies = [
 "proc-macro2",
 "quick-xml",
@@ -3988,9 +4012,9 @@ dependencies = [
 [[package]]
 name = "wayland-sys"
-version = "0.31.8"
+version = "0.31.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e6dbfc3ac5ef974c92a2235805cc0114033018ae1290a72e474aa8b28cbbdfd"
+checksum = "d8eab23fefc9e41f8e841df4a9c707e8a8c4ed26e944ef69297184de2785e3be"
 dependencies = [
 "dlib",
 "log",
@@ -15,6 +15,11 @@ wgpu = { workspace = true }
 image = { workspace = true }
 accesskit = { workspace = true }
 tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] }
 # For diagnostics visible through android_logger (or whatever logger the
 # app crate installs) -- this crate never installs one itself. Not in the
 # android-only block below any more: the lines that matter most are in
 # shared widget code, which the host backend compiles too.
 log = "0.4.28"
 # 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
@@ -53,9 +58,20 @@ accesskit_android = "0.8.0"
 # 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.
+[features]
-log = "0.4.28"
+# 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). Read by `android/render.rs` and, so the GLES path can be
 # reproduced on a machine with a real GPU rather than only in the emulator,
 # by `default/render.rs`:
 #     ./run-headless.sh transcript --shot /tmp/x.png -- -p transcript-ui \
 #         --features iris/force-gles
 force-gles = []
 [dev-dependencies]
 tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread", "time"] }
@@ -73,13 +89,21 @@ name = "message_list"
 harness = false
 [workspace]
-members = ["core", "macro", "tabs-ui", "transcript-ui", "desktop-app"]
+members = [
    "core",
    "macro",
    "tabs-ui",
    "transcript-ui",
    "transcript-fixture",
    "rig-input",
    "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`.
+# -t x86_64 -P 29 build`.
 exclude = ["android-app"]
 [workspace.package]
@@ -558,6 +558,12 @@ dependencies = [
 "arrayvec",
 ]
 [[package]]
 name = "base64"
 version = "0.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
 [[package]]
 name = "bit-set"
 version = "0.8.0"
@@ -734,6 +740,17 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
 [[package]]
 name = "client-core"
 version = "0.1.0"
 dependencies = [
 "event-model",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
 ]
 [[package]]
 name = "clipboard-win"
 version = "5.4.1"
@@ -779,6 +796,35 @@ dependencies = [
 "crossbeam-utils",
 ]
 [[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 = "core-foundation"
 version = "0.9.4"
@@ -886,6 +932,12 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f"
 [[package]]
 name = "deranged"
 version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 [[package]]
 name = "dispatch"
 version = "0.2.0"
@@ -1048,6 +1100,14 @@ dependencies = [
 "pin-project-lite",
 ]
 [[package]]
 name = "event-model"
 version = "0.1.0"
 dependencies = [
 "serde",
 "serde_json",
 ]
 [[package]]
 name = "exr"
 version = "1.74.2"
@@ -1179,6 +1239,15 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
 [[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 = "futures-core"
 version = "0.3.34"
@@ -1253,6 +1322,26 @@ dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "getopts"
 version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
 dependencies = [
 "unicode-width",
 ]
 [[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.3.4"
@@ -1423,6 +1512,22 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dfa686283ad6dd069f105e5ab091b04c62850d3e4cf5d67debad1933f55023df"
 [[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"
@@ -1551,6 +1656,27 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae293c039020f9ec10710af98d29ce6aa2051486638b49c9a6409f3b4a9e98ad"
 [[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 = "image"
 version = "0.25.10"
@@ -1640,9 +1766,16 @@ version = "0.1.0"
 dependencies = [
 "android-view",
 "android_logger",
 "client-core",
 "event-model",
 "iris",
 "libc",
 "log",
 "serde_json",
 "tabs-ui",
 "tokio",
 "transcript-fixture",
 "transcript-ui",
 ]
 [[package]]
@@ -1654,6 +1787,7 @@ dependencies = [
 "fxhash",
 "image",
 "parley",
 "pollster",
 "swash",
 "wgpu",
 ]
@@ -1676,6 +1810,12 @@ dependencies = [
 "either",
 ]
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "jni"
 version = "0.21.1"
@@ -2096,6 +2236,12 @@ dependencies = [
 "num-traits",
 ]
 [[package]]
 name = "num-conv"
 version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 [[package]]
 name = "num-derive"
 version = "0.4.2"
@@ -2744,6 +2890,12 @@ dependencies = [
 "zerovec",
 ]
 [[package]]
 name = "powerfmt"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
@@ -2796,6 +2948,25 @@ dependencies = [
 "syn 2.0.119",
 ]
 [[package]]
 name = "pulldown-cmark"
 version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9f068eba8e7071c5f9511831b44f32c740d5adf574e990f946ddb53db2f314e"
 dependencies = [
 "bitflags 2.13.1",
 "getopts",
 "memchr",
 "pulldown-cmark-escape",
 "unicase",
 ]
 [[package]]
 name = "pulldown-cmark-escape"
 version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
 [[package]]
 name = "pulp"
 version = "0.22.3"
@@ -3075,6 +3246,20 @@ version = "0.8.53"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
 [[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 = "roxmltree"
 version = "0.21.1"
@@ -3125,6 +3310,41 @@ dependencies = [
 "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 = "rustversion"
 version = "1.0.23"
@@ -3207,6 +3427,19 @@ dependencies = [
 "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 = "serde_repr"
 version = "0.1.21"
@@ -3363,6 +3596,12 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6637bab7722d379c8b41ba849228d680cc12d0a45ba1fa2b48f2a30577a06731"
 [[package]]
 name = "subtle"
 version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 [[package]]
 name = "swash"
 version = "0.2.10"
@@ -3490,6 +3729,36 @@ dependencies = [
 "zune-jpeg",
 ]
 [[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 = "tiny-skia"
 version = "0.11.4"
@@ -3596,6 +3865,28 @@ dependencies = [
 "once_cell",
 ]
 [[package]]
 name = "transcript-fixture"
 version = "0.1.0"
 dependencies = [
 "client-core",
 "event-model",
 "iris",
 "serde_json",
 "transcript-ui",
 ]
 [[package]]
 name = "transcript-ui"
 version = "0.1.0"
 dependencies = [
 "client-core",
 "event-model",
 "iris",
 "log",
 "pulldown-cmark",
 ]
 [[package]]
 name = "tree_magic_mini"
 version = "3.2.2"
@@ -3634,6 +3925,12 @@ dependencies = [
 "keyboard-types",
 ]
 [[package]]
 name = "unicase"
 version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -3652,6 +3949,62 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 [[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"
@@ -3696,6 +4049,12 @@ dependencies = [
 "winapi-util",
 ]
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 [[package]]
 name = "wasip2"
 version = "1.0.4+wasi-0.2.12"
@@ -3889,6 +4248,15 @@ dependencies = [
 "wasm-bindgen",
 ]
 [[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 = "weezl"
 version = "0.1.12"
@@ -4748,6 +5116,12 @@ dependencies = [
 "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"
@@ -4789,6 +5163,12 @@ 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"
 [[package]]
 name = "zune-core"
 version = "0.5.3"
@@ -17,10 +17,59 @@ crate-type = ["cdylib"]
 [dependencies]
 iris = { path = "../" }
 tabs-ui = { path = "../tabs-ui" }
 android-view = { git = "https://github.com/rust-mobile/android-view.git", rev = "bec6c62a96cef8239b0fd7fedeef9b184d02e3a1" }
 android_logger = "0.15.0"
 log = "0.4.28"
 # `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 }
 # P0's bench build only: the fixture and the folded screen both bench
 # clients open, shared with the headless harness and the desktop window
 # (docs/RUST.md's "Three test layers").
 transcript-fixture = { path = "../transcript-fixture", 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:transcript-fixture", "dep:libc", "dep:tokio"]
 [profile.release]
 panic = "abort"
@@ -13,15 +13,74 @@ android {
    defaultConfig {
        applicationId = "dev.iris.android.demo"
-        minSdk = 26
+        // 29, not 26: `iris::android::view`'s touch handler dates each
-        targetSdk = 34
+        // sample with `MotionEvent.getEventTimeNanos` and
        // `getHistoricalEventTimeNanos`, both API 29, and a missing JNI
        // method there is a hard crash on the first touch rather than a
        // degraded fling. Raised deliberately rather than guarded at
        // runtime: nothing this app is built for runs below 29, and an
        // untested fallback path is its own defect. `build-apk.sh`'s
        // `cargo ndk -P` is kept at the same number.
        minSdk = 29
        // 37, matching `compileSdk` and the Compose app in `app/` -- which
        // is the one part of this that is measured rather than reasoned:
        // that app targets 37 and its keyboard does push the transcript up
        // on Iris's phone, and this one targeted 34 and does not
        // (2026-09-07). The emulator here is API 36 and the push-up works
        // there at either target, so the target is the only difference the
        // two devices do not share.
        //
        // The mechanism, stated as the reading it is: below targetSdk 35
        // a window keeps the legacy behaviour, where `adjustResize` shrinks
        // the window for the IME and `getInsets(ime()).bottom` therefore
        // measures the overlap with an already-shrunk window -- zero, with
        // nothing left to push up. `MainActivity`'s
        // `setDecorFitsSystemWindows(false)` opts out of that, and on API
        // 36 it still takes; Android 16 deprecated it and Android 17 is
        // where it appears not to. At 35+ edge-to-edge is not opt-in, so
        // the app is handed the real overlap without relying on a
        // deprecated call. If the phone still reports `ime_bottom=0` with
        // a nonzero `dispatches` in the Diagnostics pane, this reading was
        // wrong and the `WindowInsetsAnimation.Callback` in
        // `MainActivity` is the other half to look at.
        targetSdk = 37
        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 {
@@ -1,6 +1,15 @@
 <?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"
@@ -1,6 +1,17 @@
 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;
@@ -16,7 +27,7 @@ public final class IrisView extends RustView {
    protected native long newViewPeer(Context context);
    native void applyWindowInsetsNative(
-            long peer, int left, int top, int right, int bottom, int imeBottom);
+            long peer, int left, int top, int right, int bottom, int imeBottom, int imeVisible);
    native void unregisterInsetsNative(long peer);
@@ -24,8 +35,9 @@ public final class IrisView extends RustView {
        super(context);
    }
-    void applyWindowInsets(int left, int top, int right, int bottom, int imeBottom) {
+    void applyWindowInsets(
-        applyWindowInsetsNative(mViewPeer, left, top, right, bottom, imeBottom);
+            int left, int top, int right, int bottom, int imeBottom, int imeVisible) {
        applyWindowInsetsNative(mViewPeer, left, top, right, bottom, imeBottom, imeVisible);
    }
    @Override
@@ -33,4 +45,112 @@ public final class IrisView extends RustView {
        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));
        });
    }
 }
@@ -4,7 +4,9 @@ import android.app.Activity;
 import android.os.Build;
 import android.os.Bundle;
 import android.view.WindowInsets;
 import android.view.WindowInsetsAnimation;
 import android.widget.FrameLayout;
 import java.util.List;
 /**
 * The android-view backend's demo activity (RUST.md's I2): one IrisView
@@ -31,17 +33,107 @@ public final class MainActivity extends Activity {
        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);
        }
        // **The keyboard's height arrives twice, over two different
        // paths, and the phone needs the second one** (Iris, 2026-09-07:
        // the emulator pushed the composer up and her Pixel did not).
        // `setOnApplyWindowInsetsListener` is the platform's *settled*
        // answer; `WindowInsetsAnimation.Callback` is the running one, and
        // an IME that animates in delivers every intermediate height
        // through the callback with the static dispatch arriving only at
        // the ends -- on some devices only at `onEnd`. Registering both
        // means neither device depends on the other's timing, and it is
        // also what makes the push-up *animate* with the keyboard rather
        // than jump when it lands.
        //
        // The two do not disagree, because they are the same call with the
        // same numbers read out of whichever `WindowInsets` is current.
        // `DISPATCH_MODE_CONTINUE_ON_SUBTREE` so this view consuming
        // nothing keeps the ordinary dispatch running underneath.
        // `onEnd` re-reads the root's insets rather than trusting the last
        // `onProgress`: an animation interrupted mid-flight never delivers
        // its final frame, which is exactly the fault the Compose app hit
        // (AGENTS.md, "the composer can get stuck floating above the
        // bottom of the screen").
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            view.setWindowInsetsAnimationCallback(new WindowInsetsAnimation.Callback(
                    WindowInsetsAnimation.Callback.DISPATCH_MODE_CONTINUE_ON_SUBTREE) {
                @Override
                public WindowInsets onProgress(
                        WindowInsets insets, List<WindowInsetsAnimation> running) {
                    sendInsets(view, insets);
                    return insets;
                }
                @Override
                public void onEnd(WindowInsetsAnimation animation) {
                    WindowInsets settled = view.getRootWindowInsets();
                    if (settled != null) {
                        sendInsets(view, settled);
                    }
                }
            });
        }
        view.setOnApplyWindowInsetsListener((v, insets) -> {
            sendInsets((IrisView) v, insets);
            return insets;
        });
    }
    /** Read one `WindowInsets` and hand it to the Rust side. The only
     * place that reads these fields, so the static dispatch and the
     * animation callback above cannot come to report different things. */
    private static void sendInsets(IrisView view, WindowInsets insets) {
        int left = insets.getSystemWindowInsetLeft();
        int top = insets.getSystemWindowInsetTop();
        int right = insets.getSystemWindowInsetRight();
        int bottom = insets.getSystemWindowInsetBottom();
        // **Two separate answers, because they are separate questions**
        // (Iris's phone, 2026-09-06: "message box does not push up the
        // scroll area"). `isVisible(ime())` says whether the keyboard is
        // up; `getInsets(ime()).bottom` says how tall it is. An earlier
        // pass sent the boolean *as* the height (0 or 1) because under
        // plain `adjustResize` the window shrinks to make room and the ime
        // inset therefore measures a zero overlap by construction -- true
        // then, and no longer true now that this is an edge-to-edge window
        // (`targetSdk` 35+, plus the `setDecorFitsSystemWindows` call
        // above for the devices below that), which is exactly the case
        // where the system stops resizing and hands the app the real
        // overlap instead. Sending 1 for it left the Rust side padding the
        // composer by one physical pixel, so the keyboard covered the bar
        // and the transcript alike.
        //
        // The visibility is still sent in its own right rather than
        // inferred from `height > 0`: the two disagree during the
        // keyboard's slide-in and -out (visible, height still climbing),
        // and "is the IME up" drives the bench's own state machine
        // (`bench_client.rs`'s `ime_state`) where a half-open frame
        // reading as "closed" is a miscount.
        int imeBottom = 0;
        int imeVisible = 0;
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            imeBottom = insets.getInsets(WindowInsets.Type.ime()).bottom;
            imeVisible = insets.isVisible(WindowInsets.Type.ime()) ? 1 : 0;
        }
-            ((IrisView) v).applyWindowInsets(left, top, right, bottom, imeBottom);
+        view.applyWindowInsets(left, top, right, bottom, imeBottom, imeVisible);
            return insets;
        });
    }
 }
@@ -0,0 +1,95 @@
 #!/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"
 # Only the ABI asked for goes into the APK. cargo ndk adds its output beside
 # whatever earlier builds left here, and Gradle packages every directory it
 # finds -- a debug x86_64 emulator build left behind made an arm64 "release"
 # 339 MB on 2026-09-06.
 rm -rf app/src/main/jniLibs
 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 29 -o app/src/main/jniLibs/ build --release --features "$FEATURES"
 else
    cargo ndk -t "$ABI" -P 29 -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"
@@ -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}")
    })
 }
@@ -0,0 +1,74 @@
 #!/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.
 # The report's own first line, not the bare "iris bench report:" prefix:
 # `copy_report` logs that prefix too ("nothing to copy -- run the benchmark
 # first", which the app emits at startup), so polling for the prefix
 # returned instantly and the script printed a report that was never run.
 REPORT_LINE="iris bench report: iris bench report"
 i=0
 while [ "$i" -lt 260 ]; do
    LINE=$(adb -s "$SERIAL" logcat -d -s iris-android-app:I 2>/dev/null | grep "$REPORT_LINE" || 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 "$REPORT_LINE"
@@ -0,0 +1,999 @@
 //! 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. Reading that fixture
 //! and folding it into a screen is **`transcript-fixture`'s** job, not
 //! this file's -- the same crate the headless harness and the
 //! phone-shaped desktop window open, so all three measure one screen
 //! (AGENTS.md's sharing rule; moved out of here 2026-09-07). The tail is
 //! 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};
 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};
 /// 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;
 /// How much of the screen a *filled* benchmark report may take before it
 /// scrolls instead of growing -- roughly a third of a phone screen, the
 /// share the pane used to reserve unconditionally. An empty report takes
 /// nothing at all; see `new`'s comment at the tree it is used in.
 const REPORT_MAX_HEIGHT_DP: f32 = 260.0;
 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
    }
 }
 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;
    // `min`/`max` are guarded by the `is_empty` check above, three lines
    // up -- pairing the `Option` unwraps with the emptiness check right
    // here (rather than two statements apart, with `mean` in between
    // reading the same slice) is what keeps a future reorder from
    // separating the guard from what it protects (docs/
    // REVIEW-2026-09-06.md finding 7).
    let (Some(min), Some(max)) = (samples.iter().min(), samples.iter().max()) else {
        unreachable!("samples is non-empty, checked above");
    };
    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);
        // The report pane is sized to whatever report it is holding, not
        // to a share of the window: `rest(1)` here reserved a third of
        // the screen for an *empty* `TextEdit` at every launch, which is
        // what Iris's 2026-09-06 11:39 phone report described as "the app
        // does not start with keyboard spacing correct" -- the composer
        // two thirds down with black below it, nothing to do with the IME
        // inset (measured: `iris insets:` reports bottom=63 ime_bottom=0
        // at launch, while the `Message` field's own box sat 789px above
        // the bottom of a 2282px surface -- exactly this pane's third).
        // Capped and scrollable so a long report cannot take the screen
        // back over, the same idiom `composer.rs` uses for the field.
        // Above the transcript, not below it: the report is what the
        // header's own "Run benchmark" button produces (UI_RULES.md --
        // results appear where the action was started), and a pane under
        // the composer would eat the navigation-bar clearance
        // `set_bottom_inset` gives it.
        let tree = (
            top_bar,
            report_display
                .pad(dp(8))
                .max_height(dp(REPORT_MAX_HEIGHT_DP)),
            content.height(rest(1)),
        )
            .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,
        };
        match transcript_fixture::build_screen(rsc) {
            Ok((opened, tree)) => {
                client.items = opened.items;
                client.stream_tail = opened.stream_tail;
                (client.content)(rsc).set(tree);
                client.screen = Some(opened.screen);
            }
            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));
        }
        // The platform's own answer, not `ime_bottom > 0.0` -- see
        // `iris::android::WindowInsets::ime_bottom`. The height is still
        // climbing while the keyboard slides in, so a frame or two of a
        // real opening reads as "closed" when the boolean is inferred from
        // it, and `shown_events`/`hidden_events` below count transitions.
        let ime_visible = insets.ime_visible;
        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 (screen, tree) = transcript_ui::build_tree(rsc, transcript_fixture::rows(&self.items));
        (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 report = self.diagnostics_text(rsc);
        self.report_display.edit(rsc).set(&report);
        self.last_report = Some(report);
    }
    /// The diagnostics report as text, with no side effect on what is on
    /// screen -- shared by the `Diagnostics` button (which shows it) and
    /// the keyboard-open capture (which only logs it), so the two can
    /// never drift into reporting different things.
    fn diagnostics_text(&self, rsc: &mut Rsc) -> String {
        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 renderer = match &self.android_state().renderer {
            Some(renderer) => renderer.diagnostics_report(&font, &frame_report),
            None => "iris diagnostics: no renderer yet (no surface)".to_string(),
        };
        // The insets line goes in the pane, not just the log: Iris has no
        // logcat on her phone, and "the keyboard does not push the
        // composer up" cannot be told from "the listener never fired"
        // without it (`AndroidUiState::insets_report`).
        format!("{renderer}\n{}", self.android_state().insets_report())
    }
    /// The keyboard's own diagnostics capture -- see `on_insets_changed`'s
    /// doc comment. **Logged only.** It used to also copy the report to
    /// the clipboard unprompted and put it in the shell's overlay view,
    /// from when the keyboard-inset callback was not firing at all and a
    /// report could not be got off the phone any other way. Both are gone
    /// as of 2026-09-06: the callback fires reliably now (edge-to-edge,
    /// `MainActivity.java`), and the overlay covered the whole screen on
    /// *every* keyboard open with its own Copy/Close buttons underneath
    /// the keyboard, so it could not be dismissed -- an interruption for
    /// something nobody asked for, over an app you are trying to type
    /// into (UI_RULES.md). The named `Diagnostics` button still shows the
    /// same text on demand, and `iris surface:`/`iris insets:` (view.rs)
    /// carry the lifecycle a `logcat` pull actually needs.
    fn capture_keyboard_diagnostics(&mut self, rsc: &mut Rsc) {
        let report = self.diagnostics_text(rsc);
        log::info!("iris keyboard diagnostics:\n{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);
    }
 }
@@ -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(())
    }
 }
@@ -1,5 +1,5 @@
-//! The android-view demo app: iris's `tabs` widget tree (`tabs_ui::build`,
+//! The android-view demo app: by default, iris's `tabs` widget tree
-//! shared with the winit example) running through
+//! (`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.
 //!
@@ -9,6 +9,32 @@
 //! 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,
@@ -18,19 +44,30 @@ use android_view::{
    },
    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
@@ -40,6 +77,7 @@ impl HasAndroidUiState for Client {
    }
 }
 #[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
@@ -61,12 +99,19 @@ impl AndroidAppState for Client {
    }
 }
 #[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::<Client>(env, view, context)
+    iris::android::new_peer::<ActiveClient>(env, view, context)
 }
 /// # Safety
@@ -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, &[]);
            }
        });
    }
 }
@@ -0,0 +1,152 @@
 #!/usr/bin/env python3
 """AOSP's fling spline, transcribed independently of the Rust port.
 This exists so the numbers in `sense.rs`'s `the_spline_matches_aosps_own_table`
 and `a_flick_decelerates_the_way_aosp_says_it_does` are not the Rust code
 grading its own homework. Every test iris's fling had before 2026-09-07
 compared the curve with itself -- monotonic, signed, integrates to the closed
 form -- and all of them passed while `distance_fraction(t)` was returning
 exactly `t` (see `android_fling_spline`'s doc comment). Numbers checked into a
 test have to come from somewhere else, and this is the somewhere else.
 Transcribed by hand from, and only from:
  * frameworks/base `core/java/android/widget/OverScroller.java`,
    `SplineOverScroller`'s static initialiser, `getSplineDeceleration`,
    `getSplineFlingDistance`, `getSplineFlingDuration` and `update`.
  * androidx.compose.animation:animation:1.12.0 `SplineBasedDecay.kt`
    (`computeSplineInfo`, `AndroidFlingSpline.flingPosition`) and
    `FlingCalculator.kt` (`computeDeceleration`, `flingDistance`,
    `flingDuration`, `FlingInfo.position`/`velocity`). The two agree line for
    line, which is why iris ports one curve rather than two.
 Run it with no arguments; it prints the table entries and the (velocity,
 density, t) points the Rust tests assert on.
 """
 NB_SAMPLES = 100
 INFLEXION = 0.35
 START_TENSION = 0.5
 END_TENSION = 1.0
 P1 = START_TENSION * INFLEXION
 P2 = 1.0 - END_TENSION * (1.0 - INFLEXION)
 # ViewConfiguration.getScrollFriction(), and SplineOverScroller's own
 # "look and feel tuning" constant -- a different number in a different place
 # of the same formula, which is the pair iris got the wrong way round once.
 SCROLL_FRICTION = 0.015
 TUNING = 0.84
 GRAVITY_EARTH = 9.80665
 INCHES_PER_METER = 39.37
 import math
 DECELERATION_RATE = math.log(0.78) / math.log(0.9)
 def spline_positions():
    """SPLINE_POSITION: distance fraction at each of 101 even time steps."""
    position = [0.0] * (NB_SAMPLES + 1)
    x_min = 0.0
    for i in range(NB_SAMPLES):
        alpha = i / NB_SAMPLES
        x_max = 1.0
        while True:
            x = x_min + (x_max - x_min) / 2.0
            coef = 3.0 * x * (1.0 - x)
            # Solved on the P1/P2 curve...
            tx = coef * ((1.0 - x) * P1 + x * P2) + x * x * x
            if abs(tx - alpha) < 1e-5:
                break
            if tx > alpha:
                x_max = x
            else:
                x_min = x
        # ...and sampled on the tension curve.
        position[i] = coef * ((1.0 - x) * START_TENSION + x * END_TENSION) + x * x * x
    position[NB_SAMPLES] = 1.0
    return position
 POSITION = spline_positions()
 def fling_sample(t):
    """(distance fraction, velocity fraction) at time fraction `t`."""
    t = min(max(t, 0.0), 1.0)
    index = int(t * NB_SAMPLES)
    if index >= NB_SAMPLES:
        return 1.0, 0.0
    t_inf = index / NB_SAMPLES
    t_sup = (index + 1) / NB_SAMPLES
    velocity_coef = (POSITION[index + 1] - POSITION[index]) / (t_sup - t_inf)
    return POSITION[index] + (t - t_inf) * velocity_coef, velocity_coef
 def physical_coefficient(density):
    return GRAVITY_EARTH * INCHES_PER_METER * density * 160.0 * TUNING
 def deceleration(velocity, density):
    return math.log(
        INFLEXION * abs(velocity) / (SCROLL_FRICTION * physical_coefficient(density))
    )
 def fling_distance(velocity, density):
    l = deceleration(velocity, density)
    return (
        SCROLL_FRICTION
        * physical_coefficient(density)
        * math.exp(DECELERATION_RATE / (DECELERATION_RATE - 1.0) * l)
    )
 def fling_duration_s(velocity, density):
    l = deceleration(velocity, density)
    return math.exp(l / (DECELERATION_RATE - 1.0))
 def position_at(velocity, density, t_seconds):
    d = fling_duration_s(velocity, density)
    return fling_distance(velocity, density) * fling_sample(t_seconds / d)[0]
 def velocity_at(velocity, density, t_seconds):
    d = fling_duration_s(velocity, density)
    return fling_sample(t_seconds / d)[1] * fling_distance(velocity, density) / d
 if __name__ == "__main__":
    print("SPLINE_POSITION at a few indices (index: value)")
    for i in (0, 1, 10, 25, 50, 75, 99, 100):
        print(f"  {i:3}: {POSITION[i]:.6f}")
    print()
    print("distance/velocity fraction at time fractions")
    for t in (0.0, 0.1, 0.25, 0.5, 0.75, 0.9, 1.0):
        d, v = fling_sample(t)
        print(f"  t={t:<5} distance={d:.6f} velocity={v:.6f}")
    print()
    # 2.55 is Iris's Pixel 9 Pro XL (docs/bench/iris-phone-v2-2026-09-06.md);
    # 2.75 is this checkout's emulator.
    for density in (2.55, 2.75):
        for velocity in (5000.0, 11064.0):
            dur = fling_duration_s(velocity, density)
            print(
                f"density={density} v={velocity}: "
                f"distance={fling_distance(velocity, density):.3f}px "
                f"duration={dur:.4f}s"
            )
            # Deliberately not round fractions. The velocity coefficient is
            # piecewise *constant* across each of the 100 samples, so it
            # steps at t = k/100 and a test asserting on 0.75 is asserting
            # on which side of a discontinuity the last float landed --
            # which is genuinely different between Python and Rust and says
            # nothing about the curve.
            for frac in (0.125, 0.335, 0.505, 0.755):
                t = frac * dur
                print(
                    f"    t={frac:>4} of duration ({t:.4f}s): "
                    f"pos={position_at(velocity, density, t):.3f}px "
                    f"vel={velocity_at(velocity, density, t):.3f}px/s"
                )
@@ -142,7 +142,7 @@ fn bench_first_frame(n: usize) {
    let start = Instant::now();
    render.update(&root, &mut rsc);
    let elapsed = start.elapsed();
-    let (draws, rewrites, moves) = render.take_counters();
+    let (draws, rewrites, moves, _shapes) = render.take_counters();
    report(
        &format!("(a) first frame, N={n}"),
        elapsed,
@@ -177,7 +177,7 @@ fn bench_scroll(n: usize, ticks: usize) {
        let start = Instant::now();
        render.update(&root, &mut rsc);
        total += start.elapsed();
-        let (draws, rewrites, moves) = render.take_counters();
+        let (draws, rewrites, moves, _shapes) = render.take_counters();
        total_draws += draws;
        total_rewrites += rewrites;
        total_moves += moves;
@@ -245,7 +245,7 @@ fn bench_input_grows(n: usize, lines: usize) {
        let start = Instant::now();
        render.update(&root, &mut rsc);
        total += start.elapsed();
-        let (draws, rewrites, moves) = render.take_counters();
+        let (draws, rewrites, moves, _shapes) = render.take_counters();
        total_draws += draws;
        total_rewrites += rewrites;
        total_moves += moves;
@@ -302,7 +302,7 @@ fn bench_insert_above_anchor(n: usize, inserts: usize) {
        let start = Instant::now();
        render.update(&root, &mut rsc);
        total += start.elapsed();
-        let (draws, rewrites, moves) = render.take_counters();
+        let (draws, rewrites, moves, _shapes) = render.take_counters();
        total_draws += draws;
        total_rewrites += rewrites;
        total_moves += moves;
@@ -384,7 +384,7 @@ fn bench_expand_holds_edge(n: usize, growths: usize) {
        let start = Instant::now();
        render.update(&root, &mut rsc);
        total += start.elapsed();
-        let (draws, rewrites, moves) = render.take_counters();
+        let (draws, rewrites, moves, _shapes) = render.take_counters();
        total_draws += draws;
        total_rewrites += rewrites;
        total_moves += moves;
@@ -5,6 +5,12 @@ 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 }