tuile 0.8.0 → 0.9.0

data/lib/tuile/component/popup.rb

@@ -4,18 +4,30 @@ module Tuile
   class Component
     # An overlay that wraps any {Component} as its content. Popup itself
     # paints nothing — it's a transparent host that handles its lifecycle
-    # ({#open} / {#close} / {#open?}, ESC/q to close) and auto-sizes to the
-    # wrapped content.
+    # ({#open} / {#close} / {#open?}, ESC/q to close) and holds a top-down
+    # {#size} the {Screen} applies.
+    #
+    # The popup does *not* size itself to its content. Its box is declared by
+    # {#size} — a {Fraction} (resolved against the screen every layout pass, so
+    # it tracks resize) or an absolute {Size} (clamped to the screen). The
+    # default is {Fraction::HALF}: half the screen, centered. The wrapped
+    # content then fills that box and handles its own overflow by wrapping and
+    # scrolling, so use content that can — a {Component::TextView} or
+    # {Component::TextArea} — for anything longer than fits. A
+    # {Component::Label} only truncates.
     #
     # Modal by default: it centers on the screen, grabs focus, eats keys, and
     # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content (still painted on top, still auto-sized)
-    # without taking focus or capturing input — the caller positions it (via
-    # {#rect=}) and drives it from app code. That is the building block for an
-    # autocomplete/slash-command list anchored to a {Component::TextField} or
-    # {Component::TextArea} caret: typing keeps focus (and the cursor) in the
-    # input, an {Component::TextInput#on_change} listener refills the list, and
-    # an {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
+    # that floats above the content (still painted on top) without taking focus
+    # or capturing input — the caller positions it (via {#rect=}) and drives it
+    # from app code. That is the building block for an autocomplete/slash-command
+    # list anchored to a {Component::TextField} or {Component::TextArea} caret:
+    # typing keeps focus (and the cursor) in the input, an
+    # {Component::TextInput#on_change} listener refills the list, and an
+    # {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
+    # Such a caller owns the list data, so it sizes the overlay itself
+    # (`overlay.size = Size.new(longest, [items.size, 8].min)`) — still
+    # caller-decides, top-down.
     #
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -36,22 +48,43 @@ module Tuile
       include Component::HasContent
 
       # @param content [Component, nil] initial content; can be set later via
-      #   {#content=}. When provided here, the popup auto-sizes to fit.
+      #   {#content=}. The content fills the popup's {#rect}; it does not
+      #   determine the popup's size.
       # @param modal [Boolean] true (default) for a centered, focus-grabbing,
       #   input-capturing modal; false for a non-modal overlay the caller
       #   positions and drives (see the class docs).
-      def initialize(content: nil, modal: true)
+      # @param size [Size, Fraction] the popup's size, applied top-down. A
+      #   {Fraction} is resolved against the screen each layout pass; a {Size}
+      #   is clamped to the screen. Defaults to {Fraction::HALF}.
+      def initialize(content: nil, modal: true, size: Fraction::HALF)
         super()
         @modal = modal
+        @size = size
         @content = nil
         self.content = content unless content.nil?
+        reposition
       end
 
+      # @return [Size, Fraction] the popup's declared size. See {#size=}.
+      attr_reader :size
+
       # @return [Boolean] whether this popup is modal. See {#initialize}.
       def modal? = @modal
 
       def focusable? = true
 
+      # Sets the popup's size and repositions it. Accepts a {Fraction}
+      # (resolved against the screen every layout pass, so it tracks resize) or
+      # an absolute {Size} (clamped to the screen). This is **authoritative**,
+      # not a preference: the screen applies exactly what you ask for (clamped),
+      # with no negotiation — a popup has no siblings to compete with.
+      # @param new_size [Size, Fraction]
+      # @return [void]
+      def size=(new_size)
+        @size = new_size
+        reposition
+      end
+
       # Reassigns the popup's rect, escalating to a full scene repaint when an
       # open popup shrinks or moves so its new rect no longer covers the cells
       # it previously painted. A popup overdraws the scene without clipping and
@@ -67,20 +100,21 @@ module Tuile
         screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
       end
 
