ai-app/docs/DECISIONS.md

# Decisions taken for Iris to review

Short list of design choices made by the design agent without asking, so
they can be judged and reversed later. Detail lives in RUST.md (and IRIS.md
for iris API changes); this file is only the summary. Newest first. Items
marked **DEFERRED** are ones the agent chose not to decide alone.

## 2026-09-06 (how a markdown block looks, P1a)

- **A table is drawn as padded monospace columns, not as a grid.** Your
  call to reverse. Compose draws a real grid: cells on a tint, each
  column with a 136dp floor, scrolling sideways when there are too many.
  iris has no grid widget, and building one would be a widget per
  markdown feature -- which is the thing the block model exists to avoid.
  In a monospace face a character count *is* a pixel width, so padding
  each cell to its column's width is alignment, the widths are still
  measured from the cells, and a table that is too wide pans sideways
  through the same mechanism a code fence already uses. The header is
  bold with a rule under it, and a long cell wraps inside its column
  (capped at 28 characters, which is what fits three columns across a
  phone). **What it trades:** no cell borders, and a table looks like
  code rather than like a table. If you want the grid, it is a new widget
  and it is a day's work.
- **Three block frames, and only three.** A heading, paragraph and list
  are plain text with spans; a fence and a table are a rounded panel that
  does not wrap; a quote is a bar with the text padded past it.
  Everything else markdown says is expressed in span styles, which cost
  no widgets and no layout nodes. So a new markdown feature is a span,
  not a widget.
- **A list's marker is part of the text, so a wrapped item's second line
  returns to the left margin.** Compose keeps it indented by giving the
  marker its own column. Doing the same here needs per-line indent in
  iris's text attributes; it is written down rather than done, because
  the list items in a real reply are usually one line.
- **A link opens on a tap and not on the end of a drag.** A press that
  panned the transcript past a link, or that held long enough to start a
  selection, does not follow it -- decided by the same gesture machine
  that decides pan-versus-select, so there is one rule rather than two
  that can disagree.

## 2026-09-06 (composer scroll and the streaming block model)

- **A streamed message becomes a column of per-block widgets.** Decided by
  the design agent; recorded here because it is the shape of every message
  on screen. A transcript row is one `TextEdit` today, so a streamed delta
  re-shapes the entire message through parley on every event -- the stream
  phase is the one place iris is behind Compose on your phone (p50 18.2ms
  vs 13.4ms). A row becomes a column of one widget per markdown block
  (paragraph, heading, fence, list, table) and a delta replaces only the
  last block, keeping every earlier block's layout. **Rejected:** splitting
  parley's layout at block boundaries inside one text widget (couples
  iris's text widget to markdown structure, and parley has no incremental
  API), and caching shaped runs per paragraph inside `TextEdit` (a second
  cache with its own invalidation beside the glyph cache). Chosen because
  P1's markdown block model is needed anyway, so the split happens once, in
  `client-core`, and iris stays a text renderer. **Status: designed, not
  built** -- this pass spent its budget on the composer's three layout
  defects; docs/RUST.md has the design and the pass conditions.
- **The composer's overflowing text now scrolls on a finger**, capped at
  six lines and clipped to the bar. Reverses the "still does not scroll"
  item below.
- **A widget may not report a `dp` length** (see IRIS.md). A rule for
  widget authors, enforced by a `debug_assert!`; nothing changes for app
  code.

## 2026-09-06 (stale-primitives and touch-scroll pass)

- **A vertical drag inside a focused composer now scrolls rather than
  selects.** Android's own `EditText` does this -- a vertical drag scrolls
  the field, and only a long press starts a selection -- so the platform
  decided it. What it costs: you can no longer drag straight down inside
  the composer to select several lines of what you typed; use a long press
  and then drag, or drag sideways. Say if that trade is wrong for you.
- **`Scroll` gets a finger pan but no fling.** `List` flings; a scroll area
  does not, because it has no per-frame tick to animate one and the areas
  it wraps are at most a screenful (Android does not fling a six-line text
  box either). Easy to add later if a scroll area ever wraps something long.
