tuile 0.15.0 → 0.17.0

data/examples/sampler.rb

@@ -12,28 +12,40 @@
 # Keys: ←→ along the strip, Enter/↓ to open a menu, or a letter for the
 # underlined mnemonic. Tab / Shift+Tab move focus between the strip, the jump
 # box and the demo's widgets. q or ESC quits.
+#
+# Runs at `capture_mouse: :hover` — the Mouse demo needs it, and the level is
+# one app-wide choice made at the event loop.
 
 require "rainbow"
 require "tuile"
 
 module SamplerExample
-  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that runs a
-  # caller-supplied block on `rect=` to position its children. Most demos are
-  # plain stacks and use the box layouts instead; this is what's left for the
-  # two that aren't — a sidebar whose width is `min(16, width / 3)`, which is a
-  # cap on a proportion and so outside {Tuile::Component::Layout::Box}'s
-  # Fixed/Percent/Expand vocabulary by design.
-  class Panel < Tuile::Component::Layout::Absolute
-    def initialize(&layout_block)
-      super()
-      @layout_block = layout_block
-    end
-
-    def rect=(new_rect)
-      super
-      @layout_block&.call(rect) unless rect.empty?
-    end
-  end
+  # `color` with `by` added to each RGB channel, clamped. Tuile ships no color
+  # arithmetic; this is the app's.
+  STEP = ->(color, by) { Tuile::Color.rgb(*color.rgb.map { (_1 + by).clamp(0, 255) }) }
+
+  # `hint` is the app's token, not Tuile's: the framework carries accents for
+  # the chrome *it* paints, and the status row below is the sampler's own
+  # (`D_status_bar` — Tuile draws none). Paired in a ThemeDef so it survives an
+  # OS appearance flip, where a bare `theme=` would be replaced. Both greys
+  # quantize to :bright_black on a 16-color terminal, so the description stays
+  # dimmer than the key beside it even there.
+  #
+  # `terminal_tint` is derived: the terminal's *own* background stepped 10 per
+  # channel away from the ink — the borderless-pane tint, which only sits right
+  # when it comes from the real background. The screen re-derives it whenever
+  # the background changes; the fixed grey is for a terminal that reported none,
+  # which is the branch most users will actually see.
+  APP_THEME = Tuile::ThemeDef.new(
+    dark: Tuile::Theme::DARK.with(custom: {
+                                    hint: Tuile::Color::GREY54,
+                                    terminal_tint: ->(bg) { bg ? STEP.call(bg, 10) : Tuile::Color::GREY15 }
+                                  }),
+    light: Tuile::Theme::LIGHT.with(custom: {
+                                      hint: Tuile::Color::GREY62,
+                                      terminal_tint: ->(bg) { bg ? STEP.call(bg, -10) : Tuile::Color::GREY89 }
+                                    })
+  )
 
   # A {Tuile::Component::Layout::Vertical} that runs {#on_tick} on every frame
   # while it is on screen. The ticker is started on attach and cancelled on
@@ -46,21 +58,26 @@ module SamplerExample
       @fps = fps
     end
 
-    # @return [Proc, nil] called with no arguments on each frame.
-    attr_writer :on_tick
+    # What `on_tick` fires.
+    TickEvent = Data.define(:source) { include Tuile::Event }
+
+    # @!method on_tick
+    #   Fired once per frame while this box is attached.
+    #   @return [Tuile::Listeners]
+    listener :on_tick
 
-    def on_attached
-      @ticker = screen.event_queue.tick_fps(@fps) { @on_tick&.call }
+    def handle_attached
+      @ticker = screen.event_queue.tick_fps(@fps) { on_tick.fire(TickEvent.new(source: self)) }
     end
 
-    def on_detached
+    def handle_detached
       @ticker&.cancel
       @ticker = nil
     end
   end
 
   # A {Tuile::Component::Layout::Vertical} that claims one key for itself. An
-  # ancestor's `handle_key` is where a scope-wide binding belongs (key-dispatch
+  # ancestor's `handle_key?` is where a scope-wide binding belongs (key-dispatch
   # rung 3); the Select demo uses one to show the letter still arriving while a
   # Select has focus — the capability a ComboBox, which eats every printable
   # unconditionally, cannot offer.
@@ -70,13 +87,18 @@ module SamplerExample
       @shortcut = shortcut
     end
 
-    # @return [Proc, nil] called with no arguments when the shortcut arrives.
-    attr_writer :on_shortcut
+    # What `on_shortcut` fires.
+    ShortcutEvent = Data.define(:source) { include Tuile::Event }
 
-    def handle_key(key)
+    # @!method on_shortcut
+    #   Fired when the claimed key arrives.
+    #   @return [Tuile::Listeners]
+    listener :on_shortcut
+
+    def handle_key?(key)
       return false unless key == @shortcut
 
-      @on_shortcut&.call
+      on_shortcut.fire(ShortcutEvent.new(source: self))
       true
     end
   end
@@ -85,26 +107,38 @@ module SamplerExample
   # the chat-prompt shape, and the one that made a multi-line paste fire the
   # submit once per pasted line before Tuile drove bracketed paste. It handles
   # no paste of its own: pasted text never arrives as ENTER, so the inherited
-  # insert-at-caret is already the wanted behavior, and `on_paste` here only
-  # feeds the demo's counter.
+  # insert-at-caret is already the wanted behavior, and `on_paste_received` here
+  # only feeds the demo's counter.
   class PromptTextArea < Tuile::Component::TextArea
-    # @return [Proc, nil] called with the submitted text; the area then clears.
-    attr_accessor :on_submit
-    # @return [Proc, nil] called with the pasted text, before it is inserted.
-    attr_accessor :on_paste
+    # What `on_submit` fires.
+    SubmitEvent = Data.define(:source, :text) { include Tuile::Event }
+
+    # What `on_paste_received` fires.
+    PasteEvent = Data.define(:source, :text) { include Tuile::Event }
+
+    # @!method on_submit
+    #   Fired with the submitted text; the area then clears.
+    #   @return [Tuile::Listeners]
+    listener :on_submit
+
+    # @!method on_paste_received
+    #   Fired with the pasted text, before it is inserted. Not `on_paste`:
+    #   `handle_paste` is the override point, and a slot may not take its name.
+    #   @return [Tuile::Listeners]
+    listener :on_paste_received
 
     def handle_paste(text)
-      @on_paste&.call(text)
+      on_paste_received.fire(PasteEvent.new(source: self, text: text))
       super
     end
 
     protected
 
