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

# Conflicts:
#	IRIS.md
#	RUST.md

.cargo/config.toml

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

.dev-updater.ron

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

.gitignore

@@ -33,3 +33,10 @@ sessions/
 # iris, the in-house UI library, is vendored at iris/ and built by cargo.
 iris/target/
 iris/android-app/target/
+
+# E5's packaging xtask (RUST.md). `build/` above already covers
+# xtask/build/outputs/apk (the published APK, see apk.rs's module doc).
+# The repo root has no Cargo workspace, so this is xtask's own
+# intermediate working files (target/xtask/apk/...), not a shared one.
+xtask/target/
+/target/

CLIENT_CORE.md

@@ -26,6 +26,7 @@ next (a Masonry or iris transcript screen, most likely).
 | `api.rs`                                  | `Api.kt`                                  | Partial -- see below |
 | `event_stream.rs`                         | `EventStream.kt`                          | Done |
 | `transcript_fold.rs`                      | `TranscriptItems.kt`, `ToolRows.kt`       | Partial -- see below |
+| `config.rs`                                | `ServerConfig.kt`'s `handleEnrollment`   | New, desktop-only so far -- see below |
 | *(not started)*                           | `TranscriptSource.kt`                     | Not started |
 | *(not ported, and may never be)*          | `TranscriptUnits.kt`                      | Out of scope -- see below |
 
@@ -103,6 +104,21 @@ deciding how `event_model` itself represents "a shape I don't recognise"
 -- a shared-model decision affecting `server/` too, not a `client-core`-only
 fix, so it is recorded here rather than silently worked around.
 
