tuile 0.16.0 → 0.17.0

data/lib/tuile/component/text_area.rb

@@ -17,7 +17,7 @@ module Tuile
     # start of the next row in nearly all cases).
     #
     # Enter inserts a newline, as in a plain `<textarea>` or text editor; only
-    # {#on_change} is wired. {Keys::CTRL_J} does the same, since that is the
+    # {#on_value_change} is wired. {Keys::CTRL_J} does the same, since that is the
     # byte a terminal sends for a typed Ctrl+J. A *pasted* line break arrives
     # through {AbstractStringField#handle_paste} instead and never as a key at
     # all — so a subclass rebinding Enter to submit keeps working under a
@@ -44,18 +44,18 @@ module Tuile
     # == Implementation details
     #
     # The wrap itself — and with it every conversion between a character
-    # **index** and a **row/column** — lives in {WrappedText}, a
-    # snapshot of `(text, rect.width)` this class caches and drops whenever
-    # either changes. What stays here is the widget: keys, mouse, painting, and
-    # the {#scroll_top_row} viewport, which {WrappedText} deliberately knows
-    # nothing about (it is a pure function of text and width; the viewport is
-    # stateful and needs {Rect#height}).
+    # **index** and a **row/column** — lives in {WrappedText}, a snapshot of
+    # `(text, rect.width)` this class caches: a text mutation drops it, and a
+    # read at another width rebuilds it. What stays here is the widget: keys,
+    # mouse, painting, and the {#scroll_top_row} viewport, which {WrappedText}
+    # deliberately knows nothing about (it is a pure function of text and
+    # width; the viewport is stateful and needs {Rect#height}).
     class TextArea < AbstractStringField
       def initialize
         super
         @scroll_top_row = 0
         # Lazy cache; nil means "stale, rebuild on next read". Reset whenever
-        # {#text} mutates or the width changes.
+        # {#text} mutates; {#wrap} notices a width change itself.
         @wrap = nil
       end
 
@@ -80,11 +80,10 @@ module Tuile
         row_in_viewport = row - @scroll_top_row
         return nil if row_in_viewport.negative? || row_in_viewport >= rect.height
 
-        # Cap so the hardware cursor never lands at rect.left+rect.width
-        # (one past the rect). Terminals with auto-wrap interpret that as
-        # column 0 of the row below; capping pins the cursor on the last
-        # visible cell instead.
-        Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + row_in_viewport)
+        # Cap so the hardware cursor never lands one past the last column.
+        # Terminals with auto-wrap interpret that as column 0 of the row below;
+        # capping pins the cursor on the last visible cell instead.
+        Point.new(col.clamp(0, rect.width - 1), row_in_viewport)
       end
 
       # @param event [Mouse::DownEvent]
@@ -92,22 +91,23 @@ module Tuile
       def handle_mouse_down?(event)
         return false unless event.button == :left
 
-        target_row = (event.y - rect.top) + @scroll_top_row
+        target_row = event.y + @scroll_top_row
         self.caret = if target_row >= wrap.row_count
                        @text.length
                      else
-                       wrap.index_at(target_row, event.x - rect.left)
+                       wrap.index_at(target_row, event.x)
                      end
         true
       end
 
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         return if rect.empty?
 
         (0...rect.height).each do |row_in_viewport|
           line = wrap.row_text(row_in_viewport + @scroll_top_row)
-          draw_text(rect.left, rect.top + row_in_viewport, StyledString.plain(line))
+          canvas.set_text(0, row_in_viewport, StyledString.plain(line))
         end
       end
 
@@ -148,10 +148,11 @@ module Tuile
         true
       end
 
+      # Re-clamps the viewport to the caret, since either axis of a new rect can
+      # scroll it away.
       # @return [void]
-      def handle_width_changed
+      def relayout
         super
-        @wrap = nil
         adjust_scroll_top_row
       end
 
@@ -159,6 +160,7 @@ module Tuile
 
       # @return [WrappedText] the current wrap of {#text} at {Rect#width}.
       def wrap
+        @wrap = nil unless @wrap&.width == rect.width
         @wrap ||= WrappedText.new(@text, rect.width)
       end
 

data/lib/tuile/component/text_field.rb

@@ -48,15 +48,12 @@ module Tuile
         @placeholder = nil
         @left_column = 0
         @max_text_length = nil
