Organize Iris support files

AGENTS.md

@@ -98,7 +98,7 @@ between network namespaces and verifies pinned TLS against 10.66.0.1.
   taps its accessibility-labelled control, and prints the report.
 - `cd app && cargo test` drives the real transcript screen without a window
   through `iris::harness`; touch recordings live in `app/touch/`.
-- `iris/run-headless.sh phone --phone --dir ../app --shot …` opens the same
+- `iris/scripts/run-headless.sh phone --phone --dir ../app --shot …` opens the same
   screen at phone size. `--replay ../app/touch/flick-120hz.touch` replays a
   recorded gesture.
 - `scripts/rigs/ui-profile/tests/frame_profile.rs` measures CPU frame cost;

app/src/android/mod.rs

@@ -23,7 +23,7 @@ mod enrollment;
 mod transcript_client;
 
 /// The app's `View` subclass, matching the Java side's package --
-/// `app/src/main/java/dev/iris/android/demo/IrisView.java`.
+/// `app/android-project/app/src/main/java/dev/iris/android/demo/IrisView.java`.
 const VIEW_CLASS: &str = "dev/iris/android/demo/IrisView";
 
 #[cfg(not(feature = "bench"))]

app/src/client/log_ring.rs

@@ -262,8 +262,7 @@ fn is_own_target(target: &str) -> bool {
         || target.starts_with("ai_app::")
 }
 
-/// This is the one filter docs/IRIS_TODO.md's "logs way too big" entry
+/// Applied once here rather than at each `debug!` call site:
-/// asked for, applied once here rather than at each `debug!` call site:
 /// Info and above always ring, from anything, because a real warning or
 /// error from a dependency is worth keeping. Debug and Trace ring only
 /// from this app's own targets, and only while tracing is switched on --

app/tests/input_log_roundtrip.rs