+## `config.rs`: `EnrolledServer`
+
+`EnrolledServer` (host, port, bearer token) plus `parse_link`, which reads
+the exact `aiapp://enroll?host=H&port=P&token=T` deep link
+`wg-app-link`'s `enroll` mints and `ServerConfig.kt`'s `handleEnrollment`
+parses on the phone -- so any Rust client enrols from the same text a
+phone would scan as a QR, with no second format invented for it (RUST.md's
+E4, DECISIONS.md 2026-09-05). Deliberately does not decide where it is
+persisted or under what file permissions -- a phone seals its token in the
+Android Keystore, `iris/desktop-app/src/config.rs` writes it to
+`$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json` at 0600 -- since that is
+caller-specific (the code rules' "ask for the least you need"). Its only
+caller today is `desktop-app`; a future Android build of this crate would
+be a second one, not a reason to move the type.
+
 ## What is not started at all
 
 - **`TranscriptSource.kt`** -- the layer that decides whether a page comes

DECISIONS.md

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

IRIS.md

@@ -8,6 +8,143 @@ capability that moved. Small and trivial changes do not go here.
 An entry gives the date, what changed, why, and a short before/after where
 it helps judge the change without the session that made it. Newest first.
 
+## 2026-09-05: `transcript_ui::build_tree` (RUST.md's E4)
+
+`transcript_ui::build` claimed the whole window (`ui_state.set_root(tree)`)
+as its last step, which is right for a window that *is* the transcript
+screen (the winit example, an eventual Android cdylib) and wrong for the
+desktop app, which puts a session list beside it. `build_tree` is `build`
+minus that last step: it returns `(TranscriptScreen, StrongWidget)` instead
+of just `TranscriptScreen`, and the caller decides where the tree goes —
+into `ui_state.set_root`, or into a `WidgetPtr` alongside something else
+(`iris/desktop-app`'s `rebuild_transcript`). `build` is now one line calling
+`build_tree` and doing the `set_root` itself, so existing callers are
+unaffected.
+
+```rust
+// before, and still available, for a caller that wants to *be* the window:
+let screen = transcript_ui::build(rsc, &mut ui_state, rows);
+
+// new, for a caller embedding the screen beside something else:
+let (screen, tree) = transcript_ui::build_tree(rsc, rows);
+some_widget_ptr(rsc).set(tree);
+```
+
+
+## 2026-09-05: `DragArbiter`, pan-vs-select for one shared touch gesture (RUST.md's I5)
+
+New public type, `iris::sense::DragArbiter`. Why: a widget author who
+registers both a list-level pan and a row-level drag-to-select on the same
+touch gesture has no way to arbitrate between them — `core/src/sense.rs`'s
+`run_sensors` always gives the innermost layer first refusal, so the inner
+one wins every frame it is pressed, not just the frame the press started
+(this is exactly what left transcript-ui's touch-drag panning unreachable
+until now). `DragArbiter` is one small state machine, one instance per
+gesture surface (a whole list, not per row), that a caller drives with its
+own `press_start`/`update`/`release` calls and a caller-supplied `Instant`
+(so it is unit-testable without a real clock or a render harness). It
+decides the way Android itself does: an ordinary vertical drag pans
+immediately; a stationary press held `LONG_PRESS` (500ms) starts a
+selection, which any further drag then extends; a horizontal drag while
+something is already selected extends it immediately, skipping the wait.
+
+```rust
+// One per list, held alongside whatever state coordinates the rows:
+let mut arbiter = DragArbiter::new();
+
+// On press-down:
+arbiter.press_start(pos, Instant::now(), already_selected);
+// Every frame the button/finger stays down:
+match arbiter.update(pos, Instant::now()) {
+    DragOutcome::Pan(dy) => list.scroll(-dy),
+    DragOutcome::SelectStart => selection.begin(...),
+    DragOutcome::SelectExtend => selection.extend(...),
+    DragOutcome::Undecided => {}
+}
+// On release:
+arbiter.release();
+```
+
+`transcript-ui`'s `Selection::drag` (`transcript-ui/src/selection.rs`) is
+the reference caller: every row's `CursorSense::click_or_drag() |
+CursorSense::unclick()` handler routes through one `Selection`-owned
+arbiter instead of calling `begin`/`extend` directly, so a drag that starts
+on a row's own rendered text now pans the list correctly instead of
+always starting a selection. 8 new unit tests in `iris/src/sense.rs`'s
+`drag_arbiter_tests` module.
+
+## 2026-09-05: `SpanStyle`, per-range text styling (RUST.md's I5)
+
+A `TextBuffer` used to have exactly one style (`TextAttrs`: colour, size,
+family, ...) for its whole string, applied via `push_default` into parley's
+ranged builder. `SpanStyle` is a second, optional layer: a byte range plus
+whichever of colour/family/font size/bold/italic/underline it overrides,
+pushed with parley's own `push(property, range)` instead. Why: a transcript
+row's markdown (a heading, **bold**, `inline code`, a link) all inside one
+wrapped paragraph needs each to carry its own look while the paragraph
+still wraps and selects as a single buffer — the thing `masonry`'s
+`TextArea` cannot do (`StyleSet` is one style for the whole editor,
+`text_area.rs:43-44`'s `// TODO: RichTextInput`), and the reason this
+existed at all.
+
+```rust
+let (text, spans) = transcript_ui::markdown::render_markdown(src, 16.0);
+wtext(text)
+    .spans(spans)   // new: TextBuilder::spans, on both Text and TextEdit
+    .editable(EditMode::MultiLine)
+    .add(rsc);
+```
+
+Two things a widget author should know before reaching for it:
+
+- **Call `.spans()` before or after `.editable()`, both work** — the field
+  lives on `TextBuilder` itself, not either output type, and both
+  `TextOutput::run` and `TextEditOutput::run` apply it to the buffer via
+  `TextBuffer::set_spans`. **These two call sites are a pair**: adding a
+  third `TextBuilderOutput` impl without also calling `set_spans` there
+  reproduces the exact bug this box shipped once already (spans silently
+  dropped for `TextEdit`, found only by screenshotting, not by any test —
+  `markdown.rs`'s own unit tests check string/range logic, which is
+  correct in isolation and proves nothing about whether the render path
+  ever sees it).
+- **Colour is now per-glyph, not per-buffer.** `PlacedGlyph` gained a
+  `color: UiColor` field (from parley's own per-run `Style::brush`), and
+  `Painter::glyphs` draws each glyph in its own colour instead of
+  `RenderedText::color` uniformly. `RenderedText::color` still exists (the
+  buffer's *base* colour, for a caller that wants it as a whole, e.g. to
+  tint a cursor) but no longer drives what a glyph actually renders as.
+
+## 2026-09-05: accessibility names via AccessKit (RUST.md's I4)
+
+`.label()` (already in `trait_fns.rs`, previously unused anywhere in-tree)
+is now load-bearing: it's the one thing that puts a widget in the AccessKit
+tree `iris_core::ui::access::AccessTree` builds and both backends push
+out. A widget author who wants a control to be findable by name (and
+tappable by name, through `ui-trace`/a real screen reader) calls `.label()`
+on it; nothing else is required, and a widget nobody labels is invisible
+to this system at zero cost, not just zero UI.
+
+```rust
+let button = rect(Color::LIME)
+    .on(CursorSense::click(), move |_, rsc| { ... })
+    .label("Add task");   // now findable by uiautomator/AccessKit as "Add task"
+```
+
+Two new things a widget author might touch directly:
+
+- **`Widget::access_role(&self) -> accesskit::Role`**, default `Unknown`.
+  Override it if your widget has a real platform equivalent —
+  `TextEdit` now returns `TextInput`/`MultilineTextInput` by `EditMode`.
+  Only consulted for a widget that also has a `.label()`; an unlabelled
+  widget's `access_role` is never called.
+- **`Widgets::named() -> impl Iterator<Item = WidgetId>`** — every widget
+  with an explicit label, for anything else that wants to walk the same
+  set `AccessTree` does.
+
+Nothing about `Painter`, `draw`, or the layout/move machinery changed —
+this sits entirely beside them, reading `resolved_region`'s output rather
+than participating in producing it.
+
 ## 2026-09-05: `List`, a virtualised bottom-anchored list (RUST.md's I3)
 
 A new widget, `iris::widget::List` (`iris/src/widget/list.rs` -- read its

IRIS_TODO.md

@@ -170,6 +170,62 @@ order and what "done" looks like. Tick and date them in place.
   behave as designed; its *append* half did not, until the fix above moved
   masks/move_offsets out of the per-image bind group — now flat at O(1)
   the same way (b) and (c) are.
+
+- **I5's transcript screen (`iris/transcript-ui/`, 2026-09-05) — what it
+  left, each recorded at the point in the code it would go rather than
+  silently dropped. See RUST.md's I5 box for the full account of what
+  *was* built (the screen, `SpanStyle`, cross-row selection, the growing
+  composer).**
+  - [ ] **Android integration for this screen does not exist yet.** No
+    cdylib/Gradle shell the way `iris-android-app` wraps `tabs-ui` (I2),
+    so `transcript-bench.sh`'s render-number pass condition against the
+    Compose baseline cannot be run. Needs: real `client-core::ApiClient`/
+    `event_stream::follow_session_events` wiring against
+    `app/ui-sandbox.sh --delay` (this crate deliberately fetches nothing
+    itself, `transcript-ui/src/lib.rs`'s doc), a new cdylib + Gradle
+    module, then the bench script pointed at it.
+  - [x] **Touch-drag panning over a row's own rendered text — done,
+    2026-09-05.** `row.rs` used to register `CursorSense::click_or_drag()`
+    on each row's `TextEdit` for cross-row selection; `TextEdit::draw`'s
+    `painter.child_layer()` (`iris/src/widget/text/edit.rs:87`) meant that
+    registration won `core/src/sense.rs::run_sensors`'s per-layer
+    arbitration on every frame it was pressed, not just the frame the
+    press started, so a list pan gesture registered on `List` itself never
+    got a turn while a row was under the finger. Fixed with
+    `iris::sense::DragArbiter` (recorded in `IRIS.md`), one small state
+    machine per list deciding pan vs. select the way Android does (a
+    vertical drag pans immediately; a stationary press held `LONG_PRESS`
+    (500ms) starts a selection which further drag extends; a horizontal
+    drag while something is already selected extends immediately) —
+    `transcript-ui/src/selection.rs`'s `Selection::drag` is the one place
+    every row's drag now routes through. 8 new unit tests
+    (`iris/src/sense.rs`'s `drag_arbiter_tests`); `cargo fmt/clippy/test
+    --workspace` and `cargo ndk` (both `iris` and `transcript-ui`) all
+    clean; `run-headless.sh` screenshot byte-identical to before the
+    change (38578 bytes). See RUST.md's I5 box, "Gap closed, 2026-09-05".
+  - [ ] **Row-level accessibility names.** The composer carries
+    `.label("Message")`; transcript rows do not carry a `.label()` of
+    their own yet, so `Widgets::named()` (I4) does not include them —
+    `row.rs`'s `build_text_row` is where one would go, keyed to something
+    stable per row (its sender + a short excerpt, matching what a screen
+    reader announcing a chat message would say).
+  - [ ] **A tappable link and a background chip behind inline code.**
+    Both need per-range glyph geometry that `TextEditCtx` does not expose
+    outside `iris::widget::text` (`edit.rs`'s `layout()` helper is
+    private) — see `markdown.rs`'s module doc for the exact shape the fix
+    would take (the same primitive `TextEdit::draw`'s own selection
+    highlight already uses internally,
+    `iris/src/widget/text/edit.rs:99`).
+  - [ ] **`Selection`'s anchor-row shortcut.** The row a drag started in
+    is selected in full (`select_all`) the moment the drag leaves it,
+    rather than "from the click point to whichever edge points away from
+    the drag" — needs the same private `layout()` access as the item
+    above. `selection.rs`'s module doc has the exact reasoning.
+  - [ ] **No syntax highlighting inside a fenced code block.**
+    `client_core::highlight` exists (built for the file explorer) and
+    could feed per-token `SpanStyle`s into a code block's span; wiring it
+    in was not attempted this pass.
+
 - [ ] **Masks defined relative to each other.** Wanted: mask A multiplies
   by something *and also* applies mask B — a mask can reference a parent
   mask, the way the move chain references a parent offset. Today masks

RUST.md

@@ -36,13 +36,69 @@ session spending an afternoon on them again.
 
 ## Where things stand (2026-09-05)
 
+- **Both of the previous note's in-flight pieces are now done, 2026-09-05.**
+  Design choices for both are summarised in `DECISIONS.md` at the repo
+  root, which is the file Iris reads for choices made without her. Next:
+  I5's Android integration and the bench numbers.
+- **E4 done, 2026-09-05.** `iris/desktop-app`: a winit window with a
+  session list beside `transcript-ui`'s screen (`build_tree`), against a
+  real `ai-server` through `client-core`, enrolled from the same
+  `aiapp://enroll?...` link a phone scans. Both pass conditions held on
+  `app/ui-sandbox.sh` -- see E4's own box for the commands, the
+  screenshot, and a real streaming-duplication bug the screenshot found
+  and a regression test now covers.
+- **The I5 touch-drag pan-vs-select gap is closed, 2026-09-05**, as a
+  `DragArbiter` in `iris/src/sense.rs` wired into `transcript-ui`'s
+  selection -- see I5's own box below, "Gap closed, 2026-09-05".
 - **Done**: E0 (toolchain), E1 (Masonry on android-view, which found the
   keyboard gap — now explained, see below), E2 (a transcript in Masonry,
   which found that Masonry has no touch-scroll on Android at all — see
-  below), **E3 (the Kotlin/Java shell over a JNI bridge into Rust, both
+  below), E3 (the Kotlin/Java shell over a JNI bridge into Rust, both
-  pass conditions proved on the emulator — see its own box)**, I0a, I0b
+  pass conditions proved on the emulator — see its own box), E5 (the
-  (iris builds on a pinned nightly and runs), I1 (parley + glyph atlas),
+  Gradle-free packaging xtask, both pass conditions proved — see its own
-  I2 (iris on android-view).
+  box), I0a, I0b (iris builds on a pinned nightly and runs), I1 (parley +
+  glyph atlas), I2 (iris on android-view), I3 (`iris::widget::List`), I4
+  (host half).
+- **E5 done, 2026-09-05.** `cargo xtask apk` (new `xtask/` crate at the
+  repo root, zero dependencies) replaces Gradle for packaging
+  `app/shellApp`: `cargo ndk` → `javac`/`d8` → `aapt2` → `zipalign` →
+  `apksigner`, signed with the same key `app/build-apk.sh` uses. Both pass
+  conditions held on this checkout's emulator: `adb install -r` over the
+  Gradle-built `shellApp` succeeded (same key, so the signatures matched),
+  and the notification service reached its follow-loop and posted a real
+  notification while the app was backgrounded. E3's open `kotlinc`
+  question resolved itself as a side effect of the one Gradle call still
+  needed for AndroidX dependency resolution — see E5's own box for the
+  full account, including the one disclosed place Gradle still runs and
+  what was deliberately left undone (a real-device `arm64-v8a` install,
+  dex shrinking).
+- **I5 — the transcript screen in iris: partial, 2026-09-05 (ticked `[~]`
+  in its own box, not `[x]`).** `iris/transcript-ui/` builds a real
+  transcript screen — markdown-folded rows in `iris::widget::List`,
+  cross-row selection, a growing composer, tool-row expand-hold — on top
+  of a new, genuinely useful iris capability this box added:
+  **`SpanStyle`**, per-range text styling (`core/src/primitive/text.rs`),
+  which is what lets one wrapped, selectable `TextEdit` carry a heading,
+  bold, italic, inline code and a link all inside the same paragraph —
+  exactly the inline-rich-text ceiling E2 found Masonry structurally
+  unable to cross. Screenshotted via `run-headless.sh` (real inline
+  styling visible, not just block-level). 9 new tests, all passing;
+  `cargo build/clippy/fmt/test --workspace` and `cargo ndk` (both `iris`
+  and `transcript-ui`) all clean. **What did not happen this pass**: any
+  Android integration for this specific screen (no cdylib/Gradle shell
+  exists for it yet, unlike `tabs-ui`'s `iris-android-app`), and therefore
+  the emulator-side pass condition (`transcript-bench.sh` against the
+  Compose baseline, `ui-trace` tap-by-name on a row) — `emu list` showed
+  the one emulator here held by another session, but the real blocker is
+  that the integration work itself is unbuilt, not the emulator being
+  busy. Full accounting, every citation, and the dated IRIS_TODO.md items
+  are in I5's own box below. **Update, 2026-09-05, same day**: touch-drag
+  panning over a row's own rendered text, which was not yet reachable for
+  a specific, diagnosed reason (it competed with this box's own
+  row-level drag-select for the same gesture, not an absent primitive),
+  is now closed — a `DragArbiter` in `iris/src/sense.rs`, wired into
+  `transcript-ui`'s selection — see the box's "Gap closed" note. Android
+  integration is the one item left before this box can tick `[x]`.
 - **E3 done, 2026-09-05, and unlike E1/E2 it is committed to this repo**
   (`android-shell/` — a JNI-bridge crate on `client-core` — plus a new
   Gradle module `app/shellApp/`, left deliberately separate from
@@ -61,6 +117,20 @@ session spending an afternoon on them again.
   box for the full account, the exact commands, and what was deliberately
   cut (attachment uploads, a session picker, the on-screen/banner
   suppression — all pending E4's screen).
+- **I4 — accessibility names via AccessKit: host half done and verified
+  2026-09-05, ticked in the box below.** `iris_core::ui::access::AccessTree`
+  builds one flat AccessKit tree from `Widgets::named()` (a side set only
+  `.label()` populates, so an unnamed widget costs this nothing), pushed
+  through `accesskit_winit` on the desktop and `accesskit_android` on
+  Android, updated only when a name/role/bounds actually changes (a
+  counter confirms it: 1 rebuild on first draw, 0 across an unchanged
+  frame, 1 more after a real move). E1's detach-abort mitigation is
+  carried (`android/access.rs`'s `raise_if_enabled`). Every check that
+  doesn't need the emulator is clean — see I4's own box for the exact
+  numbers. **What's left**: the emulator itself is held by another session
+  this pass, so `ui-trace record --do "tap 'pad'"` against
+  `iris-android-app`'s tabs screen (which now has five named buttons) has
+  not been run for real yet — exact commands at the bottom of I4's box.
 - **E2 done, 2026-09-05, and its headline finding changes what "decide
   from the measurements" (recommendation item 3) can mean right now.**
   Built a real transcript screen (`~/src/android-view/e2-transcript`,
@@ -577,6 +647,25 @@ light" has a knob inside the same stack.
    carries the screen within the Compose baseline, it is the app's
    framework and Masonry was the calibration. If it does not, the
    measurement says which parts of Masonry to adopt underneath it.
+
+   **Not decidable yet, 2026-09-05 — what's missing, named rather than
+   guessed at.** Neither side of this comparison has a render number:
+   E2 found Masonry's own scroll gesture path absent on Android
+   entirely (its box, "measurable frames"), and I5 built the iris side of
+   the screen (`iris/transcript-ui/`) but not the Android integration
+   around it — no cdylib/Gradle shell exists for this screen yet (unlike
+   `tabs-ui`'s `iris-android-app`, I2), so there is nothing installed on a
+   device for `transcript-bench.sh` to measure against the Compose
+   baseline. What would close this: build that integration (real
+   `client-core` networking against `app/ui-sandbox.sh --delay`, a cdylib
+   + Gradle module the way I2 did for `tabs-ui`), then run
+   `transcript-bench.sh`'s gesture on both. Until then, the decision rests
+   on the structural findings both sides *did* produce: Masonry cannot do
+   cross-row selection or per-span inline rich text at all today (E2's
+   `grep -rln`, zero hits, cited in its own box), and iris now does both
+   (I5's `SpanStyle` and `selection.rs`) as well as programmatic
+   touch-scroll (I3) — three structural points in iris's favour with no
+   opposing measurement yet on either side.
 4. Then the shell (E3), the desktop window (E4) and the packaging (E5),
    which do not depend on the choice.
 
@@ -1219,30 +1308,281 @@ accepted.
         errors."}` followed by the echo driver's reply -- the share
         reached the most-recently-active session as a real message, not
         a mock.
-- [ ] **E4 — the same screen on the desktop** in a winit window, from the
+- [x] **E4 — the same screen on the desktop (2026-09-05).** A new
-      same crate, with only the layout differing.
+      `iris/desktop-app` crate (added to the `iris` workspace's members, not
-- [ ] **E5 — the packaging xtask**: `cargo ndk` → `javac`/`d8` → `aapt2`
+      excluded the way `android-app` is -- nothing here needs the NDK):
-      → `zipalign` → `apksigner`, signed with the existing release key,
+      a real winit window showing a session list (`iris::widget::Span`,
-      installed through Dev Updater. Pass: the APK installs over the
+      rebuilt on selection) beside `transcript-ui`'s screen
-      Gradle-built one and the notification service starts.
+      (`transcript_ui::build_tree`, new this box -- see IRIS.md's
+      2026-09-05 entry), talking to a real `ai-server` through
+      `client-core`'s `ApiClient`/`UreqTransport`/`follow_session_events`.
+      Enrolment is `client_core::config::EnrolledServer::parse_link`
+      against the same `aiapp://enroll?host=H&port=P&token=T` link a phone
+      scans, pasted via `--link` and persisted at
+      `$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json` (0600 --
+      `iris/desktop-app/src/config.rs`); the pinned CA is a `--ca PATH`
+      argument, never baked in (DECISIONS.md, 2026-09-05).
 
-      **Not blocked by E3's layout**, and one thing E5 will need to
+      *Both pass-condition proofs held, against `app/ui-sandbox.sh`'s real
-      account for. `app/shellApp/`'s two Java classes and generated
+      server.* (1) The list showed the sandbox's spawned session
-      `PinnedCa.java` are plain `javac` input with no Kotlin of their own
+      ("Demo session", its live status); selecting it loaded the real
-      (`android-shell/src/settings.rs`'s doc explains why `kotlinc` still
+      transcript and the composer's `Submit` posted a message whose reply
-      appears in the graph regardless: `:link`, the shared `wg-app-link`
+      streamed in live over SSE, both proved by two `run-headless.sh`
-      submodule, is Kotlin and is a real dependency of this module, not
+      screenshots taken seconds apart around a real `./ui-sandbox.sh send`
-      something E3 introduced). `android-shell` itself builds with plain
+      -- the second showed the new turn appended under the first with
-      `cargo ndk build --release -o .../jniLibs/`, exactly the shape "Can
+      nothing duplicated or lost. (2) Screenshotted headless:
-      the APK be built without Gradle?" assumed. What E5 will actually
+      `/tmp/iris_e4_desktop.png` (1920x1200, 15.9 KB, the real first-run
-      need to solve that E3 did not: producing `:link`'s classes (or an
+      state -- list populated, "Select a session." on the right, nothing
-      equivalent Keystore-sealed-token implementation) without inflating
+      selected yet). `run-headless.sh` gained a `--bin` flag for this
-      the toolchain E5 is trying to shrink -- either accept `kotlinc` for
+      (`cargo build --bin NAME` + `target/debug/NAME` instead of the
-      that one shared submodule, prebuild it once into a jar/aar E5
+      `--example` path, since `desktop-app` is a real binary a person
-      consumes as a binary input, or reimplement the Keystore sealing in
+      runs, not a demo) and `$RUN_HEADLESS_ARGS`, word-split into the
-      Rust after all (rejected in E3 for reuse and phone-compatibility
+      launched binary's own argv (a real CLI's flags, which no example
-      reasons, but the calculus is different once Kotlin is otherwise
+      needed a way to pass before). Exact commands, from `iris/`:
-      gone).
+
+          TOKEN=$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/ai-app/sandbox-token")
+          LINK="aiapp://enroll?host=127.0.0.1&port=<PORT>&token=$(python3 -c \
+            'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1],safe=""))' "$TOKEN")"
+          CA="${XDG_CONFIG_HOME:-$HOME/.config}/ai-app/certs/ca.pem"
+          RUN_HEADLESS_ARGS="--ca $CA --link $LINK" \
+            ./run-headless.sh desktop-app --bin --shot /tmp/iris_e4_desktop.png -- -p desktop-app
+
+      **A real bug this screenshot found, not a synthetic one**: the first
+      attempt resumed the live SSE stream from
+      `items.iter().map(TranscriptItem::seq).max()` -- the *folded* item's
+      seq, which for a still-open `AssistantMsg` is the seq of its
+      *first* delta by design (`fold_event`'s own doc comment: "a row
+      whose identity changed with every delta would be a new row every
+      frame"). Resuming from there re-delivered every delta already
+      folded into that message, and the screenshot showed the assistant's
+      reply with its own tail duplicated ("You said: ... testsaid: ...
+      test"). Fixed by computing the resume cursor from the raw wire
+      `seq` of the last fetched line (`app.rs`'s `raw_seq`) instead of
+      from any folded item -- regression test
+      `the_resume_cursor_is_the_last_wire_seq_not_the_last_items_seq` in
+      `iris/desktop-app/src/app.rs`. Exactly the class of bug CODE_RULES
+      warns about under "a fix tried only on what it was meant to fix":
+      the bare REST fetch (no live stream yet) looked perfect on its own,
+      and only *resuming* a stream after it exposed the seam.
+
+      **Deliberately left simple, and why** (`app.rs`'s module doc has the
+      full account): every incoming SSE event refolds the session's whole
+      item list and rebuilds the entire right-hand widget tree from
+      scratch, rather than reaching for `TranscriptScreen::push_row`'s
+      incremental append -- `push_row` can only add a new row, and a
+      streaming reply is exactly a row whose text keeps changing after it
+      first appears. Fine at the size a desktop session's conversation
+      is; wrong for a long, fast-streaming one, and the real fix needs
+      `transcript-ui` to expose updating a row already on screen, which it
+      does not yet. The composer's in-progress text is saved and restored
+      across a rebuild so a reply streaming in while the reader is typing
+      a followup doesn't erase it. No history paging (I3's job, reused
+      as-is if this becomes permanent) and no scroll-position preservation
+      across a rebuild -- both named rather than silently missing.
+      Background network I/O runs on plain `std::thread`s reporting back
+      through winit's `EventLoopProxy<AppEvent>` rather than iris's own
+      `Tasks`/`task_on`, because `Tasks` only requests a redraw once after
+      its whole async closure finishes, which fits "one request, one
+      update" and not a live stream that needs a redraw after *each*
+      event it relays.
+
+      Verification: `cargo fmt --all`, `cargo clippy --workspace
+      --all-targets` (zero warnings), `cargo test --workspace` from
+      `iris/` (7 new tests in `desktop-app` -- 4 for
+      `config.rs`'s save/load/permissions/corruption, 3 for `app.rs`'s
+      transcript folding and the resume-cursor regression above -- plus
+      the existing 37 unchanged), and `./run-tests.sh` at the repo root
+      (127 passing, `client-core` alone 93 -- the `EnrolledServer` parsing
+      tests already existed before this box). Android is untouched by
+      this step, as asked.
+- [x] **E5 — the packaging xtask (2026-09-05).** Both pass-condition
+      proofs held on this checkout's own emulator: `adb install -r` of the
+      xtask-built APK over the Gradle-built one succeeded, and the
+      notification service reached its follow-loop and posted a real
+      notification while the app was backgrounded. `cargo xtask apk` at
+      the repo root (`.cargo/config.toml`'s alias for `cargo run
+      --manifest-path xtask/Cargo.toml --`) runs `cargo ndk` →
+      `javac`/`d8` → `aapt2` → `zipalign` → `apksigner` with no Gradle
+      driving the packaging itself -- one disclosed exception, below.
+
+      *Where it lives.* `xtask/` (new, independent crate at the repo
+      root -- **no Cargo workspace**, matching every other crate here;
+      `run-tests.sh` already `cd`s into each rather than assuming one).
+      **Zero dependencies**: every step is "run this SDK/JDK tool with
+      these arguments and check its exit status," which needs nothing a
+      crate would add (AGENTS.md's "new dependencies need a reason").
+      `src/sdk.rs` finds the SDK root/build-tools/`android.jar` the same
+      way `app/android-env.sh` does ($ANDROID_HOME, then
+      $ANDROID_SDK_ROOT, then `~/Android/Sdk`); `src/keystore.rs`
+      finds-or-generates the release key with the exact recipe
+      `app/build-apk.sh` uses (same env vars, same path, same `keytool`
+      invocation) so the two tools sign with the *same* key, plus a
+      `--debug` path using the conventional `~/.android/debug.keystore`;
+      `src/apk.rs` is the pipeline itself, `src/main.rs` the ~40-line CLI.
+      About 420 lines total against RUST.md's earlier "about 150" guess --
+      the difference is almost entirely dependency handling (below), which
+      the earlier estimate didn't anticipate.
+
+      *`:link`'s `kotlinc` question, resolved.* Checked first, since E3
+      left it open: no standalone `kotlinc` exists on this machine (not on
+      PATH, not under any SDK -- only `kotlin-compiler-embeddable` jars
+      inside Gradle's own distributions). So the choice was never
+      "invoke kotlinc" versus "port `ServerStore`/`ServerSettings` to
+      Java" as originally framed -- a third route fell out of solving the
+      *other* open dependency problem (androidx, next paragraph): the one
+      Gradle call already needed for that also compiles `:link`'s Kotlin
+      as a side effect, via Gradle's own embedded compiler, and hands back
+      the resulting `classes.jar` in the same resolved-jars list. That is
+      RUST.md's own "prebuild it once into a jar/aar E5 consumes as a
+      binary input" option, arrived at for free rather than built
+      specially -- no Java port of `ServerStore` was written, and
+      `android-shell/src/settings.rs`'s JNI class-by-name lookup
+      (`com/example/wgapplink/ServerStore`) needed no change.
+
+      *One disclosed exception to "no Gradle in the loop": dependency
+      resolution.* `app/shellApp` depends on `:link` (Kotlin, above) and
+      on `androidx.core:core-ktx` -- not a compile-time dependency of the
+      two Java stub classes (`MainActivity`/`NotificationService` import
+      only `android.*`), but a **runtime** one: `android-shell/src/notify.rs`
+      reaches `NotificationCompat`/`NotificationChannelCompat`/
+      `NotificationManagerCompat`/`ServiceCompat`/`ContextCompat` by class
+      name over JNI, so their bytecode has to be in the final dex even
+      though nothing in this pipeline's own Java source mentions them.
+      Reimplementing a Maven/AAR dependency resolver to avoid one Gradle
+      call was not a good trade against "smallest honest route" (the
+      standard this file already applied to `kotlinc`) -- so
+      `app/shellApp/build.gradle.kts` gained one task,
+      `printRuntimeClasspathJars`, which asks the `releaseRuntimeClasspath`
+      configuration for its artifacts through an `ArtifactView` requesting
+      the `android-classes-jar` attribute (the same post-AAR-transform
+      view AGP's own dexing task consumes, so an AAR is already unpacked
+      to a plain `.jar` by the time the xtask sees it) and writes their
+      absolute paths, one per line, to
+      `app/shellApp/build/xtask/runtime-classpath.txt`. `cargo xtask apk`
+      runs `./gradlew :shellApp:printRuntimeClasspathJars` once (a few
+      seconds, mostly UP-TO-DATE on a warm Gradle daemon), reads that file,
+      and hands every jar in it to `d8` as an ordinary program input --
+      `:link`'s `classes.jar` among them, per the paragraph above. Nothing
+      past that one call touches Gradle. **What this trades away**: the
+      pipeline is not Gradle-free end to end, only Gradle-free for the
+      part that was actually expensive (assembling and dexing the app's
+      own code, which the earlier options -- kotlinc, or a hand-rolled
+      resolver -- were the two ways to avoid entirely). Recorded here
+      rather than left implicit, matching how the `kotlinc` compromise
+      above is recorded.
+
+      *The rest of the pipeline, in order (`apk.rs`):* `cargo ndk -t
+      arm64-v8a -t x86_64 -P 26 -o app/shellApp/src/main/jniLibs/ build
+      --release -p android-shell` (both ABIs by default -- real phone and
+      this machine's emulator -- `--abi` overrides; always `--release`
+      for the native library regardless of the APK's signing variant, for
+      the reason E1 already established: a debug build's Vulkan
+      object-labelling segfaults this emulator's driver, and there is no
+      reason for a signing choice to make this crate's `.so` bigger).
+      `javac -cp android.jar` compiles `MainActivity.java`,
+      `NotificationService.java` and a freshly generated `PinnedCa.java`
+      (same template as the Gradle `generatePinnedCa` task, same
+      opening-quotes-adjacent-to-`"""` rule from AGENTS.md's "Things that
+      have bitten") into one `classes.jar` (`jar cf` -- `d8` rejects a
+      bare directory of `.class` files outright, "Unsupported source file
+      type", discovered by trying it). `d8 --release --min-api 24 --lib
+      android.jar` dexes that jar plus every classpath jar from the
+      paragraph above into one `classes.dex` (no multidex needed at this
+      size). `aapt2 link` compiles `app/shellApp/src/main/AndroidManifest.xml`
+      into the base APK's `resources.arsc` -- the checked-in manifest has
+      no `package` attribute (Gradle injects one from `android.namespace`
+      during a manifest merge this pipeline doesn't run), so `apk.rs`
+      writes a copy with `package="com.example.aiapp.shell"` spliced in
+      rather than editing the source manifest, and refuses to run at all
+      if the source ever gains one of its own (a version-drift guard
+      cheaper than a real merge). `--min-sdk-version`/`--target-sdk-version`/
+      `--version-code`/`--version-name` are passed on the command line for
+      the same reason -- the raw manifest carries none of them, Gradle's
+      `defaultConfig` normally does. `jar uf` (not a hand-rolled zip
+      writer -- `jar` ships with the JDK this pipeline already needs)
+      merges `classes.dex` and a staged `lib/<abi>/libandroid_shell.so`
+      tree into the base APK (cargo-ndk's `-o` writes
+      `jniLibs/<abi>/*.so`, matching the Gradle source-set layout it was
+      pointed at; Android's own zip convention wants `lib/<abi>/*.so` at
+      the archive root, hence the staging copy rather than an in-place
+      rename). `zipalign -f -p 4` then `apksigner sign` finish it, signed
+      with `~/.config/ai-app/release.jks` by default or
+      `~/.android/debug.keystore` under `--debug`. The signed APK is
+      copied to `xtask/build/outputs/apk/<mode>/ai-app-shell-<mode>.apk`
+      as a final step -- a Gradle-shaped path (`*/build/outputs/apk/*/*.apk`)
+      chosen so Dev Updater's fixed-pattern APK discovery
+      (`~/repos/dev-updater/server/src/discover.rs`'s `APK_PATTERNS`,
+      which has no per-component path override) finds it without any
+      change on that side; the working files above it stay under
+      `target/xtask/apk/`, an ordinary build-cache location (gitignored,
+      along with `xtask/target/`).
+
+      *Wired into `.dev-updater.ron`*: a second `Apk` component, `shell`,
+      `build: "cargo xtask apk"`, `modes: ["release", "debug"]`, no `cwd`
+      (defaults to the checkout root, which both the `cargo xtask` alias
+      and the publish path above need -- `.cargo/config.toml`'s alias
+      resolves its `--manifest-path` relative to the *invoking* working
+      directory, not to where the config file lives, which is what ruled
+      out giving this component its own `cwd`). Dev Updater's `ByMode`
+      appends the chosen mode word as the command's last argument
+      (`build-apk.sh`'s own interface, per that component's comment), so
+      `main.rs` accepts bare `release`/`debug` as well as `--release`/
+      `--debug` for typing by hand. The existing `app` component
+      (`build-apk.sh`, Gradle) is untouched.
+
+      *Verification.* `cargo fmt -- --check` and `cargo clippy
+      --all-targets` clean, zero warnings, for `xtask` (host target --
+      nothing in it is Android-specific; it *runs* `cargo ndk`, it isn't
+      cross-compiled itself). `./run-tests.sh`: 127 `server` + 88
+      `client-core` tests, unaffected, still passing. `apksigner verify
+      --print-certs` on the xtask's release output confirms a V3 signer
+      with `CN=ai-app` -- the same key `build-apk.sh` generates.
+
+      *The two pass-condition proofs*, both on this checkout's own AVD
+      (`ai-app-2`, GPU host, brought up and torn down within this
+      session):
+      - **Installs over the Gradle-built one.** Built the Gradle release
+        variant first (`AI_APP_KEYSTORE=~/.config/ai-app/release.jks
+        AI_APP_KEYSTORE_PASSWORD=$(cat
+        ~/.config/ai-app/release.jks.password) ./gradlew
+        :shellApp:assembleRelease` -- needed its own signing block added
+        to `app/shellApp/build.gradle.kts`, copied from `androidApp`'s,
+        since `shellApp` had none before this), installed it fresh
+        (`adb uninstall com.example.aiapp.shell` first -- an older debug
+        install from E3 testing was signed with a different key and
+        `install -r` over it fails loudly with
+        `INSTALL_FAILED_UPDATE_INCOMPATIBLE`, which is the correct,
+        expected failure for a mismatched key rather than a bug), then
+        `adb install -r xtask/build/outputs/apk/release/ai-app-shell-release.apk`:
+        **`Success`**.
+      - **The notification service starts.** Enrolled via
+        `adb shell "am start -a android.intent.action.VIEW -d
+        'aiappshell://enroll?host=10.0.2.2&port=<sandbox port>&token=<token>'"`,
+        force-stopped the app, then re-launched it once (enrollment calls
+        `sync()` from `MainActivity.onCreate`). `adb logcat` shows
+        `ActivityManager: Background started FGS: Allowed ... intent:
+        ... cmp=com.example.aiapp.shell/.NotificationService`, immediately
+        followed by `android-shell: jni::vm::java_vm: Attached thread
+        ai-app-notifications`, a real TLS handshake to the sandbox's
+        `10.0.2.2:<port>`, and `Response { status: 200 ... }` on
+        `/notifications`. Pressed home, spawned a sandbox session and sent
+        it `/question Should E5 proceed?`; `adb shell dumpsys notification
+        --noredact` then shows a live `NotificationRecord` for
+        `com.example.aiapp.shell`, `channel=sessions`, `tag=<session id>`
+        -- posted while the app held no visible activity, the same bar
+        E3's own proof cleared.
+
+      *Left undone, honestly.* No attempt to shrink the dex (R8/minify is
+      off, matching `shellApp`'s existing `isMinifyEnabled = false`, so
+      the APK carries the full unshrunk `androidx`/Kotlin-stdlib/coroutines
+      graph -- about 5.2 MB signed with both ABIs, most of it native
+      libraries and that dependency graph rather than this project's own
+      code). No `--abi arm64-v8a`-only real-device install was attempted
+      this session (no physical phone reachable from here); the emulator
+      proof above is `x86_64` plus a cross-compiled but unexercised
+      `arm64-v8a` `.so` in the same APK. Multidex is unneeded at today's
+      size but nothing in `dex()` checks for the 64k-method ceiling should
+      the dependency graph grow.
 
 ### The iris track
 
@@ -1772,12 +2112,399 @@ silently on real hardware.
       session screen, i.e. most of I5's work) rather than something this
       box's scope could finish alone -- recorded here rather than left
       silently undone.
-- [ ] **I4 — accessibility names via AccessKit.** Every control carries a
+- [x] **I4 — accessibility names via AccessKit, host half done and verified
-      name; `ui-trace` can find and tap it by label. Pass: `bench-lib.sh`'s
+      2026-09-05; the emulator half is the one step left, named at the
-      tap-by-name works against the iris screen unchanged.
+      bottom of this box.** Built `iris_core::ui::access::AccessTree`
-- [ ] **I5 — the transcript screen in iris.** E2's pass conditions, all
+      (`iris/core/src/ui/access.rs`) -- one flat AccessKit tree, a synthetic
-      seven behaviours, against the sandbox with `--delay`. This is the
+      `Role::Window` root with every **named** widget as a direct child.
-      point the decision in the recommendation is made at.
+      Deliberately flat rather than mirroring iris's real widget nesting:
+      nothing upstream of a named leaf needs a node, since a screen
+      reader's traversal (and uiautomator's tap-by-name, this box's own
+      pass condition) works from each node's on-screen bounds, not from
+      tree structure -- and mirroring the real tree would rebuild
+      intermediate nodes on every resize of any container above a named
+      widget, which is most frames.
+
+      **Modular the way input's sense registry is.** `Widgets` gained one
+      `HashSet<WidgetId>` (`named`), populated only by `.label()`/
+      `set_label` and drained by `free_next` (the same removal path a
+      freed id already went through -- no second bookkeeping call added
+      anywhere). `AccessTree::update` walks `widgets.named()` directly,
+      never the full widget arena, so a widget nobody named costs this
+      subsystem nothing -- not a visit, not a branch. Roles come from a
+      new `Widget::access_role(&self) -> accesskit::Role` trait method,
+      default `Unknown`; the one override so far is `TextEdit` ->
+      `TextInput`/`MultilineTextInput` by `EditMode`. Bounds come from
+      `UiRenderState::window_region`, which sits on `resolved_region`'s
+      move-chain walk -- so a widget moved via `Offset`/`Scroll` (never
+      redrawn from scratch) still reports where it actually ended up; see
+      `bounds_follow_a_moved_widget_and_updates_stay_incremental` below.
+
+      **Incremental, not per-frame.** `AccessTree` keeps the last
+      `HashMap<WidgetId, Entry>` (name, role, bounds) it sent and only
+      returns a new `TreeUpdate` -- and only then bumps its `rebuilds`
+      counter, `take_rebuilds()`'s the AccessKit twin of
+      `UiRenderState::take_counters` -- when that set actually differs.
+      Confirmed by `bounds_follow_a_moved_widget_and_updates_stay_incremental`
+      (`iris/src/access_tests.rs`): 1 rebuild on the first draw, 0 across an
+      unchanged frame, 1 more after a real move, regardless of how many
+      other widgets are on screen.
+
+      **`SlotId::as_u64`** (`core/src/util/slot.rs`) encodes a `WidgetId`
+      into accesskit's flat `NodeId(u64)`, offset by one so a real widget
+      never collides with the reserved window node (`NodeId(0)`).
+
+      **Pushed through two backends, each behind an inert action/activation
+      handler** -- see below for why inert is correct, not incomplete.
+      `default/access.rs` (winit): `accesskit_winit::Adapter`, built in
+      `DefaultApp::new` with the window created hidden
+      (`with_visible(false)`) and shown only after the adapter exists,
+      which is what that constructor requires. `process_event` runs on
+      every `WindowEvent`; `update_if_active` runs once per
+      `RedrawRequested`, after `render.update()` so bounds reflect the
+      frame just drawn. `android/access.rs` (android-view):
+      `accesskit_android::Adapter` on `AndroidUiState`, `IrisViewPeer` now
+      implements `AccessibilityNodeProvider`
+      (`create_accessibility_node_info`/`find_focus`/`perform_action`), and
+      `render()` (now taking `&mut CallbackCtx`, needed for the JNI handle
+      any `raise` requires) pushes the same `AccessTree::update` after
+      every draw.
+
+      **Why the `ActionHandler`s are empty, not a placeholder for later
+      work**: AGENTS.md's own "Driving the UI" section says it plainly --
+      `ui-trace record --do "tap 'Save'"` resolves the label against the
+      screen and performs a **real touch at that node's bounds**, the same
+      as a person's finger. It does not call into AccessKit's action
+      system at all. So once `AccessTree` reports correct bounds, the
+      ordinary pointer path (already built, already tested) is what
+      answers the tap -- there is nothing for `do_action` to do for this
+      pass condition specifically. A future real screen reader's own
+      double-tap-to-activate gesture works the same way, for the same
+      reason. If iris ever needs to answer an AccessKit `Action::Click`
+      injected without a matching touch (e.g. a switch-access scanner),
+      that is new scope, not a gap in this box.
+
+      **E1's abort mitigation, carried.** `android/access.rs`'s
+      `raise_if_enabled` is the one place `QueuedEvents::raise` may be
+      called: it asks `AccessibilityManager.isEnabled()` (a `getSystemService`
+      JNI call, since android-view has no ready-made wrapper) immediately
+      before every `raise` and drops the events instead when the answer is
+      no. Every call site (`render`'s per-frame push, `perform_action`)
+      goes through it, and each pushes it as a *deferred* callback exactly
+      like android-view's own demo, so it runs after the current JNI
+      callback has released whatever it's holding -- `raise`'s own
+      documented requirement. Not independently re-triggered on this
+      pass (that needs the emulator, see below); the mitigation is coded
+      to the exact mechanism E1 diagnosed (`sendAccessibilityEvent`
+      throwing when accessibility is off) rather than to the symptom, so
+      there is no reason to expect it behaves differently here than it did
+      there.
+
+      **Verified, 2026-09-05, host only.**
+      `cargo fmt --all -- --check`, `cargo build --workspace --all-targets`,
+      `cargo clippy --all-targets` (both plain and `--all-targets`) clean;
+      `cargo test --workspace` -- 28 tests in `iris/`, three of them new
+      (`access_tests::a_named_widget_reaches_the_tree_with_its_role_and_bounds`,
+      `::a_widget_with_no_label_never_reaches_the_tree`,
+      `::bounds_follow_a_moved_widget_and_updates_stay_incremental`).
+      `cd iris/android-app && cargo ndk -t x86_64 -P 26 build` and
+      `... clippy` clean for both `iris` (with the android module) and
+      `iris-android-app`, same shape as I2/I3's checks.
+      `iris/run-headless.sh tabs --shot /tmp/iris_i4_tabs.png --seconds 4`
+      still renders -- **27266 bytes, byte-for-byte identical to I2's own
+      post-fix screenshot** -- confirming the hidden-window-then-adapter
+      change to `DefaultApp::new` cost nothing visible. `tabs-ui`'s five
+      switch buttons (`tabs-ui/src/lib.rs`) now carry `.label()`s matching
+      their on-screen text ("pad", "span", "image span", "text layout",
+      "text edit scroll") -- both so the desktop run above exercises a
+      non-empty tree and so the emulator step below has real names to tap.
+      Not independently checked on this pass: whether `accesskit_winit`'s
+      Linux path (AT-SPI, via `accesskit_unix`) actually reaches a real
+      assistive-technology client on this VM's headless sway -- there is
+      no AT-SPI registry running here, so `default/access.rs`'s handlers
+      are exercised as inert code paths (built, called, no panic) rather
+      than confirmed end-to-end the way the emulator step below confirms
+      the Android path.
+
+      **What remains -- the one check that needs the emulator, held by
+      another session during this pass.** `iris-android-app`'s tabs screen
+      has never been driven by `ui-trace` for real; everything above is
+      "builds, runs, produces the right data" on the host. Once the
+      emulator is free:
+
+          cd iris/android-app && cargo ndk -t x86_64 -P 26 -o app/src/main/jniLibs/ build --release && gradle :app:assembleDebug
+          adb install -r app/build/outputs/apk/debug/app-debug.apk
+          # launch iris-android-app on the emulator, then:
+          ui-trace record --do "tap 'pad'"
+          ui-trace record --do "tap 'span'"
+          ui-trace record --do "tap 'image span'"
+          ui-trace record --do "tap 'text layout'"
+          ui-trace record --do "tap 'text edit scroll'"
+
+      Pass condition: each tap resolves (uiautomator finds a node with
+      that exact label) and switches `main`'s visible pane the way a
+      direct touch on that button already does -- i.e. `bench-lib.sh`'s
+      tap-by-name mechanism, unmodified, driving the iris screen instead
+      of the Compose one. Also worth checking while the emulator is up,
+      since E1 found it exactly this way: run a second `ui-trace record`
+      immediately after the first (attach, detach, attach again) and
+      confirm the process is still alive afterward -- the detach-abort
+      this box's mitigation exists for.
+- [~] **I5 — the transcript screen in iris (2026-09-05). The widget-tree
+      half is built, tested and screenshotted; the emulator half (real
+      device numbers against the Compose baseline) is not -- ticked
+      partial rather than done, see "What remains" at the end of this box.**
+
+      **Where it lives.** `iris/transcript-ui/` (new workspace member,
+      `[lib]`), the same shape as `iris/tabs-ui`: generic over `Rsc:
+      HasEvents` + `Rsc::State: FocusHost` so the same `build()` can run
+      under winit (`transcript-ui/examples/transcript.rs`) or an
+      android-view cdylib later. Depends on `client-core`/`event-model` by
+      path (real code, matching E2's precedent) and `pulldown-cmark`
+      (0.13.4, current stable). Four modules: `markdown.rs` (CommonMark ->
+      plain text + `Vec<SpanStyle>`), `row.rs` (one `iris::widget::List`
+      row per folded `TranscriptRow`), `selection.rs` (cross-row
+      selection), `composer.rs` (the growing input field). `lib.rs`'s own
+      module doc has the screen's shape and the one gap it documents up
+      front (below).
+
+      **New iris API, added in this box and recorded in `IRIS.md`:
+      `SpanStyle`, per-range text styling.** This is the actual answer to
+      RUST.md's E2 finding against Masonry ("rich inline text -- block-level
+      yes, inline no, and both for the same reason":
+      `masonry/src/widgets/text_area.rs:43-44`'s `TextArea::edit_styles()`
+      returns one `StyleSet` for the whole editor, with `// TODO:
+      RichTextInput` beside it). `core/src/primitive/text.rs`'s
+      `TextBuffer` gained `spans: Vec<SpanStyle>` and `set_spans`;
+      `SpanStyle{range, color, family, font_size, bold, italic,
+      underline}` pushes into parley's `RangedBuilder` via `.push(property,
+      range)` instead of only `.push_default(...)`, so one `TextEdit` can
+      carry a heading's bigger bold font, an inline-code span's monospace
+      colour, a link's colour+underline and an ordinary paragraph's base
+      style all in the *same* wrapped, selectable buffer.
+      `core/src/render/atlas.rs`'s `PlacedGlyph` gained a `color: UiColor`
+      field (read from parley's own per-run `Style::brush`,
+      `core/src/primitive/text.rs`'s `TextData::place`) and
+      `core/src/ui/painter.rs`'s `glyphs()` now colours each glyph from
+      that field instead of one colour for the whole `RenderedText` --
+      the change that actually makes a span's colour reach the screen.
+      **Real bug found and fixed while wiring this in**: `TextBuilder`'s
+      `.spans(...)` was only threaded through `TextOutput::run` (the
+      read-only `Text` widget), not the sibling `TextEditOutput::run` (the
+      `TextEdit` every transcript row actually uses) -- a "rule that
+      governs a set belongs to the set, not one member" miss, per
+      CODE_RULES.md; found because `run-headless.sh`'s screenshot showed
+      *no* styling at all despite `markdown.rs`'s own unit tests passing
+      (they only check the string/range logic, not the render path -- see
+      `iris/src/widget/text/build.rs`'s `TextEditOutput::run`, now fixed).
+
+      **The seven behaviours, each shown or given a sourced reason, same
+      structure as E2's own accounting:**
+
+      1. **Selection spanning rows -- shown, with a scoped shortcut
+         recorded rather than hidden.** `selection.rs`'s `Selection`
+         coordinates each visible row's own `TextEditCtx::select`/
+         `select_all`/`deselect` (already built for one field, I2) from a
+         single drag that crosses row boundaries: rows between the anchor
+         and the pointer get `select_all()`, the row under the pointer gets
+         a true partial selection from whichever edge faces the anchor,
+         and `selected_text()` concatenates the result in row order. The
+         one shortcut: the *anchor* row is selected in full once the drag
+         leaves it, rather than "from the click point to its far edge",
+         because that needs the row's own laid-out size and
+         `TextEditCtx`'s `layout()` helper is private
+         (`iris/src/widget/text/edit.rs`) -- see `selection.rs`'s module
+         doc. Pure range-membership logic (`in_range`, mirroring
+         `begin`/`extend`'s row-selection arithmetic) is unit-tested
+         without any render harness; the widget-level wiring is not
+         independently screenshotted this pass (would need a synthetic
+         drag injected into the winit example -- not attempted, time).
+      2. **Rich inline text -- shown, genuinely inline this time.**
+         `markdown::render_markdown` folds one row's whole markdown (not
+         one block at a time) into one string plus spans, so a heading, a
+         **bold** word, *italic* text, `inline code`, and a
+         [link](url) inside the same paragraph render in one `TextEdit`
+         that still wraps and selects as a single buffer --
+         screenshotted, see below. Deliberately not attempted, each
+         recorded at the point it would have gone in `markdown.rs`'s own
+         doc: a background chip behind inline code (needs glyph-run
+         geometry `TextEdit`-internal and not exposed, the same primitive
+         `TextEdit::draw`'s selection highlight uses,
+         `iris/src/widget/text/edit.rs:99`), a tappable link (same missing
+         primitive), a real table layout, and per-token syntax colour
+         inside a fence.
+      3. **Bottom-anchored virtualised list, hold-the-edge on expand --
+         shown**, reusing I3's `List` unmodified. A `TranscriptRow::Tools`
+         row collapses to "N tool calls" and expands to every call's own
+         tool/input/output on tap; `row.rs`'s click handler calls
+         `List::extent(key)` to convert the tap's row-local position into
+         the viewport-relative position `List::note_tap` wants, exactly
+         the two-step contract `list.rs`'s module doc describes for
+         `holdTopEdge`. Not independently screenshotted mid-expand this
+         pass (no input-injection into the desktop example was built) --
+         the mechanism is the same one I3 already benchmarked
+         (`expand-hold`, flat at 0.10-0.11ms across N), applied to real
+         content instead of a synthetic row.
+      4. **The soft keyboard -- inherited from I2, not re-investigated.**
+         The composer (`composer.rs`) is an ordinary `TextEdit` with the
+         same `InputConnection` bridge I2 built and measured (Gboard
+         suggestions over real buffer content); nothing new to add here,
+         and no Android shell exists yet for this screen specifically to
+         re-verify it against (see "What remains").
+      5. **Platform integration -- out of scope by design**, same as E2:
+         E3's list, not this box's.
+      6. **Accessibility names -- shown for the composer, not yet for
+         rows.** The composer field carries `.label("Message")` (I4). Rows
+         do not yet carry per-row labels (a row's own text *is* its
+         accessible content via `TextEdit`'s `access_role`, I4, but
+         nothing calls `.label()` on it, so `Widgets::named()` does not
+         include it) -- a small, real gap, recorded as an IRIS_TODO.md
+         item rather than silently left, since AGENTS.md's bench scripts
+         depend on exactly this for driving a screen by name.
+      7. **Measurable frames / the render-number pass condition -- the
+         gesture-conflict half is now fixed (2026-09-05); the emulator
+         half is still not attempted, and unlike E2 that's not an absent
+         gesture path.** `List` demonstrably scrolls (I3's flat
+         draws/moves, programmatic `scroll()`) and mouse-wheel scrolling
+         is wired here (`lib.rs`'s `CursorSense::Scroll` on `list`). What
+         was *not* reachable at first was a **touch-drag pan starting on a
+         row's own text**: `row.rs` registered `CursorSense::
+         click_or_drag()` on each row's `TextEdit` for selection, and
+         `TextEdit::draw` calls `painter.child_layer()`
+         (`iris/src/widget/text/edit.rs:87`), so `core/src/sense.rs`'s
+         `run_sensors` (which stops at the first layer, checked
+         innermost-first, that consumed the gesture) gave that row first
+         refusal on *every* frame it was pressed, not just the frame the
+         press started -- a row's drag-select won the same gesture a
+         list-level pan would want. This is a genuine, diagnosed
+         architecture gap this box's *own* two features created by both
+         wanting the same gesture -- not a missing primitive the way
+         Masonry's absent `on_pointer_event` drag handling was.
+
+         **Gap closed, 2026-09-05, same day.** `iris::sense::DragArbiter`
+         (`iris/src/sense.rs`, new public type, recorded in `IRIS.md`) is
+         one small state machine, one instance per gesture surface (a
+         whole list, not per row), driven with a caller-supplied `Instant`
+         so it needs no render harness to test. It decides the way
+         Android itself does, recorded in `DECISIONS.md`: an ordinary
+         vertical drag pans immediately; a stationary press held
+         `LONG_PRESS` (500ms) starts a selection, which any further drag
+         then extends; a horizontal drag while something is already
+         selected extends it immediately, skipping the wait.
+         `transcript-ui/src/selection.rs`'s new `Selection::drag` is the
+         one place every row's `CursorSense::click_or_drag() |
+         CursorSense::unclick()` handler now goes through (`row.rs`,
+         `build_text_row`), replacing the direct `begin`/`extend` calls
+         each row used to make on its own -- one arbiter shared across
+         every row is what keeps the decision consistent as a drag
+         crosses row boundaries, per `DragArbiter`'s own doc. `Pan(dy)`
+         calls the list's own `List::scroll` (the same method I3's
+         mouse-wheel handler and its own benchmark already use), so this
+         is not a second scroll mechanism. 8 new unit tests in
+         `iris/src/sense.rs`'s `drag_arbiter_tests` (vertical drag pans
+         immediately and keeps panning by per-frame delta; small jitter
+         under `DRAG_SLOP` stays undecided; a held press starts a
+         selection after `LONG_PRESS` and further drag extends it, even
+         vertical drag, once selecting; a horizontal drag with nothing yet
+         selected stays undecided rather than guessing; a horizontal drag
+         with something already selected extends immediately; a vertical
+         drag still pans even with a prior selection; release resets to
+         idle). Verification: `cargo fmt --all -- --check`, `cargo clippy
+         --workspace --all-targets` (zero warnings), `cargo test
+         --workspace` (28 pre-existing + 9 `transcript-ui` + **8 new**
+         `drag_arbiter_tests`, all passing), `cargo ndk -t x86_64 -P 26
+         build/clippy` for both `-p iris` and `-p transcript-ui --lib`
+         (clean), and `run-headless.sh transcript --shot ... -- -p
+         transcript-ui` -- byte-identical to this box's original
+         screenshot (38578 bytes, `cmp` confirms identical), confirming no
+         visual regression from the rewiring. **What this did not
+         attempt**: the emulator-side confirmation (a real touch swipe
+         over a row's text panning on-device) -- that still needs I5's own
+         Android integration, the one item named just above and in "What
+         remains" below; this pass only had the winit/host-side gesture
+         path to drive, since no cdylib exists yet for this screen.
+
+      **Verification, exact commands and results (2026-09-05, this VM):**
+
+      - `cargo fmt --all -- --check`: clean.
+      - `cargo build --workspace --all-targets`: clean, all six workspace
+        members (`iris`, `iris-core`, `iris-macro`, `tabs-ui`,
+        `transcript-ui`, plus the excluded `android-app`).
+      - `cargo clippy --all-targets` and `cargo clippy -p transcript-ui
+        --all-targets`: zero warnings.
+      - `cargo test --workspace`: 28 tests in `iris`/`iris-core` (all
+        pre-existing, unaffected) + **9 new in `transcript-ui`** -- 5 pure
+        markdown tests (`bold_and_italic_produce_spans_over_the_right_range`,
+        `heading_gets_a_bigger_font_size_span`,
+        `link_is_styled_and_keeps_its_visible_text`,
+        `fenced_code_block_is_monospaced`, a plain-text baseline) and 4
+        selection tests (forward/backward/single-row range arithmetic,
+        plus `unregister_forgets_the_row_and_clears_a_matching_anchor`
+        against a real minimal `TextEdit` in the arena, no window needed --
+        same harness style as `list.rs`'s own tests).
+      - `cargo ndk -t x86_64 -P 26 build -p transcript-ui` and `... clippy
+        -p transcript-ui --lib`: clean (`--lib` only -- the example uses
+        `iris::default`, winit-only by design, same as `iris/examples/
+        tabs`'s own example never having an Android build of itself; the
+        Android-facing entry point is a separate cdylib, not built this
+        pass, see below). `cargo ndk ... build -p iris` / `clippy -p iris`
+        also re-checked clean, since this box touched `iris-core`'s text
+        pipeline.
+      - `run-headless.sh transcript --shot ... -- -p transcript-ui`:
+        renders. Cropped for legibility (this VM has no image viewer --
+        see I3's own note on the same limitation and the throwaway crop
+        tool used here, not committed): a full conversation with a
+        **bold** word, *italic* text, `inline code` in its own colour, a
+        `# Sure` heading rendered visibly larger and bold, a coloured link,
+        a monospaced fenced code block, a collapsed "▸ 3 tool calls" row,
+        and the composer bar at the bottom -- every one of E2's markdown
+        screenshot's features, now inline within single paragraphs rather
+        than block-per-widget. Screenshots at `/tmp/iris_i5_transcript2.png`
+        (full) and crops there, not committed per the standing rule against
+        screenshots of real content leaving this repo -- these are
+        synthetic rows, but the rule is kept uniform regardless.
+
+      **What remains, named rather than silently dropped (also in
+      IRIS_TODO.md, dated 2026-09-05):**
+
+      - **The emulator half of the pass condition was not attempted.**
+        `emu list` shows `emulator-5554` (AVD `ai-app`, a different
+        checkout) held by another session during this pass, but even with
+        a free emulator this needs real Android integration that does not
+        exist yet for this screen: a cdylib + Gradle shell the way
+        `iris-android-app` wraps `tabs-ui` (I2), real
+        `client-core::ApiClient`/`event_stream::follow_session_events`
+        wiring against `app/ui-sandbox.sh` with `--delay` (this crate
+        deliberately does not fetch anything itself, see `lib.rs`'s doc),
+        and then `transcript-bench.sh`'s gesture compared against the
+        Compose baseline. That is real, multi-part follow-on work in its
+        own right -- closer in size to E2/E3 than to "run one more
+        script" -- not something this pass's remaining time could
+        responsibly rush and still report honestly.
+      - **Row-level accessibility names** -- behaviour 6 above.
+      - **A tappable link and a code-span background chip** -- behaviour 2.
+      - **`Selection`'s anchor-row shortcut** -- behaviour 1.
+      - **No syntax highlighting inside a fenced code block** -- `markdown.rs`
+        notes `client_core::highlight` exists and could feed this.
+      - **`row.rs`'s tool-row expand and `selection.rs`'s cross-row drag
+        are not independently screenshotted/driven** -- covered by reading
+        and by the primitives they reuse (I3's `List` tests, this box's
+        own unit tests), not by a dedicated repro this pass.
+
+      **Net for the recommendation.** Item 3 ("decide when the transcript
+      screen exists in both, from the measurements") still cannot be
+      decided by a number -- E2 could not produce one for Masonry, and I5
+      has not yet produced one for iris either, for an unrelated reason
+      (no Android harness built yet, not an absent capability). What *can*
+      be said structurally, updating E2's own conclusion: iris now also
+      demonstrates the two things E2 found Masonry structurally unable to
+      do at all -- cross-row selection and true per-span inline rich text
+      inside one wrapped, selectable buffer -- neither of which exists
+      anywhere in `masonry`/`masonry_core`/`xilem` today (E2's own
+      `grep -rln` finding). That is a second structural point in iris's
+      favour, alongside I2's working touch-scroll-vs-Masonry's-absent one,
+      still short of the render-number comparison the recommendation
+      ultimately wants.
 
 ## For the next agent
 

app/shellApp/build.gradle.kts

@@ -88,12 +88,60 @@ android {
         versionCode = 1
         versionName = "1.0"
     }
+    // Same reasoning and same key as androidApp's (see that module's comment): E5 (RUST.md)
+    // signs its own, Gradle-free build with this same keystore, and the two can only
+    // `adb install -r` over each other if they carry the same certificate.
+    val keystore = System.getenv("AI_APP_KEYSTORE")
+    signingConfigs {
+        if (keystore != null) {
+            create("release") {
+                storeFile = file(keystore)
+                storePassword = System.getenv("AI_APP_KEYSTORE_PASSWORD")
+                keyAlias = "ai-app"
+                keyPassword = storePassword
+            }
+        }
+    }
+    buildTypes {
+        getByName("release") {
+            isMinifyEnabled = false
+            if (keystore != null) signingConfig = signingConfigs.getByName("release")
+        }
+    }
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_21
         targetCompatibility = JavaVersion.VERSION_21
     }
 }
 
+// E5 (RUST.md): the xtask dexes and packages this module's Java sources itself, but it does
+// not resolve Maven dependencies -- reimplementing a dependency resolver was out of scope for a
+// packaging step, so this one task is the single place Gradle still runs in that pipeline. It
+// asks the dependency graph for the *post-transform* jars (AARs already unpacked to a classes
+// jar, the same artifact type AGP's own dexing task consumes) rather than the raw configuration,
+// which would hand back .aar files d8 cannot read directly.
+val artifactType = Attribute.of("artifactType", String::class.java)
+
+tasks.register("printRuntimeClasspathJars") {
+    description = "Writes the resolved release runtime classpath jars, one per line, for xtask."
+    val outputFile = layout.buildDirectory.file("xtask/runtime-classpath.txt")
+    outputs.file(outputFile)
+    val jars =
+        configurations
+            .getByName("releaseRuntimeClasspath")
+            .incoming
+            .artifactView { attributes.attribute(artifactType, "android-classes-jar") }
+            .files
+    // Captured as a plain FileCollection (not the ArtifactView itself, which the
+    // configuration cache cannot serialize) so this task is still cacheable.
+    inputs.files(jars)
+    doLast {
+        val file = outputFile.get().asFile
+        file.parentFile.mkdirs()
+        file.writeText(jars.joinToString("\n") { it.absolutePath })
+    }
+}
+
 androidComponents {
     onVariants { variant ->
         variant.sources.java?.addGeneratedSourceDirectory(generatePinnedCa, GeneratePinnedCa::outputDir)

client-core/src/config.rs

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

client-core/src/lib.rs

@@ -4,6 +4,7 @@
 
 pub mod ansi;
 pub mod api;
+pub mod config;
 pub mod event_stream;
 pub mod highlight;
 pub mod notifications;

iris/Cargo.toml

@@ -13,6 +13,7 @@ swash = { workspace = true }
 pollster = { workspace = true }
 wgpu = { workspace = true }
 image = { workspace = true }
+accesskit = { workspace = true }
 tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] }
 
 # winit everywhere except Android; android-view (below) is what stands in
@@ -27,6 +28,11 @@ tokio = { workspace = true, features = ["sync", "rt", "rt-multi-thread"] }
 [target.'cfg(not(target_os = "android"))'.dependencies]
 winit = { workspace = true }
 arboard = { workspace = true, features = ["wayland-data-control"] }
+# I4 (RUST.md): the desktop half of the AccessKit push, `winit`'s own
+# adapter over `accesskit`. No pin needed the way android-view's rev is
+# pinned -- this is an ordinary crates.io release with no local abort to
+# track (that finding is Android-only, see below).
+accesskit_winit = "0.34.0"
 
 # Pinned to the exact commit RUST.md's E1 (2026-09-04) measured on this
 # emulator -- real Vulkan rendering, a working `InputConnection`, and the
@@ -35,6 +41,14 @@ arboard = { workspace = true, features = ["wayland-data-control"] }
 # is dated rather than floating.
 [target.'cfg(target_os = "android")'.dependencies]
 android-view = { git = "https://github.com/rust-mobile/android-view.git", rev = "bec6c62a96cef8239b0fd7fedeef9b184d02e3a1" }
+# I4 (RUST.md): the Android half of the AccessKit push, over android-view's
+# `AccessibilityNodeProvider`. **0.8.0 carries the same detach-abort E1
+# found on 0.4.0** (the `State` enum still never returns to `Inactive`,
+# and `send_completed_event` still unwraps a Java exception) -- advancing
+# the version is not the fix, so pinning to a specific rev buys nothing
+# here the way it does for android-view itself. `android/view.rs`'s
+# `raise_if_enabled` is the mitigation, carried from E1.
+accesskit_android = "0.8.0"
 # Not re-exported by android-view (only `jni` and `ndk` are), and needed
 # for `android/insets.rs`'s own id -> state map -- the same reason
 # android-view's own `PEER_MAP` carries one.
@@ -59,7 +73,7 @@ name = "message_list"
 harness = false
 
 [workspace]
-members = ["core", "macro", "tabs-ui"]
+members = ["core", "macro", "tabs-ui", "transcript-ui", "desktop-app"]
 # android-app pulls in android-view, which needs the NDK sysroot to link
 # -- excluded so `cargo build --workspace --all-targets` on the host stays
 # buildable. Cross-compile it from its own directory (its own single-crate
@@ -82,6 +96,12 @@ parley = "0.11.1"
 swash = "0.2.10"
 fxhash = "0.2.1"
 arboard = "3.6.1"
+accesskit = "0.25.0"
 iris-core = { path = "core" }
 iris-macro = { path = "macro" }
 tokio = "1.49.0"
+# Current stable as of 2026-09-05 (`cargo search`) -- I5's markdown block
+# model, the same crate E2's uncommitted `e2-transcript` experiment used for
+# the identical job (RUST.md), rather than reimplementing a CommonMark
+# parser.
+pulldown-cmark = "0.13.4"

iris/android-app/Cargo.lock

@@ -18,6 +18,126 @@ version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
 
+[[package]]
+name = "accesskit"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "438a7081a65b95c668db56591a4fef9bc5dad275f448bd6223fc6949d823db38"
+dependencies = [
+ "uuid",
+]
+
+[[package]]
+name = "accesskit_android"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "929aff36b0d3dd22ddb59191989d5293ed958294d7728bd6c2ec9778f73414aa"
+dependencies = [
+ "accesskit",
+ "accesskit_consumer",
+ "jni 0.21.1",
+ "log",
+]
+
+[[package]]
+name = "accesskit_atspi_common"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9d47ad644916f6cb7e432a5ca0dbd7cc78281a9772881057bb72d4aadb93257"
+dependencies = [
+ "accesskit",
+ "accesskit_consumer",
+ "atspi-common",
+ "phf",
+ "serde",
+ "zvariant",
+]
+
+[[package]]
+name = "accesskit_consumer"
+version = "0.39.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc882fa0c9c24c53649e256311b51046cf36eca9a8f7e54ff4ef682160b0cb27"
+dependencies = [
+ "accesskit",
+ "hashbrown 0.17.1",
+]
+
+[[package]]
+name = "accesskit_ios"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5e9b29c6ba5f4d2e0662e9c562484f061ffc58f658479c538ecca8299ada1e9"
+dependencies = [
+ "accesskit",
+ "accesskit_consumer",
+ "hashbrown 0.17.1",
+ "objc2 0.5.2",
+ "objc2-foundation 0.2.2",
+ "objc2-ui-kit",
+]
+
+[[package]]
+name = "accesskit_macos"
+version = "0.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3f278988416e5fb600f24d0cfffe31a249ebbff980fb9c5a3b5fbed2c579f73"
+dependencies = [
+ "accesskit",
+ "accesskit_consumer",
+ "hashbrown 0.17.1",
+ "objc2 0.5.2",
+ "objc2-app-kit 0.2.2",
+ "objc2-foundation 0.2.2",
+]
+
+[[package]]
+name = "accesskit_unix"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "665c9079b7325a8168a6793437a172dda44b19a05af8ed52d7e32abaada996fe"
+dependencies = [
+ "accesskit",
+ "accesskit_atspi_common",
+ "async-channel",
+ "async-executor",
+ "async-task",
+ "atspi",
+ "futures-lite",
+ "futures-util",
+ "serde",
+ "zbus",
+]
+
+[[package]]
+name = "accesskit_windows"
+version = "0.35.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a59e8d7160cbac991c1345c99153783ab96423644ccb1f20617cf80c97596aa1"
+dependencies = [
+ "accesskit",
+ "accesskit_consumer",
+ "hashbrown 0.17.1",
+ "static_assertions",
+ "windows",
+ "windows-core",
+]
+
+[[package]]
+name = "accesskit_winit"
+version = "0.34.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1eb960a51582305f94b3884a7ff54b3462abe38f0de95a9e7e04dd7ab7b757da"
+dependencies = [
+ "accesskit",
+ "accesskit_ios",
+ "accesskit_macos",
+ "accesskit_unix",
+ "accesskit_windows",
+ "raw-window-handle",
+ "winit",
+]
+
 [[package]]
 name = "adler2"
 version = "2.0.1"
@@ -215,12 +335,180 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "async-broadcast"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-channel"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2"
+dependencies = [
+ "concurrent-queue",
+ "event-listener-strategy",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-executor"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c96bf972d85afc50bf5ab8fe2d54d1586b4e0b46c97c50a0c9e71e2f7bcd812a"
+dependencies = [
+ "async-task",
+ "concurrent-queue",
+ "fastrand",
+ "futures-lite",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "async-io"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc"
+dependencies = [
+ "autocfg",
+ "cfg-if",
+ "concurrent-queue",
+ "futures-io",
+ "futures-lite",
+ "parking",
+ "polling",
+ "rustix 1.1.4",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-lock"
+version = "3.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-process"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75"
+dependencies = [
+ "async-channel",
+ "async-io",
+ "async-lock",
+ "async-signal",
+ "async-task",
+ "blocking",
+ "cfg-if",
+ "event-listener",
+ "futures-lite",
+ "rustix 1.1.4",
+]
+
+[[package]]
+name = "async-recursion"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b43422f69d8ff38f95f1b2bb76517c91589a924d1559a0e935d7c8ce0274c11"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "async-signal"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485"
+dependencies = [
+ "async-io",
+ "async-lock",
+ "atomic-waker",
+ "cfg-if",
+ "futures-core",
+ "futures-io",
+ "rustix 1.1.4",
+ "signal-hook-registry",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-task"
+version = "4.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
+
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
+[[package]]
+name = "atspi"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c77886257be21c9cd89a4ae7e64860c6f0eefca799bb79127913052bd0eefb3d"
+dependencies = [
+ "atspi-common",
+ "atspi-proxies",
+]
+
+[[package]]
+name = "atspi-common"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20c5617155740c98003016429ad13fe43ce7a77b007479350a9f8bf95a29f63d"
+dependencies = [
+ "enumflags2",
+ "serde",
+ "static_assertions",
+ "zbus",
+ "zbus-lockstep",
+ "zbus-lockstep-macros",
+ "zbus_names",
+ "zvariant",
+]
+
+[[package]]
+name = "atspi-proxies"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2230e48787ed3eb4088996eab66a32ca20c0b67bbd4fd6cdfe79f04f1f04c9fc"
+dependencies = [
+ "atspi-common",
+ "serde",
+ "zbus",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.1"
@@ -327,6 +615,19 @@ dependencies = [
  "objc2 0.5.2",
 ]
 
+[[package]]
+name = "blocking"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa"
+dependencies = [
+ "async-channel",
+ "async-task",
+ "futures-io",
+ "futures-lite",
+ "piper",
+]
+
 [[package]]
 name = "built"
 version = "0.8.1"
@@ -648,6 +949,33 @@ version = "1.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
 
+[[package]]
+name = "endi"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099"
+
+[[package]]
+name = "enumflags2"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef"
+dependencies = [
+ "enumflags2_derive",
+ "serde",
+]
+
+[[package]]
+name = "enumflags2_derive"
+version = "0.7.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "env_filter"
 version = "0.1.4"
@@ -700,6 +1028,26 @@ version = "3.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7"
 
+[[package]]
+name = "event-listener"
+version = "5.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
+dependencies = [
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "event-listener-strategy"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93"
+dependencies = [
+ "event-listener",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "exr"
 version = "1.74.2"
@@ -717,6 +1065,12 @@ dependencies = [
  "zune-inflate",
 ]
 
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
 [[package]]
 name = "fax"
 version = "0.2.7"
@@ -831,6 +1185,36 @@ version = "0.3.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
 
+[[package]]
+name = "futures-io"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
+
+[[package]]
+name = "futures-lite"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad"
+dependencies = [
+ "fastrand",
+ "futures-core",
+ "futures-io",
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "futures-macro"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
 [[package]]
 name = "futures-task"
 version = "0.3.34"
@@ -844,6 +1228,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
 dependencies = [
  "futures-core",
+ "futures-macro",
  "futures-task",
  "pin-project-lite",
  "slab",
@@ -1026,6 +1411,12 @@ version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284"
 
+[[package]]
+name = "hex"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
 [[package]]
 name = "hexf-parse"
 version = "0.2.1"
@@ -1225,6 +1616,9 @@ dependencies = [
 name = "iris"
 version = "0.1.0"
 dependencies = [
+ "accesskit",
+ "accesskit_android",
+ "accesskit_winit",
  "android-view",
  "arboard",
  "image",
@@ -1255,6 +1649,7 @@ dependencies = [
 name = "iris-core"
 version = "0.1.0"
 dependencies = [
+ "accesskit",
  "bytemuck",
  "fxhash",
  "image",
@@ -1541,6 +1936,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "metal"
 version = "0.33.0"
@@ -2069,6 +2473,16 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "ordered-stream"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "os_pipe"
 version = "1.2.3"
@@ -2088,6 +2502,12 @@ dependencies = [
  "ttf-parser",
 ]
 
+[[package]]
+name = "parking"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -2173,6 +2593,49 @@ dependencies = [
  "indexmap",
 ]
 
+[[package]]
+name = "phf"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "010378780309880b08997fae13be7834dba947d36393bd372f2b1556deb2a2f6"
+dependencies = [
+ "phf_macros",
+ "phf_shared",
+ "serde",
+]
+
+[[package]]
+name = "phf_generator"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aeb62e0959d5a1bebc965f4d15d9e2b7cea002b6b0f5ba8cde6cc26738467100"
+dependencies = [
+ "fastrand",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_macros"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5fa8d0ca26d424d27630da600c6624696e7dec8bf7b3b492b383c5dc49e5e085"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6fd9027e2d9319be6349febd1db4e8d02aa544921200c9b777720ac34a3aa89"
+dependencies = [
+ "siphasher",
+]
+
 [[package]]
 name = "pin-project"
 version = "1.1.13"
@@ -2199,6 +2662,17 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "piper"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1"
+dependencies = [
+ "atomic-waker",
+ "fastrand",
+ "futures-io",
+]
+
 [[package]]
 name = "pkg-config"
 version = "0.3.34"
@@ -2733,12 +3207,33 @@ dependencies = [
  "syn 3.0.5",
 ]
 
+[[package]]
+name = "serde_repr"
+version = "0.1.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
 [[package]]
 name = "shlex"
 version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
 [[package]]
 name = "simd-adler32"
 version = "0.3.10"
@@ -2770,6 +3265,12 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
 
+[[package]]
+name = "siphasher"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
+
 [[package]]
 name = "skrifa"
 version = "0.44.0"
@@ -2913,6 +3414,19 @@ dependencies = [
  "iris",
 ]
 
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix 1.1.4",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "termcolor"
 version = "1.4.1"
@@ -3058,14 +3572,29 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
  "pin-project-lite",
+ "tracing-attributes",
  "tracing-core",
 ]
 
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "tracing-core"
 version = "0.1.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
 
 [[package]]
 name = "tree_magic_mini"
@@ -3084,6 +3613,17 @@ version = "0.25.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
 
+[[package]]
+name = "uds_windows"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e"
+dependencies = [
+ "memoffset",
+ "tempfile",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "ui-events"
 version = "0.1.0"
@@ -3118,6 +3658,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "uuid"
+version = "1.26.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5772d71c9be8a8a6ac2117d949c5b224c1b72241bb611d9a3012edcf8af7812"
+dependencies = [
+ "js-sys",
+ "serde_core",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "v_frame"
 version = "0.3.9"
@@ -4044,6 +4595,112 @@ dependencies = [
  "synstructure",
 ]
 
+[[package]]
+name = "zbus"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907"
+dependencies = [
+ "async-broadcast",
+ "async-executor",
+ "async-io",
+ "async-lock",
+ "async-process",
+ "async-recursion",
+ "async-task",
+ "async-trait",
+ "blocking",
+ "enumflags2",
+ "event-listener",
+ "futures-core",
+ "futures-lite",
+ "hex",
+ "libc",
+ "ordered-stream",
+ "rustix 1.1.4",
+ "serde",
+ "serde_repr",
+ "tracing",
+ "uds_windows",
+ "uuid",
+ "windows-sys 0.61.2",
+ "winnow",
+ "zbus_macros",
+ "zbus_names",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus-lockstep"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6998de05217a084b7578728a9443d04ea4cd80f2a0839b8d78770b76ccd45863"
+dependencies = [
+ "zbus_xml",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus-lockstep-macros"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10da05367f3a7b7553c8cdf8fa91aee6b64afebe32b51c95177957efc47ca3a0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "zbus-lockstep",
+ "zbus_xml",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus_macros"
+version = "5.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+ "zbus_names",
+ "zvariant",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zbus_names"
+version = "4.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8bf88b4a3ff53e883001e0e0115b297a9d53c31b9c1edd2bfdd853e3428624e"
+dependencies = [
+ "serde",
+ "winnow",
+ "zvariant",
+]
+
+[[package]]
+name = "zbus_xml"
+version = "5.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1586c021a01ca0a9216dcd874e546382e156a5cbab5fab6cb5f10087e22682a"
+dependencies = [
+ "serde",
+ "winnow",
+ "zbus_names",
+ "zvariant",
+]
+
+[[package]]
+name = "zcheapstr"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "zeno"
 version = "0.3.3"
@@ -4155,3 +4812,44 @@ checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
 dependencies = [
  "zune-core",
 ]
+
+[[package]]
+name = "zvariant"
+version = "5.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1d34c27cc6cdd1f458427519dd6b8612f7b7e3f7b9a0b2355d041dda9869147"
+dependencies = [
+ "endi",
+ "enumflags2",
+ "serde",
+ "winnow",
+ "zcheapstr",
+ "zvariant_derive",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_derive"
+version = "5.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "864155e69b4352db0c7f374917bf45d1e0c8d17659c8b3dbf9795f3673f8c497"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+ "zvariant_utils",
+]
+
+[[package]]
+name = "zvariant_utils"
+version = "4.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn 3.0.5",
+ "winnow",
+]

iris/core/Cargo.toml

@@ -10,3 +10,4 @@ image = { workspace = true }
 parley = { workspace = true }
 swash = { workspace = true }
 fxhash = { workspace = true }
+accesskit = { workspace = true }

iris/core/src/orientation/pos.rs

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

iris/core/src/primitive/text.rs

@@ -1,8 +1,9 @@
 use crate::{Align, GlyphAtlas, GlyphKey, PlacedGlyph, RegionAlign, Textures, UiColor, util::Vec2};
 use parley::{
-    Alignment, AlignmentOptions, FontContext, FontFamily, FontFamilyName, GenericFamily, Layout,
+    Alignment, AlignmentOptions, FontContext, FontFamily, FontFamilyName, FontStyle, FontWeight,
-    LayoutContext, LineHeight, PositionedLayoutItem, StyleProperty,
+    GenericFamily, Layout, LayoutContext, LineHeight, PositionedLayoutItem, StyleProperty,
 };
+use std::ops::Range;
 use swash::{
     FontRef,
     scale::{Render, ScaleContext, Source, StrikeWith},
@@ -51,6 +52,72 @@ impl Family {
     }
 }
 
+/// One styled run inside a `TextBuffer`, overriding `TextAttrs`' base style
+/// over `range` (a byte range into the buffer's text). Every field is
+/// optional so a span only says what it changes -- e.g. a link span sets
+/// `color` and `underline` and leaves weight/family at the paragraph's own
+/// default. This is I5's answer to RUST.md's inline-rich-text ceiling
+/// (`masonry/src/widgets/text_area.rs`'s `StyleSet` is one style for the
+/// whole editor, with `// TODO: RichTextInput` beside it): parley's own
+/// `RangedBuilder::push` already takes a style and a range, so per-span
+/// bold/italic/monospace/colour/underline only needed plumbing this struct
+/// through to it and giving each glyph its own colour at draw time (see
+/// `PlacedGlyph::color` and `TextData::place` below) instead of the one
+/// `RenderedText::color` every glyph used to share.
+#[derive(Clone, PartialEq)]
+pub struct SpanStyle {
+    pub range: Range<usize>,
+    pub color: Option<UiColor>,
+    pub family: Option<Family>,
+    /// Overrides `TextAttrs::font_size` for just this range -- what lets a
+    /// heading inside a transcript row's single `TextEdit` be bigger than
+    /// the paragraph text around it, so a whole markdown-folded row (block
+    /// and inline styling both) can stay one selectable text buffer instead
+    /// of one widget per block.
+    pub font_size: Option<f32>,
+    pub bold: bool,
+    pub italic: bool,
+    pub underline: bool,
+}
+
+impl SpanStyle {
+    pub fn new(range: Range<usize>) -> Self {
+        Self {
+            range,
+            color: None,
+            family: None,
+            font_size: None,
+            bold: false,
+            italic: false,
+            underline: false,
+        }
+    }
+    pub fn color(mut self, color: UiColor) -> Self {
+        self.color = Some(color);
+        self
+    }
+    pub fn family(mut self, family: Family) -> Self {
+        self.family = Some(family);
+        self
+    }
+    pub fn font_size(mut self, size: f32) -> Self {
+        self.font_size = Some(size);
+        self
+    }
+    pub fn bold(mut self) -> Self {
+        self.bold = true;
+        self
+    }
+    pub fn italic(mut self) -> Self {
+        self.italic = true;
+        self
+    }
+    pub fn underline(mut self) -> Self {
+        self.underline = true;
+        self
+    }
+}
+
 #[derive(Clone, PartialEq)]
 pub struct TextAttrs {
     pub color: UiColor,
@@ -86,8 +153,12 @@ impl Default for TextAttrs {
 pub struct TextBuffer {
     text: String,
     layout: Layout<UiColor>,
+    spans: Vec<SpanStyle>,
     /// What the current layout was built for, so `shape` can decline to redo
-    /// work that would come out the same.
+    /// work that would come out the same. Spans are not part of this key --
+    /// `set_spans` forces `shaped` to `None` directly, the same way `edit`
+    /// does, since spans change far less often than a naive equality check
+    /// on the whole `Vec` would cost to compute every frame.
     shaped: Option<(TextAttrs, Option<f32>)>,
 }
 
@@ -96,10 +167,19 @@ impl TextBuffer {
         Self {
             text: text.into(),
             layout: Layout::new(),
+            spans: Vec::new(),
             shaped: None,
         }
     }
 
+    /// Replace this buffer's per-range style overrides (I5's rich text --
+    /// see `SpanStyle`). Invalidates the layout unconditionally, mirroring
+    /// `set_text`.
+    pub fn set_spans(&mut self, spans: Vec<SpanStyle>) {
+        self.spans = spans;
+        self.shaped = None;
+    }
+
     pub fn new_empty() -> Self {
         Self::new("")
     }
@@ -150,6 +230,27 @@ impl TextBuffer {
             attrs.line_height,
         )));
         builder.push_default(StyleProperty::Brush(attrs.color));
+        for span in &self.spans {
+            let range = span.range.clone();
+            if let Some(color) = span.color {
+                builder.push(StyleProperty::Brush(color), range.clone());
+            }
+            if let Some(family) = &span.family {
+                builder.push(StyleProperty::FontFamily(family.family()), range.clone());
+            }
+            if let Some(size) = span.font_size {
+                builder.push(StyleProperty::FontSize(size), range.clone());
+            }
+            if span.bold {
+                builder.push(StyleProperty::FontWeight(FontWeight::BOLD), range.clone());
+            }
+            if span.italic {
+                builder.push(StyleProperty::FontStyle(FontStyle::Italic), range.clone());
+            }
+            if span.underline {
+                builder.push(StyleProperty::Underline(true), range.clone());
+            }
+        }
         builder.build_into(&mut self.layout, &self.text);
         self.layout.break_all_lines(width);
         self.layout
@@ -175,6 +276,7 @@ impl TextData {
                 let font = run.run().font();
                 let font_size = run.run().font_size();
                 let coords = run.run().normalized_coords();
+                let run_color = run.style().brush;
                 let Some(font_ref) = FontRef::from_index(font.data.as_ref(), font.index as usize)
                 else {
                     continue;
@@ -227,6 +329,7 @@ impl TextData {
                             glyph.x.floor() + entry.left as f32,
                             glyph.y.floor() - entry.top as f32,
                         ),
+                        color: run_color,
                     });
                 }
             }
@@ -245,11 +348,15 @@ fn hash_coords(coords: &[i16]) -> u64 {
     h
 }
 
-/// A laid-out string, ready to draw: where each glyph goes, how big the whole
+/// A laid-out string, ready to draw: where each glyph goes and how big the
-/// thing is, and what colour to tint the atlas with.
+/// whole thing is.
 ///
 /// Cheap to clone and to keep, which is the point -- a widget holds one across
-/// frames and re-emits its quads without going near the rasteriser.
+/// frames and re-emits its quads without going near the rasteriser. `color`
+/// is the buffer's *base* colour (`TextAttrs::color`) for a caller that wants
+/// it as a whole (e.g. tinting a cursor to match); the colour each glyph is
+/// actually drawn in is `PlacedGlyph::color`, which a `SpanStyle` can
+/// override per range.
 #[derive(Clone)]
 pub struct RenderedText {
     pub glyphs: std::sync::Arc<Vec<PlacedGlyph>>,

iris/core/src/render/atlas.rs

@@ -10,7 +10,7 @@
 //! it, and a resize re-emits quads without touching the GPU's copy at all.
 
 use crate::{
-    PatchRect, TextureHandle, Textures,
+    PatchRect, TextureHandle, Textures, UiColor,
     util::{HashMap, Vec2},
 };
 use image::RgbaImage;
@@ -228,8 +228,16 @@ fn write_glyph(page: &mut RgbaImage, image: &Image, x: u32, y: u32) {
 }
 
 /// Where a glyph goes on screen, in pixels relative to the text's origin.
+///
+/// `color` is per-glyph (read from the parley run's own `Brush`, since
+/// `UiColor` is parley's brush type here) rather than a single colour for
+/// the whole `RenderedText`, so that a span pushed with its own
+/// `StyleProperty::Brush` (I5's inline rich text: a link, a diff of colour
+/// inside one wrapped paragraph) actually renders in that colour instead of
+/// the buffer's base one.
 #[derive(Clone, Copy)]
 pub struct PlacedGlyph {
     pub entry: GlyphEntry,
     pub offset: Vec2,
+    pub color: UiColor,
 }

iris/core/src/ui/access.rs

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

iris/core/src/ui/mod.rs

@@ -2,10 +2,12 @@ use crate::{
     Mask, MoveOffset, TextData, Textures, WeakWidget, WidgetId, Widgets, util::TrackedArena,
 };
 
+mod access;
 mod active;
 mod painter;
 mod render_state;
 
+pub use access::*;
 pub use active::*;
 pub use painter::Painter;
 pub use render_state::*;

iris/core/src/ui/painter.rs

@@ -194,7 +194,7 @@ impl<'a> Painter<'a> {
                     glyph.entry.uv_min,
                     glyph.entry.uv_max,
                     glyph.entry.layer,
-                    text.color,
+                    glyph.color,
                     flags_for(glyph.entry.is_color),
                 ),
                 region,

iris/core/src/util/slot.rs

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

iris/core/src/widget/mod.rs

@@ -29,6 +29,18 @@ pub trait Widget: Any {
     fn is_size_independent(&self) -> bool {
         false
     }
+
+    /// What kind of control this is, for the AccessKit tree `ui::access`
+    /// builds (RUST.md's I4). Only consulted for a widget that also has an
+    /// explicit `.label()` -- an unnamed widget is never visited by that
+    /// tree at all, named or not, so the default here costs nothing except
+    /// at the handful of call sites that opt in. Default `Unknown` (a
+    /// generic control with no more specific semantics); a widget with a
+    /// real platform equivalent -- `TextEdit`'s `MultilineTextInput` --
+    /// overrides it.
+    fn access_role(&self) -> accesskit::Role {
+        accesskit::Role::Unknown
+    }
 }
 
 impl Widget for () {

iris/core/src/widget/widgets.rs

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

iris/desktop-app/Cargo.toml

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

iris/desktop-app/src/app.rs

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

iris/desktop-app/src/config.rs

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

iris/desktop-app/src/main.rs

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

iris/run-headless.sh

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

iris/src/access_tests.rs

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

iris/src/android/access.rs

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

iris/src/android/mod.rs

@@ -12,6 +12,7 @@
 //! counterpart: winit cannot drive an IME beyond `Ime::Preedit`/`Commit`
 //! (RUST.md's E1) and has no concept of Android's window insets at all.
 
+mod access;
 mod attr;
 mod ime;
 mod input;

iris/src/android/view.rs

@@ -1,8 +1,10 @@
 use crate::prelude::*;
 use crate::task::RequestRedraw;
+use accesskit_android::Adapter as AccessAdapter;
 use android_view::{
-    CallbackCtx, Context, InputConnection, KeyEvent, MotionEvent, Rect, View, ViewPeer,
+    AccessibilityNodeInfo, AccessibilityNodeProvider, Bundle, CallbackCtx, Context,
-    jni::JNIEnv,
+    InputConnection, KeyEvent, MotionEvent, Rect, View, ViewPeer,
+    jni::{JNIEnv, sys::jint},
     ndk::event::{Keycode, MotionAction},
 };
 // `marker::Sized` explicitly: `crate::prelude::*` below also brings in the
@@ -18,6 +20,7 @@ use std::{
 };
 
 use super::{
+    access::{AndroidAccessSource, NullActionHandler, raise_if_enabled},
     insets::{Insets, Shared},
     render::{AndroidRedrawHandle, AndroidRenderer},
 };
@@ -47,6 +50,13 @@ pub struct AndroidUiState {
     /// path -- see `android/insets.rs` for why they need a registry of
     /// their own.
     shared: Rc<RefCell<Shared>>,
+    /// I4 (RUST.md): pushed from `IrisViewPeer::render` and consulted by
+    /// the `AccessibilityNodeProvider` impl below; see `android/access.rs`
+    /// for the abort mitigation every `raise` on it goes through.
+    pub access_adapter: AccessAdapter,
+    /// The AccessKit tree itself -- see `iris_core::AccessTree`'s doc
+    /// comment.
+    pub access: AccessTree,
 }
 
 impl AndroidUiState {
@@ -60,6 +70,8 @@ impl AndroidUiState {
             compose_len: 0,
             pending_show_keyboard: false,
             shared,
+            access_adapter: Default::default(),
+            access: AccessTree::new(),
         }
     }
 
@@ -234,7 +246,7 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
     /// it -- on both the Vulkan/SwiftShader and GLES/virgl backends. Leave
     /// these in until that is root-caused; removing them loses the exact
     /// evidence a `logcat` capture needs to reproduce the state.
-    fn render(&mut self) {
+    fn render(&mut self, ctx: &mut CallbackCtx) {
         let ui_state = self.state.android_state();
         if ui_state.renderer.is_none() {
             return;
@@ -267,6 +279,26 @@ impl<State: AndroidAppState> IrisViewPeer<State> {
                 .as_ref()
                 .and_then(|r| self.render.window_region(r, &self.rsc)),
         );
+
+        // I4 (RUST.md): only produces a `TreeUpdate` -- and so only queues
+        // anything to raise -- when the named set actually changed this
+        // frame; see `AccessTree`'s doc comment. Deferred rather than
+        // raised inline so it runs after this callback releases whatever
+        // it's holding, matching android-view's own demo and `raise`'s own
+        // contract.
+        let ui_state = self.state.android_state_mut();
+        if let Some(tree_update) =
+            ui_state
+                .access
+                .update(self.rsc.widgets(), &self.render, &self.rsc)
+        {
+            let ui_state = self.state.android_state_mut();
+            if let Some(events) = ui_state.access_adapter.update_if_active(|| tree_update) {
+                ctx.push_dynamic_deferred_callback(move |env, view| {
+                    raise_if_enabled(env, view, events);
+                });
+            }
+        }
     }
 }
 
@@ -384,7 +416,7 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
         let ui_state = self.state.android_state_mut();
         ui_state.renderer = None;
         ui_state.renderer = Some(AndroidRenderer::new(window, width as u32, height as u32));
-        self.render();
+        self.render(ctx);
     }
 
     fn surface_destroyed<'local>(
@@ -395,14 +427,84 @@ impl<State: AndroidAppState> ViewPeer for IrisViewPeer<State> {
         self.state.android_state_mut().renderer = None;
     }
 
-    fn do_frame(&mut self, _ctx: &mut CallbackCtx, _frame_time_nanos: i64) {
+    fn do_frame(&mut self, ctx: &mut CallbackCtx, _frame_time_nanos: i64) {
         self.drain_tasks();
-        self.render();
+        self.render(ctx);
     }
 
     fn as_input_connection(&mut self) -> Option<&mut dyn InputConnection> {
         Some(self)
     }
+
+    fn as_accessibility_node_provider(&mut self) -> Option<&mut dyn AccessibilityNodeProvider> {
+        Some(self)
+    }
+}
+
+impl<State: AndroidAppState> AccessibilityNodeProvider for IrisViewPeer<State> {
+    fn create_accessibility_node_info<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        virtual_view_id: jint,
+    ) -> AccessibilityNodeInfo<'local> {
+        let mut source = AndroidAccessSource {
+            widgets: self.rsc.widgets(),
+            render: &self.render,
+            rsc: &self.rsc,
+        };
+        let ui_state = self.state.android_state_mut();
+        AccessibilityNodeInfo(ui_state.access_adapter.create_accessibility_node_info(
+            &mut source,
+            &mut ctx.env,
+            &ctx.view.0,
+            virtual_view_id,
+        ))
+    }
+
+    fn find_focus<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        focus_type: jint,
+    ) -> AccessibilityNodeInfo<'local> {
+        let mut source = AndroidAccessSource {
+            widgets: self.rsc.widgets(),
+            render: &self.render,
+            rsc: &self.rsc,
+        };
+        let ui_state = self.state.android_state_mut();
+        AccessibilityNodeInfo(ui_state.access_adapter.find_focus(
+            &mut source,
+            &mut ctx.env,
+            &ctx.view.0,
+            focus_type,
+        ))
+    }
+
+    fn perform_action<'local>(
+        &mut self,
+        ctx: &mut CallbackCtx<'local>,
+        virtual_view_id: jint,
+        action: jint,
+        arguments: &Bundle<'local>,
+    ) -> bool {
+        let Some(action) =
+            accesskit_android::PlatformAction::from_java(&mut ctx.env, action, &arguments.0)
+        else {
+            return false;
+        };
+        let ui_state = self.state.android_state_mut();
+        let Some(events) = ui_state.access_adapter.perform_action(
+            &mut NullActionHandler,
+            virtual_view_id,
+            &action,
+        ) else {
+            return false;
+        };
+        ctx.push_dynamic_deferred_callback(move |env, view| {
+            raise_if_enabled(env, view, events);
+        });
+        true
+    }
 }
 
 /// Registers `IrisViewPeer<State>`'s native methods and builds one on every

iris/src/default/access.rs

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

iris/src/default/mod.rs

@@ -11,11 +11,13 @@ use winit::{
     window::{Window, WindowAttributes},
 };
 
+mod access;
 mod app;
 mod attr;
 mod input;
 mod render;
 
+pub use access::*;
 pub use app::*;
 pub use input::*;
 pub use render::*;
@@ -31,6 +33,17 @@ pub struct DefaultUiState {
     pub window: Arc<Window>,
     pub ime: usize,
     pub last_click: Instant,
+    /// I4 (RUST.md): pushed through in `DefaultApp::window_event`'s
+    /// `RedrawRequested` arm, from `access`'s output. Built in
+    /// `DefaultApp::new`, which is the only place with the
+    /// `&ActiveEventLoop` `accesskit_winit::Adapter::with_direct_handlers`
+    /// needs -- see that constructor's doc comment on why the window must
+    /// still be invisible when it is called.
+    pub access_adapter: accesskit_winit::Adapter,
+    /// The AccessKit tree itself -- see `iris_core::AccessTree`'s doc
+    /// comment for the flat shape and why it only rebuilds on a real
+    /// change.
+    pub access: AccessTree,
 }
 
 impl HasRoot for DefaultUiState {
@@ -40,7 +53,7 @@ impl HasRoot for DefaultUiState {
 }
 
 impl DefaultUiState {
-    pub fn new(window: impl Into<Arc<Window>>) -> Self {
+    pub fn new(window: impl Into<Arc<Window>>, access_adapter: accesskit_winit::Adapter) -> Self {
         let window = window.into();
         Self {
             root: None,
@@ -51,6 +64,8 @@ impl DefaultUiState {
             ime: 0,
             last_click: Instant::now(),
             focus: None,
+            access_adapter,
+            access: AccessTree::new(),
         }
     }
 }
@@ -179,10 +194,24 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
     type Event = State::Event;
 
     fn new(event_loop: &ActiveEventLoop, proxy: EventLoopProxy<Self::Event>) -> Self {
+        // `accesskit_winit::Adapter::with_direct_handlers` panics if the
+        // window is already visible when it's built, so the window is
+        // created hidden and only shown once the adapter exists -- the one
+        // extra step I4 (RUST.md) needs here. The three handlers are inert
+        // (see `access.rs`): a screen reader's tap is a real touch at the
+        // node's bounds, not an action request this process has to answer.
         let window = event_loop
-            .create_window(State::window_attributes())
+            .create_window(State::window_attributes().with_visible(false))
             .unwrap();
-        let default_state = DefaultUiState::new(window);
+        let access_adapter = accesskit_winit::Adapter::with_direct_handlers(
+            event_loop,
+            &window,
+            NullActivationHandler,
+            NullActionHandler,
+            NullDeactivationHandler,
+        );
+        window.set_visible(true);
+        let default_state = DefaultUiState::new(window, access_adapter);
         let (mut rsc, task_recv) = DefaultRsc::init(default_state.window.clone());
         let state = State::new(default_state, &mut rsc, proxy);
         let render = UiRenderState::new();
@@ -211,6 +240,12 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
         }
 
         let ui_state = state.default_state_mut();
+        // Required by `accesskit_winit` on every window event, not just the
+        // ones this backend otherwise cares about -- some platform adapters
+        // rely on it to notice activation (a screen reader turning on).
+        ui_state
+            .access_adapter
+            .process_event(&ui_state.window, &event);
         let input_changed = ui_state.input.event(&event);
         let cursor_state = ui_state.cursor_state().clone();
         let old = ui_state.focus;
@@ -233,6 +268,14 @@ impl<State: DefaultAppState> AppState for DefaultApp<State> {
                 render.update(&ui_state.root, rsc);
                 ui_state.renderer.update(&mut rsc.ui, render);
                 ui_state.renderer.draw();
+                // 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,
+                // so `resolved_region`/`window_region` inside it report a
+                // moved subtree's *new* position, not last frame's.
+                if let Some(tree_update) = ui_state.access.update(rsc.widgets(), render, rsc) {
+                    ui_state.access_adapter.update_if_active(|| tree_update);
+                }
             }
             WindowEvent::Resized(size) => {
                 render.resize((size.width, size.height));

iris/src/layout_tests.rs

@@ -7,9 +7,11 @@
 use crate::prelude::*;
 
 /// The minimal `UiRsc` a test needs: just the shared `UiData`, none of the
-/// event/window/state plumbing `DefaultRsc` carries.
+/// event/window/state plumbing `DefaultRsc` carries. `pub(crate)` so
-struct TestRsc {
+/// `access_tests.rs` (I4, RUST.md) can reuse it rather than keeping a
-    ui: UiData,
+/// second copy of the same harness.
+pub(crate) struct TestRsc {
+    pub(crate) ui: UiData,
 }
 
 impl UiRsc for TestRsc {

iris/src/lib.rs

@@ -26,6 +26,8 @@ pub mod state;
 pub mod task;
 pub mod widget;
 
+#[cfg(test)]
+mod access_tests;
 #[cfg(test)]
 mod layout_tests;
 #[cfg(test)]

iris/src/sense.rs

@@ -2,6 +2,7 @@ use crate::prelude::*;
 use std::{
     ops::{BitOr, Deref, DerefMut},
     rc::Rc,
+    time::{Duration, Instant},
 };
 
 #[derive(Clone, Copy, PartialEq)]
@@ -357,3 +358,241 @@ impl BitOr<CursorSense> for CursorSenses {
         self
     }
 }
+
+/// How long a stationary press has to be held before it is treated as a
+/// long-press rather than the start of a pan.
+pub const LONG_PRESS: Duration = Duration::from_millis(500);
+/// How far a press has to move, in pixels, before it counts as a drag
+/// rather than jitter -- for both the pan-vs-select axis test and the
+/// "did this actually move" long-press guard.
+pub const DRAG_SLOP: f32 = 8.0;
+
+/// What a [`DragArbiter`] decided a frame's drag should mean. `Undecided`
+/// means neither a pan nor a selection has committed yet, so the caller
+/// should do nothing observable this frame.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum DragOutcome {
+    Undecided,
+    /// Scroll the enclosing list by this many window-space pixels along
+    /// the drag axis (the delta since the arbiter's last decided frame).
+    Pan(f32),
+    /// A selection should begin at the arbiter's press origin.
+    SelectStart,
+    /// A selection already underway should extend to the current position.
+    SelectExtend,
+}
+
+#[derive(Clone, Copy, PartialEq)]
+enum ArbiterState {
+    Idle,
+    Undecided { already_selected: bool },
+    Panning,
+    Selecting,
+}
+
+/// Decides, one shared instance per gesture surface (a transcript's whole
+/// row list here), whether a touch drag that starts on a row's own
+/// selectable text is panning the list or extending a text selection --
+/// RUST.md's I5 finding that both wanted the same `CursorSense::
+/// click_or_drag()` gesture, with the inner text layer winning every frame
+/// regardless of which one the reader meant. Decided the way Android
+/// itself decides it, so a reader's existing muscle memory carries over:
+///
+/// - An ordinary vertical drag pans -- checked first, and immediately,
+///   so a swipe never waits on the long-press timer.
+/// - A stationary press held past [`LONG_PRESS`] starts a selection.
+///   Every drag frame after that extends it, whichever direction it goes.
+/// - A drag that starts **horizontally** while something is already
+///   selected extends that selection right away, skipping the long-press
+///   wait -- the "drag the selection handle" gesture a reader reaches for
+///   once text is already highlighted.
+///
+/// Pure state, no rendering or widget access, so it is unit-testable
+/// exactly like the rest of this module (`sense_tests.rs`'s style) with a
+/// caller-supplied `Instant` rather than a real clock.
+pub struct DragArbiter {
+    state: ArbiterState,
+    origin: Vec2,
+    origin_at: Instant,
+    last: Vec2,
+}
+
+impl Default for DragArbiter {
+    fn default() -> Self {
+        Self {
+            state: ArbiterState::Idle,
+            origin: Vec2::ZERO,
+            origin_at: Instant::now(),
+            last: Vec2::ZERO,
+        }
+    }
+}
+
+impl DragArbiter {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// A fresh press-down at `pos`. `already_selected` is whatever the
+    /// caller's selection state was *before* this press -- it decides
+    /// whether an early horizontal move extends that selection instead of
+    /// waiting for a long-press.
+    pub fn press_start(&mut self, pos: Vec2, now: Instant, already_selected: bool) {
+        self.origin = pos;
+        self.origin_at = now;
+        self.last = pos;
+        self.state = ArbiterState::Undecided { already_selected };
+    }
+
+    /// The press continues (still down) at `pos`. Call once per frame
+    /// while the button/finger is down; returns what this frame means.
+    pub fn update(&mut self, pos: Vec2, now: Instant) -> DragOutcome {
+        match self.state {
+            ArbiterState::Idle => DragOutcome::Undecided,
+            ArbiterState::Panning => {
+                let dy = pos.y - self.last.y;
+                self.last = pos;
+                DragOutcome::Pan(dy)
+            }
+            ArbiterState::Selecting => {
+                self.last = pos;
+                DragOutcome::SelectExtend
+            }
+            ArbiterState::Undecided { already_selected } => {
+                let dx = pos.x - self.origin.x;
+                let dy = pos.y - self.origin.y;
+                if already_selected && dx.abs() > DRAG_SLOP && dx.abs() > dy.abs() {
+                    self.state = ArbiterState::Selecting;
+                    self.last = pos;
+                    DragOutcome::SelectExtend
+                } else if dy.abs() > DRAG_SLOP && dy.abs() >= dx.abs() {
+                    self.state = ArbiterState::Panning;
+                    self.last = pos;
+                    DragOutcome::Pan(dy)
+                } else if now.duration_since(self.origin_at) >= LONG_PRESS
+                    && dx.abs() <= DRAG_SLOP
+                    && dy.abs() <= DRAG_SLOP
+                {
+                    self.state = ArbiterState::Selecting;
+                    self.last = pos;
+                    DragOutcome::SelectStart
+                } else {
+                    DragOutcome::Undecided
+                }
+            }
+        }
+    }
+
+    /// The press was released -- back to idle for the next one.
+    pub fn release(&mut self) {
+        self.state = ArbiterState::Idle;
+    }
+}
+
+#[cfg(test)]
+mod drag_arbiter_tests {
+    use super::*;
+
+    fn t(ms: u64) -> Instant {
+        // A fixed base plus an offset, rather than `Instant::now()` per
+        // call -- keeps every test's timing deterministic instead of at
+        // the mercy of how long the test itself took to run.
+        Instant::now() - Duration::from_secs(3600) + Duration::from_millis(ms)
+    }
+
+    #[test]
+    fn small_jitter_stays_undecided() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), false);
+        assert_eq!(a.update(Vec2::new(1.0, 1.0), t(10)), DragOutcome::Undecided);
+    }
+
+    #[test]
+    fn a_vertical_drag_pans_immediately() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), false);
+        assert_eq!(
+            a.update(Vec2::new(0.0, 20.0), t(10)),
+            DragOutcome::Pan(20.0)
+        );
+        // Subsequent frames keep panning, by the delta since last frame.
+        assert_eq!(
+            a.update(Vec2::new(0.0, 35.0), t(20)),
+            DragOutcome::Pan(15.0)
+        );
+    }
+
+    #[test]
+    fn a_horizontal_drag_with_nothing_selected_does_not_select() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), false);
+        // Horizontal movement alone, with no prior selection, is not any
+        // of the three named gestures -- it stays undecided rather than
+        // guessing (it will resolve to a long-press-selection if the
+        // finger then stops moving, or nothing if it lifts).
+        assert_eq!(
+            a.update(Vec2::new(20.0, 0.0), t(10)),
+            DragOutcome::Undecided
+        );
+    }
+
+    #[test]
+    fn a_long_press_without_moving_starts_a_selection() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(5.0, 5.0), t(0), false);
+        assert_eq!(a.update(Vec2::new(5.0, 5.0), t(10)), DragOutcome::Undecided);
+        assert_eq!(
+            a.update(Vec2::new(6.0, 5.0), t(LONG_PRESS.as_millis() as u64 + 1)),
+            DragOutcome::SelectStart
+        );
+    }
+
+    #[test]
+    fn after_a_long_press_any_further_drag_extends() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), false);
+        assert_eq!(
+            a.update(Vec2::new(0.0, 0.0), t(LONG_PRESS.as_millis() as u64 + 1)),
+            DragOutcome::SelectStart
+        );
+        // Even a vertical move now extends the selection rather than
+        // panning -- once a selection has started, it owns the gesture
+        // until release.
+        assert_eq!(
+            a.update(Vec2::new(0.0, 40.0), t(600)),
+            DragOutcome::SelectExtend
+        );
+    }
+
+    #[test]
+    fn a_horizontal_drag_on_already_selected_text_extends_immediately() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), true);
+        assert_eq!(
+            a.update(Vec2::new(20.0, 2.0), t(10)),
+            DragOutcome::SelectExtend
+        );
+    }
+
+    #[test]
+    fn a_vertical_drag_still_pans_even_with_a_prior_selection() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), true);
+        assert_eq!(
+            a.update(Vec2::new(0.0, 20.0), t(10)),
+            DragOutcome::Pan(20.0)
+        );
+    }
+
+    #[test]
+    fn release_resets_to_idle() {
+        let mut a = DragArbiter::new();
+        a.press_start(Vec2::new(0.0, 0.0), t(0), false);
+        a.update(Vec2::new(0.0, 20.0), t(10));
+        a.release();
+        assert_eq!(
+            a.update(Vec2::new(0.0, 999.0), t(20)),
+            DragOutcome::Undecided
+        );
+    }
+}

iris/src/widget/text/build.rs

@@ -4,6 +4,7 @@ use std::marker::{PhantomData, Sized};
 pub struct TextBuilder<State, O = TextOutput, H: WidgetOption<State> = ()> {
     pub content: String,
     pub attrs: TextAttrs,
+    pub spans: Vec<SpanStyle>,
     pub hint: H,
     pub output: O,
     state: PhantomData<State>,
@@ -39,10 +40,19 @@ impl<State, O, H: WidgetOption<State>> TextBuilder<State, O, H> {
         self.attrs.wrap = wrap;
         self
     }
+    /// Per-range style overrides -- I5's inline rich text (bold, italic,
+    /// inline-code monospace, link colour/underline) within one wrapped
+    /// paragraph. See `SpanStyle`'s doc for why this exists and what it
+    /// replaces.
+    pub fn spans(mut self, spans: Vec<SpanStyle>) -> Self {
+        self.spans = spans;
+        self
+    }
     pub fn editable(self, mode: EditMode) -> TextBuilder<State, TextEditOutput, H> {
         TextBuilder {
             content: self.content,
             attrs: self.attrs,
+            spans: self.spans,
             hint: self.hint,
             output: TextEditOutput { mode },
             state: PhantomData,
@@ -58,6 +68,7 @@ impl<Rsc: UiRsc, O> TextBuilder<Rsc, O> {
         TextBuilder {
             content: self.content,
             attrs: self.attrs,
+            spans: self.spans,
             hint: move |rsc: &mut Rsc| Some(hint.add_strong(rsc).any()),
             output: self.output,
             state: PhantomData,
@@ -81,7 +92,8 @@ impl<Rsc: UiRsc> TextBuilderOutput<Rsc> for TextOutput {
         state: &mut Rsc,
         builder: TextBuilder<Rsc, Self, H>,
     ) -> Self::Output {
-        let buf = TextBuffer::new(&builder.content);
+        let mut buf = TextBuffer::new(&builder.content);
+        buf.set_spans(builder.spans);
         let hint = builder.hint.get(state);
         let mut text = Text {
             content: builder.content.into(),
@@ -103,7 +115,8 @@ impl<State: UiRsc> TextBuilderOutput<State> for TextEditOutput {
         state: &mut State,
         builder: TextBuilder<State, Self, H>,
     ) -> Self::Output {
-        let buf = TextBuffer::new(&builder.content);
+        let mut buf = TextBuffer::new(&builder.content);
+        buf.set_spans(builder.spans);
         TextEdit::new(
             TextView::new(buf, builder.attrs, builder.hint.get(state)),
             builder.output.mode,
@@ -125,6 +138,7 @@ pub fn wtext<State>(content: impl Into<String>) -> TextBuilder<State> {
     TextBuilder {
         content: content.into(),
         attrs: TextAttrs::default(),
+        spans: Vec::new(),
         hint: (),
         output: TextOutput,
         state: PhantomData,

iris/src/widget/text/edit.rs

@@ -114,6 +114,15 @@ impl Widget for TextEdit {
         );
         used
     }
+
+    /// I4 (RUST.md): the one override that exists so far -- everything
+    /// else falls back to `Widget::access_role`'s default `Unknown`.
+    fn access_role(&self) -> accesskit::Role {
+        match self.mode {
+            EditMode::SingleLine => accesskit::Role::TextInput,
+            EditMode::MultiLine => accesskit::Role::MultilineTextInput,
+        }
+    }
 }
 
 const CARET_WIDTH: f32 = 1.0;

iris/tabs-ui/src/lib.rs

@@ -177,7 +177,14 @@ where
             )
             .on(CursorSense::HoverEnd, move |ctx, rsc| {
                 ctx.widget(rsc).color = color;
-            });
+            })
+            // I4 (RUST.md): the tabs screen's only named controls, and the
+            // ones the emulator step at the bottom of that box taps by
+            // name -- `ui-trace record --do "tap 'pad'"` and so on. `.label`
+            // slots into this chain like any other widget combinator
+            // (`RefFnTag` in `core/src/widget/tag.rs`); it does not have to
+            // be the last thing before `.add`.
+            .label(label);
         (rect, wtext(label).size(30).text_align(Align::CENTER)).stack()
     };
 

iris/transcript-ui/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "transcript-ui"
+version.workspace = true
+edition.workspace = true
+
+# I5 (RUST.md): the transcript screen's widget tree, built the same way
+# `tabs-ui` is -- its own crate, generic over `Rsc: HasEvents` +
+# `Rsc::State: FocusHost`, so the winit example and an eventual
+# `iris-android-app`-style cdylib call the same `build`. See its own module
+# doc for the design and RUST.md's I5 box for what is and is not proved yet.
+#
+# `client-core`/`event-model` by path, real code and not a reimplementation
+# -- the same dependency shape E2's uncommitted Masonry experiment used for
+# the identical job.
+
+[dependencies]
+iris = { path = ".." }
+client-core = { path = "../../client-core" }
+event-model = { path = "../../event-model" }
+pulldown-cmark = { workspace = true }

iris/transcript-ui/examples/transcript.rs

@@ -0,0 +1,122 @@
+//! I5's desktop proof: the transcript screen built from synthetic
+//! `client_core::transcript_fold` rows (no network, no server -- see
+//! `lib.rs`'s doc for why `transcript-ui` itself never fetches anything),
+//! run via `iris/run-headless.sh transcript -- -p transcript-ui` for a
+//! screenshot on the winit backend, or `cargo run --example transcript -p
+//! transcript-ui` with a real compositor.
+//!
+//! The rows exercise every one of the seven "hard to get back" behaviours
+//! this box's markdown/selection work is meant to show: a heading, bold,
+//! italic, an inline code span, a link, a fenced code block (rich inline
+//! text), a multi-message conversation (bottom-anchored virtualised list),
+//! and a three-call tool run (collapsed by default -- tap it, or drive it
+//! with `ui-trace record --do "tap 'Tools'"` on Android, to prove
+//! hold-the-edge expand).
+
+use client_core::transcript_fold::{TranscriptItem, TranscriptRow as FoldedRow};
+use iris::prelude::*;
+
+fn main() {
+    DefaultApp::<Client>::run();
+}
+
+#[derive(DefaultUiState)]
+pub struct Client {
+    ui_state: DefaultUiState,
+    #[allow(dead_code)]
+    screen: transcript_ui::TranscriptScreen,
+}
+
+fn msg(seq: u64, from_user: bool, text: &str) -> FoldedRow {
+    FoldedRow::Single(if from_user {
+        TranscriptItem::UserMsg {
+            seq,
+            text: text.to_string(),
+            attachments: Vec::new(),
+        }
+    } else {
+        TranscriptItem::AssistantMsg {
+            seq,
+            text: text.to_string(),
+            settled: true,
+        }
+    })
+}
+
+fn synthetic_rows() -> Vec<FoldedRow> {
+    vec![
+        msg(
+            1,
+            true,
+            "Can you show me a **bold** word, some *italic* text, and `inline code`?",
+        ),
+        msg(
+            2,
+            false,
+            "# Sure\n\nHere's a [link to the repo](https://example.com/ai-app-2) and a fenced block:\n\n```rust\nfn main() {\n    println!(\"hi\");\n}\n```",
+        ),
+        FoldedRow::Tools(vec![
+            TranscriptItem::ToolRun {
+                seq: 3,
+                id: "t1".into(),
+                run_id: "run1".into(),
+                tool: "Read".into(),
+                input: "{\"file\": \"src/main.rs\"}".into(),
+                output: "fn main() {}\n".into(),
+                done: true,
+                asks: Vec::new(),
+                images: Vec::new(),
+            },
+            TranscriptItem::ToolRun {
+                seq: 4,
+                id: "t2".into(),
+                run_id: "run1".into(),
+                tool: "Edit".into(),
+                input: "{\"file\": \"src/main.rs\"}".into(),
+                output: "ok".into(),
+                done: true,
+                asks: Vec::new(),
+                images: Vec::new(),
+            },
+            TranscriptItem::ToolRun {
+                seq: 5,
+                id: "t3".into(),
+                run_id: "run1".into(),
+                tool: "Bash".into(),
+                input: "cargo build".into(),
+                output: "Compiling...\nFinished.".into(),
+                done: true,
+                asks: Vec::new(),
+                images: Vec::new(),
+            },
+        ]),
+        msg(6, true, "Looks good, thanks!"),
+        msg(
+            7,
+            false,
+            "You're welcome. Let me know if you'd like anything else.",
+        ),
+    ]
+}
+
+impl DefaultAppState for Client {
+    fn new(
+        mut ui_state: DefaultUiState,
+        rsc: &mut DefaultRsc<Self>,
+        _: Proxy<Self::Event>,
+    ) -> Self {
+        let screen = transcript_ui::build(rsc, &mut ui_state, synthetic_rows());
+        // Exercises `push_row`/`ItemKey` beyond construction time, matching
+        // how a live SSE loop appends -- a row arriving after the screen
+        // already exists must land at the bottom without disturbing what's
+        // above it (I3's `push_back`/`snap_end`).
+        screen.push_row(
+            rsc,
+            &FoldedRow::Single(TranscriptItem::CommandRow {
+                seq: 8,
+                text: "clear".into(),
+            }),
+        );
+        Self { ui_state, screen }
+    }
+}

iris/transcript-ui/src/composer.rs

@@ -0,0 +1,48 @@
+//! The message composer at the bottom of the transcript screen: a
+//! multi-line editable field with a natural (not fixed) height, so it
+//! grows as typed into -- IRIS_TODO.md's "input box" benchmark case
+//! (`iris/benches/message_list.rs` exercises the mechanism in isolation;
+//! this wires the same `TextEdit`-with-no-`Sized`-wrapper idiom into the
+//! real screen). `lib.rs` gives the transcript `List` `.height(rest(1))`
+//! beside this widget in a `Span::down`, so the list's own draw already
+//! measures whatever vertical space is left each frame -- nothing here
+//! computes a height by hand, and growing this field is exactly the
+//! O(1)-move-chain case LAYOUT.md and I3's benchmark already measured.
+
+use iris::prelude::*;
+
+/// `field` is exposed so the caller can read its content on submit
+/// (`field.edit(rsc).text()`) and clear it afterward
+/// (`field.edit(rsc).set("")`).
+pub struct Composer {
+    pub field: WeakWidget<TextEdit>,
+}
+
+/// Returns the composer plus its own bar as a **weak** id -- the caller
+/// (`lib.rs::build`) embeds it in the screen's own top-level tuple, whose
+/// `set_root` performs the one real strong registration. Calling
+/// `.add_strong`/`.upgrade` a second time on an id already strong-owned
+/// panics ("was already added", `core/src/widget/like.rs:12`) -- the same
+/// mistake this box's `row.rs` first made with its sender-label header, see
+/// that file's comment for the fuller account.
+pub fn build_composer<Rsc: HasEvents>(rsc: &mut Rsc) -> (Composer, WeakWidget)
+where
+    Rsc::State: FocusHost,
+{
+    let field = wtext("")
+        .editable(EditMode::MultiLine)
+        .text_align(Align::LEFT)
+        .wrap(true)
+        .size(18)
+        .color(UiColor::WHITE)
+        .attr::<Selectable>(())
+        .label("Message")
+        .add(rsc);
+
+    let bar: WeakWidget = (field.pad(12).width(rest(1)),)
+        .span(Dir::RIGHT)
+        .background(rect(UiColor::new(40, 40, 46, 255)))
+        .add(rsc);
+
+    (Composer { field }, bar)
+}

iris/transcript-ui/src/lib.rs

@@ -0,0 +1,145 @@
+//! The transcript screen, in iris -- RUST.md's I5. Built the same way
+//! `tabs-ui` is: its own crate, generic over `Rsc: HasEvents` +
+//! `Rsc::State: FocusHost`, so the winit example (`iris/examples/
+//! transcript.rs`) and an eventual `iris-android-app`-style cdylib call the
+//! same [`build`]. See RUST.md's I5 box for the full account of what is
+//! and is not proved yet, and this doc for the shape.
+//!
+//! ```text
+//! +------------------------------------------+
+//! |  iris::widget::List (transcript_ui::row)  |  <- .height(rest(1))
+//! |    row 1: sender label + one TextEdit     |
+//! |    row 2: sender label + one TextEdit     |
+//! |    row 3 (Tools): collapsed/expanded      |
+//! |    ...                                    |
+//! +------------------------------------------+
+//! |  composer bar (transcript_ui::composer)   |  <- natural height
+//! +------------------------------------------+
+//! ```
+//!
+//! **What this crate does not do itself**: fetch anything over the network
+//! or read the transcript cache. [`build`] takes an already-folded
+//! `Vec<client_core::transcript_fold::TranscriptRow>` and
+//! [`TranscriptScreen::push_row`] takes one more as it arrives -- the
+//! caller (an app's own `main`, or a future `iris-android-app`-shaped
+//! cdylib) owns `client_core::ApiClient`/
+//! `event_stream::follow_session_events` and the transcript cache, per the
+//! code rules' "ask for the least you need": a widget-tree builder that
+//! also knew how to make an HTTPS request would be untestable without a
+//! server and unable to be driven by `run-headless.sh` with synthetic rows.
+//!
+//! **Gap closed, 2026-09-05**: a touch-drag that starts on a row's
+//! rendered text used to always begin a cross-row *selection* (`row.rs`'s
+//! `CursorSense::click_or_drag()` on each row's `TextEdit`), never a
+//! *scroll* of the list, because both wanted the same gesture over the
+//! same screen region and `core/src/sense.rs`'s `run_sensors` gave the
+//! widget in the *inner* layer (a row's own `TextEdit`) first refusal
+//! every frame it was pressed. `row.rs` now routes every row's drag
+//! through one shared `iris::sense::DragArbiter`
+//! (`Selection::drag`, `selection.rs`), which decides pan vs. select the
+//! way Android itself does -- see `DragArbiter`'s own doc and
+//! `DECISIONS.md` for the exact rule. `List` scrolls correctly when
+//! driven programmatically (I3's benchmark), via the mouse wheel (wired
+//! below, `CursorSense::Scroll`), and now via a touch pan starting on a
+//! row's own text too.
+
+pub mod composer;
+pub mod markdown;
+pub mod row;
+pub mod selection;
+
+use client_core::transcript_fold::TranscriptRow as FoldedRow;
+use iris::prelude::*;
+use selection::Selection;
+use std::{cell::RefCell, rc::Rc};
+
+pub struct TranscriptScreen {
+    /// The transcript's own `List` -- exposed so a caller can read
+    /// `.extent()`/call `.jump_to_end()` etc. directly for anything this
+    /// crate does not already wrap.
+    pub list: WeakWidget<List>,
+    pub composer: composer::Composer,
+    selection: Rc<RefCell<Selection>>,
+}
+
+impl TranscriptScreen {
+    /// Append one more folded row at the live end of the transcript --
+    /// what a caller's SSE loop or a sent message calls as new events
+    /// arrive. `List::push_back` is O(1) and keeps the view pinned to the
+    /// newest content when it already was (I3).
+    pub fn push_row<Rsc: HasEvents>(&self, rsc: &mut Rsc, row: &FoldedRow)
+    where
+        Rsc::State: FocusHost,
+    {
+        let (key, widget) = row::build_row(rsc, self.list, self.selection.clone(), row);
+        (self.list)(rsc).push_back(ListRow::new(key, widget));
+    }
+
+    /// The concatenated text of whatever is currently selected across one
+    /// or more rows, `None` if nothing is -- what a copy command reads.
+    pub fn selected_text(&self, rsc: &mut impl UiRsc) -> Option<String> {
+        self.selection.borrow().selected_text(rsc)
+    }
+}
+
+pub fn build<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    ui_state: &mut impl HasRoot,
+    rows: Vec<FoldedRow>,
+) -> TranscriptScreen
+where
+    Rsc::State: FocusHost,
+{
+    let (screen, tree) = build_tree(rsc, rows);
+    ui_state.set_root(tree);
+    screen
+}
+
+/// The same widget tree [`build`] makes, without claiming the window's
+/// whole root -- what a caller embedding this screen alongside something
+/// else of its own needs (RUST.md's E4: a session list beside the
+/// transcript on the desktop). `build` is `build_tree` plus
+/// `ui_state.set_root(tree)`; kept as its own function since most callers
+/// (the winit example, an eventual Android cdylib) want the screen to *be*
+/// the window and don't need the strong handle back.
+pub fn build_tree<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    rows: Vec<FoldedRow>,
+) -> (TranscriptScreen, StrongWidget)
+where
+    Rsc::State: FocusHost,
+{
+    let selection = Rc::new(RefCell::new(Selection::new()));
+    let list = List::new(Axis::Y).add(rsc);
+
+    for row in &rows {
+        let (key, widget) = row::build_row(rsc, list, selection.clone(), row);
+        list(rsc).push_back(ListRow::new(key, widget));
+    }
+
+    // Wheel/trackpad scrolling -- the same idiom `trait_fns.rs`'s
+    // `scrollable()` uses for `Scroll`, applied directly to `List` since
+    // `List` already does its own placement and needs no `Scroll` wrapper.
+    // Real touch-drag panning is the known gap in this module's doc.
+    list.on(CursorSense::Scroll, |ctx, rsc| {
+        let delta = ctx.data.scroll_delta.y * 50.0;
+        ctx.widget(rsc).scroll(delta);
+    })
+    .add(rsc);
+
+    let (composer, composer_bar) = composer::build_composer(rsc);
+
+    let tree = (list.width(rest(1)).height(rest(1)), composer_bar)
+        .span(Dir::DOWN)
+        .add_strong(rsc)
+        .any();
+
+    (
+        TranscriptScreen {
+            list,
+            composer,
+            selection,
+        },
+        tree,
+    )
+}

iris/transcript-ui/src/markdown.rs

@@ -0,0 +1,223 @@
+//! Markdown -> one plain string plus a `Vec<SpanStyle>`, for I5's row
+//! builder to hand to a single `TextEdit` (`row.rs`). This is the crate's
+//! answer to RUST.md's E2 finding against Masonry ("rich inline text --
+//! block-level yes, inline no, and both for the same reason": `TextArea`'s
+//! `StyleSet` is one style for the whole editor,
+//! `masonry/src/widgets/text_area.rs:43-44`'s `// TODO: RichTextInput`
+//! beside it). iris's `SpanStyle` (`core/src/primitive/text.rs`, added for
+//! this box) is per-range, so bold/italic/inline-code/links/headings inside
+//! one wrapped paragraph render in their own style *and* the paragraph
+//! still wraps and selects as one buffer -- there is no second widget per
+//! span the way E2's block-level `Prose`-per-heading was.
+//!
+//! **What this deliberately does not attempt**, each for a reason recorded
+//! here rather than silently dropped (see IRIS_TODO.md's dated entries for
+//! the same list):
+//! - **No background chip behind inline code.** Drawing one needs the
+//!   glyph run's own geometry (the way `TextEdit::draw`'s selection
+//!   highlight uses `selection.geometry(layout)`,
+//!   `iris/src/widget/text/edit.rs:99`), which is `TextEdit`-internal and
+//!   not exposed to a caller building spans externally. `SpanStyle` gives
+//!   the code range a monospace family and a dimmer text colour instead --
+//!   visually distinct, just not chip-shaped.
+//! - **A link is styled (colour + underline) but not tappable.** Following
+//!   it needs the same kind of per-range hit-testing a chip's background
+//!   would (which byte range did the tap land in, then look up its URL),
+//!   which is exactly the same missing primitive.
+//! - **Tables render as plain paragraphs of their cell text**, no columns.
+//!   `pulldown_cmark::Tag::Table` is walked but not laid out -- a real grid
+//!   needs its own widget, out of scope for a row builder.
+//! - **A fenced code block's language is not syntax-highlighted.**
+//!   `client-core::highlight` exists and could feed per-token `SpanStyle`s,
+//!   but wiring it in is real work belonging to whoever needs it next
+//!   (IRIS_TODO.md).
+//!
+//! A heading's `SpanStyle::font_size` override does not also raise its
+//! `line_height` (a buffer has one, set from the *base* font size in
+//! `TextAttrs`), so a heading's own line looks slightly tighter than a
+//! paragraph's -- visible, not incorrect, and not fixed here since it needs
+//! `SpanStyle` to carry line-height too, which nothing in this crate needed
+//! badly enough yet to justify.
+
+use iris::prelude::*;
+use pulldown_cmark::{Event, HeadingLevel, Options, Parser, Tag, TagEnd};
+
+// `UiColor` is `Color<u8>` (`core/src/lib.rs`), not the 0..1 float triples
+// its brighter/darker helpers might suggest -- these are plain 0..255 RGB.
+pub const CODE_COLOR: UiColor = UiColor::new(140, 217, 242, 255);
+pub const LINK_COLOR: UiColor = UiColor::new(140, 190, 255, 255);
+const STRIKETHROUGH_COLOR: UiColor = UiColor::new(150, 150, 150, 255);
+
+/// A block-level separator: two blocks never run into each other with no
+/// gap, but an empty `out` (the very first block) gets no leading blank.
+fn ensure_blank_line(out: &mut String) {
+    if !out.is_empty() && !out.ends_with("\n\n") {
+        out.push_str("\n\n");
+    }
+}
+
+fn heading_size(level: HeadingLevel) -> f32 {
+    match level {
+        HeadingLevel::H1 => 28.0,
+        HeadingLevel::H2 => 24.0,
+        HeadingLevel::H3 => 21.0,
+        _ => 19.0,
+    }
+}
+
+/// One markdown source string rendered into plain text plus the spans that
+/// style it. `base_size` is the row's ordinary paragraph font size, needed
+/// only so a heading's override is relative to it rather than a hardcoded
+/// absolute the caller cannot retune.
+pub fn render_markdown(src: &str, base_size: f32) -> (String, Vec<SpanStyle>) {
+    let _ = base_size; // headings use fixed sizes today; kept for callers that may want relative sizing later
+    let mut out = String::new();
+    let mut spans = Vec::new();
+    // Stack of start byte offsets for whatever inline/block styling is
+    // currently open -- pulldown-cmark's `Start`/`End` events are always
+    // balanced and each `End` already names its own kind (`TagEnd`), so a
+    // plain offset stack (rather than a tree, or repeating the kind here
+    // too) is enough.
+    let mut open: Vec<usize> = Vec::new();
+    let mut list_depth: u32 = 0;
+
+    let parser = Parser::new_ext(src, Options::ENABLE_STRIKETHROUGH | Options::ENABLE_TABLES);
+    for event in parser {
+        match event {
+            Event::Start(tag) => match tag {
+                Tag::Heading { .. }
+                | Tag::Emphasis
+                | Tag::Strong
+                | Tag::Strikethrough
+                | Tag::Link { .. } => open.push(out.len()),
+                Tag::CodeBlock(_) => {
+                    ensure_blank_line(&mut out);
+                    open.push(out.len());
+                }
+                Tag::Item => {
+                    out.push_str(&"  ".repeat(list_depth.saturating_sub(1) as usize));
+                    out.push_str("\u{2022} ");
+                }
+                Tag::List(_) => list_depth += 1,
+                Tag::Paragraph | Tag::BlockQuote(_) => ensure_blank_line(&mut out),
+                _ => {}
+            },
+            // Only the tag kinds that pushed onto `open` (Start, above) are
+            // popped here -- `List`/`Item`/`Paragraph`/`BlockQuote`/`Table`
+            // and friends push nothing, since they need no span, and must
+            // not touch this stack or they would pop an unrelated styled
+            // range still open around them.
+            Event::End(
+                tag_end @ (TagEnd::Heading(_)
+                | TagEnd::Emphasis
+                | TagEnd::Strong
+                | TagEnd::Strikethrough
+                | TagEnd::Link
+                | TagEnd::CodeBlock),
+            ) => {
+                let Some(start) = open.pop() else {
+                    continue;
+                };
+                let range = start..out.len();
+                if range.is_empty() {
+                    continue;
+                }
+                match tag_end {
+                    TagEnd::Heading(level) => {
+                        spans.push(SpanStyle::new(range).font_size(heading_size(level)).bold());
+                    }
+                    TagEnd::Emphasis => spans.push(SpanStyle::new(range).italic()),
+                    TagEnd::Strong => spans.push(SpanStyle::new(range).bold()),
+                    TagEnd::Strikethrough => {
+                        spans.push(SpanStyle::new(range).color(STRIKETHROUGH_COLOR));
+                    }
+                    TagEnd::Link => {
+                        spans.push(SpanStyle::new(range).color(LINK_COLOR).underline());
+                    }
+                    TagEnd::CodeBlock => {
+                        spans.push(
+                            SpanStyle::new(range)
+                                .family(Family::Monospace)
+                                .color(CODE_COLOR),
+                        );
+                    }
+                    _ => unreachable!("filtered by the outer match arm"),
+                }
+            }
+            Event::Text(text) => out.push_str(&text),
+            // Inline code (single backticks) is one atomic event with no
+            // `Start`/`End` pair of its own, unlike a fenced block -- so it
+            // is spanned directly here instead of through the `open` stack.
+            Event::Code(text) => {
+                let start = out.len();
+                out.push_str(&text);
+                spans.push(
+                    SpanStyle::new(start..out.len())
+                        .family(Family::Monospace)
+                        .color(CODE_COLOR),
+                );
+            }
+            Event::SoftBreak => out.push(' '),
+            Event::HardBreak => out.push('\n'),
+            Event::Rule => {
+                if !out.ends_with('\n') {
+                    out.push('\n');
+                }
+                out.push_str("\u{2500}\u{2500}\u{2500}\n");
+            }
+            Event::End(TagEnd::List(_)) => list_depth = list_depth.saturating_sub(1),
+            _ => {}
+        }
+    }
+    (out, spans)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn plain_paragraph_has_no_spans() {
+        let (text, spans) = render_markdown("just some words", 16.0);
+        assert_eq!(text, "just some words");
+        assert!(spans.is_empty());
+    }
+
+    #[test]
+    fn bold_and_italic_produce_spans_over_the_right_range() {
+        let (text, spans) = render_markdown("a **bold** and *italic* word", 16.0);
+        assert_eq!(text, "a bold and italic word");
+        let bold = spans.iter().find(|s| s.bold && !s.italic).unwrap();
+        assert_eq!(&text[bold.range.clone()], "bold");
+        let italic = spans.iter().find(|s| s.italic).unwrap();
+        assert_eq!(&text[italic.range.clone()], "italic");
+    }
+
+    #[test]
+    fn heading_gets_a_bigger_font_size_span() {
+        let (text, spans) = render_markdown("# A Title\n\nbody text", 16.0);
+        assert!(text.starts_with("A Title"));
+        let heading = spans.iter().find(|s| s.font_size.is_some()).unwrap();
+        assert_eq!(&text[heading.range.clone()], "A Title");
+        assert_eq!(heading.font_size, Some(28.0));
+    }
+
+    #[test]
+    fn link_is_styled_and_keeps_its_visible_text() {
+        let (text, spans) = render_markdown("see [the docs](https://example.com) for more", 16.0);
+        assert!(text.contains("the docs"));
+        assert!(
+            !text.contains("example.com"),
+            "the URL should not leak into the visible text"
+        );
+        let link = spans.iter().find(|s| s.underline).unwrap();
+        assert_eq!(&text[link.range.clone()], "the docs");
+    }
+
+    #[test]
+    fn fenced_code_block_is_monospaced() {
+        let (text, spans) = render_markdown("before\n\n```\nlet x = 1;\n```\n\nafter", 16.0);
+        let code = spans.iter().find(|s| s.family.is_some()).unwrap();
+        assert!(text[code.range.clone()].contains("let x = 1;"));
+    }
+}

iris/transcript-ui/src/row.rs

@@ -0,0 +1,301 @@
+//! One `iris::widget::list::ListRow` per folded transcript row
+//! (`client_core::transcript_fold::TranscriptRow`). Each row's whole text
+//! -- headings, paragraphs, inline styling -- goes through `markdown` into
+//! **one** `TextEdit`, which is what makes it one thing `Selection`
+//! (`selection.rs`) can select and what lets it wrap and scroll as a
+//! single buffer, matching RUST.md's "hard to get back" behaviour 2 (rich
+//! inline text) and half of behaviour 1 (selectable within a row; across
+//! rows is `selection.rs`'s job).
+//!
+//! A `TranscriptRow::Tools` (a run of adjacent tool calls, grouped by
+//! `client_core::transcript_fold::group_tool_runs`) is the row that proves
+//! behaviour 3's "hold the edge nearest the tap" on expand: tapping its
+//! header calls `List::note_tap` at the row's own on-screen position
+//! (read back from `List::extent`, since the tap event only knows its
+//! position *within* this row) before toggling a `WidgetPtr` between the
+//! collapsed summary and the full detail -- the same two-step contract
+//! `list.rs`'s module doc describes for `AGENTS.md`'s `holdTopEdge`.
+
+use crate::markdown::render_markdown;
+use crate::selection::Selection;
+use client_core::transcript_fold::{QuestionCard, TranscriptItem, TranscriptRow as FoldedRow};
+use iris::prelude::*;
+use std::{cell::RefCell, rc::Rc, time::Instant};
+
+/// The paragraph size every row's `TextEdit` is built at; markdown headings
+/// inside a row scale relative to a fixed set of sizes rather than this one
+/// (`markdown::heading_size`), since a heading is meant to look the same
+/// regardless of which row's base size surrounds it.
+pub const BASE_SIZE: f32 = 16.0;
+
+/// `ItemKey::Seq` already is the `RowKey` (`u64`) this crate's `List` wants.
+/// `ItemKey::RunId` is a string (a tool call's own id), so it is hashed into
+/// one -- collisions are not a correctness risk worth guarding against here
+/// (a `DefaultHasher` collision across the run ids one session produces is
+/// astronomically unlikely, and the consequence of one would only be two
+/// tool-call rows sharing a list slot, not data loss), and the high bit is
+/// forced on so a hashed key can never collide with a real sequence number
+/// (this build never produces 2^63 events).
+pub fn row_key(key: &client_core::transcript_fold::ItemKey) -> RowKey {
+    use client_core::transcript_fold::ItemKey;
+    use std::hash::{Hash, Hasher};
+    match key {
+        ItemKey::Seq(seq) => *seq,
+        ItemKey::RunId(id) => {
+            let mut h = std::collections::hash_map::DefaultHasher::new();
+            id.hash(&mut h);
+            h.finish() | (1 << 63)
+        }
+    }
+}
+
+/// The sender label shown above a row's text, and the markdown source to
+/// render below it. `None` for a system-style note that has no sender.
+fn item_content(item: &TranscriptItem) -> (Option<&str>, String) {
+    match item {
+        TranscriptItem::UserMsg { text, .. } => (Some("You"), text.clone()),
+        TranscriptItem::AssistantMsg { text, .. } => (Some("Claude"), text.clone()),
+        TranscriptItem::ErrorMsg { message, .. } => (Some("Error"), message.clone()),
+        TranscriptItem::CommandRow { text, .. } => (Some("Command"), format!("`/{text}`")),
+        TranscriptItem::PeerNote { from, text, .. } => (Some(from.as_str()), text.clone()),
+        TranscriptItem::Note { text, .. } => (None, text.clone()),
+        TranscriptItem::ClearedNote { .. } => (None, "_Context cleared._".to_string()),
+        TranscriptItem::CompactedNote {
+            pre_tokens,
+            post_tokens,
+            ..
+        } => (
+            None,
+            match (pre_tokens, post_tokens) {
+                (Some(pre), Some(post)) => format!("_Compacted: {pre} -> {post} tokens._"),
+                _ => "_Compacted._".to_string(),
+            },
+        ),
+        TranscriptItem::ImageItem { r#ref, .. } => (None, format!("_[image: {ref}]_")),
+        TranscriptItem::QuestionCard(card) => (Some("Question"), question_markdown(card)),
+        TranscriptItem::ToolRun {
+            tool,
+            input,
+            output,
+            ..
+        } => (Some(tool.as_str()), tool_call_markdown(tool, input, output)),
+    }
+}
+
+fn question_markdown(card: &QuestionCard) -> String {
+    let mut out = card.prompt.clone();
+    for opt in &card.options {
+        out.push_str(&format!("\n- {}", opt.label));
+    }
+    out
+}
+
+fn tool_call_markdown(tool: &str, input: &str, output: &str) -> String {
+    let mut out = format!("**{tool}**\n\n```\n{input}\n```");
+    if !output.is_empty() {
+        out.push_str(&format!("\n\n```\n{output}\n```"));
+    }
+    out
+}
+
+/// Build one `TextEdit` from a sender label plus markdown source, register
+/// it with `selection` under `key`, and wire the pointer handlers that
+/// drive `Selection::drag` -- shared by every row variant below, since a
+/// selectable row is always "one TextEdit plus this wiring" regardless of
+/// what folded it. `list` is threaded through so that same drag can pan
+/// the list instead of selecting, per `Selection::drag`'s own doc.
+fn build_text_row<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    list: WeakWidget<List>,
+    selection: Rc<RefCell<Selection>>,
+    key: RowKey,
+    sender: Option<&str>,
+    markdown_src: &str,
+) -> StrongWidget
+where
+    Rsc::State: FocusHost,
+{
+    let (text, spans) = render_markdown(markdown_src, BASE_SIZE);
+    let field = wtext(text)
+        .spans(spans)
+        .editable(EditMode::MultiLine)
+        .text_align(Align::LEFT)
+        .wrap(true)
+        .size(BASE_SIZE)
+        .color(UiColor::WHITE)
+        .add(rsc);
+    selection.borrow_mut().register(key, field);
+
+    field
+        // `| CursorSense::unclick()` on top of the usual click-or-drag set
+        // -- the arbiter inside `Selection::drag` needs the release too,
+        // to go back to idle for the next press (`DragArbiter::release`).
+        .on(
+            CursorSense::click_or_drag() | CursorSense::unclick(),
+            move |ctx, rsc| {
+                selection.borrow_mut().drag(
+                    rsc,
+                    list,
+                    key,
+                    ctx.data.pos,
+                    ctx.data.size,
+                    ctx.data.cursor.pos,
+                    ctx.data.sense,
+                    Instant::now(),
+                );
+            },
+        )
+        .add(rsc);
+
+    // `.add` (weak), not `.add_strong` -- `header` is about to be embedded
+    // as a child of the `.span(Dir::DOWN)` below, whose own composition is
+    // what performs the *one* real strong registration each child gets.
+    // Calling `.add_strong`/`.upgrade` here too, then feeding a `.weak()`
+    // copy into that composition, tried to strong-register the same id
+    // twice and panicked with "was already added"
+    // (`core/src/widget/like.rs:12`) -- found running this crate's own
+    // `run-headless.sh` example, the first real render of a row.
+    let header: WeakWidget = match sender {
+        Some(name) => wtext(name.to_string())
+            .size(13.0)
+            .color(UiColor::new(150, 150, 160, 255))
+            .add(rsc),
+        None => Span::empty(Dir::DOWN).add(rsc),
+    };
+
+    (header, field.width(rest(1)))
+        .span(Dir::DOWN)
+        .gap(4)
+        .pad(10)
+        .add_strong(rsc)
+        .any()
+}
+
+fn build_single<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    list: WeakWidget<List>,
+    selection: Rc<RefCell<Selection>>,
+    key: RowKey,
+    item: &TranscriptItem,
+) -> StrongWidget
+where
+    Rsc::State: FocusHost,
+{
+    let (sender, markdown_src) = item_content(item);
+    build_text_row(rsc, list, selection, key, sender, &markdown_src)
+}
+
+/// A run of adjacent tool calls: collapsed to a one-line summary by
+/// default, expanding in place to every call's own tool/input/output on
+/// tap -- see the module doc for the hold-the-edge contract this wires
+/// against `list`.
+fn build_tools<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    list: WeakWidget<List>,
+    selection: Rc<RefCell<Selection>>,
+    key: RowKey,
+    calls: Vec<TranscriptItem>,
+) -> StrongWidget
+where
+    Rsc::State: FocusHost,
+{
+    let expanded = Rc::new(RefCell::new(false));
+    // `.add_strong` (not `.add`) because nothing else in the tree holds a
+    // strong reference to this `WidgetPtr` the way a container's own
+    // `add_strong`-on-its-children does for an ordinary child -- this row
+    // *is* the top of its own subtree, so it has to own itself.
+    let ptr_strong = WidgetPtr::new().add_strong(rsc);
+    let ptr = ptr_strong.weak();
+
+    let summary_text = format!("\u{25b8} {} tool calls", calls.len());
+    let full_text = calls
+        .iter()
+        .map(|c| match c {
+            TranscriptItem::ToolRun {
+                tool,
+                input,
+                output,
+                ..
+            } => tool_call_markdown(tool, input, output),
+            other => item_content(other).1,
+        })
+        .collect::<Vec<_>>()
+        .join("\n\n");
+
+    fn build_content<Rsc: HasEvents>(
+        rsc: &mut Rsc,
+        list: WeakWidget<List>,
+        selection: Rc<RefCell<Selection>>,
+        key: RowKey,
+        expanded: bool,
+        summary: &str,
+        full: &str,
+    ) -> StrongWidget
+    where
+        Rsc::State: FocusHost,
+    {
+        let text = if expanded { full } else { summary };
+        build_text_row(rsc, list, selection, key, Some("Tools"), text)
+    }
+
+    let content = build_content(
+        rsc,
+        list,
+        selection.clone(),
+        key,
+        false,
+        &summary_text,
+        &full_text,
+    );
+    ptr(rsc).set(content);
+
+    ptr.on(CursorSense::click(), move |ctx, rsc| {
+        // `List::note_tap` wants a viewport-relative position, but the
+        // click event only knows where inside *this row* it landed
+        // (`ctx.data.pos`) -- `List::extent` (last frame's on-screen box
+        // for this row's key) is what turns the two into the position
+        // `list.rs`'s hold-the-edge layout pass resolves against, per the
+        // module doc's contract.
+        let (top, _bottom) = list(rsc).extent(key).unwrap_or((0.0, 0.0));
+        list(rsc).note_tap(top + ctx.data.pos.y);
+
+        let was_expanded = *expanded.borrow();
+        *expanded.borrow_mut() = !was_expanded;
+        let content = build_content(
+            rsc,
+            list,
+            selection.clone(),
+            key,
+            !was_expanded,
+            &summary_text,
+            &full_text,
+        );
+        // The old content's `StrongWidget` is freed when this drops --
+        // the removal half of the row this click just replaced.
+        let _old = ptr(rsc).replace(content);
+    })
+    .add(rsc);
+
+    ptr_strong.any()
+}
+
+pub fn build_row<Rsc: HasEvents>(
+    rsc: &mut Rsc,
+    list: WeakWidget<List>,
+    selection: Rc<RefCell<Selection>>,
+    row: &FoldedRow,
+) -> (RowKey, StrongWidget)
+where
+    Rsc::State: FocusHost,
+{
+    match row {
+        FoldedRow::Single(item) => {
+            let key = row_key(&item.key());
+            (key, build_single(rsc, list, selection, key, item))
+        }
+        FoldedRow::Tools(calls) => {
+            let key = row_key(&calls[0].key());
+            (key, build_tools(rsc, list, selection, key, calls.clone()))
+        }
+    }
+}

iris/transcript-ui/src/selection.rs

@@ -0,0 +1,288 @@
+//! Selection spanning multiple transcript rows -- RUST.md's "hard to get
+//! back" behaviour 1, and the one E2 found flatly impossible on Masonry:
+//! `TextArea` wraps exactly one `parley::PlainEditor`, and there is no
+//! `SelectionContainer`-shaped type anywhere in `masonry`/`masonry_core`/
+//! `xilem` (RUST.md's E2 box, citing
+//! `masonry/src/widgets/text_area.rs:414-459`). Each transcript row here is
+//! still its own `TextEdit` (one per row, not one per transcript, since a
+//! row is what `List` virtualises), so this is not literally "one
+//! `PlainEditor`" either -- iris's answer is a coordinator that drives each
+//! visible row's *own* selection primitives (`TextEditCtx::select`/
+//! `select_all`/`deselect`, already built for a single field) from one
+//! pointer drag that crosses row boundaries, giving the same reader-facing
+//! result (a selection that runs from a reply into the tool output beneath
+//! it, one copy) without needing a single shared text buffer underneath.
+//!
+//! Rows are keyed by `RowKey` (`iris::widget::list`), which every real row
+//! source (a transcript's sequence number) already assigns in the order the
+//! reader reads them in -- so "between the anchor and the current row" is
+//! answered by ordinary integer comparison via a `BTreeMap`, not a second
+//! copy of the list's own ordering.
+//!
+//! **Scoped shortcut, recorded rather than hidden**: the anchor row (the
+//! one the 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" -- the exact partial selection would need
+//! that row's own laid-out size, which `TextEditCtx` does not expose to a
+//! caller outside `iris::widget::text` (`edit.rs`'s `layout()` helper is
+//! private). Only the row currently *under the pointer* gets a true partial
+//! selection (from its own start or end, per direction, to the pointer's
+//! exact point) -- see `extend`. Re-entering the anchor row is still exact,
+//! since that branch never goes through the approximation.
+
+use iris::prelude::*;
+use std::{collections::BTreeMap, time::Instant};
+
+pub struct Selection {
+    rows: BTreeMap<RowKey, WeakWidget<TextEdit>>,
+    anchor: Option<(RowKey, Vec2)>,
+    /// One arbiter shared by every row's drag handler -- RUST.md's I5
+    /// gesture conflict (a row's own `click_or_drag()` and a list-level
+    /// pan wanting the same touch gesture). See `drag` below, and
+    /// `iris::sense::DragArbiter`'s own doc for the decision itself.
+    arbiter: DragArbiter,
+}
+
+impl Default for Selection {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Selection {
+    pub fn new() -> Self {
+        Self {
+            rows: BTreeMap::new(),
+            anchor: None,
+            arbiter: DragArbiter::new(),
+        }
+    }
+
+    /// A row's selectable text became visible/known. Every addition here
+    /// needs its removal (`unregister`) -- called when `List` evicts the
+    /// row (`pop_front`/`pop_back`), so this map never outgrows however
+    /// many rows are actually loaded.
+    pub fn register(&mut self, key: RowKey, text: WeakWidget<TextEdit>) {
+        self.rows.insert(key, text);
+    }
+
+    pub fn unregister(&mut self, key: RowKey) {
+        self.rows.remove(&key);
+        if self.anchor.map(|(k, _)| k) == Some(key) {
+            self.anchor = None;
+        }
+    }
+
+    /// A fresh press: clears whatever was selected elsewhere (an ordinary
+    /// click starts a new selection, it does not extend the old one) and
+    /// gives `key`'s row a collapsed caret at `pos` -- a plain click that
+    /// never turns into a drag leaves exactly this and nothing else
+    /// selected.
+    pub fn begin(&mut self, ui: &mut impl UiRsc, key: RowKey, pos: Vec2, size: Vec2) {
+        let rows: Vec<RowKey> = self.rows.keys().copied().collect();
+        for k in rows {
+            if k != key
+                && let Some(w) = self.rows.get(&k)
+            {
+                w.edit(ui).deselect();
+            }
+        }
+        if let Some(w) = self.rows.get(&key) {
+            w.edit(ui).select(pos, size, false, false);
+        }
+        self.anchor = Some((key, pos));
+    }
+
+    /// The drag continues, now over `key`'s row at `pos`. See the module
+    /// doc for the anchor-row shortcut.
+    pub fn extend(&mut self, ui: &mut impl UiRsc, key: RowKey, pos: Vec2, size: Vec2) {
+        let Some((anchor_key, _anchor_pos)) = self.anchor else {
+            return;
+        };
+        if key == anchor_key {
+            if let Some(w) = self.rows.get(&key) {
+                w.edit(ui).select(pos, size, true, false);
+            }
+            return;
+        }
+        let (lo, hi) = if anchor_key < key {
+            (anchor_key, key)
+        } else {
+            (key, anchor_key)
+        };
+        let in_range: Vec<RowKey> = self.rows.range(lo..=hi).map(|(&k, _)| k).collect();
+        for k in &in_range {
+            let Some(w) = self.rows.get(k).copied() else {
+                continue;
+            };
+            if *k == key {
+                // The row under the pointer: partial selection from
+                // whichever of its own edges faces the anchor, extended to
+                // the exact pointer point.
+                let start = if key > anchor_key { Vec2::ZERO } else { size };
+                w.edit(ui).select(start, size, false, false);
+                w.edit(ui).select(pos, size, true, false);
+            } else {
+                w.edit(ui).select_all();
+            }
+        }
+        let outside: Vec<RowKey> = self
+            .rows
+            .keys()
+            .copied()
+            .filter(|k| *k < lo || *k > hi)
+            .collect();
+        for k in outside {
+            if let Some(w) = self.rows.get(&k) {
+                w.edit(ui).deselect();
+            }
+        }
+    }
+
+    /// Whether any row currently has a non-empty selection -- what a fresh
+    /// press consults so `drag` knows whether an early horizontal move is
+    /// "start dragging the selection handle" rather than an ordinary tap.
+    fn has_selection(&self, ui: &mut impl UiRsc) -> bool {
+        self.rows
+            .values()
+            .any(|w| w.edit(ui).text.selected_text().is_some())
+    }
+
+    /// One row's `CursorSense::click_or_drag()` handler, for every row,
+    /// routes its raw pointer data through here rather than calling
+    /// `begin`/`extend` directly -- this is the single place that decides
+    /// whether the gesture pans `list` or extends a selection, so the
+    /// decision is made once per gesture rather than independently by
+    /// whichever row happens to be under the finger this frame (see
+    /// `DragArbiter`'s own doc for why one shared instance, not one per
+    /// row, is what makes that consistent as a drag crosses row
+    /// boundaries).
+    ///
+    /// `pos_row`/`size` are row-local, as `begin`/`extend` want;
+    /// `pos_window` is in window space, since a pan's delta has to stay
+    /// meaningful even when this frame's event landed on a different row
+    /// than the last one.
+    #[allow(clippy::too_many_arguments)]
+    pub fn drag(
+        &mut self,
+        ui: &mut impl UiRsc,
+        list: WeakWidget<List>,
+        key: RowKey,
+        pos_row: Vec2,
+        size: Vec2,
+        pos_window: Vec2,
+        sense: CursorSense,
+        now: Instant,
+    ) {
+        let outcome = match sense {
+            CursorSense::PressStart(_) => {
+                let already_selected = self.has_selection(ui);
+                self.arbiter.press_start(pos_window, now, already_selected);
+                self.arbiter.update(pos_window, now)
+            }
+            CursorSense::PressEnd(_) => {
+                self.arbiter.release();
+                return;
+            }
+            _ => self.arbiter.update(pos_window, now),
+        };
+        match outcome {
+            DragOutcome::Undecided => {}
+            DragOutcome::Pan(dy) => list(ui).scroll(-dy),
+            DragOutcome::SelectStart => self.begin(ui, key, pos_row, size),
+            DragOutcome::SelectExtend => self.extend(ui, key, pos_row, size),
+        }
+    }
+
+    /// The concatenated selected text, in row order, `None` if nothing is
+    /// selected -- what a copy command reads. Joins with a blank line
+    /// between rows, matching how the transcript itself separates them.
+    pub fn selected_text(&self, ui: &mut impl UiRsc) -> Option<String> {
+        let mut parts = Vec::new();
+        for w in self.rows.values() {
+            if let Some(text) = w.edit(ui).text.selected_text() {
+                parts.push(text);
+            }
+        }
+        if parts.is_empty() {
+            None
+        } else {
+            Some(parts.join("\n\n"))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Pure range-membership logic, independent of any widget/render
+    // machinery (the same reasoning `begin`/`extend` apply per-row) --
+    // exercised directly so the "which rows fall between anchor and
+    // current" arithmetic has a test that needs no `UiRenderState`.
+    fn in_range(anchor: RowKey, current: RowKey, keys: &[RowKey]) -> Vec<RowKey> {
+        let (lo, hi) = if anchor < current {
+            (anchor, current)
+        } else {
+            (current, anchor)
+        };
+        keys.iter()
+            .copied()
+            .filter(|k| *k >= lo && *k <= hi)
+            .collect()
+    }
+
+    #[test]
+    fn selection_spans_forward_across_rows() {
+        let keys = [1, 2, 3, 4, 5];
+        assert_eq!(in_range(2, 4, &keys), vec![2, 3, 4]);
+    }
+
+    #[test]
+    fn selection_spans_backward_across_rows() {
+        let keys = [1, 2, 3, 4, 5];
+        assert_eq!(in_range(4, 2, &keys), vec![2, 3, 4]);
+    }
+
+    #[test]
+    fn selection_within_one_row_is_just_that_row() {
+        let keys = [1, 2, 3];
+        assert_eq!(in_range(2, 2, &keys), vec![2]);
+    }
+
+    struct TestRsc {
+        ui: UiData,
+    }
+    impl UiRsc for TestRsc {
+        fn ui(&self) -> &UiData {
+            &self.ui
+        }
+        fn ui_mut(&mut self) -> &mut UiData {
+            &mut self.ui
+        }
+    }
+
+    #[test]
+    fn unregister_forgets_the_row_and_clears_a_matching_anchor() {
+        let mut rsc = TestRsc {
+            ui: UiData::default(),
+        };
+        let field = rsc
+            .ui
+            .widgets
+            .add_strong(TextEdit::new(
+                TextView::new(TextBuffer::new_empty(), TextAttrs::default(), None),
+                EditMode::MultiLine,
+            ))
+            .weak();
+
+        let mut sel = Selection::new();
+        sel.register(5, field);
+        sel.anchor = Some((5, Vec2::ZERO));
+        assert_eq!(sel.rows.len(), 1);
+
+        sel.unregister(5);
+        assert!(sel.rows.is_empty());
+        assert!(sel.anchor.is_none());
+    }
+}

xtask/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "xtask"
+version = "0.1.0"

xtask/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "xtask"
+version = "0.1.0"
+edition = "2024"
+
+# E5 (RUST.md): packages app/shellApp into a signed, installable APK without
+# Gradle driving the assembly (cargo ndk -> javac -> d8 -> aapt2 -> zipalign
+# -> apksigner). No dependencies beyond the standard library: every step
+# below is "run this SDK tool with these arguments and check its exit
+# status," which needs nothing a crate would help with, and every tool
+# invoked is one this project already requires (the NDK, the SDK
+# build-tools, the JDK, `cargo ndk`) -- see AGENTS.md's "new dependencies
+# need a reason."
+[[bin]]
+name = "xtask"
+path = "src/main.rs"

xtask/src/apk.rs

@@ -0,0 +1,484 @@
+//! The pipeline itself: `cargo ndk` -> `javac`/`d8` -> `aapt2` ->
+//! `zipalign` -> `apksigner`, with no Gradle driving *this* file's steps.
+//!
+//! **One disclosed exception**, recorded here rather than left to be
+//! rediscovered: step 3 below still runs `./gradlew
+//! :shellApp:printRuntimeClasspathJars` once, because `app/shellApp`
+//! depends on the `:link` submodule (Kotlin: `ServerStore`/`ServerSettings`,
+//! the Keystore-sealed enrollment, RUST.md's E3 entry explains why that
+//! code is reused rather than re-derived in Rust) and on
+//! `androidx.core:core-ktx` (used at runtime through JNI by
+//! `android-shell`'s `notify.rs`, for `NotificationCompat` and friends).
+//! Both are ordinary Maven/AAR dependency graphs, and reimplementing a
+//! dependency resolver to avoid one Gradle invocation was not a good trade
+//! against "smallest honest route" (RUST.md's E5 box) -- especially since
+//! that one call also compiles `:link`'s Kotlin as a side effect, using
+//! Gradle's own embedded Kotlin compiler. This machine has no standalone
+//! `kotlinc` (checked: not on PATH, not under any SDK), so that side
+//! effect is what answers E3's open question about `kotlinc` -- see
+//! RUST.md's E5 entry for the full account. Nothing past this one call
+//! touches Gradle: `javac`, `d8`, `aapt2`, `zipalign` and `apksigner` are
+//! invoked directly, and the jars this call resolves are consumed as
+//! plain binary inputs to `d8`, exactly like any other pre-built `.jar`.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use crate::keystore::{self, Signer};
+use crate::sdk::{self, Sdk};
+use crate::{Fail, Variant};
+
+const APPLICATION_ID: &str = "com.example.aiapp.shell";
+
+pub fn build(variant: Variant, abis: &[String]) -> Result<PathBuf, Fail> {
+    let repo_root = repo_root()?;
+    let app_dir = repo_root.join("app");
+    let shell_app_dir = app_dir.join("shellApp");
+    let android_shell_dir = repo_root.join("android-shell");
+
+    let sdk = sdk::find()?;
+    sdk::require_ndk_installed(&sdk.root)?;
+    require_cargo_ndk()?;
+
+    let out_dir = repo_root.join("target").join("xtask").join("apk");
+    std::fs::create_dir_all(&out_dir).map_err(|e| {
+        Fail::new(
+            "could not create the xtask output directory",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+
+    println!("==> Building android-shell for {}", abis.join(", "));
+    build_native_libs(&android_shell_dir, &shell_app_dir, &sdk, abis)?;
+
+    println!("==> Resolving the runtime classpath (one Gradle call -- see apk.rs's module doc)");
+    let classpath_jars = runtime_classpath_jars(&app_dir, &sdk)?;
+
+    println!("==> Compiling the Java stub classes");
+    let ca_pem = pinned_ca_pem()?;
+    let classes_jar = compile_java(&out_dir, &shell_app_dir, &sdk, &ca_pem)?;
+
+    println!("==> Dexing");
+    let dex_dir = out_dir.join("dex");
+    dex(&sdk, &classes_jar, &classpath_jars, &dex_dir)?;
+
+    println!("==> Linking resources with aapt2");
+    let base_apk = out_dir.join("base.apk");
+    aapt2_link(&sdk, &shell_app_dir, &base_apk)?;
+
+    println!("==> Merging dex and native libraries");
+    let merged_apk = out_dir.join("merged.apk");
+    merge(&base_apk, &dex_dir, &shell_app_dir, abis, &merged_apk)?;
+
+    println!(
+        "==> Aligning and signing ({})",
+        match variant {
+            Variant::Release => "release key",
+            Variant::Debug => "debug key",
+        }
+    );
+    let signer = match variant {
+        Variant::Release => keystore::release_signer()?,
+        Variant::Debug => keystore::debug_signer()?,
+    };
+    let variant_name = match variant {
+        Variant::Release => "release",
+        Variant::Debug => "debug",
+    };
+    let signed_apk = out_dir.join(format!("ai-app-shell-{variant_name}.apk"));
+    align_and_sign(&sdk, &merged_apk, &signed_apk, &signer)?;
+
+    // Copied into a Gradle-shaped path (`build/outputs/apk/<mode>/*.apk`
+    // under this xtask's own directory) as the final step, purely so Dev
+    // Updater's fixed-pattern APK discovery (`discover.rs`'s
+    // `APK_PATTERNS`, which has no per-component path override) finds it
+    // without needing a change on that side -- `.dev-updater.ron`'s
+    // `shell` component points its `cwd` here. The working files above
+    // stay under `target/xtask/apk/`, an ordinary build-cache location.
+    let published_dir = repo_root.join("xtask/build/outputs/apk").join(variant_name);
+    std::fs::create_dir_all(&published_dir).map_err(|e| {
+        Fail::new(
+            "could not create the published APK directory",
+            &e.to_string(),
+            "check permissions under xtask/build",
+        )
+    })?;
+    let published_apk = published_dir.join(format!("ai-app-shell-{variant_name}.apk"));
+    std::fs::copy(&signed_apk, &published_apk).map_err(|e| {
+        Fail::new(
+            "could not publish the signed APK",
+            &e.to_string(),
+            "check permissions under xtask/build",
+        )
+    })?;
+
+    Ok(published_apk)
+}
+
+fn repo_root() -> Result<PathBuf, Fail> {
+    // xtask's own Cargo.toml is at <repo_root>/xtask/Cargo.toml.
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    manifest_dir.parent().map(Path::to_path_buf).ok_or_else(|| {
+        Fail::new(
+            "could not find the repo root",
+            "CARGO_MANIFEST_DIR has no parent",
+            "run through cargo, not by hand",
+        )
+    })
+}
+
+fn require_cargo_ndk() -> Result<(), Fail> {
+    run_checked(
+        Command::new("cargo").args(["ndk", "--version"]),
+        "cargo-ndk is not installed",
+        "cargo install cargo-ndk",
+    )
+    .map(|_| ())
+}
+
+/// `cargo ndk`'s `-t` target name for each ABI, and `-P 26` -- the API
+/// level every other cross-compile in this repo uses (RUST.md: E0, E1, E3,
+/// I2), kept consistent here rather than picked fresh.
+fn build_native_libs(
+    crate_dir: &Path,
+    shell_app_dir: &Path,
+    sdk: &Sdk,
+    abis: &[String],
+) -> Result<(), Fail> {
+    let jni_libs = shell_app_dir.join("src/main/jniLibs");
+    let mut cmd = Command::new("cargo");
+    cmd.current_dir(crate_dir);
+    cmd.arg("ndk");
+    for abi in abis {
+        cmd.args(["-t", abi]);
+    }
+    cmd.args(["-P", "26", "-o"]).arg(&jni_libs);
+    // Always the release profile for the native library, independent of
+    // the APK's signing variant -- a debug build's Vulkan object-labelling
+    // segfaults this emulator's driver (RUST.md's E1 entry), and there is
+    // no reason for this crate's debug build to be bigger or slower for a
+    // signing choice that has nothing to do with it.
+    cmd.args(["build", "--release", "-p", "android-shell"]);
+    cmd.env("ANDROID_HOME", &sdk.root);
+    cmd.env("ANDROID_SDK_ROOT", &sdk.root);
+    run_checked(
+        &mut cmd,
+        "cargo ndk build failed",
+        "see the compiler output above",
+    )
+    .map(|_| ())
+}
+
+fn runtime_classpath_jars(app_dir: &Path, sdk: &Sdk) -> Result<Vec<PathBuf>, Fail> {
+    let mut cmd = Command::new(app_dir.join("gradlew"));
+    cmd.current_dir(app_dir);
+    cmd.args(["--console=plain", ":shellApp:printRuntimeClasspathJars"]);
+    cmd.env("ANDROID_HOME", &sdk.root);
+    cmd.env("ANDROID_SDK_ROOT", &sdk.root);
+    run_checked(
+        &mut cmd,
+        "resolving app/shellApp's dependencies with Gradle failed",
+        "see the Gradle output above",
+    )?;
+
+    let list_file = app_dir.join("shellApp/build/xtask/runtime-classpath.txt");
+    let contents = std::fs::read_to_string(&list_file).map_err(|e| {
+        Fail::new(
+            "printRuntimeClasspathJars did not produce its output file",
+            &format!("{}: {e}", list_file.display()),
+            "check app/shellApp/build.gradle.kts's printRuntimeClasspathJars task",
+        )
+    })?;
+    Ok(contents
+        .lines()
+        .filter(|l| !l.is_empty())
+        .map(PathBuf::from)
+        .collect())
+}
+
+/// The CA this build pins, found the same way `build-apk.sh` and
+/// `androidApp`/`shellApp`'s Gradle `generatePinnedCa` tasks do:
+/// `$AI_APP_CA`, else `$XDG_CONFIG_HOME/ai-app/certs/ca.pem`.
+fn pinned_ca_pem() -> Result<String, Fail> {
+    let path = std::env::var_os("AI_APP_CA")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            let config_home = std::env::var_os("XDG_CONFIG_HOME")
+                .map(PathBuf::from)
+                .unwrap_or_else(|| {
+                    PathBuf::from(std::env::var_os("HOME").unwrap()).join(".config")
+                });
+            config_home.join("ai-app").join("certs").join("ca.pem")
+        });
+    let pem = std::fs::read_to_string(&path).map_err(|e| {
+        Fail::new(
+            &format!("no CA certificate at {}", path.display()),
+            &e.to_string(),
+            "start ai-server (or app/ui-sandbox.sh) once on this machine first -- it generates the CA this build pins",
+        )
+    })?;
+    let pem = pem.trim().to_string();
+    if !pem.starts_with("-----BEGIN CERTIFICATE-----") {
+        return Err(Fail::new(
+            &format!("{} is not a PEM certificate", path.display()),
+            "missing the BEGIN CERTIFICATE header",
+            "point AI_APP_CA at a valid one",
+        ));
+    }
+    Ok(pem)
+}
+
+fn compile_java(
+    out_dir: &Path,
+    shell_app_dir: &Path,
+    sdk: &Sdk,
+    ca_pem: &str,
+) -> Result<PathBuf, Fail> {
+    let gen_dir = out_dir.join("generated-java");
+    let package_dir = gen_dir.join("com/example/aiapp/shell");
+    std::fs::create_dir_all(&package_dir).map_err(|e| {
+        Fail::new(
+            "could not create the generated-sources directory",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+    // Same shape as shellApp's Gradle `generatePinnedCa` task: the text
+    // block must start immediately after the opening `"""`, or
+    // CertificateFactory stops recognising the "-----BEGIN" preamble (a
+    // real bug this project hit once -- see AGENTS.md's "Things that have
+    // bitten").
+    let pinned_ca_java = format!(
+        "package com.example.aiapp.shell;\n\npublic final class PinnedCa {{\n    private PinnedCa() {{}}\n    public static final String PINNED_CA_PEM = \"\"\"\n{ca_pem}\"\"\";\n}}\n"
+    );
+    std::fs::write(package_dir.join("PinnedCa.java"), pinned_ca_java).map_err(|e| {
+        Fail::new(
+            "could not write PinnedCa.java",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+
+    let classes_dir = out_dir.join("classes");
+    std::fs::create_dir_all(&classes_dir).map_err(|e| {
+        Fail::new(
+            "could not create the classes directory",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+
+    let java_dir = shell_app_dir.join("src/main/java/com/example/aiapp/shell");
+    let mut cmd = Command::new("javac");
+    cmd.args(["-cp"]).arg(&sdk.android_jar);
+    cmd.args(["-d"]).arg(&classes_dir);
+    cmd.arg(java_dir.join("MainActivity.java"));
+    cmd.arg(java_dir.join("NotificationService.java"));
+    cmd.arg(package_dir.join("PinnedCa.java"));
+    run_checked(&mut cmd, "javac failed", "see the compiler output above")?;
+
+    let classes_jar = out_dir.join("classes.jar");
+    let mut cmd = Command::new("jar");
+    cmd.current_dir(&classes_dir);
+    cmd.args(["cf"])
+        .arg(&classes_jar)
+        .args(["-C", "."])
+        .arg(".");
+    run_checked(
+        &mut cmd,
+        "jar failed to package the compiled classes",
+        "see the output above",
+    )?;
+    Ok(classes_jar)
+}
+
+fn dex(
+    sdk: &Sdk,
+    classes_jar: &Path,
+    classpath_jars: &[PathBuf],
+    dex_dir: &Path,
+) -> Result<(), Fail> {
+    std::fs::create_dir_all(dex_dir).map_err(|e| {
+        Fail::new(
+            "could not create the dex output directory",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+    let mut cmd = Command::new(sdk.tool("d8"));
+    cmd.args(["--release", "--min-api"])
+        .arg(sdk::MIN_SDK.to_string());
+    cmd.arg("--lib").arg(&sdk.android_jar);
+    cmd.arg("--output").arg(dex_dir);
+    cmd.arg(classes_jar);
+    cmd.args(classpath_jars);
+    run_checked(&mut cmd, "d8 failed", "see the compiler output above").map(|_| ())
+}
+
+fn aapt2_link(sdk: &Sdk, shell_app_dir: &Path, base_apk: &Path) -> Result<(), Fail> {
+    let manifest_src = shell_app_dir.join("src/main/AndroidManifest.xml");
+    let manifest_text = std::fs::read_to_string(&manifest_src).map_err(|e| {
+        Fail::new(
+            "could not read the manifest",
+            &format!("{}: {e}", manifest_src.display()),
+            "check app/shellApp/src/main/AndroidManifest.xml",
+        )
+    })?;
+    // The checked-in manifest has no `package` attribute -- Gradle injects
+    // it from `android.namespace` during its own manifest merge, which
+    // this pipeline does not run. aapt2 needs it to know what package to
+    // generate resources under.
+    if manifest_text.contains("package=") {
+        return Err(Fail::new(
+            "app/shellApp's manifest already has a package attribute",
+            "aapt2_link() assumes it doesn't and injects one",
+            "update aapt2_link() in xtask/src/apk.rs to stop injecting a second one",
+        ));
+    }
+    let merged_manifest = manifest_text.replacen(
+        "<manifest ",
+        &format!("<manifest package=\"{APPLICATION_ID}\" "),
+        1,
+    );
+    let merged_manifest_path = base_apk.with_file_name("AndroidManifest.merged.xml");
+    std::fs::write(&merged_manifest_path, merged_manifest).map_err(|e| {
+        Fail::new(
+            "could not write the merged manifest",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+
+    let mut cmd = Command::new(sdk.tool("aapt2"));
+    cmd.args(["link", "-o"]).arg(base_apk);
+    cmd.args(["--manifest"]).arg(&merged_manifest_path);
+    cmd.arg("-I").arg(&sdk.android_jar);
+    cmd.args(["--min-sdk-version", &sdk::MIN_SDK.to_string()]);
+    cmd.args(["--target-sdk-version", &sdk::COMPILE_SDK.to_string()]);
+    cmd.args(["--version-code", "1", "--version-name", "1.0"]);
+    run_checked(&mut cmd, "aapt2 link failed", "see the output above").map(|_| ())
+}
+
+fn merge(
+    base_apk: &Path,
+    dex_dir: &Path,
+    shell_app_dir: &Path,
+    abis: &[String],
+    merged_apk: &Path,
+) -> Result<(), Fail> {
+    std::fs::copy(base_apk, merged_apk).map_err(|e| {
+        Fail::new(
+            "could not copy the base APK",
+            &e.to_string(),
+            "check permissions under target/",
+        )
+    })?;
+
+    let mut cmd = Command::new("jar");
+    cmd.current_dir(dex_dir);
+    cmd.args(["uf"])
+        .arg(std::path::absolute(merged_apk).unwrap_or_else(|_| merged_apk.to_path_buf()));
+    cmd.args(["classes.dex"]);
+    run_checked(
+        &mut cmd,
+        "jar failed to add classes.dex to the APK",
+        "see the output above",
+    )?;
+
+    // Android's zip layout wants "lib/<abi>/*.so" at the archive root, but
+    // cargo ndk's `-o` wrote "jniLibs/<abi>/*.so" (matching the Gradle
+    // source-set layout it was pointed at) -- so this stages a "lib/"
+    // directory rather than trying to rename inside the zip.
+    let stage = merged_apk.with_file_name("lib-stage");
+    if stage.exists() {
+        std::fs::remove_dir_all(&stage).ok();
+    }
+    for abi in abis {
+        let so_name = "libandroid_shell.so";
+        let src = shell_app_dir
+            .join("src/main/jniLibs")
+            .join(abi)
+            .join(so_name);
+        if !src.is_file() {
+            return Err(Fail::new(
+                &format!("no native library built for {abi}"),
+                &format!("expected {}", src.display()),
+                "check cargo ndk's output above for that ABI",
+            ));
+        }
+        let dest_dir = stage.join("lib").join(abi);
+        std::fs::create_dir_all(&dest_dir).map_err(|e| {
+            Fail::new(
+                "could not stage the native library",
+                &e.to_string(),
+                "check permissions under target/",
+            )
+        })?;
+        std::fs::copy(&src, dest_dir.join(so_name)).map_err(|e| {
+            Fail::new(
+                "could not stage the native library",
+                &e.to_string(),
+                "check permissions under target/",
+            )
+        })?;
+    }
+    let mut cmd = Command::new("jar");
+    cmd.current_dir(&stage);
+    cmd.args(["uf"])
+        .arg(std::path::absolute(merged_apk).unwrap_or_else(|_| merged_apk.to_path_buf()));
+    cmd.arg("lib");
+    run_checked(
+        &mut cmd,
+        "jar failed to add the native libraries to the APK",
+        "see the output above",
+    )
+    .map(|_| ())
+}
+
+fn align_and_sign(
+    sdk: &Sdk,
+    merged_apk: &Path,
+    final_apk: &Path,
+    signer: &Signer,
+) -> Result<(), Fail> {
+    let aligned_apk = merged_apk.with_file_name("aligned.apk");
+    let mut cmd = Command::new(sdk.tool("zipalign"));
+    cmd.args(["-f", "-p", "4"])
+        .arg(merged_apk)
+        .arg(&aligned_apk);
+    run_checked(&mut cmd, "zipalign failed", "see the output above")?;
+
+    let mut cmd = Command::new(sdk.tool("apksigner"));
+    cmd.args(["sign", "--ks"]).arg(&signer.keystore);
+    cmd.arg("--ks-pass")
+        .arg(format!("pass:{}", signer.password));
+    cmd.arg("--ks-key-alias").arg(&signer.alias);
+    cmd.arg("--out").arg(final_apk);
+    cmd.arg(&aligned_apk);
+    run_checked(
+        &mut cmd,
+        "apksigner failed to sign the APK",
+        "see the output above",
+    )
+    .map(|_| ())
+}
+
+fn run_checked(cmd: &mut Command, what: &str, fix: &str) -> Result<(), Fail> {
+    let status = cmd.status().map_err(|e| {
+        Fail::new(
+            what,
+            &format!("could not run {:?}: {e}", cmd.get_program()),
+            fix,
+        )
+    })?;
+    if status.success() {
+        Ok(())
+    } else {
+        Err(Fail::new(
+            what,
+            &format!("{:?} exited with {status}", cmd.get_program()),
+            fix,
+        ))
+    }
+}

xtask/src/keystore.rs

@@ -0,0 +1,254 @@
+//! The signing key. Mirrors `app/build-apk.sh`'s exact logic for the
+//! release key -- same env vars, same path, same generation recipe -- so
+//! the two tools sign with the *same* key and their outputs can
+//! `adb install -r` over each other. That is the whole point of E5's pass
+//! condition: the key has to be identical, not merely present.
+
+use std::path::PathBuf;
+use std::process::Command;
+
+use crate::Fail;
+
+pub struct Signer {
+    pub keystore: PathBuf,
+    pub password: String,
+    pub alias: String,
+}
+
+/// The release key at `$AI_APP_KEYSTORE` or
+/// `$XDG_CONFIG_HOME/ai-app/release.jks` (`~/.config/ai-app/release.jks` by
+/// default) -- generated with `keytool` if it doesn't exist yet, exactly as
+/// `build-apk.sh` does, so either tool can run first on a fresh machine.
+pub fn release_signer() -> Result<Signer, Fail> {
+    let keystore = std::env::var_os("AI_APP_KEYSTORE")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            let config_home = std::env::var_os("XDG_CONFIG_HOME")
+                .map(PathBuf::from)
+                .unwrap_or_else(|| {
+                    PathBuf::from(std::env::var_os("HOME").unwrap()).join(".config")
+                });
+            config_home.join("ai-app").join("release.jks")
+        });
+    let alias = "ai-app".to_string();
+    let password_file = keystore.with_extension("jks.password");
+
+    if keystore.is_file() {
+        let password = std::fs::read_to_string(&password_file)
+            .map_err(|e| {
+                Fail::new(
+                    "release key exists but its password file is unreadable",
+                    &format!("{}: {e}", password_file.display()),
+                    "restore the password file, or delete both and let this regenerate them",
+                )
+            })?
+            .trim()
+            .to_string();
+        return Ok(Signer {
+            keystore,
+            password,
+            alias,
+        });
+    }
+
+    let keytool = which_keytool()?;
+    if let Some(parent) = keystore.parent() {
+        std::fs::create_dir_all(parent).map_err(|e| {
+            Fail::new(
+                "could not create the keystore's directory",
+                &format!("{}: {e}", parent.display()),
+                "check permissions on that path",
+            )
+        })?;
+    }
+    let password = random_password();
+    write_owner_only(&password_file, format!("{password}\n").as_bytes())?;
+
+    let status = Command::new(&keytool)
+        .args(["-genkeypair", "-keystore"])
+        .arg(&keystore)
+        .args([
+            "-alias",
+            &alias,
+            "-keyalg",
+            "RSA",
+            "-keysize",
+            "2048",
+            "-validity",
+            "10000",
+        ])
+        .args(["-storepass", &password, "-keypass", &password])
+        .args(["-dname", "CN=ai-app"])
+        .status()
+        .map_err(|e| {
+            Fail::new(
+                "failed to run keytool",
+                &format!("{}: {e}", keytool.display()),
+                "set JAVA_HOME to the JDK Gradle uses",
+            )
+        })?;
+    if !status.success() {
+        return Err(Fail::new(
+            "keytool exited with an error while generating the release key",
+            &format!("status: {status}"),
+            "check the keytool output above",
+        ));
+    }
+    // Owner-only, matching build-apk.sh -- this key is what the phone
+    // recognises the app by, so it never goes in the repo and it stays
+    // unreadable to anything else on this machine.
+    set_owner_only(&keystore)?;
+
+    Ok(Signer {
+        keystore,
+        password,
+        alias,
+    })
+}
+
+/// The conventional Android debug key (`~/.android/debug.keystore`,
+/// well-known password `android`, alias `androiddebugkey`) -- generated on
+/// first use exactly the way Android Studio and Gradle's own debug signing
+/// config do, so a `--debug` build here needs no setup and never touches
+/// the real release key.
+pub fn debug_signer() -> Result<Signer, Fail> {
+    let home = PathBuf::from(std::env::var_os("HOME").ok_or_else(|| {
+        Fail::new(
+            "no $HOME set",
+            "the debug keystore lives under ~/.android",
+            "set $HOME",
+        )
+    })?);
+    let keystore = home.join(".android").join("debug.keystore");
+    let alias = "androiddebugkey".to_string();
+    let password = "android".to_string();
+
+    if !keystore.is_file() {
+        let keytool = which_keytool()?;
+        std::fs::create_dir_all(keystore.parent().unwrap()).map_err(|e| {
+            Fail::new(
+                "could not create ~/.android",
+                &format!("{e}"),
+                "check permissions on your home directory",
+            )
+        })?;
+        let status = Command::new(&keytool)
+            .args(["-genkeypair", "-keystore"])
+            .arg(&keystore)
+            .args([
+                "-alias",
+                &alias,
+                "-keyalg",
+                "RSA",
+                "-keysize",
+                "2048",
+                "-validity",
+                "10000",
+            ])
+            .args(["-storepass", &password, "-keypass", &password])
+            .args(["-dname", "CN=Android Debug,O=Android,C=US"])
+            .status()
+            .map_err(|e| {
+                Fail::new(
+                    "failed to run keytool",
+                    &format!("{}: {e}", keytool.display()),
+                    "set JAVA_HOME to the JDK Gradle uses",
+                )
+            })?;
+        if !status.success() {
+            return Err(Fail::new(
+                "keytool exited with an error while generating the debug key",
+                &format!("status: {status}"),
+                "check the keytool output above",
+            ));
+        }
+    }
+    Ok(Signer {
+        keystore,
+        password,
+        alias,
+    })
+}
+
+fn which_keytool() -> Result<PathBuf, Fail> {
+    if let Some(java_home) = std::env::var_os("JAVA_HOME") {
+        let candidate = PathBuf::from(java_home).join("bin").join("keytool");
+        if candidate.is_file() {
+            return Ok(candidate);
+        }
+    }
+    if Command::new("keytool").arg("-help").output().is_ok() {
+        return Ok(PathBuf::from("keytool"));
+    }
+    Err(Fail::new(
+        "no keytool available to generate the release key",
+        "checked $JAVA_HOME/bin/keytool and keytool on PATH",
+        "set JAVA_HOME to the JDK Gradle uses, or set AI_APP_KEYSTORE to an existing key",
+    ))
+}
+
+fn random_password() -> String {
+    // No dependency on `rand`: /dev/urandom is what build-apk.sh's `head -c
+    // 24 /dev/urandom | base64` reads too, so this reproduces exactly the
+    // same recipe without shelling out to head/base64/tr for it.
+    let mut bytes = [0u8; 24];
+    std::fs::File::open("/dev/urandom")
+        .and_then(|mut f| std::io::Read::read_exact(&mut f, &mut bytes))
+        .expect("/dev/urandom must be readable to generate a signing key password");
+    base64_no_padding(&bytes)
+}
+
+fn base64_no_padding(bytes: &[u8]) -> String {
+    const ALPHABET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut out = String::new();
+    for chunk in bytes.chunks(3) {
+        let b0 = chunk[0] as u32;
+        let b1 = *chunk.get(1).unwrap_or(&0) as u32;
+        let b2 = *chunk.get(2).unwrap_or(&0) as u32;
+        let n = (b0 << 16) | (b1 << 8) | b2;
+        out.push(ALPHABET[(n >> 18 & 0x3f) as usize] as char);
+        out.push(ALPHABET[(n >> 12 & 0x3f) as usize] as char);
+        if chunk.len() > 1 {
+            out.push(ALPHABET[(n >> 6 & 0x3f) as usize] as char);
+        }
+        if chunk.len() > 2 {
+            out.push(ALPHABET[(n & 0x3f) as usize] as char);
+        }
+    }
+    // build-apk.sh strips '/', '+' and '=' from its password (tr -d
+    // '/+='), so the value never needs quoting when it is passed as a
+    // command-line argument later.
+    out.retain(|c| c != '/' && c != '+' && c != '=');
+    out
+}
+
+#[cfg(unix)]
+fn write_owner_only(path: &std::path::Path, contents: &[u8]) -> Result<(), Fail> {
+    use std::os::unix::fs::OpenOptionsExt;
+    std::fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(true)
+        .mode(0o600)
+        .open(path)
+        .and_then(|mut f| std::io::Write::write_all(&mut f, contents))
+        .map_err(|e| {
+            Fail::new(
+                "could not write the keystore password file",
+                &format!("{}: {e}", path.display()),
+                "check permissions on that directory",
+            )
+        })
+}
+
+#[cfg(unix)]
+fn set_owner_only(path: &std::path::Path) -> Result<(), Fail> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).map_err(|e| {
+        Fail::new(
+            "could not restrict the keystore's permissions",
+            &format!("{}: {e}", path.display()),
+            "chmod 600 it by hand",
+        )
+    })
+}

xtask/src/main.rs

@@ -0,0 +1,115 @@
+//! `cargo xtask apk` -- E5 (RUST.md): packages `app/shellApp` into a
+//! signed, installable APK with no Gradle in the packaging step itself.
+//! `cargo ndk` cross-compiles `android-shell`; `javac`/`d8` turn its two
+//! Java stub classes (plus the generated pinned-CA constant) into dex;
+//! `aapt2` compiles the manifest into `resources.arsc`; the dex and native
+//! libraries are merged into that base APK with `jar`; `zipalign` and
+//! `apksigner` finish it. See `apk.rs`'s module doc for what "no Gradle in
+//! the packaging step" does and does not cover -- one disclosed exception.
+//!
+//! Usage: `cargo xtask apk [--release|--debug] [--abi ABI]...`
+
+mod apk;
+mod keystore;
+mod sdk;
+
+use std::fmt;
+use std::process::ExitCode;
+
+/// A failure a person acts on: what went wrong, what this process actually
+/// saw, and the next thing to try. Matches CODE_RULES's "a failure message
+/// names the thing, the cause, and the fix."
+pub struct Fail {
+    what: String,
+    cause: String,
+    fix: String,
+}
+
+impl Fail {
+    pub fn new(what: &str, cause: &str, fix: &str) -> Self {
+        Fail {
+            what: what.to_string(),
+            cause: cause.to_string(),
+            fix: fix.to_string(),
+        }
+    }
+}
+
+impl fmt::Display for Fail {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}\n  cause: {}\n  fix:   {}",
+            self.what, self.cause, self.fix
+        )
+    }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum Variant {
+    /// Signed with `~/.config/ai-app/release.jks`, the same key
+    /// `build-apk.sh` uses for `androidApp` -- what E5's pass condition
+    /// needs, since installing over an existing app requires a matching
+    /// signature.
+    Release,
+    /// Signed with the standard Android debug keystore
+    /// (`~/.android/debug.keystore`, well-known password, generated if
+    /// missing the same way Gradle would), for a fast local loop that
+    /// doesn't touch the real signing key.
+    Debug,
+}
+
+fn main() -> ExitCode {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let Some(("apk", rest)) = args.split_first().map(|(cmd, rest)| (cmd.as_str(), rest)) else {
+        eprintln!("usage: cargo xtask apk [release|debug] [--abi ABI]...");
+        return ExitCode::FAILURE;
+    };
+
+    let mut variant = Variant::Release;
+    let mut abis: Vec<String> = Vec::new();
+    let mut i = 0;
+    while i < rest.len() {
+        match rest[i].as_str() {
+            // Bare "release"/"debug" is `.dev-updater.ron`'s interface
+            // (`ByMode::One` appends the chosen mode as the build
+            // command's last argument -- the same convention
+            // `app/build-apk.sh`'s `${1:-release}` uses); the `--`-prefixed
+            // spellings are for typing this by hand.
+            "release" | "--release" => variant = Variant::Release,
+            "debug" | "--debug" => variant = Variant::Debug,
+            "--abi" => {
+                i += 1;
+                match rest.get(i) {
+                    Some(abi) => abis.push(abi.clone()),
+                    None => {
+                        eprintln!("--abi needs a value (e.g. arm64-v8a, x86_64)");
+                        return ExitCode::FAILURE;
+                    }
+                }
+            }
+            other => {
+                eprintln!("unknown argument: {other}");
+                return ExitCode::FAILURE;
+            }
+        }
+        i += 1;
+    }
+    if abis.is_empty() {
+        // arm64-v8a for a real phone, x86_64 for this machine's emulator --
+        // the two ABIs every other experiment in RUST.md has actually run
+        // on. `--abi` overrides either way.
+        abis = vec!["arm64-v8a".to_string(), "x86_64".to_string()];
+    }
+
+    match apk::build(variant, &abis) {
+        Ok(path) => {
+            println!("==> Built {}", path.display());
+            ExitCode::SUCCESS
+        }
+        Err(fail) => {
+            eprintln!("xtask: {fail}");
+            ExitCode::FAILURE
+        }
+    }
+}

xtask/src/sdk.rs

@@ -0,0 +1,130 @@
+//! Finds the Android SDK/NDK pieces the packaging pipeline needs, the same
+//! way `app/android-env.sh` and `app/build-apk.sh` do: `$ANDROID_HOME`, then
+//! `$ANDROID_SDK_ROOT`, then `~/Android/Sdk`. Kept in one place because
+//! every step in `main.rs` needs at least one of these paths, and a
+//! mismatch between them (an `android.jar` from one SDK, `d8` from
+//! another) fails in ways that point at the wrong cause.
+
+use std::path::{Path, PathBuf};
+
+use crate::Fail;
+
+/// compileSdk / targetSdk, matching `app/shellApp/build.gradle.kts`. Not
+/// read from that file -- if the two drift, `android.jar` or a platform
+/// tools directory goes missing and the error below names the exact path
+/// that wasn't there, which is no harder to act on than a parsed number
+/// would have been.
+pub const COMPILE_SDK: u32 = 37;
+pub const MIN_SDK: u32 = 24;
+
+pub struct Sdk {
+    pub root: PathBuf,
+    pub build_tools: PathBuf,
+    pub android_jar: PathBuf,
+}
+
+impl Sdk {
+    pub fn tool(&self, name: &str) -> PathBuf {
+        self.build_tools.join(name)
+    }
+}
+
+pub fn find() -> Result<Sdk, Fail> {
+    let root = std::env::var_os("ANDROID_HOME")
+        .or_else(|| std::env::var_os("ANDROID_SDK_ROOT"))
+        .map(PathBuf::from)
+        .filter(|p| p.is_dir())
+        .or_else(|| {
+            let home = std::env::var_os("HOME").map(PathBuf::from)?;
+            let candidate = home.join("Android/Sdk");
+            candidate.is_dir().then_some(candidate)
+        })
+        .ok_or_else(|| {
+            Fail::new(
+                "no Android SDK found",
+                "checked $ANDROID_HOME, $ANDROID_SDK_ROOT and ~/Android/Sdk",
+                "set ANDROID_HOME, or run app/android-env.sh once to install one",
+            )
+        })?;
+
+    let build_tools = latest_build_tools(&root)?;
+    let android_jar = root
+        .join("platforms")
+        .join(format!("android-{COMPILE_SDK}.0"))
+        .join("android.jar");
+    let android_jar = if android_jar.is_file() {
+        android_jar
+    } else {
+        // Some installs use the bare "android-37" directory name instead of
+        // "android-37.0" -- both exist on this machine's SDK depending on
+        // how the platform was installed, so try the other spelling before
+        // giving up.
+        let alt = root
+            .join("platforms")
+            .join(format!("android-{COMPILE_SDK}"))
+            .join("android.jar");
+        if alt.is_file() {
+            alt
+        } else {
+            return Err(Fail::new(
+                &format!("no android.jar for API {COMPILE_SDK}"),
+                &format!("checked {} and {}", android_jar.display(), alt.display()),
+                &format!("install it: android sdk install \"platforms/android-{COMPILE_SDK}.0\""),
+            ));
+        }
+    };
+
+    Ok(Sdk {
+        root,
+        build_tools,
+        android_jar,
+    })
+}
+
+fn latest_build_tools(sdk_root: &Path) -> Result<PathBuf, Fail> {
+    let dir = sdk_root.join("build-tools");
+    let mut versions: Vec<(Vec<u32>, PathBuf)> = std::fs::read_dir(&dir)
+        .map_err(|e| {
+            Fail::new(
+                "no build-tools directory in the Android SDK",
+                &format!("{}: {e}", dir.display()),
+                "install one: android sdk install \"build-tools;37.0.0\"",
+            )
+        })?
+        .filter_map(|entry| entry.ok())
+        .filter(|entry| entry.path().is_dir())
+        .filter_map(|entry| {
+            let name = entry.file_name();
+            let name = name.to_str()?;
+            let parts: Vec<u32> = name.split('.').filter_map(|p| p.parse().ok()).collect();
+            (!parts.is_empty()).then_some((parts, entry.path()))
+        })
+        .collect();
+    versions.sort();
+    versions.pop().map(|(_, path)| path).ok_or_else(|| {
+        Fail::new(
+            "no usable build-tools version found",
+            &format!("{} has no version-numbered subdirectory", dir.display()),
+            "install one: android sdk install \"build-tools;37.0.0\"",
+        )
+    })
+}
+
+/// The NDK version `cargo ndk` should find on its own by scanning
+/// `$ANDROID_HOME/ndk/*` -- this just checks one exists, so a missing NDK
+/// is reported before `cargo ndk` does it with a less specific message.
+pub fn require_ndk_installed(sdk_root: &Path) -> Result<(), Fail> {
+    let ndk_dir = sdk_root.join("ndk");
+    let has_one = std::fs::read_dir(&ndk_dir)
+        .map(|entries| entries.filter_map(|e| e.ok()).any(|e| e.path().is_dir()))
+        .unwrap_or(false);
+    if has_one {
+        Ok(())
+    } else {
+        Err(Fail::new(
+            "no NDK installed under the Android SDK",
+            &format!("{} has no version subdirectory", ndk_dir.display()),
+            "install one: android sdk install \"ndk;29.0.14206865\"",
+        ))
+    }
+}