tuile 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 246774aae8809b045b95adef86263642f561d726cb907162101cef1c94135142
-  data.tar.gz: d6858c0ece1e461a5ff767572ac1fd6255eb338a84caff1b12d0a0db66aec6b0
+  metadata.gz: fd5711addbd65a00c8d471204d50973da93ac9be65ba197114ac04c94cace526
+  data.tar.gz: 4505d93153dc96fd439e5d69a7b1506e985fc9094f8428fe092ebc6247d62b8a
 SHA512:
-  metadata.gz: 97ecd56ae772b96c8944d78245ee628f56dbcf4a4c0a955319bc8d1bf630132dd6b23ec6bb23899a97f45b6b4b92b3686fd548c056bc9eb107caa06bcaf97a89
-  data.tar.gz: 6b0f6c0f887ede7a2e7aa3309241b3b39844f5a2819f92fafdee52b1be4e88a2c9fc5a32f18ddcc3e0a671c0dedb4724de833da75d4c391a62619b8d4be58136
+  metadata.gz: 23c69343d8a0cc87143b12cd1a4a9a11862c770debf9c5381cabfcb59b55786f8be143ef362581e0a79bb1dc7f9ce512f47d755f603cb486bf4058b3487d4399
+  data.tar.gz: '0974d322289b63b43bdd498e172f446d7cc56df656645b8e6826fed388154dda4a287110819d305572dbbf1c1ee23011fc4e0cb208f6459d67535e2df5c1d2b1'

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-18
+
+- Add `Component::TextView` — read-only scrollable wrapped prose with word wrap, incremental append, and a lazy text reader.
+- Add `Tuile::StyledString` for span-modeled ANSI styling, with `#wrap` (span-preserving word wrap), `#ellipsize` (width-bounded truncation), `#with_bg`, and an `EMPTY` shared instance.
+- Model `Label`, `List`, and `TextView` text as `StyledString`; pre-pad clipped/physical lines.
+- Extract `Tuile::Ansi` for shared ANSI helpers.
+- `Window#scrollbar=` accepts any content that exposes `scrollbar_visibility=`.
+- Document `TextView` in the README and `examples/sampler.rb`.
+- Remove `Tuile::Wrap` (superseded by `StyledString#wrap`).
+- Remove `Tuile::Truncate` (superseded by `StyledString#ellipsize`).
+
+## [0.2.0] - 2026-05-15
+
+- Add `Component::TextArea` with multi-line editing, word navigation, and VT220-style Home/End handling.
+- Add `Component::Button`.
+- Add Tab / Shift+Tab focus cycling.
+- Add Ctrl+arrow word navigation to `Component::TextField`.
+- Add `Component::List#on_cursor_changed`.
+- Add `examples/sampler.rb`.
+- Paint `TextField` with a colored background.
+- Buffer `Screen#print` into a per-frame buffer during repaint, and release it on exception.
+- Join the key thread after killing it in `run_loop`'s ensure block.
+- Auto-clear gappy children in `Component#repaint`.
+- Inline a minimal truncation helper and drop the `strings-truncation` dependency.
+- Lower the Ruby floor to 3.4; pin CI head to 4.0; fix Ruby 3.4 compatibility.
+- Bump `minitest` to 6.0.
+- Document `TextField` SGR constants; refresh `sig/tuile.rbs`.
+
 ## [0.1.0] - 2026-05-02
 
 - Initial release

data/README.md

@@ -28,31 +28,28 @@ Ruby that we are aware of.
 
 ## Installation
 
