ai-app/docs/HANDOFF.md

# Handoff

Where the work in flight stands. The durable layout design and the
measurement method are in `docs/LAYOUT.md`; what the review of #19 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 `58ce74d`:
`add6774` fixes collapsed-share placement, retained mask ownership and a
redraw-on-reparent defect, `84dad21` removes repeated work in the test
harness, and `5642f20` through `58ce74d` are the vocabulary and API work
below.
The core design remains sound; round-to-nearest is still unchanged.

Two checkouts share one Git storage. `/home/bob/repos/iris` is the active
`layout/one-ask` worktree; `ai-app-2/iris` stays on `main` at the app's
`32f6ad8` pin, and is kept until the app's integration is ready.

Each round was checked with format, workspace clippy under `-D warnings`, the
workspace tests with and without `layout-diagnostics`, the release fast
oracle, and the three prescribed seed scans — 400 at depth 5, 1,000 at depth
6, 2,000 at depth 4. The cold dump covers 34,488 boxes: the fixes moved 650 of
them, all from the collapsed-share correction, and nothing since has moved
one.

## The vocabulary and the container API are settled

`5642f20` finished the rename decided on 2026-09-17, which `frame`'s return
as a length had left half-applied, and `aeb60e5` finished the word `frame`
itself. Three names, and only two of them are boxes:

- **region** -- the box a parent asks a widget in. It draws there, and a text
  wraps at it. Was `Painter::extent`, `ActiveData::part`, `DrawInfo::part`,
  `Placing::extent`, `LayoutHolds::extent`.
- **placement** -- the box its drawing ends up in, the size it reported,
  once it has answered. Equal to the region wherever it fills one. Was
  `ActiveData::extent`; `placed_extent` is now `placement`.
- **rel_base** -- not a box: the length a fraction it declares or reports is
  a fraction of. Was `frame`, which said the wrong shape.
  `Painter::frame_len()` is `Painter::rel_base()`, `LayoutHolds::frame_len`
  is `rel_base`, and `frame_and_extent` is `rel_base_and_region`.

`aeb60e5` also cut what a container has to say, since correctness and cost
had been paid for and ergonomics had not:

- **One argument says where a child goes.** `widget_at` and `place_at` take
  `impl Into<PlaceDesc>`, so a wrapper passes a `UiRegion` and says nothing
  else -- `Pad` and `Offset` are one call each. `Place` and `Part` are gone:
  `Place` was a product written as a sum, and `Part`'s three cases named
  operations the geometry already had (`UiSpan::within`, `UiSpan::shift`,
  and `placement`'s own body).
- **`PlaceDescAxis` is named after the operation**: `within`, `shifted`,
  `sized`, `WHOLE`, with `fills` and `rel_base` as builders. The rel base a
  caller does not state follows the constructor -- `within` narrows it,
  `shifted` passes it through, `sized` is it -- which removes the one rule a
  caller could get wrong with nothing failing.
- **`PlaceDesc` is a proper pair**, with `x`/`y`, `axis`, `axis_mut` and
  `from_axis` like every other pair here, so joint work is written once
  rather than per axis.
- `Painter::place_at` returns the answer and draws the child where there is
  no answer to re-express, so `Span`'s second pass is one call and its
  `drawn_across` bookkeeping is gone.
- `widget_within` and `ActiveData::narrow_rel_base` are deleted; `asked` and
  `placed` carry the rel base their ask stated.

Cold layout is byte-identical to `84dad21` across all of it, over 400
depth-5 trees.

## What is next, in order

1. **Bryan's review of #19.** Fixes are themselves unreviewed code: repeat
   `pre-submit-review` over each round's changes, and re-run the three
   fuzzers and dump diff for edits to `Span`, `Painter`, or `render_state`.
   The ordinary oracle does not replace absolute geometry and
   retained-primitive expectations.
2. **Integrate the app's Iris capabilities before changing its pin.**
   `32f6ad8` has 45 commits not reachable from the review branch; shared UI
   ownership, richer masks, Android support, and app-side performance work
   must survive the integration. The app then absorbs the branch's
   vocabulary and container API, all of it already upstream: `rest` →
   `leftover`, `SizeRule` beside widgets, alignment properties, the removal
   of `OrthoSize`, the region/placement/rel_base names above, and
   `widget_within`/`place_at`.
3. **Round-to-nearest**, CPU and shader together as one verified change.
   Bryan approved it on 2026-09-17 and neither half has landed; the
   derivation, the form to use and what to re-check are in `docs/LAYOUT.md`
   under "Rendering the grid (pending)".

## Smaller layout items, none urgent

- Nested spans pass `leftover` weight up, so three leftover children in one
  inner span beside one in another get three quarters to one quarter. No
  other layout system does that; confirm it is wanted.
- A span can overflow itself without bound, so boxes of negative length reach
  children and nothing states what a widget may assume about one.
- `Fixed::div` by zero answers `MIN`/`MAX` while `ratio` answers `ZERO`; both
  are caller bugs under `debug_assert`, but the fallbacks differ.
- `docs/LAYOUT.md` §4, §5 and the density section name `Painter::place`,
  `Painter::region()`, `SetSize`, `desired_width`, `apply_rest`, `Len::dp`,
  `Aligned` and `MaxSize`, none of which exist. Do not restore
  `OnResize::Translate` or `OrthoSize`.
- `LazySpan`, then `SizeRule::{Min, Max, Clamp}`. A cap may not contain
  `leftover`; whether `Max` narrows the child's drawing box is a product
  decision.
- `Scroll` taking a direction rather than one axis.

Other product work is in `docs/PLAN.md` and the focused documents it links.
Do not mix it into the Iris layout branch.