tuile 0.16.0 → 0.17.0

data/lib/tuile/component_background.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Tuile
+  # One component's background: what it states, and the {Color} that resolves
+  # to right now. A component reaches its own through the protected
+  # {Component#bg}; an app tints through {Component#bg_color=}.
+  #
+  #   # a widget: its own well, brighter while focused
+  #   def initialize
+  #     super
+  #     bg.default_color = ComponentBackground::INPUT_WELL
+  #   end
+  #
+  #   panel.bg_color = Theme.ref(:panel_bg)   # an app: tint a whole subtree
+  #
+  # The chain, first answer wins: the owner's {Component#error_bg_color}, then
+  # {#color} (the app's), then {#default_color} (the widget's), then the parent's
+  # {#effective}, then `nil` — the terminal default. {INHERIT} at a level skips
+  # the owner's remaining levels and goes straight to the parent. Every level
+  # takes a {Color}, a {Theme::Ref} or a Hash keyed by {STATES}, and resolves
+  # against the live theme and the owner's {Component#active?} at paint time,
+  # so nothing here caches a color.
+  #
+  # == Implementation details
+  #
+  # The error level is *pulled* from the owner rather than stored here: it
+  # follows the validation state, and a pushed copy would need every edge of
+  # that state to remember to re-set it. A stale error well fails silently.
+  class ComponentBackground
+    # The states a background may be keyed by. Closed and framework-defined:
+    # a key is added when Tuile grows the state, never to let an app invent one.
+    # @return [Array<Symbol>]
+    STATES = %i[normal active].freeze
+
+    # Assign to {#color} to say "I contribute no background of my own" —
+    # resolution skips the owner's {#default_color} and takes whatever
+    # surrounds it. CSS's `background: inherit`, and the reason a widget with a
+    # well can be made to sit flush in a tinted panel:
+    #
+    #   field.bg_color = ComponentBackground::INHERIT   # no well; take the pane's tint
+    #
+    # Distinct from `nil`, which falls through to {#default_color} *first*.
+    # There is deliberately no counterpart forcing the terminal default despite
+    # a tinted ancestor (`D_bg_inherit`).
+    # @return [Symbol]
+    INHERIT = :inherit
+
+    # The well every input field paints: {Theme#input_bg_color} at rest,
+    # {Theme#active_bg_color} while on the focus chain. Live {Theme::Ref}s, so a
+    # {Screen#theme=} restyles it with no hook.
+    # @return [Hash{Symbol => Theme::Ref}]
+    INPUT_WELL = { normal: Theme.ref(:input_bg_color), active: Theme.ref(:active_bg_color) }.freeze
+
+    # @param owner [Component] whose background this is.
+    def initialize(owner)
+      @owner = owner
+      @color = nil
+      @default_color = nil
+    end
+
+    # @return [Color, Theme::Ref, Hash{Symbol => Color, Theme::Ref}, Symbol, nil]
+    #   the app's background — the value as set, so a {Theme::Ref} comes back
+    #   unresolved and a state map comes back a Hash; `nil` when unset.
+    attr_reader :color
+
+    # Tints the owner and every descendant that doesn't state its own, and
+    # invalidates that subtree. See {Component#bg_color=}, its public face.
+    # @param value [Color, Theme::Ref, Hash, Symbol, Integer, Array<Integer>, nil]
+    # @raise [ArgumentError] when a Hash carries a key outside {STATES}.
+    # @raise [KeyError] when a {Theme::Ref} names an absent custom token.
+    # @return [void]
+    def color=(value)
+      value = coerce(value)
+      return if @color == value
+
+      @color = value
+      invalidate
+    end
+
+    # @return [Color, Theme::Ref, Hash{Symbol => Color, Theme::Ref}, nil] the
+    #   widget's own surface — `nil` by default, meaning "whatever is behind me
+    #   shows through".
+    attr_reader :default_color
+
+    # States the opaque surface a widget paints when the app has set no
+    # {#color} — and inheritance stops there, which is what keeps a form's
+    # fields looking like fields inside a tinted panel. Set it unconditionally,
+    # at construction: a widget owned by a bigger one is told so with
+    # {INHERIT}, and must not work it out from where it sits in the tree.
+    #
+    #   bg.default_color = ComponentBackground::INPUT_WELL             # the field well
+    #   bg.default_color = { normal: Theme.ref(:panel_bg), active: … } # an app widget's
+    #
+    # **Hand it a {Theme::Ref}, never `screen.theme.input_bg_color`** — a
+    # resolved {Color} is a cached token and strands on the old scheme after a
+    # {Screen#theme=}, with nothing raising.
+    # @param value [Color, Theme::Ref, Hash, Symbol, Integer, Array<Integer>, nil]
+    # @raise [ArgumentError] when a Hash carries a key outside {STATES}.
+    # @raise [KeyError] when a {Theme::Ref} names an absent custom token.
+    # @return [void]
+    def default_color=(value)
+      value = coerce(value)
+      return if @default_color == value
+
+      @default_color = value
+      invalidate
+    end
+
+    # @return [Color, nil] the background actually painted, for the state the
+    #   owner is in right now — the whole chain, resolved. {Screen#canvas_for}
+    #   loads it onto the canvas; an app never needs it.
+    def effective
+      own = resolve(@owner.__send__(:error_bg_color)) || resolve(@color) || resolve(@default_color)
+      return parent_effective if own.nil? || own == INHERIT
+
+      own
+    end
+
+    # What surrounds the owner — the app's {#color}, else whatever the parent
+    # paints. Skips {#default_color} and the error well, the owner's *own*
+    # surface, which is what makes it the right answer for a dead tail outside
+    # {Component#extent} and a container's gaps.
+    # @return [Color, nil]
+    def ambient
+      own = resolve(@color)
+      return parent_effective if own.nil? || own == INHERIT
+
+      own
+    end
+
+    private
+
+    # @return [Color, nil]
+    def parent_effective = @owner.parent&.__send__(:bg)&.effective
+
+    # @return [void]
+    def invalidate
+      @owner.walk_tree { |c| @owner.screen.invalidate(c) } if @owner.attached?
+    end
+
+    # Collapses one level to the {Color} it means right now. An absent state
+    # key yields `nil`, so resolution falls through to the next level — which
+    # is what lets `bg_color = { active: … }` keep the widget's own normal well.
+    # @param value [Color, Theme::Ref, Hash, Symbol, nil]
+    # @return [Color, Symbol, nil]
+    def resolve(value)
+      case value
+      when nil then nil
+      when Hash then resolve(value[@owner.active? ? :active : :normal])
+      when Theme::Ref then value.resolve(@owner.screen.theme)
+      else value
+      end
+    end
+
+    # Validates and normalizes a level's value, so a bad token or a misspelled
+    # state raises at the assignment rather than deep in a repaint. A chrome
+    # token needs no theme to check, which keeps construction screen-free.
+    # @param value [Object]
+    # @return [Color, Theme::Ref, Hash, Symbol, nil]
+    # @raise [ArgumentError] on a Hash key outside {STATES}.
+    # @raise [KeyError] on a {Theme::Ref} naming an absent custom token.
+    def coerce(value)
+      case value
+      when nil, Color, INHERIT then value
+      when Theme::Ref
+        value.tap { _1.resolve(@owner.screen.theme) unless Theme.chrome_token?(_1.name) }
+      when Hash
+        unknown = value.keys - STATES
+        raise ArgumentError, "unknown background state(s) #{unknown.join(", ")}; known: #{STATES.join(", ")}" \
+          unless unknown.empty?
+
+        value.to_h { |state, color| [state, coerce(color)] }.freeze
+      else Color.coerce(value)
+      end
+    end
+  end
+end

