tuile 0.16.0 → 0.17.0

data/lib/tuile/listeners.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A listener slot: the callables registered on one `on_foo`, fired with one
+  # {Event}. The reader *is* the registrar:
+  #
+  #   button.on_click { save }                         # a block
+  #   field.on_value_change << method(:preview)        # anything callable
+  #   field.on_value_change.remove(method(:preview))   # …removed, holding nothing
+  #   field.on_value_change.empty?                     # => true
+  #
+  # `Method#==` compares receiver and name, so a widget unsubscribes with the
+  # expression it subscribed with and holds nothing. A `Proc` equals only itself,
+  # which is why the block form returns the `Proc` it registered rather than the
+  # list.
+  #
+  # Declare one with {Declare}, never by hand. It is not a collection: {#each},
+  # {#size} and {#include?} are the whole surface.
+  #
+  # == There is no setter, and no `clear`
+  #
+  # The semantics are *append, and remove your own*, and the absent `on_foo=` is
+  # the point. A replaceable slot made every claim a contention: wherever the
+  # gem wires a listener onto a child it also exposes for tuning
+  # (`DateTimeField#date_field`, `RadioGroup#list`, `TabSheet#strip`), an app
+  # reaching for that slot silently broke the widget. With no replace operation
+  # that failure cannot be written.
+  #
+  # == An empty list is meaningful, and each slot's rdoc says what its empty means
+  #
+  # Nothing here reads empty as "nothing to do": while empty, a key-claiming slot
+  # declines the key so it keeps bubbling and {Screen#on_error} re-raises.
+  # {Declare}'s transition block is for the widget that must *install* something
+  # when the slot stops being empty.
+  #
+  # Duplicates are allowed: two adds fire twice, and one {#remove} balances one
+  # {#add}.
+  class Listeners
+    # A registered callable plus the arity verdict {#fire} needs, settled once
+    # at {#add} rather than per fire.
+    Entry = Data.define(:callable, :takes_event)
+    private_constant :Entry
+
+    # @param name [Symbol] the slot's name (`:on_click`), used in error messages.
+    # @yieldparam claimed [Boolean] `true` when the list just became non-empty,
+    #   `false` when it just became empty — never called for any other change.
+    def initialize(name:, &claim_changed)
+      @name = name
+      @claim_changed = claim_changed
+      @entries = []
+    end
+
+    # Appends `callable` and returns it, so a lambda can be held for removal.
+    #
+    #   cb = field.on_value_change.add(->(e) { preview(e.value) })
+    #   field.on_value_change.remove(cb)
+    #
+    # Arity is settled here rather than per fire, so a listener that cannot take
+    # the event raises at registration instead of later inside a repaint on the
+    # loop thread.
+    #
+    # Deliberately does not call `Screen#check_locked`, alone among the gem's
+    # mutations: that would mean holding an owner, hence a `Screen` reach inside
+    # {Component::HasValue} and {Component::HasValidation}, plain mixins with
+    # none.
+    #
+    # @param callable [#call] the listener.
+    # @return [#call] `callable`.
+    # @raise [ArgumentError] if it is not callable, or cannot take zero or one
+    #   argument.
+    def add(callable)
+      entry = Entry.new(callable, takes_event?(callable))
+      was_empty = @entries.empty?
+      @entries << entry
+      @claim_changed&.call(true) if was_empty
+      callable
+    end
+
+    # Appends `callable` and returns self, so registrations chain.
+    #
+    #   field.on_value_change << method(:preview) << method(:log)
+    #
+    # @param callable [#call] the listener.
+    # @return [self]
+    def <<(callable)
+      add(callable)
+      self
+    end
+
+    # Removes the **first** occurrence of `callable`.
+    #
+    # Not `Array#delete`, which drops every occurrence: one `remove` balances
+    # one {#add}, the only rule that composes when a widget and an app happen to
+    # register the same `method(:x)`.
+    #
+    # @param callable [#call] the listener to remove.
+    # @return [Boolean] whether it was there.
+    def remove(callable)
+      index = @entries.index { _1.callable == callable }
+      return false if index.nil?
+
+      @entries.delete_at(index)
+      @claim_changed&.call(false) if @entries.empty?
+      true
+    end
+
+    # @param callable [#call]
+    # @return [Boolean] whether `callable` is registered.
+    def include?(callable) = @entries.any? { _1.callable == callable }
+
+    # @return [Boolean] whether nothing is registered — a state each slot gives
+    #   its own meaning.
+    def empty? = @entries.empty?
+
+    # @return [Integer] how many listeners are registered, duplicates counted.
+    def size = @entries.size
+
+    # Yields each listener in registration order.
+    # @yieldparam callable [#call]
+    # @return [void]
+    def each
+      @entries.each { yield _1.callable }
+    end
+
+    # Calls every listener in registration order — so the gem's own listener
+    # runs before any app's, a widget having wired itself in its constructor.
+    #
+    # A listener that raises **aborts the fire**: the ones behind it do not run
+    # and the exception propagates, as a single slot did. Isolating each
+    # listener would turn a bug into a partial fire that nothing reports.
+    #
+    # @param event [Event] passed to every listener that declared a parameter.
+    # @return [void]
+    def fire(event)
+      # Snapshot: a listener may add or remove during the fire, and the
+      # newcomer is meant to run on the *next* one.
+      @entries.dup.each { _1.takes_event ? _1.callable.call(event) : _1.callable.call }
+    end
+
+    private
+
+    # @param callable [#call]
+    # @return [Boolean] whether {#fire} passes it the event.
+    # @raise [ArgumentError]
+    def takes_event?(callable)
+      raise ArgumentError, "#{@name}: expected a callable, got #{callable.inspect}" unless callable.respond_to?(:call)
+
+      arity = callable.is_a?(Proc) || callable.is_a?(Method) ? callable.arity : callable.method(:call).arity
+      required = arity.negative? ? -arity - 1 : arity
+      if required > 1
+        raise ArgumentError, "#{@name}: a listener takes the event or nothing, but #{callable.inspect} requires " \
+                             "#{required} arguments"
+      end
+
+      # A negative arity means optional or splat parameters, which can absorb
+      # the event; only an exact zero declares it wants none.
+      !arity.zero?
+    end
+
+    # Declares listener slots on the class or module that extends it — what
+    # `attr_accessor` is to a plain attribute:
+    #
+    #   module HasValue
+    #     extend Listeners::Declare
+    #
+    #     # @!method on_value_change
+    #     #   Fired whenever the value actually changes — never on a no-op set.
+    #     #   @return [Listeners]
+    #     listener :on_value_change
+    #   end
+    #
+    # The `@!method` directive is not decoration: a `define_method` reader is
+    # invisible to sord, so without it the slot vanishes from `sig/tuile.rbs` —
+    # and it is the rdoc the slot owes rubydoc.info anyway.
+    #
+    # Extending {Component} covers every widget, since a subclass inherits the
+    # singleton method.
+    module Declare
+      # Defines the slot's reader, which returns the {Listeners} — or, given a
+      # block, registers it and returns the `Proc`.
+      #
+      # An optional block is the slot's *transition* block, run on the owner
+      # whenever the list becomes non-empty or empty again. It is what lets a
+      # widget install a bridge only while somebody is listening:
+      #
+      #   listener :on_enter do |claimed|
+      #     claimed ? editor.on_enter << @bridge : editor.on_enter.remove(@bridge)
+      #   end
+      #
+      # The list is built on first read, so no mixin has to remember a
+      # constructor line — which means in-class code goes through the reader and
+      # never touches `@on_foo`, nil until somebody asks.
+      #
+      # @param name [Symbol] the slot's **full** name, `on_`-prefixed. Spelling
+      #   it out is what keeps `on_value_change` greppable from its declaration.
+      # @yieldparam claimed [Boolean] whether the list just became non-empty.
+      # @return [Symbol] `name`.
+      # @raise [Error] unless `name` starts with `on_`.
+      def listener(name, &claim_changed)
+        unless name.to_s.start_with?("on_")
+          raise Error, "listener :#{name} — a listener slot is named on_…, and declared this way the string " \
+                       "on_#{name} appears nowhere in lib/ for a grep to find. Declare it as :on_#{name}."
+        end
+
+        ivar = :"@#{name}"
+        define_method(name) do |&block|
+          slot = instance_variable_get(ivar)
+          unless slot
+            owner = self
+            transition = claim_changed && ->(claimed) { owner.instance_exec(claimed, &claim_changed) }
+            slot = instance_variable_set(ivar, Listeners.new(name: name, &transition))
+          end
+          block ? slot.add(block) : slot
+        end
+        name
+      end
+    end
+  end
+end

