Move the settled layout vocabulary into LAYOUT.md and prune the handoff

The handoff had grown a chronicle of what each commit renamed. What is
durable about it -- the three names, and the one argument a container uses
to say them -- is design, so it goes to `docs/LAYOUT.md` as its own section
and the handoff keeps a pointer plus where the branch stands.

`docs/PLAN.md`'s "frame/extent experiment" entry described a prototype in
retired words; it becomes a pointer, and the one finding it held that was
not recorded elsewhere -- why the extent-relative child-frame trial was
removed -- joins the failed hypotheses in `docs/LAYOUT.md`.
This commit is contained in:
iris-ai committed 2026-09-19 18:06:28 -04:00
1 parent 265ce6f829
commit 61a2f601bb
4 files changed
+113 -98

No files matched your search

+10 -28
View File
@@ -864,34 +864,16 @@ such as corner radius and text's position within horizontal overflow use
`Len`. Flexible padding participates in the same proportional allocation as a
span rather than silently discarding its `rest` component.
**The frame/extent experiment keeps measurement and geometry references separate**
(2026-09-17, prototype only; verification and costs in `HANDOFF.md`). The parent
chooses the reference for fractions; placing a widget's reported size does not
replace that reference. A measurement also records the available extent, so
reusing it checks both inputs. Retained primitive and mask coordinates name
whether they follow the frame or the extent. Numeric extent reads constrain
layout validity; merely drawing in an extent does not require another widget
evaluation when it moves. Widgets also retain their original local frames,
so reuse composes positions in the same order as a fresh draw instead of
recovering fractions by division. The experimental oracle requires exact
pixel-region equality. `Widget::draw` remains the only layout body. The
prototype has significant container-update costs and is not yet adopted into
the pinned framework. A container's length query can evaluate the offered extent
without first placing the child's reported size; the parent's subsequent draw
assigns the final slot using the same `Widget::draw` body. A parent-selected slot
still honors a fixed child's alignment within that slot. Answer dependencies
are collected only from child sizes actually read; drawing dependencies
include all painted children. Root resize and local propagation check both
contracts. An unchanged answer with a wider validity range retains its old
contract: the parent's guarantee is still valid, and narrowing back must not
trigger layout. The same rule applies to retained drawing validity. A changed
declared size defers to its direct parent, then ordinary bottom-up propagation
stops when both contracts remain unchanged. Blanket ancestor invalidation is
unnecessary. The extent-relative child-frame API trial was removed: the major
size/resize cost came from conflating these dependencies, not from Pad and
Stack's conservative raw-placement reads. Cold layout and widespread content
changes still perform excess provisional work; that residual has not been
established as necessary for correctness.
**The one-ask layout design is settled, and lives in `docs/LAYOUT.md`**
(2026-09-17 to 2026-09-19). What this entry used to describe as the
"frame/extent experiment" is Iris PR #19, and it has its own vocabulary now:
the box a parent asks a widget in is its *region*, where the drawing ends up
is its *placement*, and the length a fraction resolves against is its *rel
base*. A container says all three in one `PlaceDesc` argument. `Widget::draw`
remains the only layout body. The invariants, the measured costs, the fuzzing
method and the failed hypotheses are all in `docs/LAYOUT.md`; the app's pin at
`32f6ad8` predates every part of it, so nothing here depends on it until the
integration described in `docs/HANDOFF.md` lands.
**A `Span` leaves its children in the offered orthogonal region unless
explicitly compacted** (2026-09-12). It still reports the widest orthogonal