-    def handle_text_input_key(key)
+    def handle_text_input_key?(key)
       return super unless key == Tuile::Keys::ENTER
 
-      @on_submit&.call(text)
-      self.text = ""
+      on_submit.fire(SubmitEvent.new(source: self, text: text))
+      self.value = ""
       true
     end
   end
@@ -115,8 +149,8 @@ module SamplerExample
   # a newline with no menu up — stays the TextArea's own.
   #
   # Subclassing *is* the seam for this. A component receives keys through
-  # `handle_key`, so one that wants different keys overrides it (here its
-  # `handle_text_input_key` hook) and calls `super` for the rest, which composes
+  # `handle_key?`, so one that wants different keys overrides it (here its
+  # `handle_text_input_key?` hook) and calls `super` for the rest, which composes
   # and stacks. None of this is baked into TextArea.
   class SlashCommandTextArea < Tuile::Component::TextArea
     # @param overlay [Tuile::Component::ListDropdown] the menu to steer.
@@ -127,7 +161,7 @@ module SamplerExample
 
     protected
 
-    def handle_text_input_key(key)
+    def handle_text_input_key?(key)
       return super unless @overlay.open?
       return true if @overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
 
@@ -140,6 +174,304 @@ module SamplerExample
     end
   end
 
+  # A drawing surface answering every mouse handler, in two inks that both
+  # persist: a left-drag strokes `X`, a plain hover leaves a `.` trail behind
+  # the pointer, and a right-drag lifts marks again.
+  #
+  #      X          a diagonal drag, then one hover sweep across it
+  #       X
+  #        X
+  #         X
+  #     .....X........
+  #           X
+  #
+  # A trail never overwrites a stroke, so the picture stays a readout of which
+  # channel drew which cell — an eraser-on-hover would instead make the drawing
+  # unviewable with the pointer over it.
+  #
+  #   canvas = Canvas.new
+  #   canvas.on_report { |e| log.log(e.line) }
+  #   canvas.on_move { |e| label.text = "#{e.mouse.x},#{e.mouse.y} (#{e.moves})" }
+  #
+  # Two slots, because the traffic is two: {#on_report} carries the discrete
+  # events to a log, {#on_move} the ~84-a-second moves to one replaced row.
+  # Feeding both to a log would drown enter/exit inside 12 ms.
+  #
+  # Every gesture owes a key (`D_mouse`): the arrows move the caret, space or
+  # `x` strokes it, Delete lifts it, `c` clears. The trail, the enter/exit lines
+  # and {#on_move} need `capture_mouse: :hover` and arrive as nothing below it;
+  # the drag works from `:drag`, a single-cell stroke from `:clicks`.
+  #
+  # == Implementation details
+  # Both glyphs are ASCII on purpose: `·` is East-Asian Ambiguous, so a
+  # two-column trail cell would push every painted row past `rect.width`
+  # (`D_ambiguous_width`).
+  #
+  # It paints every cell of its rect itself, one {Tuile::Canvas#set_text}
+  # per run of like cells, and so skips `super` in {#repaint} — whose
+  # auto-clear blanks the whole rect, which would re-emit every cell this widget
+  # is about to paint over anyway. Repainting whole on every move still costs
+  # one cell on the wire, since a cell dirties only on a real change.
+  #
+  # Marks are keyed by rect-local {Tuile::Point}: ink beyond a narrowed rect
+  # stops painting and comes back when the rect grows again.
+  class Canvas < Tuile::Component
+    # @return [String] the drag/keyboard ink.
+    STROKE = "X"
+    # @return [String] the hover ink.
+    TRAIL = "."
+
+    # Which ink each button drags — `nil` erases. The middle button is absent:
+    # a press this component declines bubbles on to the window around it.
+    # @return [Hash{Symbol => String, nil}]
+    DRAG_INK = { left: STROKE, right: nil }.freeze
+
+    # What `on_report` fires.
+    ReportEvent = Data.define(:source, :line) { include Tuile::Event }
+
+    # What `on_move` fires.
+    MoveEvent = Data.define(:source, :mouse, :moves) { include Tuile::Event }
+
+    # @!method on_report
+    #   Fired with one line of commentary per discrete event.
+    #   @return [Tuile::Listeners]
+    listener :on_report
+
+    # @!method on_move
+    #   Fired on every move and every drag, with the {Tuile::Mouse::Event} as
+    #   `mouse` — not `event`, which would read as the event's event — and the
+    #   number of moves so far.
+    #   @return [Tuile::Listeners]
+    listener :on_move
+
+    # @return [Tuile::Point] the keyboard caret, in rect-local coordinates.
+    attr_reader :caret
+
+    # The marks, keyed by rect-local {Tuile::Point} — read-only in practice:
+    # writing one behind {#paint}'s back skips the `invalidate`.
+    # @return [Hash{Tuile::Point => String}]
+    attr_reader :ink
+
+    def initialize
+      super
+      @ink = {}
+      @caret = Tuile::Point.new(0, 0)
+      @moves = 0
+      @drag_ink = nil
+      @drag_outside = false
+      bg.default_color = Tuile::ComponentBackground::INPUT_WELL
+    end
+
+    def focusable? = true
+
+    def tab_stop? = true
+
+    # The caret is already rect-local, and so is what a cursor position means —
+    # {Tuile::Screen#cursor_position} puts it on screen.
+    # @return [Tuile::Point, nil]
+    def cursor_position
+      return nil if rect.empty?
+
+      @caret
+    end
+
+    # Clamps the caret into the new rect, so a shrink cannot strand it — and
+    # with it the hardware cursor — outside what this widget paints.
+    # @param old_rect [Tuile::Rect]
+    def handle_rect_changed(old_rect)
+      super
+      @caret = Tuile::Point.new(@caret.x.clamp(0, [rect.width - 1, 0].max),
+                                @caret.y.clamp(0, [rect.height - 1, 0].max))
+    end
+
+    # @return [void]
+    def repaint(canvas)
+      return if rect.empty?
+
+      # The clear is what a self-painter opts out of; the cascade never is
+      # (`D_repaint_cascade`), leaf or not.
+      invalidate_children
+      trail_color = screen.theme[:hint]
+      rect.height.times { |row| draw_row(canvas, row, trail_color) }
+    end
+
+    # @param event [Tuile::Mouse::DownEvent]
+    # @return [Boolean]
+    def handle_mouse_down?(event)
+      unless DRAG_INK.key?(event.button)
+        report("down #{event.button} at #{event.x},#{event.y} — declined, bubbles to the window")
+        return false
+      end
+
+      report("down #{event.button} at #{event.x},#{event.y} — claimed, grab held")
+      @drag_ink = DRAG_INK.fetch(event.button)
+      @drag_outside = false
+      mark(cell_at(event))
+      true
+    end
+
+    # @param event [Tuile::Mouse::DragEvent]
+    # @return [void]
+    def handle_mouse_drag(event)
+      super
+      cell = cell_at(event)
+      if @drag_outside != cell.nil?
+        @drag_outside = cell.nil?
+        report(@drag_outside ? "drag left the canvas — the grab still delivers" : "drag back inside")
+      end
+      mark(cell)
+      report_move(event)
+    end
+
+    # @param event [Tuile::Mouse::UpEvent]
+    # @return [void]
+    def handle_mouse_up(event)
+      super
+      report("up at #{event.x},#{event.y} — grab released")
+      @drag_ink = nil
+    end
+
+    # @param event [Tuile::Mouse::MoveEvent]
+    # @return [Boolean]
+    def handle_mouse_move?(event)
+      cell = cell_at(event)
+      paint(cell, TRAIL) if cell && @ink[cell].nil?
+      report_move(event)
+      true
+    end
+
+    # @return [void]
+    def handle_mouse_enter
+      super
+      report("enter")
+    end
+
+    # @return [void]
+    def handle_mouse_exit
+      super
+      report("exit")
+    end
+
+    # Declines the notch — nothing here scrolls — which is what lets it bubble
+    # on to an ancestor that does.
+    # @param event [Tuile::Mouse::ScrollEvent]
+    # @return [Boolean] always false.
+    def handle_mouse_scroll?(event)
+      report("wheel #{event.direction} — declined, bubbles on")
+      false
+    end
+
+    # @param key [String]
+    # @return [Boolean]
+    def handle_key?(key)
+      case key
+      when Tuile::Keys::UP_ARROW then move_caret(0, -1)
+      when Tuile::Keys::DOWN_ARROW then move_caret(0, 1)
+      when Tuile::Keys::LEFT_ARROW then move_caret(-1, 0)
+      when Tuile::Keys::RIGHT_ARROW then move_caret(1, 0)
+      when " ", "x" then stroke_caret(STROKE)
+      when Tuile::Keys::DELETE, *Tuile::Keys::BACKSPACES then stroke_caret(nil)
+      when "c" then clear_marks
+      else return super
+      end
+      true
+    end
+
+    private
+
+    # One row, as runs of like cells: every cell is painted exactly once, so
+    # none is blanked and then painted over (`D_progress_bar`). The canvas
+    # paints in the same rect-local coordinates the marks are keyed by, so a
+    # run goes straight to `set_text` with no offset.
+    # @param row [Integer] rect-local row.
+    # @param trail_color [Tuile::Color]
+    # @return [void]
+    def draw_row(canvas, row, trail_color)
+      column = 0
+      while column < rect.width
+        glyph = @ink[Tuile::Point.new(column, row)]
+        run = 1
+        run += 1 while column + run < rect.width && @ink[Tuile::Point.new(column + run, row)] == glyph
+        text = (glyph || " ") * run
+        styled = glyph == TRAIL ? Tuile::StyledString.styled(text, fg: trail_color) : Tuile::StyledString.plain(text)
+        canvas.set_text(column, row, styled)
+        column += run
+      end
+    end
+
+    # The event's cell, or nil when it lands outside — which a grabbed
+    # {Tuile::Mouse::DragEvent} routinely does. A mouse event already arrives in
+    # this component's own coordinates, so there is nothing to subtract; the
+    # bounds test is the whole job.
+    # @param event [Tuile::Mouse::Event]
+    # @return [Tuile::Point, nil]
+    def cell_at(event)
+      return nil unless (0...rect.width).cover?(event.x) && (0...rect.height).cover?(event.y)
+
+      Tuile::Point.new(event.x, event.y)
+    end
+
+    # Lays the dragged ink at `cell` and takes the caret with it, so a stroke
+    # can be continued from the keyboard. Outside the rect (`nil`) it is a
+    # no-op, which is a grabbed drag's normal case.
+    # @param cell [Tuile::Point, nil] rect-local.
+    # @return [void]
+    def mark(cell)
+      return if cell.nil?
+
+      paint(cell, @drag_ink)
+      @caret = cell
+    end
+
+    # @param cell [Tuile::Point] rect-local.
+    # @param ink [String, nil] nil lifts the mark.
+    # @return [void]
+    def paint(cell, ink)
+      return if @ink[cell] == ink
+
+      ink.nil? ? @ink.delete(cell) : @ink.store(cell, ink)
+      invalidate
+    end
+
+    # @param ink [String, nil]
+    # @return [void]
+    def stroke_caret(ink)
+      paint(@caret, ink)
+      report("#{ink || "lift"} at #{@caret.x},#{@caret.y} — from the keyboard")
+    end
+
+    # @param columns [Integer]
+    # @param rows [Integer]
+    # @return [void]
+    def move_caret(columns, rows)
+      return if rect.empty?
+
+      @caret = Tuile::Point.new((@caret.x + columns).clamp(0, rect.width - 1),
+                                (@caret.y + rows).clamp(0, rect.height - 1))
+      invalidate # the hardware cursor is placed from #cursor_position at flush
+    end
+
+    # @return [void]
+    def clear_marks
+      return if @ink.empty?
+
+      @ink.clear
+      report("cleared")
+      invalidate
+    end
+
+    # @param line [String]
+    # @return [void]
+    def report(line) = on_report.fire(ReportEvent.new(source: self, line: line))
+
+    # @param event [Tuile::Mouse::Event]
+    # @return [void]
+    def report_move(event)
+      @moves += 1
+      on_move.fire(MoveEvent.new(source: self, mouse: event, moves: @moves))
+    end
+  end
+
   # Top-level sampler component: a shell row across the top — a
   # {Tuile::Component::MenuBar} of the demos, grouped, and a
   # {Tuile::Component::ComboBox} jump box at its right end — over one demo