-        @on_key_up = nil
-        @on_key_down = nil
-        @on_enter = nil
       end
 
       # Optional cap on {#text}'s length **in characters** — a wide glyph counts
       # once. Typing into a field already at the cap does nothing.
       #
-      # Deliberately does not police {#text=}: lowering the cap under an existing
+      # Deliberately does not police {#value=}: lowering the cap under an existing
       # value leaves that value intact rather than silently trimming it.
       # @return [Integer, nil] maximum characters, or nil for unbounded (default).
       attr_reader :max_text_length
@@ -72,35 +69,54 @@ module Tuile
         @max_text_length = max
       end
 
-      # Optional callback fired when the UP arrow key is pressed. When set, UP
-      # is consumed by the field; when nil, UP falls through to the parent
-      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
-      # since `k` is a printable character inserted into {#text}.
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      attr_accessor :on_key_up
-
-      # Optional callback fired when the DOWN arrow key is pressed. When set,
-      # DOWN is consumed by the field; when nil, DOWN falls through to the
-      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
-      # `j`, since `j` is a printable character inserted into {#text}.
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      attr_accessor :on_key_down
-
-      # Optional callback fired when ENTER is pressed. When set, ENTER is
-      # consumed by the field; when nil, ENTER falls through to the parent
-      # (default behavior).
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      attr_accessor :on_enter
+      # What {#on_key_up} fires.
+      #
+      # @!attribute [r] source
+      #   @return [TextField] the field the key reached.
+      KeyUpEvent = Data.define(:source) { include Tuile::Event }
+
+      # What {#on_key_down} fires.
+      #
+      # @!attribute [r] source
+      #   @return [TextField] the field the key reached.
+      KeyDownEvent = Data.define(:source) { include Tuile::Event }
+
+      # What {#on_enter} fires.
+      #
+      # @!attribute [r] source
+      #   @return [TextField] the field the key reached.
+      EnterEvent = Data.define(:source) { include Tuile::Event }
+
+      # @!method on_key_up
+      #   Fired with a {KeyUpEvent} when the UP arrow key is pressed. **Empty means
+      #   the field declines UP**, which then falls through to the parent; a
+      #   registered listener consumes it. Only triggered by {Keys::UP_ARROW},
+      #   not by `k`, which is a printable character inserted into {#text}.
+      #   @return [Listeners]
+      listener :on_key_up
+
+      # @!method on_key_down
+      #   Fired with a {KeyDownEvent} when the DOWN arrow key is pressed. **Empty
+      #   means the field declines DOWN**, which then falls through to the
+      #   parent. Only triggered by {Keys::DOWN_ARROW}, not by `j`.
+      #   @return [Listeners]
+      listener :on_key_down
+
+      # @!method on_enter
+      #   Fired with an {EnterEvent} when ENTER is pressed. **Empty means the field
+      #   declines ENTER**, which then falls through to the parent — which is how
+      #   a scope's default button keeps working.
+      #   @return [Listeners]
+      listener :on_enter
 
       # @return [Point, nil]
       def cursor_position
         return nil unless rect.width.positive?
 
         # Scrolling already keeps the caret inside the rect, so the cap is a
-        # guard rather than a policy: a cursor parked at rect.left + rect.width
+        # guard rather than a policy: a cursor parked one past the last column
         # reads as column 0 of the next row on an auto-wrapping terminal.
-        offset = (column_at(@caret) - @left_column).clamp(0, rect.width - 1)
-        Point.new(rect.left + offset, rect.top)
+        Point.new((column_at(@caret) - @left_column).clamp(0, rect.width - 1), 0)
       end
 
       # Places the caret at the pressed column. A press on the right half of a
@@ -110,17 +126,18 @@ module Tuile
       def handle_mouse_down?(event)
         return false unless event.button == :left
 
-        self.caret = index_at(event.x - rect.left + @left_column)
+        self.caret = index_at(event.x + @left_column)
         true
       end
 
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         return if rect.empty?
 
-        return draw_text(rect.left, rect.top, placeholder_row) if show_placeholder?
+        return canvas.set_text(0, 0, placeholder_row) if show_placeholder?
 
-        draw_text(rect.left, rect.top, StyledString.plain(visible_text))
+        canvas.set_text(0, 0, StyledString.plain(visible_text))
       end
 
       protected
@@ -137,17 +154,17 @@ module Tuile
         when *Keys::BACKSPACES then delete_before_caret
         when Keys::DELETE then delete_at_caret
         when Keys::UP_ARROW
