From 7b8b43a7d28e659c7c441556b299230cf6e612b7 Mon Sep 17 00:00:00 2001
From: iris-ai <4+iris-ai@noreply.localhost>
Date: Tue, 15 Sep 2026 16:41:03 -0400
Subject: [PATCH] Record explicit span orthogonal sizing

---
 docs/HANDOFF.md | 50 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md
index 05cab4c..79dcc3e 100644
--- a/docs/HANDOFF.md
+++ b/docs/HANDOFF.md
@@ -8,7 +8,7 @@ log.
 
 Canonical Iris `main` is **`ca2b4b2`** (#17, the headless rig). **#18
 `split/18-position-chain`** is open in `/home/bob/repos/iris-pr18`; its local
-head is **`29c7881`**, forty-five commits, pushed to the fork. No PR reviews
+head is **`f437495`**, forty-six commits, pushed to the fork. No PR reviews
 were present when checked on 2026-09-15; the verification summary is posted on
 the PR.
 
@@ -17,14 +17,27 @@ The current head completes LAYOUT.md §2's position chain and the requested
 nothing is left. A child that also asks for pixels or a relative fraction keeps
 that part and overflows as before.
 
-The last commit replaces the parallel resize rules with one retained-layout
-contract, `Holds`: the interval of box lengths for which a widget's drawing and
-reported size stay valid. Reading `Painter::px_len` or `px_size` narrows the
-interval to the length read; `Painter::holds` lets the widget widen it. Parent
-validity is the intersection of the ranges its children induce. This contract
-is trusted. A widget that declares an incorrect range is a defective widget;
-Iris does not add defensive work to recover optimizations from a false
-declaration.
+`29c7881` replaces the parallel resize rules with one retained-layout contract,
+`Holds`: the interval of box lengths for which a widget's drawing and reported
+size stay valid. Reading `Painter::px_len` or `px_size` narrows the interval to
+the length read; `Painter::holds` lets the widget widen it. Parent validity is
+the intersection of the ranges its children induce. This contract is trusted.
+A widget that declares an incorrect range is a defective widget; Iris does not
+add defensive work to recover optimizations from a false declaration.
+
+`f437495` restores explicit `Span::ortho(OrthoSize::{Children, Full})` sizing.
+`Children` remains the default and preserves the old conservative behavior:
+the largest fixed orthogonal length is reported, while any relative or
+`leftover` child makes the span report `leftover`. `Full` reports exactly
+`Len::rel(1.0)`. It does not read the children's orthogonal sizes, but their
+`Holds` ranges still propagate through placement, so a resize repositions them
+without redrawing when their own contracts permit it.
+
+Do not change `Children` to select the pixel-longest arbitrary `Len` at the
+span's current width. A fixed child and a relative child can create multiple
+self-sizing fixed points; generated seed 13 settled differently warm and cold
+under that attempted implementation. A `Holds` interval says where an already
+chosen answer stays valid, but cannot make that circular choice unique.
 
 The implementation also fixes three counterexamples found while finishing the
 rewrite:
@@ -43,22 +56,27 @@ rewrite:
 `core/src/ui/holds.rs`, the retained tests, and the generated cold-layout oracle
 pin those rules. Seeds 10 and 86 are now in the ordinary generated set.
 
-## Verification at `29c7881`
+## Verification at `f437495`
 
 - `cargo fmt --all --check`
 - `cargo clippy --workspace --all-targets --all-features -- -D warnings`
-- `cargo test --workspace`: 74 passed, 8 ignored
+- `cargo test --workspace`: 77 passed, 8 ignored
 - `cargo test --release --test generated -- --ignored
-  a_long_run_of_seeds_agrees`: 100 seeds passed in 65.63 s
-- Reference renders against `/home/bob/repos/iris-main-cmp` at `ca2b4b2`:
+  a_long_run_of_seeds_agrees`: 100 seeds passed in 66.81 s
+- The `tabs` reference at 900x1200 remained byte-identical to `ca2b4b2` after
+  retaining `Children` as the default.
+- At preceding head `29c7881`, reference renders against
+  `/home/bob/repos/iris-main-cmp` at `ca2b4b2` covered:
   `tabs`, `view`, `minimal`, and `text` at 1920x1200; `tabs` cold at
   900x1200; live resize from 1920x1200 to 900x1200; and the tab interaction
   before and after replay. Every comparison had zero differing pixels. The
   live-resize image is also byte-identical to the cold 900x1200 image.
 
-The final pre-submit review was run in four passes. It caught the retained
-layer defect above, corrected validity-range inversion for negative relative
-extents, and removed an impossible-state `unwrap` from `Scroll`.
+The final pre-submit review was run in four passes. The earlier retained-layout
+review caught the layer defect above, corrected validity-range inversion for
+negative relative extents, and removed an impossible-state `unwrap` from
+`Scroll`. The orthogonal-sizing review caught both the circular longest-child
+choice and the incompatible visual effect of making `Full` the default.
 
 ### Performance