- **The composer still does not scroll its overflowed text**, though the
  mechanism it needs is now in place. Wrapping the field in `.scrollable()`
  was tried and reverted the same day: `Scroll` measures its content and
  container against the *window*, so inside the `MaxSize` that caps the
  composer at six lines the two are in different spaces and the field pans
  itself entirely out of the bar (measured on the emulator with 474
  characters in it -- the bar collapsed to its padding). Fixing that means
  `Scroll` measuring against its own offered box, which is a change to a
  widget the transcript and the bench shell both use, so it is its own
  piece of work rather than a rider on this one.

## 2026-09-06 (defect pass)

- **The keyboard-open diagnostics overlay is gone; the capture only
  logs now.** It was added when `on_insets_changed` was not firing at all
  and there was no way to get a report off the phone. It fires reliably
  since the activity went edge-to-edge -- and what that looks like in
  use is a full-screen report covering the app **every time the keyboard
  opens**, with its own Copy/Close buttons sitting underneath the
  keyboard, so it cannot be dismissed (reproduced on the emulator this
  pass: two `tap 'CLOSE'` runs left it up). An interruption for something
  nobody asked for, over the app you are trying to type into. The named
  `Diagnostics` button still shows the same text on demand, and the new
  `iris surface:`/`iris insets:` log lines carry the lifecycle a `logcat`
  pull needs. Reversible: `capture_keyboard_diagnostics` is still the one
  place this is decided, and `PlatformHandle::show_diagnostics_overlay`
  is still there.

- **The bench shell's report pane is sized to its report, not to a share
  of the window.** It held `.height(rest(1))` beside the transcript's
  `rest(2)`, so an *empty* `TextEdit` reserved a third of every screen --
  which is what Iris's "the app does not start with keyboard spacing
  correct" screenshot was showing, with the composer two thirds down and
  black below it. It is `.max_height(dp(260))` now and sits above the
  transcript rather than under the composer, where it was eating the
  navigation-bar clearance. Cost: a filled report is clipped at 260dp
  rather than scrolling (a `Scroll` there drew itself off the top of the
  screen, since `Scroll` pins to the end of its content and reports its
  content's full length to the parent -- worth fixing in `Scroll`, not
  worked around here). "Copy report" and `logcat` still have the whole
  thing.

## 2026-09-05

- **iris no longer asks every device for compute-shader limits it never
  uses.** `adapter.request_device` (both `iris/src/android/render.rs` and
  `iris/src/default/render.rs`) used `Limits::default()` plus an override
  for `max_buffer_size`, and `Limits::default()` unconditionally requests
  desktop-tier compute limits (`max_compute_workgroups_per_dimension:
  65535`, per `wgpu_types`) even though nothing in `iris`/`iris-core`
  creates a `ComputePipeline` or writes a `@compute` shader stage —
  confirmed by grepping the whole tree, not assumed. That crashed
  `request_device` outright on the Android emulator's software GL path
  (`EMU_GPU=software`, `--features force-gles`): SwiftShader's GL reports
  itself as OpenGL ES 3.0, which has no compute shaders at all, so the
  adapter's real limit is 0 against the unconditional request for 65535 —
  `RUST.md`'s "Software mode ... crashes for a third, different reason,"
  2026-09-05, earlier today. The same would happen on any real
  GLES-3.0-only Android device, not just the emulator. Fixed by a new
  `iris_core::device_limits()` (`iris/core/src/render/mod.rs`), shared by
  both platform backends so the two requests cannot drift, that zeros the
  six `max_compute_*` fields explicitly rather than switching to a
  downlevel `Limits` preset — `Limits::downlevel_webgl2_defaults()` was
  considered and rejected: it also zeros
  `max_storage_buffers_per_shader_stage`, and `shader.wgsl`'s vertex stage
  reads four `var<storage>` buffers (rects, glyphs, masks, move_offsets),
  so that preset would trade the compute crash for a bind-group-layout
  one on the same downlevel hardware this is meant to support. No
  capability check or fallback path was needed since nothing is being
  disabled — the request is simply narrowed to what the pipeline actually
  uses. `rigs/gpu-probe`'s own mirrored limits (it is deliberately its own
  crate, not a workspace member, so it cannot call `device_limits()`
  directly) were updated to match, and confirm `IRIS DEVICE: ok` against
  this VM's own Vulkan and GL adapters. **Not verified this pass**: the
  specific SwiftShader-ES-3.0 crash this fixes, on-device — the
  `EMU_GPU=software` cold boot this needs would have force-restarted this
  checkout's emulator while another session was actively running its own
  app on it (`com.example.aiapp` had window focus at the time), so it was
  left for a pass when the emulator is free rather than disrupting that
  session. Everything reachable without the emulator is clean: `cargo
  fmt`/`clippy --workspace --all-targets`/`test --workspace`, `cargo ndk
  build`/`clippy` for `iris-android-app` with `force-gles`, and
  `gpu-probe` against this VM's own Vulkan and GL(ES 3.2, which still has
  compute and so would not have reproduced the crash even before this
  fix — not a substitute for the real ES-3.0 test).