data/lib/tuile/component_util.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Pure queries over the component tree, as module functions:
+  #
+  #   ComponentUtil.effectively_visible?(field)   # false under a hidden panel
+  #
+  # Home for a question that belongs to no one component and to no one asker.
+  # Deliberately **not** {Component} methods, for the reason `D_empty_ancestor`
+  # declined a `Component#paintable?`: each reads as a component-level concept
+  # and is really the framework's question.
+  #
+  # **The gate for a new member** is a pure query over the tree — no state, no
+  # mutation — with **two or more call sites in `lib/`**; one caller stays
+  # private to the class that asks. Without it this becomes the drawer internal
+  # things go in.
+  #
+  # Tuile-internal: a member may change or vanish with no migration note, and
+  # one an app turns out to need graduates to a documented home instead.
+  #
+  # @api private
+  module ComponentUtil
+    module_function
+
+    # Whether `component` is genuinely on screen: attached, with neither it nor
+    # any ancestor hidden. {Component#visible?} is a component's own flag alone,
+    # so a field under a hidden panel is still `visible?` itself.
+    #
+    # A *walk* needs no such predicate — it prunes at the hidden subtree's root
+    # ({Component#walk_shown_tree}).
+    # @param component [Component]
+    # @raise [TypeError] on `nil` — a caller that may hold one says so itself,
+    #   rather than having "no component" quietly answer "not visible".
+    # @return [Boolean]
+    def effectively_visible?(component)
+      raise TypeError, "expected Component, got nil" if component.nil?
+
+      cursor = component
+      cursor = cursor.parent while cursor&.visible?
+      cursor.nil? && component.attached?
+    end
+  end
+end