@@ -166,13 +498,14 @@ module SamplerExample
 
     # The bottom row. Tuile draws no status bar and reserves no row
     # (`D_status_bar`) — this one is the sampler's own, kept current by
-    # {Tuile::Screen#on_focus_changed=}. Naming the focused component makes Tab
+    # {Tuile::Screen#on_focus_changed}. Naming the focused component makes Tab
     # traversal visible as you walk a pane, which no per-pane label shows.
     # @return [void]
     def refresh_status
       focused = screen.focused
       name = focused ? focused.class.name.sub("Tuile::Component::", "") : "(none)"
-      @status.text = "q #{screen.theme.hint("quit")}  ⇥ #{screen.theme.hint(name)}"
+      t = screen.theme
+      @status.text = "q #{t.fg(:hint, "quit")}  ⇥ #{t.fg(:hint, name)}"
     end
 
     # Chrome for a demo pane: a blank row top and bottom, two columns either
@@ -208,9 +541,11 @@ module SamplerExample
     # as a live index of the catalogue and any drift between the two is visible.
     #
     # Mnemonics are *hand-picked*: {Tuile::Component::MenuBar#add_item} raises on
-    # a duplicate among siblings, and five leaves therefore answer to a letter
+    # a duplicate among siblings, and seven leaves therefore answer to a letter
     # other than their initial (Past`e`, Checkbox`G`roup, C`o`mboBox,