-      # Mounts this popup on the {Screen}. Recomputes the popup's size from
-      # the current content first, so reopening a popup whose content has
-      # grown or shrunk while closed picks up the new size.
+      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
+      # current screen first.
       # @return [void]
       def open
-        update_rect unless @content.nil?
+        reposition
         screen.add_popup(self)
       end
 
       # Constructs and opens a popup in one call.
       # @param content [Component, nil]
+      # @param modal [Boolean] see {#initialize}.
+      # @param size [Size, Fraction] see {#initialize}.
       # @return [Popup] the opened popup.
-      def self.open(content: nil)
-        Popup.new(content: content).tap(&:open)
+      def self.open(content: nil, modal: true, size: Fraction::HALF)
+        Popup.new(content: content, modal: modal, size: size).tap(&:open)
       end
 
       # Removes this popup from the {Screen}. No-op if not currently open.
@@ -94,44 +128,29 @@ module Tuile
         screen.has_popup?(self)
       end
 
-      # Recenters the popup on the screen, preserving its current width/height.
-      # Called automatically by the screen's layout pass and by {#content=}
-      # when the popup is open.
+      # Re-resolves {#size} against the current screen and repositions the popup
+      # *itself* (this is not laying out content — the popup's own rect): a
+      # modal popup recenters; a non-modal overlay keeps its caller-assigned
+      # top-left (only its size follows the screen). Called on {#open}, on
+      # {#size=}, and by the screen's layout pass (so a {Fraction} size tracks
+      # SIGWINCH).
+      #
+      # The final rect is computed and assigned in one step rather than sizing
+      # at the origin and then centering: the intermediate origin rect rarely
+      # covers the previous one, which would make {#rect=}'s shrink/move
+      # detection fire a full repaint on every resize.
       # @return [void]
-      def center
-        self.rect = rect.centered(screen.size)
-      end
-
-      # @return [Integer] max height the popup will grow to fit its content.
-      #   Defers to the content's {Component#popup_max_height} advice when it
-      #   gives one, else defaults to 12. Override in a subclass to allow
-      #   taller popups regardless of content.
-      def max_height = @content&.popup_max_height || 12
-
-      # @return [Integer] min height the popup occupies even when its content
-      #   is shorter. Defers to the content's {Component#popup_min_height}
-      #   advice when it gives one, else defaults to 0 (size purely to
-      #   content) — so a {Component::LogWindow} stays readable while only a
-      #   few lines are in without callers wiring up a subclass. Override in a
-      #   subclass to keep any popup from collapsing to a couple of rows.
-      #   Capped at the same 4/5-of-screen ceiling {#update_rect} applies.
-      def min_height = @content&.popup_min_height || 0
-
-      # Sets the popup's content and auto-sizes the popup to fit.
-      # @param new_content [Component, nil]
-      def content=(new_content)
-        super
-        update_rect unless new_content.nil?
+      def reposition
+        size = @size.is_a?(Fraction) ? @size.resolve(screen.size) : @size.clamp(screen.size)
+        r = Rect.new(rect.left, rect.top, size.width, size.height)
+        r = r.centered(screen.size) if modal?
+        self.rect = r
       end
 
-      # Re-sizes (and recenters, when open) whenever the wrapped content's
-      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
-      # `add_line`, or a nested {Window} whose own content grew (the window
-      # recomputes its {Component#content_size} and the change bubbles here).
-      # @param _child [Component]
+      # Recenters the popup on the screen, preserving its current width/height.
       # @return [void]
-      def on_child_content_size_changed(_child)
-        update_rect
+      def center
+        self.rect = rect.centered(screen.size)
       end
 
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
@@ -164,30 +183,6 @@ module Tuile
       def layout(content)
         content.rect = rect
       end