data/lib/tuile/event.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The marker every event includes: *something happened, described by a frozen
+  # value*.
+  #
+  #   class ValueChangeEvent < Data.define(:source, :value)
+  #     include Tuile::Event
+  #   end
+  #
+  #   case event
+  #   when Mouse::DownEvent then …    # one concrete class
+  #   when Tuile::Event     then …    # …or all of them at once
+  #   end
+  #
+  # One concept in three namespaces — {Mouse}'s wire events, {EventQueue}'s loop
+  # events, and the ones a {Listeners} slot fires. There is no base class: the
+  # `case` above works off the marker alone (`D_mouse_dispatch`).
+  #
+  # **It mandates no members and supplies no defaults.** `source` belongs to the
+  # classes that have one — for the twelve events predating this marker it would
+  # be nil throughout, and a member nothing reads is the mailbox shape
+  # `D_bad_input` refuses. A default here would be worse than the absence rather
+  # than better: `from_user? = false` on the marker would make
+  # {Mouse::DownEvent}, the most from-user thing in the gem, answer `false`, and
+  # nothing would say so.
+  module Event
+  end
+end

data/lib/tuile/event_queue.rb

@@ -32,6 +32,9 @@ module Tuile
     # Submits block to be run in the event queue. Returns immediately.
     #
     # The function may be called from any thread.
+    #
+    # The block runs only while a loop is draining: submitted before the first
+    # {#run_loop} it waits for one, submitted after the last it never runs.
     # @yield called from the event-loop thread.
     # @yieldreturn [void]
     # @return [void]
@@ -165,6 +168,7 @@ module Tuile
     # @!attribute [r] key
     #   @return [String] key code.
     class KeyEvent < Data.define(:key)
+      include Tuile::Event
     end
 
     # Text arrived from the clipboard rather than the keyboard: the terminal
@@ -181,6 +185,8 @@ module Tuile
     #   @return [String] the pasted text, `\n`-normalized by
     #     {Keys.normalize_paste}.
     class PasteEvent < Data.define(:text)
+      include Tuile::Event
+
       # @param text [String]
       def initialize(text:)
         super(text: text.freeze)
@@ -193,6 +199,7 @@ module Tuile
     # @!attribute [r] error
     #   @return [StandardError] the underlying error.
     class ErrorEvent < Data.define(:error)
+      include Tuile::Event
     end
 
     # TTY has been resized. Contains the current width and height of the TTY
@@ -203,6 +210,8 @@ module Tuile
     # @!attribute [r] height
     #   @return [Integer] terminal height in rows.
     class TTYSizeEvent < Data.define(:width, :height)
+      include Tuile::Event
+
       # @param width [Integer]
       # @param height [Integer]
       def initialize(width:, height:)