-    # Pic`k`erWindow, S`l`ash menu) — the underline shows which. No item may use
+    # Pic`k`erWindow, S`l`ash menu, DateTi`m`eField, F`o`rmLayout) — the
+    # underline shows which.
+    # No item may use
     # `q`: quit is the unhandled-key fallback, so a `q` on the live level would
     # swallow it while the bar has focus.
     MENUS = [
@@ -233,6 +568,7 @@ module SamplerExample
                             Entry.new("BigDecimalField", :build_big_decimal_field, "b"),
                             Entry.new("DateField", :build_date_field, "d"),
                             Entry.new("TimeField", :build_time_field, "t"),
+                            Entry.new("DateTimeField", :build_date_time_field, "m"),
                             Entry.new("Bad input", :build_bad_input, "a"),
                             Entry.new("Validation", :build_validation, "v")
                           ]),
@@ -246,7 +582,7 @@ module SamplerExample
                           ])
                ]),
       # One entry, so it is the item and not a menu — a top-level leaf on the
-      # strip is a button, which nothing else here demos.
+      # strip is a button rather than a drop-down.
       Entry.new("Button", :build_buttons, "b"),
       Menu.new("Overlay", "o", [
                  Entry.new("Popup", :build_popup_launcher, "p"),
@@ -257,6 +593,8 @@ module SamplerExample
                  Entry.new("LogWindow", :build_log_window, "l")
                ]),
       Menu.new("Shell", "h", [
+                 Entry.new("FormLayout", :build_form_layout, "o"),
+                 Entry.new("Scroller", :build_scroller, "s"),
                  Entry.new("TabSheet", :build_tab_sheet, "t"),
                  Entry.new("MenuBar", :build_menu_bar, "m"),
                  Entry.new("Narrow strips", :build_narrow_strips, "n"),
@@ -264,7 +602,10 @@ module SamplerExample
                  Entry.new("Background", :build_background, "b"),
                  Entry.new("Visibility", :build_visibility, "v"),
                  Entry.new("Focus & Tab", :build_focus_demo, "f")
-               ])
+               ]),
+      # The one demo needing a tracking level above the default, which is why
+      # the runner asks for `capture_mouse: :hover` for the whole app.
+      Entry.new("Mouse", :build_mouse_demo, "m")
     ].freeze
 
     # Every {Entry} in strip order — what the jump box offers.
@@ -308,7 +649,7 @@ module SamplerExample
     def build_jump_box
       combo = Tuile::Component::ComboBox.new(items: ENTRIES)
       combo.item_label = :caption.to_proc
-      combo.on_value_change = ->(entry) { load_entry(entry) if entry }
+      combo.on_value_change { |e| load_entry(e.value) if e.value }
       combo
     end
 
@@ -363,7 +704,7 @@ module SamplerExample
                     "Home/End jump to row start/end; Up/Down at the first/last row jumps to text start/end.\n" \
                     "Overflowing rows scroll vertically to keep the caret visible."
       area = Tuile::Component::TextArea.new
-      area.text = "The quick brown fox jumps over the lazy dog. " \
+      area.value = "The quick brown fox jumps over the lazy dog. " \
                   "Edit me — the text wraps to the area's width and scrolls vertically " \
                   "once the cursor leaves the visible rows."
       form do |f|
@@ -382,7 +723,7 @@ module SamplerExample
       items = %w[Ruby Python JavaScript TypeScript Rust Go Elixir Crystal Haskell Kotlin Swift Zig]
       combo = Tuile::Component::ComboBox.new(items: items)
       status = Tuile::Component::Label.new.tap { _1.text = "(nothing selected)" }
-      combo.on_value_change = ->(value) { status.text = "Selected: #{value}" }
+      combo.on_value_change { |e| status.text = "Selected: #{e.value}" }
       form do |f|
         f.add(prompt, Fixed[3])
         # A cross constraint clamps to the pane, so this is 30 columns or fewer.
@@ -423,14 +764,14 @@ module SamplerExample
         status.text = "level: #{level.value.inspect}  endings: #{endings.value&.label.inspect}"
       end
       update.call
-      [level, endings].each { _1.on_value_change = ->(_v) { update.call } }
+      [level, endings].each { _1.on_value_change { update.call } }
 
       pane = ShortcutBox.new("r", spacing: 1, padding: FORM_PADDING)
       pane.add(prompt, Fixed[3])
       pane.add(labelled("Log level", level), Fixed[1])
       pane.add(labelled("Line endings", endings), Fixed[1])
       pane.add(status, Fixed[1])
-      pane.on_shortcut = lambda do
+      pane.on_shortcut do
         level.value = "warn"
         endings.value = nil
         update.call
@@ -450,7 +791,7 @@ module SamplerExample
       # Set on the composed field, not on the TextField inside it.
       field.placeholder = "1-65535"
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      field.on_value_change { |e| status.text = "e.value: #{e.value.inspect}" }
       form do |f|
         f.add(prompt, Fixed[2])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -468,7 +809,7 @@ module SamplerExample
                     "Up/Down step the value by one. Watch the value while you type '1.5'."
       field = Tuile::Component::FloatField.new
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = "value: #{value.inspect}" }
+      field.on_value_change { |e| status.text = "e.value: #{e.value.inspect}" }
       form do |f|
         f.add(prompt, Fixed[2])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -487,7 +828,7 @@ module SamplerExample
                     "what you typed (19.90 keeps its zero)."
       field = Tuile::Component::BigDecimalField.new
       status = Tuile::Component::Label.new.tap { _1.text = "value: nil" }