@@ -103,7 +103,7 @@ fn tracing_is_silent_off_and_round_trips_the_flick_on() {
     let report = input_lines.join("\n");
     let script_path = concat!(
         env!("CARGO_MANIFEST_DIR"),
-        "/../iris/benches/report_to_touch.py"
+        "/../iris/scripts/report_to_touch.py"
     );
     let mut child = Command::new("python3")
         .arg(script_path)

app/touch/flick-120hz.touch

@@ -1,6 +1,5 @@
 # A finger flick the shape Iris's phone delivers one, from
-# docs/bench/iris-phone-v2-2026-09-06.md and docs/IRIS_TODO.md's
+# docs/bench/iris-phone-v2-2026-09-06.md: at 120Hz a flick reaches the app
-# "From the phone, 2026-09-06, 22:16": at 120Hz a flick reaches the app
 # as DOWN, one or two MOVEs and UP inside a few frames, with the
 # intermediate positions batched inside those MOVEs as historical
 # samples (~4ms apart, the touch digitiser's own rate) rather than

docs/EXPLORER.md

@@ -247,8 +247,9 @@ is a unit test with exactly those names in it.
 
 ### 12. Icons
 
-Added to `NerdIcons.kt` **and** `build-icon-font.sh`, then the script rerun
+Add these to `iris/core/src/icon.rs` **and**
-and its output committed: `md-folder` U+F024B (the header button and
+`iris/core/build-icon-font.sh`, then rerun the script and commit its output:
+`md-folder` U+F024B (the header button and
 directory rows), `md-plus` U+F0415, `md-pencil` U+F03EB,
 `md-content_save` U+F0193, `md-file_outline` U+F0224. The folder and the plus
 are the same codepoints dev-updater uses and must not drift from it, as the

docs/IRIS_TODO.md

@@ -1,75 +0,0 @@
-# iris: known problems and things still to build
-
-Only open Iris framework work lives here. Delete an item when it lands.
-
-## Build (for the port)
-
-Framework capabilities needed by `RUST.md`'s port plan:
-
-- [ ] **Overflow ellipsis with an explicit retained end.** `TextAttrs` can
-  only wrap or clip, so a tool summary is cut with no mark. Parley has no
-  ellipsis primitive; use its line breaker to find the cut, but keep source
-  and displayed strings distinct with one byte mapping shared by spans,
-  links, selection and editing. Replace `wrap: bool` with an enum that can
-  say wrap, clip, head ellipsis and tail ellipsis—the caller must choose
-  because a command is identified by its head and a path by its tail.
-- [ ] **Expose the distance from a `LazySpan` viewport to its unloaded
-  edge.** (**P1**.) `viewport_len` and the visible extents are already
-  measured internally, but a paging caller cannot ask whether it is within
-  the product's six-viewport `HISTORY_SCREENS` cushion. The API should
-  answer in pixels or viewport multiples, never rows: a row ranges from one
-  line to a screen, so a fixed row count is not a distance.
-- [ ] **Let an image fit a bounded box while preserving its aspect ratio.**
-  (**P1**.) `Image` currently always reports and draws the decoded texture's
-  natural pixel size. Decoding and fetching a server-produced attachment
-  belong in `app`; iris only owes the generic fit/scale widget used to
-  draw its thumbnail.
-- [ ] **Per-range backgrounds for rich text.** (**P1**.) Inline code is
-  already monospace and coloured, but the inline-code chip also needs
-  the glyph run's boxes so a surface can be drawn behind exactly that byte
-  range. The shared `TextSelection` engine already computes the same geometry
-  for selection highlights; expose one shared primitive rather than giving
-  the app a second text-layout path.
-- [ ] **A horizontal gauge/bar widget.** (**P1**.) For
-  `SessionUsageBar`'s equivalent — a bounded fill reflecting a fraction,
-  nothing fancier.
-- [ ] **A toggle switch.** (**P3**.) For the delete dialog's
-  `deleteForeign` control; iris has no switch/checkbox widget yet as far
-  as this pass found.
-
-## Later
-
-- [ ] **Intern independently constructed solid paint definitions.** Inline
-  `rect(Srgba8::...)` values currently receive a new `PaintId` each time.
-  Cache them by canonical linear RGBA bits, but keep `Paints::add` explicitly
-  unique so two semantic theme roles that start with the same value can later
-  change independently. Cache entries must be weak and disappear when the
-  last real handle releases the slot; gradients and texture paints need their
-  own identity rules rather than inheriting solid-value interning blindly.
-
-- [ ] **Property/content animations.** Cosmetic, so after correctness and
-  parity. Keep them modular, like input; scrolling already animates through
-  `Widget::tick` and `UiData::animate`. A widget that does not opt in must
-  pay nothing and import nothing for them.
-
-- [ ] **Remove `WidgetView` unless a real composite adopts it.** Every
-  composite in `app/src/ui` uses ordinary child handles plus a root;
-  `WidgetView` and its derive are used only by `iris/examples/view.rs`.
-  It currently demonstrates itself rather than shortening production code.
-
-- [ ] **A `Stack` that chooses its mask the way it chooses its size
-  should replace `masked_by`.** For a square-cornered surface,
-  `.background(rect(BAR_FILL)).masked()` was measured
-  against `.masked_by(rect(BAR_FILL))` on the composer at the phone's own
-  size and density and the two are identical to the pixel. What the pair
-  cannot express is a clip that is not a box: `Painter::set_mask` writes
-  a `RectPrimitive::color` using `PaintId::NONE` at the widget's own region,
-  with no radius, so `.background(rect(fill).radius(r)).masked()` draws a
-  rounded panel and then cuts its content square. Both other call sites
-  (`row.rs`'s fence, `tool.rs`'s raw output) are rounded, which is why
-  the method stands for now.
-  Let `Stack` name the mask child the way `StackSize::Child(n)` names the
-  sizing child. Then `.background(x)` remains the one way to add a surface
-  and clipping to it is a stack property; the named mask child must have
-  drawn before any child that uses it. Once that exists, delete
-  `masked_by` and `Masked::shape` rather than retaining two APIs.

docs/LAYOUT.md

@@ -244,8 +244,7 @@ have `ActiveData`'s existing lifecycle through `remove`/`remove_rec`.
 ## Density: `Len::dp`, resolved at `apply_rest` time
 
 Iris asked for a third length kind beside `abs` (physical pixels) and
-`rel`/`rest` (a fraction of the parent) — IRIS_TODO.md's "density-
+`rel`/`rest` (a fraction of the parent) after the P0 phone pass found 16px text
-independent length unit" — after the P0 phone pass found 16px text
 drawing at roughly a third size on a real phone. The fix that shipped
 first (RUST.md's P0 box) was a global stopgap: divide the whole window
 into a "logical" coordinate space (physical ÷ `content_scale`) and let

docs/RUST.md

@@ -49,7 +49,7 @@ Later product work:
 - Desktop layouts for those surfaces.
 
 Client route coverage and gaps live in `docs/CLIENT_CORE.md`; framework work
-lives in `docs/IRIS_TODO.md`.
+lives in `iris/TODO`.
 
 ## Test layers
 
@@ -74,8 +74,8 @@ compute pass to prove the shader and CPU hit-test arithmetic agree.
 ### 2. Phone-shaped desktop window
 
     cd iris
-    ./run-headless.sh phone --phone --dir ../app --shot /tmp/phone.png
+    ./scripts/run-headless.sh phone --phone --dir ../app --shot /tmp/phone.png
-    ./run-headless.sh phone --phone --dir ../app \
+    ./scripts/run-headless.sh phone --phone --dir ../app \
       --replay ../app/touch/flick-120hz.touch --shot /tmp/replay.png
 
 This layer is for visual output and desktop input integration. Debug frame
@@ -187,7 +187,7 @@ name. Explicit benchmark builds add `.bench` to the application id.
 - Release builds are signed by the machine-local
   `~/.config/ai-app/release.jks`. No key or enrollment secret belongs in the
   repository.
-- `iris/run-headless.sh --dir DIR` selects the workspace containing the
+- `iris/scripts/run-headless.sh --dir DIR` selects the workspace containing the
   example and defaults to `iris/`.
 
 ## Session-screen pass condition

docs/SCROLL.md

@@ -1,6 +1,6 @@
 # Scrolling in iris
 
-This is the current scrolling design; `docs/IRIS_TODO.md` holds open work.
+This is the current scrolling design; `iris/TODO` holds open work.
 
 Read this before touching `iris/src/widget/position/scrollable.rs`,
 `scroll_area.rs`, `lazy_span.rs`, or anything that pans, flings or lays

iris/TODO

@@ -1,40 +1,75 @@
-images
+# iris: known problems and things still to build
-    settings (sampler)
 
-text
+Only open Iris framework work lives here. Delete an item when it lands.
-    figure out ways to speed up / what costs the most
-    resizing (per frame) is really slow (assuming painter isn't griefing)
-    j is weird / fix x offset
 
-masks r just made to bare minimum work
+## Build (for the port)
 
-scaling
+Framework capabilities needed by `RUST.md`'s port plan:
-    could be just a simple scaling factor that multiplies abs
-    and need to ensure text uses raw abs and not scaled abs
-    naming? (pt, px)
-    want to keep (drawn) regions using px? or should I add another field to UiScalar/Vec
-    field could be best solution so redrawing stuff isn't needed & you can specify both as user
 
-WidgetRef<W> or smth instead of Id
+- [ ] **Overflow ellipsis with an explicit retained end.** `TextAttrs` can
-    enum that's either an Id or an actual concrete instance of W
+  only wrap or clip, so a tool summary is cut with no mark. Parley has no
-    painter takes them in instead of (or in addition to) id
+  ellipsis primitive; use its line breaker to find the cut, but keep source
-    then type wrapper widgets to contain them
+  and displayed strings distinct with one byte mapping shared by spans,
-    allows for compile time optimization if a widget wrapper's inner is known at compile time
+  links, selection and editing. Replace `wrap: bool` with an enum that can
-        and the id of inner is not needed anywhere
+  say wrap, clip, head ellipsis and tail ellipsis—the caller must choose
-    maybe introduce InnerWidget trait to allow for editors to expose & modify inner type
+  because a command is identified by its head and a path by its tail.
-    maybe could also store a parent widget and keep using InnerWidget trait? unsure if possible
+- [ ] **Expose the distance from a `LazySpan` viewport to its unloaded
+  edge.** (**P1**.) `viewport_len` and the visible extents are already
+  measured internally, but a paging caller cannot ask whether it is within
+  the product's six-viewport `HISTORY_SCREENS` cushion. The API should
+  answer in pixels or viewport multiples, never rows: a row ranges from one
+  line to a screen, so a fixed row count is not a distance.
+- [ ] **Let an image fit a bounded box while preserving its aspect ratio.**
+  (**P1**.) `Image` currently always reports and draws the decoded texture's
+  natural pixel size. Decoding and fetching a server-produced attachment
+  belong in `app`; iris only owes the generic fit/scale widget used to
+  draw its thumbnail.
+- [ ] **Per-range backgrounds for rich text.** (**P1**.) Inline code is
+  already monospace and coloured, but the inline-code chip also needs
+  the glyph run's boxes so a surface can be drawn behind exactly that byte
+  range. The shared `TextSelection` engine already computes the same geometry
+  for selection highlights; expose one shared primitive rather than giving
+  the app a second text-layout path.
+- [ ] **A horizontal gauge/bar widget.** (**P1**.) For
+  `SessionUsageBar`'s equivalent — a bounded fill reflecting a fraction,
+  nothing fancier.
+- [ ] **A toggle switch.** (**P3**.) For the delete dialog's
+  `deleteForeign` control; iris has no switch/checkbox widget yet as far
+  as this pass found.
 
-really weird limitation:
+## Later
-    I don't think you can currently remove an element from a parent and put it in a child of the same parent
-    because it removes the unused children after the entire parent redraw
-    but the child gets drawn during that, so it will think the child is still active !!!
-    or something like that idk, maybe I need a special enum for parent that includes a undecided state where it may or may not get redrawn by the parent
-    or just do ref counting and ensure all drawn things == 1 afterwards (seems like best way)
-    ok so I'm removing the limit for now
 
-don't forget I'm streaming
+- [ ] **Intern independently constructed solid paint definitions.** Inline
+  `rect(Srgba8::...)` values currently receive a new `PaintId` each time.
+  Cache them by canonical linear RGBA bits, but keep `Paints::add` explicitly
+  unique so two semantic theme roles that start with the same value can later
+  change independently. Cache entries must be weak and disappear when the
+  last real handle releases the slot; gradients and texture paints need their
+  own identity rules rather than inheriting solid-value interning blindly.
 
-tags
+- [ ] **Property/content animations.** Cosmetic, so after correctness and
-vecs for each widget type?
+  parity. Keep them modular, like input; scrolling already animates through
+  `Widget::tick` and `UiData::animate`. A widget that does not opt in must
+  pay nothing and import nothing for them.
 
-POTENTIAL BUG: closures that store IDs will not decrement the id!!! need to not increment id if moved into closure somehow??? wait no, need to decrement ID every time an event fn is added...... only if the id is used in it..??
+- [ ] **Remove `WidgetView` unless a real composite adopts it.** Every
+  composite in `app/src/ui` uses ordinary child handles plus a root;
+  `WidgetView` and its derive are used only by `iris/examples/view/lib.rs`.
+  It currently demonstrates itself rather than shortening production code.
+
+- [ ] **A `Stack` that chooses its mask the way it chooses its size
+  should replace `masked_by`.** For a square-cornered surface,
+  `.background(rect(BAR_FILL)).masked()` was measured
+  against `.masked_by(rect(BAR_FILL))` on the composer at the phone's own
+  size and density and the two are identical to the pixel. What the pair
+  cannot express is a clip that is not a box: `Painter::set_mask` writes
+  a `RectPrimitive::color` using `PaintId::NONE` at the widget's own region,
+  with no radius, so `.background(rect(fill).radius(r)).masked()` draws a
+  rounded panel and then cuts its content square. Both other call sites
+  (`row.rs`'s fence, `tool.rs`'s raw output) are rounded, which is why
+  the method stands for now.
+  Let `Stack` name the mask child the way `StackSize::Child(n)` names the
+  sizing child. Then `.background(x)` remains the one way to add a surface
+  and clipping to it is a stack property; the named mask child must have
+  drawn before any child that uses it. Once that exists, delete
+  `masked_by` and `Masked::shape` rather than retaining two APIs.

iris/scripts/headless.conf

@@ -1,4 +1,4 @@
-# The compositor `run-headless.sh` starts, because this machine has no
+# The compositor `scripts/run-headless.sh` starts, because this machine has no
 # display. Nothing here is meant to be looked at directly; `grim` is.
 #
 # No Xwayland: winit talks Wayland natively, and starting an X server is a

iris/scripts/reference/fling_spline_reference.py

@@ -125,7 +125,7 @@ if __name__ == "__main__":
     # 2.55 is Iris's Pixel 9 Pro XL (docs/bench/iris-phone-v2-2026-09-06.md);
     # 2.75 is this checkout's emulator.
     for density in (2.55, 2.75):
-        # 15250 is `transcript-fixture/touch/flick-120hz.touch`'s own
+        # 15250 is `app/touch/flick-120hz.touch`'s own
         # release velocity (velocity_reference.py), so `phone_screen.rs`
         # can bound the fling it produces from *here* rather than from the
         # `FlingCalculator` under test (docs/REVIEW-2026-09-07.md's T1).

iris/scripts/reference/velocity_reference.py

@@ -218,7 +218,7 @@ def average(samples):
 
 
 
-# 1. `transcript-fixture/touch/flick-120hz.touch`, as `DragGesture` feeds it:
+# 1. `app/touch/flick-120hz.touch`, as `DragGesture` feeds it:
 #    the DOWN position, then one position per MOVE. The UP at t=20 adds no
 #    sample (see the module doc), which is why the finger sitting still for its
 #    last 4ms does not drag the estimate down. y only; the flick is vertical.

iris/scripts/run-bench.sh

@@ -1,15 +1,16 @@
 #!/bin/sh
-# Runs iris's on-demand benchmark suite (IRIS_TODO.md's "Benchmarks" item).
+# Runs iris's on-demand benchmark suite.
 # Never run by `cargo test`; run this by hand or before/after a layout
 # change. Always release -- see AGENTS.md's own rule against reading a
 # frame time from a debug build.
 #
-#   ./run-bench.sh            # everything
+#   ./scripts/run-bench.sh            # everything
-#   ./run-bench.sh list       # just the CPU-only message-list scenarios
+#   ./scripts/run-bench.sh list       # just the CPU-only message-list scenarios
-#   ./run-bench.sh images     # just the GPU bind-group-creation scenario
+#   ./scripts/run-bench.sh images     # just the GPU bind-group-creation scenario
 set -eu
-here=$(cd "$(dirname "$0")" && pwd)
+scripts=$(cd "$(dirname "$0")" && pwd)
-cd "$here"
+root=$(cd "$scripts/.." && pwd)
+cd "$root"
 
 what="${1:-all}"
 
@@ -20,5 +21,5 @@ fi
 
 if [ "$what" = "all" ] || [ "$what" = "images" ]; then
     echo "=== bench_images (real wgpu device, via run-headless.sh) ==="
-    timeout 60 ./run-headless.sh bench_images --seconds 4 2>&1 | grep "^BENCH_IMAGES"
+    timeout 60 "$scripts/run-headless.sh" bench_images --seconds 4 2>&1 | grep "^BENCH_IMAGES"
 fi

iris/scripts/run-headless.sh

@@ -1,14 +1,14 @@
 #!/bin/sh
 # Run an iris example on this machine, which has no display.
 #
-#   ./run-headless.sh tabs [-- cargo args]
+#   ./scripts/run-headless.sh tabs [-- cargo args]
-#   ./run-headless.sh tabs --shot /tmp/tabs.png --seconds 4
+#   ./scripts/run-headless.sh tabs --shot /tmp/tabs.png --seconds 4
-#   ./run-headless.sh phone --phone --dir ../app --shot /tmp/p.png
+#   ./scripts/run-headless.sh phone --phone --dir ../app --shot /tmp/p.png
-#   ./run-headless.sh phone --phone --dir ../app \
+#   ./scripts/run-headless.sh phone --phone --dir ../app \
 #       --replay ../app/touch/flick-120hz.touch --shot /tmp/p.png
 #
-# `--dir DIR` names the workspace to build in, defaulting to `iris/` (this
+# `--dir DIR` names the workspace to build in, defaulting to `iris/`. The
-# script's own directory). The app's examples -- the phone-sized transcript
+# app's examples -- the phone-sized transcript
 # screen and everything else that is about *this product* -- live in
 # `app/`, which is a workspace of its own; `replay-touch` is still
 # built from iris, since it is part of the rig rather than of either app.
@@ -50,8 +50,10 @@
 # socket and its own runtime directory and goes away with the machine.
 set -eu
 
-here=$(cd "$(dirname "$0")" && pwd)
+scripts=$(cd "$(dirname "$0")" && pwd)
-workdir="$here"
+root=$(cd "$scripts/.." && pwd)
+workdir="$root"
+cd "$root"
 run="${XDG_RUNTIME_DIR:-/tmp}/iris-headless"
 seconds=3
 shot=""
@@ -90,7 +92,7 @@ export SWAYSOCK="$run/sway.sock"
 if ! swaymsg -t get_version >/dev/null 2>&1; then
     rm -f "$SWAYSOCK"
     WLR_BACKENDS=headless WLR_LIBINPUT_NO_DEVICES=1 LIBSEAT_BACKEND=noop \
-        setsid sway -c "$here/headless.conf" >"$run/sway.log" 2>&1 &
+        setsid sway -c "$scripts/headless.conf" >"$run/sway.log" 2>&1 &
     i=0
     while [ $i -lt 20 ]; do
         swaymsg -t get_version >/dev/null 2>&1 && break
@@ -134,7 +136,7 @@ out_h=${mode#*x}; out_h=${out_h%@*}
 
 # Built before the app starts, so a compile error is not reported as a
 # window that failed to move.
-[ -z "$replay" ] || (cd "$here" && cargo build --bin replay-touch -p rig-input) >&2
+[ -z "$replay" ] || (cd "$root" && cargo build --bin replay-touch -p rig-input) >&2
 
 cd "$workdir"
 if [ "$kind" = bin ]; then
@@ -173,7 +175,7 @@ if [ -n "$replay" ] && kill -0 "$pid" 2>/dev/null; then
         grim "${shot%.png}-before.png"
         echo "run-headless: wrote ${shot%.png}-before.png (before the gesture)" >&2
     fi
-    "$here/target/debug/replay-touch" "$out_w" "$out_h" "$replay"
+    "$root/target/debug/replay-touch" "$out_w" "$out_h" "$replay"
     # A fling outlives the finger: the gesture's own last sample is not
     # when the list stops. Long enough for Android's spline to settle
     # (`FlingCalculator::duration` tops out around a second and a half).

iris/src/android/view.rs

@@ -829,7 +829,7 @@ impl<State: AndroidAppState> AccessibilityNodeProvider for IrisViewPeer<State> {
 /// `newViewPeer` call from Java. `State`'s app crate wraps this in a
 /// concrete `extern "system" fn` (a generic function cannot be handed to
 /// `register_view_class`, which wants a plain function pointer) -- see
-/// `iris/android-app/src/lib.rs`.
+/// `app/src/android/mod.rs` and `iris/examples/*/android.rs`.
 pub fn new_peer<'local, State: AndroidAppState>(
     mut env: JNIEnv<'local>,
     view: View<'local>,

iris/src/rsc/sense.rs

@@ -1035,7 +1035,7 @@ const FIT_COEFFICIENTS: usize = FIT_DEGREE + 1;
 pub const MAX_FLING_VELOCITY_DP_S: f32 = 8000.0;
 
 /// The numbers its tests assert on come from
-/// `iris/benches/velocity_reference.py`, an independent transcription of
+/// `iris/scripts/reference/velocity_reference.py`, an independent transcription of
 /// the same Kotlin -- not from this code, for the reason
 /// `android_fling_spline`'s doc gives at length.
 #[derive(Default)]

iris/src/rsc/sense_tests.rs

@@ -101,7 +101,7 @@ fn a_button_over_a_list_scrolls_the_list_and_still_clicks() {
         events: EventManager::default(),
     };
 
-    // the case in IRIS_TODO.md's report.
+    // A button nested over a scrolling surface must participate in both gestures.
     let list = rsc.ui.widgets.add_strong(Rect::new(PaintId::WHITE));
     let list_weak = list.weak();
     let button = rsc.ui.widgets.add_strong(Rect::new(PaintId::RED));