@@ -233,6 +242,8 @@ module Tuile
     # @!attribute [r] scheme
     #   @return [Symbol] `:light` or `:dark`.
     class ColorSchemeEvent < Data.define(:scheme)
+      include Tuile::Event
+
       # The DSR-style color-scheme report: `\e[?997;1n` dark, `\e[?997;2n`
       # light.
       # @return [Regexp]
@@ -257,6 +268,8 @@ module Tuile
     # @!attribute [r] color
     #   @return [Color] the reported background, 24-bit RGB.
     class BackgroundColorEvent < Data.define(:color)
+      include Tuile::Event
+
       # @param key [String] key read via {Keys.getkey}.
       # @return [BackgroundColorEvent, nil] nil when `key` is not an OSC 11
       #   background reply.
@@ -271,6 +284,7 @@ module Tuile
     # repainting windows.
     class EmptyQueueEvent
       include Singleton
+      include Tuile::Event
     end
 
     # Handle returned by {EventQueue#tick}. Cancel a running ticker via

data/lib/tuile/fake_screen.rb

@@ -11,6 +11,11 @@ module Tuile
   # run an event loop, so it is *not* suitable for system-testing whole apps
   # — for that, drive the real script through a PTY (see `spec/examples/`).
   #
+  # It also turns the stale-rect diagnostic on ({Tuile::StrictLayout}): a rect
+  # read before the layout has settled raises here, where in an app it would
+  # quietly answer the previous pass's rectangle. `Tuile.strict_layout = false`
+  # opts a suite out; {Tuile.without_strict_layout} opts one read out.
+  #
   # Call {Screen.fake} to initialize the fake screen easily. Typical usage:
   #
   #   before { Screen.fake }
@@ -23,13 +28,21 @@ module Tuile
   #     assert_includes Screen.instance.prints.join, "hi"
   #   end
   class FakeScreen < Screen
-    def initialize
-      super
+    # The terminal starts at the size given, as if it had always been that big:
+    # nothing is dispatched and nothing repaints. To exercise a change of size,
+    # the SIGWINCH path, call {#resize_terminal} instead.
+    # @param width [Integer] the terminal's columns.
+    # @param height [Integer] the terminal's rows.
+    def initialize(width: 160, height: 50)
+      super()
+      # `Tuile.strict_layout` defaults to `:raise` under this screen; this puts
+      # the check it answers through into `Component#rect`.
+      StrictLayout.install
       @event_queue = FakeEventQueue.new
-      @size = Size.new(160, 50)
+      @size = Size.new(width, height)
       # super sized both to the test runner's TTY.
       @buffer.resize(@size)
-      @pane.rect = Rect.new(0, 0, @size.width, @size.height)
+      size_pane
       @prints = []
     end
 
@@ -72,7 +85,7 @@ module Tuile
     # against `\n`.
     # @param text [String]
     # @return [Boolean] true if some component consumed it.
-    def paste(text) = handle_paste(Keys.normalize_paste(text))
+    def paste(text) = dispatch(EventQueue::PasteEvent.new(Keys.normalize_paste(text)))
 
     # @param component [Component] the component to check.
     # @return [Boolean]
@@ -101,7 +114,7 @@ module Tuile
     # Plays a whole click at a screen cell — the press, then the release that
     # ends its grab:
     #
-    #   screen.click(save_button.rect.left, save_button.rect.top)
+    #   screen.click(save_button.absolute_rect.left, save_button.absolute_rect.top)
     #
     # Routed exactly as the terminal's own report would be ({Mouse::Router}), so
     # it focuses, dismisses popups and bubbles.
@@ -114,26 +127,33 @@ module Tuile
       release(x, y)
     end
 
+    # The terminal reporting a new size, routed as its own report would be: the
+    # pane takes the whole screen, and every popup is placed again.
+    # @param width [Integer]
+    # @param height [Integer]
+    # @return [void]
+    def resize_terminal(width, height) = dispatch(EventQueue::TTYSizeEvent.new(width, height))
+
     # Half a {#click}, for a spec about the grab — what is claimed, what the
     # drag does, what the release lands on.
     # @param x [Integer] 0-based column.
     # @param y [Integer] 0-based row.
     # @param button [Symbol] `:left`, `:middle` or `:right`.
     # @return [void]