-
-      private
-
-      # Recompute width/height from {#content}'s natural size and recenter
-      # if currently open. Called whenever content is (re)assigned.
-      #
-      # Computes the final (centered) rect and assigns it in one step rather
-      # than positioning at the origin and then centering: the intermediate
-      # origin rect rarely covers the previous one, which would make
-      # {#rect=}'s shrink/move detection fire a full repaint on every resize.
-      # @return [void]
-      def update_rect
-        ceiling = screen.size.height * 4 / 5
-        size = @content.content_size.clamp_height(max_height)
-        size = size.clamp(Size.new(screen.size.width * 4 / 5, ceiling))
-        floor = min_height.clamp(0, ceiling)
-        size = Size.new(size.width, floor) if size.height < floor
-        # A non-modal overlay is positioned by the caller, so an open one keeps
-        # its current top-left when its content resizes; a modal popup recenters.
-        origin = open? && !modal? ? Point.new(rect.left, rect.top) : Point.new(0, 0)
-        r = Rect.new(origin.x, origin.y, size.width, size.height)
-        r = r.centered(screen.size) if open? && modal?
-        self.rect = r
-      end
     end
   end
 end

data/lib/tuile/component/text_view.rb

@@ -122,7 +122,6 @@ module Tuile
         rewrap
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Creates a new empty {Region} at the spatial tail of the document
@@ -191,7 +190,6 @@ module Tuile
         @text = nil
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Verbatim append, returning `self` for chainability (`view << a << b`).
@@ -266,7 +264,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Replaces a contiguous range of hard lines with the parsed content
@@ -327,7 +324,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Inserts `str` at hard-line index `at`. Equivalent to
@@ -386,13 +382,6 @@ module Tuile
 
       def tab_stop? = true
 