- **P0's Compose half is built and smoke-tested on the emulator** — the
  `bench` build type, the shared `app/bench-fixture/` transcript, and an
  in-process fake backend (`BenchFixture.kt`/`BenchNetwork.kt`) that
  answers `TranscriptSource`/`EventStream` from an in-memory event log
  instead of a real server, so the fold and paging under test are the real
  ones. Full account, the smoke run's report, and what is deliberately
  left (the iris half, the real on-phone runs) are in RUST.md's P0 box.
  Not a decision to review so much as the gate itself now being runnable —
  flagged here because it is the first half of something Iris explicitly
  asked to see before P1.

- **P0's iris half is also built and smoke-tested on the emulator,
  2026-09-05.** A new `bench` Cargo feature on `iris-android-app`, on top
  of `transcript-screen`: the same checked-in fixture (`include_str!`, no
  asset pipeline needed), the same 24-swipe scroll loop animated through
  `List::scroll` and the same 400-event/20s streaming phase through
  `fold_event`, "Run benchmark"/"Copy report" as named accessible
  controls, and the same three added report fields (process CPU time,
  peak RSS, battery current) via direct JNI calls
  (`bench_jni.rs::PlatformHandle`) since `android_view` has no
  `BatteryManager`/`ClipboardManager` wrapper of its own. One small public
  API addition to get there: `AndroidAppState::platform_ready` (`IRIS.md`),
  a default-no-op lifecycle hook handing an implementor a `JavaVM` +
  `GlobalRef` it can call Java through from any thread. Packaged with a
  new `release` build type on `iris-android-app`'s own Gradle project
  (there was previously only `debug`), signed with the same key
  `app/build-apk.sh` generates. Smoke run and the full report are in
  RUST.md's P0 box; not attempted this pass: the real on-phone runs and
  Iris's pass/fail call, which is the actual gate.

- **The intermittent touch-scroll dropout is root-caused and fixed: a
  missed `ACTION_DOWN` hit-test, not the previously-suspected coalesced
  first `ACTION_MOVE`.** Diagnosed by temporary logcat tracing of every
  touch event, `DragArbiter` state transition and `Selection::drag`
  dispatch (removed once confirmed), reproduced on this checkout's own
  emulator against a real sandbox session. The trace showed the actual
  mechanism: a gesture's `ACTION_DOWN` lands wherever the finger actually
  is, which is not guaranteed to fall inside the same row-local sensor
  region a later `ACTION_MOVE` in the same gesture lands in (a row's own
  padding/gap, or its non-selectable sender-name header, is
  pointer-transparent to `iris::sense::CursorSense`). When that happens,
  the widget that ends up handling the gesture never saw `PressStart`, so
  `DragArbiter` sits in `Idle` — which answers every subsequent frame with
  `Undecided` and has no way to tell "no press is happening" from "a press
  is happening but I missed its start," so it never recovers on its own
  for the rest of that gesture. One real trace showed exactly this: touch
  `Down`/`Move`/`Up` all delivered correctly, but zero `PressStart`
  reaching the arbiter, `state=Idle` unchanged from first frame to last.
  Fixed at the call site that has the context to recover
  (`iris::transcript_ui::selection::Selection::drag`,
  `iris/transcript-ui/src/selection.rs`): a new `DragArbiter::is_idle()`
  (`iris/src/sense.rs`) lets it notice a `Pressing` frame arriving with the
  arbiter still `Idle` — which can only mean a missed `PressStart`, since a
  `Pressing` sense requires the button to genuinely be down — and start the
  press there instead of where it was missed. Three new unit tests in
  `sense.rs`'s `drag_arbiter_tests` and one in `transcript-ui`'s
  `selection::tests` (the latter fails on the code before this fix).
  Commit follows. Not the same failure the earlier pass's `DECISIONS.md`
  DEFERRED item speculated about (a coalesced first `ACTION_MOVE` skipping
  slop detection) — that hypothesis is now ruled out; the arbiter's own
  slop/long-press logic was never wrong. RUST.md's I5 box,
  "Touch-scroll dropout root-caused, 2026-09-05" has the full trace.