data/lib/tuile/mouse/router.rb

@@ -11,7 +11,9 @@ module Tuile
     # Every event resolves against one **path**: the topmost popup containing the
     # point, else the tiled content unless a modal popup is open
     # ({ScreenPane#mouse_root_at}), then down through the shown children whose
-    # {Component#rect} contains it.
+    # {Component#rect} contains it. A `rect` is parent-relative, so the walk
+    # converts the point as it descends and each component is handed the event
+    # in **its own** coordinates — the same ones it paints in (`D_relative_rect`).
     #
     # - **{DownEvent}** — focuses the innermost {Component#focusable?} on that
     #   path, then offers {Component#handle_mouse_down?} innermost-first until one
@@ -25,8 +27,9 @@ module Tuile
     #
     # The two geometries are deliberately different. Focus follows `rect`, so a
     # press on the dead tail a widget does not paint still focuses it; the
-    # handlers bubble only along the prefix whose {Component#extent_rect} contains
-    # the point, so that same press activates nothing (`D_extent`).
+    # handlers bubble only along the prefix whose
+    # {Component#local_extent_rect} contains the point, so that same press
+    # activates nothing (`D_extent`).
     #
     # UI-thread-confined.
     #
@@ -42,6 +45,14 @@ module Tuile
     # diffs, and {#sync_hover} — run by {Screen#repaint} — drops members that
     # were detached, hidden or reparented since, firing their exits.
     class Router