-          return false if @on_key_up.nil?
+          return false if on_key_up.empty?
 
-          @on_key_up.call
+          on_key_up.fire(KeyUpEvent.new(source: self))
         when Keys::DOWN_ARROW
-          return false if @on_key_down.nil?
+          return false if on_key_down.empty?
 
-          @on_key_down.call
+          on_key_down.fire(KeyDownEvent.new(source: self))
         when Keys::ENTER
-          return false if @on_enter.nil?
+          return false if on_enter.empty?
 
-          @on_enter.call
+          on_enter.fire(EnterEvent.new(source: self))
         else
           return insert(key) if Keys.printable?(key)
 
@@ -187,7 +204,7 @@ module Tuile
       end
 
       # @return [void]
-      def handle_width_changed
+      def relayout
         super
         adjust_left_column
       end
@@ -246,8 +263,7 @@ module Tuile
       # @return [StyledString] the hint, ellipsized to `rect.width` and padded
       #   back out to it.
       def placeholder_row
-        hint = StyledString.styled(placeholder, fg: screen.theme.placeholder_color).ellipsize(rect.width)
-        hint + StyledString.plain(" " * [rect.width - hint.display_width, 0].max)
+        StyledString.styled(placeholder, fg: screen.theme.placeholder_color).ellipsize(rect.width).ljust(rect.width)
       end
 
       # @return [Integer] total display width of {#text}.

data/lib/tuile/component/text_view.rb

@@ -20,6 +20,17 @@ module Tuile
     # splice a range in place. Turn on {#auto_scroll} to keep the latest content
     # in view.
     #
+    # {#scrollbar_visibility} turns on a {VerticalScrollBar} in the rightmost
+    # column — a real child component, so the user can drag its handle
+    # (wanting `run_event_loop(capture_mouse: :drag)`) and press its track to
+    # page. Its column and the blank one beside it are reserved whenever it is
+    # `:visible`, whether anything scrolls or not, so the text never rewraps
+    # behind a growing buffer (`D_scrollbar_reserve`, `D_scrollbar_ink`).
+    # Under `:auto` the bar shows only while the text, wrapped at the full
+    # width, has more rows than the viewport — and then the text rewraps once,
+    # two columns narrower, which is the price of the columns it hands back
+    # while everything fits.
+    #
     # Meant to be the content of a {Window} — focus indication relies on the
     # surrounding window chrome.
     class TextView < Component
@@ -37,20 +48,29 @@ module Tuile
         # Invariants:
         # - `@line_wrap_counts.size == @lines.size`
         # - `@line_wrap_counts.sum == @rows.size`
-        # A full rebuild ({#rewrap}) happens on {#text=} and width changes;
-        # other mutators splice incrementally.
+        # A full rebuild ({#rewrap}) happens on {#text=} and when
+        # {#wrap_width} moves off `@wrapped_at`; other mutators splice
+        # incrementally.
         @lines = []
         @rows = []
         @line_wrap_counts = []
+        @wrapped_at = 0
         @text = StyledString::EMPTY
         @blank_row = StyledString::EMPTY
         @scroll_top_row = 0
         @auto_scroll = false
         @follow = true
         @scrollbar_visibility = :gone
+        # Whether an `:auto` bar is showing — state, not derived on read,
+        # because `@rows` is wrapped at the width it leaves; only
+        # {#sync_auto_scrollbar} flips it.
+        @auto_scrollbar_shown = false
         # Always ≥1 region; the implicit default owns any hard lines no
         # app-created region claims. See {Region}.
         @regions = [Region.send(:new, self)]
+        @scrollbar = VerticalScrollBar.new
+        @scrollbar.on_scroll_request { self.scroll_top_row = _1.scroll_top_row }
+        add_child(@scrollbar) # chrome, appended: a TextView has no content children
       end
 
       # @return [StyledString] the current text (empty by default). Rebuilt
@@ -63,7 +83,8 @@ module Tuile
       # @return [Integer] index of the first visible row.
       attr_reader :scroll_top_row
 
-      # @return [Symbol] `:gone` or `:visible`.
+      # @return [Symbol] `:gone`, `:visible`, or `:auto` — shown only while the
+      #   text overflows the viewport at the full width. `:gone` by default.
       attr_reader :scrollbar_visibility
 
       # @return [Boolean] if true, mutating the text scrolls the viewport so