- **P0, a phone benchmark gate before any porting, asked for by Iris
  2026-09-05**: "before P1 I'd like to see benchmarks & also maybe stress
  test on my own phone ... If it doesn't match compose reasonably well then
  I don't think I'd wanna continue." Design (RUST.md's P0 box has the
  detail): the same embedded synthetic fixture in both apps with no server
  needed; the same scripted scroll loop then a streaming phase, run
  programmatically since the phone has no usable system tracing and no
  agent can drive it; the same report from both (frames, janky %, p50/p90/
  p99, process CPU time, peak RSS, battery current where readable) with a
  copy button; the iris app under its own id and the Compose one as a new
  `bench` build type with an id suffix, so neither replaces her production
  install; two arm64 APKs plus instructions delivered under `~/host/bench/`.
  The gate is hers: iris within a reasonable margin of Compose release on
  p50, p99 and CPU time, no crashes, no visible stutter. If it fails, the
  port stops.
- **The rest of the port is one UI crate, `iris/app-ui`, grown out of
  `iris/transcript-ui` rather than started beside it.** It holds a
  `Screen` enum plus a back stack — the Rust equivalent of `AppRoot.kt`'s
  `when` — and `iris/desktop-app`/`iris/android-app` become thin entry
  points over it. Chosen over a fresh crate because `transcript-ui`
  already has the right generic shape (`Rsc: HasEvents` +
  `Rsc::State: FocusHost`) and the `client-core`/`event-model` path
  dependencies every later screen needs, so growing it in place is the
  smaller diff. Platform-only code (notification service, share target,
  QR scanner, Keystore token, deep-link enrolment) stays in the E3/E5
  Java shell (`android-shell/` + `app/shellApp`) rather than moving into
  this crate, since none of it is a screen. The Android APK is built by
  `cargo xtask apk` (E5), merging the app-ui cdylib into the E3 shell so
  there is one app rather than a demo shell plus a service shell.
  `app/androidApp` (the Compose app) stays untouched and is the baseline
  every step is measured against, until parity is reached (P7 decides
  the switch, and is itself a load-bearing decision left to Iris). Order
  is by risk to the daily-use path: session screen first (P1, where
  every hard behaviour already lives), then the shell merge and a real
  phone install (P2), then root tabs (P3), the explorer (P4),
  settings/enrolment (P5), desktop parity (P6), and the cutover itself
  (P7). Full plan: RUST.md's "The port, in order (decided 2026-09-05)".