+      # One step of a resolved path: a component, and the event point in *its*
+      # coordinates. The walk down is the only place that conversion is cheap —
+      # it already holds the running offset — so it is done there once rather
+      # than by each component asking where it is.
+      # @api private
+      Hit = Data.define(:component, :point)
+      private_constant :Hit
+
       # @param screen [Screen]
       def initialize(screen)
         @screen = screen
@@ -118,7 +129,7 @@ module Tuile
         path = rect_path(root, point)
         pane.dismissing_popups_outside(point, left: event.button == :left) do
           focus_innermost(root, path) if event.button == :left
-          claimant = bubble(path.take_while { _1.extent_rect.contains?(point) }, :handle_mouse_down?, event)
+          claimant = bubble(within_extent(path), :handle_mouse_down?, event)
           unless claimant.nil?
             @grabbed = claimant
             @grab_button = event.button
@@ -131,63 +142,79 @@ module Tuile
       def release(event)
         grabbed = @grabbed
         release_grab
-        grabbed.__send__(:handle_mouse_up, event) if reachable?(grabbed)
+        return if grabbed.nil? || !ComponentUtil.effectively_visible?(grabbed)
+
+        local = grabbed.to_local(event.point)
+        grabbed.__send__(:handle_mouse_up, event.with(x: local.x, y: local.y))
       end
 
       # @param event [MoveEvent]
       # @return [void]
       def move(event)
         unless @grabbed.nil?
