Prune commentary and stale Rust port notes

app-rust/tests/top_edge.rs

@@ -1,23 +1,7 @@
-//! Layer 1 of docs/RUST.md's "Three test layers", for the transcript's
-//! own edges: the real screen over the real fixture, under a header bar
-//! like the bench app's, driven by `iris::harness`.
-//!
-//! What these are about is docs/IRIS_TODO.md's 2026-09-07 phone report --
-//! rows scrolled above the viewport still drawn, over the header, and a
-//! blank band where the row straddling the top edge should be. Both are
-//! one rule (`LazySpan::intersects_viewport`): a row is drawn if any part of
-//! it is inside the list's own box, and nothing outside that box reaches
-//! the screen.
-
 use ai_app::ui::fixture::{PHONE_FRAME_MS, PHONE_SCALE, phone_size};
 use iris::harness::Harness;
 use iris::prelude::*;
 
-/// A header band above the transcript, as `bench_client.rs` puts one --
-/// the surface the rows were drawing over on the phone. Its exact height
-/// does not matter; what matters is that the list's own box does not
-/// start at the top of the window, so "above the viewport" and "off the
-/// screen" are different places.
 const HEADER_H: f32 = 300.0;
 const HEADER: UiColor = UiColor::new(28, 28, 34, 255);
 
@@ -36,17 +20,12 @@ fn opened() -> (Harness, ai_app::ui::TranscriptScreen) {
     (h, opened.screen)
 }
 
-/// The list's own on-screen box, in window pixels.
 fn list_box(h: &Harness, screen: &ai_app::ui::TranscriptScreen) -> PixelRegion {
     h.render
         .window_region(&screen.list.id(), &h.rsc)
         .expect("the list is on screen")
 }
 