-      field.on_value_change = ->(value) { status.text = triple_report(value) }
+      field.on_value_change { |e| status.text = triple_report(e.value) }
       form do |f|
         f.add(prompt, Fixed[3])
         f.add(field, Fixed[1], cross: Fixed[20])
@@ -517,7 +858,7 @@ module SamplerExample
       # calendar reform, which is noise next to the one fact this row is for.
       report = -> { status.text = "value: #{field.value&.to_s || "nil"}    bad_input?: #{field.bad_input?}" }
       report.call
-      field.on_value_change = ->(_value) { report.call }
+      field.on_value_change { report.call }
       ask = Tuile::Component::Button.new("Ask again") { report.call }
       form do |f|
         f.add(prompt, Fixed[4])
@@ -550,7 +891,7 @@ module SamplerExample
                       "seconds: #{seconds.value&.strftime("%H:%M:%S") || "nil"} (#{seconds.formats.first})"
       end
       report.call
-      [minutes, seconds].each { _1.on_value_change = ->(_value) { report.call } }
+      [minutes, seconds].each { _1.on_value_change { report.call } }
       form do |f|
         f.add(prompt, Fixed[4])
         f.add(labelled("Minute stride", minutes, field_width: 12), Fixed[1], cross: Fixed[30])
@@ -568,6 +909,39 @@ module SamplerExample
       end
     end
 
+    # DateTimeField: the ink rule, which neither half can show alone. Leave the
+    # time empty and the *whole* widget reddens — half-filled is a fault no
+    # single half committed — where garbage in the date half reddens that half
+    # by itself. Both only on the way out, which is why pressing Enter first
+    # visibly changes nothing.
+    #
+    # The echo row carries the value and Save the verdict, the division
+    # `D_bad_input` draws: the notice is a push, fired when a half commits;
+    # `bad_input?` is a pull, read at the click. The Saved alert spells the
+    # value out with the `+00:00` the halves cannot fill in — `D_time_field`'s
+    # epoch cost, visible rather than hidden.
+    def build_date_time_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, type 2026-09-14, leave the time empty — then press Enter: nothing reddens.\n" \
+                    "Tab away and both halves redden at once: half-filled is the composite's own fault.\n" \
+                    "Now type 2026-99-99 in the date half instead — it reddens alone, the time half stays clean.\n" \
+                    "Save asks bad_input? at the click and names whichever fault it found."
+      field = Tuile::Component::DateTimeField.new
+      status = Tuile::Component::Label.new
+      # strftime, not inspect: DateTime#inspect spells out the Julian day, noise
+      # next to the one fact this row carries.
+      report = -> { status.text = "value: #{field.value&.strftime("%Y-%m-%d %H:%M") || "nil"}" }
+      report.call
+      field.on_value_change { report.call }
+      save = Tuile::Component::Button.new("Save") { save_form("Starts at" => field) }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(labelled("Starts at", field, field_width: 20), Fixed[1], cross: Fixed[36])
+        f.add(status, Fixed[1])
+        f.add(save, Fixed[1], cross: Fixed[button_width(save)])
+      end
+    end
+
     # HasBadInput: the one fact on_value_change cannot carry. Type a lone "-"
     # and watch the echo row stay silent — the value was nil before and is nil
     # after, so there is no diff to report — while Save, which asks bad_input?
@@ -582,8 +956,8 @@ module SamplerExample
       amount = Tuile::Component::IntegerField.new.tap { _1.id = :amount }
       rate = Tuile::Component::FloatField.new.tap { _1.id = :rate }
       echo = Tuile::Component::Label.new.tap { _1.text = "on_value_change: (nothing yet)" }
-      amount.on_value_change = ->(v) { echo.text = "on_value_change: amount = #{v.inspect}" }
-      rate.on_value_change = ->(v) { echo.text = "on_value_change: rate = #{v.inspect}" }
+      amount.on_value_change { |e| echo.text = "on_value_change: amount = #{e.value.inspect}" }
+      rate.on_value_change { |e| echo.text = "on_value_change: rate = #{e.value.inspect}" }
       save = Tuile::Component::Button.new("Save") { save_form("Amount" => amount, "Rate" => rate) }
       save.id = :save
       rows = group do |g|
@@ -629,7 +1003,7 @@ module SamplerExample
     #   the field's listener keeps current.
     def validated_row(caption, field)
       error = Tuile::Component::Label.new
-      field.on_error_message_change = ->(msg) { error.text = msg || Tuile::StyledString::EMPTY }
+      field.on_error_message_change { |e| error.text = e.error_message || Tuile::StyledString::EMPTY }
       row do |r|
         r.add(Tuile::Component::Label.new(caption), Fixed[14])
         r.add(field, Fixed[22])
@@ -696,11 +1070,11 @@ module SamplerExample
       user = Tuile::Component::TextField.new
       password = Tuile::Component::PasswordField.new
       reveal = Tuile::Component::Checkbox.new("Show password")
-      reveal.on_value_change = ->(on) { password.revealed = on }
+      reveal.on_value_change { |e| password.revealed = e.value }
       status = Tuile::Component::Label.new
       refresh = -> { status.text = "user: #{user.text.inspect}  password: #{password.value.length} chars" }
       refresh.call
-      [user, password].each { _1.on_change = ->(_) { refresh.call } }
+      [user, password].each { _1.on_value_change { refresh.call } }
       form do |f|
         f.add(prompt, Fixed[4])
         f.add([user, password], Fixed[1], cross: Fixed[30]) # one constraint, both fields
@@ -715,7 +1089,7 @@ module SamplerExample
     # A ListDropdown driven from a TextArea — the same shape {ComboBox} and
     # {Select} use, but wired by app code onto a field that knows nothing about
     # it. Focus (and the caret) stays in the TextArea the whole time: an
-    # `on_change` listener refills the menu, and {SlashCommandTextArea} hands
+    # `on_value_change` listener refills the menu, and {SlashCommandTextArea} hands
     # movement keys to `#move` and Enter to `#choose` while it is open.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
@@ -733,15 +1107,14 @@ module SamplerExample
           overlay.close if overlay.open?
         else
           overlay.items = matches
-          overlay.open unless overlay.open?
           # Width is the driver's call, never the dropdown's: measure the
           # commands rather than inherit the full-width TextArea's columns.
-          overlay.anchor_to(area.rect, rows: matches.size, width: slash_menu_width(matches))
+          overlay.anchor_to(area, width: slash_menu_width(matches))
         end
       end
 
