nomen-lang 0.0.7 → 0.0.8

package/core/System/Controls/Container.nm

@@ -0,0 +1,1562 @@
+// A handle-based layout container. Users create a Grid/VStack/HStack, add child
+// controls by their native handle, and call `grid.layout(win)` — the container
+// measures, arranges, and applies frames (flipping the y axis against the
+// window's content height) so callers never compute coordinates themselves.
+//
+// All node data lives in flat Buffer<int> arrays (structure-of-arrays). Because
+// this is trusted core library code, the runtime-indexed Buffer accesses here do
+// not trip the "constraint cannot be verified" rule that bites user code.
+//
+// Children are leaves (native controls). A leaf stores its native handle and a
+// per-axis requested size as a (kind, value) pair mirroring the `LayoutLength`
+// enum in Geometry.nm (`.auto`/`.fixed(n)`/`.percent(p)`/`.fill`). The legacy
+// `add`/`add_to` helpers take plain int `w`/`h` (0 → `.auto`, non-zero →
+// `.fixed`); `add_len`/`add_to_len` take `LayoutLength` directly, so a child
+// can ask for, say, `.percent(50)` of the cross axis or `.fill`. On a bounded
+// (cross) axis, `.auto`/`.fill` fill the available space; on an unbounded
+// (main) axis they're 0 so a `grow` weight then decides how much surplus the
+// child absorbs. `shrink` is the mirror weight: when the children's total
+// exceeds the main-axis content size, the deficit is shared between shrinkable
+// children weighted by `shrink` (default 0 = never shrink, the original
+// behavior). Grid children additionally carry a column `span`. Children flow
+// left-to-right, top-to-bottom; a child whose span won't fit in the remaining
+// columns wraps to the next row. A hidden native control (isHidden) is skipped
+// automatically, so toggling visibility and re-laying-out just works.
+
+const KIND_LEAF = 0
+const KIND_VSTACK = 1
+const KIND_HSTACK = 2
+const KIND_GRID = 3
+const KIND_ZSTACK = 4
+const KIND_BLOCK = 5
+
+// Cross-axis alignment for a child within its parent stack. The indices match
+// the `Alignment` enum case order in Geometry.nm (start, center, end, stretch).
+// The default is stretch, which preserves the original "fill the cross axis"
+// behavior every child had before grow/align landed.
+pub const ALIGN_START = 0
+pub const ALIGN_CENTER = 1
+pub const ALIGN_END = 2
+pub const ALIGN_STRETCH = 3
+
+// Per-axis requested size for a leaf. The first four cases match the
+// `LayoutLength` enum case order in Geometry.nm (auto, fixed, percent, fill);
+// `LEN_INTRINSIC` is a v1-only extension (see below). The legacy `add`/`add_to`
+// helpers translate their int `w`/`h` arguments into a (kind, value) pair:
+// `0` → `.auto` (fills a bounded axis, stays 0 on an unbounded axis so `grow`
+// decides), non-zero → `.fixed(w)`. `add_kind`/`add_to_kind` accept any case
+// directly, including `.percent(p)` (p% of the available axis), `.fill`, and
+// `.intrinsic`.
+//
+// `LEN_INTRINSIC` (v1-only; the trait-based `.auto` will fold intrinsic
+// measurement into `auto`) asks the leaf's native control for its
+// `intrinsicContentSize` on that axis, so a control can be added with no size
+// hints and size to its content. The v1 keeps `LEN_AUTO` = fill (its
+// long-standing default) rather than repurposing it, so existing `add(handle,
+// 0, h, span)` callers and the live app are unchanged; opt into intrinsic via
+// `add_intrinsic` / `add_to_intrinsic`, or per-axis via
+// `add_kind(handle, LEN_FILL, 0, LEN_INTRINSIC, 0, span)` (fill the cross axis,
+// intrinsic height). A handle of 0 (no native view) measures to 0, so the
+// pure-math geometry tests exercise this path without native calls.
+pub const LEN_AUTO = 0
+pub const LEN_FIXED = 1
+pub const LEN_PERCENT = 2
+pub const LEN_FILL = 3
+pub const LEN_INTRINSIC = 4
+
+const INF = 100000000
+
+// Translate a `LayoutLength` enum case into the internal (kind, value) int
+// pair stored in the SoA buffers. `.auto` maps to LEN_AUTO (v1 semantics:
+// fill the bounded axis — see the LEN_INTRINSIC note above), so `add_len`
+// composes with the existing measure math unchanged.
+func length_kind = (LayoutLength len, out int) {
+	var int k = match len {
+		case .auto -> LEN_AUTO
+		case .fixed(px) -> LEN_FIXED
+		case .percent(num) -> LEN_PERCENT
+		case .fill -> LEN_FILL
+	}
+	return k
+}
+
+func length_val = (LayoutLength len, out int) {
+	var int v = match len {
+		case .auto -> 0
+		case .fixed(px) -> px
+		case .percent(num) -> num
+		case .fill -> 0
+	}
+	return v
+}
+
+// Defined before the struct so their return types are resolved when the engine
+// methods below reference them (free functions aren't forward-inferred).
+
+func is_visible = (uint64 handle, out bool) {
+	if handle == 0 { return true }
+	```
+	#arch: c, aarch64_use_c
+	#platform: macos
+	BOOL hidden = ((BOOL(*)(id, SEL))objc_msgSend)((id)handle, sel_registerName("isHidden"));
+	return !hidden;
+	```
+	```
+	#arch: c, aarch64_use_c
+	#platform: ios
+	return true;
+	```
+}
+
+func apply_frame = (uint64 handle, int x, int y, int w, int h, int content_w, int content_h) {
+	```
+	#arch: c, aarch64_use_c
+	#platform: macos
+	// AppKit runs its own blocking tracking loop during a live window resize,
+	// so the manual event loop can't re-layout mid-drag. Give the control an
+	// autoresizing mask so AppKit repositions it live: pin to the nearest
+	// vertical edge (top=NSViewMinYMargin 8 / bottom=NSViewMaxYMargin 32) to
+	// respect the top-left-origin layout instead of AppKit's default
+	// bottom-left pin, and let wide controls grow with the content width
+	// (NSViewWidthSizable 2). Never set NSViewHeightSizable (16): control
+	// heights come from the layout pass, not the window. AppKit's result
+	// matches what layout() computes, so the post-drag relayout only fixes up
+	// cells AppKit can't (column reflow for sub-full-width children).
+	unsigned long mask = (y * 2 < content_h) ? 8UL : 32UL;
+	if (w * 10 >= content_w * 8) mask |= 2UL;
+	((void(*)(id, SEL, unsigned long))objc_msgSend)((id)handle, sel_registerName("setAutoresizingMask:"), mask);
+	((void(*)(id, SEL, CGRect))objc_msgSend)(
+		(id)handle, sel_registerName("setFrame:"),
+		((CGRect(*)(double, double, double, double))CGRectMake)(
+			(double)x, (double)(content_h - y - h), (double)w, (double)h));
+	```
+	```
+	#arch: c, aarch64_use_c
+	#platform: ios
+	((void(*)(id, SEL, CGRect))objc_msgSend)(
+		(id)handle, sel_registerName("setFrame:"),
+		((CGRect(*)(double, double, double, double))CGRectMake)(
+			(double)x, (double)y, (double)w, (double)h));
+	```
+}
+
+// Query a native control's intrinsic content size, returning the full
+// `[width, height]` in a single call. Used by the `LEN_INTRINSIC` leaf sizing
+// kind so a control can be added with no size hints and size to its content
+// (e.g. a `Text` measures to its rendered glyph size, a `Button` to its title
+// + chrome). Returns `[0, 0]` for handle 0 (no native view, so the pure-math
+// geometry tests exercise the wiring without native calls) and for views that
+// report no intrinsic size (AppKit returns `NSNotFound` for a generic `NSView`).
+// Also the shared backing query for the native leaf controls' `Control`
+// conformance (`Button`/`CheckBox`/`TextBox`), so each leaf's `intrinsic_size`
+// doesn't need its own raw-block FFI.
+pub func native_intrinsic = (uint64 handle, out [int, int]) {
+	if handle == 0 { return [0, 0] }
+	```
+	#arch: c, aarch64_use_c
+	#platform: macos
+	CGSize sz = ((CGSize(*)(id, SEL))objc_msgSend)((id)handle, sel_registerName("intrinsicContentSize"));
+	int w = (sz.width < 0 || sz.width > 100000) ? 0 : (int)sz.width;
+	int h = (sz.height < 0 || sz.height > 100000) ? 0 : (int)sz.height;
+	struct _Tuple_int_int r;
+	r._0 = w;
+	r._1 = h;
+	return r;
+	```
+	```
+	#arch: c, aarch64_use_c
+	#platform: ios
+	CGSize sz = ((CGSize(*)(id, SEL))objc_msgSend)((id)handle, sel_registerName("intrinsicContentSize"));
+	int w = (sz.width < 0 || sz.width > 100000) ? 0 : (int)sz.width;
+	int h = (sz.height < 0 || sz.height > 100000) ? 0 : (int)sz.height;
+	struct _Tuple_int_int r;
+	r._0 = w;
+	r._1 = h;
+	return r;
+	```
+}
+
+/**
+ * A flexbox-style container that measures and arranges its child controls.
+ *
+ * Conforms to `Control`: `measure(BoxConstraints)` measures the whole subtree,
+ * `set_frame` arranges it into a rectangle, and `intrinsic_size` reports the
+ * unbounded-content size. The handle-based `add` API and the SoA engine are
+ * unchanged — the trait methods are thin entry points over the existing math,
+ * so a `Container` can also be driven polymorphically as a `Control` (passed to
+ * a `Control`-taking function, stored in a `ClassBuffer<Control>`, etc.).
+ **/
+pub class Container : Control {
+	var kinds = Buffer<int>()
+	// Per-leaf requested size, stored as a (kind, value) pair per axis. The
+	// kind is one of LEN_* (auto/fixed/percent/fill); the value is the pixel
+	// count for `fixed` or the percent numerator for `percent` (0 otherwise).
+	// The legacy int-based `add`/`add_to` translate `w`/`h` into these pairs
+	// (non-zero → fixed, 0 → auto); `add_len`/`add_to_len` store any case.
+	var w_kinds = Buffer<int>()
+	var w_vals = Buffer<int>()
+	var h_kinds = Buffer<int>()
+	var h_vals = Buffer<int>()
+	var gaps = Buffer<int>() // container spacing
+	var pars = Buffer<int>() // parent index, encoded as parent + 1 (0 = root)
+	var spans = Buffer<int>() // grid column span
+	var cols = Buffer<int>() // grid column count (on grid nodes)
+	var handles = Buffer<int>() // leaf native handle (0 = none/container)
+	var pads = Buffer<int>() // per-node inset (padding) for Block
+	var grows = Buffer<int>() // flex weight: absorbs surplus on the main axis
+	var shrinks = Buffer<int>() // flex weight: absorbs deficit on the main axis
+	var aligns = Buffer<int>() // cross-axis alignment (ALIGN_*)
+	// Per-node dirty flag for incremental relayout: a dirty node (and its
+	// descendants) is re-measured on the next `compute`/`layout`; a clean node
+	// returns its cached size. `mark_dirty` sets a node, walks up to the root
+	// (ancestors must re-flow) and down through descendants (their constraints
+	// may change), so a clean node always has unchanged constraints.
+	var dirty = Buffer<int>()
+	// How many times a node's `measure` body actually ran — purely for tests
+	// that want to observe which subtrees were re-measured.
+	var measured_count = Buffer<int>()
+	var rx = Buffer<int>()
+	var ry = Buffer<int>()
+	var rw = Buffer<int>()
+	var rh = Buffer<int>()
+	// Previously-applied frame per node (leaf only), used by the dirty-rect
+	// tracker: a leaf enters the dirty list only when its resolved frame
+	// differs from this baseline. Initialised to -1 so the first layout marks
+	// every leaf dirty.
+	var prx = Buffer<int>()
+	var pry = Buffer<int>()
+	var prw = Buffer<int>()
+	var prh = Buffer<int>()
+	// Dirty-rect list: the node indices (leaves) whose frame changed in the
+	// most recent `compute`/`layout`, in the order discovered. `dirty_count`
+	// / `dirty_rect` expose it; `apply` repaints only these.
+	var dirty_idx = Buffer<int>()
+	var dirty_n = 0
+	var root = 0
+	var count = 0
+	var padding = 0
+	// Last available size passed to `compute`/`layout`. When it changes the
+	// whole tree is marked dirty (the external constraint changed); when it's
+	// the same, only explicitly `mark_dirty`'d subtrees are re-measured.
+	var int last_w = -1
+	var int last_h = -1
+
+	func init_buffers = (ref self, int cap) {
+		self.kinds.grow_int(cap)
+		self.w_kinds.grow_int(cap)
+		self.w_vals.grow_int(cap)
+		self.h_kinds.grow_int(cap)
+		self.h_vals.grow_int(cap)
+		self.gaps.grow_int(cap)
+		self.pars.grow_int(cap)
+		self.spans.grow_int(cap)
+		self.cols.grow_int(cap)
+		self.handles.grow_int(cap)
+		self.pads.grow_int(cap)
+		self.grows.grow_int(cap)
+		self.shrinks.grow_int(cap)
+		self.aligns.grow_int(cap)
+		self.dirty.grow_int(cap)
+		self.measured_count.grow_int(cap)
+		self.rx.grow_int(cap)
+		self.ry.grow_int(cap)
+		self.rw.grow_int(cap)
+		self.rh.grow_int(cap)
+		self.prx.grow_int(cap)
+		self.pry.grow_int(cap)
+		self.prw.grow_int(cap)
+		self.prh.grow_int(cap)
+		self.dirty_idx.grow_int(cap)
+	}
+
+	func make_root = (ref self, int kind, int gap, int col_count) {
+		self.init_buffers(32)
+		self.kinds.store_int(0, kind)
+		self.w_kinds.store_int(0, LEN_AUTO)
+		self.w_vals.store_int(0, 0)
+		self.h_kinds.store_int(0, LEN_AUTO)
+		self.h_vals.store_int(0, 0)
+		self.gaps.store_int(0, gap)
+		self.cols.store_int(0, col_count)
+		self.spans.store_int(0, 1)
+		self.pars.store_int(0, 0)
+		self.handles.store_int(0, 0)
+		self.pads.store_int(0, 0)
+		self.grows.store_int(0, 0)
+		self.shrinks.store_int(0, 0)
+		self.aligns.store_int(0, ALIGN_STRETCH)
+		self.dirty.store_int(0, 1)
+		self.prx.store_int(0, -1)
+		self.pry.store_int(0, -1)
+		self.prw.store_int(0, -1)
+		self.prh.store_int(0, -1)
+		self.root = 0
+		self.count = 1
+	}
+
+	func first_child = (self, int parent, out int) {
+		var int p = parent + 1
+		var i = 0
+		while i < self.count; i += 1 {
+			if self.pars.load_int(i) == p { return i }
+		}
+		return -1
+	}
+
+	func next_sibling = (self, int after, int parent, out int) {
+		var int p = parent + 1
+		var int i = after + 1
+		while i < self.count; i += 1 {
+			if self.pars.load_int(i) == p { return i }
+		}
+		return -1
+	}
+
+	// Core append: store a node (leaf or container) as a child of `parent`
+	// (a node index; use root_index() for the top level), returning the new
+	// node's index. All the public add* helpers route through here.
+	//
+	// `w_kind`/`w_val`/`h_kind`/`h_val` are the per-axis requested size as a
+	// (LEN_*, value) pair; only leaves use them (containers size to content),
+	// so the leaf helpers set them after this returns. `grow` is the flex
+	// weight (surplus on the main axis is shared weighted by it); `shrink` is
+	// the deficit weight; `align` is the cross-axis alignment (ALIGN_*).
+	// (The aarch64 backend now spills args past the 8-register ABI limit, so
+	// this signature no longer has to stay within 8 register params.)
+	func append_node = (
+		ref self,
+		int parent,
+		int kind,
+		int handle,
+		int gap,
+		int cols,
+		int span,
+		int grow,
+		int shrink,
+		int align,
+		out int
+	) {
+		if self.kinds.cap < self.count + 1 {
+			self.init_buffers(self.count + 1)
+		}
+		var int idx = self.count
+		self.kinds.store_int(idx, kind)
+		self.w_kinds.store_int(idx, LEN_AUTO)
+		self.w_vals.store_int(idx, 0)
+		self.h_kinds.store_int(idx, LEN_AUTO)
+		self.h_vals.store_int(idx, 0)
+		self.gaps.store_int(idx, gap)
+		self.spans.store_int(idx, span)
+		self.cols.store_int(idx, cols)
+		self.handles.store_int(idx, handle)
+		self.grows.store_int(idx, grow)
+		self.shrinks.store_int(idx, shrink)
+		self.aligns.store_int(idx, align)
+		self.pars.store_int(idx, parent + 1)
+		self.pads.store_int(idx, 0)
+		self.dirty.store_int(idx, 1)
+		self.measured_count.store_int(idx, 0)
+		// A new child changes the parent's subtree, so mark the parent chain
+		// (and the new node itself) dirty so the next measure re-flows them.
+		var int p = parent
+		while p != -1 {
+			self.dirty.store_int(p, 1)
+			p = self.pars.load_int(p) - 1
+		}
+		self.prx.store_int(idx, -1)
+		self.pry.store_int(idx, -1)
+		self.prw.store_int(idx, -1)
+		self.prh.store_int(idx, -1)
+		self.count = self.count + 1
+		return idx
+	}
+
+	// Index of the root node — pass this as `parent` to add children to the
+	// top level (the plain `add` helper already does this for leaves).
+	pub func root_index = (self, out int) {
+		return self.root
+	}
+
+	// Add a leaf child (a native control by handle) under the root. `w`/`h` of
+	// 0 mean "fill" on the cross axis (or "no intrinsic opinion" on the main
+	// axis, where `grow` then absorbs the surplus); a non-zero `w`/`h` is an
+	// exact pixel size. `span` is the grid column span (use 1 for
+	// VStack/HStack). `grow` is the flex weight for sharing surplus space on
+	// the parent's main axis (0 = hold at intrinsic size); `align` is the
+	// cross-axis alignment (default ALIGN_STRETCH = 3, the original "fill the
+	// cross axis" behavior); `shrink` is the flex weight for sharing a deficit
+	// when the children's total exceeds the main-axis content size (0 = never
+	// shrink, the original behavior). For `.percent` / `.fill` / mixed sizing,
+	// use `add_len`.
+	pub func add = (
+		ref self,
+		uint64 handle,
+		int w,
+		int h,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			self.root,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_size(idx, w, h)
+	}
+
+	// Add a leaf child under an explicit `parent` (a node index returned by an
+	// add_vstack/add_hstack/add_grid/add_zstack call).
+	pub func add_to = (
+		ref self,
+		int parent,
+		uint64 handle,
+		int w,
+		int h,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			parent,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_size(idx, w, h)
+	}
+
+	// Add a leaf child under the root with an explicit per-axis size kind.
+	// `w_kind`/`h_kind` are `LEN_*` constants (LEN_AUTO/LEN_FIXED/LEN_PERCENT/
+	// LEN_FILL); `w_val`/`h_val` are the pixel count for LEN_FIXED or the
+	// percent numerator (0-100) for LEN_PERCENT — ignored for LEN_AUTO/
+	// LEN_FILL. This is the explicit-size escape hatch when neither `add`
+	// (which only expresses fixed/auto) nor a future LayoutLength-taking
+	// helper fits; e.g. `add_kind(0, LEN_PERCENT, 50, LEN_FIXED, 30, 1)`
+	// asks for 50% of the cross axis and a fixed 30px on the main axis.
+	// `span`/`grow`/`align`/`shrink` match `add`.
+	pub func add_kind = (
+		ref self,
+		uint64 handle,
+		int w_kind,
+		int w_val,
+		int h_kind,
+		int h_val,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			self.root,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, w_kind, w_val, h_kind, h_val)
+	}
+
+	// Add a leaf child with explicit per-axis size kinds under an explicit
+	// `parent` (a node index returned by an add_* container helper).
+	pub func add_to_kind = (
+		ref self,
+		int parent,
+		uint64 handle,
+		int w_kind,
+		int w_val,
+		int h_kind,
+		int h_val,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			parent,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, w_kind, w_val, h_kind, h_val)
+	}
+
+	// Add a leaf child under the root, passing `LayoutLength` values directly:
+	// `v.add_len(handle, LayoutLength.percent(50), LayoutLength.fixed(30), 1)`.
+	// The ergonomic form of `add_kind` — each axis's enum case is translated
+	// to the internal (kind, value) pair. `span`/`grow`/`align`/`shrink`
+	// match `add`.
+	pub func add_len = (
+		ref self,
+		uint64 handle,
+		LayoutLength w,
+		LayoutLength h,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			self.root,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, length_kind(w), length_val(w), length_kind(h), length_val(h))
+	}
+
+	// Add a leaf child with `LayoutLength` sizes under an explicit `parent`
+	// (a node index returned by an add_* container helper).
+	pub func add_to_len = (
+		ref self,
+		int parent,
+		uint64 handle,
+		LayoutLength w,
+		LayoutLength h,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			parent,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, length_kind(w), length_val(w), length_kind(h), length_val(h))
+	}
+
+	// Add a leaf that sizes to its native control's `intrinsicContentSize` on
+	// both axes — the "no size hints" form. Equivalent to
+	// `add_kind(handle, LEN_INTRINSIC, 0, LEN_INTRINSIC, 0, span, …)`. For
+	// per-axis intrinsic (e.g. fill the cross axis, intrinsic height) use
+	// `add_kind` directly. `span`/`grow`/`align`/`shrink` match `add`.
+	pub func add_intrinsic = (
+		ref self,
+		uint64 handle,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			self.root,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, LEN_INTRINSIC, 0, LEN_INTRINSIC, 0)
+	}
+
+	// `add_intrinsic` under an explicit `parent` (a node index returned by an
+	// add_* container helper).
+	pub func add_to_intrinsic = (
+		ref self,
+		int parent,
+		uint64 handle,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0
+	) {
+		var int idx = self.append_node(
+			parent,
+			KIND_LEAF,
+			handle as int,
+			0,
+			0,
+			span,
+			grow,
+			shrink,
+			align,
+		)
+		self.set_leaf_kind(idx, LEN_INTRINSIC, 0, LEN_INTRINSIC, 0)
+	}
+
+	// Translate the legacy int (w, h) into a (kind, value) pair: 0 → auto
+	// (no intrinsic; fills a bounded axis, stays 0 on an unbounded axis so
+	// `grow` decides), non-zero → fixed.
+	func set_leaf_size = (ref self, int idx, int w, int h) {
+		if w == 0 {
+			self.w_kinds.store_int(idx, LEN_AUTO)
+			self.w_vals.store_int(idx, 0)
+		} else {
+			self.w_kinds.store_int(idx, LEN_FIXED)
+			self.w_vals.store_int(idx, w)
+		}
+		if h == 0 {
+			self.h_kinds.store_int(idx, LEN_AUTO)
+			self.h_vals.store_int(idx, 0)
+		} else {
+			self.h_kinds.store_int(idx, LEN_FIXED)
+			self.h_vals.store_int(idx, h)
+		}
+	}
+
+	// Store the per-axis (kind, value) pair directly.
+	func set_leaf_kind = (ref self, int idx, int w_kind, int w_val, int h_kind, int h_val) {
+		self.w_kinds.store_int(idx, w_kind)
+		self.w_vals.store_int(idx, w_val)
+		self.h_kinds.store_int(idx, h_kind)
+		self.h_vals.store_int(idx, h_val)
+	}
+
+	// Add a nested container under `parent`; returns the new node's index so
+	// children can be added to it via add_to (or another nested container).
+	pub func add_vstack = (
+		ref self,
+		int parent,
+		int spacing,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		return self.append_node(parent, KIND_VSTACK, 0, spacing, 0, span, grow, shrink, align)
+	}
+
+	pub func add_hstack = (
+		ref self,
+		int parent,
+		int spacing,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		return self.append_node(parent, KIND_HSTACK, 0, spacing, 0, span, grow, shrink, align)
+	}
+
+	// Add a spacer: a flexible empty leaf (no native handle) that simply
+	// occupies layout space. With `grow > 0` it absorbs the surplus on the
+	// parent's main axis — the classic "push the rest of the row/column to the
+	// far edge" glue; with `shrink > 0` it yields space in a deficit. It sizes
+	// to 0 on an unbounded axis (so it has no intrinsic opinion) and fills the
+	// cross axis by default. Because it carries no handle, `apply` never calls
+	// `setFrame:` for it and `hit_test` reports it as "no control" (handle 0).
+	pub func add_spacer = (ref self, int span, int grow = 0, int shrink = 0, int align = 3) {
+		self.append_node(self.root, KIND_LEAF, 0, 0, 0, span, grow, shrink, align)
+	}
+
+	pub func add_spacer_to = (
+		ref self,
+		int parent,
+		int span,
+		int grow = 0,
+		int shrink = 0,
+		int align = 3
+	) {
+		self.append_node(parent, KIND_LEAF, 0, 0, 0, span, grow, shrink, align)
+	}
+
+	pub func add_grid = (
+		ref self,
+		int parent,
+		int cols: cols > 0,
+		int spacing,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		return self.append_node(parent, KIND_GRID, 0, spacing, cols, span, grow, shrink, align)
+	}
+
+	pub func add_zstack = (
+		ref self,
+		int parent,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		return self.append_node(parent, KIND_ZSTACK, 0, 0, 0, span, grow, shrink, align)
+	}
+
+	// Add a Block: a single-child container with insets (padding) on all four
+	// sides. It forwards its content rect (frame minus 2·padding) to its one
+	// child via `add_to(block, …)`. `measure` subtracts the insets from the
+	// constraints and returns the child size plus the insets; `arrange` places
+	// the child inside the inset content rect. Like the other containers this
+	// is a node in the SoA tree, so it needs no trait model — it recurses
+	// through `first_child`/`next_sibling` like everything else.
+	pub func add_block = (
+		ref self,
+		int padding,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		var int idx = self.append_node(self.root, KIND_BLOCK, 0, 0, 0, span, grow, shrink, align)
+		self.pads.store_int(idx, padding)
+		return idx
+	}
+
+	pub func add_block_to = (
+		ref self,
+		int parent,
+		int padding,
+		int span,
+		int grow = 0,
+		int align = 3,
+		int shrink = 0,
+		out int
+	) {
+		var int idx = self.append_node(parent, KIND_BLOCK, 0, 0, 0, span, grow, shrink, align)
+		self.pads.store_int(idx, padding)
+		return idx
+	}
+
+	// Measure a node against box constraints. Returns the resolved width and
+	// stores the resolved height in rh[idx] (and the width in rw[idx]).
+	func measure_node = (self, int idx, int min_w, int max_w, int min_h, int max_h, out int) {
+		var int kind = self.kinds.load_int(idx)
+		// Incremental relayout: a clean node's constraints are unchanged, so
+		// reuse its cached size instead of re-measuring the subtree. The cached
+		// height is already in rh[idx] from the previous pass, so the caller's
+		// `self.rh.load_int(ci)` picks it up without a re-measure.
+		if self.dirty.load_int(idx) == 0 {
+			var int cached = self.rw.load_int(idx)
+			return cached
+		}
+		self.measured_count.store_int(idx, self.measured_count.load_int(idx) + 1)
+
+		if kind == KIND_LEAF {
+			// Resolve the per-axis `LayoutLength` (kind, value) against the
+			// constraints: `.fixed` is exact, `.percent` is p% of the bounded
+			// max (0 on an unbounded axis), `.fill`/`.auto` fill a bounded axis
+			// and stay 0 on an unbounded one (so `grow` then absorbs surplus
+			// rather than a phantom INF), `.intrinsic` asks the native control
+			// for its `intrinsicContentSize` on that axis (0 for handle 0). All
+			// results are then clamped to the min/max range. (Nomen has no
+			// `else if` — the cases are `switch`es.)
+			var int wk = self.w_kinds.load_int(idx)
+			var int wv = self.w_vals.load_int(idx)
+			var int hk = self.h_kinds.load_int(idx)
+			var int hv = self.h_vals.load_int(idx)
+			var uint64 ih = self.handles.load_int(idx) as uint64
+
+			// A single intrinsic query returns both axes, so a `LEN_INTRINSIC`
+			// leaf makes at most one native call per dirty measure pass.
+			var intr_w = 0
+			var intr_h = 0
+			if wk == LEN_INTRINSIC || hk == LEN_INTRINSIC {
+				var [iw, ih2] = native_intrinsic(ih)
+				intr_w = iw
+				intr_h = ih2
+			}
+
+			var w = 0
+			switch {
+				case wk == LEN_FIXED -> w = wv
+				case wk == LEN_PERCENT -> if max_w < INF { w = max_w * wv / 100 }
+				case wk == LEN_FILL -> if max_w < INF { w = max_w }
+				case wk == LEN_AUTO -> if max_w < INF { w = max_w }
+				case wk == LEN_INTRINSIC -> w = intr_w
+			}
+
+			var h = 0
+			switch {
+				case hk == LEN_FIXED -> h = hv
+				case hk == LEN_PERCENT -> if max_h < INF { h = max_h * hv / 100 }
+				case hk == LEN_FILL -> if max_h < INF { h = max_h }
+				case hk == LEN_AUTO -> if max_h < INF { h = max_h }
+				case hk == LEN_INTRINSIC -> h = intr_h
+			}
+
+			if w > max_w { w = max_w }
+			if w < min_w { w = min_w }
+			if h > max_h { h = max_h }
+			if h < min_h { h = min_h }
+			self.rw.store_int(idx, w)
+			self.rh.store_int(idx, h)
+			self.dirty.store_int(idx, 0)
+			return w
+		}
+
+		if kind == KIND_VSTACK {
+			var total_h = 0
+			var max_child_w = 0
+			var n = 0
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					var int cw = self.measure_node(ci, min_w, max_w, 0, INF)
+					var int ch = self.rh.load_int(ci)
+					total_h = total_h + ch
+					if cw > max_child_w { max_child_w = cw }
+					n += 1
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			if n > 1 { total_h = total_h + self.gaps.load_int(idx) * (n - 1) }
+			if total_h < min_h { total_h = min_h }
+			if total_h > max_h { total_h = max_h }
+			if max_child_w < min_w { max_child_w = min_w }
+			if max_child_w > max_w { max_child_w = max_w }
+			self.rw.store_int(idx, max_child_w)
+			self.rh.store_int(idx, total_h)
+			self.dirty.store_int(idx, 0)
+			return max_child_w
+		}
+
+		if kind == KIND_HSTACK {
+			var total_w = 0
+			var max_child_h = 0
+			var n = 0
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					var int cw = self.measure_node(ci, 0, INF, min_h, max_h)
+					var int ch = self.rh.load_int(ci)
+					total_w = total_w + cw
+					if ch > max_child_h { max_child_h = ch }
+					n += 1
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			if n > 1 { total_w = total_w + self.gaps.load_int(idx) * (n - 1) }
+			if total_w < min_w { total_w = min_w }
+			if total_w > max_w { total_w = max_w }
+			if max_child_h < min_h { max_child_h = min_h }
+			if max_child_h > max_h { max_child_h = max_h }
+			self.rw.store_int(idx, total_w)
+			self.rh.store_int(idx, max_child_h)
+			self.dirty.store_int(idx, 0)
+			return total_w
+		}
+
+		if kind == KIND_ZSTACK {
+			var best_w = 0
+			var best_h = 0
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					self.measure_node(ci, min_w, max_w, min_h, max_h)
+					var int cw = self.rw.load_int(ci)
+					var int ch = self.rh.load_int(ci)
+					if cw > best_w { best_w = cw }
+					if ch > best_h { best_h = ch }
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			if best_w < min_w { best_w = min_w }
+			if best_w > max_w { best_w = max_w }
+			if best_h < min_h { best_h = min_h }
+			if best_h > max_h { best_h = max_h }
+			self.rw.store_int(idx, best_w)
+			self.rh.store_int(idx, best_h)
+			self.dirty.store_int(idx, 0)
+			return best_w
+		}
+
+		// KIND_BLOCK: a single-child rect with insets. Subtract the padding from
+		// the constraints, measure the (first) child into the inner box, and
+		// return the child size plus the insets on both axes. A Block with no
+		// child resolves to just its padding (2·pad on each axis).
+		if kind == KIND_BLOCK {
+			var int pad = self.pads.load_int(idx)
+			var int inner_min_w = min_w - pad * 2
+			if inner_min_w < 0 { inner_min_w = 0 }
+			var int inner_max_w = max_w - pad * 2
+			if inner_max_w < 0 { inner_max_w = 0 }
+			var int inner_min_h = min_h - pad * 2
+			if inner_min_h < 0 { inner_min_h = 0 }
+			var int inner_max_h = max_h - pad * 2
+			if inner_max_h < 0 { inner_max_h = 0 }
+			var cw = 0
+			var ch = 0
+			var int ci = self.first_child(idx)
+			if ci != -1 {
+				cw = self.measure_node(ci, inner_min_w, inner_max_w, inner_min_h, inner_max_h)
+				ch = self.rh.load_int(ci)
+			}
+			var int total_w = cw + pad * 2
+			var int total_h = ch + pad * 2
+			if total_w < min_w { total_w = min_w }
+			if total_w > max_w { total_w = max_w }
+			if total_h < min_h { total_h = min_h }
+			if total_h > max_h { total_h = max_h }
+			self.rw.store_int(idx, total_w)
+			self.rh.store_int(idx, total_h)
+			self.dirty.store_int(idx, 0)
+			return total_w
+		}
+
+		// KIND_GRID: children flow into cells; each may span columns.
+		var int cols = self.cols.load_int(idx)
+		var int col_w = max_w / cols
+		var total_h = 0
+		var row_h = 0
+		var col_cursor = 0
+		var any = 0
+		var int ci = self.first_child(idx)
+		while ci != -1 {
+			if is_visible(self.handles.load_int(ci) as uint64) {
+				var int span = self.spans.load_int(ci)
+				if span < 1 { span = 1 }
+				if span > cols { span = cols }
+				if col_cursor + span > cols {
+					total_h = total_h + row_h
+					if any > 0 { total_h = total_h + self.gaps.load_int(idx) }
+					row_h = 0
+					col_cursor = 0
+				}
+				var int cell_w = span * col_w
+				self.measure_node(ci, cell_w, cell_w, 0, INF)
+				var int ch = self.rh.load_int(ci)
+				if ch > row_h { row_h = ch }
+				col_cursor = col_cursor + span
+				any += 1
+			}
+			ci = self.next_sibling(ci, idx)
+		}
+		if any > 0 {
+			total_h = total_h + row_h
+		}
+		if total_h < min_h { total_h = min_h }
+		if total_h > max_h { total_h = max_h }
+		self.rw.store_int(idx, cols * col_w)
+		self.rh.store_int(idx, total_h)
+		self.dirty.store_int(idx, 0)
+		return cols * col_w
+	}
+
+	func arrange_node = (self, int idx, int x, int y, int w, int h) {
+		self.rx.store_int(idx, x)
+		self.ry.store_int(idx, y)
+		self.rw.store_int(idx, w)
+		self.rh.store_int(idx, h)
+
+		var int kind = self.kinds.load_int(idx)
+		if kind == KIND_LEAF { return }
+
+		if kind == KIND_VSTACK {
+			var int gap = self.gaps.load_int(idx)
+			// Tally children's measured heights, total grow weight, and total
+			// shrink weight so we can share any surplus (grow) or deficit
+			// (shrink) on the main (vertical) axis between flex children.
+			var total_h = 0
+			var total_grow = 0
+			var total_shrink = 0
+			var n = 0
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					total_h = total_h + self.rh.load_int(ci)
+					var int g = self.grows.load_int(ci)
+					if g > 0 { total_grow = total_grow + g }
+					var int s = self.shrinks.load_int(ci)
+					if s > 0 { total_shrink = total_shrink + s }
+					n += 1
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			if n > 1 { total_h = total_h + gap * (n - 1) }
+			var int surplus = h - total_h
+			// Surplus (grow) and deficit (shrink) are mutually exclusive — at
+			// most one of `surplus > 0` / `surplus < 0` holds — so they're two
+			// independent top-level ifs rather than an else-if chain.
+			if total_grow > 0 && surplus > 0 {
+				var int ci2 = self.first_child(idx)
+				while ci2 != -1 {
+					if is_visible(self.handles.load_int(ci2) as uint64) {
+						var int g = self.grows.load_int(ci2)
+						if g > 0 {
+							self.rh.store_int(ci2, self.rh.load_int(ci2) + surplus * g / total_grow)
+						}
+					}
+					ci2 = self.next_sibling(ci2, idx)
+				}
+			}
+			// Distribute the deficit weighted by `shrink`. Each shrinkable child
+			// loses `deficit * shrink / total_shrink` pixels, floored at 0 so
+			// an over-weighted sibling can't drag another negative.
+			if total_shrink > 0 && surplus < 0 {
+				var int deficit = 0 - surplus
+				var int ci2 = self.first_child(idx)
+				while ci2 != -1 {
+					if is_visible(self.handles.load_int(ci2) as uint64) {
+						var int s = self.shrinks.load_int(ci2)
+						if s > 0 {
+							var int new_h = self.rh.load_int(ci2) - deficit * s / total_shrink
+							if new_h < 0 { new_h = 0 }
+							self.rh.store_int(ci2, new_h)
+						}
+					}
+					ci2 = self.next_sibling(ci2, idx)
+				}
+			}
+			// Place children top-to-bottom; cross (width) axis per alignment.
+			var int running_y = y
+			var int ci3 = self.first_child(idx)
+			while ci3 != -1 {
+				if is_visible(self.handles.load_int(ci3) as uint64) {
+					var int ch = self.rh.load_int(ci3)
+					var int cw = self.rw.load_int(ci3)
+					var int cx = x
+					var int align = self.aligns.load_int(ci3)
+					if align == ALIGN_STRETCH {
+						cw = w
+					}
+					if align == ALIGN_CENTER {
+						cx = x + (w - cw) / 2
+					}
+					if align == ALIGN_END {
+						cx = x + w - cw
+					}
+					self.arrange_node(ci3, cx, running_y, cw, ch)
+					running_y = running_y + ch + gap
+				}
+				ci3 = self.next_sibling(ci3, idx)
+			}
+			return
+		}
+
+		if kind == KIND_HSTACK {
+			var int gap = self.gaps.load_int(idx)
+			// Tally children's measured widths, total grow weight, and total
+			// shrink weight so we can share any surplus (grow) or deficit
+			// (shrink) on the main (horizontal) axis between flex children.
+			var total_w = 0
+			var total_grow = 0
+			var total_shrink = 0
+			var n = 0
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					total_w = total_w + self.rw.load_int(ci)
+					var int g = self.grows.load_int(ci)
+					if g > 0 { total_grow = total_grow + g }
+					var int s = self.shrinks.load_int(ci)
+					if s > 0 { total_shrink = total_shrink + s }
+					n += 1
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			if n > 1 { total_w = total_w + gap * (n - 1) }
+			var int surplus = w - total_w
+			// Surplus (grow) and deficit (shrink) are mutually exclusive — see
+			// the VStack branch above for the rationale.
+			if total_grow > 0 && surplus > 0 {
+				var int ci2 = self.first_child(idx)
+				while ci2 != -1 {
+					if is_visible(self.handles.load_int(ci2) as uint64) {
+						var int g = self.grows.load_int(ci2)
+						if g > 0 {
+							self.rw.store_int(ci2, self.rw.load_int(ci2) + surplus * g / total_grow)
+						}
+					}
+					ci2 = self.next_sibling(ci2, idx)
+				}
+			}
+			// Mirror of the VStack path: distribute the deficit weighted by
+			// `shrink`, floored at 0.
+			if total_shrink > 0 && surplus < 0 {
+				var int deficit = 0 - surplus
+				var int ci2 = self.first_child(idx)
+				while ci2 != -1 {
+					if is_visible(self.handles.load_int(ci2) as uint64) {
+						var int s = self.shrinks.load_int(ci2)
+						if s > 0 {
+							var int new_w = self.rw.load_int(ci2) - deficit * s / total_shrink
+							if new_w < 0 { new_w = 0 }
+							self.rw.store_int(ci2, new_w)
+						}
+					}
+					ci2 = self.next_sibling(ci2, idx)
+				}
+			}
+			var int running_x = x
+			var int ci3 = self.first_child(idx)
+			while ci3 != -1 {
+				if is_visible(self.handles.load_int(ci3) as uint64) {
+					var int cw = self.rw.load_int(ci3)
+					var int ch = self.rh.load_int(ci3)
+					var int cy = y
+					var int align = self.aligns.load_int(ci3)
+					if align == ALIGN_STRETCH {
+						ch = h
+					}
+					if align == ALIGN_CENTER {
+						cy = y + (h - ch) / 2
+					}
+					if align == ALIGN_END {
+						cy = y + h - ch
+					}
+					self.arrange_node(ci3, running_x, cy, cw, ch)
+					running_x = running_x + cw + gap
+				}
+				ci3 = self.next_sibling(ci3, idx)
+			}
+			return
+		}
+
+		if kind == KIND_ZSTACK {
+			var int ci = self.first_child(idx)
+			while ci != -1 {
+				if is_visible(self.handles.load_int(ci) as uint64) {
+					self.arrange_node(ci, x, y, w, h)
+				}
+				ci = self.next_sibling(ci, idx)
+			}
+			return
+		}
+
+		// KIND_BLOCK: forward the content rect (frame minus insets) to the single
+		// child. The node's own frame is already stored above.
+		if kind == KIND_BLOCK {
+			var int bpad = self.pads.load_int(idx)
+			var int ci = self.first_child(idx)
+			if ci != -1 {
+				self.arrange_node(ci, x + bpad, y + bpad, w - bpad * 2, h - bpad * 2)
+			}
+			return
+		}
+
+		// KIND_GRID
+		var int cols = self.cols.load_int(idx)
+		var int col_w = w / cols
+		var int running_y = y
+		var row_h = 0
+		var col_cursor = 0
+		var int ci = self.first_child(idx)
+		while ci != -1 {
+			if is_visible(self.handles.load_int(ci) as uint64) {
+				var int span = self.spans.load_int(ci)
+				if span < 1 { span = 1 }
+				if span > cols { span = cols }
+				if col_cursor + span > cols {
+					running_y = running_y + row_h + self.gaps.load_int(idx)
+					row_h = 0
+					col_cursor = 0
+				}
+				var int child_x = x + col_cursor * col_w
+				var int child_w = span * col_w
+				var int child_h = self.rh.load_int(ci)
+				self.arrange_node(ci, child_x, running_y, child_w, child_h)
+				if child_h > row_h { row_h = child_h }
+				col_cursor = col_cursor + span
+			}
+			ci = self.next_sibling(ci, idx)
+		}
+	}
+
+	// Recompute the dirty-rect list: any leaf whose resolved frame differs
+	// from its previously-applied frame is appended to `dirty_idx` (in tree
+	// order) and its baseline is advanced. Hidden leaves keep a stable
+	// (0,0,0,0) frame, so toggling visibility and re-laying-out marks them
+	// dirty exactly once, like any other frame change.
+	func collect_dirty = (ref self) {
+		self.dirty_n = 0
+		var i = 0
+		while i < self.count; i += 1 {
+			if self.kinds.load_int(i) == KIND_LEAF {
+				var int x = self.rx.load_int(i)
+				var int y = self.ry.load_int(i)
+				var int w = self.rw.load_int(i)
+				var int h = self.rh.load_int(i)
+				var int px = self.prx.load_int(i)
+				var int py = self.pry.load_int(i)
+				var int pw = self.prw.load_int(i)
+				var int ph = self.prh.load_int(i)
+				if x != px || y != py || w != pw || h != ph {
+					if self.dirty_idx.cap < self.dirty_n + 1 {
+						self.dirty_idx.grow_int(self.dirty_n + 1)
+					}
+					self.dirty_idx.store_int(self.dirty_n, i)
+					self.dirty_n = self.dirty_n + 1
+					self.prx.store_int(i, x)
+					self.pry.store_int(i, y)
+					self.prw.store_int(i, w)
+					self.prh.store_int(i, h)
+				}
+			}
+		}
+	}
+
+	// Number of leaves whose frame changed in the most recent `compute`/
+	// `layout` (the current dirty-rect list length).
+	pub func dirty_count = (self, out int) {
+		return self.dirty_n
+	}
+
+	// The i-th dirty rectangle (new frame) as "x,y,w,h", where i is in
+	// [0, dirty_count). The rect is the leaf's current resolved frame — the
+	// region the compositor must repaint.
+	pub func dirty_rect = (self, int i, out string) {
+		var int idx = self.dirty_idx.load_int(i)
+		return self.rx.load_int(idx).to_string() + "," + self.ry.load_int(idx).to_string() + "," + self.rw.load_int(idx).to_string() + "," + self.rh.load_int(idx).to_string()
+	}
+
+	// Mark a node dirty for incremental relayout: the node, its ancestors (their
+	// size may change as a result), and its descendants (their constraints flow
+	// down from this node) are all re-measured on the next `compute`/`layout`.
+	// A node left clean is known to have unchanged constraints, so its cached
+	// size is reused.
+	pub func mark_dirty = (ref self, int idx) {
+		self.dirty.store_int(idx, 1)
+		var int ci = self.first_child(idx)
+		while ci != -1 {
+			self.mark_dirty(ci)
+			ci = self.next_sibling(ci, idx)
+		}
+		var int p = self.pars.load_int(idx) - 1
+		while p != -1 {
+			self.dirty.store_int(p, 1)
+			p = self.pars.load_int(p) - 1
+		}
+	}
+
+	// How many times a node's `measure` body has actually run (incremental
+	// relayout lets this stay put for clean subtrees). Test/observability aid.
+	pub func measure_count = (self, int i, out int) {
+		return self.measured_count.load_int(i)
+	}
+
+	func apply = (self, int content_w, int content_h) {
+		// Only repaint the dirty leaves — the compositor's dirty-rect win.
+		var k = 0
+		while k < self.dirty_n; k += 1 {
+			var int i = self.dirty_idx.load_int(k)
+			var uint64 handle = self.handles.load_int(i) as uint64
+			if handle != 0 {
+				apply_frame(
+					handle,
+					self.rx.load_int(i),
+					self.ry.load_int(i),
+					self.rw.load_int(i),
+					self.rh.load_int(i),
+					content_w,
+					content_h,
+				)
+			}
+		}
+	}
+
+	// ── Control trait conformance ──
+	// The trait entry points delegate to the SoA engine: `measure` runs the
+	// recursive measure against the constraints and returns the resolved content
+	// size; `set_frame` arranges the whole subtree into the given rectangle
+	// (top-left origin); `intrinsic_size` measures against unbounded space. The
+	// `compute`/`layout` helpers below layer window integration, the root
+	// main-axis fill, dirty tracking, and native `apply` on top of this same
+	// math. A `Container` passed as a `Control` dispatches through these.
+
+	pub func measure = (self, BoxConstraints constraints, out Size) {
+		var int w = self.measure_node(
+			self.root,
+			constraints.min_width,
+			constraints.max_width,
+			constraints.min_height,
+			constraints.max_height,
+		)
+		var int h = self.rh.load_int(self.root)
+		var Size s = Size()
+		s.width = w
+		s.height = h
+		return s
+	}
+
+	pub func set_frame = (ref self, int x, int y, int width, int height) {
+		self.arrange_node(self.root, x, y, width, height)
+	}
+
+	pub func intrinsic_size = (self, out Size) {
+		var int w = self.measure_node(self.root, 0, INF, 0, INF)
+		var int h = self.rh.load_int(self.root)
+		var Size s = Size()
+		s.width = w
+		s.height = h
+		return s
+	}
+
+	// Pure measure + arrange against a size (no native calls). For testing.
+	// The root fills its main axis (VStack → height, HStack → width) so that
+	// children with `grow > 0` have surplus to absorb; the cross axis stays at
+	// the measured content size, preserving child alignment. Grid/ZStack roots
+	// keep both axes at content.
+	pub func compute = (ref self, int avail_w, int avail_h) {
+		// External constraint changed → the whole tree must re-measure.
+		if self.last_w != avail_w || self.last_h != avail_h {
+			self.mark_dirty(self.root)
+			self.last_w = avail_w
+			self.last_h = avail_h
+		}
+		var int root_w = self.measure_node(self.root, 0, avail_w, 0, avail_h)
+		var int root_h = self.rh.load_int(self.root)
+		var int frame_w = root_w
+		var int frame_h = root_h
+		var int kind = self.kinds.load_int(self.root)
+		if kind == KIND_VSTACK {
+			frame_h = avail_h
+		}
+		if kind == KIND_HSTACK {
+			frame_w = avail_w
+		}
+		self.arrange_node(self.root, 0, 0, frame_w, frame_h)
+		self.collect_dirty()
+	}
+
+	// Measure + arrange against the window's content rect (minus padding) and
+	// apply frames to every leaf, flipping y against the content height. The
+	// root fills its main axis (see `compute`).
+	pub func layout = (ref self, Window win) {
+		var int cw = win.content_width()
+		var int ch = win.content_height()
+		var int avail_w = cw - self.padding * 2
+		var int avail_h = ch - self.padding * 2
+		// External constraint changed → the whole tree must re-measure.
+		if self.last_w != avail_w || self.last_h != avail_h {
+			self.mark_dirty(self.root)
+			self.last_w = avail_w
+			self.last_h = avail_h
+		}
+		var int root_w = self.measure_node(self.root, 0, avail_w, 0, avail_h)
+		var int root_h = self.rh.load_int(self.root)
+		var int frame_w = root_w
+		var int frame_h = root_h
+		var int kind = self.kinds.load_int(self.root)
+		if kind == KIND_VSTACK {
+			frame_h = avail_h
+		}
+		if kind == KIND_HSTACK {
+			frame_w = avail_w
+		}
+		self.arrange_node(self.root, self.padding, self.padding, frame_w, frame_h)
+		self.collect_dirty()
+		self.apply(cw, ch)
+	}
+
+	// Install a windowDidResize: delegate so the layout re-runs *during* a
+	// live window resize. AppKit runs its own blocking tracking loop for the
+	// whole drag (our manual event loop is stuck inside sendEvent: and can't
+	// re-layout mid-drag), but it calls windowDidResize: on the delegate at
+	// each step — so re-running the layout there keeps every control,
+	// including sub-full-width grid cells that autoresizing masks can't
+	// express, sized and positioned live. Call once after the first layout().
+	// The callback calls nomen_layout_thunk (a free function) rather than the
+	// layout method directly: free functions are exported for C linkage on
+	// both backends, methods are not.
+	pub func set_resize_callback = (ref self, Window win) {
+		```
+		#arch: c, aarch64_use_c
+		#platform: macos
+		#scope: file
+		struct Container;
+		struct Window;
+		// nomen_layout_thunk is a free function (defined in Nomen below) that
+		// forwards to Container.layout — exported for C linkage on both
+		// backends, unlike the layout method itself. It takes the Container by
+		// `ref` (mutable reference): as a `class`, `ref Container` lowers to
+		// `struct Container **` (reference to the instance pointer), so the
+		// callback passes the address of the stored instance pointer.
+		extern void nomen_layout_thunk(struct Container**, struct Window*);
+		static void *g_resize_grid = 0;
+		static void *g_resize_win = 0;
+		void nomen_set_resize_target(void *grid, void *win) {
+			g_resize_grid = grid;
+			g_resize_win = win;
+		}
+		void nomen_window_did_resize(id self, SEL cmd, id notification) {
+			(void)self; (void)cmd; (void)notification;
+			if (g_resize_grid && g_resize_win) {
+				nomen_layout_thunk((struct Container**)&g_resize_grid, (struct Window*)g_resize_win);
+			}
+		}
+		```
+		```
+		#arch: c, aarch64_use_c
+		#platform: macos
+		nomen_set_resize_target(self, win);
+		Class Dc = objc_getClass("NomenResizeDelegate");
+		if (!Dc) {
+			Dc = objc_allocateClassPair(objc_getClass("NSObject"), "NomenResizeDelegate", 0);
+			if (Dc) {
+				class_addMethod(Dc, sel_registerName("windowDidResize:"), (IMP)nomen_window_did_resize, "v@:@");
+				objc_registerClassPair(Dc);
+			}
+		}
+		if (Dc) {
+			id delegate = ((id(*)(id, SEL))objc_msgSend)((id)Dc, sel_registerName("alloc"));
+			delegate = ((id(*)(id, SEL))objc_msgSend)(delegate, sel_registerName("init"));
+			((void(*)(id, SEL, id))objc_msgSend)((id)win->handle, sel_registerName("setDelegate:"), delegate);
+		}
+		```
+	}
+
+	// Hit test: is point (cx, cy) (top-left origin, as returned by click_x/
+	// click_y) inside the leaf with the given handle?
+	pub func contains = (self, uint64 handle, int cx, int cy, out bool) {
+		var int needle = handle as int
+		var i = 0
+		while i < self.count; i += 1 {
+			if self.kinds.load_int(i) == KIND_LEAF {
+				if self.handles.load_int(i) == needle {
+					var int x = self.rx.load_int(i)
+					var int y = self.ry.load_int(i)
+					var int w = self.rw.load_int(i)
+					var int h = self.rh.load_int(i)
+					if cx >= x {
+						if cx <= x + w {
+							if cy >= y {
+								if cy <= y + h {
+									return true
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+		return false
+	}
+
+	// Compositor hit test: walk the frame tree front-to-back and return the
+	// frontmost leaf whose frame contains (cx, cy) (top-left origin, matching
+	// `click_x`/`click_y` and `contains`). For every container we test children
+	// in paint order (front-to-back) and keep the last hit — a later child paints
+	// on top of earlier ones, so the frontmost claimant wins. Hidden leaves are
+	// skipped, as in measure/arrange. Returns the leaf's native handle (0 = no
+	// hit). This needs no platform code — it's pure rect math on the frame tree.
+	pub func hit_test = (self, int cx, int cy, out uint64) {
+		var int idx = self.hit_test_node(self.root, cx, cy)
+		if idx == -1 { return 0 }
+		return self.handles.load_int(idx) as uint64
+	}
+
+	// Same as `hit_test` but returns the frontmost leaf's node index (root is 0;
+	// -1 = no hit). Handy for callers that want the node rather than the handle
+	// (e.g. to read the resolved frame via `fmt_frame`).
+	pub func hit_test_index = (self, int cx, int cy, out int) {
+		return self.hit_test_node(self.root, cx, cy)
+	}
+
+	func hit_test_node = (self, int idx, int cx, int cy, out int) {
+		var int kind = self.kinds.load_int(idx)
+		if kind == KIND_LEAF {
+			if is_visible(self.handles.load_int(idx) as uint64) {
+				var int x = self.rx.load_int(idx)
+				var int y = self.ry.load_int(idx)
+				var int w = self.rw.load_int(idx)
+				var int h = self.rh.load_int(idx)
+				if cx >= x {
+					if cx <= x + w {
+						if cy >= y {
+							if cy <= y + h {
+								return idx
+							}
+						}
+					}
+				}
+			}
+			return -1
+		}
+		// Container: iterate children in paint order; keep the last (frontmost) hit.
+		var int result = -1
+		var int ci = self.first_child(idx)
+		while ci != -1 {
+			if is_visible(self.handles.load_int(ci) as uint64) {
+				var int hit = self.hit_test_node(ci, cx, cy)
+				if hit != -1 { result = hit }
+			}
+			ci = self.next_sibling(ci, idx)
+		}
+		return result
+	}
+
+	// Format a child's resolved frame as "x,y,w,h" (root is 0; children start at 1).
+	pub func fmt_frame = (self, int i, out string) {
+		return self.rx.load_int(i).to_string() + "," + self.ry.load_int(i).to_string() + "," + self.rw.load_int(i).to_string() + "," + self.rh.load_int(i).to_string()
+	}
+}
+
+// Free-function wrapper around Container.layout so the C delegate callback
+// (nomen_window_did_resize) can trigger a live relayout: free functions are
+// exported for C linkage on both backends, methods are not.
+/**
+ * Entry point the layout engine calls to lay out a Container's tree
+ **/
+pub func nomen_layout_thunk = (ref Container grid, Window win) {
+	grid.layout(win)
+}
+
+/**
+ * Creates a vertical stack container with the given spacing
+ **/
+pub func VStack = (int spacing, out Container) {
+	var c = Container()
+	c.make_root(KIND_VSTACK, spacing, 0)
+	return c
+}
+
+/**
+ * Creates a horizontal stack container with the given spacing
+ **/
+pub func HStack = (int spacing, out Container) {
+	var c = Container()
+	c.make_root(KIND_HSTACK, spacing, 0)
+	return c
+}
+
+/**
+ * Creates a Z-stack container (children layered on top of one another)
+ **/
+pub func ZStack = (out Container) {
+	var c = Container()
+	c.make_root(KIND_ZSTACK, 0, 0)
+	return c
+}
+
+/**
+ * Creates a grid container with `cols` columns and the given spacing
+ **/
+pub func Grid = (int cols: cols > 0, int spacing, out Container) {
+	var c = Container()
+	c.make_root(KIND_GRID, spacing, cols)
+	return c
+}