- **iris gets its own measured frame report, rather than waiting on a
  `dumpsys`/`gfxinfo` answer that cannot see a `SurfaceView`'s GPU-drawn
  frames.** `iris_core::FrameReport` (`iris/core/src/render/frame_report.rs`)
  times each frame's wall clock from the same point `render()`'s redraw
  starts to just after `queue.submit` + `present()` — the span Compose's
  own render report and `gfxinfo` both count — into a fixed 4096-entry
  ring (no allocation per frame; `report()` is the only place that
  allocates, and only on a button tap). The report gives total frames,
  janky % over the same 16.7ms budget `gfxinfo` uses, P50/P90/P99 and the
  worst, plus a reset. Exposed the way the Compose app's copy-button
  report already is: two named controls ("Frame report", "Reset frame
  report") on the transcript screen, tappable by accessibility name via
  `ui-trace`, logging under this crate's fixed `android_logger` tag
  (`iris-android-app`) so a script can grep `"iris frame report"` the way
  `transcript-bench.sh` greps `"ai-app render report"`. The report's own
  `Display` line says plainly that it measures up to the `present()` call
  returning, not GPU/compositor completion — wgpu's `present()` is not
  fenced against either, so presenting that span as "time to reach the
  screen" would be a measured-looking number that is actually inferred,
  which the standing UI rule forbids.
- **`ui-trace` gains a hold-then-drag gesture, additive, in
  `emulator-tools`.** Neither of its two existing actions can produce
  "hold stationary for `LONG_PRESS`, then move without lifting" — `tap`
  has no hold and `swipe X1 Y1 X2 Y2 MS` interpolates motion across its
  whole duration from t=0. A new action presses, waits, then moves to a
  second point and releases as one continuous touch (raw
  `sendevent`/`MotionEvent` injection, extending whatever mechanism the
  existing `swipe` already uses), so `DragArbiter`'s pan-vs-select rule
  (`iris/src/sense.rs`, already covered by 8 unit tests against a
  synthetic clock) can finally be driven on a real device instead of only
  in a test harness.
- **Touch drag on a transcript row follows Android's own rule**: a vertical
  drag pans the list immediately; a stationary press held 500 ms starts a
  text selection which further dragging extends; a horizontal drag while
  something is already selected extends that selection without the wait.
  One `DragArbiter` per list decides it (`iris/src/sense.rs`). Chosen over a
  "text layer always wins" or "list always wins" rule because either loses
  one of the two gestures a reader expects.
- **E4's desktop shape is a new `iris/desktop-app` crate**: a winit window
  holding `transcript-ui`'s screen beside a session list, talking to a real
  `ai-server` through `client-core`. It enrols by pasting the same
  `aiapp://enroll?…` link a phone scans (`client-core::config::EnrolledServer`)
  and keeps it owner-only under `$XDG_CONFIG_HOME/ai-app-desktop/`. The
  pinned CA is a path given on the command line, not baked in. Chosen so
  the phone and desktop share one enrolment format and no second one is
  invented.
- **I5's Android integration extends `iris-android-app` (I2's shell)
  behind a Cargo feature (`transcript-screen`), rather than a third
  shell crate.** That project already has the Gradle module, the
  `IrisView`/`MainActivity` Java, and the JNI registration; the only
  thing a second screen needs on top is a different `AndroidAppState`,
  the same axis `tabs_ui::build`/`transcript_ui::build` already vary
  along on the winit side. `tabs-screen`/`transcript-screen` are
  mutually exclusive and each pulls in only its own deps, so the plain
  tabs build (I2/I4) is untouched.
- **Order of remaining work, updated 2026-09-05**: the two in-flight
  pieces and I5's Android integration are all done; next is giving iris
  its own frame-timing report so item 3 below can be decided by a number.
- **DECIDED by Iris, 2026-09-05: iris is the app's framework; Masonry was
  the calibration.** Her words: "I think iris definitely makes more sense
  based on the limitations we've found." The limitations: Masonry has no
  touch scroll on Android (E2), no per-span rich text and no cross-row
  selection on the pinned commit (E2), and its keyboard bridge is a TODO
  (E1); iris carries the same screen under the Compose baseline on the
  host GPU (p50 15.0 ms against Compose's 20.0 ms, RUST.md's I5 box). What
  follows: the E-steps are closed as calibration, and the port proceeds
  on iris — screens, the shell (E3/E5), and `client-core` underneath.
  The item below is kept as the record of what she decided from.