-          drag = DragEvent.new(@grab_button, event.x, event.y)
-          @grabbed.__send__(:handle_mouse_drag, drag) if reachable?(@grabbed)
+          if ComponentUtil.effectively_visible?(@grabbed)
+            local = @grabbed.to_local(event.point)
+            @grabbed.__send__(:handle_mouse_drag, DragEvent.new(@grab_button, local.x, local.y))
+          end
           return
         end
         return unless @level == :hover
 
         path = extent_path(event.point)
-        rehover(path)
+        rehover(path.map(&:component))
         bubble(path, :handle_mouse_move?, event)
       end
 
       # A non-modal overlay is never focused into: it sits outside the key scope,
       # so focus there would make every keystroke go dead (`D_overlay`).
       # @param root [Component, nil]
-      # @param path [Array<Component>]
+      # @param path [Array<Hit>]
       # @return [void]
       def focus_innermost(root, path)
         return if root.is_a?(Component::Overlay) && !root.modal?
 
-        target = path.reverse_each.find(&:focusable?)
+        target = path.reverse_each.map(&:component).find(&:focusable?)
         @screen.focused = target unless target.nil? || target.active?
       end
 
-      # @param path [Array<Component>] root first.
+      # @param path [Array<Hit>] root first.
       # @param handler [Symbol] a routed `handle_mouse_…?`.
-      # @param event [Mouse::Event]
+      # @param event [Mouse::Event] in screen coordinates; each component is
+      #   handed it converted to its own.
       # @return [Component, nil] the component that answered true.
       def bubble(path, handler, event)
         # A handler may detach what is below it on the path (a click that swaps
         # a slot's occupant), so re-check before each delivery.
-        path.reverse_each.find { |c| c.attached? && c.__send__(handler, event) }
+        hit = path.reverse_each.find do |h|
+          h.component.attached? &&
+            h.component.__send__(handler, event.with(x: h.point.x, y: h.point.y))
+        end
+        hit&.component
       end
 
-      # @param point [Point]
-      # @return [Array<Component>] the shown components under `point` whose
-      #   extent contains it, root first.
-      def extent_path(point)
-        rect_path(@screen.pane.mouse_root_at(point), point).take_while { _1.extent_rect.contains?(point) }
-      end
+      # @param point [Point] in screen coordinates.
+      # @return [Array<Hit>] the shown components under `point` whose extent
+      #   contains it, root first.
+      def extent_path(point) = within_extent(rect_path(@screen.pane.mouse_root_at(point), point))
+
+      # @param path [Array<Hit>]
+      # @return [Array<Hit>] the prefix whose extent contains the point — the
+      #   test each component answers in its own coordinates, so a widget that
+      #   paints less than its rect has a dead tail (`D_extent`).
+      def within_extent(path) = path.take_while { _1.component.local_extent_rect.contains?(_1.point) }
 
       # @param root [Component, nil]
-      # @param point [Point]
-      # @return [Array<Component>] the shown components whose rect contains
-      #   `point`, root first. Tiled siblings never overlap, so at most one child
-      #   qualifies at each level.
+      # @param point [Point] in `root`'s parent's coordinates — screen
+      #   coordinates, since every mouse root is a {ScreenPane} child.
+      # @return [Array<Hit>] the shown components whose rect contains `point`,
+      #   root first, each paired with the point in its own coordinates. Tiled
+      #   siblings never overlap, so at most one child qualifies at each level.
       def rect_path(root, point)
         path = []
         component = root
         while component&.visible? && component.rect.contains?(point)
-          path << component
+          point = Point.new(point.x - component.rect.left, point.y - component.rect.top)
+          path << Hit.new(component:, point:)
           component = component.children.find { _1.visible? && _1.rect.contains?(point) }
         end
         path
@@ -201,17 +228,6 @@ module Tuile
         (old - chain).reverse_each { _1.__send__(:handle_mouse_exit) }
         (chain - old).each { _1.__send__(:handle_mouse_enter) }
       end