-    def press(x, y, button: :left) = handle_mouse(Mouse::DownEvent.new(button, x, y))
+    def press(x, y, button: :left) = dispatch(Mouse::DownEvent.new(button, x, y))
 
     # The other half of {#press}.
     # @param x [Integer] 0-based column.
     # @param y [Integer] 0-based row.
     # @return [void]
-    def release(x, y) = handle_mouse(Mouse::UpEvent.new(x, y))
+    def release(x, y) = dispatch(Mouse::UpEvent.new(x, y))
 
     # One wheel notch over a cell.
     # @param direction [Symbol] `:up`, `:down`, `:left` or `:right`.
     # @param x [Integer] 0-based column.
     # @param y [Integer] 0-based row.
     # @return [void]
-    def scroll(direction, x, y) = handle_mouse(Mouse::ScrollEvent.new(direction, x, y))
+    def scroll(direction, x, y) = dispatch(Mouse::ScrollEvent.new(direction, x, y))
 
     # Moves the pointer, firing the enter/exit hooks the new position implies —
     # or, while a press is grabbed, one {Component#handle_mouse_drag}.
@@ -141,7 +161,7 @@ module Tuile
     # @param y [Integer] 0-based row.
     # @param button [Symbol, nil] the button held while moving, if any.
     # @return [void]
-    def move(x, y, button: nil) = handle_mouse(Mouse::MoveEvent.new(button, x, y))
+    def move(x, y, button: nil) = dispatch(Mouse::MoveEvent.new(button, x, y))
 
     # Plays a whole drag: the press at the first point, one move per point
     # after it, and the release at the last.
@@ -169,6 +189,17 @@ module Tuile
 
     private
 
+    # Settles the layout on the way *in* as well as out. A spec mutates between
+    # gestures, where the loop would have settled at the end of the previous
+    # dispatch and there is none — and routing a press reads rects, so without
+    # this a `click` hit-tests what the last mutation left half-finished.
+    # @param event [Object] see {Screen#dispatch}.
+    # @return [Object] whatever the handler returned.
+    def dispatch(event)
+      flush_layout
+      super
+    end
+
     # @param point [Point, Array(Integer, Integer)]
     # @return [Point]
     def coerce_point(point)

data/lib/tuile/keys.rb

@@ -158,12 +158,13 @@ module Tuile
 
       # Escape sequence. Try to read more data.
       begin
-        # Read up to 5 bytes: that's the maximum tail length of any escape
-        # sequence Tuile recognizes after the initial \e (X10 mouse `[Mbxy`,
-        # CTRL+arrow `[1;5D`, etc.). Reading 6 here would over-read into the
-        # next sequence on tight mouse-event bursts — we'd silently steal
-        # the next event's leading \e and the rest of it would surface as
-        # individual printable keypresses in focused inputs.
+        # Read up to 5 bytes: that's the maximum tail length of any *fixed*-
+        # length escape sequence Tuile recognizes after the initial \e (X10
+        # mouse `[Mbxy`, CTRL+arrow `[1;5D`, etc.); the variable-length ones
+        # are drained below. Reading 6 here would over-read into the next
+        # sequence on tight mouse-event bursts — we'd silently steal the next
+        # event's leading \e and the rest of it would surface as individual
+        # printable keypresses in focused inputs.
         char += $stdin.read_nonblock(5)
       rescue IO::EAGAINWaitReadable
         # The "ESC" key pressed => only the \e char is emitted.
@@ -176,6 +177,14 @@ module Tuile
       # instead of leaking tail bytes as keypresses.
       char += $stdin.read(6 - char.bytesize) if char.start_with?("\e[M") && char.bytesize < 6
 