- **Was DEFERRED — whether to commit to iris over Masonry for `ai-app`.**
  Updated 2026-09-05 with the clean comparison the recommendation wanted:
  same sandbox session content, same emulator, `EMU_GPU=software`, one
  session. Headline numbers (RUST.md's I5 box, "Clean scroll comparison,
  2026-09-05," has the full table and every caveat):

  | app | build | frames | janky % | p50 | p90 | p99 | worst |
  |---|---|---|---|---|---|---|---|
  | Compose (in-app report) | debug | 1102 | 99.0% late | 33.8ms | 50.6ms | 79.5ms | -- |
  | Compose (`dumpsys gfxinfo`) | debug | 1499 | 21.15% (95.66% legacy) | 32ms | 48ms | 150ms (p99) | -- |
  | iris (`FrameReport`) | **release** | 299 | 94.65% | 79.1ms | 98.6ms | 117.8ms | 212.6ms |
  | iris (`FrameReport`, repeat) | **release** | 233 | 94.42% | 109.3ms | 130.8ms | 147.1ms | 150.5ms |

  **Not a clean apples-to-apples reading, stated plainly rather than
  smoothed over**: iris had to be built **release** (debug `SIGSEGV`s on
  this emulator's Vulkan loader, I4's finding) against Compose's mandated
  **debug** build, so this asymmetry likely *understates* iris's gap
  rather than the reverse; the three frame-time sources measure different
  things (Compose's own phase accounting vs. Android's HWUI deadline-miss
  definition vs. iris's redraw-start-to-present window, the last of which
  `dumpsys gfxinfo` cannot see at all for iris's `SurfaceView`); and both
  figures are emulator numbers under software rasterisation, which
  Compose's *own* in-app report shows already costs 20-34ms/frame in
  `swap`+`gpu` alone under this GPU mode, so a same-mode iris number well
  above 16.7ms was expected going in for either app. A second pair under
  `-gpu host` was not taken this pass. The earlier session's suspected
  intermittent touch-delivery dropout was **not reproduced** this pass —
  the zero-frame results this time traced to this pass's own script bug
  (a `cd` that changed which emulator `ui-trace` targeted), not the
  emulator; a CPU-load rise during the gesture was observed by a sampler
  running throughout, but did not correlate with any failure, so the
  original candidate is neither confirmed nor ruled out.
  The choice in front of Iris, updated: decide now on the
  structural-plus-functional case already made (iris works end-to-end
  where Masonry's scroll gesture doesn't exist at all on Android) plus
  this table — reading the two build profiles and three jank definitions
  with the caveats above rather than as a single number — or ask for a
  same-profile, same-GPU-mode rerun first. RUST.md's I5 box has the full
  account.

  **Updated 2026-09-05, the `-gpu host` pair taken.** Real GPU rendering
  (`force-gles` -- the default Vulkan backend has no adapter at all under
  plain host-GPU boot, confirmed by the exact `wgpu` error) reverses the
  software-mode shape:

  | app | build | GPU mode | frames | janky % | p50 | p90 | p99 | worst | cpu p50 | gpu-wait p50 |
  |---|---|---|---|---|---|---|---|---|---|---|
  | Compose (in-app report) | debug | host (virgl) | 1268 | 96.4% late | 20.0ms | 28.4ms | 37.7ms | -- | -- | -- |
  | iris (`FrameReport`), **best of three, 2026-09-05** | release, `force-gles` | host (virgl) | 439 | 46.24% | 15.7ms | 23.3ms | 31.2ms | 57.4ms | 1.2ms | 13.2ms |

  Under real GPU rendering iris's median frame is *faster* than
  Compose's, not the 2-3x-slower shape the software-mode table shows. A
  new split inside `FrameReport` (redraw-to-submit vs. submit-to-present,
  commit `e2a1fad`) says why: iris's own CPU work per frame is a median
  ~1ms -- almost the entire frame is time spent handing the frame to the
  driver, not in iris's layout/text/primitive code. This is consistent
  with the earlier software-mode gap being mostly SwiftShader's CPU
  rasterisation cost rather than an iris-specific slowness. **Still not
  proof, and now closed as unanswerable rather than merely untaken**: a
  same-mode software `force-gles` run to isolate the backend was retried
  2026-09-05 after fixing the compute-limit crash the first attempt hit,
  and hit a second, structural wall instead — SwiftShader's ES 3.0 GL
  path has no storage-buffer capacity at all, and `shader.wgsl` reads
  `var<storage>` buffers unconditionally, so reaching that path needs a
  shader rewrite, not a limits fix (RUST.md's I5 box, "The three
  remaining I5 verifications, closed 2026-09-05," item 2). The
  intermittent touch-scroll dropout this pass also reproduced is
  root-caused and fixed as of the same date (a missed `ACTION_DOWN` on a
  row's padding/header left `DragArbiter` stuck in `Idle`); three clean
  `iris-scroll.sh` runs post-fix each scrolled all 24/24 swipes, replacing
  the single-attempt 62-frame reading this table used to carry. RUST.md's
  I5 box, "Where iris's frame time goes, 2026-09-05, the `-gpu host`
  pass," and "The three remaining I5 verifications, closed 2026-09-05,"
  have the full account. The iris-vs-Masonry choice itself is still
  Iris's to make.