-
-      # @param component [Component, nil]
-      # @return [Boolean] whether `component` is attached and it and every
-      #   ancestor are shown.
-      def reachable?(component)
-        return false if component.nil? || !component.attached?
-
-        cursor = component
-        cursor = cursor.parent while cursor&.visible?
-        cursor.nil?
-      end
     end
   end
 end

data/lib/tuile/mouse.rb

@@ -16,7 +16,13 @@ module Tuile
   module Mouse
     # Included by every mouse event class: a marker for `case`/`is_a?`, plus the
     # {#point} they share.
+    #
+    # The include must stay qualified — a bare `Event` in this namespace
+    # resolves right back to here, and the gem-wide marker would be silently
+    # lost.
     module Event
+      include Tuile::Event
+
       # @return [Point] the event's position.
       def point = Point.new(x, y)
     end
@@ -88,12 +94,34 @@ module Tuile
     MODES = { clicks: 1000, drag: 1002, hover: 1003 }.freeze
     private_constant :MODES
 
-    # X10 button code layout: `button | 4 shift | 8 meta | 16 ctrl | 32 motion |
-    # 64 wheel`, button 3 meaning "released" (`R_mouse_reporting`).
+    # The SGR encoding mode, requested alongside whichever {MODES} rung the
+    # level picked — encoding and reporting are orthogonal modes. A terminal
+    # that does not understand it ignores the DECSET and keeps sending X10
+    # (`R_mouse_reporting`).
+    # @return [Integer]
+    SGR_MODE = 1006
+    private_constant :SGR_MODE
+
+    # Button code layout, shared by both encodings: `button | 4 shift | 8 meta
+    # | 16 ctrl | 32 motion | 64 wheel` (`R_mouse_reporting`).
     # @return [Integer]
     MODIFIER_BITS = 4 | 8 | 16
     private_constant :MODIFIER_BITS
 