-      area.on_change = ->(_text) { refill.call }
-      overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
+      area.on_value_change { refill.call }
+      overlay.list.on_item_chosen { |e| accept_slash_command(area, e.item.to_s) }
 
       form do |f|
         f.add(prompt, Fixed[4])
@@ -767,14 +1140,14 @@ module SamplerExample
       refresh = lambda do
         stats.text = "submits: #{submits}   pastes: #{pastes}   rows in draft: #{area.row_count}"
       end
-      area.on_change = ->(_text) { refresh.call }
-      area.on_paste = lambda do |text|
+      area.on_value_change { refresh.call }
+      area.on_paste_received do |e|
         pastes += 1
-        log.add_line(Rainbow("pasted #{text.lines.size} line(s), #{text.length} chars").cyan)
+        log.add_line(Rainbow("pasted #{e.text.lines.size} line(s), #{e.text.length} chars").cyan)
       end
-      area.on_submit = lambda do |text|
+      area.on_submit do |e|
         submits += 1
-        log.add_line(Rainbow("submitted: #{text.inspect}").green)
+        log.add_line(Rainbow("submitted: #{e.text.inspect}").green)
       end
       refresh.call
 
@@ -860,7 +1233,7 @@ module SamplerExample
         status.text = "checked: #{on.empty? ? "(none)" : on.join(", ")}"
       end
       refresh.call
-      boxes.each { _1.on_value_change = ->(_) { refresh.call } }
+      boxes.each { _1.on_value_change { refresh.call } }
       # The boxes sit flush against each other while the form keeps a blank row
       # around the block: a spacing-0 group nested in the spacing-1 form, rather
       # than a per-child gap the framework deliberately doesn't offer.
@@ -891,7 +1264,7 @@ module SamplerExample
         conditional.each { _1.visible = business.checked? }
         status.text = "visible fields: #{business.checked? ? 4 : 2}"
       end
-      business.on_value_change = ->(_) { apply.call }
+      business.on_value_change { apply.call }
       # The rows sit flush; the form keeps its blank row around the block.
       rows = group do |g|
         g.add(labelled("Name", Tuile::Component::TextField.new), Fixed[1])
@@ -945,7 +1318,7 @@ module SamplerExample
     # *items* — LogLevel objects, not their labels — so the filter below is plain
     # set membership, no lookup table. Rows come from `item_label`, which may
     # return styled text (these colors are inherent to the data, not theme
-    # accents, so they need no on_theme_changed hook).
+    # accents, so they need no handle_theme_changed hook).
     def build_checkbox_group
       prompt = Tuile::Component::Label.new
       # Kept under 48 columns a line, so an 80-column terminal shows it whole.
@@ -974,16 +1347,13 @@ module SamplerExample
         status.text = "value: {#{shown.join(", ")}} — #{log.items.size} of #{entries.size} lines"
       end
       refresh.call
-      group.on_value_change = ->(_set) { refresh.call }
+      group.on_value_change { refresh.call }
 
-      # The body keeps a rect-callback {Panel}: its sidebar is `min(16, width/3)`
-      # — a cap on a proportion, which Fixed/Percent/Expand can't say. The stack
-      # around it is a box, so only the part that needs arithmetic has any.
-      body = panel(group, log) do |r|
-        group_width = [16, r.width / 3].min
-        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [LOG_LEVELS.size, r.height].min)
-        log.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
-                                   [r.width - group_width - 2, 4].max, r.height)
+      # The sidebar is a third of the row but never over 16 columns — a capped
+      # proportion, which is a Percent with a clamp.
+      body = row do |r|
+        r.add(group, Percent[33].clamp(..16), cross: Fixed[LOG_LEVELS.size])
+        r.add(log, Expand[1])
       end
       form do |f|
         f.add(prompt, Fixed[4])
@@ -1014,7 +1384,7 @@ module SamplerExample
     SAMPLE_FILES = [
       SampleFile.new("AGENTS.md", 31_402, "2026-07-30"),
       SampleFile.new("CHANGELOG.md", 4118, "2026-07-05"),
-      SampleFile.new("DECISIONS.md", 48_990, "2026-07-31"),
+      SampleFile.new("design/decisions.md", 48_990, "2026-07-31"),
       SampleFile.new("Gemfile", 312, "2026-06-18"),
       SampleFile.new("README.md", 9674, "2026-07-12"),
       SampleFile.new("Rakefile", 2118, "2026-06-18"),
@@ -1058,20 +1428,17 @@ module SamplerExample
         update_status.call
       end
       resort.call
-      group.on_value_change = ->(_order) { resort.call }
+      group.on_value_change { resort.call }
       # `list` is the composed List, which is where the cursor lives.
       # Watching it is what makes the chrome/value split visible above.
-      group.list.on_cursor_changed = ->(_idx, _line) { update_status.call }
-
-      # Side-by-side body on a rect-callback {Panel}, as in the CheckboxGroup
-      # demo — the sidebar width is a capped proportion, not a constraint.
-      body = panel(group, files) do |r|
-        # List pads a column either side of a row, so a label needs
-        # `width - 2`; the file rows lose one more to their scrollbar.
-        group_width = [14, r.width / 3].min
-        group.rect = Tuile::Rect.new(r.left, r.top, group_width, [SORT_ORDERS.size, r.height].min)
-        files.rect = Tuile::Rect.new(r.left + group_width + 2, r.top,
-                                     [r.width - group_width - 2, 4].max, r.height)
+      group.list.on_cursor_changed { update_status.call }
+
+      # Side-by-side body with a capped sidebar, as in the CheckboxGroup demo.
+      # List pads a column either side of a row, so a label needs `width - 2`;
+      # the file rows lose one more to their scrollbar.
+      body = row do |r|
+        r.add(group, Percent[33].clamp(..14), cross: Fixed[SORT_ORDERS.size])
+        r.add(files, Expand[1])
       end
       form do |f|
         f.add(prompt, Fixed[4])
@@ -1138,7 +1505,7 @@ module SamplerExample
       pane.add(prompt, Fixed[4])
       pane.add(determinate, Fixed[2])
       pane.add(indeterminate, Fixed[3])
-      pane.on_tick = lambda do
+      pane.on_tick do
         done = done < PROGRESS_TOTAL ? done + 1 : 0
         bar.value = done
         refresh.call
@@ -1156,6 +1523,7 @@ module SamplerExample
     # of hard-coded ANSI / 256-palette / RGB colors that stay put across flips.
     BG_CHOICES = [
       BgChoice.new("None (terminal default)", nil),
+      BgChoice.new("Terminal background, stepped (derived)", Tuile::Theme.ref(:terminal_tint)),
       BgChoice.new("Theme: input well", Tuile::Theme.ref(:input_bg_color)),
       BgChoice.new("Theme: active", Tuile::Theme.ref(:active_bg_color)),
       BgChoice.new("Theme: active border", Tuile::Theme.ref(:active_border_color)),
@@ -1169,21 +1537,6 @@ module SamplerExample
       BgChoice.new("Hot pink (RGB)", Tuile::Color.rgb(120, 20, 70))
     ].freeze
 
-    # The one choice that can't be a constant: the terminal's *own* background
-    # stepped +10 per channel — the borderless-pane tint, which only sits right
-    # when it's derived from the real background. Nil on a terminal that
-    # reported none, which is the branch most users will actually see.
-    def terminal_tint_choice
-      bg = Tuile::Screen.instance.background_color
-      return BgChoice.new("Terminal background — none reported", nil) if bg.nil?
-
-      BgChoice.new("Terminal background +10 (derived)",
-                   Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }))
-    end
-
-    # @param derived [BgChoice] the live terminal-derived tint, offered second.
-    def bg_choices(derived) = [BG_CHOICES.first, derived, *BG_CHOICES[1..]]
-
     def build_background
       intro = Tuile::Component::Label.new
       intro.text = "bg_color tints a component and every descendant that doesn't set its own.\n" \
