Organize Iris support files

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.

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

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).

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.

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

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).

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>,

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)]

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));