+    # @return [String] the X10 report prefix, followed by three biased bytes.
+    X10_PREFIX = "\e[M"
+    private_constant :X10_PREFIX
+
+    # @return [String] the SGR report prefix, followed by a {SGR_REPORT} body.
+    SGR_PREFIX = "\e[<"
+    private_constant :SGR_PREFIX
+
+    # `\e[<Cb;x;y` then `M` for a press and `m` for a release — decimal and
+    # uncapped, where X10 packs each coordinate into a byte and dies past 223.
+    # @return [Regexp]
+    SGR_REPORT = /\A\e\[<(\d+);(\d+);(\d+)([Mm])\z/
+    private_constant :SGR_REPORT
+
     class << self
       # Normalizes a `capture_mouse:` argument to a level.
       # @param capture_mouse [Boolean, Symbol] `false`, `true` (== `:clicks`),
@@ -111,64 +139,103 @@ module Tuile
         end
       end
 
+      # The escape asking for that level, SGR encoding included:
+      #
+      #   Mouse.start_tracking(:clicks)   # => "\e[?1006h\e[?1000h"
+      #
       # @param level [Symbol] one of {LEVELS}.
       # @return [String] the escape enabling that level.
-      def start_tracking(level) = "\e[?#{MODES.fetch(level)}h"
+      def start_tracking(level) = "\e[?#{SGR_MODE}h\e[?#{MODES.fetch(level)}h"
 
       # @param level [Symbol] one of {LEVELS}.
-      # @return [String] the escape disabling that level.
-      def stop_tracking(level) = "\e[?#{MODES.fetch(level)}l"
+      # @return [String] the escape disabling that level, reporting first.
+      def stop_tracking(level) = "\e[?#{MODES.fetch(level)}l\e[?#{SGR_MODE}l"
 
-      # Whether `key` is a mouse report. True on the X10 `\e[M` prefix
-      # regardless of length — {.parse} is the place that validates the full
-      # 6-byte shape and raises on malformed input.
+      # Whether `key` is a mouse report — the X10 `\e[M` prefix or the SGR
+      # `\e[<` one, regardless of length. {.parse} is the place that validates
+      # the full shape and raises on malformed input.
       # @param key [String] key read via {Keys.getkey}
       # @return [Boolean]
-      def report?(key) = key.start_with?("\e[M")
+      def report?(key) = key.start_with?(X10_PREFIX, SGR_PREFIX)
 
-      # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y) into one of
-      # {DownEvent}, {UpEvent}, {ScrollEvent} or {MoveEvent}. Modifier bits are
-      # ignored.
+      # Parses a mouse report in either wire encoding into one of {DownEvent},
+      # {UpEvent}, {ScrollEvent} or {MoveEvent}. Modifier bits are ignored.
+      #
+      #   Mouse.parse("\e[M !\"")        # => X10:  DownEvent[:left, 0, 0]
+      #   Mouse.parse("\e[<0;1;1M")      # => SGR:  DownEvent[:left, 0, 0]
+      #   Mouse.parse("\e[<0;1;1m")      # => SGR:  UpEvent[0, 0]
+      #
+      # Which encoding arrived is invisible in the result, deliberately: SGR
+      # names the button on a release and X10 cannot, so the button is dropped
+      # (`D_mouse_dispatch`).
       #
-      # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
-      # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
-      # the upstream key-reader: a shorter prefix means the tail was lost on
-      # the way in, and a longer one means we over-consumed into the next
-      # escape sequence. We refuse to silently truncate either case because
-      # the trailing `\e` of an over-read corrupts the *next* getkey, and the
-      # corruption then surfaces as garbled keystrokes in focused inputs
-      # rather than as a parser failure pointing at the actual cause.
+      # A prefix without a whole well-formed report raises rather than
+      # truncates: it is always a bug in the upstream key-reader — a short read
+      # lost the tail, a long one over-consumed into the next escape sequence —
+      # and swallowing it corrupts the *next* getkey, surfacing as garbled
+      # keystrokes in focused inputs rather than as a parser failure pointing at
+      # the cause.
       # @param key [String] key read via {Keys.getkey}
-      # @return [Event, nil] `nil` if `key` is not a mouse report, or reports
+      # @return [Mouse::Event, nil] `nil` if `key` is not a mouse report, or reports
       #   a wheel button beyond the four directions.
       # @raise [Tuile::Error] if `key` is a malformed mouse report
       def parse(key)
         return nil unless report?(key)
+
+        key.start_with?(SGR_PREFIX) ? parse_sgr(key) : parse_x10(key)
+      end
+
+      private
+
+      # @param key [String] a report known to carry {X10_PREFIX}.
+      # @return [Mouse::Event, nil]
+      def parse_x10(key)
         unless key.bytesize == 6
           raise Tuile::Error,
                 "malformed mouse event: expected 6 bytes after \\e[M prefix, got #{key.bytesize}: #{key.inspect}"
         end
 
         code = (key[3].ord - 32) & ~MODIFIER_BITS
-        # XTerm reports coordinates 1-based (column N is encoded as N + 32);
-        # subtract 33 so that `x` and `y` are 0-based.
-        x = key[4].ord - 33
-        y = key[5].ord - 33
+        # Coordinates are 1-based and biased by 32, so - 33 lands them 0-based.
+        # X10's release is the anonymous code 3 exactly: button-less motion is
+        # 32 | 3 and the rightwards wheel 64 | 3, neither of them an up.
+        event(code, key[4].ord - 33, key[5].ord - 33, released: code == 3)
+      end
+
+      # @param key [String] a report known to carry {SGR_PREFIX}.
+      # @return [Mouse::Event, nil]
+      def parse_sgr(key)
+        match = SGR_REPORT.match(key)
+        unless match
+          raise Tuile::Error,
+                "malformed mouse event: expected \\e[<Cb;x;y and M or m, got #{key.inspect}"
+        end
+
+        code, x, y = match.values_at(1, 2, 3).map(&:to_i)
+        event(code & ~MODIFIER_BITS, x - 1, y - 1, released: match[4] == "m")
+      end
+
+      # The half both encodings share: a button code (unbiased, modifier bits
+      # already cleared) and 0-based coordinates become an event.
+      # @param code [Integer]
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param released [Boolean] whether the report says a button came up.
+      # @return [Mouse::Event, nil]
+      def event(code, x, y, released:)
         low = code & 3
         if code.anybits?(64)
           direction = %i[up down left right][low]
           direction && ScrollEvent.new(direction, x, y)
+        elsif released
+          UpEvent.new(x, y)
         elsif code.anybits?(32)
           MoveEvent.new(button(low), x, y)
-        elsif low == 3
-          UpEvent.new(x, y)
         else
           DownEvent.new(button(low), x, y)
         end
       end
 
-      private
-
       # @param low [Integer] the code's two low bits.
       # @return [Symbol, nil]
       def button(low) = %i[left middle right][low]

data/lib/tuile/point.rb

@@ -10,5 +10,11 @@ module Tuile
   class Point < Data.define(:x, :y)
     # @return [String]
     def to_s = "#{x},#{y}"
+
+    # `(0, 0)`, named for the value rather than for a role. Every coordinate
+    # space has an origin, and {Canvas#origin} is a *different* point — where a
+    # canvas's zero lands on its backend, which is rarely this one.
+    # @return [Point]
+    ZERO = new(0, 0)
   end
 end

data/lib/tuile/rect.rb

@@ -26,6 +26,15 @@ module Tuile
       Rect.new(point.x, point.y, width, height)
     end
 
+    # {#at}'s relative counterpart — the same size, shifted. What moves a
+    # rectangle between two coordinate spaces one offset apart, either way;
+    # paint and screen, a {Canvas#origin} apart, are the pair Tuile has.
+    # @param point [Point] added to {#left} and {#top}.
+    # @return [Rect] moved by `point`.
+    def moved_by(point)
+      Rect.new(left + point.x, top + point.y, width, height)
+    end
+
     # Centers the rectangle — keeps {#width} and {#height} but modifies
     # {#top} and {#left} so that the rectangle is centered on a screen.
     # @param screen_size [Size] screen size
@@ -43,6 +52,13 @@ module Tuile
       new_width == width && new_height == height ? self : Rect.new(left, top, new_width, new_height)
     end
 
+    # Half-open: the `left`/`top` edges are inside, `right`/`bottom` are not,
+    # so two abutting rectangles never both claim the cell they share.
+    #
+    #   r = Rect.new(0, 0, 2, 2)
+    #   r.contains?(Point.new(0, 0))   # => true
+    #   r.contains?(Point.new(2, 0))   # => false — right edge is outside
+    #
     # @param point [Point]
     # @return [Boolean]
     def contains?(point)
@@ -61,6 +77,23 @@ module Tuile
         other.top + other.height <= top + height
     end
 
+    # The region both rectangles cover, in the coordinate space they share.
+    # Half-open edges, like {#contains?}.
+    #
+    # Disjoint rectangles yield an {#empty? empty} rectangle rather than `nil`,
+    # so folding a chain of them needs no nil test per level and the caller
+    # asks {#empty?} once at the end — which is what a clip resolved up an
+    # ancestor chain does.
+    # @param other [Rect]
+    # @return [Rect]
+    def intersect(other)
+      new_left = [left, other.left].max
+      new_top = [top, other.top].max
+      Rect.new(new_left, new_top,
+               [[left + width, other.left + other.width].min - new_left, 0].max,
+               [[top + height, other.top + other.height].min - new_top, 0].max)
+    end
+
     # @return [Size]
     def size = Size.new(width, height)