@@ -108,6 +129,7 @@ module Tuile
         rewrap
         update_scroll_top_row_if_auto_scroll
         invalidate
+        invalidate_layout
       end
 
       # Creates a new empty {Region} at the spatial tail of the document
@@ -169,6 +191,7 @@ module Tuile
         @text = nil
         update_scroll_top_row_if_auto_scroll
         invalidate
+        invalidate_layout # `@rows` grew, and the bar's row_count follows it
       end
 
       # Verbatim append, returning `self` for chainability (`view << a << b`).
@@ -231,10 +254,7 @@ module Tuile
           remaining -= take
         end
 
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Replaces a contiguous range of hard lines with the parsed content of
@@ -272,10 +292,7 @@ module Tuile
 
         splice_lines(from, length, new_lines)
         update_region_counts(from, length, new_lines.size)
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Inserts `str` at hard-line index `at`. Equivalent to
@@ -307,17 +324,23 @@ module Tuile
         @scroll_top_row = new_row
         @follow = at_bottom?
         invalidate
+        invalidate_layout # {#relayout} pushes the row to the bar
       end
 
-      # @param value [Symbol] `:gone` or `:visible`.
+      # @param value [Symbol] `:gone`, `:visible` or `:auto`.
+      # @raise [ArgumentError] on any other value.
       # @return [void]
       def scrollbar_visibility=(value)
-        raise ArgumentError, "expected :gone or :visible, got #{value.inspect}" unless %i[gone visible].include?(value)
+        unless %i[gone visible auto].include?(value)
+          raise ArgumentError, "expected :gone, :visible or :auto, got #{value.inspect}"
+        end
         return if @scrollbar_visibility == value
 
         @scrollbar_visibility = value
+        @auto_scrollbar_shown = false # starts at the full width; the settle decides
         rewrap
         invalidate
+        invalidate_layout # the bar's rect appears or collapses
       end
 
       # Sets `auto_scroll`. If true, re-engages tailing and immediately
@@ -383,35 +406,50 @@ module Tuile
         scroll_top_row != before
       end
 
-      # Paints the text into {#rect}.
+      # Paints the text into {#rect}, out to the blank column that
+      # {#scrollbar_columns} reserves. The bar's own column is not painted
+      # here — it is the child {VerticalScrollBar}'s, placed by {#relayout}.
       #
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with padded blanks past the last line), so the
       # "fully draw over your rect" contract is met without an upfront wipe.
-      # Rows go through {Component#draw_text}, so content and blank rows inherit
-      # {Component#effective_bg_color} (a {#bg_color} set here or on an ancestor).
+      # {Component#invalidate_children} is the half that cannot be skipped
+      # with it, or the bar goes stale under an ancestor's clear
+      # (`D_repaint_cascade`). Rows go through {Canvas#set_text}, so content
+      # and blank rows inherit {ComponentBackground#effective} (a {#bg_color}
+      # set here or on an ancestor).
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         return if rect.empty?
 
-        scrollbar = if scrollbar_visible?
-                      VerticalScrollBar.new(rect.height, row_count: @rows.size, scroll_top_row: @scroll_top_row)
-                    end
+        invalidate_children
         (0...rect.height).each do |row|
-          line = paintable_row(row + @scroll_top_row, row, scrollbar)
-          draw_text(rect.left, rect.top + row, line)
+          canvas.set_text(0, row, paintable_row(row + @scroll_top_row))
         end
       end
 
       protected
 
-      # Rewraps the text on width changes — {#wrap_width} is {#rect}`.width`
-      # minus {#scrollbar_columns}, and the latter varies with the width too.
-      # A {#scrollbar_visibility=} flip rewraps from its own setter instead.
+      # Places the scrollbar, the view's one child, and pushes the two numbers
+      # it paints a handle from. No `rect.empty?` guard: a container assigns
+      # every child a rect on every pass (`D_empty_ancestor`), and
+      # {#scrollbar_visible?} already answers false for an empty rect.
+      #
+      # The rows are settled first, before the bar is placed, so the layout mark
+      # a scroll clamp makes is dropped rather than costing a second pass: a
+      # rewrap if {#wrap_width} moved — on a height change too, since an empty
+      # rect hides a `:visible` bar — then the `:auto` bar, then the
+      # {#auto_scroll} pin, which a taller viewport moves. Every mutator already
+      # marks, for the bar's `row_count`, so this runs after each one.
       # @return [void]
