ai-app/docs/LAYOUT.md

# iris: one `draw` that reports a size

Iris, 2026-09-04:

> I don't like that widgets need both a draw and size functions. I'd much
> rather them have a single draw that reports a size, and if it needs to be
> moved then that can be done after the fact efficiently, or resized just
> done after as well. This should be done efficiently like everything else
> tries to do right now.

**Implemented 2026-09-04.** Every widget was migrated in one change; none
kept `desired_width`/`desired_height`. What is kept below is the design as
it stands, the five corrections implementation forced (read those before
touching `Aligned`, `Sized`, `MaxSize`, `Scroll` or the move-slot lifecycle
in `render_state.rs` -- each is a real bug the first draft would have
reproduced), and the two later additions that build on it. The
pre-implementation framing -- what the old trait looked like, the checklist
the design had to answer, the migration list, the pass conditions and the
"copy this into the design log" note -- was deleted on 2026-09-08,
having been carried out.

## Design

### 1. The new `Widget` trait

```rust
pub trait Widget: Any {
    /// Draw within `painter.region()` (the space the parent offered) and
    /// report how much of it was actually used, per axis.
    fn draw(&mut self, painter: &mut Painter) -> Size;

    /// True if `draw`'s output (both the primitives it writes and the
    /// `Size` it returns) is the same for any `painter.region()` of the
    /// same *content* -- an icon, a fixed-size rect, an already-decoded
    /// image at its natural size. Default `false` (redraw on any change to
    /// the offered region) because assuming independence wrongly produces
    /// a stale draw; a widget must opt in.
    fn is_size_independent(&self) -> bool {
        false
    }
}
```

No `available` parameter: `Painter` already carries the region the parent
handed down (`Painter::region()`, `core/src/ui/painter.rs:137`) and already
exposes the pixel-resolved form (`px_size()`, `:156`) and the output surface
size (`output_size()`, `:152`). Passing it again would be the same value
under a second name. `desired_width`/`desired_height` (`core/src/widget/mod.rs:20-21`)
and `WidgetAxisFns::desired_len` (`:24-35`) are deleted outright — not
deprecated, not kept as a fallback — because a widget that implements both
`draw` and `desired_*` for the same thing is exactly the "two names for one
concept" the code rules call out, and it is what today's `Span::desired_ortho`
(`iris/src/widget/position/span.rs:98-152`) already complains about in its
own comment: "this literally copies draw so that the lengths are correctly
set in the context, which makes this slow and not cool." Folding sizing into
`draw` deletes that duplicate simulation, not just moves it.

**No single-draw alternative was found that does less work per frame.** The
two-method trait was checked against three properties a real screen needs —
a row placing children in sequence, a widget centering on its own content,
and wrapped text — and in every one, `draw` already has to visit the child
to get a size that is *this specific one's* answer, which today's
`desired_width`/`desired_height` re-derive by re-running (a shrunk copy of)
the same layout the draw pass will do again. So the two-method trait is not
"measure once, draw once" in the general case; it is "measure once per axis,
then draw once," i.e. up to three visits per widget per frame, against one
under the design here. The single-draw model is therefore adopted as
proposed, not merely accepted as a preference.

### 2. Move: O(1) per moved subtree, via a per-widget offset chain

**What exists today, and why it is not O(1).** `UiRenderState::mov`
(`core/src/ui/render_state.rs:156-168`) fires when a widget's region keeps
its *size* but changes *position* (`draw_inner`, `:85-100`:
`active.region.size() == region.size()` after excluding the exact-match
case). It rewrites every primitive's `region` field via
`Primitives::region_mut` (`core/src/render/primitive.rs:176-179`) for the
widget's own primitives, then recurses into every child — O(primitives in
the subtree). Both call sites that trigger it today, `Scroll::draw`
(`iris/src/widget/position/scroll.rs:29-31`) and `Offset::draw`
(`iris/src/widget/position/offset.rs:9-11`), are "translate this subtree by
an abs pixel amount, `rel` framing unchanged" — a transcript scroll
re-touches every glyph in every visible row, every frame of the drag, and
I3's target is 800 rows on screen.

**Recommendation: a per-widget offset slot forming a parent-linked chain,
resolved in the vertex shader.**

- `UiData` (`core/src/ui/mod.rs:14-20`) gains
  `pub move_offsets: TrackedArena<MoveOffset, u32>`, the same arena shape
  already used for `masks: TrackedArena<Mask, u32>` on the line above it.
