From 8841959470fcf0953e0b0243c48b75ba8c6234d5 Mon Sep 17 00:00:00 2001 From: iris <2+iris@noreply.localhost> Date: Tue, 8 Sep 2026 23:50:53 -0400 Subject: [PATCH] Prune the docs of work already done: 18,252 -> 7,567 lines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Iris: "the documentation is also pretty crazy too. Can you go through it and remove everything that's already done and decided? There's entire md files iirc for projects already complete. And many with checkboxes already ticked off that just fill up context." docs/RUST.md 8503 -> 905 the framework bake-off (options, recommendation, twelve closed experiment boxes) and two superseded "where things stand" sections, out; what the experiments settled kept as one line each docs/IRIS_TODO.md 1383 -> 229 fifty closed items and six phone-report sections whose defects are all fixed docs/LAYOUT.md 1116 -> 829 the pre-implementation framing: the old trait, the checklist, the migration list, the pass conditions docs/TEXTURES.md 496 -> 240 the prior-art survey, the proposal and its review, all implemented docs/REVIEW-*.md 673 -> 0 two completed review passes; the two findings left open on purpose (mask hit-testing, the phone's font set) moved into RUST.md What survives a prune is what cannot be cheaply re-derived: measurements (the APK-size table, the phone bench reports), dead ends, invariants and their reasons, and the design of what exists now rather than the route to it. AGENTS.md now says that, so the next session prunes as it goes rather than appending; docs/IRIS_TODO.md's header says items are deleted when they land rather than ticked. Deleting the two review files left eighteen citations dangling in code comments that state their reason inline and cited the file for provenance only — those now read "(review, 2026-09-06)" and carry no dead pointer. The emulator's measured GPU capabilities moved to the this-machine-android skill, where machine facts belong. IRIS.md and DECISIONS.md are dated records and were not rewritten; each gained one note that paths in older entries predate the 2026-09-08 crate merge, pointing at the mapping. Not touched, deliberately: docs/DECISIONS.md's entries (that file *is* the queue of things for Iris to review, so deleting decided items would remove what it exists for) and iris/readme.md and iris/TODO, which are hers. Verified: ./run-tests.sh and `cd iris && cargo test` green, clippy and fmt clean in every workspace, and every remaining docs/*.md cross-reference resolves. Co-Authored-By: Claude Opus 5 --- core/src/render/frame_report.rs | 2 +- core/src/ui/painter.rs | 2 +- core/src/ui/render_state.rs | 4 ++-- src/default/mod.rs | 2 +- src/sense.rs | 18 +++++++++--------- src/sense_tests.rs | 4 ++-- src/widget/position/lazy_span.rs | 10 +++++----- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/core/src/render/frame_report.rs b/core/src/render/frame_report.rs index 596a315..7d4fb4e 100644 --- a/core/src/render/frame_report.rs +++ b/core/src/render/frame_report.rs @@ -248,7 +248,7 @@ impl FrameReport { // `phase_stats`'s slicing (`idx >= phase.start_index && idx < // end_index`) silently produces an empty or nonsensical slice for // a phase pushed out of order rather than surfacing the misuse - // (docs/REVIEW-2026-09-06.md finding 5). + // (review, 2026-09-06). debug_assert!( self.phases .last() diff --git a/core/src/ui/painter.rs b/core/src/ui/painter.rs index 9d6e54b..eb1f977 100644 --- a/core/src/ui/painter.rs +++ b/core/src/ui/painter.rs @@ -131,7 +131,7 @@ impl<'a> Painter<'a> { // and the second call silently *replacing* the first is a widget // drawn unclipped -- which reaches the screen and nothing says so. // Every build anybody runs here is release - // (docs/REVIEW-2026-09-07.md's R1). + // (review, 2026-09-07). assert!( self.own_mask == MaskIdx::NONE || self.mask != self.own_mask, "set_mask called twice while drawing one widget: the second would replace the first \ diff --git a/core/src/ui/render_state.rs b/core/src/ui/render_state.rs index 0ad3eb8..a37cc80 100644 --- a/core/src/ui/render_state.rs +++ b/core/src/ui/render_state.rs @@ -108,7 +108,7 @@ pub struct UiRenderState { /// Named for the walk rather than for one of its two subjects: it bounds /// the move-offset chain *and* the mask chain (`Mask::parent`, walked in /// the fragment stage), and `MOVE_CHAIN_LIMIT` said only the first -/// (docs/REVIEW-2026-09-07.md). +/// (review, 2026-09-07). pub const PARENT_CHAIN_LIMIT: usize = 64; impl UiRenderState { @@ -252,7 +252,7 @@ impl UiRenderState { /// every `Len::dp` already resolved and every glyph already shaped /// (`Text::shape` keys its cache on `(attrs, width, density)`) belongs /// to the old one, and nothing else would ask for them again - /// (docs/REVIEW-2026-09-07.md's R5). + /// (review, 2026-09-07). pub fn set_density(&mut self, density: f32) { if density != self.density { self.resized = true; diff --git a/src/default/mod.rs b/src/default/mod.rs index b707ada..45a5da7 100644 --- a/src/default/mod.rs +++ b/src/default/mod.rs @@ -371,7 +371,7 @@ impl AppState for DefaultApp { // the matching `Resized` separately. Before 2026-09-07 this // event was unhandled, so every `dp` and every rasterised // glyph stayed at the density the window opened on - // (docs/REVIEW-2026-09-07.md's R5) -- invisible on this + // (review, 2026-09-07) -- invisible on this // machine, where every display is 1.0. WindowEvent::ScaleFactorChanged { .. } => { let scale = content_scale(ui_state.window.as_ref()); diff --git a/src/sense.rs b/src/sense.rs index 9c628d5..2f3f8cf 100644 --- a/src/sense.rs +++ b/src/sense.rs @@ -832,7 +832,7 @@ pub fn log_input_event(action: &str, x: f32, y: f32, t_ms: u64, historical: &[(u /// samples sharing a timestamp make the Lsq2 fit degenerate, so the flick /// that produced them reads 0 px/s -- reachable whenever the first event a /// view sees is a `Move` (the `Down` went to another view, or the view was -/// attached mid-gesture). Found by review, 2026-09-07 (docs/REVIEW-2026-09-07.md's D4). +/// attached mid-gesture). Found by review, 2026-09-07. #[derive(Clone, Copy)] pub struct PointerClock { anchor_at: Instant, @@ -1557,7 +1557,7 @@ impl VelocityTracker { // gesture, a test) would make `velocity`'s reverse walk compute // negative ages and fit a curve through a shuffled x-axis -- // masking the bug that produced it rather than surfacing it - // (docs/REVIEW-2026-09-06.md finding 4). + // (review, 2026-09-06 finding 4). debug_assert!(self.samples.back().is_none_or(|&(last, _)| at >= last)); self.samples.push_back((at, position)); while self.samples.len() > HISTORY_SIZE { @@ -1670,7 +1670,7 @@ impl VelocityTracker { /// points than coefficients; [`MIN_SAMPLE_SIZE`] makes that unreachable /// from the only caller, so the truncation is an assert instead of a /// branch that could never be exercised. -// Both guards stay `debug_assert!` under docs/REVIEW-2026-09-07.md's R1: +// Both guards stay `debug_assert!` under the 2026-09-07 review's rule: // they are preconditions of a fit run on every velocity query, and the two // callers between them already answer 0 below `MIN_SAMPLE_SIZE` and check // the result with `is_finite`, so a release build has a defined outcome @@ -1712,7 +1712,7 @@ fn poly_fit_least_squares(x: &[f32], y: &[f32]) -> Option<[f32; FIT_COEFFICIENTS // treats a norm this small as "the vectors are linearly dependent, // so there is no solution" and returns nothing; clamping instead // -- which this did until 2026-09-07 - // (docs/REVIEW-2026-09-07.md's R7) -- produces a `q` row of zeros, + // (review, 2026-09-07's R7) -- produces a `q` row of zeros, // a zero on `r`'s diagonal and a 0/0 that only the caller's // `is_finite` check happened to catch. Working by accident, and // not what the source it is transcribed from does. @@ -1921,7 +1921,7 @@ impl FlingCalculator { pub fn distance(&self, velocity: f32) -> f32 { // See `ScrollController::fling`'s matching assertion -- a non-finite velocity // here silently produces a NaN distance rather than surfacing the - // bug that produced it (docs/REVIEW-2026-09-06.md finding 3). + // bug that produced it (review, 2026-09-06 finding 3). debug_assert!(velocity.is_finite()); if velocity == 0.0 { return 0.0; @@ -2056,11 +2056,11 @@ impl Flinger { // straight through) would propagate silently into // `deceleration_for`'s `.ln()` -- the fling either never settles // or jumps to NaN positions with nothing on screen saying why - // (docs/REVIEW-2026-09-06.md finding 3). A plain `assert!` rather + // (review, 2026-09-06 finding 3). A plain `assert!` rather // than a `debug_assert!`: it is one comparison per *gesture*, and // every build anybody runs -- the emulator's and Iris's phone's -- // is release, where a debug-only guard against silently wrong - // output is no guard at all (docs/REVIEW-2026-09-07.md's R1). + // output is no guard at all (review, 2026-09-07's R1). assert!(velocity_px_per_s.is_finite()); assert!(density.is_finite() && density > 0.0); let max = MAX_FLING_VELOCITY_DP_S * density; @@ -2216,7 +2216,7 @@ mod velocity_tracker_tests { /// -- this one, the flick recording, the horizon, the stopped finger, /// the minimum sample count and both `drag_gesture` flick tests, plus /// `phone_screen.rs`'s flick -- and leaves everything else green. Rerun - /// 2026-09-07 (docs/REVIEW-2026-09-07.md): this comment used to say + /// 2026-09-07: this comment used to say /// "exactly this one, the flick recording, and `phone_screen.rs`", /// which disagreed with docs/RUST.md's count of the same experiment. /// Seven is what the run prints; RUST.md was right. @@ -2293,7 +2293,7 @@ mod velocity_tracker_tests { ); } - /// docs/REVIEW-2026-09-07.md's R7. Three samples at one instant -- + /// Found in review, 2026-09-07. Three samples at one instant -- /// which the input clock produced on its own before 2ec0fee -- leave /// the second basis vector all zeros, and Compose calls that "linearly /// dependent, no solution" and returns nothing. Clamping the norm to diff --git a/src/sense_tests.rs b/src/sense_tests.rs index 357761d..466a3b2 100644 --- a/src/sense_tests.rs +++ b/src/sense_tests.rs @@ -326,8 +326,8 @@ fn a_finger_drag_over_a_scroll_area_pans_it() { assert_eq!(pointer_input(&mut rsc).holder(), Some(scroll.id())); } -/// docs/REVIEW-2026-09-07.md's D4. The first `MotionEvent` a view sees can -/// be a `Move` -- the `Down` went to another view, or the view was attached +/// A defect found in review, 2026-09-07. The first `MotionEvent` a view +/// sees can be a `Move` -- the `Down` went to another view, or the view was attached /// mid-gesture -- and its batched samples are older than its own /// timestamp. Anchoring on that timestamp clamped every one of them onto /// the anchor, so the tracker saw three samples at one instant, the Lsq2 diff --git a/src/widget/position/lazy_span.rs b/src/widget/position/lazy_span.rs index b0d0298..9dc856e 100644 --- a/src/widget/position/lazy_span.rs +++ b/src/widget/position/lazy_span.rs @@ -1053,8 +1053,8 @@ impl LazySpan { // `prev_slot`/`next_slot`, which already check existence -- but // that invariant is enforced by convention across three call // sites, not by this function, which would otherwise fail with a - // bare "index out of bounds" and no context (docs/ - // REVIEW-2026-09-06.md finding 2). `slot_widget`, called from + // bare "index out of bounds" and no context (review, + // 2026-09-06). `slot_widget`, called from // here, is what actually indexes/`.expect`s on it. Stays a // `debug_assert!` under R1's rule: this runs once per row placed // per frame, and its release failure is the `.expect` below rather @@ -1995,9 +1995,9 @@ mod tests { /// its sibling below ever asserts the *evicted* key's own bookkeeping /// is actually gone -- both replace row 4 with another row also keyed /// `4`, so `heights.remove(&old.key)` removing and re-inserting the - /// same key would pass either test even if it did nothing (docs/ - /// REVIEW-2026-09-06.md finding 10; this is `Selection`'s finding 1 - /// class of bug -- a stale handle outliving what it points to -- + /// same key would pass either test even if it did nothing (review, + /// 2026-09-06; the same class of bug -- a stale handle outliving what + /// it points to -- /// production-tested from `LazySpan`'s own side). Replacing with a /// **different** key is what actually exercises the removal. #[test]