+      # SGR mouse reports (`\e[<Cb;x;yM`, mode 1006) are variable-length and do
+      # not align to read boundaries, so no gulp width fits: drain to the final
+      # `M`/`m` a byte at a time. The gulp above cannot over-read one — the
+      # shortest report is 8 bytes after the `\e` — and only digits and `;`
+      # precede the terminator, so this stops at the first event's end.
+      # Keyboard sequences never start with `\e[<`, so this eats no real key.
+      char += $stdin.read(1) while char.start_with?("\e[<") && !char.end_with?("M", "m")
+
       # Private-mode CSI reports (`\e[?` params… final byte in 0x40..0x7E)
       # can outgrow the 5-byte gulp above — the mode-2031 color-scheme
       # notification `\e[?997;1n` (see {EventQueue::ColorSchemeEvent}) is 8

data/lib/tuile/layout_pass.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Who may assign a rect right now. {Component#rect=} is refused outside the
+  # parent's {Component#relayout}, and this is the bracket that says when one
+  # is running:
+  #
+  #   LayoutPass.run(container) { relayout }    # inside the container
+  #
+  # A pass also records which children it has placed *so far*. Before the
+  # first, {Component#invalidate_layout} drops a mark the container makes on
+  # itself — the pass that would answer it is the one running — and until a
+  # child's turn, {Component#rect_stale?} reports its rect as the previous
+  # pass's ({.unplaced?}).
+  #
+  # **Thread-local rather than an ivar**, because a tree with no {Screen}
+  # places children too, so there is no one object to hang the state on.
+  #
+  # Tuile-internal: a member may change or vanish with no migration note. The
+  # rule it enforces is {Component#rect=}'s and is documented there.
+  #
+  # @api private
+  module LayoutPass
+    # The thread-local naming what is placing children right now.
+    # @return [Symbol]
+    PLACING = :tuile_placing
+    private_constant :PLACING
+
+    # The thread-local holding the children the current placer has assigned a
+    # rect so far — an identity `Set`, or `nil` before the first.
+    # @return [Symbol]
+    PLACED = :tuile_placed
+    private_constant :PLACED
+
+    # Drain rounds a {Screen#flush_layout} or a detached {Component#flush_layout}
+    # runs before giving up. No container sizes itself from its children, so a
+    # tree settles in about its depth; one that is still marking past this is
+    # feeding a pass's output back into its input — a {Component::Scroller}
+    # whose `content_rows` the app derives from the content's width, say — and
+    # would otherwise hang the UI thread.
+    # @return [Integer]
+    MAX_ROUNDS = 50
+
+    module_function
+
+    # Runs the block with `placer` as the one thing whose children's rects may
+    # be assigned. Nests: the enclosing pass is restored on the way out.
+    # @param placer [Component, Screen]
+    # @return [Object] the block's value.
+    def run(placer)
+      outer = Thread.current[PLACING]
+      outer_placed = Thread.current[PLACED]
+      Thread.current[PLACING] = placer
+      Thread.current[PLACED] = nil
+      yield
+    ensure
+      Thread.current[PLACING] = outer
+      Thread.current[PLACED] = outer_placed
+    end
+
+    # Whether any pass is placing children right now — what a drain refuses to
+    # run inside ({.refuse_nested}), and {Screen#focused=} defers its geometry under.
+    # @return [Boolean]
+    def running? = !Thread.current[PLACING].nil?
+
+    # The guard at the top of both drains, {Screen#flush_layout} and a detached
+    # {Component#flush_layout}.
+    # @raise [Tuile::Error] while a pass is running: it has not placed its
+    #   children yet, so a nested drain would read the rects it is about to
+    #   reassign.
+    # @return [void]
+    def refuse_nested
+      return unless running?
+
+      raise Tuile::Error, "flush_layout inside #{Thread.current[PLACING]}'s relayout: the running pass " \
+                          "has not placed its children yet, so a nested drain would read stale rects"
+    end
+
+    # What may assign `component`'s rect: its parent, whose
+    # {Component#relayout} does. The exception is the {ScreenPane}, which has
+    # no parent whose pass could place it, so the {Screen} does (`D_tree_first`
+    # keeps the screen out of the tree). Those are the only two cases — this is
+    # a closed rule rather than a hook a component may answer for itself.
+    # @param component [Component]
+    # @return [Component, Screen, nil]
+    def placer(component)
+      component.is_a?(ScreenPane) ? component.screen : component.parent
+    end
+
+    # @param component [Component] the one whose rect is being assigned.
+    # @raise [Tuile::Error] unless {.placer} is what is placing now.
+    # @return [void]
+    def check(component)
+      current = Thread.current[PLACING]
+      return if !current.nil? && current.equal?(placer(component))
+
+      if component.parent.nil?
+        raise Tuile::Error, "#{component} has no parent to place it; to size a detached tree, " \
+                            "hold it in a Layout::Absolute (add(tree, rect), then flush_layout)"
+      end
+      raise Tuile::Error, "#{component}'s rect assigned outside #{component.parent}'s relayout; change " \
+                          "what the parent places it by instead (Absolute#constrain, Box#constrain, " \
+                          "Overlay#placement=)"
+    end
+
+    # Runs every {Component#relayout} `root`'s tree owes, to a fixpoint — the one
+    # drain behind both {Screen#flush_layout} and a detached
+    # {Component#flush_layout}.
+    #
+    # **The dirty flags are the queue.** Each round walks the tree pre-order and
+    # runs whatever is marked, so a parent lays out before the children whose
+    # rects it just wrote, and those children run in the same walk. A mark on
+    # something *earlier* in the order — a child's pass marking its parent —
+    # waits for the next round, and the drain ends on the first walk that finds
+    # nothing marked. A flag is cleared by the pass that answers it, so a
+    # container is never run twice for one mark, and a raise strands nothing.
+    # @param root [Component] the tree's root: the {ScreenPane}, or a detached root.
+    # @param rounds [Integer] rounds already run in this flush, so a caller
+    #   draining more than once — the screen, re-checking anchors — keeps one count.
+    # @raise [Tuile::Error] past {MAX_ROUNDS} rounds, naming the containers still marked.
+    # @return [Integer] the rounds run in total.
+    def drain(root, rounds = 0)
+      while drain_round(root)
+        next rounds += 1 if rounds < MAX_ROUNDS
+
+        culprits = []
+        root.walk_tree { culprits << _1 if _1.layout_dirty? }
+        raise Tuile::Error, "layout did not settle after #{MAX_ROUNDS} rounds, still marking: " \
+                            "#{culprits.first(5).map(&:inspect).join(", ")} — a relayout keeps changing its " \
+                            "own input (content_rows derived from the content's width?)"
+      end
+      rounds
+    end
+
+    # One pre-order walk running every marked container.
+    # @param root [Component]
+    # @return [Boolean] whether it ran anything.
+    def drain_round(root)
+      ran = false
+      root.walk_tree do |component|
+        next unless component.layout_dirty?
+
+        # `__send__`: private, because it is this drain's alone.
+        component.__send__(:perform_relayout)
+        ran = true
+      end
+      ran
+    end
+    private_class_method :drain_round
+
+    # Records that the running pass has assigned `component` its rect. Past
+    # the first, a mark on the placer is kept rather than dropped.
+    # @param component [Component]
+    # @return [void]
+    def note_placement(component)
+      (Thread.current[PLACED] ||= Set.new.compare_by_identity) << component
+    end
+
+    # Whether `component` is the running placer and has placed no child yet —
+    # the window in which a mark it makes on itself is redundant.
+    # @param component [Component]
+    # @return [Boolean]
+    def before_first_placement?(component)
+      Thread.current[PLACING].equal?(component) && Thread.current[PLACED].nil?
+    end
+
+    # Whether `component`'s placer is running its pass right now and has not
+    # reached it yet — so its rect is the previous pass's, though no flag says
+    # so: {Component#perform_relayout} clears the placer's before the body runs.
+    # @param component [Component]
+    # @return [Boolean]
+    def unplaced?(component)
+      placing = Thread.current[PLACING]
+      return false if placing.nil? || !placing.equal?(placer(component))
+
+      placed = Thread.current[PLACED]
+      placed.nil? || !placed.include?(component)
+    end
+  end
+end