# Handoff

Where the work in flight stands. The durable layout design, the measurement
method and the findings that outlived the working log are in
`docs/LAYOUT.md`.

## The Iris layout repair is submitted

**Iris PR #19** (`layout/one-ask` at `cadfba0`, 123 commits over upstream
`main` at `ca2b4b2`) is open and waiting on Bryan. It **replaces #18**, which
is closed and whose branch `split/18-position-chain` stays as the reviewed
baseline the newer work was measured against. Bryan decided on 2026-09-19
that the experiment replaces it, because it is more performant where it
matters.

The checkout is `/home/bob/repos/iris-layout-experiment`, on branch
`wip/hint-first`, which is the same commit as `layout/one-ask`. Both are
pushed to `origin` (`iris-ai/iris`). What the branch does and what it leaves
undone is in the PR description; the settled protocol is in `docs/LAYOUT.md`
under "Frames, decided boxes and padding".

Verification at `cadfba0`, all run in this checkout:

| check | result |
| --- | --- |
| `cargo fmt --all --check`, clippy `-D warnings`, with and without `layout-diagnostics` | clean |
| `cargo test --workspace` | 123 suite, 20 core, 11 generated, green |
| `cargo test --release --test generated` | 11/11 |
| shrinker, 400 seeds, depth 5, sixteen cases | agree, 60 s |
| 1000 seeds at depth 6 | agree, 177 s |
| 2000-seed depth-4 scan, sixteen cases | agree, 295 s (82,203 widgets) |
| cold dump of 400 trees at depth 5, diffed against `f6242aa` | identical, 34,488 widget boxes |
| counters, seeds 1 and 13 at depth 8 | unchanged from `f6242aa` (the table is in `docs/LAYOUT.md`) |
| five renders, the `tabs` replay, a live resize against a cold render | all byte-identical to `a888717` |

The renderer was Vulkan on the host's RX 7900 XT: `src/default/render.rs`
asks for `Backends::PRIMARY` and `.expect()`s the adapter, so a PNG at all
means it was not the software fallback.

## What is next, in order

1. **Bryan's review of #19.** Fixes to it are unreviewed code: repeat the
   `pre-submit-review` passes over whatever each round changes, and re-run
   the three fuzzers and the dump diff for anything that touches `Span`,
   `Painter` or `render_state`.
2. **The app's Iris pin**, once #19 lands. It is still on the old submodule
   commit, and the branch changes API the app uses: `SizeRule` beside a
   widget rather than a wrapper, alignment as a widget property, `rest`
   renamed to `leftover`, `OrthoSize` gone.
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

- An undrawn `leftover` child still contributes its gap, so a vanished child
  leaves a double gap.
- 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.
- The comment on the `local == UiRegion::FULL` shortcut in `widget_at` says
  composing through `FULL` "is not quite the identity in f32"; on the grid it
  is exact and the shortcut is performance only.
- `docs/LAYOUT.md` §4, §5 and the density section name `Painter::place`,
  `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.