@@ -1194,7 +1547,7 @@ module SamplerExample
       list.cursor = Tuile::Component::List::Cursor.new
       list.lines = (1..12).map { |i| "List row #{i}" }
       field = Tuile::Component::TextField.new
-      field.text = "TextField keeps its own background"
+      field.value = "TextField keeps its own background"
 
       # A borderless sub-box holding the list + field; it inherits the tint too.
       box = Tuile::Component::Layout::Vertical.new(spacing: 1)
@@ -1204,34 +1557,81 @@ module SamplerExample
       # A ComboBox over BG_CHOICES swaps the whole panel's bg_color on commit, so
       # the tint flows down to every descendant without its own background — the
       # label and the list — while the input widgets (the combo, the field) keep
-      # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook;
-      # the hard-coded Colors are fixed by design, so no on_theme_changed here.
+      # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook —
+      # the derived terminal tint too, re-derived when the background changes —
+      # and the hard-coded Colors are fixed by design, so no handle_theme_changed.
       outer = nil
-      derived = terminal_tint_choice
-      combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
+      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
       combo.item_label = :label.to_proc
-      combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
+      combo.on_value_change { |e| outer.bg_color = e.value.color }
 
       outer = form do |f|
         f.add(intro, Fixed[3])
         f.add(combo, Fixed[1], cross: Fixed[40])
         f.add(box, Expand[1])
       end
-      # The derived tint is the one pick whose *color* moves under it: a flip
-      # re-probes the terminal, so rebuild the choice and re-apply it if it is
-      # the current one. Expect it to correct itself a frame late — the flip
-      # report carries no RGB, so this hook runs once on the old background and
-      # again when the re-probe answers.
-      outer.on_theme_changed = lambda do
-        was_derived = combo.value.equal?(derived)
-        derived = terminal_tint_choice
-        combo.items = bg_choices(derived)
-        combo.value = derived if was_derived
-      end
       combo.value = BG_CHOICES.first # show "None" as the resting selection
       outer
     end
 
+    # FormLayout: hand it fields and captions, and it stacks the FormItems it
+    # builds. No binder here — the two name fields validate themselves from
+    # their own `on_value_change`, and `error_message=` is what puts the text
+    # in the item's message row. That row is also the gap, so a field going
+    # invalid while you type into the one below it moves nothing.
+    def build_form_layout
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab into a name field, type a letter, then erase it: the message row under it\n" \
+                    "fills and the well goes red, and nothing below moves. The ∙ beside a caption\n" \
+                    "is the required marker — chrome, not a rule; the listener is the rule."
+      fields = Tuile::Component::FormLayout.new
+      first = Tuile::Component::TextField.new
+      surname = Tuile::Component::TextField.new
+      [first, surname].each do |field|
+        field.on_value_change { |e| e.source.error_message = e.value.empty? ? "Must not be blank" : nil }
+      end
+      fields.add(first, caption: "First name", required: true)
+      fields.add(surname, caption: "Surname", required: true)
+      fields.add(Tuile::Component::DateField.new, caption: "Date of birth")
+      form do |f|
+        f.add(prompt, Fixed[3])
+        f.add(fields, Expand[1], cross: Fixed[FORM_WIDTH])
+      end
+    end
+
+    # Wide enough for the longest message row below a field.
+    FORM_WIDTH = 30
+
+    # A form taller than its viewport. Every field starts empty, hence
+    # invalid, so each message row is filled and visibly scrolls in with it.
+    def build_scroller
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab down the form: the view follows focus, caption and message included, and\n" \
+                    "the wheel scrolls it too. The Scroller claims no keys — ↑↓ stay the fields'."
+      fields = Tuile::Component::FormLayout.new
+      ["First name", "Surname", "Email", "Phone", "Street", "City", "Postcode"].each do |caption|
+        fields.add(non_empty(Tuile::Component::TextField.new), caption:, required: true)
+      end
+      fields.add(non_empty(Tuile::Component::DateField.new), caption: "Date of birth", required: true)
+      # Nothing measures (`D_scroller`): eight items, three rows each.
+      scroller = Tuile::Component::Scroller.new(fields, content_rows: 8 * 3)
+      form do |f|
+        f.add(prompt, Fixed[2])
+        f.add(scroller, Fixed[10], cross: Fixed[FORM_WIDTH + 2])
+      end
+    end
+
+    # Validates `field` as non-empty now and on every change, setting *or
+    # clearing* the verdict each time, as {Tuile::Component::HasValidation} asks.
+    # @param field [Tuile::Component]
+    # @return [Tuile::Component] `field`.
+    def non_empty(field)
+      validate = -> { field.error_message = field.empty? ? "Can not be empty" : nil }
+      field.on_value_change(&validate)
+      validate.call
+      field
+    end
+
     # Horizontal splitting a row between two equal Expand shares. Resize the
     # terminal to watch it recompute: on an odd width the spare column goes to
     # the left pane, since the remainder is handed to the earliest Expand first.
@@ -1279,7 +1679,7 @@ module SamplerExample
                     "so they bubble past the strip."
 
       field = Tuile::Component::TextField.new
