diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 20daf1e..27ab7a0 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,8 +6,8 @@ found is in `docs/LAYOUT_LOG.md`. ## The Iris layout repair is submitted -**Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `6c84b6f`, -and past the reviewed `cadfba0` it is four rounds, each described in +**Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `7e2b4cd`, +and past the reviewed `cadfba0` it is five rounds, each described in `docs/LAYOUT_LOG.md`: - **The repair**, `add6774` and `84dad21` -- collapsed-share placement, @@ -16,6 +16,9 @@ and past the reviewed `cadfba0` it is four rounds, each described in - **The vocabulary and the container API**, `5642f20` through `58ce74d`. - **Naming**, `55df32a` through `40b89c1`. - **A sweep over the logic those names exposed**, `8d2b7a5` and `6c84b6f`. +- **A clarity sweep**, `3da1c71` and `7e2b4cd` -- naming the pairs layout + returns, `Span::slot`, and a diagnostic that printed the rel base while + calling it the box. The settled design of the last three is in `docs/LAYOUT.md` under "Three names, and the one argument that says them". Bryan settled the API over @@ -35,7 +38,7 @@ the **cold dump**. `layout_dump` over 400 depth-5 trees is 34,492 boxes, and it is the only thing that catches two same-typed values being swapped, which is the failure mode of a rename or a move. The repair moved 650 of those boxes, all from the collapsed-share correction; every commit since has been -byte-identical to `84dad21`. +byte-identical to `84dad21`, the clarity sweep included. **Only when the change can alter what layout computes**: the three seed scans -- 400 at depth 5, 1,000 at depth 6, 2,000 at depth 4. They cost about a diff --git a/docs/LAYOUT_LOG.md b/docs/LAYOUT_LOG.md index 6ded0b0..20b8b17 100644 --- a/docs/LAYOUT_LOG.md +++ b/docs/LAYOUT_LOG.md @@ -191,17 +191,40 @@ The descriptions above preserve the original failure at `cadfba0`. Everything about naming is done: the unswept `extent`, the two same-typed boxes on `ActiveData` and `Painter`'s four holds accumulators in `5642f20`, `Part::All` in `aeb60e5`, and `Place`/`Part` themselves in `58ce74d`. The -settled vocabulary and the ask API are in `docs/LAYOUT.md`. What is left: +settled vocabulary and the ask API are in `docs/LAYOUT.md`. + +The clarity sweep of `3da1c71` and `7e2b4cd` closed the first three items +that stood here. Both are cold-dump identical to `6c84b6f`, so none of it +moved a box: + +- `Answer` {size, holds} and `Drawn` {answer, drawing_holds} replace + `(Size, LayoutHolds)` and the three-tuple with two `LayoutHolds` in it. + `try_reuse` answers `bool` rather than `Option<()>`. +- `Span::along` is `Span::slot`; `far` is `row`, `shares` is `has_room` + beside a named `any_leftover`, and `reached` guards on the weight it + divides by rather than on the numerator. +- `DrawInfo::px` was the rel base in pixels, and all three readers printed + it as the box the widget drew in. Removed; each reads + `region.to_px(window)`. `Placing::window` existed only to feed it. +- `diag::outside` holds the 23 counter lines that were inside `try_reuse`. +- `ActiveData::is_region_node` replaces four copies of + `move_idx != parent_move`; `Axis::BOTH` replaces `AXES` in three modules; + `Len::rel_min`, `rel_max` and the unused `select_len` are gone. + +What is left, none of it urgent: -- `draw_inner` returns `(Size, LayoutHolds, LayoutHolds)`, two same-typed - values ordered by convention. A named pair makes the swap unwriteable. -- `DrawInfo::px` is computed at all four construction sites and read only by - `diag::draw_request` and two `debug_assert!` messages. Compute it in the - assert. -- The `layout-diagnostics` block inside `try_reuse` is 23 lines of counters - in the middle of the decision; one `diag::outside(...)` call would keep - the branch readable. - `widget_at` does three linear scans per child (`children.contains`, `under.iter_mut().find`, `depend_on`), so a span of *n* children is O(n^2) per draw. Not a problem at today's sizes; it is worth knowing before a long transcript list lands on it. +- `PlaceSpan` is private to `place.rs`, so `Painter::in_parent` asks five + yes/no questions (`stated_rel_base`, `is_sized`, `within_span`, + `narrows_rel_base`, `does_fill`) about a three-case enum instead of + matching it. Two of those questions are redundant with one another -- + `Sized` always states a rel base -- but only because nothing constructs + a `Sized` without one, which nothing states. `pub(crate)` on the enum + would let `in_parent` read as its three cases. +- `DrawInfo` and `ActiveData` both carry `placed` and `asked`, two + `PlaceDesc` fields distinguished only by position in every literal. + They are genuinely different and documented, but the names are past + participles with no operand; a rename is Bryan's vocabulary call.