docs/RUST.md: the emulator crash loop was the missing GLES fallback, with the panic-hook note

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
iris: the Android renderer falls back to GLES, and every failure reports
2026-09-07 21:50:06 -04:00 · 2026-09-07 21:50:02 -04:00 · 2026-09-07 21:49:45 -04:00 · 2026-09-07 21:21:55 -04:00 · 2026-09-07 21:18:29 -04:00 · 2026-09-07 21:09:35 -04:00
142 changed files with 25675 additions and 1651 deletions
@@ -19,6 +19,21 @@ 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 +
@@ -261,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
@@ -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"
@@ -76,7 +82,10 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 name = "client-core"
 version = "0.1.0"
 dependencies = [
 "base64",
 "event-model",
 "log",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
@@ -206,6 +215,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 +508,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 +820,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"
@@ -3,9 +3,13 @@ package com.example.aiapp
 import android.content.Context
 import android.os.BatteryManager
 import android.os.Process
-import androidx.compose.animation.core.tween
+import android.view.View
-import androidx.compose.foundation.gestures.animateScrollBy
+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
@@ -19,27 +23,84 @@ import kotlinx.coroutines.launch
 * 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, 900px over 200ms, 500ms apart. */
+    /** 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
    /**
-     * Scrolls, then streams, then returns the extra report lines P0 asked for (CPU time, peak RSS,
+     * Type phase (v2): sentences built from long, multisyllabic words so the composer actually
-     * battery current) -- [FrameStats] and [DebugStats] are reset first, exactly as
+     * wraps across lines rather than fitting one, and long enough (600 chars) that the composer's
-     * `copyRenderReport` resets them, so the two accountings cover the same stretch of work.
+     * 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()
@@ -55,34 +116,10 @@ object BenchRun {
            }
        }
-        // The swipe loop: transcript-bench.sh's four swipes per cycle are two drags toward newer
+        val travel = runFlingPhase(listState, flingBehavior)
-        // content and two back, so a cycle returns to where it started and the whole loop measures
+        val sent = runStreamPhase()
-        // steady-state scrolling rather than travelling somewhere new each time.
+        runTypePhase(listState, composerFocus, setComposerText, view)
-        repeat(CYCLES) {
+        val keyboard = runKeyboardPhase(context, view)
            repeat(2) {
                listState.animateScrollBy(SWIPE_PX, tween(SWIPE_MS))
                delay(SWIPE_PAUSE_MS)
            }
            repeat(2) {
                listState.animateScrollBy(-SWIPE_PX, tween(SWIPE_MS))
                delay(SWIPE_PAUSE_MS)
            }
        }
        // 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.
        listState.scrollToItem(0)
        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 report is read.
        delay(300)
        samplerJob.cancel()
        val cpuMs = Process.getElapsedCpuTime() - cpuStartMs
@@ -90,13 +127,158 @@ object BenchRun {
        val batteryLine = battery.finish()
        return listOf(
-            "  scroll: $CYCLES cycles (${CYCLES * 4} swipes), streamed $sent/$total fixture events",
+            "  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 =
@@ -134,6 +134,13 @@ fun debugReport(
     * 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)
@@ -148,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()
@@ -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
@@ -187,13 +187,20 @@ class MainActivity : ComponentActivity() {
            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,
@@ -12,6 +12,7 @@ import androidx.activity.result.PickVisualMediaRequest
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.gestures.ScrollableDefaults
 import androidx.compose.foundation.gestures.awaitEachGesture
 import androidx.compose.foundation.gestures.awaitFirstDown
 import androidx.compose.foundation.layout.Box
@@ -64,12 +65,15 @@ import androidx.compose.runtime.snapshots.Snapshot
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.drawWithContent
 import androidx.compose.ui.focus.FocusRequester
 import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.input.pointer.PointerEventPass
 import androidx.compose.ui.input.pointer.pointerInput
 import androidx.compose.ui.layout.onSizeChanged
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.platform.LocalView
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.semantics
 import androidx.compose.ui.text.TextRange
@@ -354,6 +358,17 @@ fun SessionScreen(
    // `rememberSaveable`, and this screen restores by its own anchor instead -- two restores would
    // fight over the first frame.
    val listState = remember(address) { LazyListState() }
    // The list's own fling path -- what a real flick decays through -- captured here so BenchRun's
    // fling phase can drive `LazyListState.scroll` through exactly the `FlingBehavior` this
    // screen's
    // `TranscriptList` already uses by not overriding it (its `LazyColumn` takes no `flingBehavior`
    // argument, so this is the same default it gets).
    val flingBehavior = ScrollableDefaults.flingBehavior()
    // Where BenchRun's type phase focuses before it types, and the view it toggles the keyboard on
    // -- both bench-only, but cheap enough (a remembered object, a CompositionLocal read) to hold
    // unconditionally rather than behind a second code path only the bench build compiles.
    val composerFocus = remember { FocusRequester() }
    val view = LocalView.current
    // Whether the newest message is on screen right now. The list is reversed, so the newest end is
    // the scrolling start: nothing behind you is exactly being at the bottom. Asked of the scroll
    // state rather than of item indices, because a zero-height first item makes an index ambiguous.
@@ -1256,6 +1271,10 @@ fun SessionScreen(
                    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
@@ -1270,15 +1289,24 @@ fun SessionScreen(
        Toast.makeText(context, "Copied render report", Toast.LENGTH_SHORT).show()
    }
    val copyRenderReport = { buildAndCopyReport() }
-    // Bench build only: P0's scripted scroll-and-stream benchmark (BenchRun.kt), against the
+    // Bench build only: P0's scripted fling/stream/type/keyboard benchmark (BenchRun.kt), against
-    // fixture session opened below instead of a real server. Null everywhere else -- see
+    // 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, scope, listState)
+                    val extra =
                        BenchRun.run(
                            context = context,
                            scope = scope,
                            listState = listState,
                            flingBehavior = flingBehavior,
                            composerFocus = composerFocus,
                            setComposerText = { text -> input = atEnd(text) },
                            view = view,
                        )
                    buildAndCopyReport(extra)
                }
            }
@@ -1777,7 +1805,10 @@ fun SessionScreen(
                            input = it
                            saveDraft(context, summary.id, it.text)
                        },
-                        modifier = Modifier.fillMaxWidth(),
+                        // BenchRun's type phase requests focus on this exact field
                        // (`composerFocus`)
                        // so it types through the real composer rather than a stand-in.
                        modifier = Modifier.fillMaxWidth().focusRequester(composerFocus),
                        // No longer "(+image)": the images are on screen above this, and a
                        // placeholder saying so said it in words beside the thing itself.
                        placeholder = { Text("Message") },
@@ -404,12 +404,27 @@ done
 # Percent-encoded because the app URL-decodes the deep link's query: a
 # token with '+' in it enrols as one with a space, and nothing reports it.
 enc=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$TOKEN")
 # The CA rides in the link (`wg_app_link::enroll::ca_param`: base64url of
 # the DER, which needs no percent-encoding). The Compose app ignores it and
 # pins the copy its APK was built with; the iris app has no baked copy at
 # all -- it is cross-compiled and could be pointed at any machine -- so
 # without this it enrols and then trusts nothing. Minted here rather than by
 # `--enroll-link` because this token is the sandbox's own, carried across
 # restarts so the emulator stays enrolled (see the top of this file).
 ca=$(python3 - "$CERTS/ca.pem" <<'CA'
 import base64, sys
 pem = open(sys.argv[1]).read()
 body = pem.split("-----BEGIN CERTIFICATE-----")[1].split("-----END CERTIFICATE-----")[0]
 der = base64.b64decode("".join(body.split()))
 print(base64.urlsafe_b64encode(der).decode().rstrip("="))
 CA
 )
 cat <<INFO
 sandbox: server $pid on 127.0.0.1:$PORT, log $LOG
 sandbox: 9 invented Claude Code sessions under $PROJECTS (one of them ${BIG_MB}MB)
  enrol the emulator (once; it survives sandbox restarts):
-    adb shell "am start -a android.intent.action.VIEW -d 'aiapp://enroll?host=10.0.2.2&port=$PORT&token=$enc'"
+    adb shell "am start -a android.intent.action.VIEW -d 'aiapp://enroll?host=10.0.2.2&port=$PORT&token=$enc&ca=$ca'"
  drive it:
    ./ui-sandbox.sh spawn [title]        an echo session; prints its id
@@ -46,7 +46,10 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 name = "client-core"
 version = "0.1.0"
 dependencies = [
 "base64",
 "event-model",
 "log",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "tempfile",
@@ -173,6 +176,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 +437,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 +692,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"
@@ -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,21 @@ 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"
 # The enrollment link's `ca` parameter is base64url of the CA's DER
 # (`config::parse_link`). Same version `wg-app-link` already pins for the
 # minting half, so a workspace that has both resolves one copy.
 base64 = "0.23"
 # The logging facade only -- `log_ring` implements a `log::Log` backend and
 # wraps whichever real one the platform installed (`android_logger` on the
 # phone, `env_logger` on the desktop), which is why neither of those is a
 # dependency here. See `log_ring`'s module doc.
 log = { version = "0.4.28", features = ["std"] }
 [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,15 +275,72 @@ impl<T: Transport> ApiClient<T> {
        limit: u32,
        coalesce: bool,
    ) -> Result<Vec<Value>, ApiError> {
-        let mut path = format!("/sessions/{session_id}/transcript?limit={limit}");
+        self.json_request(
-        if let Some(before) = before {
+            "GET",
-            path.push_str(&format!("&before={before}"));
+            &transcript_path(session_id, before, limit, coalesce, None),
-        }
+            None,
-        if coalesce {
+        )
            path.push_str("&coalesce=true");
        }
        self.json_request("GET", &path, None)
    }
    /// A page of transcript history, each line handed back paired with the
    /// exact text it came from, and bounded below by `after` -- the shape
    /// `crate::transcript_source::TranscriptSource` needs to store what it
    /// fetched in the transcript cache without a second round trip to fetch
    /// the raw text separately. Ported from `Api.kt`'s `fetchTranscript`.
    ///
    /// Uses [`serde_json::value::RawValue`] rather than re-serializing a
    /// parsed [`Value`], so the stored line is the exact bytes the server
    /// sent (key order and float literal included) rather than this
    /// crate's own idea of how to write them back out -- the cache and a
    /// live SSE frame must agree byte-for-byte on the same event, which is
    /// exactly what caught the `serde_json` float-rounding bug this
    /// project's `AGENTS.md` records.
    pub fn fetch_transcript_lines(
        &self,
        session_id: &str,
        before: Option<u64>,
        limit: u32,
        coalesce: bool,
        after: Option<u64>,
    ) -> Result<Vec<(String, SeqEvent)>, ApiError> {
        let path = transcript_path(session_id, before, limit, coalesce, after);
        let raw: Vec<Box<serde_json::value::RawValue>> = self.json_request("GET", &path, None)?;
        raw.into_iter()
            .map(|value| {
                let line = value.get().to_string();
                let event: SeqEvent = serde_json::from_str(&line).map_err(|e| ApiError {
                    message: format!(
                        "the server sent a transcript line this build couldn't parse: {e}"
                    ),
                    status: None,
                })?;
                Ok((line, event))
            })
            .collect()
    }
 }
 /// The query string shared by [`ApiClient::fetch_transcript_page`] and
 /// [`ApiClient::fetch_transcript_lines`], so the two agree on how each
 /// parameter is written rather than keeping two copies to drift.
 fn transcript_path(
    session_id: &str,
    before: Option<u64>,
    limit: u32,
    coalesce: bool,
    after: Option<u64>,
 ) -> String {
    let mut path = format!("/sessions/{session_id}/transcript?limit={limit}");
    if let Some(before) = before {
        path.push_str(&format!("&before={before}"));
    }
    if coalesce {
        path.push_str("&coalesce=true");
    }
    if let Some(after) = after {
        path.push_str(&format!("&after={after}"));
    }
    path
 }
 /// The blocking [`Transport`] backed by `ureq`, the same crate `server/`
@@ -6,33 +6,57 @@
 //! the same text a phone would scan as a QR, with no second format
 //! invented for it (RUST.md's E4).
 //!
-//! What this type deliberately does not decide: where it is persisted, and
+//! [`EnrollmentStore`] persists one of these as JSON, owner-only, in a
-//! under what file permissions. A phone seals its token in the Android
+//! directory the caller names -- `$XDG_CONFIG_HOME/ai-app-desktop` for the
-//! Keystore; a desktop client has its own `$XDG_CONFIG_HOME/<app>/`
+//! desktop app, the app-private files directory on Android. **Which**
-//! directory and its own file-mode conventions (MACHINE.md: owner-only,
+//! directory is the only part left to the platform: the format, the file
-//! never in the repo). Both are caller-specific, so they stay out of this
+//! mode and the "nothing saved yet is not an error" answer are the same on
-//! crate per the code rules' "ask for the least you need" -- see
+//! both, and were written twice before this.
-//! `iris/desktop-app/src/config.rs` for the desktop instance.
+//!
 //! JSON rather than the project's usual RON: `wg-app-link`'s RON house
 //! rules (`format`) are for configs a person hand-edits, and this file
 //! never is one -- only the app itself writes or reads it.
 use base64::Engine;
 use serde::{Deserialize, Serialize};
 use std::io;
 use std::path::{Path, PathBuf};
 /// One enrolled server: reachable at `https://{host}:{port}`, authenticated
-/// with `token` as a bearer header. Does not carry the pinned CA -- that is
+/// with `token` as a bearer header.
-/// a public certificate rather than a secret, and where to find it differs
+///
-/// by caller (a phone pins the one its APK was built against; a desktop
+/// `ca_pem` is the trust anchor to pin, when the link carried one (the
-/// client is told a path).
+/// `ca` parameter, `wg_app_link::enroll::ca_param`). It is optional
 /// because an app built on the machine its server runs on pins the CA at
 /// build time and needs nothing from the link; one built elsewhere -- the
 /// iris Android client is cross-compiled in a VM and run against the
 /// host's server -- has no other way to get it. A public certificate
 /// rather than a secret, so it costs the link nothing but length.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct EnrolledServer {
    pub host: String,
    pub port: u16,
    pub token: String,
    /// `#[serde(default)]` so an enrollment saved before this field
    /// existed still loads, as the enrolled server it always was.
    #[serde(default)]
    pub ca_pem: Option<String>,
 }
 impl EnrolledServer {
-    /// Parses `aiapp://enroll?host=H&port=P&token=T` (query order does not
+    /// Parses `aiapp://enroll?host=H&port=P&token=T[&ca=B]` (query order
-    /// matter; unrecognised keys are ignored). `token` is percent-decoded,
+    /// does not matter; unrecognised keys are ignored). `token` is
-    /// since `ui-sandbox.sh` encodes it precisely because a raw token can
+    /// percent-decoded, since `ui-sandbox.sh` encodes it precisely because
-    /// contain `+`, which turns into a space if left to a naive splitter.
+    /// a raw token can contain `+`, which turns into a space if left to a
    /// naive splitter.
    ///
    /// `ca` is base64url of the certificate's DER and is rebuilt into PEM
    /// here, because that is what every consumer of it wants
    /// (`UreqTransport::new`, and the file a person points `curl --cacert`
    /// at). A `ca` that does not decode fails the whole link rather than
    /// enrolling a server with no trust anchor: the link said which
    /// certificate to pin, and quietly not pinning it is the one outcome
    /// nothing downstream could notice.
    pub fn parse_link(link: &str) -> Result<Self, String> {
        let query = link.split_once('?').map(|(_, q)| q).ok_or_else(|| {
            format!(
@@ -44,6 +68,7 @@ impl EnrolledServer {
        let mut host = None;
        let mut port = None;
        let mut token = None;
        let mut ca = None;
        for pair in query.split('&') {
            let Some((key, value)) = pair.split_once('=') else {
                continue;
@@ -53,6 +78,7 @@ impl EnrolledServer {
                "host" => host = Some(value),
                "port" => port = Some(value),
                "token" => token = Some(value),
                "ca" => ca = Some(value),
                _ => {}
            }
        }
@@ -63,8 +89,14 @@ impl EnrolledServer {
            .parse()
            .map_err(|e| format!("'{link}''s port ('{port_str}') is not a number: {e}"))?;
        let token = token.ok_or_else(|| format!("'{link}' is missing 'token'"))?;
        let ca_pem = ca.map(|ca| pem_from_link_param(&ca)).transpose()?;
-        Ok(Self { host, port, token })
+        Ok(Self {
            host,
            port,
            token,
            ca_pem,
        })
    }
    /// Where a `client_core::api::UreqTransport` reaches this server.
@@ -73,6 +105,80 @@ impl EnrolledServer {
    }
 }
 /// The `ca` parameter (base64url of DER, unpadded) as a PEM certificate.
 fn pem_from_link_param(ca: &str) -> Result<String, String> {
    let der = base64::engine::general_purpose::URL_SAFE_NO_PAD
        .decode(ca.as_bytes())
        .map_err(|e| format!("the link's 'ca' is not base64url ({e})"))?;
    let body = base64::engine::general_purpose::STANDARD.encode(&der);
    let mut pem = String::from("-----BEGIN CERTIFICATE-----\n");
    for line in body.as_bytes().chunks(64) {
        pem.push_str(std::str::from_utf8(line).expect("base64 is ASCII"));
        pem.push('\n');
    }
    pem.push_str("-----END CERTIFICATE-----\n");
    Ok(pem)
 }
 /// Where one client keeps the enrollment it should not have to be told
 /// about a second time. `dir` is the caller's, because that is the only
 /// part that differs by platform -- see this module's doc.
 pub struct EnrollmentStore {
    dir: PathBuf,
 }
 impl EnrollmentStore {
    pub fn new(dir: impl Into<PathBuf>) -> Self {
        Self { dir: dir.into() }
    }
    pub fn dir(&self) -> &Path {
        &self.dir
    }
    fn file(&self) -> PathBuf {
        self.dir.join("enrollment.json")
    }
    /// Writes `server` under `dir`, creating it if needed, and sets the
    /// file owner-only -- it carries a bearer token, the same reason
    /// `server/`'s own token store is 0600.
    pub fn save(&self, server: &EnrolledServer) -> io::Result<()> {
        std::fs::create_dir_all(&self.dir)?;
        let path = self.file();
        let json = serde_json::to_vec_pretty(server)
            .expect("EnrolledServer holds nothing that fails to serialise");
        std::fs::write(&path, json)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
        }
        Ok(())
    }
    /// `Ok(None)` when nothing has been enrolled yet, rather than an error
    /// -- "not enrolled" is an ordinary first-run state, not a failure
    /// (UI_RULES' "a deliberate choice is not a problem to report" applies
    /// just as well to a file that simply hasn't been written yet).
    pub fn load(&self) -> io::Result<Option<EnrolledServer>> {
        let path = self.file();
        match std::fs::read(&path) {
            Ok(bytes) => {
                let server = serde_json::from_slice(&bytes).map_err(|e| {
                    io::Error::new(
                        io::ErrorKind::InvalidData,
                        format!("{} is not a valid enrollment ({e})", path.display()),
                    )
                })?;
                Ok(Some(server))
            }
            Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(e),
        }
    }
 }
 fn percent_decode(s: &str) -> String {
    let bytes = s.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
@@ -108,6 +214,7 @@ mod tests {
                host: "127.0.0.1".to_string(),
                port: 8547,
                token: "abcDEF123".to_string(),
                ca_pem: None,
            }
        );
        assert_eq!(server.base_url(), "https://127.0.0.1:8547");
@@ -141,6 +248,115 @@ mod tests {
        );
    }
    /// The CA travels as base64url of the DER and comes back out as the
    /// PEM every consumer of it wants -- the same round trip
    /// `wg_app_link::enroll::ca_param` mints.
    #[test]
    fn a_ca_in_the_link_comes_back_as_pem() {
        let der = [0x30u8, 0x82, 0x01, 0xfb, 0x3e, 0x7f];
        let param = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(der);
        let server =
            EnrolledServer::parse_link(&format!("aiapp://enroll?host=h&port=1&token=t&ca={param}"))
                .unwrap();
        let pem = server.ca_pem.expect("the link carried a CA");
        assert!(pem.starts_with("-----BEGIN CERTIFICATE-----\n"), "{pem}");
        assert!(
            pem.trim_end().ends_with("-----END CERTIFICATE-----"),
            "{pem}"
        );
        assert_eq!(
            base64::engine::general_purpose::STANDARD
                .decode(
                    pem.lines()
                        .filter(|l| !l.starts_with("-----"))
                        .collect::<String>()
                )
                .unwrap(),
            der
        );
    }
    /// A link with no `ca` is an ordinary link, not a broken one: an app
    /// that pins at build time mints and reads exactly these.
    #[test]
    fn no_ca_parameter_is_none_not_an_error() {
        let server = EnrolledServer::parse_link("aiapp://enroll?host=h&port=1&token=t").unwrap();
        assert_eq!(server.ca_pem, None);
    }
    /// The half that cannot be noticed later: a `ca` that does not decode
    /// must fail the link rather than enrolling with nothing pinned.
    #[test]
    fn a_ca_that_does_not_decode_fails_the_link() {
        let err =
            EnrolledServer::parse_link("aiapp://enroll?host=h&port=1&token=t&ca=not!base64url")
                .unwrap_err();
        assert!(err.contains("ca"), "{err}");
    }
    #[test]
    fn a_saved_enrollment_reads_back_the_same() {
        let dir = tempfile::tempdir().unwrap();
        let store = EnrollmentStore::new(dir.path());
        let server = EnrolledServer {
            host: "127.0.0.1".to_string(),
            port: 8547,
            token: "tok".to_string(),
            ca_pem: Some("-----BEGIN CERTIFICATE-----\nQUJD\n-----END CERTIFICATE-----\n".into()),
        };
        store.save(&server).unwrap();
        assert_eq!(store.load().unwrap(), Some(server));
    }
    #[test]
    fn nothing_saved_yet_is_none_not_an_error() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(EnrollmentStore::new(dir.path()).load().unwrap(), None);
    }
    /// An enrollment written before `ca_pem` existed still loads.
    #[test]
    fn an_enrollment_without_a_ca_still_loads() {
        let dir = tempfile::tempdir().unwrap();
        let store = EnrollmentStore::new(dir.path());
        std::fs::create_dir_all(dir.path()).unwrap();
        std::fs::write(
            dir.path().join("enrollment.json"),
            br#"{"host":"h","port":1,"token":"t"}"#,
        )
        .unwrap();
        assert_eq!(store.load().unwrap().unwrap().ca_pem, None);
    }
    #[test]
    #[cfg(unix)]
    fn the_saved_file_is_owner_only() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let store = EnrollmentStore::new(dir.path());
        store
            .save(&EnrolledServer {
                host: "h".to_string(),
                port: 1,
                token: "t".to_string(),
                ca_pem: None,
            })
            .unwrap();
        let mode = std::fs::metadata(dir.path().join("enrollment.json"))
            .unwrap()
            .permissions()
            .mode();
        assert_eq!(mode & 0o777, 0o600);
    }
    #[test]
    fn a_corrupt_file_is_named_in_the_error() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("enrollment.json"), b"not json").unwrap();
        let err = EnrollmentStore::new(dir.path()).load().unwrap_err();
        assert!(err.to_string().contains("enrollment.json"));
    }
    #[test]
    fn a_non_numeric_port_is_named_in_the_error() {
        let err = EnrolledServer::parse_link("aiapp://enroll?host=h&port=x&token=t").unwrap_err();
@@ -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(""), "");
    }
 }
@@ -5,11 +5,16 @@
 pub mod ansi;
 pub mod api;
 pub mod config;
 pub mod durations;
 pub mod event_stream;
 pub mod highlight;
 pub mod log_ring;
 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,549 @@
 //! The app's own recent log, held in memory so it can be read back
 //! without `logcat`.
 //!
 //! **Why this exists**: Iris tests iris builds on a GrapheneOS phone with
 //! no `adb`, and Android forbids one app reading another's logcat, so
 //! nothing outside the process can recover what it wrote. The only way a
 //! line reaches her is for the app to carry its own copy. This is that
 //! copy: a bounded ring every `log::info!` in the process lands in, on top
 //! of whichever platform logger was already installed (`android_logger`,
 //! `env_logger`) rather than instead of it -- see [`RingLogger`].
 //!
 //! Two consumers, both reading the same ring rather than each keeping
 //! their own: the bench app's `Copy report`/`Diagnostics` (which reads
 //! [`LogRing::to_text`] and [`LogRing::summary`]) and whatever hands the
 //! log out of the process -- on Android, the `DevLogProvider` Dev Updater
 //! queries, which reads [`LogRing::since`] and [`LogRing::newest_seq`].
 //! That is why reading does not consume: a line already handed over must
 //! still be in the report, and a report taken twice must say the same
 //! thing.
 use std::collections::VecDeque;
 use std::sync::{Arc, Mutex, OnceLock};
 use std::time::{SystemTime, UNIX_EPOCH};
 /// How many lines a default ring holds, and how many bytes of message.
 ///
 /// Both bounds apply -- whichever bites first -- because the two failure
 /// modes are different: a flood of short lines exhausts the count, and one
 /// pathological line (a stack trace, a pretty-printed JSON body) exhausts
 /// the bytes. A ring bounded only by lines can hold megabytes; one bounded
 /// only by bytes can be emptied by a single line.
 pub const DEFAULT_MAX_LINES: usize = 2000;
 pub const DEFAULT_MAX_BYTES: usize = 256 * 1024;
 /// One recorded line. `seq` is assigned by the ring and only ever
 /// increases, so a reader that remembers where it got to can ask for what
 /// came after -- and a gap in the sequence is exactly the lines the bound
 /// dropped.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct LogLine {
    pub seq: u64,
    /// Milliseconds since the unix epoch, from the app's own clock. The
    /// app's rather than the receiver's: a line is timestamped when it
    /// happened, and an upload can be minutes later or never.
    pub at_ms: u64,
    pub level: log::Level,
    pub target: String,
    pub message: String,
 }
 impl LogLine {
    /// Roughly what the line costs the ring. The two `String`s dominate;
    /// the fixed fields are counted as a flat overhead so a ring of empty
    /// messages still has a bound.
    fn weight(&self) -> usize {
        self.target.len() + self.message.len() + 32
    }
    /// `12:34:56.789 INFO  iris::android: the message`, the shape a
    /// person skims. Time of day only -- the date is in the report's own
    /// header, and a ring never spans one.
    pub fn format(&self) -> String {
        format!(
            "{} {:<5} {}: {}",
            clock_time(self.at_ms),
            self.level,
            self.target,
            self.message
        )
    }
 }
 /// `HH:MM:SS.mmm` in UTC from a unix millisecond count, without a date
 /// library: the only field this needs is the time of day, and dividing out
 /// the day is the whole calculation. Deliberately not local time -- the
 /// phone's offset is not knowable here, and a report that says UTC is
 /// comparable with the server's log, which is what it gets read against.
 fn clock_time(at_ms: u64) -> String {
    let ms = at_ms % 1000;
    let secs_of_day = (at_ms / 1000) % 86_400;
    format!(
        "{:02}:{:02}:{:02}.{:03}",
        secs_of_day / 3600,
        (secs_of_day % 3600) / 60,
        secs_of_day % 60,
        ms
    )
 }
 /// Now, in unix milliseconds. Saturating rather than panicking on a clock
 /// before the epoch: a wrong timestamp in a diagnostic is not worth taking
 /// the app down for.
 pub fn now_ms() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
 }
 #[derive(Debug)]
 struct Inner {
    lines: VecDeque<LogLine>,
    bytes: usize,
    max_lines: usize,
    max_bytes: usize,
    next_seq: u64,
    /// How many lines the bounds have discarded since the ring was made.
    /// Reported rather than inferred, so "the log starts here" and "the
    /// log was cut off here" are distinguishable -- the unknown state the
    /// UI rules ask for.
    dropped: u64,
 }
 /// A bounded, shareable ring of recent log lines. Cloning shares the ring;
 /// there is one per process and every holder sees the same lines.
 #[derive(Debug, Clone)]
 pub struct LogRing(Arc<Mutex<Inner>>);
 impl LogRing {
    pub fn new(max_lines: usize, max_bytes: usize) -> Self {
        assert!(
            max_lines > 0 && max_bytes > 0,
            "a ring with no room holds nothing"
        );
        Self(Arc::new(Mutex::new(Inner {
            lines: VecDeque::new(),
            bytes: 0,
            max_lines,
            max_bytes,
            next_seq: 0,
            dropped: 0,
        })))
    }
    /// The bounds this project ships with: [`DEFAULT_MAX_LINES`] and
    /// [`DEFAULT_MAX_BYTES`].
    pub fn with_defaults() -> Self {
        Self::new(DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES)
    }
    /// A poisoned lock is a bug in a panicking logger, not a reason to
    /// take the app down a second time -- the ring is a diagnostic, and
    /// losing it must not be worse than the fault it was recording.
    fn with<R>(&self, f: impl FnOnce(&mut Inner) -> R) -> R {
        let mut guard = match self.0.lock() {
            Ok(guard) => guard,
            Err(poisoned) => poisoned.into_inner(),
        };
        f(&mut guard)
    }
    /// Records a line, evicting the oldest until both bounds hold again.
    pub fn push(&self, level: log::Level, target: &str, message: String) {
        self.with(|inner| {
            let line = LogLine {
                seq: inner.next_seq,
                at_ms: now_ms(),
                level,
                target: target.to_string(),
                message,
            };
            inner.next_seq += 1;
            inner.bytes += line.weight();
            inner.lines.push_back(line);
            // `!is_empty()` rather than `len() > 1`: one line larger than
            // the whole byte bound is kept, because dropping it would
            // leave the ring silently empty while lines were arriving.
            while inner.lines.len() > inner.max_lines
                || (inner.bytes > inner.max_bytes && inner.lines.len() > 1)
            {
                if let Some(evicted) = inner.lines.pop_front() {
                    inner.bytes -= evicted.weight();
                    inner.dropped += 1;
                }
            }
        })
    }
    /// Every line held, oldest first.
    pub fn snapshot(&self) -> Vec<LogLine> {
        self.with(|inner| inner.lines.iter().cloned().collect())
    }
    /// The lines with a sequence number at or after `seq`, oldest first,
    /// and the sequence to ask from next time. Does not consume: see this
    /// module's doc for why.
    pub fn since(&self, seq: u64) -> (Vec<LogLine>, u64) {
        self.with(|inner| {
            let lines: Vec<LogLine> = inner
                .lines
                .iter()
                .filter(|line| line.seq >= seq)
                .cloned()
                .collect();
            let next = lines.last().map(|line| line.seq + 1).unwrap_or(seq);
            (lines, next)
        })
    }
    pub fn len(&self) -> usize {
        self.with(|inner| inner.lines.len())
    }
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
    pub fn dropped(&self) -> u64 {
        self.with(|inner| inner.dropped)
    }
    /// The sequence number of the newest line held, or `None` for a ring
    /// nothing has been written to.
    ///
    /// What a reader needs to notice that this process **restarted**: the
    /// ring is in memory, so a new process starts again at zero, and a
    /// reader holding a cursor from the previous one would otherwise ask
    /// for lines after a number nothing will reach for hours and see
    /// nothing at all -- silently, which is worse than seeing the log
    /// begin again. Answering `None` rather than 0 for an empty ring is
    /// the same distinction [`Self::summary`] draws: "nothing has been
    /// logged" is not a sequence number.
    pub fn newest_seq(&self) -> Option<u64> {
        self.with(|inner| inner.lines.back().map(|line| line.seq))
    }
    /// When the newest line was written, in unix milliseconds, or `None`
    /// for a ring nothing has been written to.
    pub fn last_at_ms(&self) -> Option<u64> {
        self.with(|inner| inner.lines.back().map(|line| line.at_ms))
    }
    /// Every line held, formatted one per line -- what `Copy report`
    /// appends.
    pub fn to_text(&self) -> String {
        self.snapshot()
            .iter()
            .map(LogLine::format)
            .collect::<Vec<_>>()
            .join("\n")
    }
    /// One line for a diagnostics pane: how much is held, how much was
    /// dropped, and when the last line arrived. "no lines yet" is its own
    /// wording rather than a count of zero with a made-up time, because
    /// "nothing has been logged" and "logging is not running" would
    /// otherwise look the same.
    pub fn summary(&self) -> String {
        let (len, dropped, last) = self.with(|inner| {
            (
                inner.lines.len(),
                inner.dropped,
                inner.lines.back().map(|line| line.at_ms),
            )
        });
        match last {
            None => "app log: no lines yet".to_string(),
            Some(at) => {
                let dropped = if dropped > 0 {
                    format!(", {dropped} dropped")
                } else {
                    String::new()
                };
                format!(
                    "app log: {len} lines held{dropped}, last {}",
                    clock_time(at)
                )
            }
        }
    }
 }
 /// A `log` backend that records into a [`LogRing`] **and** forwards to the
 /// logger the platform already installs, so nothing that reads the
 /// platform's log (`logcat`, a terminal) changes.
 ///
 /// The inner logger is passed in rather than chosen here: `client-core`
 /// has no business depending on `android_logger` or `env_logger`, and
 /// which one is right is exactly what differs between the two platforms
 /// (the sharing rule in AGENTS.md).
 pub struct RingLogger {
    ring: LogRing,
    inner: Box<dyn log::Log>,
 }
 impl RingLogger {
    pub fn new(ring: LogRing, inner: Box<dyn log::Log>) -> Self {
        Self { ring, inner }
    }
 }
 impl log::Log for RingLogger {
    /// True for anything `log`'s own max level lets through: the ring
    /// wants everything, even where the platform logger would filter it
    /// out. The filter is applied per-logger in [`Self::log`] instead.
    fn enabled(&self, _metadata: &log::Metadata) -> bool {
        true
    }
    fn log(&self, record: &log::Record) {
        self.ring
            .push(record.level(), record.target(), record.args().to_string());
        if self.inner.enabled(record.metadata()) {
            self.inner.log(record);
        }
    }
    fn flush(&self) {
        self.inner.flush();
    }
 }
 /// Installs a [`RingLogger`] as the process logger and answers the ring it
 /// records into.
 ///
 /// Fails only if a logger is already installed, which is a programmer
 /// error (two initialisation paths) rather than a recoverable condition --
 /// the caller is named in the error so it is findable.
 pub fn install(
    ring: LogRing,
    inner: Box<dyn log::Log>,
    max_level: log::LevelFilter,
 ) -> Result<(), log::SetLoggerError> {
    log::set_boxed_logger(Box::new(RingLogger::new(ring, inner)))?;
    log::set_max_level(max_level);
    Ok(())
 }
 /// The one ring this process records into.
 ///
 /// **A deliberate process-global, where this project's rules otherwise say
 /// pass context explicitly.** What is being modelled is already one: `log`
 /// has exactly one backend per process, set once, and every `log::info!`
 /// anywhere in the binary goes to it. A ring handed around as a parameter
 /// would be a *second* answer to "which lines exist" -- the report would
 /// show one ring while the logger filled another, and which one a caller
 /// got would depend on how far down the call tree it was. The tests above
 /// all use their own [`LogRing`], so nothing here needs this to be
 /// testable.
 static PROCESS_RING: OnceLock<LogRing> = OnceLock::new();
 /// The process's ring, created on first use with the default bounds.
 /// Safe to call before [`install_process_logger`] -- it will simply be
 /// empty.
 pub fn process_ring() -> &'static LogRing {
    PROCESS_RING.get_or_init(LogRing::with_defaults)
 }
 /// Installs [`process_ring`] as the recording half of the process logger,
 /// forwarding to `inner` (the platform's own logger, already configured).
 /// The platform half of AGENTS.md's sharing rule is `inner`; everything
 /// else is shared.
 pub fn install_process_logger(
    inner: Box<dyn log::Log>,
    max_level: log::LevelFilter,
 ) -> Result<(), log::SetLoggerError> {
    install(process_ring().clone(), inner, max_level)
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use log::Level;
    fn fill(ring: &LogRing, count: usize) {
        for n in 0..count {
            ring.push(Level::Info, "test", format!("line {n}"));
        }
    }
    #[test]
    fn lines_come_back_oldest_first() {
        let ring = LogRing::new(10, 1 << 20);
        fill(&ring, 3);
        let text: Vec<String> = ring.snapshot().into_iter().map(|l| l.message).collect();
        assert_eq!(text, ["line 0", "line 1", "line 2"]);
    }
    #[test]
    fn the_line_bound_drops_the_oldest_and_says_how_many() {
        let ring = LogRing::new(3, 1 << 20);
        fill(&ring, 5);
        let text: Vec<String> = ring.snapshot().into_iter().map(|l| l.message).collect();
        assert_eq!(text, ["line 2", "line 3", "line 4"], "the newest survive");
        assert_eq!(ring.len(), 3);
        assert_eq!(ring.dropped(), 2, "and the loss is reported, not silent");
    }
    #[test]
    fn the_byte_bound_bites_before_the_line_bound_when_lines_are_large() {
        // Room for 1000 lines but only a few hundred bytes.
        let ring = LogRing::new(1000, 300);
        for n in 0..10 {
            ring.push(Level::Info, "t", format!("{n}{}", "x".repeat(100)));
        }
        assert!(
            ring.len() < 10,
            "the byte bound evicted: {} held",
            ring.len()
        );
        assert!(ring.dropped() > 0);
        assert!(
            ring.snapshot().last().unwrap().message.starts_with('9'),
            "and it evicted from the old end"
        );
    }
    /// The case the `len() > 1` guard exists for: one line larger than the
    /// whole bound must still be readable, or a ring that is over budget
    /// reads as a ring nothing was written to.
    #[test]
    fn one_oversized_line_is_kept_rather_than_leaving_the_ring_empty() {
        let ring = LogRing::new(100, 64);
        ring.push(Level::Error, "t", "y".repeat(5000));
        assert_eq!(ring.len(), 1);
        assert_eq!(ring.dropped(), 0);
    }
    #[test]
    fn sequence_numbers_only_increase_and_survive_eviction() {
        let ring = LogRing::new(2, 1 << 20);
        fill(&ring, 5);
        let seqs: Vec<u64> = ring.snapshot().into_iter().map(|l| l.seq).collect();
        assert_eq!(seqs, [3, 4], "a gap is exactly what was dropped");
    }
    #[test]
    fn since_returns_only_what_is_new_and_the_next_cursor() {
        let ring = LogRing::new(100, 1 << 20);
        fill(&ring, 3);
        let (first, cursor) = ring.since(0);
        assert_eq!(first.len(), 3);
        assert_eq!(cursor, 3);
        let (none, cursor) = ring.since(cursor);
        assert!(none.is_empty(), "nothing new yet");
        assert_eq!(cursor, 3, "and the cursor does not move");
        ring.push(Level::Warn, "test", "later".into());
        let (more, cursor) = ring.since(cursor);
        assert_eq!(more.len(), 1);
        assert_eq!(more[0].message, "later");
        assert_eq!(cursor, 4);
    }
    /// The restart signal: a reader that saw sequence 4 and is now told
    /// the newest is 0 knows the process is not the one it was reading.
    #[test]
    fn the_newest_sequence_says_where_the_ring_is_and_nothing_for_an_empty_one() {
        let ring = LogRing::new(100, 1 << 20);
        assert_eq!(ring.newest_seq(), None, "an empty ring has no newest line");
        fill(&ring, 5);
        assert_eq!(ring.newest_seq(), Some(4));
        let restarted = LogRing::new(100, 1 << 20);
        fill(&restarted, 1);
        assert_eq!(
            restarted.newest_seq(),
            Some(0),
            "a fresh ring starts again, which is exactly what a reader has to notice"
        );
    }
    #[test]
    fn reading_does_not_consume() {
        let ring = LogRing::new(100, 1 << 20);
        fill(&ring, 2);
        let (sent, _) = ring.since(0);
        assert_eq!(sent.len(), 2);
        assert_eq!(ring.len(), 2, "the report still has them after an upload");
        assert_eq!(ring.to_text().lines().count(), 2);
    }
    #[test]
    fn an_empty_ring_says_so_rather_than_reporting_a_time() {
        let ring = LogRing::with_defaults();
        assert_eq!(ring.summary(), "app log: no lines yet");
        assert_eq!(ring.last_at_ms(), None);
        assert!(ring.is_empty());
    }
    #[test]
    fn the_summary_names_dropped_lines_only_when_there_are_some() {
        let ring = LogRing::new(2, 1 << 20);
        fill(&ring, 2);
        assert!(!ring.summary().contains("dropped"), "{}", ring.summary());
        fill(&ring, 2);
        assert!(ring.summary().contains("2 dropped"), "{}", ring.summary());
    }
    #[test]
    fn a_line_formats_as_time_level_target_message() {
        let line = LogLine {
            seq: 0,
            // 1970-01-01T12:34:56.789Z, so the arithmetic is checkable by
            // hand rather than against another clock.
            at_ms: (12 * 3600 + 34 * 60 + 56) * 1000 + 789,
            level: Level::Info,
            target: "iris::android".into(),
            message: "surface created".into(),
        }
        .format();
        assert_eq!(line, "12:34:56.789 INFO  iris::android: surface created");
    }
    /// The forwarding half: a line reaches the ring *and* the logger the
    /// platform already had, and one the inner logger filters out is still
    /// in the ring.
    #[test]
    fn the_ring_logger_forwards_to_the_inner_logger() {
        use log::Log;
        struct Collect(Arc<Mutex<Vec<String>>>, log::Level);
        impl Log for Collect {
            fn enabled(&self, metadata: &log::Metadata) -> bool {
                metadata.level() <= self.1
            }
            fn log(&self, record: &log::Record) {
                self.0.lock().unwrap().push(record.args().to_string());
            }
            fn flush(&self) {}
        }
        let seen = Arc::new(Mutex::new(Vec::new()));
        let ring = LogRing::with_defaults();
        let logger = RingLogger::new(ring.clone(), Box::new(Collect(seen.clone(), Level::Info)));
        logger.log(
            &log::Record::builder()
                .args(format_args!("kept"))
                .level(Level::Info)
                .target("t")
                .build(),
        );
        logger.log(
            &log::Record::builder()
                .args(format_args!("filtered"))
                .level(Level::Debug)
                .target("t")
                .build(),
        );
        assert_eq!(
            *seen.lock().unwrap(),
            ["kept"],
            "the inner logger's own filter still applies"
        );
        let held: Vec<String> = ring.snapshot().into_iter().map(|l| l.message).collect();
        assert_eq!(held, ["kept", "filtered"], "the ring keeps both");
    }
 }
@@ -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()]
        );
    }
 }
@@ -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
@@ -780,6 +1076,7 @@ mod tests {
            Event::ToolEnd {
                id: "x".to_string(),
                output: "done".to_string(),
                is_error: false,
            },
        )]);
        assert_eq!(
@@ -792,6 +1089,7 @@ mod tests {
                input: String::new(),
                output: "done".to_string(),
                done: true,
                failed: false,
                asks: Vec::new(),
                images: Vec::new(),
            }]
@@ -939,4 +1237,284 @@ mod tests {
        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).
@@ -5,6 +5,308 @@ 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-07 (platform fonts, not bundled ones)
 - **Iris's own decision, carried out as directed**: removed the 3.6 MB of
  bundled Noto Sans/Noto Sans Mono TTFs from `iris-core` and load text
  from the platform's own font collection instead (`fontique`'s system
  discovery, already on by default). Matches what the Compose app does --
  it takes body text from `FontFamily.Default` and code text from
  `FontFamily.Monospace`, both platform-resolved, and ships no text font
  of its own. Rejected alternative (the one this pass had left open
  2026-09-06): subsetting the bundled Noto Sans to Latin/common
  punctuation instead of removing it outright, which would have kept
  identical rendering across devices for a smaller (not zero) size cost;
  Iris chose to match Compose instead.
 - `.so` **-3,748,136 bytes** (11,193,608 -> 7,445,472), matching the
  original 3.6 MB estimate. Fallback still lands on the platform's own
  tofu for a codepoint no resolved face has (checked with CJK + emoji on
  desktop) rather than blank space, so the UI_RULES unknown-glyph rule
  still holds.
 - **Gap found, then closed same day**: this fontique version's Android
  backend never resolved the `Monospace` generic family at all (confirmed
  on this checkout's emulator, `mono=None` in the startup diagnostic) --
  two pre-existing bugs in fontique's own `fonts.xml` parsing stacked (an
  ordering bug, and a `<family name="monospace">` declaration whose
  `<font>` children the backend's parser never reads), not something this
  change introduced, but this change is what stopped masking it (the
  bundled mono font used to be registered ahead of the broken platform
  lookup, so it always won). Checked `linebender/parley`'s `main` branch
  on GitHub: neither bug is fixed there, so there was no newer release to
  bump to. Fixed instead in `iris-core` itself
  (`TextData::patch_android_monospace`, Android-only): reads
  `/system/etc/fonts.xml`'s own `"monospace"` declaration for the font
  filename it names, then registers whichever of fontique's actually-
  scanned families owns that file as the `Monospace` generic -- the same
  authority Compose's `Typeface.MONOSPACE` resolves through, without
  pinning an OEM-specific family name. Verified on this checkout's
  emulator: `mono=Some("Droid Sans Mono")`, and a screenshot showing the
  bench-fixture's code block and tool-card values in a visibly monospaced
  face beside sans body text; the desktop `fontconfig` backend is
  unaffected (still resolves monospace correctly, confirmed unchanged).
  docs/RUST.md's "Platform fonts (2026-09-07)" has the full account.
 ## 2026-09-07 (a phone log reaches Iris through Dev Updater's own tab)
 **Supersedes the "how a phone log reaches Iris" entry below, same day.**
 Iris's call once the route was working: put it in Dev Updater properly
 rather than smuggling the lines through `ai-server`'s log.
 - **The app exposes its own log on the device, and Dev Updater reads it
  there.** A `ContentProvider` at `<applicationId>.devlog`, one table of
  lines queried with `?since=<seq>` so a poll is incremental, plus a
  `status` row (`held`, `dropped`, `newest_seq`). Dev Updater's phone app
  polls it while the component's **Runtime** tab is open and forwards what
  is new to its own build machine, into that APK component's runtime log
  -- so the same tab renders both kinds and the history outlives the
  phone. No tunnel, no token, no second enrolment: the two apps are on the
  same phone.
  **It is a contract, not a feature for iris.** Written down in
  dev-updater's `README.md` ("An app's own log"), so any app that server
  delivers gets the tab by implementing it; the Compose app in `app/` can
  do the same later. That is the reason it beat the route below on its
  second look -- the earlier one only ever worked for the one project that
  had a server, and put a phone's lines under a *different component* than
  the one they came from.
 - **Read access is `protectionLevel="normal"`, and that is a real trade.**
  `signature` is what this wants and is not available: Dev Updater and the
  apps it delivers are built on one machine but signed with different
  locally generated keys, so a signature permission would be held by
  nothing at all. What `normal` costs is that any app on that phone which
  requests `dev.updater.permission.READ_DEVLOG` by name can read another
  app's dev log. Accepted because these are development builds on a
  development phone and the alternative was no log; stated in the manifest
  beside the declaration and in dev-updater's README so it is not
  rediscovered as a surprise.
 - **The provider polls rather than notifying.** `notifyChange` was not
  implemented: the ring is filled by a `log::Log` backend on whatever
  thread logged, and giving that a route to a `ContentProvider` means
  plumbing a callback through `client-core` for every platform. Dev
  Updater's contract therefore says it polls (about a second, only while
  the tab is open), which is what keeps implementing the contract cheap --
  a provider that does notify loses nothing.
 - **What was deleted, so there is one mechanism**: `client-core`'s
  `log_upload` module, `POST /client-log` on `ai-server`, the
  `AI_APP_LOG_HOST`/`_PORT`/`_TOKEN` baking in `iris/android-app/build.rs`
  (which left that file with nothing to do, so it is gone too), and the
  uploader fields on both Android clients. Kept: the ring, `RingLogger`,
  `install_process_logger`, and the Diagnostics line counting what is
  held. The upload-status line there is now **"devlog provider:
  content://<authority>"** -- named from what the provider registered
  rather than composed from the package here, so a screenshot of that pane
  is evidence the contract is live and says which package's log it is.
 ## 2026-09-07 (how a phone log reaches Iris) -- superseded, see above
 - **The app sends its own log to `ai-server`, and Dev Updater shows it as
  `ai-server`'s runtime log.** Iris has no `adb`/`logcat` on her phone, and
  Android forbids one app reading another's logcat, so the app has to carry
  its own copy and post it somewhere. `POST /client-log` on `ai-server`
  re-emits each line into that server's own `tracing` output; Dev Updater
  already runs `ai-server` as a `Managed` component, whose stdout its own
  service script redirects to a file and reports through
  `GET /apps/{key}/components/{name}/logs?kind=runtime`, which the phone
  app's log dialog already offers as a **Runtime** tab for a `server`
  component. So **no change to Dev Updater at all** -- one route on
  `ai-server`, and the client in `client-core`.
  **Rejected: posting to Dev Updater's own server** (the first candidate,
  and what the entry above went on to build -- the estimate below was
  right about the work and wrong about it being too much).
  It would need a new authenticated *write* route on a TLS surface whose
  module doc says every route on it "is, or decides, the bytes that get
  handed to `REQUEST_INSTALL_PACKAGES` next"; a per-app device-log store;
  a change to `component_logs` so an APK component can have a runtime log;
  a change to the phone app's `hasBothKinds = component.kind == "server"`
  gate and to what `hasRuntimeLogs` means on the wire; and -- the real
  cost -- a **second** enrollment for the iris app, since it has no CA or
  token for Dev Updater and Dev Updater mints tokens per device by QR.
  Five changes across two repos against one route, for the same line
  landing in the same viewer.
  **Rejected: a share intent from a debug button** (a log file in the app's
  external files dir, shared by hand). It works today and needs no server,
  but every line costs Iris a manual export and a message, which is the
  round trip through a person this was meant to remove. It is still the
  fallback when the tunnel is down, and GrapheneOS's own per-app log export
  already covers the crash case (that is how the `ToolInput.highlighted`
  crash was reported).
 - **The ring is in `client-core`, not in the Android crate.** A bounded
  in-memory ring (2000 lines or 256 KiB, whichever bites first) behind a
  `log::Log` backend that *forwards* to whichever logger the platform
  already installed, so `logcat` and a desktop terminal see exactly what
  they saw before. The platform supplies only its own logger and its
  destination. `Copy report` appends the ring to what goes on the
  clipboard, and flushes the uploader first.
 - **The destination is baked in at build time, from the build machine's
  own files** (`AI_APP_LOG_HOST`/`_PORT`/`_TOKEN` plus the pinned CA) --
  *gone; the provider above replaced it.* What is worth keeping from it is
  the reason it went: an APK good only for the server that built it cannot
  be built in this VM for Iris's phone, which is the case that mattered.
  all three or none, never two. The same trust boundary the transcript
  config and the Compose APK's CA already use: nothing secret is
  committed, and an APK is good for the server that built it. A build told
  nothing still keeps its ring and still copies it; the diagnostics pane
  says which of "not tried yet", "failing -- <why>" and "no server
  configured" it is, because otherwise all three look like silence.
 ## 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
@@ -264,24 +566,82 @@ marked **DEFERRED** are ones the agent chose not to decide alone.
  | 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`) | **release**, `force-gles` | host (virgl) | 62 | 41.94% | 15.0ms | 21.8ms | 37.1ms | 37.1ms | 0.2ms | 12.9ms |
+  | 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
-  0.2ms -- almost the entire frame is time spent handing the frame to the
+  ~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, but is not
+  rasterisation cost rather than an iris-specific slowness. **Still not
-  proof of it: a same-mode software `force-gles` run to isolate the
+  proof, and now closed as unanswerable rather than merely untaken**: a
-  backend crashed for an unrelated reason (SwiftShader's GL path reports
+  same-mode software `force-gles` run to isolate the backend was retried
-  itself as OpenGL ES 3.0, which has no compute shaders, and iris's device
+  2026-09-05 after fixing the compute-limit crash the first attempt hit,
-  request assumes them unconditionally) — real scope to fix, not done
+  and hit a second, structural wall instead — SwiftShader's ES 3.0 GL
-  here — and the two apps' frame populations still differ in kind the same
+  path has no storage-buffer capacity at all, and `shader.wgsl` reads
-  way the software-mode caveats describe. A real intermittent touch-
+  `var<storage>` buffers unconditionally, so reaching that path needs a
-  scroll dropout was also reproduced this pass (six consecutive swipes
+  shader rewrite, not a limits fix (RUST.md's I5 box, "The three
-  produced zero redraws while taps kept working; an identical retry then
+  remaining I5 verifications, closed 2026-09-05," item 2). The
-  succeeded) and is not explained. RUST.md's I5 box, "Where iris's frame
+  intermittent touch-scroll dropout this pass also reproduced is
-  time goes, 2026-09-05, the `-gpu host` pass," has the full account. The
+  root-caused and fixed as of the same date (a missed `ACTION_DOWN` on a
-  iris-vs-Masonry choice itself is still Iris's to make.
+  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.
 ## 2026-09-07: the enrolment link carries the CA, so an APK need not be built where its server runs
 **Problem.** Every phone build pinned the CA of the machine that compiled
 it -- the Compose app from `GeneratePinnedCert`, the iris app from
 `build.rs` reading `$XDG_CONFIG_HOME/ai-app/certs/ca.pem`. That is fine
 while the two are the same machine and impossible when they are not, which
 is exactly the iris client's situation: cross-compiled in this VM,
 delivered to a phone, run against `ai-server` on the host. Baking the
 host/port/token as well made it worse -- a token in a built artifact.
 **Decided: the CA rides in the enrolment link**, as `&ca=<base64url of the
 DER>` (`wg_app_link::enroll::ca_param`), optional and per mint. The app
 that opens the link pins what the link said, and an APK built anywhere
 works against whatever server it is pointed at.
 Two alternatives were worked out and rejected.
 - **A CA *fingerprint* in the link, pinned at the TLS handshake.** The
  smallest link (43 more characters) and the strongest shape, but `ureq`
  3.4 exposes no hook for a custom `rustls` `ServerCertVerifier`: its
  `TlsConfig` builds the `ClientConfig` itself, so this needs a hand-written
  `Connector` on the `unversioned` API and `rustls` as a direct dependency
  of `client-core`. A lot of machinery in the one crate that must stay
  light.
 - **A fingerprint in the link plus an unauthenticated `GET /ca.pem`.**
  Small code, but it needs a first connection with verification disabled,
  and it breaks a documented, tested posture -- `auth.rs`'s "gates every
  route with zero unauthenticated endpoints", which is a load-bearing
  decision rather than an implementation detail. Not something to change
  silently for this.
 **What it costs**, measured rather than guessed: on this project's P-256
 CA the link goes from 89 bytes to 652, and `print_enrollment`'s terminal
 QR from 45x23 to 93x47 characters. That is why the parameter is the
 minter's choice per call: `ai-server` passes it (its iris client needs it),
 `dev-updater` passes `None` (its app is built on the machine it talks to,
 and its QR stays scannable in an 80-column terminal). The URI printed under
 the QR is the fallback either way, and is the path Dev Updater's Enroll
 button already uses -- it opens the link with `ACTION_VIEW`, so Android
 offers whichever apps registered the scheme, which needed no change here.
 The CA is a public certificate, so putting it in the QR leaks nothing the
 token did not already: photographing the terminal still costs exactly the
 token, which is rotatable.
 **The log upload's destination is moot**, so it is not wired to this. On
 the same day Iris decided Dev Updater will read an APK's runtime log from
 an on-device ContentProvider instead, which removes `log_upload`,
 `POST /client-log` and the `AI_APP_LOG_*` baking altogether -- so the
 enrolment landed without touching any of them, for that change to delete
 whole.
@@ -8,6 +8,573 @@ 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-07: iris runs on a GLES-only Android device, and reports the renderer it cannot build
 `AndroidRenderer::new` asked wgpu for `Backends::PRIMARY`, which does not
 include `GL`. A device that offers a Vulkan driver with no adapter behind
 it -- this checkout's emulator -- therefore had no adapter at all, and the
 `.expect` on that turned into a crash loop with nothing on screen. It now
 probes for a `PRIMARY` adapter first and falls back to `Backends::GL` when
 there is none, so **Vulkan still wins wherever it has an adapter** and
 nothing changes on a phone.
 The probe deliberately runs on an instance that never touches the window:
 an Android window can be connected to one graphics API only, so an
 instance carrying both backends lets Vulkan claim the window and leaves
 the GLES surface unusable. That is why this is a second instance rather
 than one wider `Backends` value.
 The other half a caller sees: `AndroidRenderer::new` already returned
 `Result<Self, String>`, and now **every** way it can fail goes through
 that -- no surface, no adapter, no device, as well as the bind-group
 validation failure it was originally written for. `surface_changed` puts
 that string on screen and in the log ring instead of aborting.
 ## 2026-09-07: `VelocityTracker` takes positions, not deltas
 A flick released at the wrong speed because the tracker averaged. It now
 does what Compose's touch scrolling does, and that changes what a caller
 feeds it.
    // before -- one frame's motion
    tracker.add_sample(dy, now);
    // after -- where the finger was
    tracker.add_position(pos.axis(axis), now);
 `VelocityTracker::velocity` is a port of Compose's `VelocityTracker1D`
 with `Strategy.Lsq2`: a degree-2 least-squares fit through the last 20
 positions, differentiated at the newest sample, with Compose's 100ms
 horizon, 40ms stopped-gap and three-sample minimum. Positions rather than
 deltas because a fit needs points on a curve -- Compose itself throws on
 differential data for this strategy.
 Three consequences a caller sees. **A gesture with fewer than three
 samples answers `0.0`**, where the average answered a number from two;
 that is Compose's answer too, and on the phone a 120Hz flick delivers
 four or five. **A finger that rests for more than 40ms before lifting
 answers `0.0`** rather than flinging at the speed it arrived with.
 **`add_position` must be called in time order** -- the same debug assert
 as before, now load-bearing for the fit's x-axis.
 Also new: `VelocityTracker::samples_display` (the held samples as
 `t_ms:position`, printed by `DragGesture` at debug level so a flick
 reported from a phone can be replayed), `DragArbiter::axis`, and
 `sense::MAX_FLING_VELOCITY_DP_S` (8000, `ViewConfiguration`'s own).
 `List::fling` now applies that maximum against its own density and
 ignores anything at or under 1px/s, which is Compose's pair of thresholds
 exactly -- there is deliberately no 50dp/s minimum, because Compose's
 scrolling never consults the one in `ViewConfiguration`.
 ## 2026-09-07: `client-core` carries the app's own log
 Not iris itself but the crate beside it, and it is a new public surface an
 app author will use: `client_core::log_ring`. Because Iris's phone has no
 `logcat`, an app now keeps a bounded copy of its own log and hands it to
 Dev Updater on the device.
 Before, an app installed a platform logger and that was the end of it:
    android_logger::init_once(config);           // Android
    // nothing at all on the desktop
 After, the platform's logger becomes the *inner* logger of a ring that
 records everything alongside it -- `logcat` and a terminal see exactly
 what they saw before:
    client_core::log_ring::install_process_logger(
        Box::new(android_logger::AndroidLogger::new(config)),
        LevelFilter::Debug,
    )?;
    let ring = client_core::log_ring::process_ring();   // 2000 lines / 256 KiB
    ring.to_text();                                     // for a report
    ring.summary();                                     // "1801 lines held, 12 dropped, last 20:09:24"
    // and, for whatever hands the log out of the process:
    let (lines, next) = ring.since(cursor);   // inclusive of `cursor`
    ring.newest_seq();                        // None for a ring nothing was written to
 `process_ring` is a deliberate process-global, unusually for this project:
 `log` already has exactly one backend per process, and a ring passed around
 as a parameter would be a second answer to "which lines exist".
 **Amended later the same day.** `client_core::log_upload` and
 `ai-server`'s `POST /client-log` are **gone** -- an app no longer sends
 its log anywhere. It exposes it on the device instead, and Dev Updater
 reads it there: on Android that is a `ContentProvider` at
 `<applicationId>.devlog`, which is Dev Updater's own contract (its
 `README.md`, "An app's own log") rather than anything iris-specific.
 `LogRing::newest_seq()` is the one addition that went with it: a reader
 holding a cursor uses it to notice the process **restarted**, since the
 ring is in memory and a new process starts again at sequence zero.
 The reasoning and the rejected alternatives are in docs/DECISIONS.md,
 2026-09-07.
 ## 2026-09-07: `TextData` no longer bundles a font
 Iris's call: "remove the font for now; just match what compose does."
 `TextData::default()` used to embed six Noto Sans/Noto Sans Mono `.ttf`s
 (3.6 MB, `include_bytes!`) and register them ahead of the platform's own
 fonts in the `SansSerif`/`Monospace` fallback lists. That registration is
 gone; `TextData::default()`'s signature is unchanged, but what it produces
 now depends entirely on `fontique`'s platform discovery (already on by
 default, previously shadowed) -- Roboto/Roboto Flex on Android, whatever
 the desktop's fontconfig resolves on Linux. No caller-visible type or
 method changed, but every consumer of `iris-core` text now renders with
 whatever the host platform's fonts are, not a fixed bundled face -- worth
 knowing if you were relying on pixel-identical text across devices.
 `.so` shrank by 3.75 MB. One real gap surfaced by the switch: this
 fontique version's Android backend never resolves the `Monospace`
 generic family (a fontique ordering bug, not new in this change), so
 `Family::Monospace` text falls through to the same face as
 `SansSerif` on Android rather than a true monospaced one -- still
 visible, not blank, just not monospaced. docs/RUST.md's "Platform fonts
 (2026-09-07)" has the full account.
 ## 2026-09-07: a headless harness, replayed touch, and physical-pixel desktop layout
 Layer 1 and 2 of docs/RUST.md's "Three test layers".
 **New: `iris::harness`** -- a screen driven in-process with no window, no
 compositor and no GPU, on a clock the caller advances. `Harness::new(size,
 density)` gives you an `Rsc`, a `UiRenderState` and a state that
 implements `FocusHost`/`OpenUrl` by *recording* what the platform was
 asked for (`keyboard_shown`, `opened_urls`) rather than doing it;
 `frame(t_ms)`/`frames_until(..)` run frames, `touch(action, pos, t_ms)`
 feeds one pointer sample the way Android's `on_touch_event` does, and
 `replay(&TouchScript)` runs a whole recorded gesture. `TouchScript` parses
 a plain `t_ms action x y` file (`down`/`move`/`up`/`cancel`), so the
 batched 120Hz flick shape your phone actually delivers is a file that
 `cargo test` can replay -- something the emulator cannot produce at all.
 **New: `List::fling_velocity() -> Option<f32>`**, what the release
 measured, readable where it landed rather than by re-timing the gesture.
 **Changed: `List` starts a fling's curve at its first `tick_fling`, not
 at the release.** The only clock it reads is now the one its driver hands
 it; in a running app the difference is at most a frame.
 **Changed: the desktop backend lays out in physical pixels with a
 density, exactly as Android does.** `iris::default::content_scale(window)`
 is the desktop's `content_scale` -- winit's scale factor, overridable with
 the `IRIS_SCALE` environment variable -- and it now feeds
 `UiRenderState::set_density`/`TextData::density` instead of dividing
 coordinates into a separate "logical" space. That division had
 `UiRenderState::resize` (physical) and the window uniform (logical)
 disagreeing on any display whose scale factor is not 1.0, and rasterised
 glyphs at one resolution to display them at another. `Input::event` lost
 its `scale_factor` parameter as a result, and `DefaultUiState::
 window_size()` now answers physical pixels. On a 1.0 display nothing
 changes. The override is what lets `run-headless.sh --phone` open a window
 at your phone's own 1080x2424 and 2.55.
 ## 2026-09-07: the fling curve was the identity function
 You said the fling "seems to just be linear velocity with an abrupt stop."
 It was, exactly: `android_fling_spline`'s lookup returned `t` for every
 `t`. Two halves of AOSP's spline build loop had been transposed, which made
 its two tables identical, and the lookup interpolated one against the
 other -- which reduces algebraically to `t`. So a fling coasted at its
 release speed for the whole (correctly computed) duration and stopped dead
 at the end of it.
 Ported exactly now from `OverScroller.java` and Compose's
 `SplineBasedDecay.kt`, which agree line for line. One public addition:
 **`FlingCalculator::velocity_at(velocity, elapsed) -> f32`**, beside the
 existing `position_at` -- AOSP's `mCurrVelocity` and Compose's
 `FlingInfo.velocity`. It is what makes "is this decelerating" answerable
 rather than inferred, and it is what `List::tick_fling`'s new
 `iris fling tick:` debug line reports each frame.
 The lesson worth keeping, since it cost two builds on your phone: every
 test the calculator had compared it with itself -- monotonic, correctly
 signed, integrates to the closed form, per-tick deltas non-increasing --
 and **all of them pass on a straight line**. The numbers now come from
 `iris/benches/fling_spline_reference.py`, a separate hand transcription of
 the two sources, checked in beside the tests.
 ## 2026-09-07: the Android insets bridge counts its own dispatches
 `AndroidUiState::insets_report() -> String` is new, and the bench app's
 Diagnostics pane shows it. It carries the last insets plus **how many times
 the platform has delivered any**, because "the keyboard did not push
 anything up" has two causes that look identical on screen -- the listener
 never fired, or it fired with a zero height -- and you have no logcat on
 the phone. `dispatches=0` prints a sentence saying so rather than the
 numbers, which would be defaults rather than measurements.
 ## 2026-09-07: widgets can animate, and a fling finally moves
 Iris's phone said "fling still doesn't work" twice. The velocity was only
 half of it: **nothing in iris advanced an animation between input
 events**, so `List::fling` stored a speed that nothing ever applied. Three
 public changes come out of fixing that.
 **`Widget::tick(&mut self, now: Instant) -> bool`** is a new trait method,
 defaulted to `false`, so no existing widget changes. A widget that
 overrides it is animating; answering `false` is how it stops.
 **`UiData::animate(id)` and `UiData::tick_animations(now) -> bool`** are
 the registry and its driver. A gesture that starts an animation registers
 the widget; each backend calls `tick_animations` once per frame before the
 draw and asks for another frame while it answers `true`. That answer is
 the *only* thing in iris that makes a frame happen without an input event,
 and an animation's path out is its own `tick` returning false -- nothing
 has to remember to unregister it.
    // before: the velocity was stored and never applied
    list(ui).fling(-v);
    // after
    list(ui).fling(-v);
    let id = list.id();
    ui.ui_mut().animate(id);
 The two calls are deliberate rather than folded into `fling`: the velocity
 is the list's business and whether anything animates at all is the frame
 loop's, and a caller driving its own frames (the benchmark, the headless
 tests) still calls `tick_fling` directly.
 **`FlingCalculator` needs the real display density, and its coefficient
 was wrong.** `new(density)` takes physical pixels per `dp` and the
 velocity handed to it must be in those same physical pixels -- the
 density does *not* cancel out, contrary to what that type's doc used to
 claim. Separately, `physical_coefficient` multiplied by the scroll
 friction (0.015) where AOSP multiplies by its own tuning constant 0.84, a
 factor of 56 inside an exponential. Together they gave an ordinary flick a
 **45-second** coast, which nobody could see while flings never animated.
 `List` reads its density from the painter now, and
 `a_flick_lasts_what_aosps_own_formula_says_it_does` pins the absolute
 numbers (0.59s and 621px for 3000px/s at density 2.75) against AOSP's
 formula -- the check every previous test could not make, because they all
 compared the calculator with itself.
 **`MOVE_CHAIN_LIMIT` is 64, not 16**, in `render_state.rs` and
 `shader.wgsl` alike. It bounds a walk so a cyclic `parent` cannot hang
 either side; it was never meant as a claim about tree depth, and the
 transcript screen's composer field sits 17 slots below the root. Past the
 bound both walks silently stop summing, so a widget draws and hit-tests
 short with nothing to say so; the CPU assert now prints the chain, so a
 cycle and a deep tree can be told apart.
 ## 2026-09-06: tool cards, `ToolState`, and a screen that knows whether its session is working
 `transcript_ui::tool` is new: a card per tool call, a group per run
 (P1b). Three things in the public surface follow from it.
 **`client_core::transcript_fold::ToolState`** is what a card colours
 itself by -- `Running`, `Deciding`, `Succeeded`, `Failed`, `NoResult` --
 built by `ToolState::of(&item, session_working)`. The pair it exists for
 is `Succeeded` against `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.
 Only the session's own status separates them, which is why `of` takes it.
 **`event_model::Event::ToolEnd` gained `is_error`** (`#[serde(default)]`,
 so an older transcript still parses), and
 `client_core::transcript_fold::TranscriptItem::ToolRun` gained `failed`.
 Without them a result was everything a card knew and a broken call drew
 exactly as confidently as one that worked -- the missing state, not a
 wrong one. Every construction site of both had to gain a field; the value
 comes from the CLI's own `tool_result`, read in one place
 (`import::tool_result_is_error`) by both the live translator and the
 import replay.
 **`TranscriptScreen::set_session_working(rsc, bool)`** is new, and is the
 only thing that writes it. Before: a card with no result was drawn the
 same whether its turn was still going or had been interrupted. After:
 only the *newest* row can say "running", because every row behind it
 belongs to a turn that has ended, and changing the flag redraws that one
 row rather than the screen. `TranscriptScreen::expand_tail_tools(rsc,
 bool)` joins it, answering whether there was a tool run to act on -- a
 group's expanded appearance is otherwise unreachable from anything that
 cannot press the screen.
 **`transcript_ui::row::build_row` now returns a `TailRow`** rather than an
 `Option<RowBlocks>`: `Blocks` for a message (a delta costs the last
 markdown block) or `Tools` for a run (an arriving result costs one card).
 One mechanism for "what can this row change cheaply", asked of the row
 rather than decided again at each call site. It also takes the row's own
 `working` flag.
 Two smaller ones. `client_core::tool_summary::parse_tool_input` is
 `ToolInput.kt`'s subject/description/timeout/rest split, and
 `client_core::durations::format_millis` is `Durations.kt`'s -- both pure,
 both with the Kotlin's own tests ported.
 ## 2026-09-06: a tap is its own gesture outcome, and opening a URL is a backend capability
 Three related additions, all for following a markdown link.
 **`iris::platform::OpenUrl`** is a new trait beside `attr::FocusHost`, and
 has the same shape: declared in `iris`, implemented once per backend (a
 detached `xdg-open`/`open`/`start` on the desktop, an `ACTION_VIEW` intent
 on Android, deferred to the next view callback exactly the way
 `pending_show_keyboard` is). A widget asks for the capability by bound --
 `Rsc::State: FocusHost + OpenUrl` -- instead of a caller threading a
 callback down through every builder. One method, not a general "run an
 intent": a narrower capability is a narrower thing to get wrong. Nothing
 is returned; the platform either shows a browser or does not, and both
 are outside the process.
 **`GestureOutcome::Tapped`** is new. `Released(None)` used to mean both
 "the press ended having selected something" and "the press ended having
 done nothing at all", and only the second is a tap. Any caller that acts
 on a tap -- following a link -- must not also act when the finger was
 panning the list past that link, so the distinction is made once, in the
 gesture machine every widget already shares, rather than timed again per
 widget. `DragArbiter::is_undecided()` is what answers it.
 `Selection::drag` returns the outcome now instead of `()`.
 **`DragArbiter`/`DragGesture` take an axis** (`::on(Axis)`; `::new()` is
 still vertical). A code fence pans across its own long lines exactly the
 way a transcript pans down its rows, and the two were the same state
 machine with `dx` and `dy` swapped. `WidgetLike::scrollable_on(axis)`
 joins `scrollable()` for the same reason. Before this, a horizontal
 `Scroll` existed but could not be dragged by a finger at all -- its
 arbiter only ever committed on the vertical axis.
 Two smaller ones in the same pass. **`TextEditCtx::byte_at(pos, size)`**
 answers which byte of the text a tap landed on, doing the same
 region-relative transform `select` does, without handing out the parley
 layout a caller could shape against stale text. And **`Rect::radius` now
 takes a `Len`**, so a corner can be written in `dp` and come out the same
 physical size on every display; a bare number still means physical pixels.
 **One behaviour change worth knowing about**: `Rect::is_size_independent()`
 answers `false` now. It answered `true`, and a `Rect` fills whatever
 region it is given -- so `draw_inner`'s fast path, which rewrites a
 widget's primitives in place instead of redrawing it, could not reproduce
 what `draw` would have done. A `.background(rect(..))` behind
 variable-height content kept the size of the provisional pass its parent
 `Span` had drawn it at, which on the transcript screen meant one code
 block's panel covering every block below it. Costs one primitive's redraw
 when a rect is resized.
 ## 2026-09-06: a transcript row is a column of blocks, and a block is the selection unit
 `transcript-ui`'s row builder used to make **one** `TextEdit` per message.
 It makes one per top-level markdown block now -- heading, paragraph,
 fenced code, list, table -- in a `Span::down`, because a streamed delta
 into a single buffer re-shaped the whole message through parley on every
 event. `client_core::markdown_blocks::split_blocks` does the splitting;
 `row::RowBlocks::apply_delta` updates the block a delta lands in and
 leaves the rest of the message's layout alone.
 **The change to judge, since it is what a reader feels**:
 `Selection` is keyed by `SelKey = (RowKey, u32)` -- a row and a block --
 so **a block, not a row, is the unit a selection steps in**. A drag still
 runs from a reply into the tool output beneath it and copies as one
 thing; what changed is that the row under the finger is filled in block by
 block rather than all at once, which is if anything closer to what the
 old shortcut in `Selection`'s module doc was apologising for. `register`
 takes a `SelKey`; `unregister` still takes a `RowKey` and now drops every
 block of it (dropping only the first is how a freed widget gets left in
 the map -- the shape docs/REVIEW-2026-09-06.md's finding 1 called out).
 `Selection::locate(ui, render, pos_window)` is new: which block is under a
 window position, with that block's own local position and size. The
 list-level handler uses it for the pointer-captured half of a drag,
 instead of computing a row-local position from `List::extent`.
 `row::build_row` returns `(RowKey, StrongWidget, Option<RowBlocks>)` --
 the third is the per-block state a caller keeps only for the row a reply
 is streaming into, and is `None` for a tool run, which never streams.
 ## 2026-09-06: a reported `Size` may not carry `dp`; `Len::fold_dp`
 **New: `Len::fold_dp(density) -> Len`** -- the same fold `apply_rest` does
 (`dp` becomes physical pixels), but staying a `Len` so `rest` survives.
 **New rule, and it is a rule about every widget, not about the two that
 broke it**: a `Len` a widget *reports* from `draw` must not carry an
 unresolved `dp`. `dp` is an input unit -- a number the widget author wrote
 -- and the containers that consume a reported length read `abs`, `rel` and
 `rest` straight off it (`Span`'s placement arithmetic, `Pad`'s addition),
 so a reported `dp` is silently worth **zero**. `MaxSize` and `Sized` both
 returned the caller's declared `Len` as written; a `.max_height(dp(168))`
 therefore gave its child a slot of nothing the moment the cap actually
 applied, which is what made the composer's bar collapse. Both put their
 declared lengths through `fold_dp` now, and
 `UiRenderState::draw_inner` `debug_assert!`s the invariant after every
 `Widget::draw`, so a widget that gets this wrong says so at the mistake
 rather than laying out at zero somewhere else.
 Nothing changes for a caller: `.max_height(dp(48))` is written the same
 way. It is only widget *authors* who now have a rule to follow, and a
 debug build that enforces it.
 ## 2026-09-06: `Painter::set_mask` reuses one slot; `ActiveData` gains two fields
 **`Painter::set_mask(region)` allocates its widget's mask slot once and
 rewrites it in place** on every later draw, instead of pushing a new one
 each time. It has to: `draw_inner`'s unchanged-region fast path does not
 revisit a descendant whose own region did not change, so those descendants
 go on referencing whichever slot they were first drawn under. Pushing a
 fresh slot per draw left the composer's field clipped to a box the bar had
 long since moved away from -- four live mask entries, none of them the
 `Masked`'s current region -- and it drew nothing at all. Same call, same
 signature; only the lifetime changed.
 **`ActiveData` gains `own_mask` and `move_applied`** (both public, since
 `ActiveData` is). `own_mask` is the slot above, `MaskIdx::NONE` for a
 widget that sets no mask. `move_applied` is how much of a widget's own
 move-slot delta its `region` already accounts for: `mov` shifts both,
 `Painter::reposition` shifts only the slot, and `resolved_region` -- and so
 every hit test -- has to subtract it. Without that a widget that had been
 panned had its *own* hit box at twice the pan while its descendants were
 correct, which made the composer's field untappable after a finger drag.
 ## 2026-09-06: `Scroll` pans on a finger drag, and a vertical drag in a focused text field no longer selects
 Three related public changes, all in aid of IRIS_TODO.md's "the composer
 has no touch-drag scroll".
 **`Scroll::drag(render, id, sense, pos_window, now)` is new**, and
 `WidgetLike::scrollable()` now registers it alongside the wheel handler it
 already registered -- so anything built with `.scrollable()` pans on a
 finger drag with no extra wiring at the call site. It goes through the same
 `sense::DragGesture` that `transcript-ui::Selection::drag` drives `List`
 with (arbitration, `DRAG_SLOP`, velocity, pointer capture), rather than a
 second copy of that widget's wiring: `DragGesture` owns the mechanics and
 each caller decides only what a committed pan *means*. `Scroll::amt()` is
 new too, the read-only pan position a test or a scroll indicator needs.
 There is deliberately **no fling** on `Scroll`. Unlike `List` it has no
 per-frame tick to animate one with (`List::set_redraw_handle`/`tick_fling`),
 and the areas it wraps today are at most a screenful, where Android does not
 fling either. The released velocity is dropped rather than approximated.
 **A vertical drag inside an already-focused `TextEdit` no longer extends a
 selection.** `iris::attr`'s `on_press` used to treat a focused field as the
 plain `click_or_drag` case -- every `Pressing` frame updated the selection.
 It now applies the same `DRAG_SLOP` rule the *unfocused* branch already
 applied: a press that moves past the slop vertically abandons its pending
 selection for the rest of the gesture, so the scroll area around the field
 gets the drag instead. Horizontal drag-to-select is unchanged, and a long
 press still starts a selection. This is Android's own `EditText` behaviour
 (a vertical drag scrolls; only a long press selects), and it is what makes
 "swipe up over the composer to scroll the transcript" work without dragging
 a highlight through the message you were typing.
 **`UiRenderState::orphaned_primitives()` is new**, and `update` now
 `debug_assert!`s (debug builds only) that nothing is orphaned. An orphan is
 a primitive still bound for the GPU that no live `ActiveData` names -- a
 copy nothing can move, clip or free. That was the doubled `Compacted:` row
 on the phone; see the same date's commit `76b1f99` and docs/RUST.md. The
 per-frame guard is a count comparison (O(active widgets)); the walk that
 names the offenders only runs when the counts disagree, because the walk is
 O(primitives) and made a debug build on a phone too slow to finish a
 benchmark run.
 ## 2026-09-06: a tap on a text field always leaves a caret
 `TextEditCtx::select` used to compare the tap position against the
 *laid-out text's* own box and set `selection = None` for anything outside
 it. A press only reaches `select` after being hit-tested to the widget, so
 that "outside" meant the field's own padding -- or, for an **empty** field,
 everything, since an empty layout is a zero-width box. So tapping an empty
 composer focused it and opened the keyboard while leaving no caret, and
 `TextEditCtx::insert`/`insert_str` return early with no caret: every
 keystroke was dropped in silence, and no glyph ever appeared. Parley's
 `from_point`/`extend_to_point` already clamp a point outside the layout to
 the nearest cursor position, which is also what a tap in a field's padding
 should do.
 Behaviour change a caller would notice, in one line: **`select` with a
 non-drag position now always produces a selection; it no longer clears
 one.** Clearing is `TextEditCtx::deselect`, which is what the backends'
 focus handling already calls. A drag is unchanged -- with no previous
 selection there is still nothing to extend, so it produces none.
 `insert_str` also gained a `debug_assert!` for the no-caret case, so an
 insert routed to an unfocused field fails at the mistake in a debug build
 instead of silently swallowing input.
 ## 2026-09-06: `List::anchor_position_display`## 2026-09-06: `List::anchor_position_display`, `FrameReport::mark_phase`/`phase_stats`/`late_at_hz` (RUST.md's "Benchmark v2")
 `List` gained `anchor_position_display(&self) -> String`, reporting the
 anchor's own row index and pixel offset (`idx=N/off=Mpx`, or
 `idx=more-before`/`idx=more-after`/`idx=none`) -- what a scripted
 benchmark reads to report fling travel. Note the anchor does not
 necessarily change *slot* over a long scroll (this widget's own documented
 design: the anchor is a stable identity, not re-derived from what's on
 screen each frame), so this is not the same measurement as a Compose
 `LazyListState.firstVisibleItemIndex`, which does track the true topmost
 visible row -- the `off` half is what actually reflects how far a fling
 travelled.
 `iris_core::render::frame_report::FrameReport` gained three methods for
 per-phase benchmark reporting: `mark_phase(name)` records a named phase
 boundary at the current frame/instant; `phase_stats(now, refresh_hz)`
 returns one `PhaseStats` (frames, wall duration, late count/percent,
 p50/p90/p99, worst) per marked phase, sliced from the existing ring by a
 new parallel `index_ring`; `late_at_hz(refresh_hz)` gives the whole run's
 late count/percent judged against an arbitrary refresh rate rather than
 the fixed 60Hz `JANK_THRESHOLD` every existing caller still uses (a
 separate method, not a parameter on `report()`, so nothing else changes
 behaviour). `RING_CAPACITY` grew 4096->16384 to hold a full multi-phase
 run without evicting earlier phases' samples.
 ## 2026-09-06: `List::fling`, `VelocityTracker`, `FlingCalculator` (IRIS_TODO.md's "swiping has no momentum")
 `iris::widget::List` gained a real fling: `fling(velocity_px_per_s)` starts
 one (cancelled by the next touch-down via `cancel_fling`, or automatically
 once it settles or reaches loaded content's start/end), `is_scrolling()`
 reports whether one is running, and `tick_fling(now: Instant) -> bool`
 advances it and returns whether it is still going -- a caller that owns a
 `RequestRedraw` handle can hand it to the list once via the new
 `set_redraw_handle`, after which `List` re-arms its own next frame while
 flinging with no further polling needed; a caller driving a scripted
 benchmark instead calls `tick_fling` itself in a loop, same as it already
 drives `scroll`.
 The physics is `iris::sense::FlingCalculator` + `VelocityTracker`
 (`sense.rs`, beside `DragArbiter`): a port of AOSP `SplineOverScroller`'s
 deceleration curve (the same one Compose's own `ScrollableDefaults.
 flingBehavior()` uses), cited at the definition, so a fling here travels
 the same distance a Compose `LazyColumn` would for the same initial
 velocity. `VelocityTracker` estimates that velocity from the drag's last
 ~100ms of samples rather than one frame's last delta. Unit-tested:
 velocity from known samples, fling distance/duration against the closed-
 form spline result (within 1%), cancel-on-touch, and the start/end clamp
 (a fling stops rather than scrolling into content that was never loaded).
 Before: a touch-drag panned exactly as far as the finger moved and stopped
 dead on release. After: releasing mid-drag continues scrolling and
 decelerates, matching the muscle memory every other Android scroll view
 already trained. `transcript_ui::selection::Selection::drag` wires this in
 -- a release only flings if the gesture had committed to panning
 (`DragArbiter::is_panning`, new), never a selection or an undecided tap.
 ## 2026-09-06: `UiRenderNode::new` returns `Result`, not `Self` (RUST.md's P0 box, phone-crash fix)
 `iris_core::UiRenderNode::new(device, queue, config)` now returns
 `Result<Self, String>` instead of `Self`. Why: it used to let a bind-group-
 layout validation failure reach wgpu's default error handler, which panics
 with no way for a caller to intervene -- exactly what aborted the P0 bench
 APK on Iris's phone with the crash report truncated to "wgpu error:
 Validation Error" and nothing else recoverable. It now runs its creation
 calls inside wgpu error scopes and returns the full error text (wgpu's own
 "Caused by" chain) as `Err` instead.
 Both callers changed to match: `android::render::AndroidRenderer::new`
 itself now returns `Result<Self, String>` too, building a fuller report
 (adapter identity, the limits/downlevel flags a layout validates against,
 then wgpu's text) on failure -- its caller,
 `android::view::IrisViewPeer::surface_changed`, logs that report as one
 logcat line and shows it on screen (a new `IrisView.showRendererError`,
 called via an ordinary JNI method call rather than a new `native fn`)
 instead of letting the process abort. `default::render::UiRenderer::new`
 (the winit/desktop backend) still panics on failure -- there is no
 on-screen fallback there -- but the panic message is now the same full
 text rather than whatever wgpu's own handler would have printed.
 No change for an app that never constructs a `UiRenderNode` directly (every
 current one goes through `AndroidRenderer`/`UiRenderer`), but anyone who
 does needs an `?`/`.expect()`/`match` at the call site now. Full audit and
 the named hypothesis for what actually failed on the phone are in
 RUST.md's P0 box, "iris bench crash on the phone, 2026-09-06."
 ## 2026-09-05: `AndroidAppState::platform_ready` (RUST.md's P0 box, iris half)
 Added a second, optional lifecycle method to `iris::android::AndroidAppState`
@@ -437,3 +1004,255 @@ with a number instead of a guess (RUST.md's I5 box).
  blocked handing the frame to the driver," not a confirmed GPU-completion
  time. Enough to separate "iris is slow building the frame" from "iris is
  slow handing it off," not enough to claim an exact GPU budget.
 ## 2026-09-05: `List::replace_back`/`List::clear`, and `TranscriptScreen::apply`
 Fixes the "every client refolds and rebuilds the whole widget tree per
 streamed event" cost RUST.md's P0 box measured (20 events/second against a
 ~3,200-row transcript). Two small additions to `iris::widget::List`
 (`iris/src/widget/list.rs`), plus one new method on `transcript-ui`'s
 `TranscriptScreen`.
 - **`List::replace_back(row: ListRow) -> Option<ListRow>`**: swaps the
  *last* row's widget for a new one without moving it — same slot index,
  so an anchor already pinned there (in particular a list flush with its
  own end) stays pinned, and a `List` scrolled elsewhere is untouched.
  `None` if the list is empty. `RowKey` may differ between the old and new
  row; only `heights`/`extents` care, and both are invalidated for the
  evicted key the same way `pop_back` already does.
 - **`List::clear()`**: drops every loaded row and resets to `List::new`'s
  state (`more_before`/`more_after` untouched — a caller that wants those
  cleared too calls `set_more_before(None)`/`set_more_after(None)` itself).
  The fallback path for a change that touches more than the tail.
 - **`transcript_ui::TranscriptScreen::apply(&self, rsc, old: &[TranscriptItem], new: &[TranscriptItem])`**:
  the incremental alternative to rebuilding the whole screen from
  `transcript_ui::build_tree` on every folded event. Diffs the two
  `group_tool_runs` outputs and picks the cheapest update: nothing changed
  (no-op), a pure append (`push_row`, unchanged cost), or — the common
  streaming case, a delta into a still-open assistant message — a rebuild
  of just the one changed row via `List::replace_back`, with any further
  new rows appended after it. A row changing *before* the tail (only
  `group_tool_runs` retroactively grouping tool calls into a run does
  this) falls back to `List::clear` plus a full rebuild, counted in
  `TranscriptScreen::take_rebuilds()`. **A caller that keeps its own
  row-keyed side table alongside `List` (`Selection`'s `rows:
  BTreeMap<RowKey, WeakWidget<TextEdit>>` is the one this crate has) must
  clear it in step with `List::clear()`** — the fallback drops every row
  `List` was holding, so any side table not cleared the same way is left
  pointing at widgets the clear just freed (docs/REVIEW-2026-09-06.md
  finding 1, fixed 2026-09-06 by `Selection::clear()`, called from
  `apply`'s `Rebuild` arm right before `List::clear()`). `bench_client.rs`, `transcript_client.rs`
  and `desktop-app/app.rs` all call this now instead of rebuilding on every
  event; only the opening page (and `apply`'s own fallback) still calls
  `build_tree`.
 - **`TextEditCtx::set_with_spans(text, spans)`**: `set()` plus a fresh
  `Vec<SpanStyle>` in one call, needed because a streamed row's markdown
  re-renders to both a new string and a new span list on every delta and
  the two have to land together — a stale span list drawn against new
  text can point past its end. `set()` itself is unchanged (still clears
  spans to none, as before).
 Measured on this checkout's emulator (`iris/android-app/run-bench.sh`,
 release, x86_64, `force-gles`): worst-frame and p99 during the streaming
 phase dropped from 369.3ms/284.5ms (full rebuild per event, prior pass) to
 ~101–130ms/~76–103ms across three runs (this fix) — see RUST.md's P0 box
 for the full numbers and the comparison's caveats (different AVD
 instances, not a controlled A/B on identical hardware state).
 ## 2026-09-06: bundled fonts, `content_scale`, `AndroidAppState::on_insets_changed`
 From RUST.md's P0 box, working Iris's first real-phone report (font/scale/
 inset bugs the emulator never showed).
 - **`TextData` now bundles Noto Sans + Noto Sans Mono** (regular/bold/
  italic/bold-italic static faces, OFL) and registers them ahead of the
  platform's own fonts in the `SansSerif`/`Monospace` generic-family
  lists, rather than relying on the platform's font enumeration alone.
  `TextData::font_diagnostics() -> FontDiagnostics` reports what was found
  and what each style axis resolved to — logged once at startup and shown
  on a screen's Diagnostics page if it has one. Adds ~3.6 MB uncompressed
  to any binary linking `iris-core`; `build-apk.sh`'s own output says the
  delivered (compressed) number.
 - **`UiRenderNode::new`/`resize` now take the window size explicitly**
  (`window_size: impl Into<Vec2>`) instead of deriving it from the
  surface's physical `SurfaceConfiguration`. Existing callers pass a
  *logical* size (physical ÷ density/scale-factor) now; this is what makes
  a `font_size: 16.0` 16 dp instead of 16 raw device pixels on a
  high-density phone. Before this, `scale_factor` did not exist anywhere
  in the crate, on either platform.
 - **`AndroidUiState::content_scale: f32`** (`DisplayMetrics.density`, read
  once in `new_peer`) and the desktop equivalent (`window.scale_factor()`)
  now divide every physical-pixel number before it reaches layout or
  touch handling — see `content_scale`'s own field doc for the full list
  of what depends on it.
 - **New: `AndroidAppState::on_insets_changed(&mut self, rsc, LogicalInsets)`**,
  a default-no-op hook called from `render()` exactly when
  `AndroidUiState::insets()` changes. Nothing previously consumed
  `insets().top` at all; a screen with chrome under the status bar
  implements this to pad it, in the same logical units `content_scale`
  converts everything else to.
 - **New: `iris_core::WgpuErrorLog`**, installed via `Device::
  on_uncaptured_error` on the Android device (wgpu's default handler is an
  unconditional panic outside `UiRenderNode::new`'s own error scopes).
  Explicit `Arc`-backed value passed to the callback and kept on
  `AndroidRenderer`, not a global — a caller wanting one on desktop builds
  its own the same way.
 ## 2026-09-06: `Len::dp`, physical pixels throughout, the keyboard glyph wipe
 Iris's phone report on build a9232ac (screenshots): text now the right
 size but blurry; the keyboard still wipes every glyph; the header buttons
 have nothing behind them. All three are fixed; this entry is the public
 API side. docs/LAYOUT.md has the layout-side writeup, docs/RUST.md's P0
 box has the full investigation and the phone verification still to do.
 - **The keyboard wipe was `surface_changed` rebuilding the whole renderer
  on every resize**, including an IME-driven one — a fresh, empty glyph
  atlas while the CPU-side glyph cache kept UV coordinates from the old
  one. `surface_changed` now calls `AndroidRenderer::resize` (reconfigures
  the surface and window uniform only) when a renderer is already live,
  and only builds a new one when there genuinely isn't one yet.
 - **`Len` has a third field, `dp`** (Android's dp / CSS's reference pixel,
  1/160in), beside the existing `abs` (now explicitly *physical* pixels)
  and `rel`/`rest`. `len_fns::dp`/`Len::dp` construct one, used exactly
  like `abs`/`rel`/`rest` — `dp(16)` instead of a bare `16` wherever a
  size should look the same physical size on any density. This is the
  unit IRIS_TODO.md's "density-independent length unit" item asked for;
  it replaces the previous stopgap (the whole rendered scene divided by
  `content_scale` then implicitly stretched back up), which is also what
  made text blurry — a glyph rasterised at the small, pre-stretch size and
  then upscaled onto the real framebuffer.
 - **`UiRenderState`/`Painter` gained `density()`/`set_density()`** (physical
  pixels per dp). Every place a length resolves (`Len::apply_rest`,
  `Size::to_uivec2`) now takes it; `Span::gap` and `Padding`'s four sides
  moved from a bare `f32` to `Len` so they take `dp(...)` too. A bare
  number anywhere is unaffected — still `abs`, physical pixels.
 - **Text is rasterised at physical resolution now.** `TextBuffer::shape`
  takes `density` and multiplies `font_size`/`line_height` (and any span
  override) by it before handing them to parley, so the atlas holds a
  bitmap at the size it is actually shown at rather than a low-resolution
  one stretched afterward.
 - **Everything at the Android boundary is physical pixels now** — window
  size, touch coordinates, insets (`LogicalInsets` renamed
  `WindowInsets`). The previous "logical" division by `content_scale` is
  gone; `content_scale` now feeds `set_density` instead.
 - Not yet verified on Iris's actual phone (this pass had no device) —
  built and checked on this checkout's emulator only. RUST.md's P0 box
  says what she should check for: crisp text at two densities, the
  keyboard no longer wiping, and the header's background.
 ## 2026-09-06: composing text, focus-on-tap, and atlas invalidation on a new renderer
 Three small but public API changes, from the same phone-report pass as the
 entry above (RUST.md's P0 box has the full account, including a real bug
 still not root-caused).
 - **`FocusHost` gained `is_focused(&self, id) -> bool`** (both platform
  impls). `attr.rs`'s `Selector`/`Selectable` used to grant focus (and so
  request the IME) on the very first frame of *any* press, before it was
  known whether the gesture was a tap or a drag — a swipe over a text
  field wrongly summoned the keyboard. They now wait for a completed tap
  (press and release with no frame crossing `sense::DRAG_SLOP`) unless the
  field is already focused, in which case dragging inside it to select
  text is unchanged. `TextEdit` gained one new `pub(crate)` field
  (`press_origin`) to track this; no public surface change there.
 - **`android::ime`'s `InputConnection` now calls `InputMethodManager::
  updateSelection` after every edit** (`IrisViewPeer::update_ime_selection`,
  called from `after_input`). Gboard was holding keystrokes back because
  nothing ever told it where the app's own selection/composing region had
  moved to — this is what android-view's own demo does in its `render()`
  and this bridge never did.
 - **`GlyphAtlas::clear()` and `Textures::reset()`** (`iris_core`). Called
  together, once, from `android::view`'s `surface_changed` exactly when a
  *genuinely new* `AndroidRenderer` is built (backgrounding and returning,
  not a keyboard-triggered resize, which already reuses the renderer) —
  both CPU-side caches otherwise kept pointing at the old, now-destroyed
  device's textures, which is why text used to vanish again after leaving
  and returning to the app.
 ## 2026-09-06: `take_counters` counts text layouts too
 One public API change, from the verification pass over the composer-scroll
 and per-block-row work (RUST.md's "Verification pass over Tasks A and B").
 - **`UiRenderState::take_counters` returns four numbers, not three**:
  `(draws, region rewrites, move writes, **text shapes**)`. The new one is
  bumped in `Painter::render_text`, which `TextView::render` only reaches
  on a cache miss, so it counts layouts actually computed rather than
  layouts asked for. Callers destructuring the tuple need one more `_`.
  It exists because a draw counter cannot answer the question the
  per-block transcript row was built for. A widget can be redrawn without
  re-shaping (the layout is memoized by width) and re-shaped without any
  extra draw, and re-shaping is the expensive half — so "a streamed delta
  costs one block" was, until now, argued from the code rather than
  measured. With the counter it is a test: one delta into a 100-paragraph
  reply shapes exactly **1** text layout, the same as into a
  one-paragraph one.
 ## 2026-09-07: `iris::diagnostics` -- a trace toggle for input/frame lines, gating four existing per-frame `debug!` calls
 One new public module and one behaviour change to four existing log
 lines, from Iris's "add another button to copy input event info ...
 instrument a lot of the code with timings" request (RUST.md's own
 section has the full account).
 - **`iris::diagnostics::set_trace(bool)`/`trace_enabled() -> bool`**, a
  process-global switch, off by default. It gates two new diagnostics
  (`sense::log_input_event`, one line per platform pointer sample under
  target `iris::input`; `diagnostics::log_frame`, one line per frame
  under `iris::frame`, with the frame number, the frame clock, time
  since the last input, layout/draw durations, `RedrawKind`, primitives
  on screen, and whether something is animating) and, as of a same-day
  review finding (D1), four *older* `debug!` lines that were previously
  unconditional: `android::view`'s two `render():` lines, `widget::
  list`'s `iris fling tick:`, `widget::text`'s `iris text render:`, and
  `sense`'s `iris drag release samples:`. Not `log::log_enabled!`/
  `log::set_max_level`, because the app installs its logger at
  `LevelFilter::Debug` already and the ring records everything that
  level lets through regardless of target — the gate has to live on
  this side. **Not wired to a control**: the Diagnostics pane is in
  `bench_client.rs`, off-limits while another agent had it open; this
  is the whole surface a button needs.
 - **`UiRenderState` gained `RedrawKind`, `frame_number()`, `epoch()`,
  `last_layout_duration()`, `last_redraw_kind()`,
  `active_primitive_count()`, `note_input(Instant)` and
  `time_since_input(Instant) -> Option<Duration>`** (`iris-core`). All
  read back by `log_frame`; `note_input` is called once from
  `SensorUi::run_sensors`, which both backends and the harness already
  share, so a frame's `since_input` is comparable across all three
  without either platform doing its own bookkeeping.
 - **`iris::harness::TouchAction` gained `word() -> &'static str`**, the
  inverse of its own `parse` -- what a caller (here, `Harness::touch`)
  hands the input logger so a `.touch` file and an `iris::input` line
  agree on one spelling of each action.
 - **`iris_core::Axis` gained `Debug`** — a one-line derive, needed to log
  which axis a drag committed to.
 - **`iris/benches/report_to_touch.py`** (new): turns a report's
  `iris::input` lines back into a `.touch` file, expanding inline
  historical samples into their own lines first. Round-tripped against
  the harness in `iris/transcript-fixture/tests/input_log_roundtrip.rs`.
 ## 2026-09-07: the phone app is told which server to talk to, and pins from the link
 Not an iris API change -- a client-facing one, in the crates around it,
 worth knowing because it changes what a build of the Android app *is*.
 - **An iris APK is no longer tied to the machine that compiled it.** It
  used to have the server's host, port, token and CA compiled in, which
  made a build good for exactly one emulator/server pair and put a token
  in the artifact. Now it registers `aiapp://enroll` like the Compose app:
  open the link (Dev Updater's Enroll button already offers it, and the
  phone asks which app should take it) and the app stores where to go and
  what to trust.
 - **The CA rides in the link** as `&ca=<base64url DER>`, which is what
  makes the above possible at all -- a pinned certificate cannot be baked
  into an APK cross-compiled somewhere else. Optional, so the projects
  that do build on their own machine keep the short link and the small QR.
  docs/DECISIONS.md, 2026-09-07, has why not a fingerprint.
 - **`client_core::config` now holds the storage as well as the parsing**:
  `EnrolledServer` gained an optional `ca_pem`, and `EnrollmentStore` (the
  0600 JSON file, moved out of `desktop-app`) is one implementation for
  both the desktop and the phone -- only the directory differs.
  `desktop-app --ca` is now the override for a link that carried no CA
  rather than a required flag.
@@ -117,6 +117,375 @@ order and what "done" looks like. Tick and date them in place.
  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
@@ -306,22 +675,31 @@ order and what "done" looks like. Tick and date them in place.
    `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.**
+  - [x] **A tappable link** — done 2026-09-06 (P1a). `TextEditCtx::
-    Both need per-range glyph geometry that `TextEditCtx` does not expose
+    byte_at(pos, size)` answers which byte a tap landed on without
-    outside `iris::widget::text` (`edit.rs`'s `layout()` helper is
+    handing out the parley layout, `GestureOutcome::Tapped` says the
-    private) — see `markdown.rs`'s module doc for the exact shape the fix
+    press committed to neither a pan nor a selection, and
-    would take (the same primitive `TextEdit::draw`'s own selection
+    `iris::platform::OpenUrl` is the capability each backend implements
-    highlight already uses internally,
+    (`xdg-open`/`open`/`start`; an `ACTION_VIEW` intent on Android,
-    `iris/src/widget/text/edit.rs:99`).
+    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.
-  - [ ] **No syntax highlighting inside a fenced code block.**
+  - [x] **Syntax highlighting inside a fenced code block** — done
-    `client_core::highlight` exists (built for the file explorer) and
+    2026-09-06 (P1a). `client_core::highlight::spans_of` by language,
-    could feed per-token `SpanStyle`s into a code block's span; wiring it
+    converted from its char indices to `SpanStyle`'s byte offsets, in
-    in was not attempted this pass.
+    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
@@ -341,6 +719,109 @@ order and what "done" looks like. Tick and date them in place.
  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
@@ -385,3 +866,249 @@ do not duplicate it there.
  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)
 - [x] **"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.
  **Done, e922b73 + d507ae4.** Three causes, and the rule above is what
  they are all fixed with (`List::intersects_viewport`).
  `iris/transcript-fixture/tests/top_edge.rs` is the layer-1
  reproduction -- the real screen under a bench-app-shaped header --
  and each test was confirmed to fail on its own subject and no other.
  1. *Drawn over the header*: **nothing was clipping the list at all**,
     and a row straddling an edge is drawn in full, so the part above
     the list was on screen. It could not be `.masked()` before, either:
     `Painter::set_mask` aborted when an ancestor already had a mask,
     and the list's own rows use `.masked()` (a code fence, a tool
     card's title). So masks nest now -- `Mask::parent`, walked in the
     fragment stage, chained rather than intersected on the CPU because
     each mask moves with its own widget. `the_list_is_clipped_to_its_
     own_box`.
  2. *Rows already scrolled past still drawn*: the layout walk runs from
     the anchor, `scroll` moves the anchor's offset and nothing else, so
     panning leaves the anchor's row further and further outside the
     viewport and **every row between it and the viewport was drawn,
     every frame** -- measured at 64 rows for a 2012px viewport after 8
     scrolls of 3000px. `place` skips a row whose known box does not
     overlap, and `rehome_anchor` puts the anchor back on a visible row
     each frame without moving anything drawn.
     `rows_that_have_left_the_viewport_are_not_drawn`.
  3. *The blank band*: not a culling rule at all -- the list could rest
     **past its own first row** (`fling_toward_the_start_stops_at_the_
     first_row` was leaving it 1398px below a 600px viewport, a blank
     screen, and that test's own assertion could not see it).
     `clamp_to_content` gives the gap back. Both ends:
     `scrolling_past_the_first_row_settles_on_it`,
     `scrolling_past_the_last_row_settles_on_it`. This is also the first
     item of the later report below.
  What was suspected and is *not* what happened: the visible-range test
  never compared a row's top against the viewport's top (there was no
  culling test at all), and `03c6be8`'s header duplicate is untouched by
  any of this -- it stays open. A row straddling the top edge is drawn
  both before and after; the test that would catch that mistake
  (`the_row_across_the_top_edge_is_drawn`) is in place, and fails if the
  rule is written against the row's top instead of its bottom.
 ## From the phone, 2026-09-07, later (build from 4274b8b, ai-app-bench b47eb73)
 - [x] **"You shouldn't be able to scroll below the bottom (or above
  top)."** Done in e922b73, as `List::clamp_to_content` rather than as a
  clamp inside the scroll setter: nothing at the moment of a `scroll`
  call knows where the content ends (that is what walking the rows finds
  out), so the correction is measured from the ends the layout walk
  already placed and written to the anchor. In the app that lands in the
  same frame -- a scrolled list is dirty, and `redraw_updates` drains
  the mark the correction sets before the frame is submitted -- so
  nothing displaced is displayed; only a full-tree redraw (a resize)
  could show one frame of it. A fling that reaches an end already ends
  there (`tick_fling`'s `hit_bound`), and now stops *on* the end rather
  than wherever the spline's last step had put it. Layer-1 tests at both
  ends, listed in the item above. The list's offset is not clamped to its content range while
  dragging and/or flinging. Compose's `LazyColumn` never moves content
  past its ends -- the overscroll *effect* on Android 12+ is a stretch
  drawn over clamped content, not a displacement. Clamp the offset in
  one place (`List`'s scroll setter, so drag, fling, page-in and
  programmatic scroll all go through it) and end a fling that hits the
  clamp. Test at layer 1: a drag past either end leaves the offset at
  the end; a fling into the end stops there.
 - [x] **"Flinging now actually works but is slower than Compose's
  immediately after releasing the flick (the slow down seems
  correct)."** Done; RUST.md's "The fling started too slow" has the
  derivation and the table. On `flick-120hz.touch` the release velocity
  goes from **12250px/s to 15250px/s**, and on an accelerating flick --
  the shape a real finger makes, and what the recording is too short to
  show -- from 1080 to 2445px/s. The curve was right; `VelocityTracker`
  was averaging total motion over the sample span, which cannot tell an
  accelerating flick from a steady drag.
  **Two things the plan for this item had wrong, both found by reading
  the sources rather than remembering them.** Compose's touch path is
  **not** `Strategy.Impulse`: `scrollable`/`draggable` release through
  the 2D `VelocityTracker`, which on Android is two
  `VelocityTracker1D(strategy = Lsq2)` over absolute *positions* -- a
  degree-2 least-squares fit, differentiated at the newest sample.
  Impulse is reached only by `DifferentialVelocityTracker`, for mouse
  wheel and trackpad. And there is **no minimum** fling velocity on that
  path: `ViewConfiguration.minimumFlingVelocity`'s 50dp/s is used only by
  `NestedScrollInteropConnection`, while `DefaultFlingBehavior` skips
  `abs(v) <= 1f` to dodge a NaN from the spline. So iris ports Lsq2, caps
  at 8000dp/s, and floors at 1px/s -- no 50dp/s threshold Compose does
  not have. `iris/benches/velocity_reference.py` is the independent
  transcription the checked-in numbers come from; the negative control
  (reverting to the average) fails exactly the seven tests about the
  estimator and none of the rest. The release log gains a debug
  `iris drag release samples:` line so a flick reported from the phone can
  be replayed at layer 1.
 - [~] **Input-event and timing report from the phone.** Iris: "add
  another button to copy input event info so that I can do some stuff
  manually and then send the event log to you ... instrument a lot of
  the code with timings so I can give you time reports through the
  same button." **Built on the log ring, 2026-09-07** (docs/RUST.md's
  own section): `iris::sense::log_input_event` (one line per platform
  pointer sample -- Android's `MotionEvent`, historical samples inline;
  winit's `WindowEvent`; the harness's `TouchScript` line) and
  `iris::diagnostics::log_frame` (one line per frame: frame number,
  the frame clock, time since the last input, layout/draw durations,
  `redraw_all`/`redraw_updates`/neither, primitives on screen,
  whether something is animating), both under
  `iris::diagnostics::trace_enabled()`, off by default because the ring
  is only 2000 lines / 256 KiB and both targets at 120Hz fill that in
  seconds. `iris/benches/report_to_touch.py` turns a report's
  `iris::input` lines back into a `.touch` file for layer 1/2 replay --
  round-tripped in `iris/transcript-fixture/tests/
  input_log_roundtrip.rs`. **Not wired to a button**: the Diagnostics
  pane is `iris/android-app/src/bench_client.rs`, open under another
  agent at the time this landed; `set_trace(bool)` is the whole surface
  a control needs. `docs/REVIEW-2026-09-07.md`'s D1 (the ring already
  drowned in per-frame `debug!` lines that predated this pass) is fixed
  in the same change -- see RUST.md's section for which four call
  sites.
 ## From the phone, 2026-09-07, night (build 92985ba, ai-app-bench bf2088b)
 Iris pasted a full Copy report (Mali-G715 Vulkan, 2.55, 120Hz). What it
 showed, beyond her words:
 - [ ] **"Sometimes when I try to catch it while it's still moving
  (particularly if I drag) then it fails to stop & snap to where finger
  is."** The report's release lines show catches ending as
  `v=-41`/`v=-274` pans, so the gesture *does* reach `Panning`, but the
  content under the finger does not follow it while the fling is still
  running and the slop has not been crossed. Compose: a down while
  `isScrollInProgress` stops the fling *at the down* and starts the
  drag immediately with no touch slop (`scrollable`'s
  `startDragImmediately = isScrollInProgress`); the content is pinned to
  the finger from the first sample. Port that: `PressStart` on a list
  with a live fling ends the fling on that sample and enters `Panning`
  without waiting for `DRAG_SLOP`; a release with no movement is then a
  `Released(None)`, not a tap (Compose does not deliver a click either).
  Layer-1 test on a flick followed by a down + small drag 150 ms later:
  offset tracks the finger sample-for-sample from the down.
 - [ ] **"The copy report button seemed impossible to hit until I hit the
  diagnostics one."** Not hit-testing: the button logged `iris bench
  report: nothing to copy -- run the benchmark first` six times and did
  nothing on screen. A control that silently declines is the UI_RULES
  failure "a failure is reported where it happened": Copy report must
  always copy something -- the diagnostics and the log with a first line
  saying no benchmark has run -- and never depend on another button
  having been pressed first.
 - [ ] **"The logs seem way too big to send in this message box, causes a
  lot of lag."** Two causes. (1) The ring was 1339 lines of `naga::front`
  / `wgpu_core` / `jni` DEBUG output with 4050 dropped: the ring logger
  accepts every crate at Debug, and the trace gate (992c472) only covers
  iris's own lines. The ring must take Debug only from `iris`/`client_core`
  targets when trace is on, and Info and above from everything else --
  one filter at the ring, not per callsite. (2) Copy report appends the
  whole ring. It should append the last ~150 lines and a first line
  saying "N earlier lines omitted; full log in Dev Updater's Runtime
  tab" -- the full ring is what the devlog provider is for.
 - [x] Keyboard: the report shows `ime_bottom=891 ime_visible=true` then
  back to 0 on the phone, so the insets now arrive with a height; the
  push-up was not reported broken this time.
@@ -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.
@@ -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.
@@ -0,0 +1,459 @@
 # Review, 2026-09-07 — `ba2afba..origin/rustify`
 Read-only review of the day's 24 commits: the glyph-atlas fix, the fling
 spline and Lsq2 velocity estimator, keyboard/IME insets and `targetSdk`,
 historical touch samples and the input clock, list culling / clamp /
 anchor re-homing, nested masks and `draw_again`, the headless harness +
 `transcript-fixture` + `rig-input`, desktop density, the release profile,
 platform fonts + the Android monospace patch, and the client-core log ring
 with `POST /client-log`.
 **Verified while reviewing** (working tree, which also carries three other
 agents' uncommitted edits — `iris/src/sense.rs`, `iris/core/src/ui/render_state.rs`,
 `iris/src/lib.rs`, `iris/core/src/orientation/axis.rs`, and an untracked
 `iris/src/diagnostics.rs`): `cargo fmt --check` clean in `iris/`,
 `client-core/` and `server/`; `cargo clippy --all-targets` clean in `iris/`
 and `client-core/`; `cargo test --lib -p iris` 101 passed, `cargo test -p
 transcript-fixture` 10 passed. The `iris` doctest target fails to link
 (`extern location for iris_core does not exist`) — a stale build artefact,
 not a code fault, but worth knowing before trusting `cargo test -p iris`
 as a whole.
 The work is unusually well documented and the two "a test that compared
 the code with itself" findings the authors made themselves are real and
 were fixed correctly. What follows is what is left.
 Counts: **5 defects, 7 risks, 3 tests that cannot fail in the bug's
 direction, 7 rule findings, 2 nits.**
 ## Fix pass, 2026-09-07 evening
 Every finding below carries a **Status** line. In summary: **13 fixed**
 (D1, D4, D5, R1, R5, R7, T1, T2, T3 and four of the rule findings and both
 nits), **6 moot or deferred** (D2, D3, R3, R4 and two rule findings, all
 of them in the phone-logging route that `06b8a1f` deleted or in files the
 devlog agent held open), and **2 not done on purpose** (R2, which waits on
 docs/LAYOUT.md's mask redesign, and R6, which needs Iris's own phone).
 The commits are `2ec0fee` (D4), `7e79ec1` (D5), `551c013` (R1), `e10582a`
 (T1-T3), `ff1d6ea` (R5, R7) and `a6a100e` (the rename and the nits). Each
 fix that the rig can express carries a test, and each of those was
 confirmed by breaking its subject on purpose -- the break is recorded
 beside the assertion, so the next reader does not have to re-derive it.
 ---
 ## Defects
 ### D1 — the app's own log ring is drowned by the same day's per-frame `debug!` lines, so the route built to get Iris's logs to her carries almost none of them
 `iris/android-app/src/lib.rs:132` installs the ring at `LevelFilter::Debug`,
 and `client-core/src/log_ring.rs:279` (`RingLogger::enabled`) returns
 `true` unconditionally by design, so **every `log::debug!` in the process
 lands in a 2000-line / 256 KiB ring**. In the same commit range that ring
 became the only way a line reaches Iris, three ungated per-frame `debug!`
 callsites are live:
 - `iris/src/android/view.rs:446` and `:509` — two lines *per rendered frame*.
 - `iris/src/widget/list.rs:576` — `iris fling tick:`, one line per fling tick.
 - `iris/src/widget/text/mod.rs:81` — one per text shape (many per frame while rows compose).
 **Failure scenario.** Iris flicks the transcript on a 120 Hz phone. That is
 ~240–360 debug lines a second; the ring's 2000-line bound is exhausted in
 **under ten seconds**, so by the time she presses `Copy report` every
 `log::info!` about what she was actually investigating has been evicted.
 The uploader makes it worse: it sends at most the ring per 10 s wake
 (2000 lines ≈ 200 lines/s) against ~350 lines/s produced, so it also runs
 permanently behind and pushes tens of KB/s of frame spam over the tunnel.
 Note that another agent has already built the right mechanism — the
 untracked `iris/src/diagnostics.rs` has `set_trace`/`trace_enabled`, a
 default-off gate, and its module doc states this exact problem in as many
 words. It gates `iris::input`/`iris::frame`; it does **not** gate the four
 callsites above.
 *Fix*: put `List::tick_fling`'s line and `view.rs`'s two `render():` lines
 behind `iris::diagnostics::trace_enabled()` (the mechanism that already
 exists for exactly this), and/or record into the ring at `Info` while
 leaving `android_logger` at `Debug`.
 **Status:** fixed in `992c472` (verified 2026-09-07: all four callsites, plus `sense.rs`'s drag-release samples line, now sit behind `iris::diagnostics::trace_enabled`, and `input_log_roundtrip` proves both directions).
 ### D2 — `POST /client-log` can make `ai-server` write an unbounded runtime log at an authenticated client's request
 `server/src/routes.rs:1473` bounds the **line count** (500) and nothing
 else. The route sits inside the router that applies
 `DefaultBodyLimit::max(32 * 1024 * 1024)` at `server/src/routes.rs:179`
 (raised for phone photos), so one request may carry 500 lines of ~64 KiB
 each, and each is re-emitted verbatim into `tracing`. There is no
 per-message cap on the server, no rate limit, and the runtime log
 `ai-server` writes is the file Dev Updater tails and never rotates.
 `MAX_MESSAGE_BYTES` (4096) exists only in the *client*
 (`client-core/src/log_upload.rs:33`), i.e. the server trusts a value the
 attacker controls.
 **Failure scenario.** A buggy client (a `log::debug!` in a loop is enough —
 see D1) or one holding a leaked bearer token posts 32 MiB every 10 s; the
 host's disk fills and every other component's log goes with it.
 *Fix*: give the route its own `DefaultBodyLimit` (the attachments route at
 `:175` is the precedent for a per-route limit) and truncate each `message`
 server-side to the same 4096 bytes rather than assuming the client did.
 **Status:** moot -- `POST /client-log` was deleted with the whole upload route (`06b8a1f`), the app hands its log to Dev Updater through an on-device ContentProvider instead. Nothing to bound.
 ### D3 — lines the ring drops before the uploader sends them vanish with nothing saying so
 `LogRing::since` (`client-core/src/log_ring.rs:169`) filters `seq >= cursor`
 and silently returns fewer lines when eviction has passed the cursor;
 `LogUploader::flush_once` (`:94`) then advances to whatever came back.
 `dropped` is counted (`log_ring.rs:109`) and shown in the *local*
 diagnostics pane, but it is never put in the upload body, and
 `ClientLogBody` has no field for it.
 **Failure scenario.** The tunnel is down for two minutes; the ring wraps.
 When it comes back, the server log jumps from `#812` to `#5106` with no
 line saying anything was lost. This is precisely the "unknown state
 sharing a value with the empty state" UI_RULES asks to design first, and
 the module doc for `dropped` claims it is "reported rather than inferred"
 — it is, but only on the half of the path nobody is reading.
 *Fix*: carry `dropped` (or `firstSeq`) in the batch and have `client_log`
 emit one `warn!` when the sequence is not contiguous with the last batch
 from that `source`.
 **Status:** moot -- `client-core/src/log_upload.rs` was deleted with the route (`06b8a1f`). Whatever the ContentProvider does about eviction is that design's question, not this one's.
 ### D4 — the input clock anchors on the first event's *own* time, so that event's historical samples are dated before the anchor: the ordering assert fires, and release silently collapses them onto one instant
 `iris/src/android/view.rs:628` takes the anchor as
 `(Instant::now(), event.event_time_nanos())` from the first `MotionEvent`
 the view ever sees, and `at()` computes
 `anchor_at + (sample_time - anchor_nanos).max(0)`. Historical samples of
 that same event are by definition **earlier** than its own `event_time`.
 **Failure scenario.** The first event this view receives is an
 `ACTION_MOVE` (the `DOWN` was delivered to another view, or the view was
 attached mid-gesture). Its historical samples are, say, 12 ms before
 `anchor_nanos`; `at()` clamps all of them to `anchor_at`, so the tracker
 receives three samples with identical timestamps, the Lsq2 fit is
 degenerate, and the flick reads 0 px/s. In a debug build the
 `debug_assert!(ht >= previous)` at `:653` fires first — but `previous`
 starts at `anchor_nanos` (`:651`), which is a value from a *different*
 event, so that assert is also the wrong comparison for the first sample of
 every later event.
 *Fix*: anchor on the earliest sample of the first event
 (`historical_event_time_nanos(0)` when `history_size() > 0`, else
 `event_time`), and seed `previous` from the previous event's last sample
 rather than from the anchor.
 **Status:** fixed in `2ec0fee`. The arithmetic moved into `sense::PointerClock`, which anchors at `now - (event_time - oldest_sample)` and carries the last sample seen *across* events, so the ordering assert compares against the previous event's last sample rather than the anchor. It lives in `sense` because `iris::android` is `cfg`'d out everywhere but the device: `sense_tests.rs`'s `the_first_events_batched_samples_are_dated_apart` reports `[0ns, 0ns, 0ns]` against the old anchoring.
 ### D5 — the "before" velocity quoted in four places is not what the reference script prints
 `iris/benches/velocity_reference.py`, run today, prints **12250 px/s** for
 `flick-120hz.touch`'s average and **12500 px/s** for "press and one move
 frame". Four places say 11750 for both:
 - `docs/RUST.md:900` (`flick-120hz.touch | 11750 px/s`)
 - `docs/RUST.md:905` (`press + one move frame | 11750 px/s`)
 - `docs/IRIS_TODO.md:1026`
 - `iris/transcript-fixture/tests/phone_screen.rs:55`
 `iris/src/sense.rs:1406` has the correct 12250, so the two halves of the
 same change disagree. The file that carries the wrong number is the one
 that says "every number below is printed by `velocity_reference.py` … do
 not 'fix' one by running the Rust and copying what it said". One of the
 two rows also being 11750 for a completely different sample set is the
 tell.
 *Fix*: replace 11750 with the script's own 12250 / 12500 in those four
 places, or say which run produced 11750.
 **Status:** fixed in `7e79ec1`. All four places now say 12250 / 12500, the 1.30x ratio becomes 1.24x, and RUST.md records where 11750 half came from (196 px over a 16.68 ms **60 Hz** frame rather than the recording's own 16 ms -- which explains the flick row and not the other one, so that one was copied).
 ---
 ## Risks
 ### R1 — every new invariant guard is a `debug_assert!`, and the phone runs release
 The five guards added today —
 `iris/src/widget/list.rs:1156` (a `List` must be inside a `.masked()`),
 `:1218` (`extents` holds only on-screen rows),
 `iris/src/android/view.rs:653` (historical sample ordering),
 `iris/src/sense.rs:1076` (`poly_fit_least_squares` sample count), and
 `iris/core/src/ui/painter.rs`'s doubled-`set_mask` check — are all
 `debug_assert!`. `docs/RUST.md` records that the bench APK **must** be
 installed as `release` on the emulator (the debug `libmain.so` is 325 MB
 and will not install) and Iris's phone gets release too. So none of these
 can fire on any build anybody actually runs; in release a `List` drawn
 without a mask silently paints over its surroundings again — the exact
 fault e922b73 was written to fix.
 *Fix*: for the two that are cheap and once-per-draw (`is_masked`, the
 extents check), consider a plain `assert!` or a one-shot `log::error!`, so
 the guard survives into the build the defect was found in.
 **Status:** fixed in `551c013`. `is_masked`, the `extents` check, `set_mask`'s doubled-call check, `Painter::glyphs`'s atlas generation and `List::fling`'s finiteness are `assert!`/`assert_eq!` now; `List::place`'s slot precondition, `poly_fit_least_squares`'s two, and `PointerClock::sample`'s ordering stay `debug_assert!` and say in a comment why. The layer-1 suites pass in `--release` as well as debug, which is what says the promoted ones do not fire on a real replayed flick.
 ### R2 — a straddling row is now invisible above the list and still tappable through the header
 Masks are applied in the fragment shader
 (`iris/core/src/render/shader.wgsl:203`); the CPU hit path
 (`UiRenderState::resolved_region`, `iris/core/src/ui/render_state.rs:709`)
 does not consult `masks` at all. Before today the top of a straddling row
 was drawn over the header *and* hit-testable there; now it is clipped away
 but still hit-testable, which is worse — a tap on "Run benchmark" can land
 on an invisible link in the row behind it. `docs/LAYOUT.md:1012` ("Hit-
 testing applies the shape") is design, not code.
 *Fix*: until LAYOUT.md's mask redesign lands, intersect a widget's hit
 region with its mask chain in `resolved_region`; the chain walk already
 exists on the GPU side.
 **Status:** not done, deliberately -- docs/LAYOUT.md's mask redesign ("masks reference a drawn primitive instead of copying a shape", `1121d7c`) is where hit-testing gets the shape, and intersecting a chain in `resolved_region` now would be a second mechanism to unpick. Pointer left here rather than a fix.
 ### R3 — three copies of one wire contract, none of them linked
 `client-core/src/log_upload.rs:28` (`MAX_LINES_PER_BATCH = 500`) and
 `server/src/routes.rs:1418` (`CLIENT_LOG_MAX_LINES = 500`) must agree, in
 different crates, with only a comment saying so; the body itself is built
 by hand with `serde_json::json!` on one side and parsed by a
 `#[serde(deny_unknown_fields)]` struct on the other. This project already
 has the mechanism for exactly this — `event-model`, a crate both `server`
 and `client-core` depend on precisely so "the app hand-mirroring it" stops
 happening (`server/Cargo.toml:16` says so).
 **Failure scenario.** Somebody raises the client's batch to 1000. Every
 upload now returns 400, the uploader retries the *same* batch from the same
 cursor forever, and the only sign is one line in a diagnostics pane on a
 phone.
 *Fix*: move `ClientLogLine`/`ClientLogBody` and the batch constant into a
 shared crate.
 **Status:** moot -- both copies went with the route (`06b8a1f`). If a client/server contract comes back, `event-model` is still the answer.
 ### R4 — `build.rs` bakes in a CA it never asks Cargo to watch, and the bench build now has no rebuild trigger at all
 `emit_log_config` (`iris/android-app/build.rs:92`) calls `read_pinned_ca()`
 but emits only `rerun-if-env-changed` for `AI_APP_LOG_HOST/_PORT/_TOKEN` —
 no `rerun-if-changed` for the CA *file*, and (because the bench build
 returns at `:65`, before the transcript path's declarations) no
 `rerun-if-env-changed=AI_APP_CA`/`XDG_CONFIG_HOME` either. Emitting any
 `rerun-if-*` directive turns off Cargo's default "rerun when anything in
 the package changes" heuristic, so the bench build lost the only trigger it
 had.
 **Failure scenario.** `~/.config/ai-app` is wiped (AGENTS.md calls this the
 one-way door), `ai-server` mints a new CA, the APK is rebuilt — and
 `build.rs` does not re-run, so the APK still pins the dead CA and every
 upload fails with a TLS error nobody can attribute.
 *Fix*: `println!("cargo:rerun-if-changed={}", ca_path.display())` inside
 `read_pinned_ca`, and move the `AI_APP_CA`/`XDG_CONFIG_HOME` declarations
 above the bench early-return.
 **Status:** moot -- `iris/android-app/build.rs` was deleted (`06b8a1f`/`d8562d9`): the destination comes from the enrolment link now, so nothing is baked in at build time and there is nothing for Cargo to watch.
 ### R5 — desktop density is read once and never updated
 `iris/src/default/mod.rs:254` reads `content_scale(window)` at startup and
 sets it on both `rsc.ui.text.density` and `render`. `WindowEvent::
 ScaleFactorChanged` is not handled, and `UiRenderer::resize` deliberately
 no longer consults `scale_factor`. Dragging the window to a monitor with a
 different scale leaves every `dp(...)` and every rasterised glyph at the
 old density — the same class of disagreement the commit removed elsewhere.
 It is invisible here (every display on this machine is 1.0), which is why
 it needs writing down.
 **Status:** fixed in `ff1d6ea`. `WindowEvent::ScaleFactorChanged` re-reads `content_scale` -- through that function, so `IRIS_SCALE` still pins `--phone`'s density instead of following the monitor -- and `UiRenderState::set_density` marks the tree for a full redraw when the value actually changes, since `Text::shape` keys its cache on `(attrs, width, density)`.
 ### R6 — removing the bundled fonts removed the guard for a fault that was found on the phone, and the check was run on the desktop
 `iris/core/src/primitive/text.rs`'s `register_bundled_fonts` existed
 because "bold spans on a real phone rendered as blank gaps of the correct
 advance width" — the deleted doc says so. Its removal is Iris's own call
 and is recorded properly in `docs/DECISIONS.md`, but the verification
 recorded there is "checked with CJK + emoji **on desktop**", which is the
 half that cannot fail: the fault was Android's font enumeration resolving
 a weight/style. `iris/transcript-ui/src/tool.rs:110`'s comment is honest
 that `CLOSED_MARK`/`OPEN_MARK`/`UP_MARK` (U+25B8/BE/B4) are now "a bet"
 that the platform monospace face has them — which is UI_RULES' "don't rely
 on characters the platform might not have", stated and then accepted.
 *Fix*: before the next phone build, look at a bold run and the three
 chevrons on Iris's device specifically; the emulator's font set is not
 evidence for hers.
 **Status:** not done here -- it is a *look at it on Iris's phone* item, and no build in this VM is evidence about her device's font set. Carried forward as the review said: before the next phone build, look at a bold run and at `CLOSED_MARK`/`OPEN_MARK`/`UP_MARK` (U+25B8/BE/B4) on her device specifically.
 ### R7 — the least-squares fit clamps a degenerate norm instead of detecting it
 `iris/src/sense.rs:1105`: `1.0 / dot(...).sqrt().max(1e-6)`. Compose's
 `polyFitLeastSquares` treats `norm < 1e-6` as "vectors are linearly
 dependent, no solution" and bails; clamping instead produces a `q` row of
 zeros, a zero on `r`'s diagonal, and a `0/0` that the `is_finite` check at
 `:1059` happens to catch. It works, but it works by accident and the escape
 is not the one the source it is transcribed from takes.
 **Status:** fixed in `ff1d6ea`. `poly_fit_least_squares` returns `Option` and bails at `DEGENERATE_NORM` (Compose's `0.000001f`) instead of clamping; `velocity()` answers 0 on `None`. `a_fit_through_linearly_dependent_points_has_no_solution` reports `Some([NaN, NaN, NaN])` with the clamp back in place.
 ---
 ## Tests that cannot fail in the direction the bug would go
 ### T1 — `iris/transcript-fixture/tests/phone_screen.rs:64` computes the expected fling duration with the calculator under test, and asserts it one-sidedly
 `let expected = FlingCalculator::new(PHONE_SCALE).duration(velocity);` then
 `assert!(ran_for <= expected + 2 frames)`. This is the same
 "calculator compared with itself" shape the fling-spline commit
 (73f956f) identified and fixed elsewhere, and the direction it can fail in
 is "the fling ran too long" — never "the fling stopped dead", which is
 literally Iris's reported symptom. The companion
 `assert_ne!(before, after)` passes on one pixel of travel. A fling that
 settles on the first tick passes this test.
 *Fix*: add a lower bound from `velocity_reference.py`'s number (a fling at
 -15250 px/s at density 2.55 must run ≥ ~1.4 s and travel ≥ ~6000 px), not
 from `FlingCalculator`.
 **Status:** fixed in `e10582a`. Both bounds come from `fling_spline_reference.py`, which gained this case's own line (`density=2.55 v=15250.0: distance=11057.424px duration=2.0716s`), and travel is measured in pixels from a row's own on-screen extent (10527px measured). Scaling `tick_fling`'s elapsed by 1000 reports "stopped after 8ms"; scaling its delta by 0.01 reports "travelled 111px".
 ### T2 — `top_edge.rs:150` checks a row *count* on the leg where the culling bug appeared, and the box only on the other leg
 `rows_that_have_left_the_viewport_are_not_drawn` asserts `rows.len() <= 24`
 on the outbound leg and the per-row `inside the box` predicate only on the
 return leg. The doc explains why (an unmeasured row must be drawn to be
 measured), which is correct — but it means the test's name is only true of
 half of it, and a regression that draws 20 rows in the wrong *place* on the
 outbound leg passes.
 **Status:** fixed in `e10582a`. The first leg still cannot assert the box (an unmeasured row has to be drawn to be measured), so there is a third leg -- back again, every height known. Widening `intersects_viewport` downwards passes all 40 forward steps and fails at "back 6".
 ### T3 — `top_edge.rs:116` checks that a mask exists and where it is, not that it reaches anything
 `the_list_is_clipped_to_its_own_box` asserts `active.mask != MaskIdx::NONE`
 and that the mask's region lies within the list's box. It never checks the
 row primitives actually reference that mask, so a broken `Mask::parent`
 chain — the thing d507ae4 introduced — would leave this green while a code
 fence inside a row drew unclipped again.
 *Fix*: assert that a row primitive's mask chain contains the list's mask
 slot.
 **Status:** fixed in `e10582a`. It walks every row primitive's mask chain and requires the list's own slot on it, and rejects a chain that loops. Forcing `Painter::set_mask`'s `parent` to `NONE` fails it with "clips to [Id(1)], a chain that never reaches the list's own mask Id(0)".
 ---
 ## Rules
 - **`iris/src/widget/list.rs:576` is a second mechanism for per-frame
  instrumentation.** `iris::diagnostics::trace_enabled` exists for exactly
  "a default-off `debug!` in a hot path" and this line does not use it.
  (Cause of D1; the gate is in the untracked `diagnostics.rs`, so at the
  reviewed commit the line is simply ungated.)
 - **`server/src/routes.rs:1518` (`client_log_time`) duplicates
  `client-core/src/log_ring.rs:76` (`clock_time`)** — the same arithmetic
  written twice in two crates, with a comment noting they must agree. Same
  shared-crate answer as R3.
 - **`client-core/src/log_ring.rs:301`'s doc claims more than the code
  delivers**: "the caller is named in the error so it is findable" —
  `log::SetLoggerError` names nobody. `iris/android-app/src/app_log.rs:44`
  repeats the claim.
 - **Stale comment: `iris/src/android/view.rs:624`** cites
  `VelocityTracker::add_sample`'s debug assert; the method was renamed to
  `add_position` in the same commit range.
 - **`MOVE_CHAIN_LIMIT` now bounds two different chains** (move offsets and
  masks) under a name that says one, in both
  `iris/core/src/ui/render_state.rs:63` and `shader.wgsl:97`. The shader's
  comment already calls it "the bound on the parent walk"; the constant
  should say that too, or masks should get their own.
 - **`iris/src/sense.rs:1434`'s stated negative control is not reproducible
  as written.** "Reverting `velocity` to `total / span` fails exactly this
  one, the flick recording, and `phone_screen.rs`" — but `samples` now
  holds *positions*, so `total / span` over them gives 2750 for the steady
  drag too, and the commit message for the same change says "exactly seven
  tests". Two numbers for one experiment.
 - **`iris/android-app/src/bench_client.rs:393`'s `ime_visible` is right and
  its sibling one line up is not.** `set_bottom_inset(rsc,
  insets.bottom.max(insets.ime_bottom))` still infers "make room" from a
  `max`, so during the slide-in the composer is padded by the system-bar
  inset while `ime_visible` already says the keyboard is up. Harmless
  today; it is the same conflation the comment beside it warns about.
 **Status of the rule findings, 2026-09-07 evening.**
 - `list.rs:576`'s ungated per-frame line -- **fixed in `992c472`** with
  the rest of D1.
 - `routes.rs:1518`'s `client_log_time` duplicating `log_ring.rs`'s
  `clock_time` -- **moot**: the route was deleted (`06b8a1f`).
 - `log_ring.rs:301`'s "the caller is named in the error" -- **deferred to
  the devlog agent**; `client-core/src/log_ring.rs` is its file this pass,
  and `app_log.rs` no longer repeats the claim.
 - `view.rs:624`'s stale `VelocityTracker::add_sample` -- **fixed in
  `2ec0fee`**; the paragraph was rewritten for the anchoring change and
  now names `PointerClock` rather than a method that no longer exists.
 - `MOVE_CHAIN_LIMIT` naming two chains -- **fixed in `a6a100e`**: renamed
  to `PARENT_CHAIN_LIMIT` in `render_state.rs` and `shader.wgsl` at once
  (it had no other users), with the doc naming both chains it governs.
 - `sense.rs:1434`'s unreproducible negative control -- **fixed in
  `7e79ec1`**. Rerun with `velocity` reverted to `(newest - oldest) /
  span`: seven fail in `-p iris` (the flick recording, the accelerating
  flick, the horizon, the stopped finger, the minimum sample count, both
  `drag_gesture` flick tests) plus `phone_screen.rs`'s flick. RUST.md's
  "exactly seven" was right; the doc comment's "exactly this one, the
  flick recording, and `phone_screen.rs`" was not, and now says the same
  thing RUST.md does.
 - `bench_client.rs:393`'s `set_bottom_inset(.., max(..))` -- **deferred to
  the devlog agent**; `iris/android-app/**` was open under it this pass.
 ## Nits
 - `iris/src/sense.rs:798` computes `self.velocity.velocity()` twice on a
  release when `info` logging is on (once for the outcome, once for the
  log line) — a full Lsq2 fit each.
 - `iris/transcript-ui/src/selection.rs:303` calls `ui.ui_mut().animate(id)`
  even when `fling()` bailed (`|v| <= 1.0`, or no anchor). Harmless — the
  first `tick` unregisters — but it registers an animation that is known
  not to exist.
 ---
 **Status of the nits, both fixed in `a6a100e`.** `DragGesture`'s release
 computes `velocity()` once into a local both the outcome and the
 `iris drag release:` line read. `selection.rs`'s `animate(id)` is behind
 `is_scrolling()`, which is the same answer `List::fling` itself reached --
 and `phone_screen.rs`'s recorded flick still flings, which is the half
 that says the guard did not turn a working release off.
 ## Commits reviewed
 ```
 7e4e26a iris: resolve fontique's Android monospace generic family ourselves
 84a13e8 iris: a fling starts at Compose's velocity, which is a curve fit and not an average
 452c442 docs/RUST.md: queue -- logging landed; iris app enrolment ...
 238057a docs: the phone-logging decision, how to use it, and two build-apk traps
 896c93a iris: drop bundled Noto Sans, match Compose's platform-font fonts
 690161e docs: the transcript's edges were three faults, and what the rig found
 e922b73 iris: a transcript row is drawn if it overlaps the viewport, and clipped to it
 d507ae4 iris-core: masks nest instead of aborting, and a widget can ask to be drawn again
 9ed01e2 docs: phone report 2026-09-07 later -- overscroll, low initial fling velocity ...
 5be9f1b iris-android-app: keep the app's own log, put it in Copy report, upload it
 977bdb9 client-core: the app's own log ring, and POST /client-log to get it off a phone
 9cd1263 docs/RUST.md: queue -- APK size done, the embedded-fonts question left for Iris
 42af780 iris android-app: strip+LTO+cgu1+opt-level=s halve libmain.so, no feature trim needed
 4274b8b Merge remote-tracking branch 'origin/rustify' into worktree-agent-ace98b0bdaf33ffff
 73f956f iris: the fling curve was the identity function, and the keyboard was a targetSdk
 038f6a3 docs: the test rig's layers 1 and 2, with their commands and their limits
 1121d7c docs/LAYOUT.md: masks reference a drawn primitive instead of copying a shape ...
 232de0e iris: a phone-shaped desktop window, driven by the same touch recordings
 e430880 docs: phone report 2026-09-07, rows at the transcript's top edge culled early ...
 a999bd1 docs: masks with a shape (LAYOUT.md, decided 2026-09-07) and the orchestrator queue
 6840edf iris-android-app: the bench's fixture half comes from transcript-fixture
 3332201 iris: a headless in-process harness, and the bench fixture as a shared crate
 7f4ea7e docs/TODO.md: Compose app crash from Iris's phone log export, reversed AnnotatedString range
 591128e AGENTS.md: the phone app and the planned desktop app share widgets and styling
 ```
@@ -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,
    },
@@ -720,7 +720,10 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 name = "client-core"
 version = "0.1.0"
 dependencies = [
 "base64",
 "event-model",
 "log",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
@@ -964,9 +967,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 +1760,7 @@ dependencies = [
 "fxhash",
 "image",
 "parley",
 "pollster",
 "swash",
 "wgpu",
 ]
@@ -2873,9 +2877,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 +3060,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 +3657,19 @@ dependencies = [
 "once_cell",
 ]
 [[package]]
 name = "transcript-fixture"
 version = "0.1.0"
 dependencies = [
 "client-core",
 "event-model",
 "iris",
 "log",
 "serde_json",
 "transcript-ui",
 "winit",
 ]
 [[package]]
 name = "transcript-ui"
 version = "0.1.0"
@@ -3892,9 +3918,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",
@@ -3906,9 +3932,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",
@@ -3940,9 +3966,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",
@@ -3965,9 +3991,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",
@@ -3978,9 +4004,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",
@@ -3989,9 +4015,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,6 @@ 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.
 log = "0.4.28"
 [features]
 # RUST.md's I5 "Where iris's frame time goes" diagnosis: forces the Android
@@ -64,7 +66,11 @@ log = "0.4.28"
 # default) or virgl's GLES path, without a second env-var plumbing path that
 # nothing on this machine can hand to an already-launched Android process
 # (there is no `am start` environment and no system-property reader here to
-# add one). Android-only; `android/render.rs` is the only reader.
+# 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]
@@ -83,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]
@@ -744,7 +744,10 @@ checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
 name = "client-core"
 version = "0.1.0"
 dependencies = [
 "base64",
 "event-model",
 "log",
 "pulldown-cmark",
 "serde",
 "serde_json",
 "ureq",
@@ -1773,6 +1776,7 @@ dependencies = [
 "serde_json",
 "tabs-ui",
 "tokio",
 "transcript-fixture",
 "transcript-ui",
 ]
@@ -1785,6 +1789,7 @@ dependencies = [
 "fxhash",
 "image",
 "parley",
 "pollster",
 "swash",
 "wgpu",
 ]
@@ -3862,6 +3867,17 @@ 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"
@@ -29,6 +29,10 @@ log = "0.4.28"
 # 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 }
@@ -65,10 +69,22 @@ force-gles = ["iris/force-gles"]
 # `event-model` -- `lib.rs`'s `ActiveClient` selection gives this feature
 # priority over `transcript-screen`'s own `TranscriptClient` when both are
 # listed, which is how this crate's build command names both explicitly.
-bench = ["transcript-screen", "dep:libc", "dep:tokio"]
+bench = ["transcript-screen", "dep:transcript-fixture", "dep:libc", "dep:tokio"]
 [profile.release]
 panic = "abort"
 # Measured 2026-09-07 (docs/RUST.md's "APK size" subsection): together these
 # take libmain.so from 18,546,488 to 11,193,608 bytes (-39.7%) and the APK
 # from 20,678,956 to 13,326,076 bytes (-35.5%), arm64-v8a release. `strip`
 # also works around AGP's own stripReleaseDebugSymbols failing silently on
 # this .so ("packaging them as they are"). `opt-level = "s"` over `"z"`:
 # `z` measured another ~800 KB smaller but was not checked against iris's
 # own frame-time bench, so it is not worth the unmeasured risk -- see the
 # doc for the number and the follow-up this leaves.
 strip = true
 lto = "fat"
 codegen-units = 1
 opt-level = "s"
 [profile.dev]
 panic = "abort"
@@ -13,8 +13,37 @@ 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"
    }
@@ -24,8 +24,45 @@
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <!-- The enrollment link Dev Updater's Enroll button opens
                 (what `ai-server` mints), the same one the Compose app
                 in `app/` registers: which app answers it is the phone
                 owner's choice at the moment of the tap, and both being
                 offered is the intended behaviour rather than a clash.
                 BROWSABLE so a link tapped in another app reaches here,
                 and `android:host` so this app is not offered for every
                 aiapp:// URI a future route invents. -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="aiapp" android:host="enroll" />
            </intent-filter>
            <meta-data android:name="android.app.lib_name" android:value="main" />
        </activity>
        <!-- This app's own recent log, for Dev Updater to read on the
             phone. Iris runs these builds with no adb, and Android
             forbids one app reading another's logcat, so this is the
             only way a log::info! here reaches her. The shape is Dev
             Updater's contract (its README.md, "An app's own log"), not
             something invented for this app.
             The authority carries ${applicationId}, so the bench package
             and the ordinary one each get their own and neither can read
             the other's log. Exported, because the whole point is
             another app reading it, and guarded by a permission Dev
             Updater declares at protectionLevel="normal" (a signature
             permission is not available: the two apps are signed with
             different locally generated keys). Read-only: insert,
             update and delete throw. -->
        <provider
            android:name=".DevLogProvider"
            android:authorities="${applicationId}.devlog"
            android:exported="true"
            android:readPermission="dev.updater.permission.READ_DEVLOG" />
    </application>
 </manifest>
@@ -0,0 +1,186 @@
 package dev.iris.android.demo;
 import android.content.ContentProvider;
 import android.content.ContentValues;
 import android.content.UriMatcher;
 import android.database.Cursor;
 import android.database.MatrixCursor;
 import android.net.Uri;
 /**
 * This app's own recent log, exposed on the device.
 *
 * Iris runs these builds on a phone with no {@code adb}, and Android
 * forbids one app reading another's {@code logcat} -- so nothing outside
 * this process can recover what it wrote. The process already keeps a
 * bounded copy of its log (Rust: {@code client_core::log_ring}); this
 * hands it to Dev Updater, which is on the same phone, so it needs no
 * tunnel, no token and no second enrolment.
 *
 * <p>The shape is <em>Dev Updater's contract</em>, not something invented
 * here -- see that project's {@code README.md}, "An app's own log". Any
 * app it delivers can implement the same and get the same Runtime tab.
 * Two paths:
 *
 * <ul>
 *   <li>{@code lines?since=<seq>} -- every held line with a sequence at or
 *       after {@code since}, oldest first.
 *   <li>{@code status} -- one row: how many lines are held, how many the
 *       ring's own bound has dropped, and the newest sequence ({@code -1}
 *       for a log nothing has been written to, which is also how a reader
 *       notices this process restarted).
 * </ul>
 *
 * <p>Read-only: there is nothing here for anyone else to change, so the
 * three writing methods throw rather than silently doing nothing.
 *
 * <p>The authority is {@code <applicationId>.devlog}, filled in from
 * Gradle so the bench build and the ordinary one each get their own and
 * neither can read the other's. Read access is guarded by
 * {@code dev.updater.permission.READ_DEVLOG}, declared in the manifest.
 *
 * <p>No {@code notifyChange}: the ring is filled by a {@code log::Log}
 * backend on whatever thread logged, and giving that a way to reach a
 * provider would mean plumbing a callback through {@code client-core} for
 * every platform. Dev Updater polls while its tab is open, which its
 * contract says it does precisely so implementing this stays cheap.
 */
 public final class DevLogProvider extends ContentProvider {
    static {
        // The provider is created before any activity, so it cannot rely
        // on MainActivity's own load. Loading twice is a no-op.
        System.loadLibrary("main");
    }
    /** Matches {@link #nativeLinesSince}'s flat answer. Both sides say it once. */
    private static final int FIELDS_PER_LINE = 5;
    private static final String[] LINE_COLUMNS = {"seq", "t_ms", "level", "target", "message"};
    private static final String[] STATUS_COLUMNS = {"held", "dropped", "newest_seq"};
    private static final int LINES = 1;
    private static final int STATUS = 2;
    private UriMatcher matcher;
    /** Every held line, {@link #FIELDS_PER_LINE} strings each, oldest first. */
    private static native String[] nativeLinesSince(long since);
    /** Three strings: held, dropped, newest sequence. */
    private static native String[] nativeStatus();
    /**
     * Tells the Rust side which authority this build registered under, so
     * the diagnostics pane can name somewhere a reader can actually query
     * -- and so "declared but never created" is a state it can say. Only
     * the provider knows it was instantiated; Android creates one lazily.
     */
    private static native void nativeReady(String authority);
    @Override
    public boolean onCreate() {
        // The authority is not a constant here: it is derived from this
        // build's applicationId, so the bench package and the ordinary one
        // do not share one. Read back from the manifest rather than
        // recomposed, so there is one answer to what it is.
        String authority = getContext().getPackageName() + ".devlog";
        matcher = new UriMatcher(UriMatcher.NO_MATCH);
        matcher.addURI(authority, "lines", LINES);
        matcher.addURI(authority, "status", STATUS);
        nativeReady(authority);
        return true;
    }
    @Override
    public Cursor query(
            Uri uri,
            String[] projection,
            String selection,
            String[] selectionArgs,
            String sortOrder) {
        switch (matcher.match(uri)) {
            case LINES:
                return lines(sinceOf(uri));
            case STATUS:
                return status();
            default:
                // Null rather than an exception: an unknown path is a
                // reader asking for something this app does not have, and
                // the contract's own answer for that is no cursor.
                return null;
        }
    }
    /**
     * {@code ?since=} as a number, or 0 for a reader starting from the
     * beginning. A value that is not a number is treated as 0 rather than
     * refused -- what a caller wants from a malformed cursor is the log,
     * not a stack trace about the query string.
     */
    private static long sinceOf(Uri uri) {
        String since = uri.getQueryParameter("since");
        if (since == null) {
            return 0;
        }
        try {
            return Long.parseLong(since);
        } catch (NumberFormatException ignored) {
            return 0;
        }
    }
    private static Cursor lines(long since) {
        String[] fields = nativeLinesSince(since);
        if (fields == null) {
            return null;
        }
        MatrixCursor cursor = new MatrixCursor(LINE_COLUMNS, fields.length / FIELDS_PER_LINE);
        for (int at = 0; at + FIELDS_PER_LINE <= fields.length; at += FIELDS_PER_LINE) {
            cursor.addRow(
                    new Object[] {
                        Long.parseLong(fields[at]),
                        Long.parseLong(fields[at + 1]),
                        fields[at + 2],
                        fields[at + 3],
                        fields[at + 4],
                    });
        }
        return cursor;
    }
    private static Cursor status() {
        String[] fields = nativeStatus();
        if (fields == null || fields.length != STATUS_COLUMNS.length) {
            return null;
        }
        MatrixCursor cursor = new MatrixCursor(STATUS_COLUMNS, 1);
        cursor.addRow(
                new Object[] {
                    Long.parseLong(fields[0]), Long.parseLong(fields[1]), Long.parseLong(fields[2]),
                });
        return cursor;
    }
    @Override
    public String getType(Uri uri) {
        // A MIME type is for something meant to be handed to another app
        // as data; these rows are read by one reader that knows the
        // columns. Saying nothing is the honest answer, not a gap.
        return null;
    }
    @Override
    public Uri insert(Uri uri, ContentValues values) {
        throw new UnsupportedOperationException("this app's log is read-only");
    }
    @Override
    public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
        throw new UnsupportedOperationException("this app's log is read-only");
    }
    @Override
    public int delete(Uri uri, String selection, String[] selectionArgs) {
        throw new UnsupportedOperationException("this app's log is read-only");
    }
 }
@@ -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));
        });
    }
 }
@@ -1,10 +1,14 @@
 package dev.iris.android.demo;
 import android.app.Activity;
 import android.content.Intent;
 import android.net.Uri;
 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
@@ -18,9 +22,28 @@ public final class MainActivity extends Activity {
        System.loadLibrary("main");
    }
    /**
     * The app's private directory, where the Rust side keeps its enrollment
     * (`src/enrollment.rs`). Handed over before the view is built, because
     * the client the view creates reads the enrollment as it starts.
     */
    private static native void nativeSetFilesDir(String path);
    /**
     * One `aiapp://enroll?host=&port=&token=&ca=` link, as Dev Updater's
     * Enroll button opens it. Parsed and stored on the Rust side, which is
     * where the enrollment lives for the desktop app too -- nothing about
     * the link's format is known here.
     */
    private static native void nativeEnroll(String uri);
    @Override
    public void onCreate(Bundle state) {
        super.onCreate(state);
        // Before the view: creating it starts the Rust client, which asks
        // straight away which server it is enrolled with.
        nativeSetFilesDir(getFilesDir().getAbsolutePath());
        handleEnrollmentIntent(getIntent());
        IrisView view = new IrisView(this);
        view.setLayoutParams(new FrameLayout.LayoutParams(
                FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT));
@@ -31,17 +54,136 @@ 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) -> {
-            int left = insets.getSystemWindowInsetLeft();
+            sendInsets((IrisView) v, insets);
            int top = insets.getSystemWindowInsetTop();
            int right = insets.getSystemWindowInsetRight();
            int bottom = insets.getSystemWindowInsetBottom();
            int imeBottom = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                imeBottom = insets.getInsets(WindowInsets.Type.ime()).bottom;
            }
            ((IrisView) v).applyWindowInsets(left, top, right, bottom, imeBottom);
            return insets;
        });
    }
    /**
     * A link that arrives while the activity is already up. `singleTop` is
     * not set, so this is the resumed case only -- the fresh-launch case
     * goes through `onCreate`'s `getIntent`. `setIntent` so a later
     * `getIntent` reports the one actually being acted on rather than the
     * one this activity started with.
     */
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
        handleEnrollmentIntent(intent);
    }
    /**
     * Hands a VIEW intent's URI to the Rust side, which decides whether it
     * is an enrollment link -- the scheme is checked here only so a launch
     * intent (which carries no data) costs nothing.
     */
    private static void handleEnrollmentIntent(Intent intent) {
        if (intent == null) {
            return;
        }
        Uri data = intent.getData();
        if (data != null) {
            nativeEnroll(data.toString());
        }
    }
    /** 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;
        }
        view.applyWindowInsets(left, top, right, bottom, imeBottom, imeVisible);
    }
 }
@@ -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"
@@ -1,100 +0,0 @@
 // 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,124 @@
 //! The platform half of this app's logging: what
 //! `client_core::log_ring` needs that only Android can supply, which is
 //! `android_logger` as the logger to forward to and nothing else.
 //!
 //! Everything general -- the ring, its bounds, the `log::Log` backend --
 //! is in `client-core`, shared with the desktop app (AGENTS.md's sharing
 //! rule).
 //!
 //! **Why an app carries its own log at all**: Iris tests these builds on a
 //! GrapheneOS phone with no `adb`, and Android forbids one app reading
 //! another's `logcat`. Nothing outside this process can recover what it
 //! wrote, so the process keeps a copy -- and hands it to Dev Updater on
 //! the same phone through `devlog`'s `ContentProvider`. See
 //! `docs/DECISIONS.md`, 2026-09-07.
 use client_core::log_ring::{self, LogRing};
 /// Installs the ring in front of `android_logger`, so `logcat` still sees
 /// exactly what it saw before and the ring sees it too.
 ///
 /// Called once, from `JNI_OnLoad`. A second call is refused by `log`
 /// itself; the message says which caller, since two initialisation paths
 /// is a programmer error rather than something to recover from.
 pub fn install(max_level: log::LevelFilter) {
    let inner = android_logger::AndroidLogger::new(
        android_logger::Config::default()
            .with_max_level(max_level)
            .with_tag("iris-android-app"),
    );
    if log_ring::install_process_logger(Box::new(inner), max_level).is_err() {
        // Not a panic: a logger already installed means logging works,
        // just without the ring, and taking the app down over a
        // diagnostic would be worse than the diagnostic being missing.
        // The line goes through whatever logger did win.
        log::warn!("iris app log: a logger was already installed, so there is no ring");
    }
    install_panic_hook();
 }
 /// The process's ring -- what `Copy report` appends, what the diagnostics
 /// pane counts, and what `devlog`'s provider hands to Dev Updater.
 pub fn ring() -> &'static LogRing {
    log_ring::process_ring()
 }
 /// Only the bench build has a diagnostics pane to put this in; the
 /// transcript build's screen is the app's own and has no room for a
 /// readout. Gated rather than left dead so the build stays warning-clean.
 #[cfg(feature = "bench")]
 /// Two lines for the diagnostics pane: how much of this app's log is held,
 /// and where it can be read from.
 ///
 /// The second names the provider's authority rather than saying "logging
 /// is on", so a screenshot of this pane is enough to tell whether the
 /// contract is live and which package's log it is -- the bench build and
 /// the ordinary one have different ones.
 pub fn diagnostics_line() -> String {
    let where_to_read = match crate::devlog::authority() {
        Some(authority) => format!("devlog provider: content://{authority}"),
        // Not "off": Android creates a provider lazily, so this is what
        // "nobody has asked for it yet" looks like, and it is a different
        // thing from a build that does not have one.
        None => "devlog provider: declared, not created yet".to_string(),
    };
    format!("{}\n{where_to_read}", ring().summary())
 }
 /// Where the panic hook leaves its one line, under the app's private
 /// directory. Read back and dropped by [`set_crash_dir`] on the next
 /// start.
 const CRASH_FILE: &str = "last-panic.txt";
 static CRASH_PATH: std::sync::OnceLock<std::path::PathBuf> = std::sync::OnceLock::new();
 /// Installs a `log`-level panic hook, so a panic's message and location
 /// reach the ring and `logcat` rather than only the tombstone.
 ///
 /// **Why this is needed at all**: these builds are `panic = "abort"`
 /// (`Cargo.toml`), and the default hook writes to `stderr` plus
 /// `android_set_abort_message` -- the crash report. Iris runs these on a
 /// phone with no `adb`, so the crash report is exactly the surface she
 /// cannot read, and an `assert!` that fired said nothing anywhere she
 /// could see it. Routing it through `log::error!` puts it in front of
 /// `android_logger` *and* in the ring `devlog`'s provider hands to Dev
 /// Updater.
 ///
 /// The ring is memory only, so after an abort the process that holds it
 /// is gone -- hence the file half. [`set_crash_dir`] replays it.
 fn install_panic_hook() {
    let previous = std::panic::take_hook();
    std::panic::set_hook(Box::new(move |info| {
        let where_at = match info.location() {
            Some(at) => format!("{}:{}:{}", at.file(), at.line(), at.column()),
            None => "an unknown location".to_string(),
        };
        // `info`'s own `Display` repeats the location and a newline;
        // the payload alone keeps this to the one line the ring wants.
        let message = info.payload_as_str().unwrap_or("Box<dyn Any>");
        let line = format!("iris panic at {where_at}: {message}");
        log::error!("{line}");
        if let Some(path) = CRASH_PATH.get() {
            // Best effort by design: a panic is already the failure, and
            // failing to record it must not become a second one.
            let _ = std::fs::write(path, &line);
        }
        previous(info);
    }));
 }
 /// Tells the panic hook where to leave its line, and replays the line a
 /// previous run left there into the ring before deleting it.
 ///
 /// Called from `nativeSetFilesDir`, which is the first moment the app's
 /// private directory is known. The replay is at `error` level and says
 /// it is from the previous run, so a crash loop shows the reason it is
 /// looping in the Runtime tab of the run that is still up.
 pub fn set_crash_dir(dir: &std::path::Path) {
    let path = dir.join(CRASH_FILE);
    if let Ok(previous) = std::fs::read_to_string(&path) {
        log::error!("iris app log: the previous run died -- {}", previous.trim());
        let _ = std::fs::remove_file(&path);
    }
    let _ = CRASH_PATH.set(path);
 }
@@ -1,11 +1,14 @@
 //! 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, and `ClipboardManager.setPrimaryClip` for
+//! per-second battery sample, `ClipboardManager.setPrimaryClip` for the
-//! the "Copy report" control (P0's iris half, docs/RUST.md). Neither is
+//! "Copy report" control (P0's iris half, docs/RUST.md), and -- added for
-//! part of `android_view::context`'s own `Context`/`Resources` wrappers
+//! RUST.md's "Benchmark v2" -- `Display.getRefreshRate()` for the phase
-//! (that file's own `// TODO: more methods?`), so this calls them
+//! report's real late-frame budget and `InputMethodManager.
-//! directly rather than growing that crate's wrapper for two one-off
+//! 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
@@ -131,4 +134,119 @@ impl PlatformHandle {
        .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(())
    }
 }
@@ -0,0 +1,183 @@
 //! The JNI half of `DevLogProvider`: reading this process's own log ring
 //! for a `ContentProvider` that Dev Updater queries.
 //!
 //! **Why**: Iris runs these builds on a phone with no `adb`, and Android
 //! forbids one app reading another's `logcat`, so nothing outside this
 //! process can recover what it wrote. The app already keeps a bounded copy
 //! (`client_core::log_ring`); this is how the copy leaves the process. Dev
 //! Updater is on the same phone, so handing it over needs no tunnel, no
 //! token and no second enrolment -- and it is Dev Updater's own contract
 //! rather than something invented here, so any app it delivers can do the
 //! same (its `README.md`, "An app's own log").
 //!
 //! **Everything general stays in `client-core`** (AGENTS.md's sharing
 //! rule). What is here is only what Android forces: the JNI boundary and
 //! the Java class on the other side of it.
 //!
 //! Both entry points answer a **flat `String[]`** rather than a row of
 //! typed columns. That is the whole of the JNI, and it is one array type
 //! instead of three interleaved ones for a payload the provider is about
 //! to hand back over binder as a `MatrixCursor` anyway; `DevLogProvider`
 //! parses the two numeric fields. Kept flat rather than nested for the
 //! same reason -- an array of arrays is four more JNI calls per line.
 use android_view::jni::JNIEnv;
 use android_view::jni::objects::{JClass, JObject, JString};
 use android_view::jni::sys::{jlong, jobjectArray};
 use std::sync::OnceLock;
 /// How many `String`s each log line occupies in the flat answer:
 /// `seq`, `t_ms`, `level`, `target`, `message`, in that order. The Java
 /// side has the same constant, and the two are the one place the shape is
 /// written down on each side.
 const FIELDS_PER_LINE: usize = 5;
 /// The authority the provider registered itself under, once it has been
 /// created. `None` until then, which is a state worth being able to say:
 /// a provider Android never instantiated and one that is answering look
 /// the same from inside this process otherwise.
 static AUTHORITY: OnceLock<String> = OnceLock::new();
 /// Where this app's log can be read from, for the diagnostics pane.
 ///
 /// The provider's own answer rather than one composed from the package
 /// name here: what makes the line worth showing is that it names an
 /// authority somebody can actually query, and only the provider knows it
 /// registered.
 #[cfg(feature = "bench")]
 pub fn authority() -> Option<&'static str> {
    AUTHORITY.get().map(String::as_str)
 }
 /// `DevLogProvider.nativeReady` -- the provider announcing the authority
 /// it registered under, from its own `onCreate`.
 ///
 /// # Safety
 /// Called by the JVM with the arguments its `native` declaration names.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_dev_iris_android_demo_DevLogProvider_nativeReady(
    mut env: JNIEnv,
    _class: JClass,
    authority: JString,
 ) {
    if authority.is_null() {
        return;
    }
    let Ok(authority) = env.get_string(&authority) else {
        return;
    };
    let authority: String = authority.into();
    log::info!("iris devlog: serving this app's log at content://{authority}");
    let _ = AUTHORITY.set(authority);
 }
 /// `DevLogProvider.nativeStatus` -- `held`, `dropped`, `newest_seq`, as
 /// three strings.
 ///
 /// `newest_seq` is `-1` for a ring nothing has been written to, which is
 /// what tells a reader holding a cursor that this process **restarted**:
 /// the ring is in memory, so a new process starts again at zero and a
 /// stale cursor would otherwise skip everything silently.
 ///
 /// Exported by name rather than registered, matching this crate's other
 /// activity-side natives: the mangled name is the whole of what a class
 /// this app owns needs.
 ///
 /// # Safety
 /// Called by the JVM with the arguments its `native` declaration names.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_dev_iris_android_demo_DevLogProvider_nativeStatus(
    mut env: JNIEnv,
    _class: JClass,
 ) -> jobjectArray {
    string_array(&mut env, &status_fields())
 }
 /// `DevLogProvider.nativeLinesSince` -- every held line with a sequence at
 /// or after `since`, oldest first, [`FIELDS_PER_LINE`] strings each.
 ///
 /// Inclusive of `since` because [`client_core::log_ring::LogRing::since`]
 /// is, and one definition of the cursor is what keeps the app's own
 /// uploaded report and this provider describing the same lines.
 ///
 /// # Safety
 /// Called by the JVM with the arguments its `native` declaration names.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_dev_iris_android_demo_DevLogProvider_nativeLinesSince(
    mut env: JNIEnv,
    _class: JClass,
    since: jlong,
 ) -> jobjectArray {
    // A negative cursor is a caller asking for everything, not an error to
    // take the app down over: the provider is a diagnostic.
    string_array(&mut env, &line_fields(since.max(0) as u64))
 }
 /// The three status numbers, as the provider's row.
 #[cfg(feature = "transcript-screen")]
 fn status_fields() -> Vec<String> {
    let ring = client_core::log_ring::process_ring();
    vec![
        ring.len().to_string(),
        ring.dropped().to_string(),
        ring.newest_seq().map_or(-1, |seq| seq as i64).to_string(),
    ]
 }
 /// The tabs demo links no `client-core` and keeps no ring, so it holds
 /// nothing and has never dropped anything -- which is the truth, not a
 /// stand-in. The natives are still exported there, because a `native`
 /// method Java declares and the library does not is an
 /// `UnsatisfiedLinkError` the moment the class loads.
 #[cfg(not(feature = "transcript-screen"))]
 fn status_fields() -> Vec<String> {
    vec!["0".to_string(), "0".to_string(), "-1".to_string()]
 }
 #[cfg(feature = "transcript-screen")]
 fn line_fields(since: u64) -> Vec<String> {
    let (lines, _next) = client_core::log_ring::process_ring().since(since);
    let mut fields = Vec::with_capacity(lines.len() * FIELDS_PER_LINE);
    for line in lines {
        fields.push(line.seq.to_string());
        fields.push(line.at_ms.to_string());
        fields.push(line.level.to_string());
        fields.push(line.target);
        fields.push(line.message);
    }
    fields
 }
 #[cfg(not(feature = "transcript-screen"))]
 fn line_fields(_since: u64) -> Vec<String> {
    Vec::new()
 }
 /// A Java `String[]` of those, or a null array if the JVM refused one.
 ///
 /// Null rather than a panic across the JNI boundary: `DevLogProvider`
 /// reads it as "the provider could not answer" and returns no cursor,
 /// which Dev Updater already draws as a distinct state. Taking the app
 /// down to report that its diagnostic is unavailable would be worse than
 /// the diagnostic being unavailable.
 fn string_array(env: &mut JNIEnv, fields: &[String]) -> jobjectArray {
    let null = std::ptr::null_mut();
    let Ok(class) = env.find_class("java/lang/String") else {
        return null;
    };
    let Ok(array) = env.new_object_array(fields.len() as i32, class, JObject::null()) else {
        return null;
    };
    for (index, field) in fields.iter().enumerate() {
        let Ok(value) = env.new_string(field) else {
            return null;
        };
        if env
            .set_object_array_element(&array, index as i32, value)
            .is_err()
        {
            return null;
        }
    }
    array.into_raw()
 }
@@ -0,0 +1,133 @@
 //! Which `ai-server` this app talks to, and how it was told.
 //!
 //! The parsing, the file and its owner-only mode are
 //! `client_core::config` (`EnrolledServer`/`EnrollmentStore`), shared with
 //! the desktop app. What is genuinely this platform's, and all that is
 //! here, is the intent plumbing: Android hands an `aiapp://enroll?...`
 //! link to `MainActivity`, which passes it and the app's private files
 //! directory across JNI (see `lib.rs`'s two exported functions).
 //!
 //! **Why the app is told at runtime rather than at build time.** The APK
 //! is cross-compiled in a VM and run against the server on the host, whose
 //! CA and token are not this machine's -- so nothing about the destination
 //! can be baked in, and no token or CA may sit in a repo or a delivered
 //! artifact either way. The CA arrives with the link (`ca` parameter,
 //! `wg_app_link::enroll::ca_param`), which is what makes an APK built
 //! anywhere able to pin the server it is pointed at.
 //!
 //! The files directory is process-wide state, which this project otherwise
 //! avoids: it arrives from the activity, and `AndroidAppState::new` -- the
 //! first thing that wants the enrollment -- has no parameter it could come
 //! in through. Same shape, and the same reason, as
 //! `client_core::log_ring`'s process ring.
 #[cfg(not(feature = "bench"))]
 use client_core::api::UreqTransport;
 use client_core::config::{EnrolledServer, EnrollmentStore};
 use std::path::PathBuf;
 use std::sync::OnceLock;
 /// `Context.getFilesDir()`, handed over by `MainActivity` before it builds
 /// the view. Set once per process; a second call with a different path is
 /// a programmer error rather than something to recover from, and a second
 /// call with the same one is what a re-created activity does.
 static FILES_DIR: OnceLock<PathBuf> = OnceLock::new();
 pub fn set_files_dir(dir: PathBuf) {
    if let Err(existing) = FILES_DIR.set(dir.clone()) {
        assert_eq!(
            existing, dir,
            "the app's files directory was set twice with different paths"
        );
    }
 }
 /// `None` before `MainActivity` has handed the directory over -- which is
 /// **not** the same as "not enrolled", and is why [`status`] has a state
 /// for it (UI_RULES: design the unknown state first).
 fn store() -> Option<EnrollmentStore> {
    FILES_DIR.get().map(EnrollmentStore::new)
 }
 /// What this app has been told, or why it has not been.
 pub enum Status {
    Enrolled(EnrolledServer),
    /// Nothing has been enrolled yet: the ordinary first-run state.
    NotEnrolled,
    /// The question could not be answered -- the activity never handed a
    /// files directory over, or the file is there and unreadable. Kept
    /// apart from `NotEnrolled` because the two want different actions
    /// from whoever is looking.
    Unknown(String),
 }
 pub fn status() -> Status {
    let Some(store) = store() else {
        return Status::Unknown("the activity never handed over a files directory".to_string());
    };
    match store.load() {
        Ok(Some(server)) => Status::Enrolled(server),
        Ok(None) => Status::NotEnrolled,
        Err(error) => Status::Unknown(error.to_string()),
    }
 }
 /// One line for the diagnostics pane. The three states read differently on
 /// purpose: "not enrolled" says what to do about it, and "couldn't tell"
 /// must not be mistaken for it.
 ///
 /// Only the bench build has a pane to put this in -- same gate, and the
 /// same reason, as `app_log::diagnostics_line`. The transcript build says
 /// the same things where they matter to it, in the message
 /// [`transport`]'s error becomes on screen.
 #[cfg(feature = "bench")]
 pub fn status_line() -> String {
    match status() {
        Status::Enrolled(server) => format!("enrolled: {}:{}", server.host, server.port),
        Status::NotEnrolled => "not enrolled -- open the enrol link from Dev Updater".to_string(),
        Status::Unknown(why) => format!("enrolment unreadable: {why}"),
    }
 }
 /// Parses an `aiapp://enroll?...` link and saves it, replacing whatever
 /// was enrolled before -- opening a link is how somebody says "this server
 /// now", including after the old one's token was rotated.
 ///
 /// The returned `Err` is the message for a person: this is called from a
 /// tap on a link, and a link that did nothing with nothing said is the
 /// failure the UI rules are most insistent about.
 pub fn apply_link(uri: &str) -> Result<EnrolledServer, String> {
    let server = EnrolledServer::parse_link(uri)?;
    let store = store().ok_or("the app has no files directory to save an enrollment in")?;
    store
        .save(&server)
        .map_err(|error| format!("couldn't save the enrollment: {error}"))?;
    Ok(server)
 }
 /// A transport for the enrolled server, pinning the CA the link carried.
 ///
 /// Gated to the same builds as `transcript_client`, its only caller: the
 /// bench build opens a checked-in fixture and reaches no server, so
 /// compiling this into it would be a warning about dead code that is
 /// dead on purpose.
 ///
 /// Every failure here is a sentence a screen can show, because there is
 /// nowhere else for it to go: this app has no `logcat` on the phone it is
 /// built for.
 #[cfg(not(feature = "bench"))]
 pub fn transport() -> Result<UreqTransport, String> {
    let server = match status() {
        Status::Enrolled(server) => server,
        Status::NotEnrolled => {
            return Err("Not enrolled yet -- open the enrol link from Dev Updater.".to_string());
        }
        Status::Unknown(why) => return Err(format!("Couldn't read the enrollment: {why}")),
    };
    let ca_pem = server.ca_pem.as_ref().ok_or(
        "The enrollment link carried no CA, so there is nothing to pin. \
         Enrol again with a link minted by this server.",
    )?;
    UreqTransport::new(server.base_url(), &server.token, ca_pem.as_bytes())
        .map_err(|error| error.message)
 }
@@ -40,6 +40,7 @@ use android_view::{
    Context, View,
    jni::{
        JNIEnv, JavaVM,
        objects::{JClass, JString},
        sys::{JNI_VERSION_1_6, JavaVM as RawJavaVM, jint, jlong},
    },
    register_view_class,
@@ -51,10 +52,25 @@ use iris::prelude::*;
 use log::LevelFilter;
 use std::ffi::c_void;
 /// The app's own log ring and its upload -- only where `client-core` is
 /// linked, which is every build that has a server to send to. The plain
 /// tabs demo keeps `android_logger` alone, as it always had.
 #[cfg(feature = "transcript-screen")]
 mod app_log;
 #[cfg(feature = "bench")]
 mod bench_client;
 #[cfg(feature = "bench")]
 mod bench_jni;
 /// This app's log ring, handed to Dev Updater on the phone through a
 /// `ContentProvider`. Declared in every build for the reason the module
 /// gives: the Java class is in the manifest either way, and a `native`
 /// method the library does not export fails the class load.
 mod devlog;
 /// Which server this app talks to, told to it at runtime by an
 /// `aiapp://enroll` link. Only where `client-core` is linked -- the plain
 /// tabs demo makes no network call and has nothing to enrol against.
 #[cfg(feature = "transcript-screen")]
 mod enrollment;
 #[cfg(all(feature = "transcript-screen", not(feature = "bench")))]
 mod transcript_client;
@@ -119,6 +135,13 @@ extern "system" fn new_view_peer<'local>(
 /// mirrors android-view's own demo, which carries the same comment.
 #[unsafe(no_mangle)]
 pub unsafe extern "system" fn JNI_OnLoad(vm: *mut RawJavaVM, _: *mut c_void) -> jint {
    // The ring in front of `android_logger` where there is one (see
    // `app_log`), and `android_logger` alone otherwise. Both install the
    // same tag and level, so `logcat` cannot tell the two builds apart --
    // the ring only adds a second reader.
    #[cfg(feature = "transcript-screen")]
    app_log::install(LevelFilter::Debug);
    #[cfg(not(feature = "transcript-screen"))]
    android_logger::init_once(
        android_logger::Config::default()
            .with_max_level(LevelFilter::Debug)
@@ -130,3 +153,83 @@ pub unsafe extern "system" fn JNI_OnLoad(vm: *mut RawJavaVM, _: *mut c_void) ->
    iris::android::register_native_methods(&mut env, VIEW_CLASS);
    JNI_VERSION_1_6
 }
 /// `MainActivity.nativeSetFilesDir` -- the app's private directory, handed
 /// over before the view exists because that is where the enrollment is
 /// read from and written to (`enrollment`'s module doc).
 ///
 /// Exported by name rather than registered through `RegisterNatives`: the
 /// view's methods are registered because `android-view` owns that class
 /// and hands out one function pointer, whereas these two are this app's
 /// own activity and the mangled name is the whole of what is needed.
 ///
 /// Declared in every build, including the tabs demo that has no
 /// `client-core` to store anything -- a `native` method Java declares and
 /// the library does not export is an `UnsatisfiedLinkError` when the class
 /// loads, which would take down a build that merely shares the activity.
 ///
 /// # Safety
 /// Called by the JVM with the arguments its `native` declaration names.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_dev_iris_android_demo_MainActivity_nativeSetFilesDir(
    mut env: JNIEnv,
    _class: JClass,
    dir: JString,
 ) {
    let Some(dir) = jstring(&mut env, dir) else {
        return;
    };
    #[cfg(feature = "transcript-screen")]
    {
        app_log::set_crash_dir(std::path::Path::new(&dir));
        enrollment::set_files_dir(std::path::PathBuf::from(&dir));
    }
    log::debug!("iris app: files directory is {dir}");
 }
 /// `MainActivity.nativeEnroll` -- one `aiapp://enroll?...` link, from the
 /// VIEW intent that started or resumed the activity.
 ///
 /// Logged either way rather than answered: the activity has nothing to do
 /// with the result, and where the enrollment shows up is the diagnostics
 /// pane (`enrollment::status_line`), which reads the stored answer rather
 /// than being told it.
 ///
 /// # Safety
 /// Called by the JVM with the arguments its `native` declaration names.
 #[unsafe(no_mangle)]
 pub extern "system" fn Java_dev_iris_android_demo_MainActivity_nativeEnroll(
    mut env: JNIEnv,
    _class: JClass,
    uri: JString,
 ) {
    let Some(uri) = jstring(&mut env, uri) else {
        return;
    };
    #[cfg(feature = "transcript-screen")]
    match enrollment::apply_link(&uri) {
        // Never the token: `wg-app-link`'s enroll module forbids logging
        // it, and this line would otherwise be the one place it leaked.
        Ok(server) => log::info!("iris app: enrolled with {}:{}", server.host, server.port),
        Err(error) => log::warn!("iris app: that enrolment link was refused -- {error}"),
    }
    #[cfg(not(feature = "transcript-screen"))]
    log::warn!("iris app: {uri} arrived, but this build has no server to enrol with");
 }
 /// A `JString` as a Rust `String`, or `None` for a null or non-UTF-8 one --
 /// neither is worth taking the app down for, and both are logged where
 /// they happen.
 fn jstring(env: &mut JNIEnv, value: JString) -> Option<String> {
    if value.is_null() {
        log::warn!("iris app: the activity passed a null string across JNI");
        return None;
    }
    match env.get_string(&value) {
        Ok(value) => Some(value.into()),
        Err(error) => {
            log::warn!("iris app: couldn't read a string from the activity -- {error}");
            None
        }
    }
 }
@@ -7,27 +7,35 @@
 //!
 //! **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
+//! session list here -- the first session `ApiClient::fetch_sessions`
-//! pinned CA are baked in at build time (`build.rs`'s
+//! returns is opened automatically, since there is nothing to tap to get
-//! `AI_APP_TRANSCRIPT_HOST`/`_PORT`/`_TOKEN`/`AI_APP_CA`), and the first
+//! there, which is what `transcript-bench.sh` and `ui-trace` need to land
-//! session `ApiClient::fetch_sessions` returns is opened automatically --
+//! straight on the screen under test.
-//! 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
+//! Which server it opens it against is no longer baked in: it is the
-//! app needs `desktop-app`'s `EnrolledServer`/QR-link flow or E3's
+//! enrollment an `aiapp://enroll` link left behind (`crate::enrollment`,
-//! Keystore-sealed `ServerConfig.kt`; building a second one of those was
+//! and `desktop-app`'s identical `--link`), because an APK
-//! not this pass's job.
+//! cross-compiled here cannot pin the CA of a server on the host.
 //!
 //! **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, and a full rebuild of the widget tree on
+//! a stale background response. What differs is only the redraw
-//! every event (same tradeoff, same reason: `push_row` cannot update a row
+//! mechanism: android-view has no `winit::EventLoopProxy`, so this uses
-//! already on screen, and this rig's conversations are small). What
+//! `iris::task::Tasks::redraw_handle` (new, added alongside this box) to
-//! differs is only the redraw mechanism: android-view has no
+//! request a frame after each `TaskCtx::update` instead of relying on
-//! `winit::EventLoopProxy`, so this uses `iris::task::Tasks::redraw_handle`
+//! `Tasks::spawn`'s single end-of-future redraw -- see that method's own
-//! (new, added alongside this box) to request a frame after each
+//! doc for why.
-//! `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};
@@ -38,10 +46,6 @@ 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
@@ -77,18 +81,16 @@ impl HasAndroidUiState for TranscriptClient {
    }
 }
-/// Builds one `UreqTransport` from the config `build.rs` baked in. Called
+/// Builds one `UreqTransport` from the stored enrollment. Called twice per
-/// twice per session load, same as `desktop-app`'s `build_transport`
+/// session load, same as `desktop-app`'s `build_transport` closure --
-/// closure -- `ApiClient` and the live-stream follow each need their own,
+/// `ApiClient` and the live-stream follow each need their own, since
-/// since `UreqTransport` holds its own `ureq::Agent`.
+/// `UreqTransport` holds its own `ureq::Agent`.
 ///
 /// Read afresh each time rather than held: opening a new enrolment link
 /// while the app is running is how somebody points it at another server,
 /// and a cached transport would keep talking to the old one.
 fn build_transport() -> Result<UreqTransport, String> {
-    let base_url = format!("https://{}:{}", pinned::HOST, pinned::PORT);
+    crate::enrollment::transport()
    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 {
@@ -360,8 +362,17 @@ impl TranscriptClient {
    }
    fn apply_event(&mut self, rsc: &mut AndroidRsc<Self>, event: &SeqEvent) {
        let old_items = self.items.clone();
        self.items = fold_event(&self.items, event);
-        self.rebuild_transcript(rsc);
+        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) {
@@ -0,0 +1,156 @@
 #!/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):
        # 15250 is `transcript-fixture/touch/flick-120hz.touch`'s own
        # release velocity (velocity_reference.py), so `phone_screen.rs`
        # can bound the fling it produces from *here* rather than from the
        # `FlingCalculator` under test (docs/REVIEW-2026-09-07.md's T1).
        for velocity in (5000.0, 11064.0, 15250.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;
@@ -0,0 +1,96 @@
 #!/usr/bin/env python3
 """Turns `iris::input` debug lines -- from a phone's diagnostics report, or
 from a report the layer-1 harness produced with tracing on
 (`iris::diagnostics::set_trace(true)`) -- back into a `TouchScript` file
 `iris::harness::Harness::replay` can play back at layer 1.
 Why this exists: `docs/RUST.md`'s "Three test layers" box says the cheapest
 layer that can answer a question wins, and a gesture that misbehaves on
 Iris's phone is otherwise only describable in words. `iris::sense::
 log_input_event`'s one line per platform event (Android's on_touch_event
 once per `MotionEvent`, with historical samples inline; winit's once per
 pointer `WindowEvent`; the harness's `touch`, once per script line) already
 carries everything a `.touch` file's `t_ms action x y` needs -- this just
 reads it back out and reconstructs the samples in order, expanding each
 event's inline historical samples into their own `move` lines first (they
 are always intermediate positions of a move, and Android documents them as
 oldest first, which is also the order they appear in the line).
 Usage:
    report_to_touch.py < report.txt > replay.touch
    report_to_touch.py report.txt > replay.touch
 Only lines containing "iris input: action=..." are read; everything else in
 the report (insets, frame timings, drag-release summaries) is ignored, so
 this can be pointed at Copy report's whole clipboard text directly.
 """
 import re
 import sys
 # The message half of `sense::log_input_event`'s format string, prefix-
 # agnostic: a real report line also carries the ring's own
 # `HH:MM:SS.mmm LEVEL target:` header (`LogLine::format`) or, forwarded
 # through `ai_server::client_log`, a `[<source> <clock> #<seq>]` tag ahead
 # of that -- neither of which this needs to understand, since `search`
 # (not `match`) finds the marker wherever it starts.
 LINE_RE = re.compile(
    r"iris input: action=(?P<action>\w+) x=(?P<x>-?[0-9.]+) y=(?P<y>-?[0-9.]+) "
    r"t=(?P<t>[0-9]+)ms history=(?P<hist>[0-9]+)(?P<rest>.*)$"
 )
 # One historical sample inside `rest`: `t:x,y`, space-separated, oldest first
 # -- see `log_input_event`'s own doc for why order matters.
 HIST_RE = re.compile(r"(?P<t>[0-9]+):(?P<x>-?[0-9.]+),(?P<y>-?[0-9.]+)")
 def _fmt(value: float) -> str:
    """The number as `TouchScript::parse`'s own `f32::parse` would round-trip
    it -- an integer without a trailing `.0` where the source was one
    (every coordinate here is a physical pixel), `{:g}` otherwise so a
    fractional value from a real device is not silently truncated."""
    if value == int(value):
        return str(int(value))
    return f"{value:g}"
 def convert(lines):
    """Every `iris::input` line, oldest first, expanded to one `(t_ms,
    action, x, y)` tuple per touch sample -- a historical sample is always
    an intermediate `move`, and the event's own sample keeps its real
    action (`down`/`move`/`up`/`cancel`)."""
    rows = []
    for line in lines:
        m = LINE_RE.search(line)
        if not m:
            continue
        hist_count = int(m.group("hist"))
        hist_matches = list(HIST_RE.finditer(m.group("rest")))
        if len(hist_matches) != hist_count:
            print(
                f"report_to_touch: {line.strip()!r} says history={hist_count} but "
                f"holds {len(hist_matches)} samples -- skipped",
                file=sys.stderr,
            )
            continue
        for hm in hist_matches:
            rows.append(
                (int(hm.group("t")), "move", float(hm.group("x")), float(hm.group("y")))
            )
        rows.append(
            (int(m.group("t")), m.group("action"), float(m.group("x")), float(m.group("y")))
        )
    return rows
 def main():
    if len(sys.argv) > 2:
        print("usage: report_to_touch.py [report.txt] < report.txt", file=sys.stderr)
        return 2
    text = open(sys.argv[1]) if len(sys.argv) == 2 else sys.stdin
    for t_ms, action, x, y in convert(text):
        print(f"{t_ms} {action} {_fmt(x)} {_fmt(y)}")
    return 0
 if __name__ == "__main__":
    sys.exit(main())
@@ -0,0 +1,298 @@
 #!/usr/bin/env python3
 """Compose's touch velocity tracker, transcribed independently of the Rust port.
 Same reason `fling_spline_reference.py` exists: the numbers checked into
 `sense.rs`'s velocity tests must not be numbers the Rust produced. The old
 estimator -- total motion over the sample span, an average -- passed every test
 it had, because every one of those tests asserted the average's own definition
 back at it. An average cannot tell an accelerating flick from a steady drag, and
 that is exactly what Iris reported from the phone on 2026-09-07: "flinging now
 actually works but is slower than Compose's immediately after releasing the
 flick".
 Transcribed by hand from, and only from, the `-sources.jar` of
 **androidx.compose.ui:ui-android:1.12.0** and
 **androidx.compose.foundation:foundation-android:1.12.0**
 (dl.google.com/dl/android/maven2), read 2026-09-07:
  * `androidx/compose/ui/input/pointer/util/VelocityTracker.kt` --
    `VelocityTracker1D.calculateVelocity`, `polyFitLeastSquares`,
    `calculateImpulseVelocity`, `kineticEnergyToVelocity`, and the constants
    `HistorySize = 20`, `HorizonMilliseconds = 100`,
    `AssumePointerMoveStoppedMilliseconds = 40`.
  * `androidx/compose/ui/input/pointer/util/PlatformVelocityTracker.kt` --
    `Lsq2VelocityTracker`, which is what the 2D `VelocityTracker` delegates to.
  * `androidx/compose/ui/input/pointer/util/PlatformVelocityTracker.android.kt`
    -- the `AndroidComposeUiFlags.isFrameworkVelocityTrackerEnabled` fork.
  * `androidx/compose/ui/AndroidComposeUiFlags.android.kt` -- that flag's
    default, which is `false`.
  * `androidx/compose/foundation/gestures/Draggable.kt` -- `sendDragStart` /
    `sendDragEvent` / `sendDragStopped`, i.e. *which* samples a touch drag
    feeds the tracker and where the maximum-velocity clamp is applied.
  * `androidx/compose/foundation/gestures/DifferentialVelocityTracker.kt` and
    `NonTouchScrollingLogic.kt` -- the Impulse strategy's only caller.
  * `androidx/compose/foundation/gestures/Scrollable.kt` --
    `DefaultFlingBehavior.performFling`, for the minimum-velocity question.
 **Which strategy a touch fling actually uses, since this was the surprise.**
 `Strategy.Impulse` is *not* it. `scrollable`/`draggable` release through
 `DragGestureNode.sendDragStopped`, which calls the 2D `VelocityTracker`; on
 Android that is `Lsq2VelocityTracker` (the framework-tracker flag defaults to
 false), which is two `VelocityTracker1D(strategy = Lsq2)` -- a degree-2
 least-squares fit over **absolute positions**, whose velocity is the fitted
 polynomial's derivative at the newest sample. Impulse is reached only through
 `DifferentialVelocityTracker`, whose sole caller is `NonTouchScrollingLogic`:
 mouse wheel and trackpad, never a finger. So this script transcribes Lsq2 and
 iris ports Lsq2. `calculate_impulse_velocity` is here anyway, unused by the
 printed points, because ruling it out by reading is cheaper than ruling it out
 again next time somebody remembers "Compose uses impulse".
 **Which samples a touch drag feeds it.** `sendDragStart` adds the DOWN change;
 every subsequent MOVE, historical samples included, is added by `sendDragEvent`.
 The **UP position is never added**: `Lsq2VelocityTracker.addPointerInputChange`
 wraps its two `addPosition` calls in `if (!event.changedToUpIgnoreConsumed())`,
 and all the UP branch does is reset the tracker when more than 40ms have passed
 since the last MOVE (b/238654963). So a finger that stops before lifting reads
 as a stop, not as a decelerating tail. Positions are the raw event positions,
 so the touch slop is inside the motion the tracker sees even though the list
 never scrolled by it.
 Two of Compose's samples iris does *not* reproduce, both noted rather than
 copied: pre-slop MOVEs (iris's `DragArbiter` is `Undecided` then too, so it
 feeds none either -- these agree), and the single MOVE that *crosses* the slop,
 which Compose drops because `sendDragStart` adds only the DOWN. iris feeds that
 one, since it is a real measured position and dropping it would be copying a
 quirk of where Compose happens to split its state machine.
 **The clamps.** Maximum: `sendDragStopped` passes
 `LocalViewConfiguration.maximumFlingVelocity`, which on Android is
 `ViewConfiguration.getScaledMaximumFlingVelocity()` -- 8000 dp/s. Minimum:
 there is **none** on this path. `ViewConfiguration.minimumFlingVelocity`
 exists in Compose's `ViewConfiguration` interface but its only use in either
 artifact is `NestedScrollInteropConnection`, for View interop.
 `DefaultFlingBehavior.performFling` guards with `abs(initialVelocity) > 1f`
 and says why in its own comment: "we need it since spline curve gives us
 NaNs". 1 px/s, not 50 dp/s.
 Run it with no arguments; it prints the sample sets and the velocities the
 Rust tests assert on.
 """
 import math
 HISTORY_SIZE = 20
 HORIZON_MILLISECONDS = 100.0
 ASSUME_POINTER_MOVE_STOPPED_MILLISECONDS = 40.0
 MIN_SAMPLE_SIZE_LSQ2 = 3
 # ViewConfiguration.getScaledMaximumFlingVelocity(), in dp/s.
 MAXIMUM_FLING_VELOCITY_DP_S = 8000.0
 # DefaultFlingBehavior.performFling's own threshold, in the units of the
 # positions fed to the tracker -- pixels per second here.
 FLING_MINIMUM_PX_S = 1.0
 def poly_fit_least_squares(x, y, sample_count, degree):
    """`polyFitLeastSquares`: Gram-Schmidt QR, coefficients low order first."""
    if degree < 1:
        raise ValueError("The degree must be at positive integer")
    if sample_count == 0:
        raise ValueError("At least one point must be provided")
    truncated_degree = sample_count - 1 if degree >= sample_count else degree
    m = sample_count
    n = truncated_degree + 1
    # a[i][h] = x[h]**i, pre-multiplied by the (always 1.0) weight.
    a = [[0.0] * m for _ in range(n)]
    for h in range(m):
        a[0][h] = 1.0
        for i in range(1, n):
            a[i][h] = a[i - 1][h] * x[h]
    q = [[0.0] * m for _ in range(n)]
    r = [[0.0] * n for _ in range(n)]
    for j in range(n):
        w = q[j]
        w[:] = a[j][:m]
        for i in range(j):
            z = q[i]
            dot = sum(w[h] * z[h] for h in range(m))
            for h in range(m):
                w[h] -= dot * z[h]
        norm = math.sqrt(sum(v * v for v in w))
        inverse_norm = 1.0 / max(norm, 1e-6)
        for h in range(m):
            w[h] *= inverse_norm
        for i in range(n):
            r[j][i] = 0.0 if i < j else sum(w[h] * a[i][h] for h in range(m))
    coefficients = [0.0] * n
    for i in range(n - 1, -1, -1):
        c = sum(q[i][h] * y[h] for h in range(m))
        for j in range(n - 1, i, -1):
            c -= r[i][j] * coefficients[j]
        coefficients[i] = c / r[i][i]
    return coefficients
 def kinetic_energy_to_velocity(kinetic_energy):
    sign = 0.0 if kinetic_energy == 0.0 else math.copysign(1.0, kinetic_energy)
    return sign * math.sqrt(2 * abs(kinetic_energy))
 def calculate_impulse_velocity(data_points, time, sample_count, is_data_differential):
    """`calculateImpulseVelocity` -- not on the touch path; see the module doc."""
    work = 0.0
    start = sample_count - 1
    next_time = time[start]
    for i in range(start, 0, -1):
        current_time = next_time
        next_time = time[i - 1]
        if current_time == next_time:
            continue
        if is_data_differential:
            delta = -data_points[i - 1]
        else:
            delta = data_points[i] - data_points[i - 1]
        v_curr = delta / (current_time - next_time)
        v_prev = kinetic_energy_to_velocity(work)
        work += (v_curr - v_prev) * abs(v_curr)
        if i == start:
            work = work * 0.5
    return kinetic_energy_to_velocity(work)
 def calculate_velocity(samples):
    """`VelocityTracker1D.calculateVelocity` with `Strategy.Lsq2`.
    `samples` is `(time_millis, position)` oldest first, at most the last
    `HISTORY_SIZE` of which the circular buffer would still be holding.
    Returns units per second.
    """
    held = samples[-HISTORY_SIZE:]
    if not held:
        return 0.0
    data_points = []
    time = []
    newest_time, _ = held[-1]
    previous_time = newest_time
    for sample_time, sample_position in reversed(held):
        age = float(newest_time - sample_time)
        delta = abs(float(sample_time - previous_time))
        # Lsq2 walks back sample to sample; only the non-differential
        # Impulse branch compares every sample against the newest one.
        previous_time = sample_time
        if age > HORIZON_MILLISECONDS or delta > ASSUME_POINTER_MOVE_STOPPED_MILLISECONDS:
            break
        data_points.append(sample_position)
        time.append(-age)
        if len(data_points) == HISTORY_SIZE:
            break
    if len(data_points) < MIN_SAMPLE_SIZE_LSQ2:
        return 0.0
    try:
        coefficients = poly_fit_least_squares(time, data_points, len(data_points), 2)
    except ValueError:
        return 0.0
    # The 2nd coefficient is the fitted polynomial's derivative at x = 0,
    # which is the newest sample's timestamp. units/ms -> units/s.
    return coefficients[1] * 1000.0
 def clamped(velocity, maximum):
    """`VelocityTracker1D.calculateVelocity(maximumVelocity)`."""
    if velocity == 0.0 or math.isnan(velocity):
        return 0.0
    return min(velocity, maximum) if velocity > 0 else max(velocity, -maximum)
 def average(samples):
    """The estimator being replaced: total motion over the span."""
    if len(samples) < 2:
        return 0.0
    span = (samples[-1][0] - samples[0][0]) / 1000.0
    if span <= 0.0:
        return 0.0
    return (samples[-1][1] - samples[0][1]) / span
 # --- The three recorded sample sets the Rust tests assert on. ----------------
 # 1. `transcript-fixture/touch/flick-120hz.touch`, as `DragGesture` feeds it:
 #    the DOWN position, then one position per MOVE. The UP at t=20 adds no
 #    sample (see the module doc), which is why the finger sitting still for its
 #    last 4ms does not drag the estimate down. y only; the flick is vertical.
 FLICK_120HZ = [(0, 1000.0), (4, 1040.0), (8, 1086.0), (12, 1138.0), (16, 1196.0)]
 # 2. A steady drag: 5px every 10ms for 100ms. A constant-velocity fit and an
 #    average must agree here -- this is the case that cannot tell the two
 #    estimators apart, which is why it is not the only one.
 STEADY_DRAG = [(i * 10, float(i * 5)) for i in range(11)]
 # 3. A flick that accelerates into the release: 10ms apart, deltas doubling.
 #    This is the case the average gets wrong, and the negative control for
 #    the port -- reverting to the average must fail this test and only this
 #    kind of test.
 ACCELERATING_FLICK = [(0, 0.0), (10, 2.0), (20, 6.0), (30, 14.0), (40, 30.0), (50, 54.0)]
 # 4. The two edges of the sample walk, checked here so the Rust asserts
 #    Compose's answer rather than iris's own reading of the rule.
 #    (a) An old, fast burst outside the 100ms horizon, then a slow steady
 #        drag: the burst must not leak into the estimate.
 OLD_BURST_THEN_STEADY = [(0, 0.0)] + [(10 + i * 10, 1000.0 + i) for i in range(11)]
 #    (b) The finger stops for 48ms and then lifts. The gap exceeds
 #        AssumePointerMoveStopped, so the walk breaks after one sample and
 #        there is no fling -- what stops a "park it and let go" from
 #        flinging at whatever speed the finger arrived with.
 STOPPED_BEFORE_RELEASE = [(0, 0.0), (4, 40.0), (8, 90.0), (12, 150.0), (60, 152.0)]
 # 5. `sense.rs`'s own `drag_gesture_tests`: what `DragGesture` feeds for a
 #    press and two move frames, which is the fewest a fit can use.
 TWO_MOVE_FRAMES = [(0, 0.0), (8, 100.0), (16, 220.0)]
 #    ... and one move frame, which Compose cannot fit either.
 ONE_MOVE_FRAME = [(0, 0.0), (8, 100.0)]
 # The phone: 1080x2424 at content_scale 2.55.
 PHONE_DENSITY = 2.55
 def report(name, samples):
    v = calculate_velocity(samples)
    print(f"{name}:")
    print(f"  samples (t_ms, position): {samples}")
    print(f"  Lsq2 (Compose's touch path):    {v:.4f} px/s")
    print(f"  average (the old estimator):    {average(samples):.4f} px/s")
    print(f"  impulse (non-touch, for ref):   ", end="")
    held = list(reversed(samples[-HISTORY_SIZE:]))
    newest = held[0][0]
    print(
        f"{calculate_impulse_velocity([p for _, p in held], [-(newest - t) for t, _ in held], len(held), False) * 1000.0:.4f} px/s"
    )
    print()
 if __name__ == "__main__":
    print("Compose 1.12.0 touch velocity: VelocityTracker1D, Strategy.Lsq2,")
    print("non-differential (positions), HistorySize=20, Horizon=100ms,")
    print("AssumePointerMoveStopped=40ms, minSampleSize=3.\n")
    report("flick-120hz.touch", FLICK_120HZ)
    report("steady drag (5px/10ms)", STEADY_DRAG)
    report("accelerating flick (deltas 2,4,8,16,24 per 10ms)", ACCELERATING_FLICK)
    report("old burst then steady 1px/10ms", OLD_BURST_THEN_STEADY)
    report("stopped 48ms before release", STOPPED_BEFORE_RELEASE)
    report("press and two move frames", TWO_MOVE_FRAMES)
    report("press and one move frame", ONE_MOVE_FRAME)
    print("Clamps:")
    print(f"  maximum: {MAXIMUM_FLING_VELOCITY_DP_S} dp/s")
    print(
        f"           = {MAXIMUM_FLING_VELOCITY_DP_S * PHONE_DENSITY:.1f} px/s at the phone's density {PHONE_DENSITY}"
    )
    print(f"  minimum: none on the fling path; DefaultFlingBehavior skips |v| <= {FLING_MINIMUM_PX_S} px/s")
    print()
    print("Two samples only (a press and one move, the phone's 120Hz worst case):")
    print(f"  Lsq2 needs 3 and answers {calculate_velocity(FLICK_120HZ[:2]):.4f} px/s")
@@ -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 }
@@ -1,6 +1,6 @@
 use super::*;
-#[derive(Copy, Clone, Eq, PartialEq)]
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum Axis {
    X,
    Y,
@@ -9,7 +9,31 @@ pub struct Size {
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Len {
    /// Physical pixels -- a raw device pixel, unaffected by the display's
    /// density. Rare to want directly (a hairline border is the usual
    /// case); most sizes should be `dp` instead. See `dp`'s own doc for why
    /// the two are kept separate rather than one field a caller has to
    /// remember to pre-multiply.
    pub abs: f32,
    /// Density-independent pixels -- Android's `dp` / CSS's reference pixel
    /// (1 unit = 1/160in), resolved against the display's density at
    /// layout time (`apply_rest`'s `density` parameter) rather than at the
    /// point a widget is built, since density is a property of the device
    /// this ends up running on, not of the widget tree. This is the unit
    /// IRIS_TODO.md's "a density-independent length unit" item asked for,
    /// 2026-09-06: before it existed, every size in the tree was `abs`
    /// (physical pixels), and the only way to make a 16px design draw at
    /// the right *size* on a denser display was a single global multiply
    /// applied to the whole rendered scene after layout -- which is also
    /// what made text blurry (RUST.md's P0 box, "blurry ... glyphs drawn
    /// at logical size and stretched by the scale"): a glyph rasterised at
    /// 16 physical px and then stretched 3x by that global multiply is a
    /// 48px area sampled from a 16px bitmap. Resolving `dp` per-length at
    /// layout time instead means the font size handed to the text shaper
    /// is already the physical size (`16.0.dp() * 3.0`), so the glyph
    /// atlas rasterises at the display's real resolution and nothing
    /// downstream needs to stretch anything.
    pub dp: f32,
    pub rel: f32,
    pub rest: f32,
 }
@@ -67,10 +91,10 @@ impl Size {
        }
    }
-    pub fn to_uivec2(self) -> UiVec2 {
+    pub fn to_uivec2(self, density: f32) -> UiVec2 {
        UiVec2 {
-            x: self.x.apply_rest(),
+            x: self.x.apply_rest(density),
-            y: self.y.apply_rest(),
+            y: self.y.apply_rest(density),
        }
    }
@@ -98,26 +122,66 @@ impl Size {
 impl Len {
    pub const ZERO: Self = Self {
        abs: 0.0,
        dp: 0.0,
        rel: 0.0,
        rest: 0.0,
    };
    pub const REST: Self = Self {
        abs: 0.0,
        dp: 0.0,
        rel: 0.0,
        rest: 1.0,
    };
-    pub fn apply_rest(&self) -> UiScalar {
+    /// Resolves to a `UiScalar`, folding `dp` into `abs` pixels against
    /// `density` (physical pixels per dp -- 1.0 on a desktop or an
    /// unscaled display, `content_scale` on Android; see `dp`'s field
    /// doc). Every other component of `Len` is already resolution-
    /// independent (`rel` is a fraction of the parent; `rest` becomes a
    /// fraction too, below), so `density` only ever touches this one term.
    pub fn apply_rest(&self, density: f32) -> UiScalar {
        UiScalar {
            rel: self.rel + if self.rest > 0.0 { 1.0 } else { 0.0 },
-            abs: self.abs,
+            abs: self.abs + self.dp * density,
        }
    }
    /// The same fold as [`Self::apply_rest`] but staying a `Len`, so
    /// `rest` survives: `dp` becomes physical pixels and every other
    /// component is left alone.
    ///
    /// **A `Len` a widget *reports* must have been through this.** `dp` is
    /// an input unit -- a number the widget author wrote -- and the
    /// containers that consume a reported length read `abs`/`rel`/`rest`
    /// directly (`Span::draw`'s placement arithmetic, `Pad`'s addition),
    /// so a reported `dp` is silently worth zero. That is what made the
    /// composer's bar collapse to nothing the moment its content grew past
    /// `MaxSize`'s cap: the cap was `dp(168)` and was returned unresolved,
    /// so the bar was given a slot of 0 and the field inside it was panned
    /// out of a container measured at -63px. `UiRenderState::draw_inner`
    /// debug-asserts the invariant after every `Widget::draw`.
    pub fn fold_dp(&self, density: f32) -> Self {
        Self {
            abs: self.abs + self.dp * density,
            dp: 0.0,
            rel: self.rel,
            rest: self.rest,
        }
    }
    pub fn abs(abs: impl UiNum) -> Self {
        Self {
            abs: abs.to_f32(),
            dp: 0.0,
            rel: 0.0,
            rest: 0.0,
        }
    }
    pub fn dp(dp: impl UiNum) -> Self {
        Self {
            abs: 0.0,
            dp: dp.to_f32(),
            rel: 0.0,
            rest: 0.0,
        }
@@ -125,6 +189,7 @@ impl Len {
    pub fn rel(rel: impl UiNum) -> Self {
        Self {
            abs: 0.0,
            dp: 0.0,
            rel: rel.to_f32(),
            rest: 0.0,
        }
@@ -132,6 +197,7 @@ impl Len {
    pub fn rest(ratio: impl UiNum) -> Self {
        Self {
            abs: 0.0,
            dp: 0.0,
            rel: 0.0,
            rest: ratio.to_f32(),
        }
@@ -144,6 +210,15 @@ pub mod len_fns {
    pub fn abs(abs: impl UiNum) -> Len {
        Len {
            abs: abs.to_f32(),
            dp: 0.0,
            rel: 0.0,
            rest: 0.0,
        }
    }
    pub fn dp(dp: impl UiNum) -> Len {
        Len {
            abs: 0.0,
            dp: dp.to_f32(),
            rel: 0.0,
            rest: 0.0,
        }
@@ -151,6 +226,7 @@ pub mod len_fns {
    pub fn rel(rel: impl UiNum) -> Len {
        Len {
            abs: 0.0,
            dp: 0.0,
            rel: rel.to_f32(),
            rest: 0.0,
        }
@@ -158,14 +234,15 @@ pub mod len_fns {
    pub fn rest(ratio: impl UiNum) -> Len {
        Len {
            abs: 0.0,
            dp: 0.0,
            rel: 0.0,
            rest: ratio.to_f32(),
        }
    }
 }
-impl_op!(Len Add add; abs rel rest);
+impl_op!(Len Add add; abs dp rel rest);
-impl_op!(Len Sub sub; abs rel rest);
+impl_op!(Len Sub sub; abs dp rel rest);
 impl_op!(Size Add add; x y);
 impl_op!(Size Sub sub; x y);
@@ -187,6 +264,9 @@ impl std::fmt::Display for Len {
        if self.abs != 0.0 {
            write!(f, "{} abs;", self.abs)?;
        }
        if self.dp != 0.0 {
            write!(f, "{} dp;", self.dp)?;
        }
        if self.rel != 0.0 {
            write!(f, "{} rel;", self.rel)?;
        }
@@ -1,10 +1,6 @@
 use std::ops::{Index, IndexMut};
-use crate::{
+use crate::{render::LayerOrder, util::to_mut};
    UiRegion, WidgetId,
    render::{MaskIdx, MoveIdx, Primitive, PrimitiveHandle, PrimitiveInst, Primitives},
    util::to_mut,
 };
 pub type LayerId = usize;
@@ -40,7 +36,10 @@ struct Child {
    tail: usize,
 }
-pub type PrimitiveLayers = Layers<Primitives>;
+/// The draw order of every layer. The primitives themselves live in one
 /// arena beside this (`UiRenderState::primitives`); a layer names the
 /// slots it draws, which is what its vertex buffer is.
 pub type PrimitiveLayers = Layers<LayerOrder>;
 impl<T: Default> Layers<T> {
    pub fn new() -> Layers<T> {
@@ -120,32 +119,6 @@ impl<T: Default> Layers<T> {
    }
 }
 impl PrimitiveLayers {
    pub fn write<P: Primitive>(
        &mut self,
        layer: LayerId,
        info: PrimitiveInst<P>,
    ) -> PrimitiveHandle {
        self[layer].write(layer, info)
    }
    pub fn free(&mut self, h: &PrimitiveHandle) -> MaskIdx {
        self[h.layer].free(h)
    }
    pub fn write_image(
        &mut self,
        layer: LayerId,
        id: WidgetId,
        texture_idx: u32,
        region: UiRegion,
        mask_idx: MaskIdx,
        move_idx: MoveIdx,
    ) -> PrimitiveHandle {
        self[layer].write_image(layer, id, texture_idx, region, mask_idx, move_idx)
    }
 }
 impl<T: Default> Default for Layers<T> {
    fn default() -> Self {
        Self::new()
@@ -10,6 +10,35 @@ use swash::{
    zeno::{Format, Vector},
 };
 /// What starting up found about text rendering, for the on-screen
 /// Diagnostics page and the one startup log line (RUST.md's P0 box, "log
 /// once at startup ... the number of font families found, the default
 /// family resolved"). Built once by `TextData::font_diagnostics` --
 /// `Default::default` still exists for callers (tests, examples) that
 /// don't need the report.
 #[derive(Clone, Debug)]
 pub struct FontDiagnostics {
    /// `Collection::family_names().count()` after registering the bundled
    /// fonts -- system families plus the two bundled ones.
    pub families_found: usize,
    /// The family `GenericFamily::SansSerif` resolves to first -- the
    /// bundled "Noto Sans" unless registration itself failed.
    pub default_family: Option<String>,
    /// The family `GenericFamily::Monospace` resolves to first.
    pub default_mono_family: Option<String>,
    /// One resolved family name per style axis this crate actually uses
    /// (`SpanStyle::bold`/`italic`), so a report can say plainly whether a
    /// bold/italic request is landing on a real face rather than being
    /// silently absorbed by whatever the sans-serif default resolves to
    /// for every weight (RUST.md's P0 box, "bold words render as blank
    /// gaps" -- a family that resolves but has no distinct bold face is
    /// exactly what produced that).
    pub regular_resolved: Option<String>,
    pub bold_resolved: Option<String>,
    pub italic_resolved: Option<String>,
    pub mono_resolved: Option<String>,
 }
 /// Everything text needs that outlives one string: the font collection, the
 /// layout scratch space, the glyph rasteriser and the atlas they fill.
 pub struct TextData {
@@ -17,15 +46,221 @@ pub struct TextData {
    pub layout_cx: LayoutContext<UiColor>,
    scale_cx: ScaleContext,
    pub atlas: GlyphAtlas,
    /// Physical pixels per dp -- a second copy of
    /// `UiRenderState::density`, kept here too because `TextEditCtx::layout`
    /// (cursor movement and hit-testing, `widget/text/edit.rs`) shapes text
    /// from an event callback that has a `TextData` but no `Painter`, so it
    /// has nowhere else to read the display's density from. Both copies are
    /// set together, from the one place either backend learns the real
    /// value (`android::view::new_peer`); this is the same accepted
    /// duplication as `AndroidRenderer::content_scale`; a single source of
    /// truth would mean carrying a `Painter` (or output size) into every
    /// input handler for the sake of one field.
    pub density: f32,
 }
 impl Default for TextData {
    /// Text comes entirely from the platform's own font collection --
    /// `FontContext::new()` builds a `fontique::Collection` with
    /// `CollectionOptions::system_fonts` on by default, which is real
    /// discovery on both targets this crate ships on: Android's backend
    /// parses `/system/fonts` and `/system/etc/fonts.xml` and maps
    /// `SansSerif`/`SystemUi` to `["Roboto Flex", "Roboto", "Noto Sans"]`
    /// and `Monospace` to the platform's `"monospace"` alias; the desktop
    /// build's backend is fontconfig. No font is bundled or registered
    /// here -- see DECISIONS.md's 2026-09-07 entry for why (matching what
    /// the Compose app does: it takes body/monospace text from
    /// `FontFamily.Default`/`FontFamily.Monospace`, i.e. Android's Roboto
    /// and its platform monospace face, and ships no text font of its own,
    /// only its committed Nerd Fonts icon subset for fixed glyphs).
    fn default() -> Self {
        let mut font_cx = FontContext::new();
        patch_android_monospace(&mut font_cx);
        Self {
-            font_cx: FontContext::new(),
+            font_cx,
            layout_cx: LayoutContext::new(),
            scale_cx: ScaleContext::new(),
            atlas: GlyphAtlas::default(),
            density: 1.0,
        }
    }
 }
 /// Works around `fontique` 0.11.1's Android backend never resolving
 /// `GenericFamily::Monospace` (confirmed against
 /// `fontique-0.11.1/src/backend/android.rs`'s `SystemFonts::new`, and still
 /// present on `linebender/parley`'s `main` as of 2026-09-07, so there is no
 /// released fix to bump to yet -- see DECISIONS.md's 2026-09-07 entry,
 /// "Platform fonts," for the full account). Two bugs stack, not one:
 /// `DEFAULT_GENERIC_FAMILIES` looks up the name `"monospace"` *before*
 /// `fonts.xml` is parsed into that same name map, and even after parsing,
 /// AOSP's `fonts.xml` names it with a `<family name="monospace">` element
 /// (not an `<alias>`) whose `<font>` children the backend's own parser
 /// does not read (a `TODO` in that match arm) -- so the name gets a
 /// `FamilyId` with no font data behind it, and `family_by_name("monospace")`
 /// comes back empty too. Confirmed on this checkout's emulator: `adb pull
 /// /system/etc/fonts.xml` shows
 /// `<family name="monospace"><font weight="400"
 /// style="normal">DroidSansMono.ttf</font></family>` with no matching
 /// alias.
 ///
 /// So this reads `fonts.xml` itself (already on-device, already the
 /// authority Compose's own `Typeface.MONOSPACE` resolves through) for the
 /// filename that declaration names, then finds which of fontique's
 /// *actually* scanned families (from `/system/fonts`, which do carry real
 /// font data, just under whatever name the font's own metadata gives it --
 /// "Droid Sans Mono" here, but that name is never hardcoded) owns a font
 /// file with that name, and registers that family as the `Monospace`
 /// generic the way the backend itself would have if its parser had reified
 /// the declaration. A no-op if the family is somehow already resolved
 /// (future fontique) or nothing matches (no `fonts.xml`, e.g. a headless
 /// test, or a device that names it some other way).
 #[cfg(target_os = "android")]
 fn patch_android_monospace(font_cx: &mut FontContext) {
    use parley::fontique::SourceKind;
    let already_resolved = font_cx
        .collection
        .generic_families(GenericFamily::Monospace)
        .next()
        .is_some();
    if already_resolved {
        return;
    }
    let Some(target_file) = android_monospace_font_filename() else {
        return;
    };
    let names: Vec<String> = font_cx
        .collection
        .family_names()
        .map(str::to_string)
        .collect();
    for name in names {
        let Some(id) = font_cx.collection.family_id(&name) else {
            continue;
        };
        let Some(info) = font_cx.collection.family(id) else {
            continue;
        };
        let Some(font) = info.default_font() else {
            continue;
        };
        let SourceKind::Path(path) = font.source().kind() else {
            continue;
        };
        if path.file_name().and_then(|f| f.to_str()) == Some(target_file.as_str()) {
            font_cx
                .collection
                .append_generic_families(GenericFamily::Monospace, std::iter::once(id));
            return;
        }
    }
 }
 /// Reads the font filename `fonts.xml` names for its `"monospace"` family
 /// (e.g. `"DroidSansMono.ttf"`), by plain substring search rather than a
 /// real XML parser -- a new dependency for one well-known, stable AOSP file
 /// whose structure fontique itself already parses with a full parser one
 /// module over. Not a general XML reader; assumes the file has exactly one
 /// `<family name="monospace">` element with at least one `<font>` child,
 /// which is the format on every AOSP `fonts.xml` this was checked against.
 #[cfg(target_os = "android")]
 fn android_monospace_font_filename() -> Option<String> {
    let android_root = std::env::var("ANDROID_ROOT").unwrap_or_else(|_| "/system".to_string());
    let xml =
        std::fs::read_to_string(std::path::Path::new(&android_root).join("etc/fonts.xml")).ok()?;
    let family_start = xml.find("<family name=\"monospace\">")?;
    let block = &xml[family_start..];
    let block = &block[..block.find("</family>")?];
    let font_tag = block.find("<font")?;
    let after_tag = &block[font_tag..];
    let content_start = after_tag.find('>')? + 1;
    let content = &after_tag[content_start..];
    let filename = content[..content.find('<')?].trim();
    (!filename.is_empty()).then(|| filename.to_string())
 }
 #[cfg(not(target_os = "android"))]
 fn patch_android_monospace(_font_cx: &mut FontContext) {}
 impl TextData {
    /// Builds the startup report -- see `FontDiagnostics`. Queries the
    /// collection directly (`fontique::Query`) rather than shaping a real
    /// string, since all that's needed is which family each axis lands on.
    pub fn font_diagnostics(&mut self) -> FontDiagnostics {
        use parley::fontique::{Attributes, FontWidth, QueryStatus};
        let families_found = self.font_cx.collection.family_names().count();
        let default_family_id = self
            .font_cx
            .collection
            .generic_families(GenericFamily::SansSerif)
            .next();
        let default_family = default_family_id
            .and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string));
        let default_mono_family_id = self
            .font_cx
            .collection
            .generic_families(GenericFamily::Monospace)
            .next();
        let default_mono_family = default_mono_family_id
            .and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string));
        // Resolves the family a (generic family, weight, style) query lands
        // on, without holding the `Query`'s borrow of `collection` across
        // the `family_name` lookup that needs it back -- the `FamilyId` is
        // captured out of the closure first, then looked up once `query`
        // (and its borrow) has been dropped.
        let mut resolve_family =
            |generic: GenericFamily, weight: FontWeight, style: FontStyle| -> Option<String> {
                let mut family_id = None;
                {
                    let mut query = self
                        .font_cx
                        .collection
                        .query(&mut self.font_cx.source_cache);
                    query.set_families([generic]);
                    query.set_attributes(Attributes {
                        width: FontWidth::NORMAL,
                        style,
                        weight,
                    });
                    query.matches_with(|font| {
                        family_id = Some(font.family.0);
                        QueryStatus::Stop
                    });
                }
                family_id.and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string))
            };
        let regular_resolved = resolve_family(
            GenericFamily::SansSerif,
            FontWeight::NORMAL,
            FontStyle::Normal,
        );
        let bold_resolved = resolve_family(
            GenericFamily::SansSerif,
            FontWeight::BOLD,
            FontStyle::Normal,
        );
        let italic_resolved = resolve_family(
            GenericFamily::SansSerif,
            FontWeight::NORMAL,
            FontStyle::Italic,
        );
        let mono_resolved = resolve_family(
            GenericFamily::Monospace,
            FontWeight::NORMAL,
            FontStyle::Normal,
        );
        FontDiagnostics {
            families_found,
            default_family,
            default_mono_family,
            regular_resolved,
            bold_resolved,
            italic_resolved,
            mono_resolved,
        }
    }
 }
@@ -159,7 +394,7 @@ pub struct TextBuffer {
    /// `set_spans` forces `shaped` to `None` directly, the same way `edit`
    /// does, since spans change far less often than a naive equality check
    /// on the whole `Vec` would cost to compute every frame.
-    shaped: Option<(TextAttrs, Option<f32>)>,
+    shaped: Option<(TextAttrs, Option<f32>, f32)>,
 }
 impl TextBuffer {
@@ -215,19 +450,42 @@ impl TextBuffer {
        Vec2::new(self.layout.width(), self.layout.height())
    }
-    /// Lay the text out, unless it is already laid out for these attributes and
+    /// Lay the text out, unless it is already laid out for these
-    /// this width.
+    /// attributes, this width and this density.
-    pub fn shape(&mut self, data: &mut TextData, attrs: &TextAttrs, width: Option<f32>) {
+    ///
-        if self.shaped.as_ref() == Some(&(attrs.clone(), width)) {
+    /// **`attrs.font_size`/`line_height` and every span's own `font_size`
    /// are density-independent (dp) units, multiplied by `density` here --
    /// the one place text crosses from the widget tree's dp sizes into the
    /// physical pixels the shaper and rasteriser (`TextData::place`) both
    /// then work in.** This is what makes glyphs sharp on a dense display:
    /// before this existed, `font_size` was already a physical-pixel value
    /// (RUST.md's P0 box's global-scale stopgap resolved density by
    /// stretching the whole rendered frame afterward instead), so a glyph
    /// was rasterised small and then upscaled by whatever the display's
    /// scale factor was -- exactly the blur Iris's report described.
    /// Multiplying here instead means the font size hitting `ScaleContext`
    /// in `place` below is already the display's real physical size, so
    /// the atlas holds a bitmap at the resolution it is actually shown at.
    /// `GlyphKey.size` already keys on that resolved `font_size`
    /// (`(font_size * 16.0).round()`), so a cache entry is naturally per
    /// physical size with no change needed there.
    pub fn shape(
        &mut self,
        data: &mut TextData,
        attrs: &TextAttrs,
        width: Option<f32>,
        density: f32,
    ) {
        if self.shaped.as_ref() == Some(&(attrs.clone(), width, density)) {
            return;
        }
        let mut builder = data
            .layout_cx
            .ranged_builder(&mut data.font_cx, &self.text, 1.0, true);
        builder.push_default(StyleProperty::FontFamily(attrs.family.family()));
-        builder.push_default(StyleProperty::FontSize(attrs.font_size));
+        builder.push_default(StyleProperty::FontSize(attrs.font_size * density));
        builder.push_default(StyleProperty::LineHeight(LineHeight::Absolute(
-            attrs.line_height,
+            attrs.line_height * density,
        )));
        builder.push_default(StyleProperty::Brush(attrs.color));
        for span in &self.spans {
@@ -239,7 +497,7 @@ impl TextBuffer {
                builder.push(StyleProperty::FontFamily(family.family()), range.clone());
            }
            if let Some(size) = span.font_size {
-                builder.push(StyleProperty::FontSize(size), range.clone());
+                builder.push(StyleProperty::FontSize(size * density), range.clone());
            }
            if span.bold {
                builder.push(StyleProperty::FontWeight(FontWeight::BOLD), range.clone());
@@ -255,7 +513,7 @@ impl TextBuffer {
        self.layout.break_all_lines(width);
        self.layout
            .align(Alignment::Start, AlignmentOptions::default());
-        self.shaped = Some((attrs.clone(), width));
+        self.shaped = Some((attrs.clone(), width, density));
    }
 }
@@ -362,6 +620,11 @@ pub struct RenderedText {
    pub glyphs: std::sync::Arc<Vec<PlacedGlyph>>,
    pub size: Vec2,
    pub color: UiColor,
    /// The [`GlyphAtlas::generation`] the glyphs above were placed against.
    /// A holder must re-render rather than re-emit these quads once the
    /// atlas has moved on (`GlyphAtlas::clear`'s doc says what happens
    /// otherwise); `Painter::glyphs` debug-asserts it.
    pub generation: u64,
 }
 impl TextData {
@@ -372,13 +635,15 @@ impl TextData {
        attrs: &TextAttrs,
        width: Option<f32>,
        textures: &mut Textures,
        density: f32,
    ) -> RenderedText {
-        buffer.shape(self, attrs, width);
+        buffer.shape(self, attrs, width, density);
        let glyphs = self.place(buffer, textures);
        RenderedText {
            glyphs: std::sync::Arc::new(glyphs),
            size: buffer.size(),
            color: attrs.color,
            generation: self.atlas.generation(),
        }
    }
 }
@@ -141,6 +141,27 @@ impl Textures {
        self.updates.push(Update::Patch(handle.slot, rect));
    }
    /// Forget every image, page and pending update -- what a genuinely new
    /// GPU device needs alongside [`crate::render::atlas::GlyphAtlas::
    /// clear`], which this module's own doc references: every slot number
    /// and every queued [`Update`] here describes the *old* device's
    /// textures (an `Update::Push`/`Update::Patch` already drained into a
    /// renderer that no longer exists is gone for good, and a fresh
    /// `UiRenderNode`'s own texture manager starts with none of them
    /// applied), so nothing is lost by starting this bookkeeping over too.
    /// Any `TextureHandle` a caller still holds across the reset (none in
    /// the transcript screen this reset is wired up for today -- confirmed
    /// by grep, the only standalone (non-atlas) image anywhere in this
    /// workspace is `iris/widget/image.rs`'s `Image`, used by the separate
    /// `tabs-ui` example) is left pointing at a slot this instance no
    /// longer recognises and needs reinserting via `add`/`add_page` again
    /// -- the same pre-existing gap a renderer restart already left for
    /// such a handle before this method existed, just named rather than
    /// silent now.
    pub fn reset(&mut self) {
        *self = Self::new();
    }
    pub fn free(&mut self) {
        for (kind, idx) in self.recv.try_iter() {
            self.images[idx as usize] = None;
@@ -71,6 +71,10 @@ struct Page {
 #[derive(Default)]
 pub struct GlyphAtlas {
    pages: Vec<Page>,
    /// Bumped by [`GlyphAtlas::clear`], so anything holding placed glyphs
    /// from an earlier atlas can tell that its coordinates are stale --
    /// see that method's doc for what goes wrong without it.
    generation: u64,
    /// `None` for a glyph that rasterised to nothing -- a space, say. Cached
    /// too, so it is not re-rasterised on every layout.
    entries: HashMap<GlyphKey, Option<GlyphEntry>>,
@@ -166,6 +170,13 @@ impl GlyphAtlas {
        self.entries.insert(key, None);
    }
    /// Which atlas the entries handed out right now belong to. A
    /// [`crate::RenderedText`] records this when it is built and is only
    /// reusable while it still matches.
    pub fn generation(&self) -> u64 {
        self.generation
    }
    pub fn page_count(&self) -> usize {
        self.pages.len()
    }
@@ -173,6 +184,36 @@ impl GlyphAtlas {
    pub fn glyph_count(&self) -> usize {
        self.entries.len()
    }
    /// Forget every page and every rasterised entry -- what a genuinely new
    /// GPU device needs (`android::view::IrisViewPeer::surface_changed`'s
    /// "not already live" branch, e.g. after backgrounding): the pages this
    /// atlas remembers are `TextureHandle`s into the *old* device's
    /// textures, which no longer exist, and every `GlyphEntry`'s `uv_min`/
    /// `uv_max`/`layer` point into them. Without this, a glyph already
    /// cached here is treated as "already placed" and never re-inserted
    /// into the fresh (empty) atlas the new renderer actually has --
    /// exactly the "rectangles stay, glyphs disappear" bug the resize path
    /// (`AndroidRenderer::resize`) was built to avoid for the reuse case;
    /// this is its counterpart for the case where the renderer really is
    /// new. Dropping `pages` also drops its `TextureHandle`s, which send a
    /// free message back through their `Textures`; see `Textures::reset`'s
    /// doc for why that is harmless here.
    /// Bumping `generation` here is the other half of the same
    /// invalidation: emptying this atlas does nothing about the
    /// `RenderedText`s widgets are *already holding*
    /// (`iris::widget::TextView`'s `tex` cache), whose `PlacedGlyph`s carry
    /// `uv_min`/`uv_max`/`layer` into the atlas that has just been thrown
    /// away. Those redraw perfectly happily and sample whatever now sits at
    /// those coordinates -- the fragments-of-other-glyphs Iris photographed
    /// after resuming the app on 2026-09-06. One counter, checked where the
    /// cache is read, is what makes a cached render un-reusable across a
    /// renderer rebuild.
    pub fn clear(&mut self) {
        self.pages.clear();
        self.entries.clear();
        self.generation += 1;
    }
 }
 fn fits(page: &Page, need_w: u32, need_h: u32) -> bool {
@@ -8,6 +8,15 @@ pub struct WindowUniform {
    pub height: f32,
 }
 /// One primitive's placement and what to draw there, in the one arena
 /// every layer shares (`Primitives`). Read from a storage buffer by
 /// **both** shader stages: the vertex stage for the corners of the
 /// primitive it is drawing, the fragment stage for the corners of a
 /// *mask's* primitive, which is generally a different one and often in
 /// another layer. A layer's vertex buffer carries only the slot
 /// ([`instance_slot_layout`]), so there is exactly one copy of a
 /// placement and a mask cannot disagree with what was drawn. See
 /// LAYOUT.md's "Masks with a shape".
 #[repr(C)]
 #[derive(Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)]
 pub struct PrimitiveInstance {
@@ -18,24 +27,17 @@ pub struct PrimitiveInstance {
    pub move_idx: MoveIdx,
 }
-impl PrimitiveInstance {
+/// The vertex layout of a layer's draw order: one `u32` slot into the
-    const ATTRIBS: [VertexAttribute; 8] = vertex_attr_array![
+/// global instance arena per instance, stepped per instance. Everything a
-        0 => Float32x2,
+/// primitive is made of used to be here as eight vertex attributes; it
-        1 => Float32x2,
+/// moved into the storage buffer above so the fragment stage can read it
-        2 => Float32x2,
+/// too.
-        3 => Float32x2,
+pub fn instance_slot_layout() -> VertexBufferLayout<'static> {
-        4 => Uint32,
+    const ATTRIBS: [VertexAttribute; 1] = vertex_attr_array![0 => Uint32];
-        5 => Uint32,
+    VertexBufferLayout {
-        6 => Uint32,
+        array_stride: std::mem::size_of::<u32>() as BufferAddress,
-        7 => Uint32,
+        step_mode: VertexStepMode::Instance,
-    ];
+        attributes: &ATTRIBS,
    pub fn desc() -> VertexBufferLayout<'static> {
        VertexBufferLayout {
            array_stride: std::mem::size_of::<Self>() as BufferAddress,
            step_mode: VertexStepMode::Instance,
            attributes: &Self::ATTRIBS,
        }
    }
 }
@@ -56,6 +58,19 @@ pub struct Mask {
    /// primitive's own corners, so a mask and the content clipped by it
    /// can move independently. See LAYOUT.md section 2b.
    pub move_idx: MoveIdx,
    /// The mask this one was set *inside* (`MaskIdx::NONE` at the top), so
    /// clipping nests: the fragment stage walks the chain and a pixel has
    /// to be inside every mask on it. Chained rather than intersected on
    /// the CPU because each mask moves with its own widget -- a code fence
    /// inside a transcript row carries the row's scroll, the list's own
    /// box does not, and one region resolved when the fence was last drawn
    /// gets the second of those wrong as soon as the row moves.
    ///
    /// A child holds one ref on its parent's slot (`Painter::set_mask`),
    /// released when the child's own slot goes
    /// (`UiRenderState::remove`), so the chain cannot outlive what it
    /// points at.
    pub parent: MaskIdx,
 }
 /// One widget's cumulative on-screen translation, and the slot of the
@@ -1,15 +1,87 @@
-use std::time::Duration;
+use std::time::{Duration, Instant};
 /// The frame budget `dumpsys gfxinfo` also uses to call a frame "janky": the
 /// 60Hz vsync period. Kept as the same threshold so a percentage from this
-/// report and a percentage from `gfxinfo` mean the same thing.
+/// report and a percentage from `gfxinfo` mean the same thing. Only a
 /// fallback now that a caller can read the display's real refresh rate
 /// (`report_at_hz`/`mark_phase`'s callers) -- most devices are 60Hz, but a
 /// 90Hz or 120Hz phone judged against this constant would call every frame
 /// "late" that merely met its own, faster budget.
 pub const JANK_THRESHOLD: Duration = Duration::from_nanos(16_666_667);
 /// Enough frames for several minutes of scrolling before the oldest ones
 /// start being overwritten -- the same "diagnostic, not a log" sizing
 /// `FrameStats.kt`'s `CAP` uses on the Compose side, chosen independently
 /// here since a `Duration` is smaller than the six `Long` arrays it keeps.
-const RING_CAPACITY: usize = 4096;
+/// Bumped from 4096 for RUST.md's "Benchmark v2": a fling+stream+type+
 /// keyboard run is ~6,500+ frames on the Compose side, comfortably under
 /// this so `phase_stats` never has to report a phase as partially evicted.
 const RING_CAPACITY: usize = 16384;
 /// One `mark_phase` call: the wall-clock instant and the (0-based,
 /// never-reset-by-`reset`-except-at-`reset`-time) absolute frame index at
 /// which a phase began -- `phase_stats` slices `index_ring` against this to
 /// find which recorded samples belong to which phase, since the ring
 /// itself only keeps the most recent `RING_CAPACITY` samples' *values*,
 /// not which phase they were in.
 struct PhaseMark {
    name: String,
    start_index: u64,
    start_at: Instant,
 }
 /// One phase's own slice of a report -- RUST.md's "Benchmark v2" spec's
 /// "per-phase blocks in `FrameReport`... frames, late count/percent...
 /// p50/p90/p99, worst, duration". `Display` matches the shape
 /// `docs/bench/compose-phone-v2-2026-09-06.md`'s report already uses, so
 /// the two apps' reports read the same way side by side.
 pub struct PhaseStats {
    pub name: String,
    /// How many frames were recorded during this phase in total -- may
    /// exceed `late + (samples counted)` if some of this phase's frames
    /// have since been evicted from the ring by a very long run; that
    /// case is named in the `Display` rather than silently under-counted.
    pub frames: u64,
    pub duration: Duration,
    pub late: u64,
    pub late_percent: f64,
    pub p50: Duration,
    pub p90: Duration,
    pub p99: Duration,
    pub worst: Duration,
    /// `false` if this phase's frame count exceeds how many samples of it
    /// are still in the ring -- the percentiles above are then computed
    /// over whatever survived, not the whole phase. UI_RULES.md: this is
    /// the "we don't fully know" state, named rather than folded silently
    /// into a number that looks exact.
    pub complete: bool,
 }
 impl std::fmt::Display for PhaseStats {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        writeln!(
            f,
            "  {}: {} frames over {:.1}s{}",
            self.name,
            self.frames,
            self.duration.as_secs_f64(),
            if self.complete {
                ""
            } else {
                " (ring evicted some of this phase)"
            },
        )?;
        writeln!(f, "    late: {} ({:.1}%)", self.late, self.late_percent)?;
        writeln!(
            f,
            "      total  p50 {:.1}ms  p90 {:.1}ms  p99 {:.1}ms",
            self.p50.as_secs_f64() * 1000.0,
            self.p90.as_secs_f64() * 1000.0,
            self.p99.as_secs_f64() * 1000.0,
        )?;
        write!(f, "    worst {:.1}ms", self.worst.as_secs_f64() * 1000.0)
    }
 }
 /// A per-frame wall-time report iris keeps of itself, because `dumpsys
 /// gfxinfo` cannot see a `SurfaceView`'s own GPU-drawn frames at all
@@ -41,6 +113,11 @@ pub struct FrameReport {
    /// "Where iris's frame time goes" CPU/GPU split, added 2026-09-05).
    /// `ring[i] - submit_ring[i]` is that frame's `redraw_to_submit` half.
    submit_ring: Box<[Duration; RING_CAPACITY]>,
    /// The absolute (0-based, since the last `reset`) frame index each
    /// `ring`/`submit_ring` slot's sample belongs to -- what `phase_stats`
    /// slices against `PhaseMark::start_index` to tell which recorded
    /// frames fall in which phase.
    index_ring: Box<[u64; RING_CAPACITY]>,
    /// How many of `ring`'s slots hold a real sample -- saturates at
    /// `RING_CAPACITY`, unlike `total_frames` below which keeps counting.
    len: usize,
@@ -50,6 +127,12 @@ pub struct FrameReport {
    /// correct even once the ring itself only holds the most recent frames.
    total_frames: u64,
    janky_frames: u64,
    /// `mark_phase` calls since the last `reset`, oldest first -- see
    /// `phase_stats`. Empty on an ordinary run that never calls
    /// `mark_phase`, so `phase_stats` returns an empty `Vec` and a caller
    /// prints no "per phase:" section at all, matching RUST.md's "empty/
    /// absent on an ordinary 'Copy' press, which never marks a phase."
    phases: Vec<PhaseMark>,
 }
 /// One resolved reading. `Display` is the log line both the "Frame report"
@@ -107,10 +190,12 @@ impl FrameReport {
        Self {
            ring: Box::new([Duration::ZERO; RING_CAPACITY]),
            submit_ring: Box::new([Duration::ZERO; RING_CAPACITY]),
            index_ring: Box::new([0; RING_CAPACITY]),
            len: 0,
            pos: 0,
            total_frames: 0,
            janky_frames: 0,
            phases: Vec::new(),
        }
    }
@@ -131,6 +216,7 @@ impl FrameReport {
    pub fn record_split(&mut self, total: Duration, submit_to_present: Duration) {
        self.ring[self.pos] = total;
        self.submit_ring[self.pos] = submit_to_present;
        self.index_ring[self.pos] = self.total_frames;
        self.pos = (self.pos + 1) % RING_CAPACITY;
        self.len = (self.len + 1).min(RING_CAPACITY);
        self.total_frames += 1;
@@ -142,12 +228,98 @@ impl FrameReport {
    /// Clears every counter and every sample -- what the "Reset frame
    /// report" control calls, so a report covers only what was scrolled
    /// after the button was pressed (the same reason `FrameStats.kt`'s
-    /// `reset()` exists on the Compose side).
+    /// `reset()` exists on the Compose side). Also clears every phase
    /// mark, so a fresh run starts with no "per phase:" section until it
    /// marks one of its own.
    pub fn reset(&mut self) {
        self.len = 0;
        self.pos = 0;
        self.total_frames = 0;
        self.janky_frames = 0;
        self.phases.clear();
    }
    /// Marks the start of a named phase at the current moment -- every
    /// frame recorded from here until the next `mark_phase` (or `reset`)
    /// belongs to it. RUST.md's "Benchmark v2": a scripted bench run calls
    /// this once per phase (fling/stream/type/keyboard) so `phase_stats`
    /// can slice one whole run's frames by what was happening during each.
    pub fn mark_phase(&mut self, name: &str) {
        // `phase_stats`'s slicing (`idx >= phase.start_index && idx <
        // end_index`) silently produces an empty or nonsensical slice for
        // a phase pushed out of order rather than surfacing the misuse
        // (docs/REVIEW-2026-09-06.md finding 5).
        debug_assert!(
            self.phases
                .last()
                .is_none_or(|p| self.total_frames >= p.start_index)
        );
        self.phases.push(PhaseMark {
            name: name.to_string(),
            start_index: self.total_frames,
            start_at: Instant::now(),
        });
    }
    /// One [`PhaseStats`] per `mark_phase` call since the last `reset`,
    /// oldest first. `now` closes the last phase's wall-clock span (there
    /// is no "next phase" instant to use for it); `refresh_hz` is what
    /// each phase's own `late`/`late_percent` is judged against, read from
    /// the display rather than assumed -- RUST.md's "Benchmark v2": "late
    /// count/% against the display's refresh rate."
    pub fn phase_stats(&self, now: Instant, refresh_hz: f32) -> Vec<PhaseStats> {
        if self.phases.is_empty() || refresh_hz <= 0.0 {
            return Vec::new();
        }
        let budget = Duration::from_secs_f64(1.0 / refresh_hz as f64);
        self.phases
            .iter()
            .enumerate()
            .map(|(i, phase)| {
                let (end_index, end_at) = match self.phases.get(i + 1) {
                    Some(next) => (next.start_index, next.start_at),
                    None => (self.total_frames, now),
                };
                let frames = end_index.saturating_sub(phase.start_index);
                let mut samples: Vec<Duration> = (0..self.len)
                    .filter(|&j| {
                        let idx = self.index_ring[j];
                        idx >= phase.start_index && idx < end_index
                    })
                    .map(|j| self.ring[j])
                    .collect();
                let complete = samples.len() as u64 >= frames;
                if samples.is_empty() {
                    return PhaseStats {
                        name: phase.name.clone(),
                        frames,
                        duration: end_at.saturating_duration_since(phase.start_at),
                        late: 0,
                        late_percent: 0.0,
                        p50: Duration::ZERO,
                        p90: Duration::ZERO,
                        p99: Duration::ZERO,
                        worst: Duration::ZERO,
                        complete,
                    };
                }
                samples.sort_unstable();
                let pct = |p: usize| samples[(samples.len() * p / 100).min(samples.len() - 1)];
                let late = samples.iter().filter(|&&d| d > budget).count() as u64;
                PhaseStats {
                    name: phase.name.clone(),
                    frames,
                    duration: end_at.saturating_duration_since(phase.start_at),
                    late,
                    late_percent: 100.0 * late as f64 / samples.len() as f64,
                    p50: pct(50),
                    p90: pct(90),
                    p99: pct(99),
                    worst: *samples.last().expect("checked not empty above"),
                    complete,
                }
            })
            .collect()
    }
    /// `None` if nothing has been recorded since the last reset -- the
@@ -186,6 +358,28 @@ impl FrameReport {
            gpu_wait_p50: median(submit_samples),
        })
    }
    /// `(late count, late percent)` over every sample still in the ring,
    /// judged against `refresh_hz`'s own frame budget rather than the
    /// fixed 60Hz `JANK_THRESHOLD` -- RUST.md's "Benchmark v2": "late
    /// count/% against the display's refresh rate... print 'at N Hz (X ms
    /// budget)' like Compose does." A separate method from `report()`
    /// rather than a parameter on it, so `report()`'s own `janky_percent`
    /// (and the exact-boundary test pinned to `JANK_THRESHOLD`) is
    /// unaffected for every existing caller that never measured a real
    /// refresh rate. `(0, 0.0)` with nothing recorded or a non-positive
    /// `refresh_hz`.
    pub fn late_at_hz(&self, refresh_hz: f32) -> (u64, f64) {
        if self.len == 0 || refresh_hz <= 0.0 {
            return (0, 0.0);
        }
        let budget = Duration::from_secs_f64(1.0 / refresh_hz as f64);
        let late = self.ring[..self.len]
            .iter()
            .filter(|&&d| d > budget)
            .count() as u64;
        (late, 100.0 * late as f64 / self.len as f64)
    }
 }
 impl Default for FrameReport {
@@ -296,4 +490,68 @@ mod tests {
        // same pattern here.
        assert!(stats.worst <= Duration::from_millis(5));
    }
    #[test]
    fn no_marks_means_no_phases() {
        let mut r = FrameReport::new();
        r.record(Duration::from_millis(5));
        assert!(r.phase_stats(Instant::now(), 60.0).is_empty());
    }
    #[test]
    fn phases_slice_frames_by_when_they_were_marked() {
        let mut r = FrameReport::new();
        r.mark_phase("a");
        for _ in 0..5 {
            r.record(Duration::from_millis(10)); // 10ms: late at 60Hz (16.7ms budget)... no, 10<16.7, not late
        }
        r.mark_phase("b");
        for _ in 0..3 {
            r.record(Duration::from_millis(20)); // 20ms: late at 60Hz
        }
        let now = Instant::now();
        let phases = r.phase_stats(now, 60.0);
        assert_eq!(phases.len(), 2);
        assert_eq!(phases[0].name, "a");
        assert_eq!(phases[0].frames, 5);
        assert_eq!(phases[0].late, 0);
        assert_eq!(phases[0].worst, Duration::from_millis(10));
        assert_eq!(phases[1].name, "b");
        assert_eq!(phases[1].frames, 3);
        assert_eq!(phases[1].late, 3);
        assert_eq!(phases[1].late_percent, 100.0);
        assert_eq!(phases[1].worst, Duration::from_millis(20));
        assert!(phases[0].complete);
        assert!(phases[1].complete);
    }
    #[test]
    fn the_last_phase_runs_until_now() {
        let mut r = FrameReport::new();
        r.mark_phase("only");
        r.record(Duration::from_millis(1));
        std::thread::sleep(Duration::from_millis(20));
        let now = Instant::now();
        let phases = r.phase_stats(now, 60.0);
        assert_eq!(phases.len(), 1);
        assert!(phases[0].duration >= Duration::from_millis(20));
    }
    #[test]
    fn reset_clears_phase_marks() {
        let mut r = FrameReport::new();
        r.mark_phase("a");
        r.record(Duration::from_millis(1));
        r.reset();
        assert!(r.phase_stats(Instant::now(), 60.0).is_empty());
    }
    #[test]
    fn late_at_hz_uses_the_given_refresh_rate_not_the_fixed_60hz_constant() {
        let mut r = FrameReport::new();
        // 10ms is under 60Hz's 16.7ms budget but over 120Hz's 8.3ms one.
        r.record(Duration::from_millis(10));
        assert_eq!(r.late_at_hz(60.0), (0, 0.0));
        assert_eq!(r.late_at_hz(120.0), (1, 100.0));
    }
 }
@@ -1,9 +1,14 @@
 use crate::{
    UiData, UiRenderState,
-    render::{data::PrimitiveInstance, texture::GpuTextures, util::ArrBuf},
+    render::{
        data::{PrimitiveInstance, instance_slot_layout},
        texture::GpuTextures,
        util::ArrBuf,
    },
    util::{HashMap, Vec2},
 };
 use data::WindowUniform;
 use pollster::FutureExt;
 use wgpu::{
    util::{BufferInitDescriptor, DeviceExt},
    *,
@@ -65,9 +70,65 @@ pub fn device_limits() -> Limits {
    }
 }
 /// A capped log of wgpu's *uncaptured* errors -- everything that reaches
 /// `Device::on_uncaptured_error` rather than one of `UiRenderNode::new`'s
 /// own error scopes, i.e. every wgpu error raised outside device/pipeline
 /// creation: a validation failure during an ordinary frame's `update`/
 /// `draw`, for instance. wgpu's default handler for these is `panic!` with
 /// no caller able to intervene -- exactly what aborted the P0 bench APK
 /// once already (this file's `UiRenderNode::new` doc comment) -- so both
 /// platform backends install a handler here instead of leaving the default
 /// in place, per RUST.md's P0 box ("every wgpu uncaptured error ... it
 /// must never panic in release").
 ///
 /// Cheap to `Clone` (an `Arc` around the real storage) rather than a
 /// process-wide static, so a caller builds one alongside its `Device`,
 /// hands one clone to `on_uncaptured_error`'s closure and keeps the other
 /// for the Diagnostics page to read -- context passed explicitly, per
 /// AGENTS.md/CODE_RULES.md's "no globals" rather than reached for through a
 /// `OnceLock`.
 #[derive(Clone)]
 pub struct WgpuErrorLog {
    errors: std::sync::Arc<std::sync::Mutex<std::collections::VecDeque<String>>>,
 }
 /// How many uncaptured errors the log keeps -- old ones drop off the front
 /// rather than being trimmed on read, so a build spraying errors every
 /// frame doesn't grow this without bound.
 const WGPU_ERROR_LOG_CAP: usize = 20;
 impl Default for WgpuErrorLog {
    fn default() -> Self {
        Self {
            errors: std::sync::Arc::new(std::sync::Mutex::new(std::collections::VecDeque::new())),
        }
    }
 }
 impl WgpuErrorLog {
    pub fn record(&self, error: impl std::fmt::Display) {
        let mut errors = self.errors.lock().unwrap();
        if errors.len() >= WGPU_ERROR_LOG_CAP {
            errors.pop_front();
        }
        errors.push_back(error.to_string());
    }
    /// A snapshot for the Diagnostics page -- cloned rather than held,
    /// since the lock must not outlive one call.
    pub fn snapshot(&self) -> Vec<String> {
        self.errors.lock().unwrap().iter().cloned().collect()
    }
 }
 pub struct UiRenderNode {
    uniform_group: BindGroup,
    primitive_layout: BindGroupLayout,
    /// Group 1: `rects` and `glyphs`. Global and bound once per frame,
    /// not per layer -- a mask referencing a rect drawn in another layer
    /// has to be able to read it (see `Primitives`).
    primitives: PrimitiveBuffers,
    primitive_group: BindGroup,
    rsc_layout: BindGroupLayout,
    rsc_group: BindGroup,
@@ -77,6 +138,9 @@ pub struct UiRenderNode {
    active: Vec<usize>,
    window_buffer: Buffer,
    textures: GpuTextures,
    /// Every primitive's placement, read by the vertex stage for the
    /// primitive being drawn and by the fragment stage for a mask's.
    instances: ArrBuf<PrimitiveInstance>,
    masks: ArrBuf<Mask>,
    move_offsets: ArrBuf<MoveOffset>,
    /// Group 3: the masks and move-offsets storage buffers, on their own --
@@ -94,16 +158,16 @@ pub struct UiRenderNode {
    masks_group: BindGroup,
 }
 /// One layer's vertex buffers: the slots it draws, in order. The
 /// primitives themselves are in `UiRenderNode::instances`.
 struct RenderLayer {
-    instance: ArrBuf<PrimitiveInstance>,
+    order: ArrBuf<u32>,
-    primitives: PrimitiveBuffers,
+    /// A standalone image's slots, kept apart from `order` because each
-    primitive_group: BindGroup,
+    /// one draws with its own bind group -- see `UiRenderNode::draw`.
-    /// A standalone image's instances, kept apart from `instance` because
+    images: ArrBuf<u32>,
-    /// each one draws with its own bind group -- see `UiRenderNode::draw`.
+    /// The texture slot each entry of `images` draws with, in the same
-    image_instance: ArrBuf<PrimitiveInstance>,
+    /// order, refreshed alongside it. Not in the vertex buffer itself
-    /// The texture slot each entry of `image_instance` draws with, in the
+    /// because it names a bind group, not shader data.
    /// same order, refreshed alongside it. Not stored in the vertex buffer
    /// itself because it names a bind group, not shader data.
    image_tex_indices: Vec<u32>,
 }
@@ -111,6 +175,8 @@ impl UiRenderNode {
    pub fn draw<'a>(&'a self, pass: &mut RenderPass<'a>) {
        pass.set_pipeline(&self.pipeline);
        pass.set_bind_group(0, &self.uniform_group, &[]);
        // Group 1 is global now, so it is set here rather than per layer.
        pass.set_bind_group(1, &self.primitive_group, &[]);
        // Set once, not per layer or per image: masks/move_offsets are read
        // by every primitive and every standalone image alike, and living
        // in their own group (rather than folded into group 2 alongside the
@@ -120,14 +186,13 @@ impl UiRenderNode {
        pass.set_bind_group(3, &self.masks_group, &[]);
        for i in &self.active {
            let layer = &self.layers[i];
-            if layer.instance.len() == 0 && layer.image_instance.len() == 0 {
+            if layer.order.len() == 0 && layer.images.len() == 0 {
                continue;
            }
-            pass.set_bind_group(1, &layer.primitive_group, &[]);
+            if layer.order.len() > 0 {
            if layer.instance.len() > 0 {
                pass.set_bind_group(2, &self.rsc_group, &[]);
-                pass.set_vertex_buffer(0, layer.instance.buffer.slice(..));
+                pass.set_vertex_buffer(0, layer.order.buffer.slice(..));
-                pass.draw(0..4, 0..layer.instance.len() as u32);
+                pass.draw(0..4, 0..layer.order.len() as u32);
            }
            // Images draw after this layer's rects and glyphs, one draw call
            // each with its own bind group. That draws every image "on top"
@@ -136,8 +201,8 @@ impl UiRenderNode {
            // draw order was already undefined before images had their own
            // list -- nothing before this relied on interleaving a rect
            // between two images at a particular position.
-            if layer.image_instance.len() > 0 {
+            if layer.images.len() > 0 {
-                pass.set_vertex_buffer(0, layer.image_instance.buffer.slice(..));
+                pass.set_vertex_buffer(0, layer.images.buffer.slice(..));
                for (k, &tex_idx) in layer.image_tex_indices.iter().enumerate() {
                    pass.set_bind_group(2, self.textures.image_bind_group(tex_idx), &[]);
                    pass.draw(0..4, k as u32..k as u32 + 1);
@@ -152,69 +217,47 @@ impl UiRenderNode {
        queue: &Queue,
        ui: &mut UiData,
        ui_render: &mut UiRenderState,
-    ) {
+    ) -> FrameUpdateStats {
        self.active.clear();
-        for (i, primitives) in ui_render.layers.iter_mut() {
+        for (i, order) in ui_render.layers.iter_mut() {
            self.active.push(i);
-            for change in primitives.apply_free() {
+            let rlayer = self.layers.entry(i).or_insert_with(|| RenderLayer {
-                if let Some(inst) = ui_render.active.get_mut(&change.id) {
+                order: ArrBuf::new(
                    for h in &mut inst.primitives {
                        // `is_image` disambiguates: `instances` and `images`
                        // are separate lists with independent indices, so
                        // without it a rect's renumbering could be applied to
                        // an image handle that happened to share the same
                        // (layer, inst_idx).
                        if h.layer == i
                            && h.inst_idx == change.old
                            && (h.binding == IMAGE_BINDING) == change.is_image
                        {
                            h.inst_idx = change.new;
                            break;
                        }
                    }
                }
            }
            let rlayer = self.layers.entry(i).or_insert_with(|| {
                let primitives = PrimitiveBuffers::new(device);
                let primitive_group =
                    Self::primitive_group(device, &self.primitive_layout, primitives.buffers());
                RenderLayer {
                    instance: ArrBuf::new(
                        device,
                        BufferUsages::VERTEX | BufferUsages::COPY_DST,
                        "instance",
                    ),
                    primitives,
                    primitive_group,
                    image_instance: ArrBuf::new(
                        device,
                        BufferUsages::VERTEX | BufferUsages::COPY_DST,
                        "image instance",
                    ),
                    image_tex_indices: Vec::new(),
                }
            });
            if primitives.updated {
                rlayer
                    .instance
                    .update(device, queue, primitives.instances());
                rlayer.primitives.update(device, queue, primitives.data());
                rlayer.primitive_group = Self::primitive_group(
                    device,
-                    &self.primitive_layout,
+                    BufferUsages::VERTEX | BufferUsages::COPY_DST,
-                    rlayer.primitives.buffers(),
+                    "layer order",
-                );
+                ),
-                rlayer
+                images: ArrBuf::new(
-                    .image_instance
+                    device,
-                    .update(device, queue, primitives.image_instances());
+                    BufferUsages::VERTEX | BufferUsages::COPY_DST,
-                rlayer.image_tex_indices = primitives
+                    "layer image order",
-                    .image_instances()
+                ),
                image_tex_indices: Vec::new(),
            });
            if order.updated {
                rlayer.order.update(device, queue, order.order());
                rlayer.images.update(device, queue, order.images());
                rlayer.image_tex_indices = order
                    .images()
                    .iter()
-                    .map(|inst| inst.idx)
+                    .map(|&slot| ui_render.primitives.instance(slot).idx)
                    .collect();
-                primitives.updated = false;
+                order.updated = false;
            }
        }
        let instances_resized = if ui_render.primitives.updated {
            ui_render.primitives.updated = false;
            let resized = self
                .instances
                .update(device, queue, ui_render.primitives.instances());
            self.primitives
                .update(device, queue, ui_render.primitives.data());
            self.primitive_group =
                Self::primitive_group(device, &self.primitive_layout, self.primitives.buffers());
            resized
        } else {
            false
        };
        let masks_resized = if ui.masks.changed {
            ui.masks.changed = false;
            self.masks.update(device, queue, &ui.masks[..])
@@ -228,14 +271,23 @@ impl UiRenderNode {
        } else {
            false
        };
-        if masks_resized || moves_resized {
+        if masks_resized || moves_resized || instances_resized {
-            self.masks_group =
+            self.masks_group = Self::masks_group(
-                Self::masks_group(device, &self.masks_layout, &self.masks, &self.move_offsets);
+                device,
                &self.masks_layout,
                &self.masks,
                &self.move_offsets,
                &self.instances,
            );
        }
        let rebuild_main = self.textures.update(&mut ui.textures, &self.rsc_layout);
        if rebuild_main {
            self.rsc_group = Self::rsc_group(device, &self.rsc_layout, &self.textures);
        }
        FrameUpdateStats {
            masks_resized,
            moves_resized,
        }
    }
    /// Takes a size rather than a window type: this is the only thing the
@@ -251,26 +303,69 @@ impl UiRenderNode {
        queue.write_buffer(&self.window_buffer, 0, bytemuck::cast_slice(slice));
    }
-    pub fn new(device: &Device, queue: &Queue, config: &SurfaceConfiguration) -> Self {
+    /// Builds every bind group layout, the pipeline, and the two storage
    /// buffers this needs -- fallibly, since this is exactly the call that
    /// aborted the process on Iris's phone in a release build with no
    /// message beyond "wgpu error: Validation Error" (RUST.md's P0 box,
    /// "iris bench crash on the phone, 2026-09-06"). wgpu's own default
    /// behaviour for an uncaptured error is `panic!` with no caller able to
    /// intervene, so every `create_bind_group_layout`/`create_render_pipeline`
    /// call below runs inside three nested error scopes (one per
    /// `ErrorFilter`) instead: whichever scope catches something, its
    /// `wgpu::Error`'s `Display` is wgpu-core's own `format_error` output
    /// (`"Validation Error\n\nCaused by:\n  ..."`, the same text the panic
    /// would have printed before Android's crash reporter truncated it) and
    /// becomes this function's `Err`. Both callers
    /// (`android::render::AndroidRenderer::new`, `default::render::
    /// UiRenderer::new`) already call `Device`-creation with
    /// `pollster::block_on`, so returning a plain `Result` here rather than
    /// making this `async fn` keeps that same synchronous shape.
    pub fn new(
        device: &Device,
        queue: &Queue,
        config: &SurfaceConfiguration,
        window_size: impl Into<Vec2>,
    ) -> Result<Self, String> {
        // Popped in reverse of this order, once every creation call below
        // has run -- `Device::push_error_scope`'s own contract.
        let oom_scope = device.push_error_scope(ErrorFilter::OutOfMemory);
        let validation_scope = device.push_error_scope(ErrorFilter::Validation);
        let internal_scope = device.push_error_scope(ErrorFilter::Internal);
        let shader = device.create_shader_module(ShaderModuleDescriptor {
            label: Some("UI Shape Shader"),
            source: ShaderSource::Wgsl(SHAPE_SHADER.into()),
        });
-        // Seeded from the surface's own size, not `WindowUniform::default()`
+        // Seeded from the caller's own reported size, not
-        // (0, 0): the vertex shader divides by `window.dim` to reach clip
+        // `WindowUniform::default()` (0, 0): the vertex shader divides by
-        // space, so a window this buffer disagrees with means every
+        // `window.dim` to reach clip space, so a window this buffer
-        // primitive's position is NaN/Inf and is dropped before
+        // disagrees with means every primitive's position is NaN/Inf and is
-        // rasterization -- the clear colour still reaches the screen (the
+        // dropped before rasterization -- the clear colour still reaches
-        // pass runs regardless) while nothing drawn on top of it ever does.
+        // the screen (the pass runs regardless) while nothing drawn on top
-        // winit's backend gets away with the old default because winit
+        // of it ever does. winit's backend gets away with the old default
-        // fires an initial `WindowEvent::Resized` that calls `resize()`
+        // because winit fires an initial `WindowEvent::Resized` that calls
-        // before the first frame; android-view has no such automatic
+        // `resize()` before the first frame; android-view has no such
-        // event, so `AndroidRenderer::new` built a node whose window buffer
+        // automatic event, so `AndroidRenderer::new` built a node whose
-        // was never corrected -- this is I2's "nothing draws" bug (RUST.md).
+        // window buffer was never corrected -- this is I2's "nothing draws"
-        let window_uniform = WindowUniform {
+        // bug (RUST.md).
-            width: config.width as f32,
+        //
-            height: config.height as f32,
+        // **Deliberately not `config.width`/`config.height`**: those are
        // the surface's *physical* pixel size, which the swapchain needs,
        // but everything downstream of this uniform (layout, hit-testing,
        // glyph/rect positions) works in the caller's own units -- on
        // Android that's *logical* (physical / density) since RUST.md's P0
        // box ("text is far too small"), on desktop it's whatever
        // `default::render::UiRenderer::new` already divides by
        // `window.scale_factor()`. Passing it in explicitly, rather than
        // deriving it from `config` here, is what keeps this crate from
        // needing to know either platform's notion of density at all.
        let window_uniform = {
            let size = window_size.into();
            WindowUniform {
                width: size.x,
                height: size.y,
            }
        };
        let window_buffer = device.create_buffer_init(&BufferInitDescriptor {
            label: Some("window"),
@@ -309,6 +404,14 @@ impl UiRenderNode {
        });
        let tex_manager = GpuTextures::new(device, queue);
        let primitives = PrimitiveBuffers::new(device);
        let primitive_group =
            Self::primitive_group(device, &primitive_layout, primitives.buffers());
        let instances = ArrBuf::new(
            device,
            BufferUsages::STORAGE | BufferUsages::COPY_DST,
            "ui instances",
        );
        let masks = ArrBuf::new(
            device,
            BufferUsages::STORAGE | BufferUsages::COPY_DST,
@@ -323,7 +426,8 @@ impl UiRenderNode {
        let rsc_layout = Self::rsc_layout(device);
        let rsc_group = Self::rsc_group(device, &rsc_layout, &tex_manager);
        let masks_layout = Self::masks_layout(device);
-        let masks_group = Self::masks_group(device, &masks_layout, &masks, &move_offsets);
+        let masks_group =
            Self::masks_group(device, &masks_layout, &masks, &move_offsets, &instances);
        let pipeline_layout = device.create_pipeline_layout(&PipelineLayoutDescriptor {
            label: Some("UI Shape Pipeline Layout"),
@@ -341,7 +445,7 @@ impl UiRenderNode {
            vertex: VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
-                buffers: &[PrimitiveInstance::desc()],
+                buffers: &[instance_slot_layout()],
                compilation_options: Default::default(),
            },
            fragment: Some(FragmentState {
@@ -373,9 +477,22 @@ impl UiRenderNode {
            cache: None,
        });
-        Self {
+        // Reverse of the push order above. Only one of these should ever be
        // `Some` in practice -- three separate scopes exist to name *which*
        // kind of error it was, not because more than one is expected at
        // once.
        let internal_err = internal_scope.pop().block_on();
        let validation_err = validation_scope.pop().block_on();
        let oom_err = oom_scope.pop().block_on();
        if let Some(err) = validation_err.or(oom_err).or(internal_err) {
            return Err(err.to_string());
        }
        Ok(Self {
            uniform_group,
            primitive_layout,
            primitives,
            primitive_group,
            rsc_layout,
            rsc_group,
            pipeline,
@@ -383,11 +500,12 @@ impl UiRenderNode {
            layers: HashMap::default(),
            active: Vec::new(),
            textures: tex_manager,
            instances,
            masks,
            move_offsets,
            masks_layout,
            masks_group,
-        }
+        })
    }
    fn bind_group_0(
@@ -517,6 +635,16 @@ impl UiRenderNode {
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 2,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Buffer {
                        ty: BufferBindingType::Storage { read_only: true },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
            ],
            label: Some("ui masks"),
        })
@@ -527,6 +655,7 @@ impl UiRenderNode {
        layout: &BindGroupLayout,
        masks: &ArrBuf<Mask>,
        move_offsets: &ArrBuf<MoveOffset>,
        instances: &ArrBuf<PrimitiveInstance>,
    ) -> BindGroup {
        device.create_bind_group(&BindGroupDescriptor {
            layout,
@@ -539,6 +668,10 @@ impl UiRenderNode {
                    binding: 1,
                    resource: move_offsets.buffer.as_entire_binding(),
                },
                BindGroupEntry {
                    binding: 2,
                    resource: instances.buffer.as_entire_binding(),
                },
            ],
            label: Some("ui masks"),
        })
@@ -554,4 +687,26 @@ impl UiRenderNode {
    pub fn take_image_bind_group_creates(&mut self) -> u64 {
        self.textures.take_bind_group_creates()
    }
    /// Atlas-array `grow_array` calls since the last call -- same calling
    /// convention as `take_image_bind_group_creates` (call once per frame,
    /// before `update()`, to read exactly the previous frame's tally). Part
    /// of the Diagnostics page's per-frame report (RUST.md's P0 box, "the
    /// first input frame" investigation): if a report ever shows a grow
    /// landing on the same frame the glyphs vanished, that is the
    /// coincidence to chase first.
    pub fn take_atlas_pages_grown(&mut self) -> u64 {
        self.textures.take_pages_grown()
    }
 }
 /// What `UiRenderNode::update` changed this frame that a caller building a
 /// per-frame diagnostic report cares about -- see `take_image_bind_group_creates`/
 /// `take_atlas_pages_grown` for the two counters this doesn't carry (they
 /// use the existing "call before update()" convention instead, so as not
 /// to disturb `bench_images`' documented counts).
 #[derive(Clone, Copy, Debug, Default)]
 pub struct FrameUpdateStats {
    pub masks_resized: bool,
    pub moves_resized: bool,
 }
@@ -6,50 +6,16 @@ use crate::{
        ArrBuf,
        data::{MaskIdx, MoveIdx, PrimitiveInstance},
    },
    util::HashSet,
 };
 use bytemuck::Pod;
 use wgpu::*;
 pub struct Primitives {
    instances: Vec<PrimitiveInstance>,
    assoc: Vec<WidgetId>,
    data: PrimitiveData,
    free: Vec<usize>,
    /// Standalone images, kept apart from `instances` because each one draws
    /// with its own bind group rather than sharing the layer's one instanced
    /// draw -- see TEXTURES.md's "Recommended shape". `idx` on each
    /// `PrimitiveInstance` here is the texture's slot in `Textures`/
    /// `GpuTextures`, not an index into `data`; there is no per-image entry
    /// in `data` because a bind group already picks the texture; nothing
    /// left to look up per-instance.
    images: Vec<PrimitiveInstance>,
    image_assoc: Vec<WidgetId>,
    image_free: Vec<usize>,
    pub updated: bool,
 }
 impl Default for Primitives {
    fn default() -> Self {
        Self {
            instances: Default::default(),
            assoc: Default::default(),
            data: Default::default(),
            free: Vec::new(),
            images: Default::default(),
            image_assoc: Default::default(),
            image_free: Vec::new(),
            updated: true,
        }
    }
 }
 /// The `binding` tag `Painter` writes on an image instance. Distinct from any
 /// `Primitive::BINDING` because images have no `PrimitiveData` entry to key
 /// one from -- a bind group already selects the texture -- so this only ever
-/// has to match the shader's `TEXTURE` constant and flag "this instance lives
+/// has to match the shader's `TEXTURE` constant and flag "this instance is
-/// in `Primitives::images`, not `Primitives::instances`" to the code below.
+/// drawn with its own bind group" to the code below.
 pub const IMAGE_BINDING: u32 = 1;
 pub trait Primitive: Pod {
@@ -133,18 +99,61 @@ macro_rules! primitives {
    (@count $t:tt) => { 1 };
 }
-pub struct PrimitiveInst<P> {
+/// Every primitive instance in the tree, in one arena that all layers
-    pub id: WidgetId,
+/// share, plus the per-primitive data (`rects`, `glyphs`) they index.
-    pub primitive: P,
+///
-    pub region: UiRegion,
+/// **Why one arena rather than one per layer**, which is what this was:
-    pub mask_idx: MaskIdx,
+/// the fragment stage evaluates a *mask's* primitive at the masked pixel
-    pub move_idx: MoveIdx,
+/// (LAYOUT.md's "Masks with a shape"), and the widget that owns a mask is
 /// routinely in a different layer from the content it clips -- a rounded
 /// container in one layer, a `Stack`'s child content in the layer below.
 /// A per-layer buffer cannot answer that lookup at all: only one layer's
 /// group is bound at a time, so the mask would silently read another
 /// layer's rect. Both buffers are therefore global and bound once per
 /// frame, and a layer keeps only its draw *order* ([`LayerOrder`]).
 ///
 /// Slots are stable for a primitive's whole life: nothing here is
 /// compacted, so a `Mask` can hold a slot across frames.
 pub struct Primitives {
    instances: Vec<PrimitiveInstance>,
    assoc: Vec<WidgetId>,
    /// Slots freed since the last [`Self::apply_free`]. Deliberately not
    /// reusable yet: the layer that drew one still names it in its draw
    /// order until that call compacts the order, so handing it out again
    /// first would draw the new primitive twice -- once through the stale
    /// order entry and once through the new one.
    freed: Vec<usize>,
    /// Slots [`Self::apply_free`] released, which is what [`Self::alloc`]
    /// hands out.
    reusable: Vec<usize>,
    data: PrimitiveData,
    /// Whether the instance arena or the per-primitive data changed since
    /// the last upload -- one flag for both, since they are uploaded
    /// together.
    pub updated: bool,
 }
 impl Default for Primitives {
    fn default() -> Self {
        Self {
            instances: Default::default(),
            assoc: Default::default(),
            freed: Vec::new(),
            reusable: Vec::new(),
            data: Default::default(),
            updated: true,
        }
    }
 }
 impl Primitives {
-    pub fn write<P: Primitive>(
+    /// Writes a primitive into the arena and hands back its slot and its
    /// entry in the per-primitive data. The caller (`UiRenderState`) puts
    /// the slot into a layer's draw order -- an instance that no layer
    /// names is never rasterized, which is what a mask shape drawn only to
    /// be *referenced* uses.
    pub fn alloc<P: Primitive>(
        &mut self,
        layer: usize,
        PrimitiveInst {
            id,
            primitive,
@@ -152,129 +161,118 @@ impl Primitives {
            mask_idx,
            move_idx,
        }: PrimitiveInst<P>,
-    ) -> PrimitiveHandle {
+    ) -> (u32, usize) {
-        self.updated = true;
+        let data_idx = P::vec(&mut self.data).add(primitive);
-        let vec = P::vec(&mut self.data);
+        let slot = self.push(
-        let i = vec.add(primitive);
+            PrimitiveInstance {
-        let inst = PrimitiveInstance {
+                region,
-            region,
+                idx: data_idx as u32,
-            idx: i as u32,
+                mask_idx,
-            mask_idx,
+                move_idx,
-            move_idx,
+                binding: P::BINDING,
-            binding: P::BINDING,
+            },
-        };
+            id,
-        let inst_i = if let Some(i) = self.free.pop() {
+        );
-            self.instances[i] = inst;
+        (slot, data_idx)
            self.assoc[i] = id;
            i
        } else {
            let i = self.instances.len();
            self.instances.push(inst);
            self.assoc.push(id);
            i
        };
        PrimitiveHandle::new::<P>(layer, inst_i, i)
    }
-    /// Writes an image instance directly -- there is no `Primitive` impl for
+    /// A standalone image, which has no `PrimitiveData` entry to allocate
-    /// it to go through `write`, since it has nowhere in `PrimitiveData` to
+    /// -- its bind group already picks the texture, so `texture_idx` rides
-    /// put a per-instance entry. `texture_idx` is the slot the bind group at
+    /// in the otherwise-unused `idx` field and names the bind group the
-    /// draw time is chosen from, carried in the otherwise-unused `idx` field.
+    /// draw call selects.
-    pub fn write_image(
+    pub fn alloc_image(
        &mut self,
        layer: usize,
        id: WidgetId,
        texture_idx: u32,
        region: UiRegion,
        mask_idx: MaskIdx,
        move_idx: MoveIdx,
-    ) -> PrimitiveHandle {
+    ) -> u32 {
        self.push(
            PrimitiveInstance {
                region,
                idx: texture_idx,
                mask_idx,
                move_idx,
                binding: IMAGE_BINDING,
            },
            id,
        )
    }
    fn push(&mut self, inst: PrimitiveInstance, id: WidgetId) -> u32 {
        self.updated = true;
-        let inst = PrimitiveInstance {
+        let slot = if let Some(i) = self.reusable.pop() {
-            region,
+            self.instances[i] = inst;
-            idx: texture_idx,
+            self.assoc[i] = id;
            mask_idx,
            move_idx,
            binding: IMAGE_BINDING,
        };
        let inst_i = if let Some(i) = self.image_free.pop() {
            self.images[i] = inst;
            self.image_assoc[i] = id;
            i
        } else {
-            let i = self.images.len();
+            self.instances.push(inst);
-            self.images.push(inst);
+            self.assoc.push(id);
-            self.image_assoc.push(id);
+            self.instances.len() - 1
            i
        };
-        PrimitiveHandle {
+        slot as u32
            layer,
            inst_idx: inst_i,
            data_idx: 0,
            binding: IMAGE_BINDING,
        }
    }
    pub fn image_instances(&self) -> &Vec<PrimitiveInstance> {
        &self.images
    }
    /// returns (old index, new index) for both lists this layer keeps --
    /// `PrimitiveChange::is_image` says which, since the two have separate
    /// index spaces and `old`/`new` alone would collide between them.
    ///
    /// Both lists free with `swap_remove`, so a layer's draw order was
    /// already undefined before images existed: nothing here may assume one
    /// primitive stays adjacent to another once anything in the layer has
    /// been freed.
    pub fn apply_free(&mut self) -> Vec<PrimitiveChange> {
        let mut changes =
            Self::apply_free_list(&mut self.free, &mut self.instances, &mut self.assoc, false);
        changes.extend(Self::apply_free_list(
            &mut self.image_free,
            &mut self.images,
            &mut self.image_assoc,
            true,
        ));
        changes
    }
    fn apply_free_list(
        free: &mut Vec<usize>,
        instances: &mut Vec<PrimitiveInstance>,
        assoc: &mut Vec<WidgetId>,
        is_image: bool,
    ) -> Vec<PrimitiveChange> {
        free.sort_by(|a, b| b.cmp(a));
        free.drain(..)
            .filter_map(|i| {
                instances.swap_remove(i);
                assoc.swap_remove(i);
                if i == instances.len() {
                    return None;
                }
                let id = assoc[i];
                let old = instances.len();
                Some(PrimitiveChange {
                    id,
                    is_image,
                    old,
                    new: i,
                })
            })
            .collect()
    }
    /// Retires a slot, answering the mask it was drawn under so the caller
    /// can drop that mask's ref. The slot itself only becomes reusable at
    /// the next [`Self::apply_free`] -- see `freed`.
    pub fn free(&mut self, h: &PrimitiveHandle) -> MaskIdx {
        self.updated = true;
-        if h.binding == IMAGE_BINDING {
+        let slot = h.slot as usize;
-            self.image_free.push(h.inst_idx);
+        if h.binding != IMAGE_BINDING {
            self.images[h.inst_idx].mask_idx
        } else {
            self.data.free(h.binding, h.data_idx);
            self.free.push(h.inst_idx);
            self.instances[h.inst_idx].mask_idx
        }
        self.freed.push(slot);
        self.instances[slot].mask_idx
    }
    /// Hands this frame's freed slots back for reuse. Called once per
    /// frame from `UiRenderState::update`, **after** every layer has
    /// compacted its draw order, since that order is the only thing still
    /// naming them.
    pub fn release_freed(&mut self) {
        self.reusable.append(&mut self.freed);
    }
    /// Which widget drew the primitive in `slot` -- how a draw-order
    /// change finds the handle it has to renumber.
    pub fn owner(&self, slot: u32) -> WidgetId {
        self.assoc[slot as usize]
    }
    pub fn clear(&mut self) {
        self.updated = true;
        self.instances.clear();
        self.assoc.clear();
        self.freed.clear();
        self.reusable.clear();
        self.data.clear();
    }
    /// How many instances are still live -- the O(1) half of the orphan
    /// check, so the O(primitives) walk below only runs on a frame that
    /// already looks wrong. See
    /// [`crate::UiRenderState::orphaned_primitives`].
    pub fn live_count(&self) -> usize {
        self.instances.len() - self.freed.len() - self.reusable.len()
    }
    /// Every live instance as `(slot, owner, is_image)` -- everything
    /// except the freed and the reusable. Only
    /// [`crate::UiRenderState::orphaned_primitives`] uses this, to check
    /// that every live primitive still belongs to a live widget.
    pub fn live_instances(&self) -> impl Iterator<Item = (u32, WidgetId, bool)> + '_ {
        let dead: HashSet<usize> = self.freed.iter().chain(&self.reusable).copied().collect();
        (0..self.instances.len())
            .filter(move |i| !dead.contains(i))
            .map(|i| {
                (
                    i as u32,
                    self.assoc[i],
                    self.instances[i].binding == IMAGE_BINDING,
                )
            })
    }
    pub fn data(&self) -> &PrimitiveData {
@@ -285,46 +283,141 @@ impl Primitives {
        &self.instances
    }
    pub fn instance(&self, slot: u32) -> &PrimitiveInstance {
        &self.instances[slot as usize]
    }
    pub fn region_mut(&mut self, h: &PrimitiveHandle) -> &mut UiRegion {
        self.updated = true;
-        if h.binding == IMAGE_BINDING {
+        &mut self.instances[h.slot as usize].region
            &mut self.images[h.inst_idx].region
        } else {
            &mut self.instances[h.inst_idx].region
        }
    }
 }
-pub struct PrimitiveChange {
+/// One layer's draw order: the slots of the global arena it draws, in the
-    pub id: WidgetId,
+/// order they were written. The vertex buffer of a layer is exactly this.
-    /// Which of `Primitives::instances`/`Primitives::images` this change
+///
-    /// belongs to -- their `old`/`new` indices are independent, so a
+/// Both lists free with `swap_remove`, so a layer's draw order was already
-    /// consumer matching only on `(layer, inst_idx)` could apply an image's
+/// undefined before this split: nothing here may assume one primitive
-    /// renumbering to a rect's handle that happens to share the same index.
+/// stays adjacent to another once anything in the layer has been freed.
-    pub is_image: bool,
+#[derive(Default)]
-    pub old: usize,
+pub struct LayerOrder {
-    pub new: usize,
+    order: Vec<u32>,
    /// Standalone images, kept apart because each draws with its own bind
    /// group rather than sharing the layer's one instanced draw -- see
    /// `UiRenderNode::draw`.
    images: Vec<u32>,
    free: Vec<usize>,
    image_free: Vec<usize>,
    pub updated: bool,
 }
 impl LayerOrder {
    pub fn push(&mut self, slot: u32, is_image: bool) -> usize {
        self.updated = true;
        let list = if is_image {
            &mut self.images
        } else {
            &mut self.order
        };
        list.push(slot);
        list.len() - 1
    }
    /// Marks a position for removal. Deferred to [`Self::apply_free`] like
    /// the arena's own, so that a position is only renumbered once per
    /// frame however many were dropped.
    pub fn free(&mut self, pos: usize, is_image: bool) {
        self.updated = true;
        if is_image {
            self.image_free.push(pos);
        } else {
            self.free.push(pos);
        }
    }
    /// Compacts both lists, answering every primitive whose position
    /// moved so its handle can be corrected.
    pub fn apply_free(&mut self) -> Vec<OrderChange> {
        let mut changes = Self::apply_free_list(&mut self.free, &mut self.order, false);
        changes.extend(Self::apply_free_list(
            &mut self.image_free,
            &mut self.images,
            true,
        ));
        changes
    }
    fn apply_free_list(
        free: &mut Vec<usize>,
        list: &mut Vec<u32>,
        is_image: bool,
    ) -> Vec<OrderChange> {
        // Descending, so removing a contiguous tail costs no renumbering
        // at all -- which is what freeing one widget's primitives is.
        free.sort_by(|a, b| b.cmp(a));
        free.drain(..)
            .filter_map(|pos| {
                list.swap_remove(pos);
                if pos == list.len() {
                    return None;
                }
                Some(OrderChange {
                    slot: list[pos],
                    is_image,
                    pos,
                })
            })
            .collect()
    }
    pub fn order(&self) -> &Vec<u32> {
        &self.order
    }
    pub fn images(&self) -> &Vec<u32> {
        &self.images
    }
 }
 /// A primitive whose position in a layer's draw order moved when
 /// something before it was freed -- `slot` names which primitive, so its
 /// owner's handle can be found and pointed at `pos`.
 pub struct OrderChange {
    pub slot: u32,
    /// Which of the layer's two lists moved: their positions are
    /// independent index spaces, so a handle matching on position alone
    /// could take an image's renumbering for a rect's.
    pub is_image: bool,
    pub pos: usize,
 }
 /// Where one primitive lives: its stable slot in the global arena, and
 /// where in a layer's draw order it currently sits. A handle with no
 /// layer position (`pos == NOT_DRAWN`) is a primitive that exists to be
 /// *referenced* -- a mask's shape -- and is never rasterized.
 #[derive(Debug)]
 pub struct PrimitiveHandle {
    pub layer: usize,
-    pub inst_idx: usize,
+    pub pos: usize,
    pub slot: u32,
    pub data_idx: usize,
    pub binding: u32,
 }
 impl PrimitiveHandle {
-    fn new<P: Primitive>(layer: usize, inst_idx: usize, data_idx: usize) -> Self {
+    pub fn is_image(&self) -> bool {
-        Self {
+        self.binding == IMAGE_BINDING
            layer,
            inst_idx,
            data_idx,
            binding: P::BINDING,
        }
    }
 }
 pub struct PrimitiveInst<P> {
    pub id: WidgetId,
    pub primitive: P,
    pub region: UiRegion,
    pub mask_idx: MaskIdx,
    pub move_idx: MoveIdx,
 }
 primitives!(
    rects: RectPrimitive => 0,
    glyphs: GlyphPrimitive => 2,
@@ -34,6 +34,10 @@ struct Mask {
    x: UiSpan,
    y: UiSpan,
    move_idx: u32,
    /// The mask this one is nested inside, or `4294967295u`. Mirrors
    /// `Mask::parent` in data.rs; walked below with the same bound the
    /// move chain uses.
    parent: u32,
 }
 /// One widget's cumulative on-screen translation and the slot of the
@@ -79,12 +83,25 @@ var samp: sampler;
 var<storage> masks: array<Mask>;
@group(3) @binding(1)
 var<storage> move_offsets: array<MoveOffset>;
 // Every primitive's placement, in one arena all layers share. The vertex
 // stage reads the primitive it is drawing (its slot arrives as the only
 // vertex attribute); the fragment stage reads a *mask's* primitive, which
 // is generally a different one in a different layer. See LAYOUT.md's
 // "Masks with a shape" and `Primitives` in primitive.rs.
@group(3) @binding(2)
 var<storage> instances: array<PrimitiveInstance>;
-// A move chain more than this deep means something else is wrong (an
+// The bound on the parent walk, kept in step with `PARENT_CHAIN_LIMIT` in
-// accidental cycle) -- kept in step with `MOVE_CHAIN_LIMIT` in
+// render_state.rs, which walks the identical chain on the CPU side for
-// render_state.rs, which walks the identical bound on the CPU side for
+// hit-testing. Bounded so a malformed chain (a cyclic `parent`) cannot
-// hit-testing. Bounded so a malformed chain cannot hang the GPU.
+// hang the GPU -- not a claim about how deep a real tree gets. It was 16
-const MOVE_CHAIN_LIMIT: u32 = 16u;
+// and that was too small: the transcript screen's composer field sits 17
 // slots below the root, measured 2026-09-07 on this checkout's emulator
 // by tapping it (the CPU walk's own debug assert names the chain now).
 // Past the bound both walks simply stop summing, so the widget draws and
 // hit-tests short by whatever the outer slots held, with nothing on
 // screen to say so.
 const PARENT_CHAIN_LIMIT: u32 = 64u;
 /// Sums the pixel delta along the parent chain starting at `idx`, shared by
 /// the vertex stage (a primitive's own corners) and the fragment stage (its
@@ -92,7 +109,7 @@ const MOVE_CHAIN_LIMIT: u32 = 16u;
 fn resolve_move(idx: u32) -> vec2<f32> {
    var total = vec2<f32>(0.0, 0.0);
    var i = idx;
-    for (var step = 0u; step < MOVE_CHAIN_LIMIT; step++) {
+    for (var step = 0u; step < PARENT_CHAIN_LIMIT; step++) {
        let entry = move_offsets[i];
        total += entry.delta;
        if entry.parent == 4294967295u {
@@ -107,15 +124,20 @@ struct WindowUniform {
    dim: vec2<f32>,
 };
 /// Mirrors `PrimitiveInstance` in data.rs -- the placement and what to
 /// draw there. `x`/`y` are the `UiRegion`'s two spans.
 struct PrimitiveInstance {
    x: UiSpan,
    y: UiSpan,
    binding: u32,
    idx: u32,
    mask_idx: u32,
    move_idx: u32,
 }
 /// A layer's draw order: one slot into `instances` per instance drawn.
 struct InstanceInput {
-    @location(0) x_start: vec2<f32>,
+    @location(0) slot: u32,
    @location(1) x_end: vec2<f32>,
    @location(2) y_start: vec2<f32>,
    @location(3) y_end: vec2<f32>,
    @location(4) binding: u32,
    @location(5) idx: u32,
    @location(6) mask_idx: u32,
    @location(7) move_idx: u32,
 }
 struct VertexOutput {
@@ -141,13 +163,14 @@ fn vs_main(
    in: InstanceInput,
 ) -> VertexOutput {
    var out: VertexOutput;
    let inst = instances[in.slot];
-    let top_left_rel = vec2(in.x_start.x, in.y_start.x);
+    let top_left_rel = vec2(inst.x.start.rel, inst.y.start.rel);
-    let top_left_abs = vec2(in.x_start.y, in.y_start.y);
+    let top_left_abs = vec2(inst.x.start.abs, inst.y.start.abs);
-    let bot_right_rel = vec2(in.x_end.x, in.y_end.x);
+    let bot_right_rel = vec2(inst.x.end.rel, inst.y.end.rel);
-    let bot_right_abs = vec2(in.x_end.y, in.y_end.y);
+    let bot_right_abs = vec2(inst.x.end.abs, inst.y.end.abs);
-    let move_delta = resolve_move(in.move_idx);
+    let move_delta = resolve_move(inst.move_idx);
    let top_left = floor(top_left_rel * window.dim) + floor(top_left_abs) + move_delta;
    let bot_right = floor(bot_right_rel * window.dim) + floor(bot_right_abs) + move_delta;
    let size = bot_right - top_left;
@@ -159,11 +182,11 @@ fn vs_main(
    let pos = (top_left + uv * size) / window.dim * 2.0 - 1.0;
    out.clip_position = vec4<f32>(pos.x, -pos.y, 0.0, 1.0);
    out.uv = uv;
-    out.binding = in.binding;
+    out.binding = inst.binding;
-    out.idx = in.idx;
+    out.idx = inst.idx;
    out.top_left = top_left;
    out.bot_right = bot_right;
-    out.mask_idx = in.mask_idx;
+    out.mask_idx = inst.mask_idx;
    return out;
 }
@@ -190,8 +213,15 @@ fn fs_main(
            color = vec4(1.0, 0.0, 1.0, 1.0);
        }
    }
-    if in.mask_idx != 4294967295u {
+    // Every mask on the chain, not just the innermost: a widget that set
-        let mask = masks[in.mask_idx];
+    // its own mask inside another is clipped by both, and each carries its
    // own move slot (`Mask::parent` in data.rs).
    var mask_idx = in.mask_idx;
    for (var step = 0u; step < PARENT_CHAIN_LIMIT; step++) {
        if mask_idx == 4294967295u {
            break;
        }
        let mask = masks[mask_idx];
        let mask_delta = resolve_move(mask.move_idx);
        let tl = UiVec2(vec2(mask.x.start.rel, mask.y.start.rel), vec2(mask.x.start.abs, mask.y.start.abs));
        let br = UiVec2(vec2(mask.x.end.rel, mask.y.end.rel), vec2(mask.x.end.abs, mask.y.end.abs));
@@ -201,6 +231,7 @@ fn fs_main(
        if pos.x < top_left.x || pos.x > bot_right.x || pos.y < top_left.y || pos.y > bot_right.y {
            color *= 0.0;
        }
        mask_idx = mask.parent;
    }
    return color;
 }
@@ -5,6 +5,10 @@ use crate::{PatchRect, TextureKind, TextureUpdate, Textures};
 use super::atlas::PAGE;
 /// The fewest layers the glyph atlas array is ever created with. Two, not
 /// one, for the GLES reason written on `create_array_texture`.
 const MIN_ARRAY_LAYERS: u32 = 2;
 /// What one texture slot is, GPU-side. Parallel to `Textures`' own slot
 /// numbering (`TextureKind`'s `Image`/`Page`), so a slot's index means the
 /// same thing on both sides without a second map to keep in sync.
@@ -67,6 +71,12 @@ pub struct GpuTextures {
    /// unchanging image list is zero, the same way `UiRenderState`'s
    /// `draw_count`/`region_mut_count` prove the layout side.
    bind_group_creates: u64,
    /// `grow_array` calls since the last `take_pages_grown` -- the
    /// Diagnostics page's per-frame report (RUST.md's P0 box, "the first
    /// input frame" investigation) reads this alongside `bind_group_creates`
    /// to say whether *this* frame's glyph disappearance, if any, coincided
    /// with the atlas array being recreated.
    pages_grown: u64,
 }
 impl GpuTextures {
@@ -226,6 +236,7 @@ impl GpuTextures {
    /// array's view, which invalidates every bind group that referenced it,
    /// so this also rebuilds all of them before returning.
    fn grow_array(&mut self, rsc_layout: &BindGroupLayout) {
        self.pages_grown += 1;
        let new_capacity = self.array_capacity * 2;
        let new_texture = Self::create_array_texture(&self.device, new_capacity);
        if self.page_count > 0 {
@@ -353,7 +364,26 @@ impl GpuTextures {
        })
    }
    /// The atlas is sampled as a `texture_2d_array`, and **a one-layer
    /// array is not one on the GLES backend**: wgpu-hal picks the GL
    /// texture target from the descriptor alone
    /// (`gles::Texture::get_info_from_desc`, `(false, 1) => TEXTURE_2D`),
    /// so a capacity of 1 creates a `GL_TEXTURE_2D` and binds it to the
    /// shader's `sampler2DArray`. GL then treats that unit as incomplete
    /// and every `textureSample` returns (0, 0, 0, 1) -- which, through
    /// `draw_glyph`'s `color.a *= texel.a`, draws every glyph as a solid
    /// filled box. That was iris's appearance on the emulator's GLES for
    /// two days (RUST.md, "the emulator cannot draw iris's glyphs"), and
    /// it is a real defect on any device whose adapter is GL rather than
    /// Vulkan, not an emulator artifact. So the array never has fewer than
    /// `MIN_ARRAY_LAYERS` layers; the second layer costs one page of
    /// texture memory and is used by the next atlas page anyway.
    fn create_array_texture(device: &Device, capacity: u32) -> Texture {
        debug_assert!(
            capacity >= MIN_ARRAY_LAYERS,
            "glyph atlas array asked for {capacity} layers; fewer than {MIN_ARRAY_LAYERS} is a \
             GL_TEXTURE_2D on the GLES backend and draws every glyph as a box"
        );
        device.create_texture(&TextureDescriptor {
            label: Some("glyph atlas array"),
            size: Extent3d {
@@ -375,7 +405,7 @@ impl GpuTextures {
    pub fn new(device: &Device, queue: &Queue) -> Self {
        let sampler = default_sampler(device);
        let null_view = null_texture_view(device);
-        let array_capacity = 1;
+        let array_capacity = MIN_ARRAY_LAYERS;
        let array_texture = Self::create_array_texture(device, array_capacity);
        let array_view = array_texture.create_view(&TextureViewDescriptor {
            dimension: Some(TextureViewDimension::D2Array),
@@ -392,6 +422,7 @@ impl GpuTextures {
            sampler,
            null_view,
            bind_group_creates: 0,
            pages_grown: 0,
        }
    }
@@ -402,6 +433,12 @@ impl GpuTextures {
        std::mem::take(&mut self.bind_group_creates)
    }
    /// Reads and zeroes the atlas-array-grow counter -- see `pages_grown`'s
    /// field comment.
    pub fn take_pages_grown(&mut self) -> u64 {
        std::mem::take(&mut self.pages_grown)
    }
    pub fn array_view(&self) -> &TextureView {
        &self.array_view
    }
@@ -1,4 +1,6 @@
-use crate::{LayerId, MaskIdx, MoveIdx, PrimitiveHandle, Size, TextureHandle, UiRegion, WidgetId};
+use crate::{
    LayerId, MaskIdx, MoveIdx, PrimitiveHandle, Size, TextureHandle, UiRegion, WidgetId, util::Vec2,
 };
 /// important non rendering data for retained drawing
 #[derive(Debug)]
@@ -9,7 +11,22 @@ pub struct ActiveData {
    pub textures: Vec<TextureHandle>,
    pub primitives: Vec<PrimitiveHandle>,
    pub children: Vec<WidgetId>,
    /// The mask this widget was drawn **under** (its parent's), not the
    /// one it set for itself -- see `own_mask` for that.
    pub mask: MaskIdx,
    /// The mask slot this widget allocated for *itself* with
    /// `Painter::set_mask`, or `MaskIdx::NONE`. Kept across redraws and
    /// rewritten in place, the way `move_slot` is: a `Masked` that pushed
    /// a fresh slot each draw left every already-drawn descendant --
    /// which `draw_inner`'s unchanged-region fast path does not revisit --
    /// clipping to the *old* slot's region, so a composer whose bar had
    /// since been placed at the bottom of the screen was still being
    /// clipped to a box at the top of it and drew nothing (measured
    /// 2026-09-06: four mask entries live, none of them the widget's
    /// current region). Its path out is the `undraw` branch of
    /// `UiRenderState::remove`, which drops the self-ownership ref taken
    /// when the slot was allocated.
    pub own_mask: MaskIdx,
    pub layer: LayerId,
    /// What `Widget::draw` returned the last time this widget was actually
    /// drawn -- read by a parent placing this widget again without
@@ -21,4 +38,32 @@ pub struct ActiveData {
    /// so a retained child's `parent` link never goes stale). See
    /// LAYOUT.md section 2.
    pub move_slot: MoveIdx,
    /// How much of this widget's own `move_slot` delta is already folded
    /// into `region` above, in window pixels. The two mechanisms that
    /// write that slot disagree about this and cannot be told apart from
    /// the slot alone: `UiRenderState::mov` shifts `region` and the delta
    /// together (the *offered* region genuinely moved), while
    /// `Painter::reposition` writes only the delta (`region` stays the
    /// offered box and the delta says where inside it the content was
    /// placed). So anything that wants the widget's real position --
    /// `resolved_region`, and through it every hit test -- must subtract
    /// this from the chain sum. Without it a panned widget's own hit box
    /// sits at twice the pan while its descendants' are correct, which is
    /// how it went unnoticed: the composer's field became untappable
    /// after a finger pan (2026-09-06). Reset to zero whenever the widget
    /// is really redrawn, since `draw_inner` zeroes the slot then too.
    pub move_applied: Vec2,
    /// The offset the last `Painter::reposition` placed this widget's
    /// content at *within* `region`, in window pixels. The move slot has
    /// exactly one owner and one meaning:
    /// `move_offsets[move_slot] == move_applied + repositioned`. `mov`
    /// adds to the first, `reposition` overwrites the second (it
    /// recomputes `from` afresh every call, so repeating it must land on
    /// the same answer rather than drifting), and both then rewrite the
    /// slot from the sum -- which is what lets a parent both move a child
    /// with its own layout and place it inside that moved region in one
    /// frame. `List::place`'s Bottom-known branch does exactly that once a
    /// row's blocks wrap. Reset to zero on a real redraw, with
    /// `move_applied` and the slot itself.
    pub repositioned: Vec2,
 }
@@ -24,6 +24,46 @@ pub struct UiData {
    /// id (never reallocated), so a retained descendant's `parent` index
    /// never goes stale -- see LAYOUT.md section 2.
    pub move_offsets: TrackedArena<MoveOffset, u32>,
    /// Every widget whose [`crate::Widget::tick`] should run before the
    /// next frame -- today, a `List` coasting through a fling. Added by
    /// [`Self::animate`] when the animation starts and removed by
    /// [`Self::tick_animations`] the frame its `tick` answers `false`, so
    /// a stopped animation costs nothing and a dropped widget cannot be
    /// ticked (`get_dyn_mut` answers `None` and it is dropped the same
    /// way).
    animating: Vec<WidgetId>,
 }
 impl UiData {
    /// Ask for `id`'s [`crate::Widget::tick`] to run every frame until it
    /// says it is done. Idempotent -- registering an already-animating
    /// widget is the ordinary case (a second fling before the first
    /// settled) and must not tick it twice per frame.
    pub fn animate(&mut self, id: WidgetId) {
        if !self.animating.contains(&id) {
            self.animating.push(id);
        }
    }
    /// Tick every registered widget to `now`, drop the ones that finished,
    /// and say whether any is still going -- which is a backend's cue to
    /// ask for another frame. Called once per frame *before* the draw, so
    /// what the frame draws is this instant's position rather than the
    /// previous one's.
    pub fn tick_animations(&mut self, now: std::time::Instant) -> bool {
        // Taken out and put back rather than iterated in place: `tick`
        // needs `&mut` on the widget arena this list lives beside, and a
        // widget is free to register another one while ticking.
        let mut registered = std::mem::take(&mut self.animating);
        registered.retain(|&id| match self.widgets.get_dyn_mut(id) {
            Some(widget) => widget.tick(now),
            None => false,
        });
        for id in registered {
            self.animate(id);
        }
        !self.animating.is_empty()
    }
 }
 pub trait UiRsc {
@@ -13,6 +13,10 @@ pub struct Painter<'a> {
    pub(super) region: UiRegion,
    pub(super) mask: MaskIdx,
    pub(super) move_slot: MoveIdx,
    /// This widget's own mask slot, reused across redraws -- see
    /// `ActiveData::own_mask`. `MaskIdx::NONE` until `set_mask` is called
    /// for the first time in this widget's life.
    pub(super) own_mask: MaskIdx,
    pub(super) textures: Vec<TextureHandle>,
    pub(super) primitives: Vec<PrimitiveHandle>,
    pub(super) children: Vec<WidgetId>,
@@ -22,7 +26,7 @@ pub struct Painter<'a> {
 impl<'a> Painter<'a> {
    fn primitive_at<P: Primitive>(&mut self, primitive: P, region: UiRegion) {
-        let h = self.state.layers.write(
+        let h = self.state.write_primitive(
            self.layer,
            PrimitiveInst {
                id: self.id,
@@ -48,12 +52,85 @@ impl<'a> Painter<'a> {
        self.primitive_at(primitive, region.within(&self.region));
    }
    /// Clip everything this widget draws, itself and its descendants, to
    /// `region`. One call per widget; a widget drawn inside another
    /// widget's mask nests instead -- the new mask chains to the inherited
    /// one (`Mask::parent`) and the fragment stage requires a pixel to be
    /// inside both, which is what lets a transcript row's code fence clip
    /// to itself *and* to the list it scrolls inside.
    ///
    /// The slot is allocated once and **rewritten in place** on every
    /// later draw rather than pushed again, because a descendant whose own
    /// region did not change is not redrawn (`draw_inner`'s fast path) and
    /// so keeps pointing at whichever slot it was drawn under. See
    /// `ActiveData::own_mask` for what pushing a fresh one cost.
    pub fn set_mask(&mut self, region: UiRegion) {
-        assert!(self.mask == MaskIdx::NONE);
+        // `assert!`, not `debug_assert!`: one comparison per widget draw,
-        self.mask = self.rsc.ui_mut().masks.push(Mask {
+        // and the second call silently *replacing* the first is a widget
        // drawn unclipped -- which reaches the screen and nothing says so.
        // Every build anybody runs here is release
        // (docs/REVIEW-2026-09-07.md's R1).
        assert!(
            self.own_mask == MaskIdx::NONE || self.mask != self.own_mask,
            "set_mask called twice while drawing one widget: the second would replace the first \
             rather than nest inside it",
        );
        let parent = self.mask;
        let mask = Mask {
            region,
            move_idx: self.move_slot,
-        });
+            parent,
        };
        let old_parent = if self.own_mask == MaskIdx::NONE {
            let slot = self.rsc.ui_mut().masks.push(mask);
            // The one ref this widget holds on its own slot, so the slot
            // outlives any single frame's primitives; released in
            // `UiRenderState::remove`'s `undraw` branch.
            self.rsc.ui_mut().masks.push_ref(slot);
            self.own_mask = slot;
            MaskIdx::NONE
        } else {
            let old = self.rsc.ui().masks[self.own_mask.idx()].parent;
            *self.rsc.ui_mut().masks.get_mut(self.own_mask) = mask;
            old
        };
        // The chain link's own ref, taken before the old one is dropped so
        // that re-chaining to the same slot cannot free it in between.
        // Released here when the link changes, and in
        // `UiRenderState::remove` when this widget's slot goes.
        if old_parent != parent {
            if parent != MaskIdx::NONE {
                self.rsc.ui_mut().masks.push_ref(parent);
            }
            if old_parent != MaskIdx::NONE {
                self.rsc.ui_mut().masks.remove(old_parent);
            }
        }
        self.mask = self.own_mask;
    }
    /// Ask for this widget to be drawn again on the next frame, from
    /// inside its own `draw` -- for a layout that can only discover a
    /// correction to itself by laying out once (`List::clamp_to_content`,
    /// which learns how far past its content the list is from the walk it
    /// has just done). The mark is the same one `Widgets::get_dyn_mut`
    /// sets, so `UiRenderState::update` picks it up exactly as it does any
    /// other dirty widget; it does **not** by itself ask the platform for
    /// a frame, which is the caller's own `RequestRedraw` handle.
    ///
    /// The correction it asks for must converge, or this is a widget that
    /// redraws forever.
    pub fn draw_again(&mut self) {
        self.rsc.widgets_mut().needs_redraw.insert(self.id);
    }
    /// Whether anything is clipping what this widget draws -- its own
    /// [`Self::set_mask`], or one an ancestor set that it inherited. What
    /// a widget whose contents may legitimately extend past its own box
    /// (`iris::widget::List`, which draws a row straddling an edge in
    /// full) asserts before relying on being cut off there.
    pub fn is_masked(&self) -> bool {
        self.mask != MaskIdx::NONE
    }
    /// Draws a widget within this widget's region, returning the size it
@@ -86,6 +163,7 @@ impl<'a> Painter<'a> {
            self.mask,
            None,
            None,
            crate::render::MaskIdx::NONE,
            self.rsc,
        );
        self.state
@@ -145,7 +223,7 @@ impl<'a> Painter<'a> {
    /// the layer's one instanced draw, so it goes through
    /// `Primitives::write_image` instead of `primitive_at`/`Primitive::vec`.
    fn write_image(&mut self, texture_idx: u32, region: UiRegion) {
-        let h = self.state.layers.write_image(
+        let h = self.state.write_image(
            self.layer,
            self.id,
            texture_idx,
@@ -165,8 +243,21 @@ impl<'a> Painter<'a> {
        attrs: &TextAttrs,
        width: Option<f32>,
    ) -> RenderedText {
        let density = self.state.density;
        // Counted here rather than in `TextView::render`, which returns
        // its memoized layout without reaching this -- so this counts
        // shapes, not requests. `UiRenderState::take_counters`.
        self.state.shape_count += 1;
        let ui = self.rsc.ui_mut();
-        ui.text.render(buffer, attrs, width, &mut ui.textures)
+        ui.text
            .render(buffer, attrs, width, &mut ui.textures, density)
    }
    /// Which glyph atlas the glyphs handed out right now belong to --
    /// what a widget caching a [`RenderedText`] across frames has to
    /// compare against before re-emitting it (`GlyphAtlas::clear`).
    pub fn atlas_generation(&mut self) -> u64 {
        self.rsc.ui_mut().text.atlas.generation()
    }
    /// Draw a laid-out string: one quad per glyph, all sampling the atlas.
@@ -175,6 +266,20 @@ impl<'a> Painter<'a> {
    /// absolute pixel offset from it, so re-drawing after a resize is this loop
    /// and nothing else.
    pub fn glyphs(&mut self, text: &RenderedText, origin: UiRegion) {
        // A caller re-emitting quads placed against an atlas that has since
        // been cleared draws every glyph from coordinates now holding
        // something else. Caught at the submission rather than on screen,
        // where it reads as fragments of unrelated letters. `assert_eq!`
        // for R1's reason: two integers per laid-out string, not per
        // glyph, and the failure is unreadable text on a release build.
        assert_eq!(
            text.generation,
            self.atlas_generation(),
            "glyphs placed against atlas generation {} submitted against {}: the holder did not \
             re-render after the atlas was cleared",
            text.generation,
            self.atlas_generation(),
        );
        let flags_for = |is_color| {
            if is_color {
                GlyphPrimitive::IS_COLOR
@@ -210,6 +315,12 @@ impl<'a> Painter<'a> {
        self.state.output_size
    }
    /// Physical pixels per `dp` -- see `UiRenderState::density`'s field
    /// doc. What `Len::dp`'s `apply_rest` call resolves against.
    pub fn density(&self) -> f32 {
        self.state.density
    }
    pub fn px_size(&mut self) -> Vec2 {
        self.region.size().to_abs(self.state.output_size)
    }
@@ -1,19 +1,74 @@
 use std::sync::Mutex;
 use std::time::{Duration, Instant};
 use crate::{
    ActiveData, IdLike, MaskIdx, MoveIdx, Painter, PixelRegion, PrimitiveLayers, RegionAlign,
    StrongWidget, UiRegion, UiRsc, UiVec2, WidgetId, Widgets,
-    render::MoveOffset,
+    render::{MoveOffset, Primitive, PrimitiveHandle, PrimitiveInst, Primitives},
    util::{HashMap, HashSet, Id, Vec2},
 };
 /// What [`UiRenderState::update`] did on its last call -- read back by the
 /// `iris::frame` diagnostic (`iris::diagnostics::log_frame` in the `iris`
 /// crate) so a report can tell a full relayout from a frame that only
 /// redrew a handful of dirty widgets from one that drew nothing at all.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RedrawKind {
    /// Neither the root nor any widget changed -- `update` did nothing.
    None,
    /// [`UiRenderState::redraw_all`]: a new root, or a resize.
    All,
    /// [`UiRenderState::redraw_updates`]: only the widgets `needs_redraw`
    /// named.
    Updates,
 }
 pub struct UiRenderState {
    pub active: HashMap<WidgetId, ActiveData>,
    /// Every primitive in the tree, in one arena -- see [`Primitives`] for
    /// why it is not per layer.
    pub primitives: Primitives,
    /// What each layer draws, in order: slots into `primitives`.
    pub layers: PrimitiveLayers,
    pub(super) output_size: Vec2,
    /// Physical pixels per `dp` -- see `Len::dp`'s field doc. `1.0` (an
    /// unscaled display) until a backend that knows its own density calls
    /// `set_density` (Android's `content_scale`, read at `surface_changed`
    /// time); the winit backend has no analogous per-monitor value wired up
    /// yet and stays at the default.
    pub(super) density: f32,
    old_root: Option<WidgetId>,
    resized: bool,
    /// The widgets whose `Widget::draw` is on the stack right now -- so
    /// [`Self::redraw`] can tell "this widget needs drawing again" from
    /// "an ancestor is drawing it at this very moment", where a second
    /// draw would leave the first one's primitives behind with nothing
    /// owning them. An id is inserted immediately before `draw` is called
    /// and removed the moment it returns (both in `draw_inner`), so this
    /// is empty between frames -- asserted at the end of `update`.
    ///
    /// It used to only ever be inserted into, and `redraw` removed the id
    /// *before* testing for it, which made the test constant `false`: the
    /// guard could never fire and the set grew by one entry per widget
    /// ever drawn and was never emptied.
    draw_started: HashSet<WidgetId>,
    /// The widget currently holding exclusive pointer input, if any --
    /// `iris::sense::SensorUi::run_sensors` reads and clears this every
    /// call. Interior mutability (a `Mutex`, not a bare `Cell`, since a
    /// `CursorData` reaching this through an async `task_on` handler needs
    /// `Send`/`Sync`) because `run_sensors` takes `&self` (widgets are
    /// dispatched to, not owned, at that layer) and this render state is
    /// the one structure both backends (winit, android-view) already hold
    /// across frames, the same way `old_root`/`resized` are -- see
    /// `iris::sense`'s pointer-capture doc for why a drag needs this: once
    /// a gesture has committed to panning or selecting, every later sample
    /// of it must reach the same widget even if the finger has moved off
    /// whatever hit region first noticed the press. Never held across an
    /// await or another lock -- every access here is a single get/set.
    captured: std::sync::Mutex<Option<WidgetId>>,
    /// `Widget::draw` calls and `Primitives::region_mut` rewrites since the
    /// last `take_counters`. LAYOUT.md section 8's pass conditions are
    /// stated in terms of these two: an unchanged frame must cost 0 of
@@ -22,44 +77,187 @@ pub struct UiRenderState {
    draw_count: u64,
    region_mut_count: u64,
    mov_count: u64,
    /// Text layouts actually computed -- bumped by `Painter::render_text`,
    /// which `TextView::render` only reaches on a cache miss.
    pub(super) shape_count: u64,
    /// `Instant::now()` at construction -- the zero every `iris::frame` line
    /// dates itself from, so a report's `now=` is comparable to a harness's
    /// own `t_ms` (`Harness::new` builds its `base` the same way, in the
    /// same constructor call) without either side needing the wall clock.
    epoch: Instant,
    /// How many times [`Self::update`] has run -- the `iris::frame` line's
    /// frame number. Counts every call, including one that found nothing to
    /// redraw, so a gap in the sequence in a report is a frame this state
    /// was never asked to run at all (a stalled event loop), not one that
    /// ran and did nothing.
    frame_no: u64,
    /// How long the redraw phase of the last [`Self::update`] took --
    /// [`Self::redraw_all`] or [`Self::redraw_updates`], whichever ran, or
    /// zero if neither did. Read back by `iris::diagnostics::log_frame`.
    last_layout: Duration,
    last_redraw_kind: RedrawKind,
    /// When the sensor dispatch (`SensorUi::run_sensors`, in the `iris`
    /// crate) last saw an input sample, dated by the sample's own clock
    /// (`CursorState::time`) rather than when the dispatch ran -- same
    /// reasoning as that field's own doc. A `Mutex` rather than a
    /// `Cell` for the same reason `captured` is: `run_sensors` takes `&self`
    /// and this is the one render state both backends already share across
    /// frames.
    last_input_at: Mutex<Option<Instant>>,
 }
-/// A move chain more than this deep would mean something else is wrong
+/// The bound on the parent walk -- see `resolve_move` in shader.wgsl,
-/// (an accidental cycle) -- see `resolve_move` in shader.wgsl, which walks
+/// which walks the identical chain and must be kept in step with this
-/// the identical bound and must be kept in step with this constant.
+/// constant. It exists so a cyclic `parent` link cannot hang either walk,
-pub const MOVE_CHAIN_LIMIT: usize = 16;
+/// not as a statement about how deep a real tree gets: it was 16, and the
 /// transcript screen's composer field turned out to sit **17** slots below
 /// the root (measured 2026-09-07 on this checkout's emulator, by tapping
 /// the composer in a debug build -- the assert in `resolve_move_chain`
 /// prints the chain). A chain past the bound is not reported anywhere at
 /// run time; both walks just stop summing, so the widget is drawn and hit
 /// tested short by whatever the outer slots held.
 ///
 /// Named for the walk rather than for one of its two subjects: it bounds
 /// the move-offset chain *and* the mask chain (`Mask::parent`, walked in
 /// the fragment stage), and `MOVE_CHAIN_LIMIT` said only the first
 /// (docs/REVIEW-2026-09-07.md).
 pub const PARENT_CHAIN_LIMIT: usize = 64;
 impl UiRenderState {
    pub fn new() -> Self {
        Self {
            active: Default::default(),
            primitives: Default::default(),
            layers: Default::default(),
            output_size: Vec2::ZERO,
            density: 1.0,
            old_root: None,
            resized: false,
            draw_started: Default::default(),
            captured: Default::default(),
            draw_count: 0,
            region_mut_count: 0,
            mov_count: 0,
            shape_count: 0,
            epoch: Instant::now(),
            frame_no: 0,
            last_layout: Duration::ZERO,
            last_redraw_kind: RedrawKind::None,
            last_input_at: Mutex::new(None),
        }
    }
    /// Reads and zeroes the (draws, region_mut rewrites, move_offsets
-    /// writes) counters -- call once per frame before `update()` to
+    /// writes, text shapes) counters -- call once per frame before
-    /// measure exactly that frame, per LAYOUT.md section 8.
+    /// `update()` to measure exactly that frame, per LAYOUT.md section 8.
-    pub fn take_counters(&mut self) -> (u64, u64, u64) {
+    ///
    /// The fourth is the one a draw count cannot stand in for: a widget
    /// can be redrawn without re-shaping (`TextView::render` memoizes by
    /// width) and re-shaped without any extra draw, and it is re-shaping
    /// that the per-block transcript row exists to avoid -- see
    /// `transcript_ui`'s `a_delta_into_a_long_reply_shapes_one_block`.
    pub fn take_counters(&mut self) -> (u64, u64, u64, u64) {
        (
            std::mem::take(&mut self.draw_count),
            std::mem::take(&mut self.region_mut_count),
            std::mem::take(&mut self.mov_count),
            std::mem::take(&mut self.shape_count),
        )
    }
    /// Writes a primitive into the arena and into `layer`'s draw order.
    pub(super) fn write_primitive<P: Primitive>(
        &mut self,
        layer: usize,
        inst: PrimitiveInst<P>,
    ) -> PrimitiveHandle {
        let (slot, data_idx) = self.primitives.alloc(inst);
        let pos = self.layers[layer].push(slot, false);
        PrimitiveHandle {
            layer,
            pos,
            slot,
            data_idx,
            binding: P::BINDING,
        }
    }
    /// A standalone image, which draws with its own bind group rather
    /// than sharing the layer's one instanced draw.
    pub(super) fn write_image(
        &mut self,
        layer: usize,
        id: WidgetId,
        texture_idx: u32,
        region: UiRegion,
        mask_idx: MaskIdx,
        move_idx: MoveIdx,
    ) -> PrimitiveHandle {
        let slot = self
            .primitives
            .alloc_image(id, texture_idx, region, mask_idx, move_idx);
        let pos = self.layers[layer].push(slot, true);
        PrimitiveHandle {
            layer,
            pos,
            slot,
            data_idx: 0,
            binding: crate::render::IMAGE_BINDING,
        }
    }
    /// Compacts every layer's draw order around the primitives freed
    /// this frame, corrects the handles that moved, and only then hands
    /// the arena slots back for reuse -- that order is the whole reason
    /// `Primitives::freed` exists. Once per frame, at the end of
    /// [`Self::update`], so the harness (which has no renderer) applies
    /// it exactly as a real backend does.
    fn apply_free(&mut self) {
        for (layer, order) in self.layers.iter_mut() {
            for change in order.apply_free() {
                let owner = self.primitives.owner(change.slot);
                if let Some(active) = self.active.get_mut(&owner) {
                    for h in &mut active.primitives {
                        if h.layer == layer && h.slot == change.slot {
                            h.pos = change.pos;
                            break;
                        }
                    }
                }
            }
        }
        self.primitives.release_freed();
    }
    pub fn resize(&mut self, size: impl Into<Vec2>) {
        self.output_size = size.into();
        self.resized = true;
    }
    /// Sets the physical-pixels-per-dp ratio every `Len::dp` in the tree
    /// resolves against from the next layout pass on -- see `density`'s
    /// field doc. Not folded into `resize` because the two change on
    /// different triggers (a surface resize on every rotation or keyboard
    /// open; a density change only if the app follows the display to a
    /// different screen, which Android surfaces separately).
    ///
    /// Marks the tree for a full redraw when the value actually changes:
    /// every `Len::dp` already resolved and every glyph already shaped
    /// (`Text::shape` keys its cache on `(attrs, width, density)`) belongs
    /// to the old one, and nothing else would ask for them again
    /// (docs/REVIEW-2026-09-07.md's R5).
    pub fn set_density(&mut self, density: f32) {
        if density != self.density {
            self.resized = true;
        }
        self.density = density;
    }
    pub fn density(&self) -> f32 {
        self.density
    }
    pub fn update<'a>(&mut self, root: impl Into<Option<&'a StrongWidget>>, rsc: &mut dyn UiRsc) {
        // safety mechanism for memory leaks; might wanna return a result instead so user can
        // decide whether to panic or not
@@ -78,15 +276,91 @@ impl UiRenderState {
            );
        }
        let root = root.into();
-        if self.needs_redraw_all(root) {
+        debug_assert!(
            self.draw_started.is_empty(),
            "a previous frame left {} widget(s) marked as mid-draw",
            self.draw_started.len(),
        );
        // Timed unconditionally -- an `Instant::now()` pair is cheap enough
        // not to move the `--phone` bench's frame time (checked when this
        // was added), and gating it behind the trace toggle would leave
        // `iris::frame` with nothing to report the one frame somebody just
        // turned tracing on to look at.
        let layout_start = Instant::now();
        let kind = if self.needs_redraw_all(root) {
            self.redraw_all(root, rsc);
            self.old_root = root.map(|r| r.id());
            self.resized = false;
            RedrawKind::All
        } else if rsc.widgets().has_updates() {
            self.redraw_updates(rsc);
            RedrawKind::Updates
        } else {
            RedrawKind::None
        };
        self.last_layout = layout_start.elapsed();
        self.last_redraw_kind = kind;
        self.frame_no += 1;
        // After the redraw and before anything reads the frame: every
        // slot freed above is still named by its layer's draw order until
        // this runs.
        self.apply_free();
        #[cfg(debug_assertions)]
        debug_assert!(self.primitive_counts_agree(), "{}", self.orphan_report(rsc),);
    }
    /// `Instant::now()` at construction -- see the field's own doc.
    pub fn epoch(&self) -> Instant {
        self.epoch
    }
    /// How many times [`Self::update`] has run, counting from 1.
    pub fn frame_number(&self) -> u64 {
        self.frame_no
    }
    /// How long the last [`Self::update`]'s redraw phase took.
    pub fn last_layout_duration(&self) -> Duration {
        self.last_layout
    }
    /// What the last [`Self::update`] did -- see [`RedrawKind`].
    pub fn last_redraw_kind(&self) -> RedrawKind {
        self.last_redraw_kind
    }
    /// Records that a real input sample was just dispatched, dated by the
    /// sample's own clock -- called once per sensor pass, so `iris::frame`'s
    /// `since_input` can answer "how stale was the input
    /// this frame drew" instead of a caller guessing from the frame
    /// interval. `&self` because `run_sensors` only ever has that -- see
    /// `last_input_at`'s field doc.
    pub fn note_input(&self, at: Instant) {
        if let Ok(mut guard) = self.last_input_at.lock() {
            *guard = Some(at);
        }
    }
    /// `now - ` the last input sample's own timestamp, or `None` if no
    /// input has ever reached this render state (a cold start, or a screen
    /// that only ever animates on its own). Saturates to zero rather than
    /// panicking if `now` is earlier than the input sample somehow was --
    /// a diagnostic reading wrong is not worth a crash over.
    pub fn time_since_input(&self, now: Instant) -> Option<Duration> {
        let at = *self.last_input_at.lock().ok()?;
        at.map(|at| now.saturating_duration_since(at))
    }
    /// Primitive instances every currently-active widget owns, summed --
    /// what `iris::frame`'s `primitives=` reports. Not a per-frame delta:
    /// `redraw_updates` only rewrites what changed, so this is "how much is
    /// on screen", which is what a report reads as "did this frame have
    /// more to draw than the last one", not "how much work did this frame
    /// do" (`take_counters` answers that).
    pub fn active_primitive_count(&self) -> usize {
        self.active.values().map(|a| a.primitives.len()).sum()
    }
    fn redraw_all(&mut self, root: Option<&StrongWidget>, rsc: &mut dyn UiRsc) {
        self.clear(rsc);
        // free all resources & cache
@@ -100,6 +374,7 @@ impl UiRenderState {
                MaskIdx::NONE,
                None,
                None,
                MaskIdx::NONE,
                rsc,
            );
        }
@@ -134,12 +409,27 @@ impl UiRenderState {
        mask: MaskIdx,
        old_children: Option<Vec<WidgetId>>,
        old_move_slot: Option<MoveIdx>,
        old_own_mask: MaskIdx,
        rsc: &mut dyn UiRsc,
    ) {
        let mut old_children = old_children.unwrap_or_default();
        let mut old_move_slot = old_move_slot;
        let mut own_mask = old_own_mask;
        // Consumed here, not merely read: this call *is* the redraw the mark
        // asked for, and leaving the mark set is what stranded a widget's
        // primitives. `Painter::draw_twice` calls this twice for the same id
        // in one frame (`List::place`'s measurement pass), and on the second
        // call the still-set mark took the whole `if let` below -- including
        // the `remove` that frees the first draw's primitives -- out of play,
        // so `active.insert` at the end overwrote the only handles that could
        // ever have freed them. The result is a full second copy of the row,
        // drawn every frame from then on at the oversized measurement region
        // and, with `List` setting no mask, outside the list's own bounds:
        // the doubled `Compacted:` row in docs/bench/iris-phone-v2-2026-09-06.md.
        // The same shape reaches any dirty widget an ancestor redraws first.
        let dirty = rsc.widgets_mut().needs_redraw.remove(&id);
        if let Some(active) = self.active.get_mut(&id)
-            && !rsc.widgets().needs_redraw.contains(&id)
+            && !dirty
        {
            // check to see if we can skip drawing first
            if active.region == region {
@@ -162,10 +452,19 @@ impl UiRenderState {
                // instead of redrawing. See LAYOUT.md section 3.
                let from = active.region;
                for h in &active.primitives {
-                    let r = self.layers[h.layer].region_mut(h);
+                    let r = self.primitives.region_mut(h);
                    *r = r.outside(&from).within(&region);
                    self.region_mut_count += 1;
                }
                // `move_applied` is deliberately **not** touched here,
                // unlike in `mov`: it counts the part of this widget's own
                // move-slot delta that `region` has already absorbed, and
                // this branch writes no delta at all -- the primitives were
                // moved directly. Counting one would make
                // `resolved_region` subtract a distance the chain never
                // held, putting the hit box short of the drawing by
                // exactly this step. See `ActiveData::move_applied`, and
                // `a_size_independent_widget_moved_by_its_parent_has_the_hit_box_it_is_drawn_at`.
                active.region = region;
                return;
            }
@@ -173,10 +472,25 @@ impl UiRenderState {
            let active = self.remove(id, false, rsc).unwrap();
            old_children = active.children;
            old_move_slot = Some(active.move_slot);
            own_mask = active.own_mask;
        } else if dirty && self.active.contains_key(&id) {
            // Dirty and already drawn: none of the fast paths above may be
            // taken (the widget's own content changed, so its old primitives
            // say nothing about its new ones), but they are also the only
            // thing that frees them. Same two lines, reached the other way.
            let active = self.remove(id, false, rsc).unwrap();
            old_children = active.children;
            old_move_slot = Some(active.move_slot);
            own_mask = active.own_mask;
        }
        // draw widget
-        self.draw_started.insert(id);
+        let reentrant = !self.draw_started.insert(id);
        debug_assert!(
            !reentrant,
            "widget {id:?} is being drawn while its own draw is already on the stack; \
             the second draw's primitives would orphan the first's"
        );
        let move_slot = match old_move_slot {
            // Reused across a real redraw of the same id: the fresh
@@ -205,11 +519,21 @@ impl UiRenderState {
            }
        };
        // The mask this widget was drawn *under*, kept aside because
        // `Painter::set_mask` overwrites `painter.mask` with the widget's
        // own new one -- and `ActiveData::mask`'s only consumer is
        // `redraw`, which feeds it back in as the *inherited* mask. Storing
        // the set one instead handed a `Masked` its own mask on every
        // targeted redraw -- an abort the first time the composer's scroll
        // area was redrawn on the emulator, and now (masks nest) a mask
        // whose parent is itself, which `set_mask`'s own assert names.
        let inherited_mask = mask;
        let mut painter = Painter {
            state: self,
            region,
            mask,
            move_slot,
            own_mask,
            layer,
            id,
            textures: Vec::new(),
@@ -221,14 +545,26 @@ impl UiRenderState {
        let mut widget = painter.rsc.widgets().get_dyn_dynamic(id);
        painter.state.draw_count += 1;
        let size = widget.draw(&mut painter);
        // A reported length is consumed by containers that read `abs`,
        // `rel` and `rest` straight off it (`Span`'s placement, `Pad`'s
        // addition), so an unresolved `dp` in one is silently worth zero
        // -- see `Len::fold_dp`, which is what a widget reporting a
        // caller-declared size has to put it through.
        debug_assert!(
            size.x.dp == 0.0 && size.y.dp == 0.0,
            "widget {id:?} reported an unresolved `dp` size ({size:?}); \
             report `Len::fold_dp(painter.density())` instead"
        );
        drop(widget);
        painter.state.draw_started.remove(&id);
        let Painter {
            state: _,
            rsc: _,
            region,
-            mask,
+            mask: _,
            move_slot,
            own_mask,
            textures,
            primitives,
            children,
@@ -244,10 +580,13 @@ impl UiRenderState {
            textures,
            primitives,
            children,
-            mask,
+            mask: inherited_mask,
            layer,
            size,
            move_slot,
            own_mask,
            move_applied: Vec2::ZERO,
            repositioned: Vec2::ZERO,
        };
        // remove old children that weren't kept
@@ -275,6 +614,7 @@ impl UiRenderState {
        let from_px = from.top_left().to_abs(self.output_size);
        let to_px = to.top_left().to_abs(self.output_size);
        let delta = to_px - from_px;
        active.move_applied += delta;
        let entry = rsc.ui_mut().move_offsets.get_mut(slot);
        entry.delta[0] += delta.x;
        entry.delta[1] += delta.y;
@@ -309,17 +649,38 @@ impl UiRenderState {
        let Some(active) = self.active.get(&id) else {
            return;
        };
        let move_applied = active.move_applied;
        let repositioned = active.repositioned;
        let from = active
            .size
-            .to_uivec2()
+            .to_uivec2(self.density)
            .align(RegionAlign::TOP_LEFT)
            .within(&active.region);
        let slot = active.move_slot;
        let from_px = from.top_left().to_abs(self.output_size);
        let to_px = to.top_left().to_abs(self.output_size);
        let delta = to_px - from_px;
        // Not `delta` alone: a parent may have `mov`ed this widget to a
        // region that itself moved earlier in the same frame, and that
        // part of the slot is `move_applied`'s, not this call's. Writing
        // `delta` on its own dropped it and put the content back at the
        // pre-move position. `from` is computed against `active.region`,
        // which `mov` already updated, so `delta` is purely the placement
        // inside the region and the two summands never overlap.
        let entry = rsc.ui_mut().move_offsets.get_mut(slot);
-        entry.delta = [delta.x, delta.y];
+        debug_assert_eq!(
            entry.delta,
            [
                move_applied.x + repositioned.x,
                move_applied.y + repositioned.y
            ],
            "widget {id:?}'s move slot was written by something other than `mov`/`reposition`; \
             the slot is theirs and means `move_applied + repositioned` -- see `ActiveData`"
        );
        entry.delta = [move_applied.x + delta.x, move_applied.y + delta.y];
        if let Some(active) = self.active.get_mut(&id) {
            active.repositioned = delta;
        }
        self.mov_count += 1;
    }
@@ -328,7 +689,8 @@ impl UiRenderState {
        let mut active = self.active.remove(&id);
        if let Some(active) = &mut active {
            for h in &active.primitives {
-                let mask = self.layers.free(h);
+                let mask = self.primitives.free(h);
                self.layers[h.layer].free(h.pos, h.is_image());
                if mask != MaskIdx::NONE {
                    rsc.ui_mut().masks.remove(mask);
                }
@@ -336,6 +698,13 @@ impl UiRenderState {
            active.textures.clear();
            rsc.ui_mut().textures.free();
            if undraw {
                // A captured widget that goes away mid-gesture (List's
                // virtualisation retiring a row, a rebuild) must not leave
                // the pointer permanently captured by an id nothing will
                // ever draw again -- `captured`'s own path out.
                if *self.captured.lock().unwrap() == Some(id) {
                    *self.captured.lock().unwrap() = None;
                }
                // Permanent removal: retire this widget's own move slot
                // (the self-ownership ref taken when it was allocated) and
                // the up-link ref it held on its parent's slot -- read from
@@ -343,6 +712,18 @@ impl UiRenderState {
                // the parent's own `ActiveData` may already be gone by the
                // time a deep descendant is retired (see LAYOUT.md
                // section 2's lifecycle note).
                if active.own_mask != MaskIdx::NONE {
                    // The self-ownership ref `Painter::set_mask` took when
                    // it allocated this widget's own mask slot, and the
                    // chain link's ref on the mask this one nests inside
                    // -- read from the arena entry, for the same reason
                    // the move slot's parent is.
                    let outer = rsc.ui().masks[active.own_mask.idx()].parent;
                    rsc.ui_mut().masks.remove(active.own_mask);
                    if outer != MaskIdx::NONE {
                        rsc.ui_mut().masks.remove(outer);
                    }
                }
                let parent_slot = rsc.ui_mut().move_offsets[active.move_slot.idx()].parent;
                rsc.ui_mut().move_offsets.remove(active.move_slot);
                if parent_slot != MoveOffset::NONE_PARENT {
@@ -369,6 +750,7 @@ impl UiRenderState {
            rsc.on_undraw(&active);
        }
        self.layers.clear();
        self.primitives.clear();
        rsc.widgets_mut().needs_redraw.clear();
        rsc.free();
    }
@@ -408,6 +790,96 @@ impl UiRenderState {
        self.active.len()
    }
    /// Primitive instances still bound for the GPU whose owner is no
    /// longer in `active`, or whose owner's `ActiveData` no longer names
    /// them: a copy nothing can move, clip, resize or free, redrawn every
    /// frame at whatever position it last had. `(slot, owner)` each --
    /// the arena knows which primitive, not which layer's draw order still
    /// names it.
    ///
    /// Asserted empty at the end of every [`Self::update`], because this
    /// is exactly the shape of the duplicated transcript row on Iris's
    /// phone (`docs/bench/iris-phone-v2-2026-09-06.md`): counting
    /// `active` alone cannot see it, since the orphan's owner is very
    /// much alive -- it is the *earlier* set of primitives that got
    /// stranded when the widget was drawn a second time without the first
    /// draw being freed. O(primitives), debug builds only.
    pub fn orphaned_primitives(&self) -> Vec<(u32, WidgetId)> {
        let mut orphans = Vec::new();
        for (slot, owner, _) in self.primitives.live_instances() {
            let owned = self
                .active
                .get(&owner)
                .is_some_and(|a| a.primitives.iter().any(|h| h.slot == slot));
            if !owned {
                orphans.push((slot, owner));
            }
        }
        orphans
    }
    /// Whether every primitive still bound for the GPU is owned by a live
    /// widget, decided by counting rather than by walking: an orphan is a
    /// live instance no `ActiveData` names, so it can only ever make the
    /// live count exceed the owned one. O(active widgets) -- a few dozen --
    /// against [`Self::orphaned_primitives`]'s O(primitives), which on a
    /// transcript is tens of thousands and made a debug build on a phone
    /// too slow to finish a benchmark run.
    fn primitive_counts_agree(&self) -> bool {
        let live: usize = self.primitives.live_count();
        let owned: usize = self.active.values().map(|a| a.primitives.len()).sum();
        live == owned
    }
    /// The message [`Self::update`]'s orphan assert prints -- built here
    /// rather than inline so the (allocating, O(primitives)) work only
    /// happens on the failing path.
    #[cfg(debug_assertions)]
    fn orphan_report(&self, rsc: &dyn UiRsc) -> String {
        let orphans = self.orphaned_primitives();
        let mut lines: Vec<String> = orphans
            .iter()
            .take(8)
            .map(|(slot, owner)| {
                let alive = self.active.contains_key(owner);
                format!(
                    "  instance {slot}: owner '{}' ({owner:?}), owner still active: {alive}",
                    rsc.widgets().label(*owner),
                )
            })
            .collect();
        if orphans.len() > lines.len() {
            lines.push(format!("  ... and {} more", orphans.len() - lines.len()));
        }
        format!(
            "{} primitive(s) are drawn but owned by nobody -- a stale copy \
             nothing will ever move or free:\n{}",
            orphans.len(),
            lines.join("\n"),
        )
    }
    /// Give `id` exclusive pointer input from the next `run_sensors` call
    /// on -- see `captured`'s field doc. Overwrites any previous capture
    /// (a gesture that starts a new one has already decided the old one
    /// is over).
    pub fn capture_pointer(&self, id: WidgetId) {
        *self.captured.lock().unwrap() = Some(id);
    }
    /// Release exclusive pointer input, if any is held -- called once
    /// `run_sensors` has delivered the terminal `Drop` to the capturing
    /// widget, or by that widget itself if it decides the gesture is over
    /// some other way.
    pub fn release_pointer(&self) {
        *self.captured.lock().unwrap() = None;
    }
    /// The widget currently holding exclusive pointer input, if any.
    pub fn captured_pointer(&self) -> Option<WidgetId> {
        *self.captured.lock().unwrap()
    }
    pub fn debug(&self, widgets: &Widgets, label: &str) -> impl Iterator<Item = &ActiveData> {
        self.active.iter().filter_map(move |(&id, inst)| {
            let l = widgets.label(id);
@@ -416,12 +888,12 @@ impl UiRenderState {
    }
    pub fn debug_layers(&self) {
-        for ((idx, depth), primitives) in self.layers.iter_depth() {
+        for ((idx, depth), order) in self.layers.iter_depth() {
            let indent = " ".repeat(depth * 2);
-            let len = primitives.instances().len();
+            let len = order.order().len();
            print!("{indent}{idx}: {len} primitives");
            if len >= 1 {
-                print!(" ({})", primitives.instances()[0].binding);
+                print!(" ({})", self.primitives.instance(order.order()[0]).binding);
            }
            println!();
        }
@@ -434,34 +906,70 @@ impl UiRenderState {
    /// section 2b.
    pub fn resolved_region(&self, id: &impl IdLike, rsc: &dyn UiRsc) -> Option<UiRegion> {
        let active = self.active.get(&id.id())?;
-        let delta = self.resolve_move_chain(active.move_slot, rsc);
+        // The chain sum is what the shader adds to this widget's
        // *primitives*, which were written before any of those moves.
        // `region`, unlike them, has already been shifted by whatever
        // part of this widget's own slot `mov` put there -- see
        // `ActiveData::move_applied`, which is exactly that part.
        let delta = self.resolve_move_chain(active.move_slot, rsc) - active.move_applied;
        Some(active.region.offset(UiVec2::abs(delta)))
    }
    /// The plain-Rust twin of `resolve_move` in shader.wgsl: sums the
    /// pixel delta along the parent chain starting at `slot`. Both walks
-    /// share `MOVE_CHAIN_LIMIT` as their bound so the two cannot disagree
+    /// share `PARENT_CHAIN_LIMIT` as their bound so the two cannot disagree
    /// about where the chain ends.
-    fn resolve_move_chain(&self, mut slot: MoveIdx, rsc: &dyn UiRsc) -> Vec2 {
+    fn resolve_move_chain(&self, slot: MoveIdx, rsc: &dyn UiRsc) -> Vec2 {
        let offsets = &rsc.ui().move_offsets;
        let mut delta = Vec2::ZERO;
-        for i in 0..MOVE_CHAIN_LIMIT {
+        let mut at = slot;
-            let entry = &offsets[slot.idx()];
+        for i in 0..PARENT_CHAIN_LIMIT {
            let entry = &offsets[at.idx()];
            delta.x += entry.delta[0];
            delta.y += entry.delta[1];
            if entry.parent == MoveOffset::NONE_PARENT {
                return delta;
            }
-            slot = Id::preset(entry.parent);
+            at = Id::preset(entry.parent);
            // The chain itself, not just the fact that it was too long: a
            // cycle and a tree genuinely nested deeper than the shader can
            // follow are different faults with different fixes, and the
            // slot numbers are the only thing that tells them apart.
            debug_assert!(
-                i + 1 < MOVE_CHAIN_LIMIT,
+                i + 1 < PARENT_CHAIN_LIMIT,
-                "move offset chain exceeded MOVE_CHAIN_LIMIT; a widget's `parent` link is \
+                "move offset chain exceeded PARENT_CHAIN_LIMIT ({PARENT_CHAIN_LIMIT}): {chain} \
-                 probably cyclic"
+                 -- a \
                 repeated slot means a `parent` link is cyclic, all-distinct slots mean the tree \
                 nests deeper than shader.wgsl's own walk of the same bound",
                chain = Self::move_chain_debug(slot, offsets)
            );
        }
        delta
    }
    /// The parent chain from `slot`, as `slot(dx, dy) -> ...`, walked twice
    /// `PARENT_CHAIN_LIMIT` so a cycle shows up as a repeated slot number
    /// rather than as a chain that merely stops. Only ever called from the
    /// failed assertion above.
    fn move_chain_debug(slot: MoveIdx, offsets: &[MoveOffset]) -> String {
        let mut parts = Vec::new();
        let mut at = slot;
        for _ in 0..PARENT_CHAIN_LIMIT * 2 {
            let entry = &offsets[at.idx()];
            parts.push(format!(
                "{}({}, {})",
                at.idx(),
                entry.delta[0],
                entry.delta[1]
            ));
            if entry.parent == MoveOffset::NONE_PARENT {
                break;
            }
            at = Id::preset(entry.parent);
        }
        parts.join(" -> ")
    }
    pub fn window_region(&self, id: &impl IdLike, rsc: &dyn UiRsc) -> Option<PixelRegion> {
        let region = self.resolved_region(id, rsc)?;
        Some(region.to_px(self.output_size))
@@ -470,7 +978,10 @@ impl UiRenderState {
    /// redraws a widget that's currently active (drawn)
    pub fn redraw(&mut self, id: WidgetId, rsc: &mut dyn UiRsc) {
        rsc.widgets_mut().needs_redraw.remove(&id);
-        self.draw_started.remove(&id);
+        // An ancestor is drawing this widget right now, and that draw is
        // about to write fresh primitives for it. Drawing it a second time
        // here would leave one of the two copies on screen with nothing
        // owning it -- see `draw_started`'s own doc.
        if self.draw_started.contains(&id) {
            return;
        }
@@ -494,9 +1005,9 @@ impl UiRenderState {
            active.mask,
            Some(active.children),
            Some(active.move_slot),
            active.own_mask,
            rsc,
        );
        // If this widget's own reported size changed, its parent's layout
        // (which placed it using the old size) is now stale and needs to
        // relay out too. Checked after the real draw, not before it --
@@ -41,6 +41,25 @@ pub trait Widget: Any {
    fn access_role(&self) -> accesskit::Role {
        accesskit::Role::Unknown
    }
    /// Advance whatever this widget is animating to `now`, and say whether
    /// it is still animating afterwards. Default: nothing is, so a widget
    /// opts in by overriding this *and* by something calling
    /// [`crate::UiData::animate`] with its id when the animation starts --
    /// which is that animation's path out, since the driver
    /// ([`crate::UiData::tick_animations`]) drops every id whose `tick`
    /// answers `false`.
    ///
    /// Called once per frame, before the frame's draw, by whichever
    /// backend owns the surface; a `true` answer is what makes that
    /// backend ask for another frame. So this is the only thing in iris
    /// that moves without an input event, and a widget that animates
    /// without registering simply never moves -- which is exactly how a
    /// finger fling looked on Iris's phone before this existed.
    #[allow(unused_variables)]
    fn tick(&mut self, now: std::time::Instant) -> bool {
        false
    }
 }
 impl Widget for () {
@@ -15,23 +15,19 @@
 //! +-----------+--------------------------------------+
 //! ```
 //!
-//! **Deliberately left simple, and why**: every incoming SSE event refolds
+//! **Incoming SSE events go through `TranscriptScreen::apply`**, not a
-//! the *entire* transcript (`client_core::transcript_fold::fold_event` is
+//! full rebuild: `client_core::transcript_fold::fold_event` folds the new
-//! already `O(items)` and a desktop session's conversation is small) and
+//! item list as before, then `apply` updates only the row(s) that actually
-//! rebuilds the whole right-hand widget tree from scratch, rather than
+//! changed (almost always the one still-open assistant message a delta
-//! reaching for `TranscriptScreen::push_row`'s incremental append.
+//! landed in) instead of rebuilding the whole right-hand widget tree from
-//! `push_row` cannot update a row already on screen -- only append a new
+//! scratch. `rebuild_transcript` still runs the whole tree once, for a
-//! one -- and a streaming assistant reply is exactly a row whose *text*
+//! freshly loaded/selected session and for `apply`'s own rare
-//! keeps changing after it first appears (see `transcript-ui`'s own doc on
+//! full-rebuild fallback (a `group_tool_runs` regroup touching a row
-//! `fold_event` folding deltas into one growing item). A full rebuild
+//! before the tail). The composer's in-progress text survives a rebuild
-//! shows that growth correctly at the cost of redrawing everything each
+//! (`rebuild_transcript`'s `in_progress` local) since the user typing a
-//! time; fine for this proof, wrong for a long, fast-streaming transcript
+//! followup while a reply streams in is the one case a naive rebuild
-//! -- the incremental path that fixes it needs `transcript-ui` to expose
+//! would otherwise lose data on -- `apply`'s own path never touches the
-//! updating a row in place, which it does not yet. The composer's
+//! composer at all, so this only matters on the fallback.
 //! in-progress text survives a rebuild (`rebuild_transcript`'s
 //! `in_progress` local) since the user typing a followup while a reply
 //! streams in is the one case a naive rebuild would otherwise lose data
 //! on.
 //!
 //! Background network I/O (`client_core::api`/`event_stream`, both
 //! blocking by design -- see `client-core`'s `Cargo.toml`) runs on plain
@@ -209,8 +205,12 @@ impl DefaultAppState for Client {
                event,
            } => {
                if self.current(&session_id, generation) {
                    let old_items = self.items.clone();
                    self.items = fold_event(&self.items, &event);
-                    self.rebuild_transcript(rsc);
+                    match &self.screen {
                        Some(screen) => screen.apply(rsc, &old_items, &self.items),
                        None => self.rebuild_transcript(rsc),
                    }
                }
            }
            AppEvent::StreamEnded {
@@ -1,19 +1,13 @@
-//! Where the desktop app keeps the enrollment it should not have to be
+//! Where the desktop app keeps its enrollment: `client_core::config`'s
-//! told about a second time: `client_core::config::EnrolledServer`,
+//! [`EnrollmentStore`] pointed at `$XDG_CONFIG_HOME/ai-app-desktop`.
 //! persisted at `$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json`,
 //! owner-only (0600) -- MACHINE.md's rule for anything holding a bearer
 //! token, and the reason `client_core::config`'s own doc comment leaves
 //! persistence and file mode to the caller.
 //!
-//! JSON rather than the project's usual RON: `wg-app-link`'s RON house
+//! Only the directory is this app's -- the file's name, its JSON, and its
-//! rules (`format`) are for configs a person hand-edits, and this file
+//! owner-only mode (MACHINE.md's rule for anything holding a bearer token)
-//! never is one -- only this program ever writes or reads it, and
+//! are the store's, shared with the Android client so the two cannot come
-//! `serde_json` is already in the dependency graph through `client-core`,
+//! to disagree about them.
 //! so nothing new is added to reach for it.
-use client_core::config::EnrolledServer;
+use client_core::config::EnrollmentStore;
-use std::io;
+use std::path::PathBuf;
 use std::path::{Path, PathBuf};
 /// `$XDG_CONFIG_HOME/ai-app-desktop`, falling back to `~/.config` the way
 /// the XDG basedir spec says to when the variable is unset -- the same
@@ -32,103 +26,6 @@ pub fn config_dir() -> PathBuf {
    base.join("ai-app-desktop")
 }
-fn enrollment_file(dir: &Path) -> PathBuf {
+pub fn store() -> EnrollmentStore {
-    dir.join("enrollment.json")
+    EnrollmentStore::new(config_dir())
 }
 /// Persists `server` under `dir` (`config_dir()` for real use; a tempdir in
 /// the tests below), creating it if needed, and sets the file owner-only --
 /// it carries a bearer token, the same reason `server/`'s own token store
 /// is 0600.
 pub fn save_enrollment_in(dir: &Path, server: &EnrolledServer) -> io::Result<()> {
    std::fs::create_dir_all(dir)?;
    let path = enrollment_file(dir);
    let json = serde_json::to_vec_pretty(server)
        .expect("EnrolledServer holds nothing that fails to serialise");
    std::fs::write(&path, json)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))?;
    }
    Ok(())
 }
 /// `Ok(None)` when nothing has been enrolled yet, rather than an error --
 /// "not enrolled" is an ordinary first-run state, not a failure (UI_RULES'
 /// "a deliberate choice is not a problem to report" applies just as well
 /// to a file that simply hasn't been written yet).
 pub fn load_enrollment_in(dir: &Path) -> io::Result<Option<EnrolledServer>> {
    let path = enrollment_file(dir);
    match std::fs::read(&path) {
        Ok(bytes) => {
            let server = serde_json::from_slice(&bytes).map_err(|e| {
                io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!("{} is not a valid enrollment ({e})", path.display()),
                )
            })?;
            Ok(Some(server))
        }
        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(None),
        Err(e) => Err(e),
    }
 }
 pub fn save_enrollment(server: &EnrolledServer) -> io::Result<()> {
    save_enrollment_in(&config_dir(), server)
 }
 pub fn load_enrollment() -> io::Result<Option<EnrolledServer>> {
    load_enrollment_in(&config_dir())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn a_saved_enrollment_reads_back_the_same() {
        let dir = tempfile::tempdir().unwrap();
        let server = EnrolledServer {
            host: "127.0.0.1".to_string(),
            port: 8547,
            token: "tok".to_string(),
        };
        save_enrollment_in(dir.path(), &server).unwrap();
        let read_back = load_enrollment_in(dir.path()).unwrap();
        assert_eq!(read_back, Some(server));
    }
    #[test]
    fn nothing_saved_yet_is_none_not_an_error() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(load_enrollment_in(dir.path()).unwrap(), None);
    }
    #[test]
    #[cfg(unix)]
    fn the_saved_file_is_owner_only() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let server = EnrolledServer {
            host: "h".to_string(),
            port: 1,
            token: "t".to_string(),
        };
        save_enrollment_in(dir.path(), &server).unwrap();
        let mode = std::fs::metadata(enrollment_file(dir.path()))
            .unwrap()
            .permissions()
            .mode();
        assert_eq!(mode & 0o777, 0o600);
    }
    #[test]
    fn a_corrupt_file_is_named_in_the_error() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(enrollment_file(dir.path()), b"not json").unwrap();
        let err = load_enrollment_in(dir.path()).unwrap_err();
        assert!(err.to_string().contains("enrollment.json"));
    }
 }
@@ -5,18 +5,20 @@
 //!
 //! Usage:
 //!
-//!     desktop-app --ca /path/to/ca.pem --link 'aiapp://enroll?host=H&port=P&token=T'
+//!     desktop-app --link 'aiapp://enroll?host=H&port=P&token=T&ca=B'
-//!     desktop-app --ca /path/to/ca.pem   # after the first run above
+//!     desktop-app                        # after the first run above
 //!     desktop-app --ca /path/to/ca.pem   # a link that carries no CA
 //!
 //! `--link` is the same text `app/ui-sandbox.sh`'s banner prints and a
 //! phone would scan as a QR (DECISIONS.md, 2026-09-05) -- pasted rather
 //! than scanned, since a desktop has no camera to assume. It is parsed and
-//! saved to `config::save_enrollment` once; later runs read it back and
+//! saved once; later runs read it back and `--link` is only needed again
-//! `--link` is only needed again to enrol against a different server. The
+//! to enrol against a different server.
-//! CA is never persisted -- it is a public certificate whose path a
+//!
-//! caller is expected to already know (`AGENTS.md`'s "prefer exercising
+//! The CA comes with the link (`wg_app_link::enroll::ca_param`, which
-//! the server directly": the same `certs/ca.pem` a `curl --cacert` call
+//! `ai-server` now always includes) and is saved with it. `--ca` is the
-//! uses).
+//! override for a link that carries none, and names the same
 //! `certs/ca.pem` a `curl --cacert` call uses.
 mod app;
 mod config;
@@ -24,7 +26,7 @@ mod config;
 use client_core::config::EnrolledServer;
 struct Args {
-    ca_path: std::path::PathBuf,
+    ca_path: Option<std::path::PathBuf>,
    link: Option<String>,
 }
@@ -43,13 +45,7 @@ fn parse_args() -> Result<Args, String> {
            other => return Err(format!("unrecognised argument '{other}'")),
        }
    }
-    Ok(Args {
+    Ok(Args { ca_path, link })
        ca_path: ca_path.ok_or(
            "--ca PATH is required (the pinned CA's certificate, e.g. \
                    ~/.config/ai-app/certs/ca.pem)",
        )?,
        link,
    })
 }
 /// What `app.rs`'s `Client::new` needs to talk to the server: the enrolled
@@ -60,14 +56,17 @@ fn parse_args() -> Result<Args, String> {
 /// other way (`DefaultApp::run()` takes no payload).
 fn load_startup_config() -> Result<(EnrolledServer, Vec<u8>), String> {
    let args = parse_args()?;
    let store = config::store();
    let server = match args.link {
        Some(link) => {
            let server = EnrolledServer::parse_link(&link)?;
-            config::save_enrollment(&server)
+            store
                .save(&server)
                .map_err(|e| format!("couldn't save the enrollment: {e}"))?;
            server
        }
-        None => config::load_enrollment()
+        None => store
            .load()
            .map_err(|e| format!("couldn't read the saved enrollment: {e}"))?
            .ok_or_else(|| {
                format!(
@@ -77,8 +76,20 @@ fn load_startup_config() -> Result<(EnrolledServer, Vec<u8>), String> {
                )
            })?,
    };
-    let ca_pem = std::fs::read(&args.ca_path)
+    // `--ca` wins where it was given, so a caller can point a link's
-        .map_err(|e| format!("couldn't read the CA at {}: {e}", args.ca_path.display()))?;
+    // server at a certificate it did not carry -- and so the flag still
    // means what it did before the link could carry one.
    let ca_pem = match (&args.ca_path, &server.ca_pem) {
        (Some(path), _) => std::fs::read(path)
            .map_err(|e| format!("couldn't read the CA at {}: {e}", path.display()))?,
        (None, Some(pem)) => pem.clone().into_bytes(),
        (None, None) => {
            return Err("this enrollment carries no CA -- pass --ca PATH (e.g. \
                 ~/.config/ai-app/certs/ca.pem), or enrol again with a link \
                 minted by a server that includes one"
                .to_string());
        }
    };
    Ok((server, ca_pem))
 }
@@ -68,12 +68,15 @@ fn build_row<Rsc: UiRsc + 'static>(rsc: &mut Rsc, i: usize) -> StrongWidget {
        let mut span = Span::empty(Dir::DOWN);
        span.push(text);
        span.push(img);
-        span.pad(8.0).background(rect(tint)).add_strong(rsc).any()
+        span.pad(dp(8.0))
            .background(rect(tint))
            .add_strong(rsc)
            .any()
    } else {
        wtext(row_text(i))
            .wrap(true)
            .color(text_color)
-            .pad(8.0)
+            .pad(dp(8.0))
            .background(rect(tint))
            .add_strong(rsc)
            .any()
@@ -0,0 +1,32 @@
 [package]
 name = "rig-input"
 version.workspace = true
 edition.workspace = true
 # Layer 2's input half (docs/RUST.md's "Three test layers"): replays one
 # of the `.touch` files the headless tests use into whatever window is
 # under a Wayland compositor, so the *same recording* drives the
 # assertion layer and the layer a person looks at.
 #
 # It exists because this machine's compositor has no pointer to move.
 # `run-headless.sh` starts sway on the headless backend with no input
 # devices at all (`WLR_LIBINPUT_NO_DEVICES=1`, `LIBSEAT_BACKEND=noop`),
 # so `swaymsg seat - cursor press` reports success and nothing reaches
 # the client -- `swaymsg -t get_seats` shows `capabilities: 0`. wlroots
 # 0.19 dropped `WLR_HEADLESS_INPUTS`, and ydotool's uinput device would
 # be ignored by a compositor that is not reading libinput. The
 # virtual-pointer protocol is what is left, and it is a client protocol,
 # so it needs no devices and no root.
 # Named for what it does rather than for the crate, since the crate may
 # grow a keyboard replay beside it.
 [[bin]]
 name = "replay-touch"
 path = "src/main.rs"
 [dependencies]
 # `TouchScript` -- the same parser the harness uses, so a file that
 # replays here and one that replays headless can never disagree.
 iris = { path = ".." }
 wayland-client = "0.31.15"
 wayland-protocols-wlr = { version = "0.3.12", features = ["client"] }
@@ -0,0 +1,164 @@
 //! Replays a `.touch` file into the compositor as a left-button drag --
 //! see this crate's `Cargo.toml` for why it exists rather than
 //! `swaymsg seat - cursor`.
 //!
 //!     WAYLAND_DISPLAY=… replay-touch WIDTH HEIGHT FILE
 //!
 //! `WIDTH`/`HEIGHT` are the output's own size, because the virtual
 //! pointer protocol positions absolutely against an extent rather than
 //! in pixels; passing the output size makes a script's coordinates mean
 //! the same pixels they mean in the headless tests.
 //!
 //! Replayed in real time (the sleeps between samples are the gaps in the
 //! file), because winit has no timestamp on a pointer event and dates
 //! each one when it arrives -- so a 20ms flick has to actually take
 //! 20ms here, unlike layer 1 where the sample carries its own time.
 use iris::harness::{TouchAction, TouchScript};
 use std::time::Duration;
 use wayland_client::protocol::wl_pointer::ButtonState;
 use wayland_client::protocol::{wl_registry, wl_seat};
 use wayland_client::{Connection, Dispatch, QueueHandle, delegate_noop};
 use wayland_protocols_wlr::virtual_pointer::v1::client::{
    zwlr_virtual_pointer_manager_v1::ZwlrVirtualPointerManagerV1,
    zwlr_virtual_pointer_v1::ZwlrVirtualPointerV1,
 };
 /// `linux/input-event-codes.h`. The protocol takes the kernel's own
 /// button code, not a wayland enum.
 const BTN_LEFT: u32 = 0x110;
 /// How long the pointer sits at the gesture's first position before the
 /// script starts -- see the comment at the pre-step in `main`.
 const SETTLE: Duration = Duration::from_millis(200);
 #[derive(Default)]
 struct Globals {
    seat: Option<wl_seat::WlSeat>,
    manager: Option<ZwlrVirtualPointerManagerV1>,
 }
 impl Dispatch<wl_registry::WlRegistry, ()> for Globals {
    fn event(
        state: &mut Self,
        registry: &wl_registry::WlRegistry,
        event: wl_registry::Event,
        _: &(),
        _: &Connection,
        qh: &QueueHandle<Self>,
    ) {
        let wl_registry::Event::Global {
            name,
            interface,
            version,
        } = event
        else {
            return;
        };
        match interface.as_str() {
            "wl_seat" => {
                state.seat = Some(registry.bind(name, version.min(7), qh, ()));
            }
            "zwlr_virtual_pointer_manager_v1" => {
                state.manager = Some(registry.bind(name, version.min(2), qh, ()));
            }
            _ => {}
        }
    }
 }
 delegate_noop!(Globals: ignore wl_seat::WlSeat);
 delegate_noop!(Globals: ZwlrVirtualPointerManagerV1);
 delegate_noop!(Globals: ZwlrVirtualPointerV1);
 fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let [width, height, path] = args.as_slice() else {
        eprintln!("usage: replay-touch WIDTH HEIGHT FILE");
        std::process::exit(2);
    };
    let (width, height) = (parse(width, "WIDTH"), parse(height, "HEIGHT"));
    let text = std::fs::read_to_string(path)
        .unwrap_or_else(|e| fail(&format!("could not read {path}: {e}")));
    let script = TouchScript::parse(&text).unwrap_or_else(|e| fail(&e));
    let conn = Connection::connect_to_env().unwrap_or_else(|e| {
        fail(&format!(
            "no wayland display ({e}); is WAYLAND_DISPLAY set?"
        ))
    });
    let mut queue = conn.new_event_queue();
    let qh = queue.handle();
    let display = conn.display();
    display.get_registry(&qh, ());
    let mut globals = Globals::default();
    queue
        .roundtrip(&mut globals)
        .unwrap_or_else(|e| fail(&format!("wayland roundtrip failed: {e}")));
    let manager = globals.manager.as_ref().unwrap_or_else(|| {
        fail(
            "this compositor does not offer zwlr_virtual_pointer_manager_v1, so a pointer cannot \
             be synthesised; sway and every wlroots compositor do",
        )
    });
    let pointer = manager.create_virtual_pointer(globals.seat.as_ref(), &qh, ());
    // Put the pointer where the gesture starts and let the compositor
    // settle before anything is pressed. Without this the press is
    // dropped: sway has just learned about this pointer, and a button
    // sent in the same breath as the motion that first puts it over a
    // window arrives before there is a focused surface to send it to --
    // winit sees `CursorEntered`, the moves and the *release*, never the
    // press, so the gesture reads as a hover and nothing scrolls. Found
    // by printing winit's own events; the settle is what fixed it.
    if let Some(first) = script.samples.first() {
        pointer.motion_absolute(0, first.pos.x as u32, first.pos.y as u32, width, height);
        pointer.frame();
        conn.flush()
            .unwrap_or_else(|e| fail(&format!("flush: {e}")));
        std::thread::sleep(SETTLE);
    }
    let mut previous = 0;
    for sample in &script.samples {
        std::thread::sleep(Duration::from_millis(sample.t_ms - previous));
        previous = sample.t_ms;
        let t = sample.t_ms as u32;
        pointer.motion_absolute(t, sample.pos.x as u32, sample.pos.y as u32, width, height);
        // One frame per sample, so the compositor delivers them as
        // separate pointer frames rather than coalescing the whole
        // gesture -- the shape the file recorded is the point.
        pointer.frame();
        // The button goes in a frame of its own, *after* the motion has
        // been committed. Sent in the same frame as the motion that
        // first puts the pointer over the window, sway drops it: the
        // client sees `CursorEntered` and the moves but never a
        // `MouseInput { state: Pressed }`, so the whole gesture reads as
        // a hover and nothing scrolls. Found exactly that way, by
        // printing winit's events.
        let state = match sample.action {
            TouchAction::Down => Some(ButtonState::Pressed),
            TouchAction::Up | TouchAction::Cancel => Some(ButtonState::Released),
            TouchAction::Move => None,
        };
        if let Some(state) = state {
            pointer.button(t, BTN_LEFT, state);
            pointer.frame();
        }
        conn.flush()
            .unwrap_or_else(|e| fail(&format!("flush: {e}")));
    }
    pointer.destroy();
    conn.flush().ok();
 }
 fn parse(text: &str, what: &str) -> u32 {
    text.parse()
        .unwrap_or_else(|_| fail(&format!("{what} is not a whole number: {text:?}")))
 }
 fn fail(message: &str) -> ! {
    eprintln!("replay-touch: {message}");
    std::process::exit(1);
 }
@@ -3,6 +3,25 @@
 #
 #   ./run-headless.sh tabs [-- cargo args]
 #   ./run-headless.sh tabs --shot /tmp/tabs.png --seconds 4
 #   ./run-headless.sh phone --phone --shot /tmp/p.png -- -p transcript-fixture
 #   ./run-headless.sh phone --phone --replay transcript-fixture/touch/flick-120hz.touch \
 #       --shot /tmp/p.png -- -p transcript-fixture
 #
 # `--phone` is layer 2 of docs/RUST.md's "Three test layers": the output
 # and the window take Iris's phone's own size and density (1080x2424 at
 # `content_scale` 2.55, from docs/bench/iris-phone-v2-2026-09-06.md,
 # carried in `transcript_fixture::PHONE_*`), and `IRIS_SCALE` hands that
 # density to iris the way `DisplayMetrics.density` does on Android
 # (`iris::default::content_scale`). So a screenshot from here and one
 # from the phone are the same layout at the same density, and what
 # differs is only the renderer. Without it the output stays desktop-
 # shaped, which is what every other example wants.
 #
 # `--replay FILE` drives one of the `.touch` recordings the headless
 # tests use (`iris/transcript-fixture/touch/`) into the window through
 # `rig-input`'s `replay-touch` -- one recording, both layers. With
 # `--shot` it also writes `<shot>-before.png` from just before the
 # gesture, since "the list moved" is a claim about two pictures.
 #
 # `--bin` runs a real crate binary instead of an example (E4's
 # `desktop-app`, which is a window a person runs, not a demo) --
@@ -29,19 +48,31 @@ here=$(cd "$(dirname "$0")" && pwd)
 run="${XDG_RUNTIME_DIR:-/tmp}/iris-headless"
 seconds=3
 shot=""
 replay=""
 example=""
 kind=example
 phone=no
 # The phone Iris runs the bench on. Not typed from memory: these are
 # `transcript_fixture::PHONE_WIDTH`/`PHONE_HEIGHT`/`PHONE_SCALE`, which
 # in turn come from her own reports -- keep the three in step.
 PHONE_MODE=1080x2424@120Hz
 PHONE_SCALE=2.55
 DESKTOP_MODE=1920x1200@60Hz
 while [ $# -gt 0 ]; do
    case "$1" in
        --shot) shot=$2; shift 2 ;;
        --seconds) seconds=$2; shift 2 ;;
        --bin) kind=bin; shift ;;
        --phone) phone=yes; shift ;;
        --replay) replay=$2; shift 2 ;;
        --) shift; break ;;
        *) example=$1; shift ;;
    esac
 done
-[ -n "$example" ] || { echo "usage: $0 NAME [--bin] [--shot PNG] [--seconds N] [-- cargo args]" >&2; exit 2; }
+[ -n "$example" ] || { echo "usage: $0 NAME [--bin] [--phone] [--replay TOUCH] [--shot PNG] [--seconds N] [-- cargo args]" >&2; exit 2; }
 [ -z "$replay" ] || [ -f "$replay" ] || { echo "run-headless: no touch script at $replay" >&2; exit 2; }
 mkdir -p "$run"
 export SWAYSOCK="$run/sway.sock"
@@ -78,6 +109,27 @@ export WAYLAND_DISPLAY
 echo "run-headless: $WAYLAND_DISPLAY (sway $(swaymsg -t get_version --raw | sed -n 's/.*"human_readable":"\([^"]*\)".*/\1/p'))" >&2
 # Set every run rather than only when it changes: this compositor is
 # reused across runs (see the socket comment above), so a desktop-shaped
 # run after a phone-shaped one would otherwise inherit the phone's output
 # and silently screenshot the wrong size.
 if [ "$phone" = yes ]; then
    mode=$PHONE_MODE
    export IRIS_SCALE="$PHONE_SCALE"
    echo "run-headless: phone-shaped output $PHONE_MODE at IRIS_SCALE=$PHONE_SCALE" >&2
 else
    mode=$DESKTOP_MODE
 fi
 swaymsg output HEADLESS-1 mode "$mode" >/dev/null
 # The extent `replay-touch` positions against, so a script's coordinates
 # are the output's own pixels.
 out_w=${mode%x*}
 out_h=${mode#*x}; out_h=${out_h%@*}
 # Built before the app starts, so a compile error is not reported as a
 # window that failed to move.
 [ -z "$replay" ] || cargo build --bin replay-touch -p rig-input >&2
 cd "$here"
 if [ "$kind" = bin ]; then
    cargo build --bin "$example" "$@" >&2
@@ -111,6 +163,18 @@ while [ $i -lt "$((seconds * 2))" ]; do
    i=$((i + 1)); sleep 0.5
 done
 if [ -n "$replay" ] && kill -0 "$pid" 2>/dev/null; then
    if [ -n "$shot" ]; then
        grim "${shot%.png}-before.png"
        echo "run-headless: wrote ${shot%.png}-before.png (before the gesture)" >&2
    fi
    "$here/target/debug/replay-touch" "$out_w" "$out_h" "$replay"
    # A fling outlives the finger: the gesture's own last sample is not
    # when the list stops. Long enough for Android's spline to settle
    # (`FlingCalculator::duration` tops out around a second and a half).
    sleep 2
 fi
 if kill -0 "$pid" 2>/dev/null; then
    [ -n "$shot" ] && grim "$shot" && echo "run-headless: wrote $shot" >&2
    kill "$pid" 2>/dev/null || true
@@ -12,6 +12,10 @@ impl<T: HasAndroidUiState> FocusHost for T {
        self.android_state_mut().focus = id;
    }
    fn is_focused(&self, id: WeakWidget<TextEdit>) -> bool {
        self.android_state().focus == Some(id)
    }
    fn focus_gained(&mut self, region: Option<PixelRegion>) {
        // Showing the keyboard is a JNI call (`InputMethodManager.showSoftInput`),
        // and this runs deep inside the platform-agnostic sensor dispatch
@@ -49,6 +49,52 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
    fn focus(&self) -> Option<WeakWidget<TextEdit>> {
        self.state.android_state().focus
    }
    /// Tell Gboard where the caret/selection and the composing region
    /// actually are, via `InputMethodManager.updateSelection` -- every one
    /// of android-view's own demo's `set_composing_text_internal`/`render`
    /// calls this, and this bridge never did, which is what left Gboard's
    /// own model of the field diverging from `TextEdit`'s real one after
    /// the very first edit (RUST.md's P0 box, "doesn't enter it until I
    /// hit space, and also doesn't move cursor forward" -- Gboard holds
    /// its composing keystrokes back until it believes the app has caught
    /// up, and without this call it never does). Called from
    /// [`IrisViewPeer::after_input`], the one tail every touch/key/IME
    /// callback already runs through, rather than duplicated at each of
    /// this file's mutating methods.
    ///
    /// `candidates_start`/`candidates_end` report the composing region;
    /// `-1, -1` when nothing is composing, matching `EditorInfo`'s own
    /// convention. `compose_len` is tracked in `char`s (this module's doc
    /// comment), so this reports it as that many UTF-16 units back from the
    /// caret -- exact for the common BMP case, the same approximation
    /// `set_composing_text` already makes.
    pub(super) fn update_ime_selection(&mut self, ctx: &mut CallbackCtx) {
        let Some(focus) = self.focus() else { return };
        let text = &self.rsc[focus];
        let Some(sel) = text.selection_range() else {
            return;
        };
        let content = text.text();
        let sel_start = byte_to_utf16(content, sel.start) as i32;
        let sel_end = byte_to_utf16(content, sel.end) as i32;
        let compose_len = self.state.android_state().compose_len;
        let (comp_start, comp_end) = if compose_len > 0 {
            let caret = byte_to_utf16(content, text.caret().unwrap_or(sel.end)) as i32;
            (caret - compose_len as i32, caret)
        } else {
            (-1, -1)
        };
        let imm = ctx.view.input_method_manager(&mut ctx.env);
        imm.update_selection(
            &mut ctx.env,
            &ctx.view,
            sel_start,
            sel_end,
            comp_start,
            comp_end,
        );
    }
 }
 impl<State: AndroidAppState> InputConnection for IrisViewPeer<State> {
@@ -45,16 +45,38 @@ pub struct Insets {
    pub top: i32,
    pub right: i32,
    pub bottom: i32,
-    /// The keyboard's own inset (`WindowInsetsCompat.Type.ime()`), separate
+    /// The keyboard's own inset (`WindowInsets.Type.ime()`), in physical
-    /// from `bottom` (the system bars): a layout wants to know about the
+    /// pixels, separate from `bottom` (the system bars): a layout wants to
-    /// keyboard specifically, since it usually means "make room" rather
+    /// know about the keyboard specifically, since it usually means "make
-    /// than "stay clear of a corner".
+    /// room" rather than "stay clear of a corner".
    pub ime_bottom: i32,
    /// `WindowInsets.isVisible(ime())` -- whether the keyboard is up, which
    /// is **not** the same question as `ime_bottom > 0` and is why the two
    /// are carried separately. They disagree for the frames the keyboard
    /// spends sliding: visible, with a height still on its way to the full
    /// one. Anything asking "make how much room" reads `ime_bottom`;
    /// anything asking "is the keyboard up" reads this. See
    /// `MainActivity.java`'s comment for the history -- the height used to
    /// be sent *as* this boolean, which is what left the composer padded by
    /// one pixel on Iris's phone.
    pub ime_visible: bool,
 }
 #[derive(Default)]
 pub struct Shared {
    pub insets: Insets,
    /// How many times Java has called `applyWindowInsetsNative` for this
    /// peer, whether or not the numbers changed. Deliberately **not** a
    /// field of `Insets`, which is compared for equality each frame to
    /// decide whether to re-run `on_insets_changed`; a counter in there
    /// would make every dispatch look like a change.
    ///
    /// It exists because "the keyboard does not push anything up" has two
    /// completely different causes that look identical on screen -- the
    /// listener never fired, or it fired with a zero `ime_bottom` -- and
    /// Iris has no logcat on her phone (docs/IRIS_TODO.md). This number is
    /// in the `Diagnostics` overlay, so one screenshot separates them.
    pub updates: u64,
 }
 type SharedMap = HashMap<jlong, SendWrapper<Rc<RefCell<Shared>>>>;
@@ -89,15 +111,19 @@ extern "system" fn apply_window_insets<'local>(
    right: jint,
    bottom: jint,
    ime_bottom: jint,
    ime_visible: jint,
 ) {
    if let Some(shared) = map().lock().unwrap().get(&peer) {
-        shared.borrow_mut().insets = Insets {
+        let mut shared = shared.borrow_mut();
        shared.insets = Insets {
            left,
            top,
            right,
            bottom,
            ime_bottom,
            ime_visible: ime_visible != 0,
        };
        shared.updates += 1;
    }
    // Insets can change (the keyboard opening) with no resize and no
    // touch, so nothing else here would otherwise ask for a frame.
@@ -115,7 +141,7 @@ pub fn register_native_methods<'local, 'other_local>(
        &[
            NativeMethod {
                name: "applyWindowInsetsNative".into(),
-                sig: "(JIIIII)V".into(),
+                sig: "(JIIIIII)V".into(),
                fn_ptr: apply_window_insets as *mut c_void,
            },
            NativeMethod {
@@ -17,13 +17,15 @@ mod attr;
 mod ime;
 mod input;
 mod insets;
 mod platform;
 mod render;
 mod view;
 pub use insets::Insets;
 pub use render::AndroidRenderer;
 pub use view::{
-    AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState, IrisViewPeer, new_peer,
+    AndroidAppState, AndroidRsc, AndroidUiState, HasAndroidUiState, IrisViewPeer, WindowInsets,
    new_peer,
 };
 /// Registers the extra native methods this backend needs beyond what
@@ -0,0 +1,89 @@
 use crate::platform::OpenUrl;
 use android_view::{
    View,
    jni::{
        JNIEnv,
        objects::{JObject, JValue},
    },
 };
 use super::view::HasAndroidUiState;
 /// Android's URL opener. Like `FocusHost::focus_gained`'s keyboard, the
 /// real work is a JNI call and this runs deep inside the sensor dispatch
 /// with no `CallbackCtx` in reach -- so it raises a flag that
 /// `IrisViewPeer::after_input` consumes, exactly as
 /// `pending_show_keyboard` does.
 ///
 /// Last request wins: two links cannot be tapped in one frame, and a URL
 /// left queued from a frame that somehow never reached `after_input`
 /// would open at some unrelated later tap, which is worse than dropping
 /// it.
 impl<T: HasAndroidUiState> OpenUrl for T {
    fn open_url(&mut self, url: &str) {
        self.android_state_mut().pending_open_url = Some(url.to_string());
    }
 }
 /// `startActivity(new Intent(ACTION_VIEW, Uri.parse(url)))` on the view's
 /// own context.
 ///
 /// `FLAG_ACTIVITY_NEW_TASK` because the context here is the view's, which
 /// may be an application context rather than the activity's -- Android
 /// throws `AndroidRuntimeException` for a non-activity context without it,
 /// and it is harmless when the context *is* an activity's.
 ///
 /// Every failure is logged with the URL and returns; there is nothing to
 /// fall back to, and the reader will see that nothing happened.
 pub(super) fn open_url<'local>(env: &mut JNIEnv<'local>, view: &View<'local>, url: &str) {
    match try_open_url(env, view, url) {
        Ok(()) => {}
        Err(e) => {
            // A pending Java exception makes every later JNI call fail in
            // ways nowhere near here, so it is cleared at the boundary.
            let _ = env.exception_clear();
            log::warn!("could not open {url}: {e}");
        }
    }
 }
 fn try_open_url<'local>(
    env: &mut JNIEnv<'local>,
    view: &View<'local>,
    url: &str,
 ) -> Result<(), android_view::jni::errors::Error> {
    let context = env
        .call_method(&view.0, "getContext", "()Landroid/content/Context;", &[])?
        .l()?;
    let jurl = env.new_string(url)?;
    let uri = env.call_static_method(
        "android/net/Uri",
        "parse",
        "(Ljava/lang/String;)Landroid/net/Uri;",
        &[JValue::Object(jurl.as_ref())],
    )?;
    let action = env.new_string("android.intent.action.VIEW")?;
    let intent = env.new_object(
        "android/content/Intent",
        "(Ljava/lang/String;Landroid/net/Uri;)V",
        &[JValue::Object(action.as_ref()), JValue::Object(&uri.l()?)],
    )?;
    env.call_method(
        &intent,
        "addFlags",
        "(I)Landroid/content/Intent;",
        &[JValue::Int(FLAG_ACTIVITY_NEW_TASK)],
    )?;
    env.call_method(
        &context,
        "startActivity",
        "(Landroid/content/Intent;)V",
        &[JValue::Object(&JObject::from(intent))],
    )?;
    Ok(())
 }
 /// `android.content.Intent.FLAG_ACTIVITY_NEW_TASK`. A constant rather than
 /// a static-field read: it is part of the platform's stable ABI and
 /// reading it costs two more JNI calls that can each fail.
 const FLAG_ACTIVITY_NEW_TASK: i32 = 0x1000_0000;
@@ -48,33 +48,127 @@ pub struct AndroidRenderer {
    config: SurfaceConfiguration,
    encoder: CommandEncoder,
    pub ui: UiRenderNode,
    /// The adapter identity, kept past `new()` for the Diagnostics page --
    /// `Adapter` itself is not `Clone`, so the three fields the page shows
    /// are copied out once here rather than holding the adapter.
    pub adapter_name: String,
    pub adapter_backend: Backend,
    pub adapter_driver: String,
    /// Every uncaptured wgpu error since this renderer was created -- see
    /// `iris_core::WgpuErrorLog`'s doc comment. Installed on `device` in
    /// `new()`, kept here so the Diagnostics page and the per-frame log in
    /// `update()` can both read it without a global.
    pub wgpu_errors: iris_core::WgpuErrorLog,
    /// Frames drawn on this surface -- what gates the first-10-frames log
    /// `update()` writes (RUST.md's P0 box, "the first input frame"
    /// investigation): a fresh surface is exactly what Iris's own report
    /// says renders correctly at first, so the frames that matter are the
    /// first several after each `surface_changed`, not an arbitrary window
    /// during a long-running session.
    frame_count: u64,
    /// Physical pixels per dp -- see `android::view::AndroidUiState::
    /// content_scale`'s field comment for what this feeds.
    content_scale: f32,
 }
 /// One frame's worth of the counters `render/mod.rs`'s doc comments on
 /// `FrameUpdateStats`/`take_image_bind_group_creates`/
 /// `take_atlas_pages_grown` describe -- assembled here because the three
 /// live on two different calling conventions (`FrameUpdateStats` from this
 /// exact `update()` call; the other two describe the *previous* frame,
 /// same as `bench_images`' existing use of them) and a diagnostic reader
 /// should not have to know that split.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct FrameDiagnostics {
    pub masks_resized: bool,
    pub moves_resized: bool,
    /// From the previous frame's `update()` -- see the struct doc.
    pub atlas_pages_grown_prev: u64,
    pub image_bind_group_creates_prev: u64,
 }
 impl AndroidRenderer {
-    pub fn new(window: NativeWindow, width: u32, height: u32) -> Self {
+    /// `Err` holds a full, human-readable report for **every** way this
-        // `force-gles` (RUST.md's I5 "Where iris's frame time goes") swaps
+    /// can fail -- no surface, no adapter, no device, or wgpu's own error
-        // the software-Vulkan (SwiftShader) path for GLES/virgl on the same
+    /// text (`UiRenderNode::new`'s doc comment) plus the adapter identity
-        // build, to isolate whether the backend itself explains the frame
+    /// and the limits/downlevel flags bind-group-layout validation checks
-        // time gap against Compose. `cfg!` rather than a runtime switch:
+    /// against -- rather than the panic wgpu's default error handler would
-        // there is no way to hand an env var to an already-launched Android
+    /// otherwise raise with no caller able to see it. This is what aborted
-        // process on this machine (see the feature's doc in Cargo.toml).
+    /// the P0 bench APK on Iris's phone with only "wgpu error: Validation
-        let backends = if cfg!(feature = "force-gles") {
+    /// Error" surviving into the crash report (RUST.md's P0 box, "iris
    /// bench crash on the phone, 2026-09-06"): `create_bind_group_layout`
    /// validates against *this* adapter's downlevel capabilities and
    /// limits, which a desktop GPU and the emulator's software renderers
    /// never exercised. The caller (`android::view::IrisViewPeer::
    /// surface_changed`) logs this one-line-flattened and shows it on
    /// screen instead of aborting the process.
    pub fn new(
        window: NativeWindow,
        width: u32,
        height: u32,
        content_scale: f32,
    ) -> Result<Self, String> {
        // `force-gles` (RUST.md's I5 "Where iris's frame time goes") pins
        // the build to GLES, to isolate whether the backend itself explains
        // the frame time gap against Compose. `cfg!` rather than a runtime
        // switch: there is no way to hand an env var to an already-launched
        // Android process on this machine (see the feature's doc in
        // Cargo.toml).
        //
        // Otherwise: **Vulkan where it has an adapter at all, GLES where it
        // has none.** `Backends::PRIMARY` leaves `GL` out, so a device
        // offering only a GLES adapter had no adapter at all and this
        // function aborted the process -- this checkout's emulator, whose
        // Vulkan ICD carries no adapter behind it (`NotFound {
        // active_backends: VULKAN, no_adapter_backends: VULKAN,
        // supported_backends: VULKAN | GL }`), and the crash loop in
        // RUST.md's queue.
        //
        // The choice is made *before any surface exists*, with an instance
        // that never touches the window, because **an Android window can be
        // connected to one graphics API only**. One instance carrying both
        // backends does not work: `create_surface` builds a raw surface per
        // backend, Vulkan's `vkCreateAndroidSurfaceKHR` claims the window
        // first, and the GLES surface made from the same window then fails
        // `configure` as lost -- measured here as "In Surface::configure /
        // Invalid surface" followed by an abort in
        // `Surface::get_current_texture_view`, "Surface is not configured
        // for presentation".
        let mut backends = if cfg!(feature = "force-gles") {
            Backends::GL
        } else {
            Backends::PRIMARY
        };
-        let instance = Instance::new(&InstanceDescriptor {
+        let mut instance = Instance::new(&InstanceDescriptor {
            backends,
            ..Default::default()
        });
        // A build already pinned to GLES has nowhere to fall back to.
        if backends != Backends::GL && instance.enumerate_adapters(backends).block_on().is_empty() {
            log::warn!(
                "iris renderer: no {backends:?} adapter on this device, falling back to GLES"
            );
            backends = Backends::GL;
            instance = Instance::new(&InstanceDescriptor {
                backends,
                ..Default::default()
            });
        }
        // SAFETY: the `NativeWindow` outlives the surface built from it --
        // android-view drops the old renderer (and this surface with it)
        // before handing over a new window, in `surface_changed` below.
        let surface = instance
            .create_surface(SurfaceTarget::from(AndroidWindowHandle { window }))
-            .expect("Could not create android surface!");
+            .map_err(|error| format!("Could not create the android surface: {error}"))?;
        // Every step from here to a live device reports rather than
        // panics, for the one reason: on the phone these builds run on
        // there is no `adb`, so an abort's message reaches a tombstone
        // nobody can read and the launcher simply restarts the app --
        // which is what a crash loop with no explanation is. The caller
        // (`android::view::IrisViewPeer::surface_changed`) puts this
        // string on screen and in the app's own log ring instead.
        let adapter = instance
            .request_adapter(&RequestAdapterOptions {
                power_preference: PowerPreference::default(),
@@ -82,7 +176,7 @@ impl AndroidRenderer {
                force_fallback_adapter: false,
            })
            .block_on()
-            .expect("Could not get adapter!");
+            .map_err(|error| format!("No usable GPU adapter for backends {backends:?}: {error}"))?;
        // Same request as the winit backend's `UiRenderer::new` -- no
        // binding-array features, see TEXTURES.md's "Recommended shape".
@@ -94,7 +188,37 @@ impl AndroidRenderer {
                ..Default::default()
            })
            .block_on()
-            .expect("Could not get device!");
+            .map_err(|error| {
                format!(
                    "The adapter {} ({:?}) refused a device: {error}",
                    adapter.get_info().name,
                    adapter.get_info().backend,
                )
            })?;
        // wgpu's default handler for an error raised outside `UiRenderNode::
        // new`'s own error scopes (i.e. everything past device creation --
        // an ordinary frame's `update`/`draw`) is `panic!`, unconditionally,
        // with no caller able to intervene: the same mechanism that aborted
        // the P0 bench APK once already, just at a different call site. Log
        // and record instead of letting that default stand -- RUST.md's P0
        // box, "every wgpu uncaptured error ... it must never panic in
        // release".
        let wgpu_errors = iris_core::WgpuErrorLog::default();
        let wgpu_errors_for_handler = wgpu_errors.clone();
        device.on_uncaptured_error(std::sync::Arc::new(move |error| {
            log::error!("iris wgpu uncaptured error: {error}");
            wgpu_errors_for_handler.record(error);
        }));
        let info = adapter.get_info();
        let adapter_name = info.name.clone();
        let adapter_backend = info.backend;
        let adapter_driver = if info.driver_info.is_empty() {
            info.driver.clone()
        } else {
            format!("{} {}", info.driver, info.driver_info)
        };
        let surface_caps = surface.get_capabilities(&adapter);
        let surface_format = surface_caps
@@ -117,16 +241,121 @@ impl AndroidRenderer {
        surface.configure(&device, &config);
        let encoder = Self::create_encoder(&device);
-        let ui = UiRenderNode::new(&device, &queue, &config);
+        // Physical pixels, matching the swapchain's own `width`/`height`
        // exactly -- see `android::view::AndroidUiState::content_scale`'s
        // field comment for why this is no longer divided into a separate
        // logical space (that stopgap is what made text blurry, RUST.md's
        // P0 box). `Len::dp` folds the density in at layout time instead,
        // so nothing here needs to know it at all.
        let window_size = iris_core::util::Vec2::new(width as f32, height as f32);
        let ui = match UiRenderNode::new(&device, &queue, &config, window_size) {
            Ok(ui) => ui,
            Err(wgpu_error) => return Err(Self::diagnostic(&adapter, &wgpu_error)),
        };
-        Self {
+        Ok(Self {
            surface,
            device,
            queue,
            config,
            encoder,
            ui,
-        }
+            adapter_name,
            adapter_backend,
            adapter_driver,
            wgpu_errors,
            frame_count: 0,
            content_scale,
        })
    }
    /// The adapter identity plus every limit and downlevel flag
    /// `create_bind_group_layout` validates a storage buffer or texture
    /// binding against, followed by wgpu's own error text -- everything a
    /// person reading this off a screenshot needs to tell "this adapter
    /// lacks X" from "this is a bug in the layout." Named explicitly rather
    /// than `{limits:?}`/`{flags:?}` wholesale, because `Limits` alone is
    /// dozens of fields nobody asked for -- these are exactly the ones
    /// `UiRenderNode::new`'s layouts (`rsc_layout`, `masks_layout`,
    /// `primitive_layout`) can fail against, per `CreateBindGroupLayoutError`
    /// (`wgpu-core::binding_model`) and its downlevel-flag checks
    /// (`wgpu-core::device::resource`, `VERTEX_STORAGE` in particular --
    /// the one storage buffer here, `move_offsets`, that is visible to the
    /// vertex stage).
    fn diagnostic(adapter: &Adapter, wgpu_error: &str) -> String {
        let info = adapter.get_info();
        let limits = adapter.limits();
        let downlevel = adapter.get_downlevel_capabilities();
        format!(
            "iris could not start rendering. Copy this text and send it to Iris.\n\n\
             adapter: {name} ({backend:?}), driver: {driver} {driver_info}\n\
             limits: max_storage_buffers_per_shader_stage={max_storage_buffers} \
             max_sampled_textures_per_shader_stage={max_sampled_textures} \
             max_bind_groups={max_bind_groups} \
             max_bindings_per_bind_group={max_bindings} \
             max_storage_buffer_binding_size={max_storage_binding} \
             min_storage_buffer_offset_alignment={min_storage_align}\n\
             downlevel flags: {flags:?}\n\n\
             {wgpu_error}",
            name = info.name,
            backend = info.backend,
            driver = info.driver,
            driver_info = info.driver_info,
            max_storage_buffers = limits.max_storage_buffers_per_shader_stage,
            max_sampled_textures = limits.max_sampled_textures_per_shader_stage,
            max_bind_groups = limits.max_bind_groups,
            max_bindings = limits.max_bindings_per_bind_group,
            max_storage_binding = limits.max_storage_buffer_binding_size,
            min_storage_align = limits.min_storage_buffer_offset_alignment,
            flags = downlevel.flags,
        )
    }
    /// The Diagnostics page's whole report: adapter identity, font
    /// resolution, the atlas's own view count, every uncaptured wgpu error
    /// so far, and the frame report -- RUST.md's P0 box, "a named
    /// `Diagnostics` control ... adapter info, limits, fonts found, atlas
    /// format/pages, wgpu errors so far, frame report". One string rather
    /// than a struct the caller formats, since the only consumer is a
    /// plain `TextView` with a "copy this and send it to Iris" affordance,
    /// the same shape `surface_changed`'s crash report already uses
    /// (UI_RULES.md: a failure -- or here, a state worth reporting --
    /// carries enough to act on where it's shown).
    pub fn diagnostics_report(
        &self,
        font: &iris_core::FontDiagnostics,
        frame_report: &str,
    ) -> String {
        let errors = self.wgpu_errors.snapshot();
        let errors_text = if errors.is_empty() {
            "none".to_string()
        } else {
            errors.join("\n  ")
        };
        format!(
            "iris diagnostics. Copy this text and send it to Iris.\n\n\
             adapter: {name} ({backend:?}), driver: {driver}\n\
             content_scale: {content_scale}\n\
             atlas format: Rgba8Unorm, views live: {views}\n\
             fonts: {families_found} families found, default={default_family:?} \
             mono={default_mono_family:?}\n\
             fonts resolved: regular={regular:?} bold={bold:?} italic={italic:?} \
             mono={mono:?}\n\
             wgpu errors since surface creation:\n  {errors_text}\n\n\
             {frame_report}",
            name = self.adapter_name,
            backend = self.adapter_backend,
            driver = self.adapter_driver,
            content_scale = self.content_scale,
            views = self.ui.view_count(),
            families_found = font.families_found,
            default_family = font.default_family,
            default_mono_family = font.default_mono_family,
            regular = font.regular_resolved,
            bold = font.bold_resolved,
            italic = font.italic_resolved,
            mono = font.mono_resolved,
        )
    }
    fn create_encoder(device: &Device) -> CommandEncoder {
@@ -135,8 +364,31 @@ impl AndroidRenderer {
        })
    }
-    pub fn update(&mut self, ui: &mut UiData, render: &mut UiRenderState) {
+    /// Returns what changed this frame -- see `FrameDiagnostics`'s doc
-        self.ui.update(&self.device, &self.queue, ui, render);
+    /// comment for why two of its four fields describe the *previous*
    /// frame rather than this one. `IrisViewPeer::render` logs this for
    /// the first `DIAGNOSTIC_FRAMES` frames after each `surface_changed`,
    /// per RUST.md's P0 box ("the first input frame" investigation): the
    /// glyph-wipe Iris reported happens on the first tap or scroll after a
    /// fresh surface, so that is exactly the window a report needs to
    /// cover, not an arbitrary slice of a long session.
    pub fn update(&mut self, ui: &mut UiData, render: &mut UiRenderState) -> FrameDiagnostics {
        let atlas_pages_grown_prev = self.ui.take_atlas_pages_grown();
        let image_bind_group_creates_prev = self.ui.take_image_bind_group_creates();
        let stats = self.ui.update(&self.device, &self.queue, ui, render);
        self.frame_count += 1;
        FrameDiagnostics {
            masks_resized: stats.masks_resized,
            moves_resized: stats.moves_resized,
            atlas_pages_grown_prev,
            image_bind_group_creates_prev,
        }
    }
    /// Frames drawn on this surface so far -- see `frame_count`'s field
    /// comment.
    pub fn frame_count(&self) -> u64 {
        self.frame_count
    }
    /// Draws and presents one frame, returning the time spent in
@@ -179,15 +431,27 @@ impl AndroidRenderer {
        submit_start.elapsed()
    }
    /// Physical pixels -- the unit layout and hit-testing use, matching
    /// the window uniform's own units. See
    /// `android::view::AndroidUiState::content_scale`'s field comment.
    pub fn size(&self) -> iris_core::util::Vec2 {
-        (self.config.width, self.config.height).into()
+        iris_core::util::Vec2::new(self.config.width as f32, self.config.height as f32)
    }
    /// Reconfigures the surface and rewrites the window uniform for a new
    /// physical size -- deliberately the *only* two things this does.
    /// `device`, `ui`'s atlas, buffers and bind groups are untouched, so a
    /// call here (as opposed to a fresh `AndroidRenderer::new`) never
    /// invalidates a glyph the CPU-side cache already placed in the atlas.
    /// See `android::view::IrisViewPeer::surface_changed`'s doc comment for
    /// why that distinction matters -- it is what keeps text on screen
    /// across an IME resize.
    pub fn resize(&mut self, width: u32, height: u32) {
        self.config.width = width;
        self.config.height = height;
        self.surface.configure(&self.device, &self.config);
-        self.ui.resize((width, height), &self.queue);
+        let size = iris_core::util::Vec2::new(width as f32, height as f32);
        self.ui.resize(size, &self.queue);
    }
 }
@@ -4,8 +4,12 @@ use accesskit_android::Adapter as AccessAdapter;
 use android_view::{
    AccessibilityNodeInfo, AccessibilityNodeProvider, Bundle, CallbackCtx, Context,
    InputConnection, KeyEvent, MotionEvent, Rect, View, ViewPeer,
-    jni::{JNIEnv, JavaVM, objects::GlobalRef, sys::jint},
+    jni::{
-    ndk::event::{Keycode, MotionAction},
+        JNIEnv, JavaVM,
        objects::{GlobalRef, JValue},
        sys::jint,
    },
    ndk::event::{Axis, Keycode, MotionAction},
 };
 // `marker::Sized` explicitly: `crate::prelude::*` below also brings in the
 // `Sized` *widget* (`widget::position::sized::Sized`), and an unqualified
@@ -29,6 +33,10 @@ use super::{
 /// `Option` because a `SurfaceView`'s surface does not outlive backgrounding
 /// the way a winit `Window` does -- `surfaceDestroyed`/`surfaceCreated` can
 /// happen any number of times over the life of one `IrisViewPeer`.
 /// How many frames after each `surface_changed` `render()` logs a full
 /// diagnostic line for -- see the log site's own comment.
 const DIAGNOSTIC_FRAMES: u64 = 10;
 pub struct AndroidUiState {
    pub root: Option<StrongWidget>,
    pub renderer: Option<AndroidRenderer>,
@@ -46,6 +54,10 @@ pub struct AndroidUiState {
    /// inside the platform-agnostic sensor dispatch with no `CallbackCtx`
    /// in reach.
    pub pending_show_keyboard: bool,
    /// A URL a tapped link asked the platform to open, for the same
    /// reason `pending_show_keyboard` is a flag rather than a call --
    /// see `android/platform.rs`.
    pub pending_open_url: Option<String>,
    /// Window insets, filled in from outside the normal `ViewPeer` callback
    /// path -- see `android/insets.rs` for why they need a registry of
    /// their own.
@@ -62,10 +74,41 @@ pub struct AndroidUiState {
    /// because `dumpsys gfxinfo` cannot see a `SurfaceView`'s own
    /// GPU-drawn frames at all. See `iris_core::FrameReport`'s own doc.
    pub frame_report: FrameReport,
    /// `DisplayMetrics.density` (`new_peer`'s doc comment): physical pixels
    /// per dp on this device, read once at view construction and carried
    /// on `UiRenderState::density` (`render.set_density`, `new_peer`) from
    /// then on -- every `Len::dp` in the widget tree resolves against it at
    /// layout time (`Len::dp`'s field doc, IRIS_TODO.md's
    /// "density-independent length unit" item, 2026-09-06).
    ///
    /// **Everything else in this module is physical pixels, matching the
    /// real wgpu surface/swapchain resolution** -- window size, touch
    /// coordinates, insets. That is a correction from an earlier version
    /// of this comment, which had `window_size`/`surface_changed`'s
    /// `UiRenderState::resize` call divide by `content_scale` into a
    /// *logical* coordinate space instead, as a global stopgap for
    /// RUST.md's P0 box's phone report ("text is far too small"). That
    /// stopgap fixed the size but not the *sharpness*: dividing to logical
    /// units meant a `16.0`-sized glyph rasterised at 16 physical px and
    /// then implicitly upscaled ~3x by the NDC mapping onto the real
    /// physical framebuffer -- the exact "blurry ... glyphs drawn at
    /// logical size and stretched by the scale" Iris reported next.
    /// Resolving `dp` at layout time replaces it: a widget author writes
    /// `dp(16)` for a size that should look the same physical size on any
    /// density, and everything downstream (layout, hit-testing, the window
    /// uniform, and the font size handed to the text shaper) works in the
    /// display's own physical pixels throughout, so nothing is
    /// rasterised at one resolution and displayed at another.
    pub content_scale: f32,
    /// The last insets `render()` saw -- compared each frame so
    /// `AndroidAppState::on_insets_changed` fires only when they actually
    /// change (once at startup for the status bar, again if the device
    /// rotates), not every frame.
    last_insets: Insets,
 }
 impl AndroidUiState {
-    fn new(shared: Rc<RefCell<Shared>>) -> Self {
+    fn new(shared: Rc<RefCell<Shared>>, content_scale: f32) -> Self {
        Self {
            root: None,
            renderer: None,
@@ -74,16 +117,41 @@ impl AndroidUiState {
            last_click: Instant::now(),
            compose_len: 0,
            pending_show_keyboard: false,
            pending_open_url: None,
            shared,
            access_adapter: Default::default(),
            access: AccessTree::new(),
            frame_report: FrameReport::new(),
            content_scale,
            last_insets: Insets::default(),
        }
    }
    pub fn insets(&self) -> Insets {
        self.shared.borrow().insets
    }
    /// The insets state as one line for a diagnostics pane, including how
    /// many times the platform has delivered any -- see
    /// `insets::Shared::updates` for why the count is the load-bearing
    /// part. `dispatches=0` says the listener has never run and the
    /// numbers beside it are defaults rather than measurements, which is
    /// the distinction a screenshot otherwise cannot make (UI_RULES.md,
    /// "design the unknown state first").
    pub fn insets_report(&self) -> String {
        let shared = self.shared.borrow();
        let i = shared.insets;
        if shared.updates == 0 {
            return "insets: dispatches=0 -- the platform has never called \
                    onApplyWindowInsets, so nothing below was measured"
                .to_string();
        }
        format!(
            "insets: dispatches={} left={} top={} right={} bottom={} ime_bottom={} \
             ime_visible={}",
            shared.updates, i.left, i.top, i.right, i.bottom, i.ime_bottom, i.ime_visible,
        )
    }
 }
 impl HasRoot for AndroidUiState {
@@ -120,6 +188,54 @@ pub trait AndroidAppState: HasAndroidUiState {
    /// storing them has no effect on that mechanism.
    #[allow(unused_variables)]
    fn platform_ready(&mut self, rsc: &mut AndroidRsc<Self>, vm: JavaVM, view: GlobalRef) {}
    /// Called from `render()` whenever `AndroidUiState::insets()` differs
    /// from what it was last frame -- once at startup for the status bar
    /// (RUST.md's P0 box: "the status-bar inset is not applied" reported
    /// the two top buttons sitting under it, because nothing read `.top`
    /// at all), and again on a rotation or the keyboard opening/closing.
    /// `insets` is in the same physical-pixel units everything else in the
    /// tree now uses (`AndroidUiState::content_scale`'s field comment), so
    /// a widget can add it to a layout size directly -- `dp(...) +
    /// abs(insets.top)` if the widget wants a density-independent size
    /// plus the system bar's own (already-physical) height. The default
    /// does nothing -- most screens have no chrome that sits under a
    /// system bar.
    #[allow(unused_variables)]
    fn on_insets_changed(&mut self, rsc: &mut AndroidRsc<Self>, insets: WindowInsets) {}
 }
 /// `insets::Insets` as `f32`, for the widget-facing callback above -- a
 /// distinct type from `insets::Insets` so a caller of `on_insets_changed`
 /// is not coupled to that module's own (`i32`, JNI-shaped) representation.
 /// Both are physical pixels; this used to divide by `content_scale` into a
 /// separate *logical* unit (hence the old name, `LogicalInsets`), back when
 /// the rest of layout was logical too -- see `AndroidUiState::content_scale`'s
 /// field comment for why that stopgap is gone.
 #[derive(Clone, Copy, Default, Debug, PartialEq)]
 pub struct WindowInsets {
    pub left: f32,
    pub top: f32,
    pub right: f32,
    pub bottom: f32,
    /// How much of the window the keyboard covers, in physical pixels --
    /// what a layout pads by. See `insets::Insets::ime_visible` for why
    /// "is the keyboard up" is a separate field rather than this one
    /// compared against zero.
    pub ime_bottom: f32,
    pub ime_visible: bool,
 }
 impl WindowInsets {
    fn from_physical(insets: Insets) -> Self {
        Self {
            left: insets.left as f32,
            top: insets.top as f32,
            right: insets.right as f32,
            bottom: insets.bottom as f32,
            ime_bottom: insets.ime_bottom as f32,
            ime_visible: insets.ime_visible,
        }
    }
 }
 /// The android-view analogue of `default::DefaultRsc` -- identical in
@@ -196,6 +312,11 @@ pub struct IrisViewPeer<State: AndroidAppState> {
    pub(super) render: UiRenderState,
    pub(super) state: State,
    task_recv: TaskMsgReceiver<AndroidRsc<State>>,
    /// Anchored on the first `MotionEvent` this view receives and never
    /// re-anchored after -- how `on_touch_event` dates every touch sample.
    /// Its path out is the peer's own drop: it holds nothing but three
    /// numbers and is meaningless to any other view.
    input_clock: Option<PointerClock>,
 }
 impl<State: 'static, I: RscIdx<AndroidRsc<State>>> std::ops::Index<I> for AndroidRsc<State> {
@@ -219,12 +340,13 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
        }
    }
-    /// Common tail for every callback that might have changed the cursor,
+    /// One pointer sample through the sensors, plus the platform calls a
-    /// the text focus, or the widget tree: run the sensors that touch
+    /// handler can only ask for by raising a flag. Split out of
-    /// input feeds, then ask for a frame if the result needs drawing.
+    /// [`Self::after_input`] because a batched `MotionEvent` carries
-    /// Mirrors `default::DefaultApp::window_event`'s tail, split across
+    /// several samples that all belong to the same *frame*
-    /// android-view's several entry points instead of winit's one.
+    /// (`on_touch_event`): each one is a real input frame the widgets must
-    pub(super) fn after_input(&mut self, ctx: &mut CallbackCtx) {
+    /// see, but only the last one ends the frame and asks for a redraw.
    fn run_input_frame(&mut self, ctx: &mut CallbackCtx) {
        let window_size = self.window_size();
        let ui_state = self.state.android_state_mut();
        let cursor = ui_state.cursor.clone();
@@ -241,6 +363,25 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
        if std::mem::take(&mut ui_state.pending_show_keyboard) {
            show_soft_input(&mut ctx.env, &ctx.view);
        }
        if let Some(url) = ui_state.pending_open_url.take() {
            super::platform::open_url(&mut ctx.env, &ctx.view, &url);
        }
    }
    /// Common tail for every callback that might have changed the cursor,
    /// the text focus, or the widget tree: run the sensors that touch
    /// input feeds, then ask for a frame if the result needs drawing.
    /// Mirrors `default::DefaultApp::window_event`'s tail, split across
    /// android-view's several entry points instead of winit's one.
    pub(super) fn after_input(&mut self, ctx: &mut CallbackCtx) {
        self.run_input_frame(ctx);
        // RUST.md's P0 box, "doesn't enter it until I hit space, and also
        // doesn't move cursor forward": Gboard needs `updateSelection`
        // after every edit to keep its own model of the field in sync, or
        // it holds keystrokes back rather than trusting a screen it
        // believes is stale. See `update_ime_selection`'s own doc.
        self.update_ime_selection(ctx);
        let ui_state = self.state.android_state_mut();
        ui_state.cursor.end_frame();
@@ -264,23 +405,70 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
    /// magenta and screenshotting), but no primitive ever appears on top of
    /// it -- on both the Vulkan/SwiftShader and GLES/virgl backends. Leave
    /// these in until that is root-caused; removing them loses the exact
-    /// evidence a `logcat` capture needs to reproduce the state.
+    /// evidence a `logcat` capture needs to reproduce the state. Gated on
    /// `iris::diagnostics::trace_enabled` since 2026-09-07 (docs/RUST.md's
    /// review, D1): unconditional, they were two `debug!` lines every
    /// rendered frame, and `client_core::log_ring`'s `RingLogger` records
    /// every level the app's already-`Debug` install lets through
    /// regardless of target, so they filled the whole ring in under ten
    /// seconds at 120Hz and left `Copy report` nothing else to show.
    fn render(&mut self, ctx: &mut CallbackCtx) {
-        let ui_state = self.state.android_state();
+        if self.state.android_state().renderer.is_none() {
        if ui_state.renderer.is_none() {
            return;
        }
-        log::debug!(
+        // See `AndroidAppState::on_insets_changed`'s doc comment: fires
-            "render(): root={:?} widgets={} active={} root_px={:?} out_size={:?}",
+        // exactly when insets actually differ from last frame, not every
-            ui_state.root.is_some(),
+        // frame -- most frames this is one `Insets` equality check against
-            self.rsc.widgets().len(),
+        // a `Copy` struct. Done before `ui_state` is bound below, since
-            self.render.active_widgets(),
+        // `on_insets_changed` needs `&mut self.state`/`&mut self.rsc` both.
-            ui_state
+        let ui_state = self.state.android_state();
-                .root
+        let current_insets = ui_state.insets();
-                .as_ref()
+        if current_insets != ui_state.last_insets {
-                .and_then(|r| self.render.window_region(r, &self.rsc)),
+            let physical = WindowInsets::from_physical(current_insets);
-            self.window_size(),
+            // One line per real insets change. Iris's phone is the only
-        );
+            // place several of these bugs reproduce and `adb logcat` is
            // the only instrument there (this-machine-android: system
            // tracing is broken on that device), so the numbers a layout
            // is actually fed have to reach the log -- "the composer
            // floats at launch" is unanswerable from a screenshot alone.
            log::info!(
                "iris insets: left={} top={} right={} bottom={} ime_bottom={} \
                 ime_visible={} window={:?}",
                physical.left,
                physical.top,
                physical.right,
                physical.bottom,
                physical.ime_bottom,
                physical.ime_visible,
                self.window_size(),
            );
            self.state.android_state_mut().last_insets = current_insets;
            self.state.on_insets_changed(&mut self.rsc, physical);
        }
        // Gated the same way `iris::frame`'s own line is (docs/RUST.md's
        // "Phone logging" review, D1): a bare `log::debug!` reaches
        // `client_core::log_ring`'s ring regardless of level, since
        // `RingLogger::enabled` is unconditionally `true` and the app
        // installs at `LevelFilter::Debug` -- two of these a rendered
        // frame filled the 2000-line ring in under ten seconds at 120Hz,
        // leaving `Copy report` nothing but frame spam. See
        // `iris::diagnostics`'s module doc.
        if crate::diagnostics::trace_enabled() {
            let ui_state = self.state.android_state();
            log::debug!(
                target: "iris::frame",
                "render(): root={:?} widgets={} active={} root_px={:?} out_size={:?}",
                ui_state.root.is_some(),
                self.rsc.widgets().len(),
                self.render.active_widgets(),
                ui_state
                    .root
                    .as_ref()
                    .and_then(|r| self.render.window_region(r, &self.rsc)),
                self.window_size(),
            );
        }
        // iris's own frame-time report (RUST.md's I5 box, "Measurements
        // taken" (b)): started here, at the same point a redraw request
        // fires, and stopped after `renderer.draw()`'s `queue.submit` +
@@ -288,27 +476,63 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
        // both count. See `iris_core::FrameReport`'s own doc for exactly
        // what this does and does not measure.
        let frame_start = Instant::now();
        // Anything moving on its own -- today a `List` coasting through a
        // fling -- is advanced here, before the draw, and asks for the
        // next frame at the end of this one. See
        // `UiData::tick_animations`; `default/mod.rs`'s
        // `RedrawRequested` arm is the same two lines for winit.
        let animating = self.rsc.ui.tick_animations(frame_start);
        let ui_state = self.state.android_state_mut();
        self.render.update(&ui_state.root, &mut self.rsc);
        let ui_state = self.state.android_state_mut();
        let Some(renderer) = &mut ui_state.renderer else {
            return;
        };
-        renderer.update(&mut self.rsc.ui, &mut self.render);
+        let frame_diagnostics = renderer.update(&mut self.rsc.ui, &mut self.render);
        // First `DIAGNOSTIC_FRAMES` frames after each `surface_changed`
        // only -- RUST.md's P0 box, "the first input frame" investigation:
        // the glyph-wipe Iris reported happens on the first tap or scroll
        // after a fresh surface, so a report from that window is what
        // would show whether an atlas grow, a masks/move_offsets resize, or
        // a fresh wgpu error coincided with it. `frame_count()` was just
        // incremented inside `update()`, so `<=` counts frame 1 through
        // `DIAGNOSTIC_FRAMES` inclusive.
        if renderer.frame_count() <= DIAGNOSTIC_FRAMES {
            log::info!(
                "iris frame diagnostics: frame={} masks_resized={} moves_resized={} \
                 atlas_pages_grown_prev={} image_bind_group_creates_prev={} wgpu_errors={}",
                renderer.frame_count(),
                frame_diagnostics.masks_resized,
                frame_diagnostics.moves_resized,
                frame_diagnostics.atlas_pages_grown_prev,
                frame_diagnostics.image_bind_group_creates_prev,
                renderer.wgpu_errors.snapshot().len(),
            );
        }
        let submit_to_present = renderer.draw();
        self.state
            .android_state_mut()
            .frame_report
            .record_split(frame_start.elapsed(), submit_to_present);
-        let ui_state = self.state.android_state();
+        crate::diagnostics::log_frame(&self.render, frame_start, submit_to_present, animating);
-        log::debug!(
+        // A frame callback is one-shot, so an animation that wants
-            "render(): after update active={} root_px={:?}",
+        // another frame has to say so every frame -- unlike `after_input`,
-            self.render.active_widgets(),
+        // which only has to ask when input dirtied something.
-            ui_state
+        if animating {
-                .root
+            ctx.view.post_frame_callback(&mut ctx.env);
-                .as_ref()
+        }
-                .and_then(|r| self.render.window_region(r, &self.rsc)),
+        if crate::diagnostics::trace_enabled() {
-        );
+            let ui_state = self.state.android_state();
            log::debug!(
                target: "iris::frame",
                "render(): after update active={} root_px={:?}",
                self.render.active_widgets(),
                ui_state
                    .root
                    .as_ref()
                    .and_then(|r| self.render.window_region(r, &self.rsc)),
            );
        }
        // I4 (RUST.md): only produces a `TreeUpdate` -- and so only queues
        // anything to raise -- when the named set actually changed this
@@ -337,6 +561,31 @@ fn show_soft_input<'local>(env: &mut JNIEnv<'local>, view: &View<'local>) {
    imm.show_soft_input(env, view, 0);
 }
 /// Replaces the activity's content with a plain, selectable, scrollable
 /// text view holding `report` -- the on-screen half of `surface_changed`'s
 /// renderer-failure path (UI_RULES.md: "a failure is reported where it
 /// happened, and says what to do next," here "copy this and send it").
 /// Goes through an ordinary instance method on the Java side
 /// (`IrisView.showRendererError`) rather than a new `native` method: this
 /// call is Rust reaching *into* Java, the opposite direction from every
 /// `native fn` android-view/`IrisView` declare, and an ordinary virtual
 /// call resolves against `ctx.view`'s real runtime class (`IrisView`) the
 /// same way any other JNI method call here does. Silently does nothing on
 /// any JNI failure -- there is no more-fallback screen to fall back to,
 /// and the `log::error!` in `surface_changed` already reached logcat
 /// first.
 fn show_renderer_error<'local>(env: &mut JNIEnv<'local>, view: &View<'local>, report: &str) {
    let Ok(message) = env.new_string(report) else {
        return;
    };
    let _ = env.call_method(
        &view.0,
        "showRendererError",
        "(Ljava/lang/String;)V",
        &[JValue::Object(message.as_ref())],
    );
 }
 impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
    fn on_key_down<'local>(
        &mut self,
@@ -379,9 +628,83 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
    ) -> bool {
        self.drain_tasks();
        let action = event.action_masked(&mut ctx.env);
        // Device (physical) pixels, same space layout now uses throughout
        // -- see `AndroidUiState::content_scale`'s field comment.
        let x = event.x(&mut ctx.env);
        let y = event.y(&mut ctx.env);
        // The event's own clock, converted through one anchor taken on the
        // first touch this view ever sees. Android reports sample times in
        // the `SystemClock.uptimeMillis()` base, which is the same
        // `CLOCK_MONOTONIC` an `Instant` reads, so a single
        // `(Instant, nanos)` pair converts every later sample exactly.
        // Anchoring **once** rather than per event is what keeps the times
        // ordered, and anchoring on the first event's *oldest* sample
        // rather than on its own time is what keeps that event's batch
        // from collapsing onto one instant -- `sense::PointerClock`'s doc
        // has both, and owns the arithmetic so it can be unit-tested off a
        // device (`sense_tests.rs`). See `CursorState::time`.
        let event_time = event.event_time_nanos(&mut ctx.env);
        if self.input_clock.is_none() {
            let history = event.history_size(&mut ctx.env);
            let oldest = if history > 0 {
                event.historical_event_time_nanos(&mut ctx.env, 0)
            } else {
                event_time
            };
            self.input_clock = Some(PointerClock::anchored(Instant::now(), event_time, oldest));
        }
        let mut clock = self.input_clock.expect("anchored just above");
        // `iris::input`'s own doc (`sense::log_input_event`): collected
        // only when tracing is on, since this is otherwise a `Vec` per
        // `MotionEvent` for a line nobody is reading -- the JNI reads
        // themselves (`historical_axis`/`historical_event_time_nanos`
        // below) already happen unconditionally, for the replay this
        // function does regardless of tracing.
        let trace_input = crate::diagnostics::trace_enabled();
        let mut historical_ms: Vec<(u64, f32, f32)> = Vec::new();
        // **Historical samples first.** A flick on a 120Hz screen is
        // delivered as one or two `MotionEvent`s with the intermediate
        // positions batched inside them, so reading only `x()`/`y()` threw
        // away every sample but the last: the velocity tracker saw one
        // `Pan` for the whole gesture, `VelocityTracker::velocity` answers
        // 0.0 below two samples, and the release therefore flung at zero --
        // Iris's phone, twice ("fling still doesn't work"), while a
        // `ui-trace` swipe, which is many evenly-spaced events, flung fine.
        // Replayed one at a time through the sensors rather than summarised,
        // so the arbiter, the tracker and any other sensor all see the same
        // motion the finger actually made; only the last sample ends the
        // frame (`after_input`).
        if matches!(action, MotionAction::Move) {
            let history = event.history_size(&mut ctx.env);
            // Android documents the historical samples as oldest first and
            // the event's own sample as the newest of the batch; everything
            // downstream (`VelocityTracker`, `DragArbiter`'s long-press
            // clock) assumes it, so say so here rather than at each reader.
            // `PointerClock::sample` is what asserts it, and it carries the
            // last sample seen *across* events, so the first sample of
            // every event is checked against the previous event's last one
            // rather than against the anchor.
            for pos in 0..history {
                let hx = event.historical_axis(&mut ctx.env, Axis::X, 0, pos);
                let hy = event.historical_axis(&mut ctx.env, Axis::Y, 0, pos);
                let ht = event.historical_event_time_nanos(&mut ctx.env, pos);
                let sample_at = clock.sample(ht);
                if trace_input {
                    historical_ms.push((clock.ms_since_anchor(ht), hx, hy));
                }
                let ui_state = self.state.android_state_mut();
                ui_state.cursor.pos = vec2(hx, hy);
                ui_state.cursor.time = sample_at;
                self.run_input_frame(ctx);
            }
        }
        let event_at = clock.sample(event_time);
        let event_ms = clock.ms_since_anchor(event_time);
        self.input_clock = Some(clock);
        let ui_state = self.state.android_state_mut();
        ui_state.cursor.time = event_at;
        match action {
            MotionAction::Down => {
                ui_state.cursor.pos = vec2(x, y);
@@ -391,12 +714,29 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
            MotionAction::Move => {
                ui_state.cursor.pos = vec2(x, y);
            }
            // `Cancel` ends the gesture the same way `Up` does, and must:
            // a release that never arrives leaves whichever widget took
            // pointer capture holding it forever, with every later touch
            // delivered to a drag nobody is performing. Confirmed present
            // before this pass rather than assumed -- it was one of the
            // three suspects listed for the phone's missing fling, and it
            // is not the cause.
            MotionAction::Up | MotionAction::Cancel => {
                ui_state.cursor.pos = vec2(x, y);
                ui_state.cursor.buttons.left.update(false);
            }
            _ => return false,
        }
        if trace_input {
            let action_word = match action {
                MotionAction::Down => "down",
                MotionAction::Move => "move",
                MotionAction::Up => "up",
                MotionAction::Cancel => "cancel",
                _ => "other",
            };
            crate::sense::log_input_event(action_word, x, y, event_ms, &historical_ms);
        }
        self.after_input(ctx);
        true
    }
@@ -431,7 +771,6 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
        height: i32,
    ) {
        self.drain_tasks();
        let window = holder.surface(&mut ctx.env).to_native_window(&mut ctx.env);
        // The layout engine's own notion of the canvas size is separate
        // from the wgpu surface's -- winit's backend sets it from
        // `WindowEvent::Resized`, and there is no equivalent automatic
@@ -440,13 +779,130 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
        // nothing but the clear colour: the widget tree laid out against
        // whatever size `UiRenderState::new` starts at instead of the
        // surface's real one.
-        self.render.resize((width as u32, height as u32));
+        //
-        // Drop the old renderer (and the surface it owns) before building
+        // **Physical pixels, matching `AndroidRenderer`'s own
-        // one from the new window -- see `AndroidRenderer`'s doc comment.
+        // `size()`/`resize()`/`new()`** -- `AndroidUiState::content_scale`'s
-        let ui_state = self.state.android_state_mut();
+        // field comment. This call sets `UiRenderState::output_size`, which
-        ui_state.renderer = None;
+        // every `rel`/`rest` length resolves against and every `abs`
-        ui_state.renderer = Some(AndroidRenderer::new(window, width as u32, height as u32));
+        // pixel-region compares to directly; a `dp(56)` height now folds
-        self.render(ctx);
+        // in the density at `Len::apply_rest` time instead of this call
        // dividing the whole window into a separate logical space, which
        // is what used to make every `abs`-unit size (a fixed `.height(56)`
        // in particular) mean something different from a `rest`-based one.
        self.render.resize((width as f32, height as f32));
        // **Reuse the existing renderer (device, atlas, buffers, bind
        // groups) when one is already live -- only reconfigure the
        // surface.** `surfaceChanged` fires on *every* size or format
        // change, not only on a genuinely new `Surface`/window: showing
        // the IME under `adjustResize` resizes the same `SurfaceView` and
        // is reported through this exact callback. Rebuilding the whole
        // `AndroidRenderer` here used to mean a fresh `UiRenderNode::new`
        // -- a brand-new, empty glyph atlas and fresh GPU buffers -- while
        // `iris_core`'s CPU-side glyph cache (`primitive/text.rs`) kept the
        // atlas coordinates it had already handed out against the *old*
        // atlas. Every glyph then drew from a UV rectangle that pointed
        // into a texture that had just been recreated empty, so text
        // vanished on the first keyboard open while rects (which never go
        // through the atlas) kept drawing -- exactly the "rectangles stay,
        // glyphs disappear" Iris reported. Confirmed by reading this path
        // end to end (no fresh-atlas rebuild anywhere in `resize()` below,
        // only in `AndroidRenderer::new`) before changing anything, per
        // AGENTS.md's "verify before finishing".
        //
        // `AndroidRenderer::resize` only reconfigures the wgpu surface and
        // rewrites the window uniform -- device, atlas, buffers and bind
        // groups are untouched, so the glyph cache's coordinates stay
        // valid. A genuinely new surface (after `surface_destroyed`, e.g.
        // backgrounding) still goes through `AndroidRenderer::new` below,
        // since `renderer` is `None` in that case.
        let already_live = self.state.android_state().renderer.is_some();
        log::info!(
            "iris surface: surface_changed {width}x{height} already_live={already_live} \
             glyphs_cached={} atlas_pages={}",
            self.rsc.ui.text.atlas.glyph_count(),
            self.rsc.ui.text.atlas.page_count(),
        );
        if already_live {
            let ui_state = self.state.android_state_mut();
            ui_state
                .renderer
                .as_mut()
                .expect("checked Some above")
                .resize(width as u32, height as u32);
            self.render(ctx);
            return;
        }
        let window = holder.surface(&mut ctx.env).to_native_window(&mut ctx.env);
        // `AndroidRenderer::new` used to panic here through wgpu's own
        // default uncaptured-error handler on a bind-group-layout
        // validation failure -- exactly what aborted the P0 bench APK on
        // Iris's phone with the message truncated to "wgpu error:
        // Validation Error" and nothing else recoverable from the crash
        // report (RUST.md's P0 box, "iris bench crash on the phone,
        // 2026-09-06"). It now returns the full diagnostic instead; this is
        // the one place in the app that can turn it into something a
        // person can read, since `ctx.view`/`ctx.env` (needed to reach the
        // Java side) are only in scope inside a `ViewPeer` callback.
        //
        // `content_scale` reaches `AndroidRenderer` only for the
        // Diagnostics page's report text now -- window size and the
        // shader's window uniform are physical pixels throughout (see the
        // `resize` call above), not divided by it.
        let content_scale = self.state.android_state().content_scale;
        match AndroidRenderer::new(window, width as u32, height as u32, content_scale) {
            Ok(renderer) => {
                // A genuinely new renderer means a genuinely new GPU device
                // and a fresh, empty glyph atlas -- the CPU-side glyph
                // cache (`TextData::atlas`) and the texture bookkeeping it
                // is built on (`UiData::textures`) both outlive `renderer`
                // itself (they live on `self.rsc`, not on `AndroidRenderer`),
                // so without this they would keep pointing at the *old*
                // device's now-gone textures -- the app-switch counterpart
                // to the keyboard-resize glyph wipe this same function's
                // `already_live` branch above already fixed by reusing the
                // renderer instead of rebuilding it. One mechanism either
                // way: this call only runs on the branch that actually
                // builds a new renderer, exactly where invalidation is
                // needed, never on the reuse branch, where it would throw
                // away perfectly valid GPU state for nothing.
                log::info!(
                    "iris surface: new renderer built ({:?}), clearing glyph atlas: \
                     glyphs={} pages={}",
                    renderer.adapter_backend,
                    self.rsc.ui.text.atlas.glyph_count(),
                    self.rsc.ui.text.atlas.page_count(),
                );
                self.rsc.ui.text.atlas.clear();
                self.rsc.ui.textures.reset();
                self.state.android_state_mut().renderer = Some(renderer);
                self.render(ctx);
            }
            Err(report) => {
                // One line for logcat (UI_RULES.md: "the full text for
                // whoever can read the log" lives here), the multi-line
                // original on screen -- `show_renderer_error` below.
                log::error!("iris renderer init failed: {}", report.replace('\n', " | "));
                // Deferred, not called directly: `Activity::setContentView`
                // tears the old view hierarchy down synchronously, which
                // fires `IrisView`'s own `onFocusChanged` before
                // `setContentView` returns -- straight back into this same
                // `IrisViewPeer` through `on_focus_changed` while
                // `with_peer` (android-view's dispatch, `view.rs` upstream)
                // still holds this peer's `RefCell` borrow for the
                // `surface_changed` call in progress. Found by inducing a
                // validation error and hitting `RefCell already borrowed`
                // at exactly that reentrant call (RUST.md's P0 box).
                // `push_dynamic_deferred_callback` runs after `with_peer`
                // drops the borrow, which is what every other callback in
                // this file that reaches into Java already relies on
                // (`raise_if_enabled`, above).
                ctx.push_dynamic_deferred_callback(move |env, view| {
                    show_renderer_error(env, view, &report);
                });
            }
        }
    }
    fn surface_destroyed<'local>(
@@ -454,6 +910,12 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
        _ctx: &mut CallbackCtx<'local>,
        _holder: &android_view::SurfaceHolder<'local>,
    ) {
        log::info!(
            "iris surface: surface_destroyed, tearing the renderer down \
             (glyphs_cached={} atlas_pages={})",
            self.rsc.ui.text.atlas.glyph_count(),
            self.rsc.ui.text.atlas.page_count(),
        );
        self.state.android_state_mut().renderer = None;
    }
@@ -557,10 +1019,19 @@ impl<State: AndroidAppState> AccessibilityNodeProvider for IrisViewPeer<State> {
 /// `register_view_class`, which wants a plain function pointer) -- see
 /// `iris/android-app/src/lib.rs`.
 pub fn new_peer<'local, State: AndroidAppState>(
-    env: JNIEnv<'local>,
+    mut env: JNIEnv<'local>,
    view: View<'local>,
-    _context: Context<'local>,
+    context: Context<'local>,
 ) -> android_view::jni::sys::jlong {
    // `DisplayMetrics.density` -- physical pixels per dp on this device.
    // Read once here, at the one point in this file already handed a
    // `Context`, and carried on `AndroidUiState` from then on (see
    // `content_scale`'s field comment for what depends on it).
    let content_scale = context
        .resources(&mut env)
        .display_metrics(&mut env)
        .density(&mut env);
    log::info!("iris: new_peer content_scale={content_scale}");
    let vm = env.get_java_vm().unwrap();
    let global_view = env.new_global_ref(&view.0).unwrap();
    let redraw: Arc<dyn RequestRedraw> = Arc::new(AndroidRedrawHandle::new(vm, global_view));
@@ -572,17 +1043,25 @@ pub fn new_peer<'local, State: AndroidAppState>(
        state: Default::default(),
        _state: PhantomData,
    };
    // See `TextData::density`'s field doc for why this is set alongside
    // `render.set_density` below rather than read from there.
    rsc.ui.text.density = content_scale;
    let shared = Rc::new(RefCell::new(Shared::default()));
-    let ui_state = AndroidUiState::new(shared.clone());
+    let ui_state = AndroidUiState::new(shared.clone(), content_scale);
    let mut state = State::new(ui_state, &mut rsc);
    let platform_vm = env.get_java_vm().unwrap();
    let platform_view = env.new_global_ref(&view.0).unwrap();
    state.platform_ready(&mut rsc, platform_vm, platform_view);
    let mut render = UiRenderState::new();
    // Every `Len::dp` in the tree resolves against this from now on -- see
    // `UiRenderState::density`'s field doc and `Len::dp`'s.
    render.set_density(content_scale);
    let peer = IrisViewPeer {
        rsc,
-        render: UiRenderState::new(),
+        render,
        state,
        task_recv,
        input_clock: None,
    };
    let id = android_view::register_view_peer(peer);
    super::insets::register(id, shared);
@@ -18,10 +18,22 @@ pub trait FocusHost {
    /// side effect the way a real double-click timer does.
    fn recent_click(&mut self) -> bool;
    fn set_focus(&mut self, id: Option<WeakWidget<TextEdit>>);
-    /// Called after a `TextEdit` becomes the focus target, with the region
+    /// Called on every tap that should put the IME on `id`: the tap that
-    /// it was hit in (`None` when the widget could not be located, which
+    /// *makes* a `TextEdit` the focus target, and any later tap on one that
-    /// happens for one it was just deselected from).
+    /// already is. `region` is where it was hit (`None` when the widget
    /// could not be located, which happens for one it was just deselected
    /// from). Implementations must be idempotent -- both backends' calls
    /// (`showSoftInput`, `set_ime_cursor_area`) already are, which is what
    /// lets the repeat tap be handled by the same call rather than by a
    /// second "re-show" entry point beside it.
    fn focus_gained(&mut self, region: Option<PixelRegion>);
    /// Whether `id` is the current focus target -- what [`select`] uses to
    /// tell a fresh press (which must wait to see whether it becomes a tap
    /// or a drag before focusing/showing the IME, Iris 2026-09-06: "if I
    /// swipe over the input bar it brings up the keyboard") from a drag
    /// continuing inside a field that was already focused (an ordinary
    /// drag-to-select, unaffected).
    fn is_focused(&self, id: WeakWidget<TextEdit>) -> bool;
 }
 /// Helper shared by every `FocusHost` impl, so the double-click window is
@@ -33,6 +45,17 @@ pub fn recent_click(last_click: &mut Instant) -> bool {
    recent
 }
 /// `PressStart`/`Pressing`/`PressEnd`, all for the left button -- what
 /// [`Selector`]/[`Selectable`] register instead of [`CursorSense::
 /// click_or_drag`], so their shared handler (`on_press`, below) sees every
 /// frame of a gesture and can tell a completed tap from a drag itself,
 /// rather than reacting to `PressStart` alone the way `click_or_drag`'s
 /// consumer used to (Iris, 2026-09-06: "if I swipe over the input bar it
 /// brings up the keyboard").
 fn press_track() -> CursorSenses {
    CursorSense::click() | CursorSense::Pressing(CursorButton::Left) | CursorSense::unclick()
 }
 pub struct Selector;
 impl<Rsc: HasEvents, W: Widget + 'static> WidgetAttr<Rsc, W> for Selector
@@ -42,7 +65,7 @@ where
    type Input = WeakWidget<TextEdit>;
    fn run(rsc: &mut Rsc, container: WeakWidget<W>, id: Self::Input) {
-        rsc.register_event(container, CursorSense::click_or_drag(), move |ctx, rsc| {
+        rsc.register_event(container, press_track(), move |ctx, rsc| {
            let region = ctx.data.render.window_region(&id, &*rsc).unwrap();
            let id_pos = region.top_left;
            let container_pos = ctx
@@ -53,14 +76,14 @@ where
                .top_left;
            let pos = ctx.data.pos + container_pos - id_pos;
            let size = region.size();
-            select(
+            on_press(
                rsc,
                ctx.data.render,
                ctx.state,
                id,
                pos,
                size,
-                ctx.data.sense.is_dragging(),
+                ctx.data.sense,
            );
        });
    }
@@ -75,31 +98,122 @@ where
    type Input = ();
    fn run(rsc: &mut Rsc, id: WeakWidget<TextEdit>, _: Self::Input) {
-        rsc.register_event(id, CursorSense::click_or_drag(), move |ctx, rsc| {
+        rsc.register_event(id, press_track(), move |ctx, rsc| {
-            select(
+            on_press(
                rsc,
                ctx.data.render,
                ctx.state,
                id,
                ctx.data.pos,
                ctx.data.size,
-                ctx.data.sense.is_dragging(),
+                ctx.data.sense,
            );
        });
    }
 }
-fn select(
+/// One press-track frame (`PressStart`, `Pressing` or `PressEnd`) over a
 /// selectable field. A field that is *already* focused behaves exactly as
 /// `click_or_drag` always did -- every frame updates the selection, which
 /// is what lets a finger already inside a focused field drag out a
 /// selection. A field that is **not** focused withholds `select`'s
 /// focus-granting side effects (and so the platform-specific `focus_gained`
 /// that shows the keyboard) until the press resolves as a tap: `PressEnd`
 /// with no frame in between having moved past [`DRAG_SLOP`] from where the
 /// press began. A drag recognised before release simply cancels the
 /// pending tap and does nothing further here -- it is not consumed, so
 /// whatever is behind the field (a list to pan) still sees every frame of
 /// it, the same as a drag that never touched a selectable field at all.
 fn on_press(
    rsc: &mut impl UiRsc,
    render: &UiRenderState,
    state: &mut impl FocusHost,
    id: WeakWidget<TextEdit>,
    pos: Vec2,
    size: Vec2,
-    dragging: bool,
+    sense: CursorSense,
 ) {
-    let recent = state.recent_click();
+    if state.is_focused(id) {
-    id.edit(rsc).select(pos, size, dragging, recent);
+        // Already focused, so there is no keyboard to withhold -- but a
-    state.set_focus(Some(id));
+        // vertical drag still is not a selection. Android's own `EditText`
-    state.focus_gained(render.window_region(&id, &*rsc));
+        // scrolls its overflowed text on a vertical drag and starts a
        // selection only from a long press; a scroll area wrapping this
        // field (`Scroll::drag`) is what actually pans, and it needs the
        // first frames of the gesture not to have selected anything behind
        // it before it crosses `DRAG_SLOP` and takes pointer capture.
        // `press_origin` carries the same meaning here as in the unfocused
        // branch below -- "this gesture is still eligible", cleared the
        // moment it becomes a drag -- so there is one flag, not two.
        match sense {
            CursorSense::PressStart(_) => {
                let recent = state.recent_click();
                id.edit(rsc).text.press_origin = Some(pos);
                id.edit(rsc).select(pos, size, false, recent);
            }
            CursorSense::Pressing(_) | CursorSense::PressEnd(_) => {
                let mut ctx = id.edit(rsc);
                let Some(origin) = ctx.text.press_origin else {
                    return;
                };
                let (dx, dy) = (pos.x - origin.x, pos.y - origin.y);
                if dy.abs() > DRAG_SLOP && dy.abs() >= dx.abs() {
                    ctx.text.press_origin = None;
                    return;
                }
                let ended = matches!(sense, CursorSense::PressEnd(_));
                if ended {
                    ctx.text.press_origin = None;
                }
                ctx.select(pos, size, true, false);
                // A tap on a field that is *already* focused asks for the
                // keyboard again (Iris's phone, 2026-09-06: "I can't reopen
                // keyboard by tapping on message box after it already
                // happened once"). Dismissing the IME -- back gesture, or
                // its own hide button -- takes the keyboard away but leaves
                // the field focused, so without this the one branch that
                // requests it (the unfocused one below) never runs again
                // and the field is permanently unable to summon it.
                // Android's own `EditText` does exactly this: every tap on
                // a focused field calls `showSoftInput`, which is a no-op
                // when the keyboard is already up.
                //
                // Gated on the same tap-vs-drag test the unfocused branch
                // uses, not on `PressEnd` alone, so a drag-to-select that
                // happens to finish inside the field does not summon a
                // keyboard the reader was not asking for.
                if ended && dx.abs() <= DRAG_SLOP && dy.abs() <= DRAG_SLOP {
                    state.focus_gained(render.window_region(&id, &*rsc));
                }
            }
            _ => {}
        }
        return;
    }
    match sense {
        CursorSense::PressStart(_) => {
            id.edit(rsc).text.press_origin = Some(pos);
        }
        CursorSense::Pressing(_) => {
            let ctx = id.edit(rsc);
            if let Some(origin) = ctx.text.press_origin
                && ((pos.x - origin.x).abs() > DRAG_SLOP || (pos.y - origin.y).abs() > DRAG_SLOP)
            {
                // Past the slop before release: this is a drag, not a tap
                // -- give up the pending focus rather than granting it once
                // the finger lifts wherever it happens to be by then.
                ctx.text.press_origin = None;
            }
        }
        CursorSense::PressEnd(_) => {
            let was_tap = id.edit(rsc).text.press_origin.take().is_some();
            if was_tap {
                let recent = state.recent_click();
                id.edit(rsc).select(pos, size, false, recent);
                state.set_focus(Some(id));
                state.focus_gained(render.window_region(&id, &*rsc));
            }
        }
        _ => {}
    }
 }
@@ -1,5 +1,5 @@
 use crate::prelude::*;
-use winit::dpi::{LogicalPosition, LogicalSize};
+use winit::dpi::{PhysicalPosition, PhysicalSize};
 impl<T: HasDefaultUiState> FocusHost for T {
    fn recent_click(&mut self) -> bool {
@@ -10,13 +10,19 @@ impl<T: HasDefaultUiState> FocusHost for T {
        self.default_state_mut().focus = id;
    }
    fn is_focused(&self, id: WeakWidget<TextEdit>) -> bool {
        self.default_state().focus == Some(id)
    }
    fn focus_gained(&mut self, region: Option<PixelRegion>) {
        let state = self.default_state_mut();
        let Some(region) = region else { return };
        state.window.set_ime_allowed(true);
        // Physical, like everything else this backend hands winit --
        // `default::content_scale`.
        state.window.set_ime_cursor_area(
-            LogicalPosition::<f32>::from(region.top_left.tuple()),
+            PhysicalPosition::<f32>::from(region.top_left.tuple()),
-            LogicalSize::<f32>::from(region.size().tuple()),
+            PhysicalSize::<f32>::from(region.size().tuple()),
        );
    }
 }
@@ -1,4 +1,10 @@
 // `CursorState::time` is the sample's own time on every backend. winit
 // carries no timestamp on a pointer event, so the moment it is handed to
 // us is the closest measurement available here -- which is also what the
 // drag code used to do for itself with `Instant::now()`, before Android's
 // batched samples made the difference matter (see `sense::CursorState`).
 use crate::prelude::*;
 use std::time::Instant;
 use winit::{
    event::{MouseButton, MouseScrollDelta, WindowEvent},
    keyboard::{Key, NamedKey},
@@ -11,13 +17,19 @@ pub struct Input {
 }
 impl Input {
    /// winit's pointer coordinates are physical pixels, which is the
    /// space the whole tree is laid out and hit-tested in -- see
    /// `default::content_scale`. Nothing is converted here; `dp(...)`
    /// resolves against the density at layout time instead.
    pub fn event(&mut self, event: &WindowEvent) -> bool {
        match event {
            WindowEvent::CursorMoved { position, .. } => {
                self.cursor.pos = Vec2::new(position.x as f32, position.y as f32);
                self.cursor.exists = true;
                self.cursor.time = Instant::now();
            }
            WindowEvent::MouseInput { state, button, .. } => {
                self.cursor.time = Instant::now();
                let buttons = &mut self.cursor.buttons;
                let pressed = state.is_pressed();
                match button {
@@ -37,6 +49,7 @@ impl Input {
                    delta.y = 0.0;
                }
                self.cursor.scroll_delta = delta;
                self.cursor.time = Instant::now();
            }
            WindowEvent::CursorLeft { .. } => {
                self.cursor.exists = false;
@@ -67,9 +80,12 @@ impl Input {
 }
 impl DefaultUiState {
    /// Physical pixels, matching `WindowEvent::Resized` (what
    /// `UiRenderState::resize` is given) and the swapchain -- see
    /// `default::content_scale`.
    pub fn window_size(&self) -> Vec2 {
        let size = self.renderer.window().inner_size();
-        (size.width, size.height).into()
+        Vec2::new(size.width as f32, size.height as f32)
    }
    pub fn cursor_state(&self) -> &CursorState {
@@ -15,6 +15,7 @@ mod access;
 mod app;
 mod attr;
 mod input;
 mod platform;
 mod render;
 pub use access::*;
@@ -24,6 +25,38 @@ pub use render::*;
 pub type Proxy<Event> = EventLoopProxy<Event>;
 /// The desktop's `content_scale`: physical pixels per dp, the same
 /// quantity Android reads from `DisplayMetrics.density` and feeds to
 /// `UiRenderState::set_density` (`android::view::AndroidUiState::
 /// content_scale`'s field comment). Everything in this backend is
 /// physical pixels -- the window size, the pointer, the widget tree --
 /// and `dp(...)` is what resolves against this at layout time, exactly
 /// as on the phone. That is a correction from an earlier version that
 /// divided winit's coordinates into a separate "logical" space instead:
 /// it left `UiRenderState::resize` (physical, from `WindowEvent::
 /// Resized`) and the window uniform (logical) disagreeing on any
 /// display whose scale factor is not 1.0, and it rasterised glyphs at
 /// one resolution to display them at another -- the blur the phone's own
 /// stopgap produced before `dp` existed.
 ///
 /// **`IRIS_SCALE` overrides it**, which is how a phone-shaped desktop
 /// window runs the phone's density (`run-headless.sh --phone`,
 /// docs/RUST.md's layer 2). An unparsable value is a typo in a command
 /// somebody just typed, so it says so and uses the window's own answer
 /// rather than silently laying out at the wrong density.
 pub fn content_scale(window: &Window) -> f32 {
    match std::env::var("IRIS_SCALE") {
        Err(_) => window.scale_factor() as f32,
        Ok(text) => match text.trim().parse::<f32>() {
            Ok(scale) if scale > 0.0 => scale,
            _ => {
                log::warn!("IRIS_SCALE={text:?} is not a positive number; using the window's own");
                window.scale_factor() as f32
            }
        },
    }
 }
 pub struct DefaultUiState {
    pub root: Option<StrongWidget>,
    pub renderer: UiRenderer,
@@ -213,8 +246,16 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
        window.set_visible(true);
        let default_state = DefaultUiState::new(window, access_adapter);
        let (mut rsc, task_recv) = DefaultRsc::init(default_state.window.clone());
        // Both copies of the density, set before the first widget is
        // built so text shapes at the right size on the opening frame --
        // the same pair `android::view::new_peer` sets from
        // `content_scale`. See `iris_core::TextData::density` for why the
        // shaper keeps its own.
        let scale = content_scale(default_state.window.as_ref());
        rsc.ui.text.density = scale;
        let state = State::new(default_state, &mut rsc, proxy);
-        let render = UiRenderState::new();
+        let mut render = UiRenderState::new();
        render.set_density(scale);
        Self {
            rsc,
            state,
@@ -253,6 +294,31 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
            ui_state.focus = None;
        }
        if input_changed {
            // The winit half of `iris::input` (`sense::log_input_event`'s
            // own doc): no batching here, so `historical` is always empty
            // -- winit hands one `WindowEvent` per pointer sample, unlike
            // Android's `MotionEvent`. The action is read back off the
            // buttons `Input::event` just updated, the same test
            // `GestureOutcome`'s callers already use to tell a press from a
            // release. Computed only when tracing is on, same reasoning as
            // `log_input_event` itself gating on it.
            if crate::diagnostics::trace_enabled() {
                let action = if cursor_state.buttons.left.is_start() {
                    "down"
                } else if cursor_state.buttons.left.is_end() {
                    "up"
                } else {
                    "move"
                };
                let t_ms = cursor_state.time.duration_since(render.epoch()).as_millis() as u64;
                crate::sense::log_input_event(
                    action,
                    cursor_state.pos.x,
                    cursor_state.pos.y,
                    t_ms,
                    &[],
                );
            }
            let window_size = ui_state.window_size();
            render.run_sensors(rsc, state, cursor_state, window_size);
        }
@@ -265,9 +331,24 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
        match &event {
            WindowEvent::CloseRequested => event_loop.exit(),
            WindowEvent::RedrawRequested => {
                // Before the draw, so this frame shows this instant's
                // position (`UiData::tick_animations`' own doc), and the
                // window is asked for another frame while anything is
                // still moving -- the winit half of what
                // `IrisViewPeer::render`'s `post_frame_callback` does on
                // Android. Nothing else in iris moves without an input
                // event.
                let frame_start = std::time::Instant::now();
                let animating = rsc.ui_mut().tick_animations(frame_start);
                let ui_state = state.default_state_mut();
                render.update(&ui_state.root, rsc);
                ui_state.renderer.update(&mut rsc.ui, render);
                let draw_start = std::time::Instant::now();
                ui_state.renderer.draw();
                crate::diagnostics::log_frame(render, frame_start, draw_start.elapsed(), animating);
                if animating {
                    ui_state.window.request_redraw();
                }
                // I4 (RUST.md): only produces a `TreeUpdate` when the named
                // set actually changed this frame -- see `AccessTree`'s doc
                // comment. `render` reflects the draw that just happened,
@@ -281,6 +362,22 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
                render.resize((size.width, size.height));
                ui_state.renderer.resize(size)
            }
            // Dragging the window to a display with a different scale.
            // Both copies again, the pair `new` sets at startup -- read
            // through `content_scale` rather than from the event, so
            // `IRIS_SCALE` still pins the density it was given (the
            // `--phone` window must not follow the monitor). winit sends
            // the matching `Resized` separately. Before 2026-09-07 this
            // event was unhandled, so every `dp` and every rasterised
            // glyph stayed at the density the window opened on
            // (docs/REVIEW-2026-09-07.md's R5) -- invisible on this
            // machine, where every display is 1.0.
            WindowEvent::ScaleFactorChanged { .. } => {
                let scale = content_scale(ui_state.window.as_ref());
                rsc.ui.text.density = scale;
                render.set_density(scale);
                ui_state.window.request_redraw();
            }
            WindowEvent::KeyboardInput { event, .. } => {
                if let Some(sel) = ui_state.focus
                    && event.state.is_pressed()