Document deferred layout requests and verification on Iris PR 19

docs/LAYOUT.md

@@ -12,6 +12,67 @@ in flight stands. The sections from "Three names, and the one argument that
 says them" onwards are the settled design, the findings that outlived the
 working log, and the measurement method.
 
+## Deferred size requests on PR #19
+
+`Widget::draw` still returns the small, copyable `Size` of two `LayoutLen`s.
+An optional `size_request` method describes an axis without drawing it. Its
+context can query children and compose sums, minima and maxima; `None` means
+that drawing in a concrete offer is necessary. Existing leaf widgets need no
+new method: their `size_hint` supplies a plain request when available.
+
+Declarations can use expressions, for example
+`rect(color).width(leftover(1).clamp(40, 120))`. In a 300-pixel row beside an
+uncapped equal share, that child takes 120 and its sibling takes 180. At 100
+pixels they take 50 each. Comparisons can have shares on both sides, such as
+`(px(30) + leftover(1)).min(leftover(2))`. Weights must be nonnegative.
+
+A span discovers requests, measures any unknown content, solves the shared
+allocation, then places children. Known requests avoid provisional painting.
+After measuring a container, discovery can use its children's measured answers
+to finish an expression that was previously incomplete. Thus a measured leaf
+inside a nested capped row does not force the row's request to become a pixel
+constant. A custom container must implement request composition to propagate
+such expressions through itself.
+
+Plain sums retain the existing symbolic allocation path. Comparisons with a
+known ordering (pixels with equal fractional/share coefficients, or shares
+with equal fixed terms) fold to ordinary lengths. Remaining expressions are
+monotone piecewise linear functions of one share unit. The allocator advances
+through exact rational crossings until the sum fills the offered room. Caps
+return room to other shares; floors may overflow; all caps being reached may
+leave unused room. Prefix rounding gives adjacent slots the same edge.
+
+Persistent declarations share immutable expression nodes. Temporary composition
+uses a reusable arena, and each retained drawing keeps its vector capacities.
+Temporary request handles are valid only within that layout pass. An explicit
+allocated placement distinguishes a solved slot from a box that merely fills
+its parent's region, so declarations are not evaluated a second time against
+the slot they already chose. Request dependencies invalidate the allocator when
+a descendant's rules or contents change. A solved declaration retains its
+pixel length when moved, including by scrolling; it must not become a fresh
+fraction of the destination box. Relative intrinsic bounds record their input
+base separately from the widget's resulting box, and retained answers compare
+resolved bounds before reuse.
+
+Two measured cases remain intentional. Intrinsic fixed content is drawn in the
+remaining offer and then moved; drawing it in its reported size would change
+wrapping and overflow. When no leftover room exists, discovered intrinsic
+shares use that same measured path. Cross-axis span maxima also remain measured:
+a main-axis share can be hidden, so the maximum of every child's request is
+not necessarily the maximum of the children that actually draw. Generalizing
+that would require carrying visibility through the expression system too.
+
+The allocation rig forces every widget to redraw across 100 resize frames:
+both the plain and clamped eight-row fixtures allocate zero times after warm-up.
+This is a measured property of those stable visible trees, not a guarantee for
+arbitrary widgets or visibility changes. An eight-level known nested span paints
+its leaf once. The 40-row, 1,000-frame text resize rig costs 9,891,085,554 retired
+instructions versus 9,341,015,256 at `de1eb7e` (5.89% more), with the same printed
+geometry. Request dependency tracking has a cost even when text still needs
+measurement. The 400-tree unbounded cold dump preserves all 34,986 boxes.
+
+The app's submodule pin is unchanged. This design lives on Iris PR #19.
+
 ## Design
 
 ### UI ownership and frame access