- `render/data.rs` gains `pub struct MoveOffset { pub delta: [f32; 2], pub
  parent: u32 }` (`Pod`/`Zeroable`, `parent = u32::MAX` = "no ancestor,
  add nothing more"). A pure abs-pixel translation, not a general
  `UiRegion` remap — sufficient for every existing call site (above).
- `PrimitiveInstance` (`render/data.rs:11-18`) gains `pub move_idx: u32`,
  a vertex attribute at `@location(7)` beside `mask_idx` at `6` — the same
  kind of per-instance handle.
- `ActiveData` (`core/src/ui/active.rs`) gains `pub move_slot: MoveIdx`,
  assigned **when the widget is first drawn** (`draw_inner`, beside
  `active.insert`), with `parent` = the drawing widget's parent's slot.
  `Painter` threads a `move_slot` field down exactly as it already threads
  `mask` and `layer` (`painter.rs:9-20`), so a freshly-drawn descendant is
  correct from its first frame — nothing is ever retrofitted onto an
  already-active primitive. An unmoved widget's slot just stays `[0, 0]`.
- `Painter::primitive_at` (`painter.rs:23-38`) writes `move_idx:
  self.move_slot`, matching how it already writes `mask_idx: self.mask`.
- `mov(id, delta)` becomes: look up `id`'s slot, write
  `move_offsets[slot].delta += delta`. One write — no primitive touched, no
  recursion, since descendants already reference this slot transitively.
- `shader.wgsl`'s vertex stage, after computing `top_left`/`bot_right` in
  pixels (after `:106`, before the clip-space divide at `:113`), walks
  `move_idx → move_offsets[i].parent` for a bounded number of steps (a
  small constant, e.g. 16, with a CPU-side debug assertion that no chain
  exceeds it), summing `delta` into both corners. Cost is O(chain depth),
  paid every frame regardless of whether anything moved — negligible next
  to the per-fragment texture sampling TEXTURES.md already measures this
  GPU as not bound by.

**Why the chain, not the flatter thing first proposed.** Iris's own
phrasing — "every instance carries an index into a small per-widget offset
buffer" — describes a flat table: one slot per subtree *declared* movable,
no parent link. It breaks the moment two such subtrees nest — a row inside
a scrolling list, itself later given its own animated offset (a
swipe-to-delete mid-scroll) — because the row's primitives would have to
pick one slot and lose the other's contribution. The chain costs one extra
field and a bounded shader loop in exchange for no such gap, and since
every `ActiveData` gets a slot unconditionally rather than lazily, it costs
no more at the common depth of one than the flat version would.

**Against `region_mut` as the steady-state mechanism**: rejected for being
O(primitives in the subtree) — the cost this section removes — but kept
for a resize that changes a region's `rel` component (a genuine reflow,
§3) and for a size-independent widget's resize (§3), where the content's
shape doesn't change and one field write already suffices.

### 2b. Two more readers of "where is this widget," and masks

Moving the offset into the vertex shader means `ActiveData.region` is no
longer the on-screen truth once a widget has been moved — it is where the
widget was *drawn*, before any `move_offsets` delta. Two things read it as
if it still were, and both must move to a resolved query or they silently
answer with the pre-move position: a click landing on a scrolled row would
be routed to whatever used to be there, with nothing on screen to say so —
exactly the "wrong answer that looks like a right one" case the code rules
single out.

**Hit-testing.** `SensorUi::run_sensors` (`src/default/sense.rs:154-200`)
does the actual pointer routing, and line 170 is the read in question:
`let shape = self.active.get(id).unwrap().region;` (`self: &UiRenderState`),
immediately turned into pixels and tested against the cursor at `:171-172`.
Under this design that region must be resolved through the same chain the
GPU walks before it means anything. Add to `UiRenderState`:

```rust
/// `active[id].region`, corrected by every `move_offsets` delta between
/// `id` and the root — the CPU-side twin of the vertex shader's chain
/// walk, over the same arena, so the two cannot disagree about where a
/// widget is. O(chain depth), not O(primitives): a plain Rust loop over
/// `move_offsets`, bounded by the same constant the shader loop uses
/// (name it once, e.g. `render::MOVE_CHAIN_LIMIT`, and reference it from
/// the WGSL loop bound in a comment, since WGSL cannot `include!` a Rust
/// const across the language boundary).
pub fn resolved_region(&self, id: WidgetId) -> UiRegion;
```

