max / makeover-layout

State the first-paint rule, and make it an admission test Nothing changes size or position after it is first drawn, and nothing stands in for content that has not arrived. It belongs in the description layer because a renderer can only reserve space the description gave it enough to size, which makes it a second test a new member has to pass. The consequence worth naming: an Option on a measurement means the host can never know it, not that it has not been counted yet. A count arriving on a later pass widens whatever prints it. Readiness::Pending says what it is not for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Max Johnson <me@maxj.phd> · 2026-08-16 19:45 UTC

Signed with PGP, not checked

Commit: 5d842b8d4d7ed452b1142e9413316a41936a0cf1

Parent: 2794cd9

1 file changed, +38 insertions, -0 deletions

M src/lib.rs +38

			@@ -337,6 +337,34 @@
337	337		//! the quieter two from the ink, so "one step back" means the same distance in
338	338		//! every theme and a renderer cannot land between them by picking its own.
339	339		//!
	340	+	//! # First paint is final paint
	341	+	//!
	342	+	//! One rule, settled 2026-08-16. Nothing may change size or position after it is
	343	+	//! first drawn, and nothing may stand in for content that has not arrived yet.
	344	+	//! Both halves are absolute.
	345	+	//!
	346	+	//! It is stated here, rather than left to each renderer, because a renderer can
	347	+	//! only reserve space the description gave it enough to size. A member whose
	348	+	//! size depends on its content therefore owes whatever makes it sizeable while
	349	+	//! the content is still absent, and that is the second admission test for a new
	350	+	//! member: not only does it compose something this crate already names, it can
	351	+	//! be laid out before it is filled.
	352	+	//!
	353	+	//! The mechanism is a reservation, and [`Sort`]'s caret is the worked example.
	354	+	//! The caret is drawn into a box its own width whether or not the column is
	355	+	//! sorted, so pressing a heading cannot reflow the row it sits in. The box names
	356	+	//! no magnitude, which is what keeps it out of `makeover-geometry`'s territory.
	357	+	//! Reserve from what is known; never discover geometry from what has not
	358	+	//! arrived.
	359	+	//!
	360	+	//! The trap is an `Option` that means "not yet". [`Readiness::Pending`] is the
	361	+	//! honest way to say a region is still waiting. An optional measurement is
	362	+	//! not: a count that shows up later widens the text that prints it and moves
	363	+	//! everything beside it, which is the reflow this rule exists to forbid. So an
	364	+	//! `Option` on a measurement means the host will never know it — a property of
	365	+	//! the query, fixed for the life of the screen — and a renderer sizes for the
	366	+	//! answer it was handed rather than for the one it hopes is coming.
	367	+	//!
340	368		//! # Where the description stops
341	369		//!
342	370		//! The rule is that a member is added when an app needs a fact the vocabulary
			@@ -1111,6 +1139,16 @@
1111	1139		/// The content is here.
1112	1140		Ready,
1113	1141		/// The content is on its way.
	1142	+	///
	1143	+	/// For a region that changes after the first paint, and never for the
	1144	+	/// first paint itself: see "First paint is final paint" in the crate header.
	1145	+	/// A host that renders once, with its data already in hand, has nothing to
	1146	+	/// say this about, and a screen arriving in this state is describing a
	1147	+	/// moment its host should not have been in.
	1148	+	///
	1149	+	/// What stands in occupies the geometry the content will occupy. A stand-in
	1150	+	/// sized to itself rather than to what replaces it is the reflow the rule
	1151	+	/// forbids, arriving one repaint later.
1114	1152		Pending,
1115	1153		/// The content arrived and there is none of it.
1116	1154		///