-      field.text = "type here"
+      field.value = "type here"
       checkbox = Tuile::Component::Checkbox.new("Remember me", value: true)
       list = Tuile::Component::List.new
       list.cursor = Tuile::Component::List::Cursor.new
@@ -1301,7 +1701,7 @@ module SamplerExample
                       "List row #{list.cursor.position}  ·  Prose row #{view.scroll_top_row}"
       end
       report.call
-      sheet.on_tab_selected = ->(_index, _tab) { report.call }
+      sheet.on_tab_selected { report.call }
 
       form do |f|
         f.add(prompt, Fixed[3])
@@ -1376,7 +1776,7 @@ module SamplerExample
                       "(#{narrow.selected_index + 1} of #{narrow.tabs.size})"
       end
       report.call
-      narrow.on_tab_selected = ->(_index, _tab) { report.call }
+      narrow.on_tab_selected { report.call }
 
       bar = Tuile::Component::MenuBar.new
       %w[File Edit View Window Help].each do |caption|
@@ -1467,7 +1867,7 @@ module SamplerExample
           dialog.button("Save")    { report.call("saved") }
           dialog.button("Discard") { report.call("discarded") }
           dialog.button("Cancel")
-          dialog.on_dismiss = -> { report.call("stayed put") }
+          dialog.on_dismiss { report.call("stayed put") }
           dialog.open
         end,
         Tuile::Component::Button.new("Long") do
@@ -1475,7 +1875,7 @@ module SamplerExample
           dialog.message = (1..40).map { "#{_1}. Clause #{_1} of the agreement, spelled out in full." }.join("\n")
           dialog.button("Accept")  { report.call("accepted the terms") }
           dialog.button("Decline") { report.call("declined the terms") }
-          dialog.on_dismiss = -> { report.call("left the terms unanswered") }
+          dialog.on_dismiss { report.call("left the terms unanswered") }
           dialog.open
         end
       ]
@@ -1543,9 +1943,14 @@ module SamplerExample
         "PickerWindow asks the user to pick one option by a single keystroke.",
         "Open PickerWindow"
       ) do
+        # Captions paint in the terminal's own foreground — the picker
+        # recommends no color of its own. Styling one is the app's call, and
+        # per option: a caption may be a String, an ANSI-coded String (what
+        # `theme.fg` hands back) or a StyledString.
         Tuile::Component::PickerWindow.open(
           "Pick a fruit",
-          [%w[a Apple], %w[b Banana], %w[c Cherry]]
+          [%w[a Apple], %w[b Banana],
+           ["c", "Cherry #{screen.theme.fg(:hint, "(in season)")}"]]
         ) { |key| Tuile.logger.info("Picked: #{key}") }
       end
     end
@@ -1578,14 +1983,33 @@ module SamplerExample
       end
     end
 
-    # --- Helpers -----------------------------------------------------------
-
-    def panel(*children, &layout_block)
-      p = Panel.new(&layout_block)
-      p.add(children)
-      p
+    def build_mouse_demo
+      intro = Tuile::Component::Label.new
+      intro.text = "Drag on the canvas to draw X; right-drag erases; just hovering leaves a dim\n" \
+                   "trail. Arrows move the caret, space or x strokes it, Delete lifts it, c clears.\n" \
+                   "Discrete events go to the log; the row below is the live pointer."
+      canvas = Canvas.new
+      pointer = Tuile::Component::Label.new
+      pointer.text = "pointer: (move over the canvas)"
+      log = Tuile::Component::LogWindow.new("Events")
+      canvas.on_report { |e| log.log(e.line) }
+      canvas.on_move do |e|
+        kind = e.mouse.is_a?(Tuile::Mouse::DragEvent) ? "drag" : "move"
+        pointer.text = "pointer: #{e.mouse.x},#{e.mouse.y}  (#{kind}, #{e.moves} reported so far)"
+      end
+      surface = row do |r|
+        r.add(Tuile::Component::Window.new("Canvas").tap { _1.content = canvas }, Percent[55])
+        r.add(log, Expand[1])
+      end
+      form do |f|
+        f.add(intro, Fixed[3])
+        f.add(surface, Expand[1])
+        f.add(pointer, Fixed[1])
+      end
     end
 
+    # --- Helpers -----------------------------------------------------------
+
     # The standard demo shell: children stacked with a blank row between them,
     # inset from the window border. Every constraint below reads unqualified —
     # `Fixed`, `Expand`, `Insets` all live on {Tuile::Component::Layout}, which
@@ -1649,19 +2073,19 @@ module SamplerExample
     end
 
     # Replaces the slash token at the caret with `command` plus a trailing
-    # space, then drops the caret after it (which re-fires on_change → refill,
+    # space, then drops the caret after it (which re-fires on_value_change → refill,
     # so the now-tokenless text closes the menu).
     def accept_slash_command(area, command)
       text = area.text
       caret = area.caret
       start = caret
       start -= 1 while start.positive? && !text[start - 1].match?(/\s/)
-      area.text = "#{text[0...start]}#{command} #{text[caret..]}"
+      area.value = "#{text[0...start]}#{command} #{text[caret..]}"
       area.caret = start + command.length + 1
     end
 
     # The slash menu's width: the widest command plus List's two row gutters,
-    # clamped to the screen. ListDropdown places itself but never measures — the
+    # clamped to the screen. ListDropdown hangs off its anchor but never measures — the
     # width policy stays with the driver, exactly as it does for Select.
     # @return [Integer]
     def slash_menu_width(matches)
@@ -1678,13 +2102,19 @@ end
 # component tree without spinning up the real event loop.
 if $PROGRAM_NAME == __FILE__
   screen = Tuile::Screen.new
+  screen.theme_def = SamplerExample::APP_THEME
   sampler = SamplerExample::Sampler.new
   screen.content = sampler
-  screen.on_focus_changed = -> { sampler.refresh_status }
+  screen.on_focus_changed { sampler.refresh_status }
   sampler.refresh_status
   sampler.menu_bar.focus
   begin
-    screen.run_event_loop
+    # `:hover` for the whole app, because the level is set once here and is
+    # all-or-nothing: the Mouse demo's trail and enter/exit lines arrive at no
+    # lower one. The upgrade from the default `:clicks` costs the ~84 motion
+    # reports a second (`R_mouse_reporting`) — not select-to-copy, which mode
+    # 1000 had already taken.
+    screen.run_event_loop(capture_mouse: :hover)
   ensure
     screen.close
   end