`window_region` (`core/src/ui/render_state.rs:264-267`), the public
coordinate query already used outside hit-testing
(`src/default/attr.rs:15,17,70`, e.g. positioning one widget relative to
another's on-screen box), is reimplemented to call `resolved_region(id)`
before `.to_px(...)` instead of reading `.region` directly — one change
covers both call sites listed there. `sense.rs:170` changes to
`let shape = self.resolved_region(*id);`. Both are required the moment §2
lands, not an optional follow-up: an unmoved widget's chain is empty and
`resolved_region` costs one arena read to find that out, so there is no
version of this design where skipping the fix is a legitimate
optimization — it is a correctness gap, not a performance one.

**Masks.** `Painter::set_mask` (`core/src/ui/painter.rs:49-52`) bakes the
painter's *current* region into a `Mask` pushed onto
`masks: TrackedArena<Mask, u32>` (`core/src/ui/mod.rs:19`), and the
fragment shader clips every primitive against `masks[in.mask_idx]`'s raw
`rel`/`abs` fields, unaffected by any move (`shader.wgsl:147-157`). If the
widget that called `set_mask` — `Masked::draw`,
`iris/src/widget/mask.rs:7-11`, `painter.set_mask(painter.region()); ...` —
is itself later moved, its clip rectangle stays where it was drawn while
its content moves out from under it: a visibly wrong clip, immediately on
screen, not a latency question.

Fix: `Mask` (`core/src/render/data.rs:46-49`) gains `pub move_idx: u32`,
written from `Painter::set_mask` as `self.move_slot` — the identical slot
the mask-owning widget's own primitives already get (§2), not a second
mechanism. Resolution happens in the **fragment** shader, not the CPU, and
not the vertex shader either: `shader.wgsl`'s mask check (`:147-157`)
currently computes the mask's `top_left`/`bot_right` inline from
`masks[in.mask_idx]`; that computation is extended to walk the same
move-offset chain §2 added, via one shared function —

```wgsl
fn resolve_move(idx: u32) -> vec2<f32> { /* the bounded parent walk, used by both stages */ }
```

— called from `vs_main` for a primitive's own corners and from `fs_main`
for its mask's corners, so the walk is written once and the two stages
cannot drift apart (the sibling-rule from the code rules: one loop, not a
hand-copied second one in the other shader stage).

**Why the fragment shader, not a CPU-side mask rewrite at move time.** A
primitive's mask is frequently owned by a *different* widget than the
primitive itself — often several levels up a subtree, with its own,
independent move slot — so a primitive's resolved offset and its mask's
resolved offset are two different chain sums, both needed, and only the
fragment shader has both `in.move_idx` (this fragment's own chain) and
`in.mask_idx` (indirecting to a second, possibly unrelated chain) already
in hand per-fragment. Resolving mask regions on the CPU at move time would
mean, for every `mov()` call, walking forward to every mask instance the
moved widget's slot could affect and rewriting its raw region — exactly
the O(subtree) cost §2 exists to remove, just moved from primitives to
masks. The fragment shader already re-reads `masks[in.mask_idx]` every
frame (`:148`); one more arena read to resolve its chain costs nothing
extra in kind.

**The scroll-container case, checked rather than assumed.** A masked,
scrollable region is built as a `Masked` wrapping a `Scroll`
(`iris/src/widget/position/scroll.rs`, `iris/src/widget/mask.rs`) — the
viewport border is drawn (and `set_mask` called) by `Masked`, which is
never itself the target of `mov()`; only `Scroll`'s inner content is,
every frame the user drags. Because each widget's move slot is its own
(§2: assigned per `ActiveData`, not shared), `Masked`'s mask references
its own, stationary slot, while the scrolled content underneath references
a separate, deeper slot whose `parent` chain passes through — but does not
write to — the viewport's slot. Moving the content therefore never touches
the mask's resolved position, and the mask staying still while its content
slides past it is what this design already produces with no special case,
not an extra rule that had to be added for it.

### 3. Resize scope

A resize is "the region a widget's parent offers it changes such that the
widget's draw might produce different output" — as opposed to a move, which
by construction cannot (§2 is scoped to pure translation). Two independent
narrowings apply, and both are real, measured properties of the code as it
stands rather than new machinery:

**(a) A window resize does not, by itself, require touching most widgets.**
`shader.wgsl:105-106` recomputes every primitive's pixel position from
`window.dim` and the primitive's stored `rel`/`abs` pair *every frame,
already, on the GPU*. A widget laid out purely in `rel`/`abs` terms (no
call to `px_size()`, `output_size()`, or anything else that reads a
concrete pixel count) is therefore already correct after a resize with zero
CPU work — the shader did it. `UiRenderState::needs_redraw_all`
(`render_state.rs:229-231`) currently ignores this and redraws the entire
tree on every `resized`, which was the safe default while sizing and
drawing were two passes; it should be narrowed to only the widgets that
*do* read a concrete pixel value. Track this the same way `needs_redraw`
already tracks per-widget dirtiness (`Widgets::needs_redraw`,
`core/src/widget/widgets.rs:9`): a widget's `draw` call marks itself
pixel-dependent by calling through `Painter` methods that read
`output_size`/`px_size` (both already funnel through `Painter`, so the
marking is one line at each), and `resize()` (`render_state.rs:32-35`)
walks only that set instead of unconditionally setting `resized = true`
for a full `redraw_all`. This turns "every resize redraws everything" into
"every resize redraws what depends on pixels" — a real behavior change
beyond what was asked, so verify it against the I0b `pre_present_notify`
resize regression (that fix depended on `redraw_all`'s completeness)
before narrowing this.

**(b) A widget's `available` (its parent's offered region) can change
without the widget's *content* changing — this is what
`is_size_independent` (§1) answers.** When a container's own layout shifts
(a sibling grew or shrank, changing this widget's offered box), a widget
that returns `true` from `is_size_independent` is not redrawn: its
primitives are unaffected by size, only by placement, so the parent
either (i) issues a move (§2) if only position changed, or (ii) rewrites
the primitive's `region` fields directly via `region_mut` if the box
changed shape too (still O(primitives owned directly by this widget, not
its subtree, since a size-independent widget by definition has no
size-dependent descendants worth distinguishing — in practice this is
always a leaf: `Rect`, `Image`, a fixed glyph). A widget that returns
`false` (the default) is redrawn in full whenever `available` changes,
which is correct always, just not free.

**Ancestor propagation** (a resized child changing its own reported size,
requiring its parent to re-lay-out) is unchanged in spirit from today's
`redraw` (`render_state.rs:270-305`), which already walks up exactly the
ancestors whose cached size differs from the new one and stops as soon as
a size is unchanged (`:274-286`). That loop moves from consulting
`Cache.size` to consulting `ActiveData.size` (§5) but keeps its shape.

### 4. Wrapped text, and "needs child height before choosing width"

**Wrapped text is not a special case any more; it already reads as one
draw.** `TextView::render` (`iris/src/widget/text/mod.rs:57-76`) already
does exactly what single-draw asks for: it reads `ctx.px_size().x` as the
wrap width, shapes once, and memoizes the shaped layout keyed on that width
plus a changed-flag on the buffer and attrs (`:63-69`) — a second call with
the same width is a hash-map-style cache hit, not a re-shape. Under the new
trait this collapses `Text::draw`/`desired_width`/`desired_height`
(`text/mod.rs:133-147`, three functions) into one `Text::draw` that calls
`self.view.draw(painter)` once, which internally still calls `render`
once, hits its own cache, and returns the size it already computed. No
new caching is needed here; the two now-redundant call sites
(`desired_width`/`desired_height` each separately calling `render`) simply
disappear, which is a second `render` avoided per frame per text widget
that is being measured by a parent.

**"Parent wants the child's height before deciding the width it will
offer"** — the genuinely circular case named in the brief, e.g. a column
that sizes its own width to its widest child, where that child is wrapped
text whose height (which the column's *own* height depends on) depends on
the width the column has not yet decided. This is not solvable in one pass
for the same reason it is not solvable in CSS shrink-to-fit with wrapped
content: the two axes' answers are mutually dependent. `Span::desired_ortho`
(`span.rs:98-136`) already hits exactly this today and already resolves it
by an explicit second, throwaway pass (its own comment: "this literally
copies draw ... which makes this slow and not cool"). The design keeps that
resolution, made explicit rather than accidental: `Painter` gets

```rust
/// Draw `child` at a provisional region to learn its size under one
/// axis's worth of assumption, discard everything it wrote, then draw it
/// again at the region that assumption produced. For the rare parent that
/// cannot pick an offered size without already knowing the answer.
/// Twice the cost of one `draw`; every other case in this file avoids it.
pub fn draw_twice(&mut self, child: &StrongWidget, first: UiRegion, second: impl FnOnce(Size) -> UiRegion) -> Size;
```

implemented as: draw at `first`, record `Size`, remove the widget and its
subtree the same way a resize-triggered redraw already does (`draw_inner`'s
"if not \[same region\], maintain resize and track old children," `:97-100`,
which already frees the old primitives before redrawing) — reusing that
path rather than adding a second one — draw again at `second(size)`, return
the final `Size`. It is opt-in and named for its cost, so a widget only
pays it if it is the one that needs it; `Span`'s cross-axis case is the one
call site converted to it, replacing the hand-rolled duplicate loop.

### 5. Caching and invalidation

`Cache.size` (`core/src/ui/cache.rs`) is **deleted, not replaced with an
equivalent** — the thing it memoized (a `desired_width`/`desired_height`
answer, independent of drawing) no longer exists as a separate query, so
there is nothing left to cache at that layer. What already provides "an
unchanged subtree costs nothing" is the check `draw_inner` performs before
touching a widget at all (`render_state.rs:85-90`): if the widget is active,
its region is unchanged, and it is not marked dirty, `draw_inner` returns
immediately — no `Painter` constructed, no primitive touched, no shader
work beyond what the GPU already redraws from the unchanged instance
buffer. That check is kept exactly as it is; it is the caching mechanism,
and it already operates at (id, region) granularity, which subsumes "(id,
available size)" once size *is* what a region change means.

What is added: `ActiveData` gains `pub size: Size` — the value `draw`
returned, stored the moment it is (`draw_inner`, alongside building the
`ActiveData` struct at `:134-143`). This is what a parent placing this
widget for a second frame without redrawing it (because nothing changed)
reads instead of recomputing — it replaces `Cache.size`'s role of "answer a
size question without a full draw" with "read the size of the last actual
draw," which is always available because `draw_inner`'s skip path is only
reachable once the widget has been drawn at least once. `Cache::remove`/
`Cache::clear` (`cache.rs:9-17`) are deleted with the type; `ActiveData`
already has an equivalent lifecycle (removed in `remove`/`remove_rec`,
`render_state.rs:171-198`, freed with the widget).

### 6. Before / after

**A leaf, `iris/src/widget/rect.rs`** — the size-independent case:

```rust
// before
impl Widget for Rect {
    fn draw(&mut self, painter: &mut Painter) {
        painter.primitive(RectPrimitive { color: self.color, radius: self.radius,
            thickness: self.thickness, inner_radius: self.inner_radius });
    }
    fn desired_width(&mut self, _: &mut SizeCtx) -> Len { Len::rest(1) }
    fn desired_height(&mut self, _: &mut SizeCtx) -> Len { Len::rest(1) }
}
```

```rust
// after
impl Widget for Rect {
    fn draw(&mut self, painter: &mut Painter) -> Size {
        painter.primitive(RectPrimitive { color: self.color, radius: self.radius,
            thickness: self.thickness, inner_radius: self.inner_radius });
        Size::REST // fills whatever it was given -- used == available
    }
    fn is_size_independent(&self) -> bool { true } // content never depends on region size
}
```

**A container that needs the child's size before placing it,
`iris/src/widget/position/align.rs`**:

```rust
// before
impl Widget for Aligned {
    fn draw(&mut self, painter: &mut Painter) {
        let region = match self.align.tuple() {
            (Some(x), Some(y)) => painter.size(&self.inner).to_uivec2().align(RegionAlign { x, y }),
            (Some(x), None) => { let x = painter.size_ctx().width(&self.inner).apply_rest().align(x);
                UiRegion::new(x, UiSpan::FULL) }
            (None, Some(y)) => { let y = painter.size_ctx().height(&self.inner).apply_rest().align(y);
                UiRegion::new(UiSpan::FULL, y) }
            (None, None) => UiRegion::FULL,
        };
        painter.widget_within(&self.inner, region);
    }
    fn desired_width(&mut self, ctx: &mut SizeCtx) -> Len { ctx.width(&self.inner) }
    fn desired_height(&mut self, ctx: &mut SizeCtx) -> Len { ctx.height(&self.inner) }
}
```

```rust
// after
impl Widget for Aligned {
    fn draw(&mut self, painter: &mut Painter) -> Size {
        let full = painter.region();
        // Draw once at the full region to learn the child's real size --
        // this placement is provisional and corrected below without a
        // second draw.
        let used = painter.widget_within(&self.inner, full);
        let region = match self.align.tuple() {
            (Some(x), Some(y)) => used.to_uivec2().align(RegionAlign { x, y }).within(&full),
            (Some(x), None) => used.x.apply_rest().align(x).within(&full),
            (None, Some(y)) => used.y.apply_rest().align(y).within(&full),
            (None, None) => full,
        };
        painter.reposition(&self.inner, region); // O(1): one offset write, no second draw
        used
    }
}
```

`Painter::widget_within`/`widget`/`widget_at` (`painter.rs:55-76`) change
return type from `()` to `Size`, carrying the child's `draw` result back —
the only signature change needed to let a parent see what its child used.
`Painter::reposition` is new, computing the delta between where a child
was actually drawn and where it belongs and calling the O(1) `mov` from
§2. `SizeCtx` and `Painter::size_ctx`/`size`/`len_axis` (`painter.rs:141-150,
180-182`) are deleted — nothing calls `desired_len` any more, so there is
nothing left for `SizeCtx` to answer; `draw_text`/`label`/`px_size`/
`output_size` already exist redundantly on both `SizeCtx` and `Painter`
today (compare `size.rs:71-90` against `painter.rs:152-174`) and this
deletes the `SizeCtx` copies, keeping the `Painter` ones.

### 7. Rejected, and why

- **A flat (non-chained) per-subtree offset table**, Iris's literal
  phrasing — rejected in §2 for breaking under nested independent moves
  (a swiped row inside a scrolling list). Costs nothing extra to avoid: the
  chain is the same mechanism with one more field.
- **Keeping `region_mut` recursion as the only move mechanism** — rejected
  as the steady-state path (O(primitives in subtree), exactly what a
  transcript scroll must not pay every frame) but kept for resize-shaped
  changes (§3) where the content's own region field, not an ancestor
  chain, is what has to change.
- **A second, size-only trait method kept alongside `draw`** (e.g.
  `fn size_hint(&self) -> Option<Size>` as a fast path some widgets could
  implement to skip a draw when a cheap answer exists) — considered and
  rejected: it reintroduces exactly the "two names for one concept" split
  this change removes, for a saving `is_size_independent` (§1, §3b)
  already covers for the cases where it would actually help (fixed-size
  leaves). A widget whose size is cheap to compute but whose *drawing* is
  not (unlikely in this codebase's widget set, but conceivable) is better
  served by that widget caching its own draw output internally — exactly
  the pattern `TextView::render` already uses (§4) — than by a second
  trait method every implementor has to reason about.
- **Passing `available` as an explicit parameter to `draw`** (mirroring
  Masonry's `layout(&mut self, ctx, bc: &BoxConstraints) -> Size`, the
  yardstick per AGENTS.md) — rejected as redundant with `Painter::region()`,
  which already carries the same information into every widget that needs
  it; adding a parameter would just be a second route to a value already
  reachable, and would invite the two drifting apart.
- **Eagerly propagating a moved widget's delta into every descendant's own
  offset value** (rather than chaining and resolving in the shader) —
  rejected as O(descendant widgets), which is smaller than O(primitives)
  but still not O(1), and the shader-side chain costs nothing extra to get
  the better bound.

## Deviations found during implementation (2026-09-04)

Five corrections this file's first draft did not anticipate, each found by
`iris/run-headless.sh tabs --shot` disagreeing with a pixel-identical
pre-change screenshot (pass condition 1) and traced with `eprintln!` in
`draw_inner`/`reposition` — not by reasoning about the design in the
abstract. Recorded here rather than silently fixed in place, per the code
rules' escape-hatch requirement.

1. **`Aligned`'s provisional draw must call `painter.widget`, not
   `widget_within(&self.inner, painter.region())`.** §6's original text drew
   the sample as the latter. `widget_within` composes its `region` argument
   as *local*, `UiRegion::FULL`-relative coordinates against
   `painter.region()` (exactly what `UiRegion::FULL.within(&self.region) ==
   self.region` relies on); handing it `painter.region()` itself —
   already-resolved, window-relative coordinates — composes that frame a
   second time. For the root widget this is silently the identity (its
   region already is `[0,1]`), which is why it can look correct in a
   trivial case and only breaks once something is nested — i.e. always, in
   practice. Symptom: a centered child rendered at a wildly wrong offset
   nested more than one level deep. Fixed by using `painter.widget`, which
   hands the child `self.region` unmodified, with no second composition.

2. **A widget that reports a size smaller than its offered region must
   actually paint at that size, anchored top-left of what it was given —
   not fill the full offered region while merely *reporting* a smaller
   number.** `Sized` and `MaxSize` both had exactly this bug: their
   `desired_width`/`desired_height` predecessors capped the *reported*
   value but their `draw` bodies called `painter.widget(&self.inner)`
   unconstrained, which was harmless under the old two-pass model (a parent
   always queried the size *before* drawing, so by the time `draw` ran the
   offered region already matched) but wrong under `Aligned`'s new
   provisional-draw-then-reposition pattern, which offers the *whole*
   region on the first, learning pass. Symptom: a `.sized((100, 100))` rect
   rendered stretched to fill its whole row instead of a 100×100 square.
   Fixed by having both widgets carve the declared sub-region (`UiSpan`
   sized to the axis's `Len`, anchored at `AxisAlign::Neg`) out of whatever
   they were offered before drawing the child in it. `Image` needed the
   same treatment from the start (`texture_within` at its own natural size,
   not `texture()` at the full offered region) and was written that way in
   the first pass, once this was understood; `Rect`'s "fill whatever I'm
   given" is the one case where painting the *whole* offered region really
   is the declared behavior, so it needed no change.

3. **The move-offset chain's `parent` link cannot be found by looking up
   the parent's `ActiveData` in `draw_inner`, because the parent's
   `ActiveData` does not exist yet while its own `Widget::draw` is still
   running.** `ActiveData` is inserted only after `draw` returns
   (`render_state.rs`, end of `draw_inner`), so a child drawn partway
   through its parent's `draw` body — the ordinary case, since every
   composite widget draws its children from inside its own `draw` — would
   always read "no parent" from `self.active`, silently orphaning it at the
   root of the chain. Fixed by threading the parent's `move_slot` down
   through `Painter` (it already carries `mask`/`layer` the same way) and
   passing it explicitly into `draw_inner` as `parent_move_slot`, rather
   than deriving it from `self.active.get(parent_id)`. `move_parent_of`
   (the `self.active`-based lookup) is kept, but only for `redraw()`, whose
   target's parent genuinely is already active at that call site — the
   doc comment on it says which is which. Symptom: `reposition` computed
   the right delta and wrote it to the right slot, but the shader never
   saw it, because the primitive doing the actual painting chained to
   `u32::MAX` one level too early.

4. **`Painter::reposition` cannot reuse `active.region` as "where the
   widget currently is," because for a widget offered more room than it
   used, `active.region` is the *offered* box, not the *painted* one.**
   This only matters for `reposition` (used by `Aligned`); `mov` (used by
   `draw_inner`'s own same-size-different-position dispatch, for `Scroll`
   and `Offset`) has no such gap, because there the offered region *is*
   the visual footprint — content is sized to fill exactly what it is
   given. `reposition` instead reconstructs "from" as `active.size`
   (already tracked, per §5) anchored at `AxisAlign::Neg` within
   `active.region` — i.e. it assumes the child painted itself top-left of
   whatever it was offered, per point 2's convention — and **overwrites**
   the slot's delta rather than accumulating it the way `mov` does, since
   "from" is recomputed fresh from stable inputs every call and repeating
   the same `reposition` (an unrelated redraw elsewhere re-running this
   widget's parent) must not drift further each time. The one shape this
   does not cover: `Aligned` wrapping `Aligned`, where the inner one's own
   `reposition` may have moved its content away from top-left already. No
   widget or example in this codebase builds that today; if one needs to,
   `reposition` would need the child to report *where* it painted, not
   just how big, which is a larger change than this pass's scope.

5. **A widget's `move_offsets` slot is allocated once, on its first-ever
   draw, and reused in place — never reallocated — for every later redraw
   of the same id, with its delta reset to `[0, 0]` on each reuse.** Not
   spelled out in §2's original text, which only said slots are assigned
   "when the widget is first drawn." Reallocating a fresh slot on every
   redraw would leave any *retained* (not-redrawn) descendant's `parent`
   link pointing at a now-orphaned old slot — a permanent leak, and worse,
   a descendant that silently stops tracking its ancestor's future moves.
   Resetting the delta on reuse (rather than carrying it forward) is
   required because a full redraw bakes the widget's correct absolute
   position into the fresh `region` argument directly; a stale delta left
   over from before the redraw would double-offset it.

Two further points worth recording because they were *design decisions*
made while implementing, not bugs — `LAYOUT.md`'s own text left them
unspecified rather than getting them wrong:

- **`Scroll` offers its content a region sized by the *previous* frame's
  measured content length, not a fresh one.** A fresh measurement would
  require drawing the content once to learn its size and — since that
  provisional size essentially never matches the previously active one —
  redrawing it a second time at the real size, on every single scroll
  tick, which is exactly the cost §2 exists to remove. Using the stale
  length means an ordinary scroll (position changes, content does not)
  offers the same *size* as last frame, only shifted, which is what makes
  `draw_inner` dispatch it as the O(1) move. The cost: a real content-size
  change lags one frame before the container's scroll range reflects it,
  self-correcting the frame after (the content length itself, read from
  what was actually drawn, is never stale — only the offered *region* used
  for placement is). No example in this repository builds a `Scroll` yet,
  so this could not be checked against a pixel diff; it is covered instead
  by `iris/src/layout_tests.rs`'s three `Scroll`-based unit tests, which
  build a tree and drive `UiRenderState` directly with no GPU or window
  needed.
- **`redraw()`'s parent-relayout check draws the widget first, then
  compares the fresh `ActiveData.size` the draw produced against the size
  from before removal** — the mirror image of the old code's "query size,
  compare, decide whether to draw," which no longer has a size query to
  do the comparison with before drawing (§5 deleted `Cache`/`SizeCtx`
  along with `desired_width`/`desired_height`). This can occasionally draw
  a widget once more than the old code would have (if the parent it
  bubbles up to ends up redrawing the same widget again as part of its own
  relayout) — `draw_inner`'s own skip/move dispatch absorbs most of that
  redundancy for free, and this path was not one of the migration's measured
  conditions, so the remaining slack was accepted rather than chased
  further.

## Density: `Len::dp`, resolved at `apply_rest` time (2026-09-06)

Iris asked for a third length kind beside `abs` (physical pixels) and
`rel`/`rest` (a fraction of the parent) — IRIS_TODO.md's "density-
independent length unit" — after the P0 phone pass found 16px text
drawing at roughly a third size on a real phone. The fix that shipped
first (RUST.md's P0 box) was a global stopgap: divide the whole window
into a "logical" coordinate space (physical ÷ `content_scale`) and let
the shader's NDC mapping stretch it back up onto the real framebuffer.
That fixed the *size* but not the *sharpness* — a glyph rasterised at the
small, pre-stretch size and then stretched onto more physical pixels than
it has texels for is blurry, which is exactly what Iris's next report
said.

**The fix**: `Len` gained a `dp` field, resolved against a `density: f32`
(physical pixels per dp) at the one place a `Len` becomes a `UiScalar`
(`Len::apply_rest`) — `abs + dp * density`. `density` lives on
`UiRenderState` (`set_density`/`density()`) and `Painter` (`density()`),
set once from `DisplayMetrics.density` in `android::view::new_peer`; the
desktop backend has no per-monitor density wired up yet and stays at
`1.0`. Every layout call site that used to call `.apply_rest()`/
`.to_uivec2()` now passes `painter.density()` (nine call sites — `Span`,
`Sized`, `MaxSize`, `Aligned`, `Scroll`, `LazySpan::place`, and
`UiRenderState::reposition` itself). This also meant the Android
boundary's global logical-space stopgap could come out entirely: window
size, touch coordinates and insets are physical pixels again, matching
`AndroidRenderer`'s own swapchain resolution, with `dp` doing the
per-length work the global divide used to do for everything at once.

**Text is the case that needed more than the `Len` plumbing.** A widget's
`font_size`/`line_height` are plain `f32`, not routed through `Len` at
all (there is no sensible `rel`/`rest` for a font size). `TextBuffer::
shape` now takes `density` directly and multiplies `font_size`/
`line_height` (and any span override) by it before handing them to
parley — so the size that reaches both the line-breaker and the
rasteriser (`TextData::place`, which reads back whatever `shape` set) is
the display's *physical* size, and the glyph atlas holds a bitmap at the
resolution it is actually shown at. `GlyphKey.size` already keys on the
resolved size, so a cache entry is naturally per-physical-size with no
further change. The one caller with no `Painter` to read density from
(`TextEditCtx::layout`, cursor movement and hit-testing) reads a second
copy kept directly on `TextData` (`TextData::density`) instead — an
accepted duplication rather than threading a `Painter` into every input
handler for one field, the same tradeoff `AndroidRenderer::content_scale`
already makes for the Diagnostics page.

**What did not change**: `rel`/`rest` are unaffected (already
resolution-independent, a fraction of the parent). `Span::gap` and
`Padding`'s four sides moved from bare `f32` to `Len` so `dp(...)` works
on them the same as any other size; a bare number is still `abs`,
physical pixels, unchanged.

## Masks with a shape (decided 2026-09-07, built 2026-09-08)

Iris, on the code block's scrolling: "the code block scrolling currently
masks in an inner rectangle. Ideally masks should have a shape
associated with them, rounded rectangle being one of them, and/or
another widget you can select, so that the mask becomes the parent
container with rounded edges. Make sure alpha works properly with it,
eg. on the corners where alpha should be decreased / multiplied."

**What exists.** `Mask` in `shader.wgsl`/`data.rs` is two `UiSpan`s and
a `move_idx`; `fs_main` resolves it and does `color *= 0.0` outside the
rectangle -- a hard cut on a pixel boundary. `Masked` (`widget/mask.rs`)
sets the painter's mask to its own region. Separately, `draw_rounded_rect`
already produces an anti-aliased rounded edge from
`distance_from_rect(pos, center, corner, radius)` with a half-pixel
`smoothstep`, and the border variant multiplies a second coverage in.

**Design** (revised the same day on Iris's two corrections: hit-testing
applies the shape too, and a mask should reference a primitive rather
than carry a copy of its shape).

1. **A mask is a reference to a primitive already drawn, plus how to
   use it.** `Mask { kind, idx, flags, parent }`: the primitive's
   binding (`RECT`, `TEXTURE`, `GLYPH`) and slot, flags (today one:
   *alpha only* -- take the primitive's coverage and ignore its colour,
   which is the default and the only mode until a need for another
   appears), and the enclosing mask's slot for nesting. The fragment
   stage evaluates the referenced primitive *at the masked pixel* --
   for a `Rect`, the same `draw_rounded_rect` coverage from the same
   SDF; for a texture or glyph, the sampled alpha -- and does
   `color.a *= coverage`. Nothing about the shape is copied: a rounded
   container's corner and its children's clipped corner are the same
   primitive's arithmetic, and a texture mask (an alpha image as the
   clip) works with no new shader path.
   What this needs from the data layout: evaluating a primitive at an
   arbitrary pixel means its placement (its spans and `move_idx`, today
   vertex attributes) has to be readable from a storage buffer in the
   fragment stage. If it is not already there, put it there once, for
   every primitive, rather than keeping a second copy for masks -- the
   vertex stage can read the same buffer. Textures: the shader binds one
   image at a time (see `masks_layout`'s comment on why an image's own
   bind group must not name the masks buffer), so a texture mask is
   limited to what the fragment can sample without a bind-group switch:
   the atlas, and the primitive's own bound image when the masked
   primitive is drawn in the same image's batch. Say so at the flag.
2. **Nested masks chain and multiply, like moves.** `parent` walks up
   the chain, bounded like `resolve_move` (`MOVE_CHAIN_LIMIT`'s sibling;
   debug-assert on overflow and print the chain); coverages multiply,
   so a pixel inside two feathered corners is dimmed by both, which is
   what a compositor does and what "alpha should be multiplied" asks.
3. **`.masked()` points the mask at the current widget's own
   primitives.** `Masked` stops describing a region: it records which
   primitive(s) the wrapping widget drew this frame (the painter knows
   -- it just allocated the slots) and sets the mask to reference them.
   So a rounded `Rect` widget's `.masked()` clips its children to
   itself by pointing at the rect it already draws; an image widget's
   `.masked()` clips to its alpha. No radius or shape argument exists to
   fall out of sync. When a widget draws more than one primitive (a
   bordered rect is one primitive; a card with a stripe is two), the
   mask references the *first* and the doc says so; a widget that wants
   another names it.
4. **Hit-testing applies the shape.** A press is inside a masked
   subtree only if the mask's coverage at that point is above one half.
   For a `Rect` that is the same rounded-rect SDF evaluated on the CPU
   -- one function in the shared crate, with the WGSL a transliteration
   of it and a test that compares the two at a grid of points
   (`headless` renders to a buffer and reads back, or the Rust version
   is checked against the values the shader produced once and recorded).
   For a texture, the CPU needs the alpha: keep the alpha channel of an
   image used as a mask readable on the CPU (it was uploaded from CPU
   memory; keeping the alpha plane is a quarter of the image), and read
   it at the point. A masked corner that cannot be tapped and a masked
   corner that is not drawn are then the same corner.

**Rejected.** A stencil buffer (a second pass per mask level and no
anti-aliasing); the scissor rectangle (rectangles only, no alpha);
rendering a masked subtree to an offscreen texture and compositing
(a texture allocation per mask, every frame it scrolls, on the phone).

**Pass conditions.** A headless test draws a rounded container with a
masked child that overhangs all four sides and asserts the child's
coverage at a corner pixel equals the container's own coverage there
(same primitive evaluated, so exactly equal, not approximately); a
nested-mask test asserts the product at a pixel inside both feathers; a
texture-mask test clips a rect to an alpha image and asserts a
transparent texel masks fully; a hit-test asserts a press in a
container's clipped corner misses and one just inside the curve hits,
and that the CPU SDF and the shader agree at a grid of points; a
`run-headless.sh --phone` screenshot of a scrolled code block shows
rounded corners with no square pixels poking out at the top and bottom
of the scrolled content. Record the commands in RUST.md when it lands.

### What was built (2026-09-08), and where it differs

The commands and the screenshot are in docs/RUST.md's queue entry. Four
places the code is narrower than the design above, each deliberate:

- **No `kind` and no `flags` on `Mask`.** It is `{ primitive, parent }`.
  The referenced instance already carries its own `binding`, so a copy
  of it in the mask is a second thing to keep in step; *alpha only* is
  the only mode there is, so there is nothing to select. Both are a
  field away if a second mode appears.
- **A mask's shape must be a rect.** `Painter::set_mask_to` asserts it,
  by name, rather than leaving the shader to read a `rects` entry that
  is not there. A glyph would need a CPU-side alpha plane before the
  hit test could agree with the shader, and a standalone image needs a
  bind-group switch the fragment stage cannot make (`masks_layout`'s own
  comment on why an image's bind group must not name the masks buffer).
  So **the texture-mask pass condition is not met and no texture mask
  exists** — the point of the reference design is that adding one is a
  binding check and a sampled alpha, with no new shader path, and the
  shader's `mask_coverage` already has the branch where it would go.
- **The shape is a primitive of its own, not always a drawn one.** A
  plain `.masked()` writes an undrawn `RectPrimitive` at its region
  (`Drawn::No`, `NOT_DRAWN`) and points the mask at that, so "clip to my
  box" and "clip to that widget's rounded background" are one mechanism
  and square-cornered clipping did not become a special case.
  `.masked_by(shape)` draws `shape` behind the content — in its own
  layer, the way `Stack` puts a background under its content — and
  clips to the first primitive it drew.
- **The CPU/shader agreement is a GPU test**, `iris/tests/mask_sdf.rs`,
  the only test in the workspace that needs an adapter. It lifts
  `distance_from_rect` and `rounded_rect_coverage` out of
  `iris_core::SHAPE_SHADER` *by name* and runs them in a compute pass,
  so the thing under test is the shader itself rather than a copy of it
  that would be edited alongside.

## What a widget's *offered* box may and may not be (2026-09-08)

Two rules that were each true in one place and missing from a sibling,
found together by Iris's 2026-09-08 phone report.

**Padding works in whatever container it is placed in, and is an inset or
an outset depending on how tight that container's region is.** Iris's
own words, 2026-09-08: "padding should work no matter what container a
widget is placed in, and acts as both inset and outset depending on how
tight the parent region is." `Pad` offers its child the region it was
handed, inset on each side, and reports `used + padding` — so given a
generous box it insets the child inside it, and given a box already the
size of the content it reports a larger size and the parent grows. What
this rules out is any container that offers a padded child a box and then
ignores what it reported, and any caller that reshapes its tree to avoid
a `Pad` (which `transcript-ui/src/tool.rs` did until 2026-09-08, at the
cost of a tool group's 4dp inset).

**A widget offered a box it does not fit is drawn again at the box its
own reported size implies, in the same frame.** Not next frame. The
temptation to defer is real — `LazySpan::place` offers a row its *cached*
height precisely so that an unchanged row hits `draw_inner`'s cheap
skip-or-move path, and `Scroll` sizes its child region from last frame's
content length for the same reason. But a `Rect` fills whatever region it
is given (`Size::REST`, and `rect.rs`'s `is_size_independent` doc says
why it must), and `.background(rect(..))` is the ordinary way to style
anything — so a one-frame-stale box is a background drawn at the wrong
size while the text inside it is already right. On screen that is a tool
card that looks closed while its text is there and open while it is not.
A `reposition` is not the fix and cannot be: it writes an offset, never a
size.

The cost is bounded and worth stating, because it is what makes the rule
safe to apply everywhere: the second draw happens only on the frame a
widget's own size actually changes, which is a frame that was already
redrawing it. A widget whose reported size is a function of the box it
was *offered* would disagree every frame and redraw every frame — which
is why `LazySpan` requires content-sized rows, and has since long before
this.