-/// Every row the list drew this frame, as `(top, bottom)` window pixels,
-/// topmost first. A `LazySpan`'s direct children are exactly its rows, and
-/// `draw_inner`'s old-children diffing means a row it did not place this
-/// frame is not among them.
 fn drawn_rows(h: &Harness, screen: &ai_app::ui::TranscriptScreen) -> Vec<(f32, f32)> {
     let mut rows: Vec<(f32, f32)> = h
         .render
@@ -62,32 +41,18 @@ fn drawn_rows(h: &Harness, screen: &ai_app::ui::TranscriptScreen) -> Vec<(f32, f
     rows
 }
 
-/// Scrolls `amount` and runs the frame it asks for, returning the time of
-/// the next one. **Positive walks back through older rows** -- the
-/// finger's own direction, and `Scroll::scroll`'s, which is the one
-/// convention a delta has anywhere in iris since the transcript's scroll
-/// position lives in the `LazySpan`'s own `ScrollController`.
-/// It used to be the opposite here, because a `LazySpan`'s anchor offset
-/// ran the other way.
 fn scrolled(h: &mut Harness, screen: &ai_app::ui::TranscriptScreen, amount: f32, t: u64) -> u64 {
     (screen.list)(&mut h.rsc).scroll(amount);
     h.frame(t);
     t + PHONE_FRAME_MS
 }
 
-/// (a) of docs/IRIS_TODO.md's reproduction: with a row across the top
-/// edge, that row is placed -- the viewport's first pixel belongs to
-/// something. A rule that culled a row once its *top* left the viewport
-/// would leave a blank band here, which is the second of Iris's two
-/// screenshots.
 #[test]
 fn the_row_across_the_top_edge_is_drawn() {
     let (mut h, screen) = opened();
     let top = list_box(&h, &screen).top_left.y;
     let mut t = PHONE_FRAME_MS * 2;
 
-    // 40px a frame, the shape a finger pan arrives in, through a straddle
-    // and out the other side of it many times over.
     for _ in 0..60 {
         t = scrolled(&mut h, &screen, 40.0, t);
         let rows = drawn_rows(&h, &screen);
@@ -108,16 +73,6 @@ fn the_row_across_the_top_edge_is_drawn() {
     }
 }
 
-/// (b): what falls outside the list's box is clipped rather than drawn
-/// over whatever is there. The straddling row above is drawn *in full*,
-/// so the only thing between its earlier lines and the header bar is this
-/// mask -- with none, the phone drew `version = "0.1.0"` behind the "Run
-/// benchmark" button.
-///
-/// The clip is one the screen **opted into** (`build_tree`'s `.masked()`),
-/// so this reads the mask the list *inherited*. A `LazySpan` sets none of
-/// its own -- masking is opt-in, like scrolling (Iris, 2026-09-08) -- so
-/// this is also the test that the transcript is still asking for one.
 #[test]
 fn the_list_is_clipped_to_its_own_box() {
     let (h, screen) = opened();
@@ -134,11 +89,6 @@ fn the_list_is_clipped_to_its_own_box() {
          edge still draws past it",
     );
 
-    // And the mask has to *reach* what the rows draw. The two above say a
-    // mask exists and sits in the right place; neither says any primitive
-    // references it, so a broken `Mask::parent` chain -- what d507ae4
-    // introduced -- would leave them green while a code fence inside a row
-    // drew unclipped again (review, 2026-09-07's T3).
     let rows = h
         .render
         .active
@@ -165,9 +115,6 @@ fn the_list_is_clipped_to_its_own_box() {
     );
 }
 
-/// Every primitive `id` and its descendants drew, as `MaskIdx`es -- images
-/// excluded, since they live in a separate instance array with their own
-/// indices (`Primitives::free`).
 fn primitives_under(h: &Harness, id: WidgetId) -> Vec<MaskIdx> {
     let Some(active) = h.render.active.get(&id) else {
         return Vec::new();
@@ -184,7 +131,6 @@ fn primitives_under(h: &Harness, id: WidgetId) -> Vec<MaskIdx> {
     out
 }
 
-/// The chain the fragment stage walks from `mask`, outermost last.
 fn mask_chain(h: &Harness, mask: MaskIdx) -> Vec<MaskIdx> {
     let mut chain = Vec::new();
     let mut at = mask;
@@ -199,31 +145,12 @@ fn mask_chain(h: &Harness, mask: MaskIdx) -> Vec<MaskIdx> {
     chain
 }
 
-/// A row that has left the viewport entirely is not drawn at all. Before
-/// the fix the walk ran from the anchor -- which `scroll` leaves wherever
-/// it was, however far outside the viewport that ends up -- and drew
-/// every row on the way: 8 scrolls of 3000px left **64 rows** placed for
-/// a 2012px viewport, ~59 of them off screen and painting over the
-/// header.
-///
-/// The box is asserted on every leg *except the first*, because a row
-/// whose height has never been measured has to be drawn to be measured
-/// (`LazySpan::place`'s doc), which on the first walk back is every row
-/// entering from the top. Every later leg crosses the same rows with
-/// every height already known -- including the second walk *back*, which
-/// is there because a regression that draws rows in the wrong place while
-/// travelling backwards would otherwise be checked only by the row count
-/// (review, 2026-09-07's T2). That is also the ordinary state of a
-/// transcript being panned around in. The bound on how many rows are
-/// placed at once holds on all three.
 #[test]
 fn rows_that_have_left_the_viewport_are_not_drawn() {
     let (mut h, screen) = opened();
     let list = list_box(&h, &screen);
     let mut t = PHONE_FRAME_MS * 2;
     let bounded = |rows: &[(f32, f32)], leg: &str, step: usize| {
-        // A handful of rows whatever distance has been travelled -- the
-        // module doc's own claim about this widget.
         assert!(
             rows.len() <= 24,
             "{leg} {step}: {} rows drawn for one 2012px viewport",
@@ -258,10 +185,6 @@ fn rows_that_have_left_the_viewport_are_not_drawn() {
     }
 }
 
-/// The end the fix had no reason to touch: the row across the *bottom*
-/// edge, where the composer starts. Same rule, other direction -- and the
-/// list opens pinned there, so this is the ordinary state of the screen
-/// rather than a scrolled-to one.
 #[test]
 fn the_row_across_the_bottom_edge_is_drawn() {
     let (mut h, screen) = opened();
@@ -287,12 +210,6 @@ fn the_row_across_the_bottom_edge_is_drawn() {
     }
 }
 
-/// Panning past the first row settles *on* it rather than beyond it. The
-/// list is scrolled far further back than the fixture is long, which is
-/// what a hard fling toward the top does; before the clamp existed it
-/// stayed wherever that left it -- the phone's "black from the header
-/// down", and a whole blank screen in `iris`'s own
-/// `fling_toward_the_start_stops_at_the_first_row`.
 #[test]
 fn scrolling_past_the_first_row_settles_on_it() {
     let (mut h, screen) = opened();
@@ -302,10 +219,6 @@ fn scrolling_past_the_first_row_settles_on_it() {
     for _ in 0..60 {
         t = scrolled(&mut h, &screen, 100_000.0, t);
     }
-    // No settling frame on purpose: the draw that discovers the gap gives
-    // it back inside that same frame (`LazySpan::overscroll_gap`), so the last
-    // frame `scrolled` drew is already flush with the first row. Adding
-    // one here would hide a regression to the old next-frame correction.
     let rows = drawn_rows(&h, &screen);
     let first = *rows.first().expect("the first row is on screen");
     assert!(
@@ -315,10 +228,6 @@ fn scrolling_past_the_first_row_settles_on_it() {
     );
 }
 
-/// The same clamp at the other end, which is where Iris met it second
-/// ("you shouldn't be able to scroll below the bottom (or above top)").
-/// The list opens flush with its newest row, so this drags *forward* off
-/// the end of the content and back.
 #[test]
 fn scrolling_past_the_last_row_settles_on_it() {
     let (mut h, screen) = opened();