-> **Note:** the gem name on RubyGems is being finalised. Until release, install
-> from git (see below). Replace
-> `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with
-> the gem name once published.
-
 Install the gem and add it to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add tuile
 ```
 
 If bundler is not being used to manage dependencies, install the gem by
 executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install tuile
 ```
 
-Until then, point your `Gemfile` at git:
+Or pin to git directly:
 
 ```ruby
 gem "tuile", git: "https://github.com/mvysny/tuile.git"
 ```
 
-Tuile requires Ruby 4.0+.
+Tuile requires Ruby 3.4+.
+
+API documentation: <https://rubydoc.info/gems/tuile>.
 
 ## Hello world
 
@@ -82,7 +79,10 @@ Save it as `hello.rb` and run `ruby hello.rb`. Press `q` or `ESC` to exit.
 
 A larger demo lives in [`examples/file_commander.rb`](examples/file_commander.rb):
 a two-pane file browser with cursor navigation, header label, and a layout
-that follows terminal resize.
+that follows terminal resize. For a tour of every shipped component, run
+[`examples/sampler.rb`](examples/sampler.rb): a two-pane sampler where the
+left pane lists demos and the right pane loads the highlighted one. Tab /
+Shift+Tab move focus between the list and the demo's widgets.
 
 ## How it works
 

data/examples/file_commander.rb

@@ -156,22 +156,8 @@ module FileCommanderExample
                                            rect.width - half, body_height)
     end
 
-    def handle_key(key)
-      if key == "\t"
-        toggle_focus
-        true
-      else
-        super
-      end
-    end
-
     private
 
-    def toggle_focus
-      target = @left_window.active? ? @right_window : @left_window
-      screen.focused = target
-    end
-
     def refresh_header
       active_list = @left_list.active? ? @left_list : @right_list
       @header.text = " #{active_list.cwd}"

data/examples/sampler.rb

@@ -0,0 +1,320 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Tuile sampler. Two-pane demo app showcasing the components shipped with
+# the framework. The left pane is a navigation list; moving the cursor
+# loads the highlighted demo into the right pane. Tab / Shift+Tab move
+# focus between the list and the demo's widgets.
+#
+# Run from the gem root:
+#   bundle exec ruby -Ilib examples/sampler.rb
+#
+# Keys (global): q or ESC to quit.
+
+require "tuile"
+
+module SamplerExample
+  # Sampler-local container: a {Tuile::Component::Layout::Absolute} that
+  # runs a caller-supplied block on `rect=` to position its children.
+  # Sampler demos sometimes have a 1-row Label sitting in a tall pane,
+  # but the stock layout's auto-clear already handles those gaps for us
+  # — Panel just needs the rect-callback to drive child positioning.
+  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
+
+  # Top-level sampler component. Splits the screen into a left entry list
+  # and a right demo pane; each `load_entry` rebuilds the demo from
+  # scratch so it always starts in a clean state.
+  class Sampler < Tuile::Component::Layout::Absolute
+    def initialize
+      super()
+      @entry_list = build_entry_list
+      @left_window = Tuile::Component::Window.new("Components").tap { it.content = @entry_list }
+      @right_window = Tuile::Component::Window.new
+      add(@left_window)
+      add(@right_window)
+      load_entry(0)
+    end
+
+    attr_reader :left_window, :right_window, :entry_list
+
+    def rect=(new_rect)
+      super
+      return if rect.empty?
+
+      list_width = (rect.width / 3).clamp(20, 40)
+      @left_window.rect = Tuile::Rect.new(rect.left, rect.top, list_width, rect.height)
+      @right_window.rect = Tuile::Rect.new(rect.left + list_width, rect.top,
+                                           rect.width - list_width, rect.height)
+    end
+
+    private
+
+    # Ordered list of demo entries: `[caption, builder_method]`. The
+    # builder runs at selection time, so every load gets a fresh component
+    # tree (an empty TextField, an un-clicked Button, etc.).
+    ENTRIES = [
+      ["Label",        :build_label],
+      ["TextField",    :build_text_field],
+      ["TextArea",     :build_text_area],
+      ["TextView",     :build_text_view],
+      ["Button",       :build_buttons],
+      ["List",         :build_list],
+      ["Layout",       :build_layout],
+      ["Popup",        :build_popup_launcher],
+      ["InfoWindow",   :build_info_launcher],
+      ["PickerWindow", :build_picker_launcher],
+      ["LogWindow",    :build_log_window],
+      ["Focus & Tab",  :build_focus_demo]
+    ].freeze
+
+    def build_entry_list
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.lines = ENTRIES.map(&:first)
+      list.on_cursor_changed = ->(idx, _line) { load_entry(idx) if idx >= 0 }
+      list
+    end
+
+    def load_entry(idx)
+      caption, builder = ENTRIES[idx]
+      @right_window.caption = caption
+      @right_window.content = send(builder)
+    end
+
+    # --- Tileable demos ----------------------------------------------------
+
+    def build_label
+      label = Tuile::Component::Label.new
+      label.text = "Label paints static text in its rect.\n" \
+                   "Multiple lines split on \\n.\n" \
+                   "Long lines are clipped to the rect width.\n\n" \
+                   "Rainbow formatting works too:\n" \
+                   "  #{Rainbow("* red").red}\n" \
+                   "  #{Rainbow("* green").green}\n" \
+                   "  #{Rainbow("* blue").blue}"
+      label
+    end
+
+    def build_text_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, then type. Arrows, Home/End, Backspace, Delete all work."
+      field = Tuile::Component::TextField.new
+      panel(prompt, field) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 1)
+        field.rect = Tuile::Rect.new(inner.left, inner.top + 3, inner.width, 1)
+      end
+    end
+
+    def build_text_area
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Multi-line input. Type to see word wrap; Enter inserts a newline.\n" \
+                    "Arrows move the caret; Ctrl+Left/Right jump by word; " \
+                    "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. " \
+                  "Edit me — the text wraps to the area's width and scrolls vertically " \
+                  "once the cursor leaves the visible rows."
+      panel(prompt, area) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        area_height = [inner.height - 6, 4].max
+        area.rect = Tuile::Rect.new(inner.left, inner.top + 5, inner.width, area_height)
+      end
+    end
+
+    def build_text_view
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Read-only viewer for prose. Word-wraps to width; ANSI formatting passes through.\n" \
+                    "Tab here, then: ↑↓ / jk scroll a line; PgUp/PgDn a page; Ctrl+U/D half a page; " \
+                    "Home/End / g/G jump to the edges."
+      window = Tuile::Component::Window.new("Excerpt")
+      view = Tuile::Component::TextView.new
+      view.text = "#{Rainbow("Tuile").green} is a small component-oriented terminal-UI framework built on top of " \
+                  "the TTY toolkit. Apps build a tree of Components under a singleton Screen; the screen runs " \
+                  "an event loop, dispatches keys and mouse events, and repaints invalidated components in " \
+                  "batch.\n\n" \
+                  "The name is #{Rainbow("French").cyan} for #{Rainbow("\"roof tile\"").yellow} — small pieces " \
+                  "that compose into a larger whole. This excerpt wraps to the viewer's current width; resize " \
+                  "the terminal to see the wrap recompute, and scroll to see the rest.\n\n" \
+                  "Components do not paint immediately. They call invalidate (which records them in the " \
+                  "Screen's pending-repaint set); after an event-loop tick drains the queue, Screen#repaint " \
+                  "walks the set, sorts by depth, and paints parents before children. Popups deliberately " \
+                  "overdraw the tiled tree on top.\n\n" \
+                  "All UI mutations must run on the thread that owns Screen#run_event_loop. Background work " \
+                  "marshals back via screen.event_queue.submit { … }. Most UI methods check the lock and " \
+                  "raise if you violate the contract; FakeScreen short-circuits the check so tests can mutate " \
+                  "freely."
+      window.content = view
+      window.scrollbar = true
+      panel(prompt, window) do |r|
+        inner = inner_rect(r)
+        prompt.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        view_height = [inner.height - 5, 4].max
+        window.rect = Tuile::Rect.new(inner.left, inner.top + 4, inner.width, view_height)
+      end
+    end
+
+    def build_buttons
+      label = Tuile::Component::Label.new
+      label.text = "Buttons fire on Enter, Space, or a left-click. Tab to focus, then activate."
+      counters = { ok: 0, cancel: 0 }
+      result = Tuile::Component::Label.new
+      refresh = -> { result.text = "Clicks: OK=#{counters[:ok]}  Cancel=#{counters[:cancel]}" }
+      refresh.call
+      ok = Tuile::Component::Button.new("OK") do
+        counters[:ok] += 1
+        refresh.call
+      end
+      cancel = Tuile::Component::Button.new("Cancel") do
+        counters[:cancel] += 1
+        refresh.call
+      end
+      panel(label, ok, cancel, result) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        ok.rect = Tuile::Rect.new(inner.left, inner.top + 4, ok.content_size.width, 1)
+        cancel.rect = Tuile::Rect.new(inner.left + ok.content_size.width + 2, inner.top + 4,
+                                      cancel.content_size.width, 1)
+        result.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      end
+    end
+
+    def build_list
+      list = Tuile::Component::List.new
+      list.cursor = Tuile::Component::List::Cursor.new
+      list.lines = (1..40).map { |i| "Item #{i}" }
+      list.scrollbar_visibility = :visible
+      list
+    end
+
+    def build_layout
+      left = Tuile::Component::Window.new("Left")
+      left.content = Tuile::Component::Label.new.tap { it.text = "Nested left window." }
+      right = Tuile::Component::Window.new("Right")
+      right.content = Tuile::Component::Label.new.tap { it.text = "Nested right window." }
+      panel(left, right) do |r|
+        half = r.width / 2
+        left.rect = Tuile::Rect.new(r.left, r.top, half, r.height)
+        right.rect = Tuile::Rect.new(r.left + half, r.top, r.width - half, r.height)
+      end
+    end
+
+    # --- Modal launchers ---------------------------------------------------
+
+    def build_popup_launcher
+      launcher(
+        "Popup is a modal overlay wrapping any Component.\n" \
+        "ESC or q closes it.",
+        "Open Popup"
+      ) do
+        list = Tuile::Component::List.new
+        list.lines = ["Hello", "from", "a Popup!", "", "Press ESC to close."]
+        Tuile::Component::Popup.new(content: list).open
+      end
+    end
+
+    def build_info_launcher
+      launcher(
+        "InfoWindow is a Window of read-only text lines, openable as a popup.",
+        "Open InfoWindow"
+      ) do
+        Tuile::Component::InfoWindow.open(
+          "Hello",
+          ["InfoWindow displays static text",
+           "inside a popup.",
+           "",
+           "Press ESC or q to close."]
+        )
+      end
+    end
+
+    def build_picker_launcher
+      launcher(
+        "PickerWindow asks the user to pick one option by a single keystroke.",
+        "Open PickerWindow"
+      ) do
+        Tuile::Component::PickerWindow.open(
+          "Pick a fruit",
+          [%w[a Apple], %w[b Banana], %w[c Cherry]]
+        ) { |key| Tuile.logger.info("Picked: #{key}") }
+      end
+    end
+
+    def build_log_window
+      log = Tuile::Component::LogWindow.new("Log")
+      log.content.add_lines([
+                              "LogWindow is a Window wrapping an auto-scrolling List.",
+                              "Lines are appended via #add_line / #add_lines.",
+                              "Used with Logger::IO it captures arbitrary log output."
+                            ])
+      log
+    end
+
+    # --- Cross-cutting -----------------------------------------------------
+
+    def build_focus_demo
+      label = Tuile::Component::Label.new
+      label.text = "Tab and Shift+Tab cycle focus through the tab stops below.\n" \
+                   "The active button highlights its background; the field shows a caret."
+      a = Tuile::Component::Button.new("Button A")
+      b = Tuile::Component::Button.new("Button B")
+      field = Tuile::Component::TextField.new
+      panel(label, a, b, field) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 2)
+        a.rect = Tuile::Rect.new(inner.left, inner.top + 4, a.content_size.width, 1)
+        b.rect = Tuile::Rect.new(inner.left + a.content_size.width + 2, inner.top + 4,
+                                 b.content_size.width, 1)
+        field.rect = Tuile::Rect.new(inner.left, inner.top + 6, inner.width, 1)
+      end
+    end
+
+    # --- Helpers -----------------------------------------------------------
+
+    def panel(*children, &layout_block)
+      p = Panel.new(&layout_block)
+      p.add(children)
+      p
+    end
+
+    def launcher(description, button_caption, &on_click)
+      label = Tuile::Component::Label.new
+      label.text = description
+      button = Tuile::Component::Button.new(button_caption, &on_click)
+      panel(label, button) do |r|
+        inner = inner_rect(r)
+        label.rect = Tuile::Rect.new(inner.left, inner.top + 1, inner.width, 3)
+        button.rect = Tuile::Rect.new(inner.left, inner.top + 5, button.content_size.width, 1)
+      end
+    end
+
+    # Carves a 2-column padding out of the panel rect so the demo content
+    # doesn't run flush to the window border.
+    def inner_rect(rect)
+      pad = 2
+      Tuile::Rect.new(rect.left + pad, rect.top, [rect.width - (pad * 2), 0].max, rect.height)
+    end
+  end
+end
+
+screen = Tuile::Screen.new
+sampler = SamplerExample::Sampler.new
+screen.content = sampler
+sampler.entry_list.focus
+begin
+  screen.run_event_loop
+ensure
+  screen.close
+end

data/lib/tuile/ansi.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tuile
+  # ANSI escape sequence constants. Tuile emits colors and text attributes
+  # via Rainbow, which produces **SGR** sequences ("Select Graphic
+  # Rendition", `ESC [ <params> m` — e.g. `\e[31m` red, `\e[1m` bold,
+  # `\e[0m` reset).
+  module Ansi
+    # SGR reset (`ESC [ 0 m`). Restores the terminal's default foreground,
+    # background, and text attributes.
+    # @return [String]
+    RESET = "\e[0m"
+  end
+end

data/lib/tuile/component/button.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A clickable button. Activated by Enter, Space, or a left mouse click;
+    # fires the {#on_click} callback. Renders as `[ caption ]` on a single
+    # row; the background is highlighted when the button is focused so the
+    # user can see which button is active.
+    #
+    # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
+    # the standard focus cycle. Click-to-focus also works via the inherited
+    # {Component#handle_mouse}.
+    #
+    # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
+    # show `[ caption ]`; {#content_size} reports that natural width.
+    class Button < Component
+      # @param caption [String] the button's label.
+      # @yield optional `on_click` callback; same as assigning {#on_click=}.
+      def initialize(caption = "", &on_click)
+        super()
+        @caption = caption.to_s
+        @on_click = on_click
+      end
+
+      # @return [String] the button's label.
+      attr_reader :caption
+
+      # Callback fired when the button is activated (Enter, Space, or
+      # left-click). The callable receives no arguments.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_click
+
+      # Sets a new caption and invalidates the button. No-op if unchanged.
+      # @param new_caption [String]
+      def caption=(new_caption)
+        new_caption = new_caption.to_s
+        return if @caption == new_caption
+
+        @caption = new_caption
+        invalidate
+      end
+
+      def focusable? = true
+
+      def tab_stop? = true
+
+      # @return [Size] natural width is `caption.length + 4` to fit
+      #   `[ caption ]`; height is 1.
+      def content_size = Size.new(@caption.length + 4, 1)
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        case key
+        when Keys::ENTER, " "
+          @on_click&.call
+          true
+        else
+          false
+        end
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
+
+        @on_click&.call
+      end
+
+      # @return [void]
+      def repaint
+        super
+        return if rect.empty?
+
+        label = "[ #{@caption} ]"[0, rect.width]
+        styled = active? ? Rainbow(label).bg(:darkslategray) : label
+        screen.print TTY::Cursor.move_to(rect.left, rect.top), styled
+      end
+    end
+  end
+end

data/lib/tuile/component/label.rb

@@ -2,38 +2,66 @@
 
 module Tuile
   class Component
-    # A label which shows static text. No word-wrapping; clips long lines.
+    # A label which shows static text. No word-wrapping; long lines are
+    # truncated with an ellipsis. Text is modeled as a {StyledString};
+    # {#text=} accepts a {String} (parsed via {StyledString.parse}, so
+    # embedded ANSI is honored) or a {StyledString} directly. {#text}
+    # always returns the {StyledString}.
     class Label < Component
       def initialize
         super
-        @lines = []
+        @text = StyledString::EMPTY
         @clipped_lines = []
+        @blank_line = ""
       end
 
-      # @param text [String, nil] draws this text. May contain ANSI formatting.
-      #   Clipped automatically.
+      # @return [StyledString] the current text. Defaults to an empty
+      #   {StyledString}.
+      attr_reader :text
+
+      # Replaces the text. A `String` is parsed via {StyledString.parse}
+      # (embedded ANSI is honored); a `StyledString` is used as-is; `nil` is
+      # coerced to an empty {StyledString}. Lines wider than {#rect} are
+      # truncated with an ellipsis at paint time.
+      # @param value [String, StyledString, nil]
       # @return [void]
-      def text=(text)
-        @lines = text.to_s.split("\n")
+      def text=(value)
+        new_text = StyledString.parse(value)
+        return if @text == new_text
+
+        @text = new_text
         @content_size = nil
-        update_clipped_text
+        update_clipped_lines
+        invalidate
       end
 
-      # @return [Size]
+      # @return [Size] longest hard-line's display width × number of hard
+      #   lines. Reported on the *unclipped* text — sizing is intrinsic to
+      #   the content, not the viewport. Empty text returns `Size.new(0, 0)`.
       def content_size
-        @content_size ||= begin
-          width = @lines.map { |line| Unicode::DisplayWidth.of(Rainbow.uncolor(line)) }.max || 0
-          Size.new(width, @lines.size)
-        end
+        @content_size ||=
+          if @text.empty?
+            Size::ZERO
+          else
+            hard_lines = @text.lines
+            width = hard_lines.map(&:display_width).max || 0
+            Size.new(width, hard_lines.size)
+          end
       end
 
+      # Paints the text into {#rect}.
+      #
+      # Skips the {Component#repaint} default's auto-clear: every row is
+      # painted explicitly (with pre-padded blanks past the last line), so
+      # the "fully draw over your rect" contract is met without an upfront
+      # wipe.
       # @return [void]
       def repaint
-        clear_background
-        height = rect.height.clamp(0, nil)
-        lines_to_print = @clipped_lines.length.clamp(nil, height)
-        (0..lines_to_print - 1).each do |index|
-          screen.print TTY::Cursor.move_to(rect.left, rect.top + index), @clipped_lines[index]
+        return if rect.empty? || rect.left.negative? || rect.top.negative?
+
+        (0...rect.height).each do |row|
+          line = @clipped_lines[row] || @blank_line
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + row), line
         end
       end
 
@@ -42,21 +70,31 @@ module Tuile
       # @return [void]
       def on_width_changed
         super
-        update_clipped_text
+        update_clipped_lines
       end
 
       private
 
+      # Recomputes {@clipped_lines} for the current text and rect width.
+      # Each line is ellipsized to fit, padded with trailing spaces out to
+      # the full width, and pre-rendered to ANSI so {#repaint} is just a
+      # lookup + screen.print per row. {@blank_line} covers rows past the
+      # last text line.
       # @return [void]
-      def update_clipped_text
-        len = rect.width.clamp(0, nil)
-        clipped = @lines.map do |line|
-          Strings::Truncation.truncate(line, length: len)
-        end
-        return if @clipped_lines == clipped
+      def update_clipped_lines
+        width = rect.width.clamp(0, nil)
+        @blank_line = " " * width
+        @clipped_lines = @text.lines.map { |line| pad_to(line.ellipsize(width), width).to_ansi }
+      end
 
-        @clipped_lines = clipped
-        invalidate
+      # @param line [StyledString]
+      # @param width [Integer]
+      # @return [StyledString]
+      def pad_to(line, width)
+        diff = width - line.display_width
+        return line if diff <= 0
+
+        line + StyledString.plain(" " * diff)
       end
     end
   end