-      # @return [Size] longest hard-line's display width × number of hard
-      #   lines. Reported on the *unwrapped* text — wrap-aware sizing would
-      #   be circular (width depends on width). Empty text returns
-      #   `Size.new(0, 0)`. Maintained incrementally by {#text=} and
-      #   {#append}, so reads are O(1).
-      attr_reader :content_size
-
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
@@ -544,7 +533,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Region-scoped {#replace}. Validates `range` against
@@ -570,7 +558,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Verbatim append into `region`.
@@ -610,7 +597,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Drops the last `n` hard lines from `region`'s tail via
@@ -632,7 +618,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Drops `region` from {@regions}: its hard lines are removed via
@@ -658,7 +643,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Adjusts region line counts after a {@hard_lines} splice that
@@ -832,13 +816,6 @@ module Tuile
         StyledString.new(spans)
       end
 
-      # @return [Size] {#content_size} computed from {@hard_lines}.
-      def compute_content_size
-        return Size::ZERO if @hard_lines.empty?
-
-        Size.new(@hard_lines.map(&:display_width).max || 0, @hard_lines.size)
-      end
-
       # @return [Integer] column width available for wrapped text — viewport
       #   width minus the scrollbar gutter (when visible). `0` when {#rect}'s
       #   width is non-positive, which yields a degenerate "no wrap" result.

data/lib/tuile/component/window.rb

@@ -20,38 +20,46 @@ module Tuile
         @border_right = 1
         @caption = caption
         @content = nil
-        # Optional bottom-row chrome that overlays the bottom border (e.g. a
-        # search field).
+        # Optional bottom-row widget slot (e.g. a search field), spanning the
+        # full inner width; and optional bottom-border chrome text embedded in
+        # the border line (mutually exclusive — the component, when present,
+        # occupies the row and hides the text).
         @footer = nil
-        @footer_sizing = Sizing::FILL
-        update_content_size
+        @footer_text = StyledString::EMPTY
       end
 
       def focusable? = true
 
-      # @return [Component, nil] optional component overlaying the bottom border
-      #   row.
+      # @return [Component, nil] optional focusable component occupying the
+      #   bottom border row, always spanning the full inner width.
       attr_reader :footer
 
-      # @return [Sizing] how the footer's width is computed from the window's
-      #   inner width; defaults to {Sizing::FILL} (the footer spans the full
-      #   inner width). The footer's height is always 1 (the border row).
-      attr_reader :footer_sizing
-
-      # Sets the footer width policy and re-lays-out the footer.
-      # @param sizing [Sizing]
-      def footer_sizing=(sizing)
-        raise TypeError, "expected Sizing, got #{sizing.inspect}" unless sizing.is_a?(Sizing)
-        return if @footer_sizing == sizing
-
-        @footer_sizing = sizing
-        layout_footer
-        invalidate # repaint border cells the footer may have just vacated
-      end
-
-      # Sets the bottom-row chrome slot. The footer overlays the bottom border
-      # row and is positioned automatically — its width is governed by
-      # {#footer_sizing}; pass `nil` to remove.
+      # @return [StyledString] optional chrome embedded into the bottom border
+      #   line, mirroring {#caption} on the top line. Empty by default; hidden
+      #   whenever a {#footer} component is present.
+      attr_reader :footer_text
+
+      # Sets the bottom-border chrome. Accepts a `String` (parsed via
+      # {StyledString.parse}), a {StyledString}, or `nil` (clears it). The text
+      # embeds into the bottom border at its own width with the border's dashes
+      # filling the remainder, clipped to the inner width — border decoration,
+      # not a component (not focusable). Hidden whenever a {#footer} component
+      # occupies the bottom row (see the precedence note on {#footer=}).
+      # @param text [String, StyledString, nil]
+      def footer_text=(text)
+        new_text = StyledString.parse(text)
+        return if @footer_text == new_text
+
+        @footer_text = new_text
+        invalidate # repaint the bottom border line
+      end
+
+      # Sets the bottom-row widget slot. The footer occupies the bottom border
+      # row, spanning the full inner width, and is positioned automatically;
+      # pass `nil` to remove.
+      #
+      # Precedence: a footer component present hides {#footer_text}; absent, the
+      # text embeds into the bottom border. No window needs both at once.
       #
       # Symmetric to {#content=}: validates the new component, swaps parent
       # pointers, invalidates the old/new components and the window border, and
@@ -122,36 +130,6 @@ module Tuile
       def caption=(new_caption)
         @caption = new_caption
         invalidate
-        update_content_size
-      end
-
-      # Sets the new content. Also recomputes the window's natural size.
-      # @param new_content [Component, nil]
-      def content=(new_content)
-        super
-        update_content_size
-      end
-
-      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
-      # size changes, and folds a content resize into the window's own
-      # natural size (whose change then bubbles to the window's parent — e.g.
-      # a {Popup} re-self-sizes). The footer deliberately does *not*
-      # participate in the window's {#content_size}: it is decoration
-      # overlaying the border, and must not drive the window's size — if it
-      # doesn't fit, it is clipped to the inner width.
-      # @param child [Component]
-      # @return [void]
-      def on_child_content_size_changed(child)
-        if child.equal?(@footer)
-          old_rect = @footer.rect
-          layout_footer
-          # Repaint on any footer geometry change: a shrinking footer vacates
-          # border cells that must be re-dashed (a growing one merely
-          # overdraws, but distinguishing isn't worth the code).
-          invalidate if @footer.rect != old_rect
-        else
-          update_content_size
-        end
       end
 
       # Fully repaints the window: both frame and contents.
@@ -178,7 +156,6 @@ module Tuile
         super
         # The shortcut key is shown in the caption — repaint.
         invalidate
-        update_content_size
       end
 
       protected
@@ -213,7 +190,26 @@ module Tuile
           buf.set_char(left, top + dy, "│", bar)
           buf.set_char(left + w - 1, top + dy, "│", bar)
         end
-        buf.set_line(left, top + h - 1, StyledString.styled("└#{"─" * inner_w}┘", fg: fg)) if h >= 2
+        buf.set_line(left, top + h - 1, bottom_border(inner_w, fg)) if h >= 2
+      end
+
+      # Builds the bottom border line. The corners take the border color; the
+      # interior is plain dashes when a {#footer} component occupies the row
+      # (it overpaints them) or when there's no chrome, otherwise it carries
+      # {#footer_text} embedded at its own width — keeping the text's own
+      # styling — with dashes filling the remainder up to the inner width.
+      # @param inner_w [Integer] the border's interior width.
+      # @param fg [Color, nil] the active-border color, or nil when inactive.
+      # @return [StyledString]
+      def bottom_border(inner_w, fg)
+        interior =
+          if @footer || @footer_text.empty?
+            StyledString.styled("─" * inner_w, fg: fg)
+          else
+            embedded = @footer_text.slice(0, inner_w)
+            embedded + StyledString.styled("─" * (inner_w - embedded.display_width), fg: fg)
+          end
+        StyledString.styled("└", fg: fg) + interior + StyledString.styled("┘", fg: fg)
       end
 
       # The caption text as it appears in the rendered border, including the
@@ -226,28 +222,14 @@ module Tuile
 
       private
 
-      # Recomputes the window's natural size: content's natural size (or the
-      # caption, whichever is wider) plus the 2-character border. The footer
-      # is deliberately excluded — see {#on_child_content_size_changed}. A
-      # window with no content or caption sizes to `Size.new(2, 2)` (bare
-      # border).
-      # @return [void]
-      def update_content_size
-        inner_w = [content&.content_size&.width || 0, frame_caption.length].max
-        inner_h = content&.content_size&.height || 0
-        self.content_size = Size.new(inner_w + 2, inner_h + 2)
-      end
-
-      # Positions the footer over the bottom border row, with its width
-      # resolved by {#footer_sizing} against the inner width. A
-      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
-      # rect — i.e. it is invisible, as if never assigned.
+      # Positions the footer over the bottom border row, spanning the full
+      # inner width (the only dimension a bottom-row widget needs — the window
+      # already knows it).
       # @return [void]
       def layout_footer
         return if @footer.nil? || rect.empty?
 
-        available = [rect.width - 2, 0].max
-        width = @footer_sizing.resolve(available, @footer.content_size.width)
+        width = [rect.width - 2, 0].max
         @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end

data/lib/tuile/component.rb

@@ -12,7 +12,6 @@ module Tuile
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
-      @content_size = Size::ZERO
       @on_theme_changed = nil
     end
 
@@ -252,30 +251,6 @@ module Tuile
       end
     end
 
-    # The {Size} big enough to show the entire component contents without
-    # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
-    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
-    # their mutators, so reads are O(1). Used by callers like
-    # {Component::Popup} to auto-size to whatever content was assigned,
-    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
-    # @return [Size]
-    attr_reader :content_size
-
-    # Called by a child component whose {#content_size} just changed (fired
-    # from the child's {#content_size=}). Does nothing by default — a plain
-    # container is not size-coupled to its children. Containers that derive
-    # their own natural size or child layout from a child's natural size
-    # override this (e.g. {Component::Window} re-lays-out a
-    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
-    # {Component::Popup} re-self-sizes). If the receiver's own
-    # {#content_size} changes as a consequence, its {#content_size=} notifies
-    # *its* parent in turn — so the event bubbles exactly as far as geometry
-    # keeps changing, and stops where it doesn't.
-    # @param child [Component] the resized direct child.
-    # @return [void]
-    def on_child_content_size_changed(child); end
-
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
     # {Screen} positions the hardware cursor after each repaint cycle by
@@ -288,49 +263,15 @@ module Tuile
     #   topmost popup. Empty by default; override to advertise shortcuts.
     def keyboard_hint = ""
 
-    # Advice to a wrapping {Component::Popup} on the minimum height this
-    # component prefers to occupy when shown in a popup. `nil` (the default)
-    # means no preference — the popup uses its own {Component::Popup#min_height}.
-    # Override in a content component that should not collapse to a couple of
-    # rows when sparse (e.g. {Component::LogWindow}).
-    # @return [Integer, nil]
-    def popup_min_height = nil
-
-    # Advice to a wrapping {Component::Popup} on the maximum height this
-    # component may grow to when shown in a popup. `nil` (the default) means
-    # no preference — the popup uses its own {Component::Popup#max_height}.
-    # @return [Integer, nil]
-    def popup_max_height = nil
-
     protected
 
-    # @param parent [Component, nil]
+    # @return [Component, nil]
     attr_writer :parent
 
     # Called whenever the component width changes. Does nothing by default.
     # @return [void]
     def on_width_changed; end
 
-    # Memoizes the component's natural size and notifies {#parent} via
-    # {#on_child_content_size_changed} when the value actually changed.
-    # Subclasses call this from their content mutators (`text=`, `add_lines`,
-    # `caption=`, …) instead of caching ad-hoc.
-    #
-    # Call this as the *last* step of a mutator: the parent hook may
-    # reentrantly reposition this component (assign {#rect} — e.g. {Window}
-    # re-laying-out a wrap-content footer, or {Popup} re-self-sizing), which
-    # triggers {#on_width_changed} and {#repaint}-related recomputation, so
-    # all internal state must already be consistent.
-    # @param new_size [Size]
-    # @return [void]
-    def content_size=(new_size)
-      raise TypeError, "expected Size, got #{new_size.inspect}" unless new_size.is_a?(Size)
-      return if @content_size == new_size
-
-      @content_size = new_size
-      parent&.on_child_content_size_changed(self)
-    end
-
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
     #

data/lib/tuile/event_queue.rb

@@ -47,10 +47,13 @@ module Tuile
       latch.wait
     end
 
-    # Schedules `block` to fire on the event-loop thread roughly `fps` times
-    # per second, passing a 0-based monotonically increasing tick counter. Use
-    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
-    # periodic UI refresh from a background task.
+    # Schedules `block` to fire on the event-loop thread every `seconds`,
+    # passing a 0-based monotonically increasing tick counter. The interval is
+    # in **seconds** — the conventional scheduling unit (`sleep`,
+    # `Concurrent::TimerTask#execution_interval`, …) — so `tick(0.2)` fires five
+    # times a second. Use it for periodic UI refresh from a background task
+    # (poll a status, redraw a clock). For animation, where frames-per-second
+    # is the natural unit, {#tick_fps} reads better.
     #
     # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
     # stop it.
@@ -64,19 +67,37 @@ module Tuile
     # ({Concurrent}.global_timer_set) — adding more tickers does not add more
     # threads, just more work on the shared scheduler.
     #
+    # @param seconds [Numeric] interval between firings, must be positive.
+    #   Fractional values are fine (`tick(0.05)` ⇒ ~20 firings a second).
+    # @yield [tick] called on the event-loop thread each firing.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [Ticker]
+    def tick(seconds, &block)
+      raise ArgumentError, "block required" unless block
+      unless seconds.is_a?(Numeric) && seconds.positive?
+        raise ArgumentError, "seconds must be a positive Numeric, got #{seconds.inspect}"
+      end
+
+      Ticker.new(self, seconds, block)
+    end
+
+    # Frames-per-second convenience over {#tick}: `tick_fps(15)` is exactly
+    # `tick(1.0 / 15)`. Reads naturally for animation (a `/-\|` spinner, a
+    # progress pulse) where you think in frames, not intervals.
     # @param fps [Numeric] firings per second, must be positive. Fractional
-    #   values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    #   values are fine (`tick_fps(0.5)` ⇒ one firing every two seconds).
     # @yield [tick] called on the event-loop thread each firing.
     # @yieldparam tick [Integer] 0-based monotonically increasing counter.
     # @yieldreturn [void]
     # @return [Ticker]
-    def tick(fps, &block)
+    def tick_fps(fps, &block)
       raise ArgumentError, "block required" unless block
       unless fps.is_a?(Numeric) && fps.positive?
         raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
       end
 
-      Ticker.new(self, fps, block)
+      tick(1.0 / fps, &block)
     end
 
     # Runs the event loop and blocks. Must be run from at most one thread at the
@@ -227,9 +248,9 @@ module Tuile
     # ({Screen#on_error} for the default Tuile setup).
     class Ticker
       # @param event_queue [EventQueue] queue to dispatch tick calls onto.
-      # @param fps [Numeric] firings per second (positive).
+      # @param interval [Numeric] seconds between firings (positive).
       # @param block [Proc] called as `block.call(tick_count)` on each fire.
-      def initialize(event_queue, fps, block)
+      def initialize(event_queue, interval, block)
         @event_queue = event_queue
         @block = block
         @tick = 0
@@ -239,7 +260,7 @@ module Tuile
         # one-shot guard against double-shutdown and well-defined visibility
         # on non-MRI Rubies.
         @cancelled = Concurrent::AtomicBoolean.new(false)
-        @timer = Concurrent::TimerTask.new(execution_interval: 1.0 / fps) do
+        @timer = Concurrent::TimerTask.new(execution_interval: interval) do
           @event_queue.submit { fire }
         end
         @timer.execute