From c8785b6091488f604e9fd8a6898adf0a2e84d095 Mon Sep 17 00:00:00 2001 From: iris <2+iris@noreply.localhost> Date: Tue, 8 Sep 2026 14:03:29 -0400 Subject: [PATCH] docs/IRIS.md: it is the log of how iris is being built, not an API changelog Iris, 2026-09-08: 'any major additions or design things should be added there, not just public API stuff. You may as well remove the public API bit at this point.' Widened the header, pointed AGENTS.md at the new scope, and added the design point behind the scroll bug -- a cached measurement needs its own value for 'not measured yet'. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 7 ++++--- docs/IRIS.md | 25 ++++++++++++++++++++----- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 08b18d9..2bddd42 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,9 +72,10 @@ Module-by-module intent is in `docs/PLAN.md`'s "Backend layout". conditions. Read it before touching anything under that branch. - `docs/IRIS.md`, `docs/IRIS_TODO.md`, `docs/DECISIONS.md`, `docs/LAYOUT.md`, `docs/TEXTURES.md`, `docs/CLIENT_CORE.md` — iris's - own public API log, working list, decisions log, layout/render design, - and texture-atlas design, and the client-core crate's design, - respectively. + own build log (**any major addition or design decision, not only + public API** -- Iris, 2026-09-08), working list, decisions log, + layout/render design, and texture-atlas design, and the client-core + crate's design, respectively. - `.dev-updater.ron` — what Dev Updater builds here: the server (run as `service: Managed(…)`, supervised by Dev Updater's own implementation rather than a script kept here) and the APK, in parallel. It points at diff --git a/docs/IRIS.md b/docs/IRIS.md index 23ca1c3..34625c3 100644 --- a/docs/IRIS.md +++ b/docs/IRIS.md @@ -1,9 +1,13 @@ -# iris: notable public API changes +# iris: the log of how it is being built -For Iris to read on her own time. Each entry is a change to iris's public -surface that a widget author or app author would notice: a trait method -added, removed or re-shaped; a type that callers construct differently; a -capability that moved. Small and trivial changes do not go here. +For Iris to read on her own time. An entry is anything **major**: a new +capability or widget, a design decision and what it was chosen over, a +mechanism that changed shape, a defect whose root cause says something +about the framework -- and the public-surface changes a widget or app +author would notice, which is all this file used to hold (widened on +Iris's instruction, 2026-09-08: "any major additions or design things +should be added there, not just public API stuff"). Small and trivial +things still stay out. An entry gives the date, what changed, why, and a short before/after where it helps judge the change without the session that made it. Newest first. @@ -65,6 +69,17 @@ what everything did before. A code fence was opening at the end of its longest line, in the middle of a word. `Scroll::new` takes the edge as a third argument rather than deciding for its caller. +The design point behind that bug is worth more than the bug: `Scroll` +held its content's length as an `f32` that was `0.0` both for "there is +nothing here" and for "I have not drawn yet". Those lead somewhere +different, and the code could not ask which it had -- so the first +frame's clamp computed a scroll range of zero, read `amt == len` as +"sitting at the end", and pinned itself there. It is an `Option` now, +and the clamp declines to answer a question it cannot yet answer. Any +measurement iris caches from a previous frame has this shape (LAYOUT.md +section 4's one-frame lag is the general case), so the rule is: give the +unmeasured state its own value, not a plausible number. + ## 2026-09-08: masks have a shape -- `.masked_by(shape)`, and clipping applies to touch A mask no longer carries a rectangle. It carries **the slot of a