ai-app/docs/LAYOUT_LOG.md

# Layout findings log

What the sessions reviewing Iris's retained layout found, kept so that
nothing here is rediscovered. Each entry says who found it and when.
**Delete this file when #19 lands and its fixes are in**; what must outlive
it (settled design, the measurement method) belongs in `docs/LAYOUT.md`, and
the current plan is in `docs/HANDOFF.md`.

## What the review of #19 found (2026-09-19)

Read at `cadfba0` in the `iris/` submodule of this checkout, which is the
same commit as `layout/one-ask`. `cargo fmt --all --check`, clippy
`-D warnings` and the 123-test suite are clean there, so both defects below
are live behaviour rather than anything the tests say.

### A span misplaces the slot after a collapsed `leftover` child

`src/widget/position/span.rs:101` keeps two cursors while it places: `fixed`,
everything taken so far, and `start`, where the next slot begins. The branch
that drops a share child with no room to divide advances `fixed` by the gap
and not `start`:

```rust
if len.leftover > Weight::ZERO && len.px == Px::ZERO && len.rel == Rel::ZERO && !shares {
    painter.undraw(child);
    fixed.px += self.gap;
    continue;              // `start` still excludes this gap
}
let from = start;
```

In a 400 px row with `gap(10)` over children of 200 px, `leftover(1)` and
180 px -- exactly full, so nothing is left over and the share collapses --
the tail is placed at `(215, 0)..(395, 100)`. Its slot was 210..400, a gap
too long and a gap too early, and the declared 180 was then centred in it.
The row reports a total that ends at 400. A child drawn with `rel` lengths
is stretched into the extra gap instead of being centred in it, because the
slot is a `Place::Fill`.

Recomputing the cursor in that branch fixes it, and the tail lands at
`(220, 0)..(400, 100)`:

```rust
start = shared(fixed, taken, total.leftover, room);
```

The 123-test suite passes with the line in. Nothing in it or in the
generated oracle catches the defect: warm and cold layouts are wrong
identically, so an oracle comparing the two cannot see it. This is the
sharp form of the handoff's older "a vanished child leaves a double gap"
item, which described the accounting and not the misplacement.

### A reused child keeps the mask its parent replaced

`ActiveData::parent_mask` is recorded and documented as the inherited mask
"the one a redraw of it must not be handed back", but `try_reuse`
(`core/src/ui/render_state.rs:565`) never compares it with `info.mask`: it
gates on dirtiness, layer, move parent and region-node status only.
`Painter::set_mask` pushes a fresh `MaskIdx` on every draw, so a masking
widget that redraws while its child is reused leaves that child's
primitives naming a mask nobody updates again:

```
frame 1: masked mask=Id(0)  inner mask=Id(0)
frame 2 (the masked widget alone marked): masked mask=Id(1)  inner mask=Id(0)
frame 3 (the subtree moves up to y=10):
   mask 0: y starts at 50    <- what the inner's primitives are clipped by
   mask 1: y starts at 10    <- the live one, clipping nothing
```

The child's drawing is then clipped 40 px too high and its top is cut off.
`main` guarded this with `active.mask == mask` in its reuse gate and
re-marked the owners of a rebuilt mask in `remask_shape_users`; the rewrite
dropped both.

Returning `None` from `try_reuse` where `active.parent_mask != info.mask`
fixes the repro and keeps the suite green, but it redraws the whole subtree
whenever a masking ancestor redraws. The better fix is to give `set_mask` a
per-widget mask slot kept across redraws, the way `UiRenderState::move_slot`
already keeps a move entry, so the index is stable and `reposition` goes on
updating the one the descendants name.

### Neither path has a test

The suite passes with and without both fixes. A span case belongs in
`tests/cases/layout.rs` and a mask-reuse case in `tests/cases/retained.rs`
when they land.

### Clarity, in the order worth doing

- **`extent` is back.** `core/src/ui` says `extent` 138 times, its comments
  say "box" 153 times, and the types are all `UiRegion`. Bryan renamed this
  to `placement` on 2026-09-17; `frame` survived with its new meaning as a
  length, `extent` did not. One sweep over `Painter::extent`,
  `ActiveData::{extent, part}`, `placed_extent`, `frame_and_extent` and
  `LayoutHolds::{extent, extent_len}`.
- `ActiveData::part` and `::extent` are both boxes told apart only by
  prose, and `draw_at` writes `part: extent` from one value. `asked_in` and
  `drawn_in` would say it in the names.
- `Painter` accumulates a `LayoutHolds` under four names that do not match
  the four fields they become (`window_own`, `extent_own`, `frame_own_len`,
  `extent_len`). One `own: LayoutHolds` field deletes the mapping.
- `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.
- `Part::All` is exactly `Part::Of(UiSpan::FULL)`: `Of` composes through
  `within`, and `through(Len::FULL)` maps a range back to itself, which
  `the_whole_of_a_box_maps_back_to_itself` already asserts. It buys a
  separate arm in `in_parent` and in `Part::of`. Keeping it as sugar is
  defensible; the case analysis being wider than the geometry is the thing
  to decide about rather than to leave unstated.