ai-app/docs/HANDOFF.md

# Handoff

Where the work in flight stands. The settled layout design, the vocabulary
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 `b7b8d09`,
and past the reviewed `cadfba0` it is eight rounds, each described in
`docs/LAYOUT_LOG.md`:

- **The repair**, `add6774` and `84dad21` -- collapsed-share placement,
  retained mask ownership, a redraw-on-reparent defect, and repeated work in
  the test harness.
- **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` through `1ebd4d3` -- naming the pairs layout
  returns, `Span::slot`, a diagnostic that printed the rel base while calling
  it the box, and `in_parent` matching a place's own cases.
- **A quality sweep**, `aea0387` through `69ba915` -- a kept contract judged
  against the placed box rather than the box asked about, two things nothing
  read, three reuse rejections the diagnostics could not see, and a fuzz case
  that ran only in the long scan.
- **A sweep over the renderer, the text store and the retained path**,
  `d8d5122` through `1096c31` -- a contract kept where the new window left
  it out, a surface configured under its own texture, a counter naming the
  wrong contract, things nothing reads, and a question asked through a value
  rather than a reference.
- **A sweep over the shader boundary and the position widgets**, `b7b8d09` --
  two constants the shader and the CPU both count in written twice, and a
  `Scroll` positioning content the framework positions, which cost a redraw
  at the default alignment.

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
2026-09-17 to 19; it is current, not frozen.

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, and `ai-app-2/iris` stays on `main` at the app's
`32f6ad8` pin until the integration below is ready.

### The base is `upstream/main`, not `main`

**Diff this branch against `upstream/main`. The local `main` is the wrong
base and gives a plausible-looking wrong answer.** PR #19 is
`iris-ai/iris:layout/one-ask` into `iris/iris:main`, which is the `upstream`
remote, at `ca2b4b2`. Local `main` tracks `origin/main` -- the *fork's* line,
which carries the app's own commits, is not an ancestor of upstream's main,
and sits four merged pull requests behind it (#10 parley text, #12 pointer
routing, #16 draw/size merge, #17 headless rig).

    git diff main...layout/one-ask             # WRONG -- base 7b54aaf
    git diff upstream/main...layout/one-ask    # right -- base ca2b4b2

`git iris-base` and `git iris-diff` are configured in this checkout and use
the right one. The authority is gitea, when it matters:

    curl -s -H "Authorization: token $(cat ~/.config/gitea/token)" \
      https://git.arirex.me/api/v1/repos/iris/iris/pulls/19 \
      | python3 -c 'import json,sys; print(json.load(sys.stdin)["base"]["sha"])'

Nothing here can be fixed by renaming: `main` is the app submodule
worktree's checked-out branch at its `32f6ad8` pin, and the two worktrees
share one ref store. Git has no way to record a pull request's base, so the
note is the mechanism.

This has already cost real work. The sixth sweep reviewed against local
`main` for half a session (Bryan caught it, 2026-09-20), and reported the
parley migration's undo path as this branch's. The fourth and fifth sweeps
deleted `Painter::text_data`, `ActiveData::size_deps` and `SizeRule::apply`
partly on the same false reading; the deletions stand on their own merits --
`text_data` had no caller at `ca2b4b2` either, and `size_deps` was read there
and orphaned by this branch's rewrite -- but "arrived on this branch" was not
the reason for all of them.

### How to check a round

**Always**, because they cost nothing: format, workspace clippy under
`-D warnings` with and without `layout-diagnostics`, the workspace tests, and
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`.

**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
quarter of an hour and they exist to find logic that is wrong on some tree
shape, so a rename has nothing for them to find (Bryan, 2026-09-19). Never
start one and then edit the tree: cargo rebuilds mid-flight and exits 1 from
a compile error, which reads exactly like a fuzzer failure.

## 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 apply the gate above to
   whatever each one touched. The ordinary oracle does not replace absolute
   geometry and retained-primitive expectations.
2. **A review of everything written before the review gate existed.**
   `pre-submit-review` and the rule that nothing is submitted unreviewed
   arrived on 2026-09-13, well after the Rust port and most of Iris were
   written, so all of that code went in unreviewed and none of the five
   sweeps above covered more than the layout branch. It wants a pass of its
   own (Bryan, 2026-09-20). The surface-texture defect in `02048ea` is the
   argument: nothing about that arm was hard, and it was written wrong
   anyway, which is what a first reader catches and a later sweep of some
   other subject does not.
3. **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. What has to survive is those capabilities,
   not the calls the app makes today: the app is to be largely rewritten
   against the new API rather than ported call by call, so nothing in Iris
   is kept alive for the app's sake (Bryan, 2026-09-20).
4. **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)".

Wanted but not started, recorded in `iris/TODO`: transforms on a move entry,
so a whole subtree scales or rotates with one buffer write and no redraw.
Compose-style stretch at the end of a scroll area is the use that prompted
it. A move entry only translates today, and composing through one scales the
`rel` part while `px` passes through untouched, so fixed-size content and
glyphs do not follow a shortened entry.

## 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.