-      def handle_width_changed
-        super
-        rewrap
+      def relayout
+        rewrap unless @wrapped_at == wrap_width
+        sync_auto_scrollbar
+        update_scroll_top_row_if_auto_scroll
+        @scrollbar.rect = scrollbar_visible? ? Rect.new(rect.width - 1, 0, 1, rect.height) : Rect.new(0, 0, 0, 0)
+        @scrollbar.row_count = @rows.size
+        @scrollbar.scroll_top_row = @scroll_top_row
       end
 
       private
@@ -502,10 +540,7 @@ module Tuile
 
         splice_lines(start, old_count, new_lines)
         region.send(:line_count=, new_lines.size)
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Region-scoped {#replace}. Validates `range` against
@@ -527,10 +562,7 @@ module Tuile
 
         splice_lines(abs_from, length, new_lines)
         region.send(:line_count=, region.line_count - length + new_lines.size)
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Verbatim append into `region`.
@@ -566,10 +598,7 @@ module Tuile
           end
           region.send(:line_count=, region.line_count + rest.size)
         end
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Drops the last `n` hard lines from `region`'s tail via
@@ -587,10 +616,7 @@ module Tuile
         drop_from = start + region.line_count - to_drop
         splice_lines(drop_from, to_drop, [])
         region.send(:line_count=, region.line_count - to_drop)
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Drops `region` from {@regions}: its hard lines are removed via
@@ -612,10 +638,7 @@ module Tuile
         @regions << Region.send(:new, self) if @regions.empty?
         return unless had_lines
 
-        @text = nil
-        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
-        update_scroll_top_row_if_auto_scroll
-        invalidate
+        content_changed
       end
 
       # Adjusts region line counts after a {@lines} splice that removed
@@ -681,7 +704,8 @@ module Tuile
       # @return [void]
       def rewrap
         width = wrap_width
-        @blank_row = pad_to(StyledString::EMPTY, width)
+        @wrapped_at = width
+        @blank_row = StyledString::EMPTY.ljust(width)
         @rows = []
         @line_wrap_counts = []
         @lines.each do |line|
@@ -695,7 +719,7 @@ module Tuile
       # Wraps `line` at `width` and returns the padded rows alongside the
       # row count. Empty lines (e.g. from a `"\n\n"`
       # run) and degenerate `width <= 0` both emit a single {@blank_row}
-      # row, matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # row, matching what `@text.wrap(width).map { |l| l.ljust(width) }`
       # would have produced.
       # @param line [StyledString]
       # @param width [Integer]
@@ -704,7 +728,7 @@ module Tuile
         return [[@blank_row], 1] if line.empty? || width <= 0
 
         wrapped = line.wrap(width)
-        [wrapped.map { |row| pad_to(row, width) }, wrapped.size]
+        [wrapped.map { |row| row.ljust(width) }, wrapped.size]
       end
 
       # Appends `line` to the tail of {@lines}, updating the
@@ -796,11 +820,13 @@ module Tuile
 
       # Columns the scrollbar claims off the right edge: the bar itself plus one
       # blank column, so a row wrapping at the full width doesn't run into `█`
-      # (`…to show the█`). `0` when the bar is hidden.
+      # (`…to show the█`). `0` when the bar is hidden. Only the blank is this
+      # view's to paint — {#paintable_row} emits it, the child
+      # {VerticalScrollBar} owns the column beyond it.
       #
       # The blank is dropped below width 3, where reserving it would leave no
-      # column for text at all — that keeps {#paintable_row}'s "exactly
-      # {#rect}`.width` columns" contract true at every width.
+      # column for text at all — that keeps row and bar together covering
+      # exactly {#rect}`.width` columns at every width.
       # @return [Integer] `0`, `1` or `2`.
       def scrollbar_columns
         return 0 unless scrollbar_visible?
@@ -821,6 +847,24 @@ module Tuile
         self.scroll_top_row = clamped unless @scroll_top_row == clamped
       end
 
+      # Every splice's tail. {#invalidate_layout} rides along because
+      # {#relayout} pushes the bar's `row_count`: a splice that changed
+      # `@rows.size` without the mark leaves the handle sized for the old
+      # buffer.
+      #
+      # Not for {#append} or {#text=}, which mark by hand — appending must not
+      # clamp, or a viewport deliberately parked past the end (which
+      # {#scroll_top_row=} allows) is yanked back by the next line, and
+      # {#text=} clamps inside {#rewrap} already.
+      # @return [void]
+      def content_changed
+        @text = nil
+        @scroll_top_row = scroll_top_row_max if @scroll_top_row > scroll_top_row_max
+        update_scroll_top_row_if_auto_scroll
+        invalidate
+        invalidate_layout
+      end
+
       # Gated on {#following?}: once the user scrolls up off the bottom the
       # viewport pin is skipped, so reading older content is not interrupted
       # by incoming lines. {#scroll_top_row=} re-arms `@follow` when the viewport
@@ -841,40 +885,60 @@ module Tuile
       def scrollbar_visible?
         return false if rect.empty?
 
-        @scrollbar_visibility == :visible
+        case @scrollbar_visibility
+        when :visible then true
+        when :auto then @auto_scrollbar_shown
+        else false
+        end
       end
 
-      # Pads `line` with trailing default-styled spaces out to `width` display
-      # columns. Callers rely on {StyledString#wrap} having already
-      # constrained the line to `<= width`, so no truncation is performed.
-      # `width <= 0` returns {StyledString::EMPTY} to handle the degenerate
-      # `wrap_width == 0` case (rect.width == 1 with scrollbar).
-      # @param row [StyledString]
-      # @param width [Integer]
-      # @return [StyledString]
-      def pad_to(row, width)
-        return StyledString::EMPTY if width <= 0
+      # The sole writer of `@auto_scrollbar_shown`: shows the bar iff the text
+      # overflows the viewport at the *full* width, and rewraps when that
+      # flips. Deciding at the full width alone is what settles it in one
+      # step — the answer does not depend on the width the bar leaves, so
+      # showing the bar can't flip it back. Idempotent.
+      # @return [void]
+      def sync_auto_scrollbar
+        return unless @scrollbar_visibility == :auto
 
-        diff = width - row.display_width
-        return row if diff <= 0
+        shown = !rect.empty? && overflows_at_full_width?
+        return if shown == @auto_scrollbar_shown
 
-        row + StyledString.plain(" " * diff)
+        @auto_scrollbar_shown = shown
+        rewrap
+        invalidate
+      end
+
+      # Whether the text, wrapped at {#rect}`.width`, has more rows than the
+      # viewport. With the bar hidden `@rows` already *is* that wrap; with it
+      # shown the lines are re-wrapped at the full width, stopping at the first
+      # row past the viewport — so the cost is bounded by what fits on screen,
+      # and a buffer with more hard lines than rows costs nothing at all.
+      # @return [Boolean]
+      def overflows_at_full_width?
+        return @rows.size > viewport_rows unless @auto_scrollbar_shown
+        return true if @lines.size > viewport_rows
+
+        width = rect.width
+        rows = 0
+        @lines.each do |line|
+          rows += line.empty? ? 1 : line.wrap(width).size
+          return true if rows > viewport_rows
+        end
+        false
       end
 
       # @param index [Integer] 0-based index into `@rows`.
-      # @param row_in_viewport [Integer] 0-based row within the viewport.
-      # @param scrollbar [VerticalScrollBar, nil]
-      # @return [StyledString] paintable row exactly `rect.width` columns wide.
-      #   Body rows come pre-padded from {#rewrap}, so this reduces to a lookup
-      #   plus a concat of the blank column and the scrollbar glyph when a bar
-      #   is present (see {#scrollbar_columns}).
-      def paintable_row(index, row_in_viewport, scrollbar)
+      # @return [StyledString] every column of {#rect} the child bar does not
+      #   own: all of them with the bar hidden, one fewer with it visible.
+      #   Rows arrive padded to {#wrap_width} from {#rewrap}, so only the blank
+      #   {#scrollbar_columns} reserves is added here.
+      def paintable_row(index)
         row = @rows[index] || @blank_row
-        return row unless scrollbar
+        blanks = scrollbar_columns - 1
+        return row unless blanks.positive?
 
-        blanks = " " * (scrollbar_columns - 1)
-        bar = StyledString.styled(scrollbar.scrollbar_char(row_in_viewport), fg: screen.theme.scrollbar_color)
-        row + StyledString.plain(blanks) + bar
+        row + StyledString.plain(" " * blanks)
       end
 
       # A logical section of a {TextView}'s text — a contiguous run of