tuile 0.9.0 → 0.11.0

data/lib/tuile/component/text_field.rb

@@ -2,23 +2,76 @@
 
 module Tuile
   class Component
-    # A single-line text input field with hardware-cursor caret.
+    # A single-line text input with a real hardware caret, scrolling
+    # horizontally to keep that caret in view:
     #
-    # The field does not scroll. Any keystroke that would make {#text} longer
-    # than `rect.width - 1` (the last column is reserved for the caret past the
-    # last char) is rejected.
+    #   f = TextField.new
+    #   f.rect  = Rect.new(0, 0, 6, 1)   # six columns wide …
+    #   f.text  = "hello world"          # … eleven columns of text, so it scrolls
+    #   f.caret = 11                     # paints "world " — left_column 6, cursor on the last column
+    #   f.caret = 0                      # paints "hello " — left_column 0
     #
-    # The caret is a logical index in `0..text.length`. The hardware cursor is
-    # positioned by {Screen} after each repaint cycle when this component is
-    # focused; see {Component#cursor_position}.
-    class TextField < TextInput
+    # The field's width never bounds its contents — {#max_text_length} does, and
+    # only for typing.
+    #
+    # == Implementation details
+    #
+    # Two axes run through this class and are *not* interchangeable:
+    #
+    # - an **index** counts characters into {#text} — {#caret},
+    #   {#max_text_length}, `text[i]`, every edit;
+    # - a **column** counts terminal cells — {#rect}, {#left_column},
+    #   {#cursor_position}, a {MouseEvent}.
+    #
+    # They coincide only while every glyph is one column wide. A fullwidth CJK
+    # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
+    # column 6. Every crossing goes through the private `column_at` / `index_at`
+    # pair; adding an index to a column anywhere else is the bug those two exist
+    # to prevent.
+    #
+    # Indices count characters while widths measure grapheme clusters, but the
+    # caret never falls between the two: {AbstractStringField} keeps it on a
+    # cluster boundary, so a column derived from it always names a real glyph
+    # edge.
+    #
+    # What gets *painted* is {#display_text}, a third seam that is `text` itself
+    # here and the mask in {PasswordField}. Every column measurement reads it, so
+    # a subclass showing something else overrides that and never {#repaint} —
+    # overriding the paint alone leaves the measurements on the buffer while the
+    # cells show the substitute, and the two drift apart by a growing offset.
+    class TextField < AbstractStringField
       def initialize
         super
+        @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
+      # 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
+
+      # @param max [Integer, nil]
+      # @return [void]
+      # @raise [TypeError] unless `max` is an Integer or nil.
+      # @raise [ArgumentError] if `max` is negative.
+      def max_text_length=(max)
+        raise TypeError, "expected Integer or nil, got #{max.inspect}" unless max.nil? || max.is_a?(Integer)
+        raise ArgumentError, "expected a non-negative max, got #{max}" if max&.negative?
+
+        @max_text_length = max
+      end
+
+      # @return [Integer] text column drawn in the field's leftmost cell — the
+      #   horizontal scroll offset. Follows {#caret}, always on a glyph boundary.
+      attr_reader :left_column
+
       # 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`,
@@ -43,37 +96,33 @@ module Tuile
       def cursor_position
         return nil unless rect.width.positive?
 
-        Point.new(rect.left + @caret, rect.top)
+        # 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
+        # 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)
       end
 
+      # Places the caret at the clicked column. A click on the right half of a
+      # wide glyph lands *after* it, as in any editor.
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
         super
         return unless event.button == :left && rect.contains?(event.point)
 
-        self.caret = (event.x - rect.left).clamp(0, @text.length)
+        self.caret = index_at(event.x - rect.left + @left_column)
       end
 
       # @return [void]
       def repaint
         return if rect.empty?
 
-        padded = @text + (" " * (rect.width - @text.length))
-        screen.buffer.set_line(rect.left, rect.top, background(padded))
+        screen.buffer.set_line(rect.left, rect.top, background(visible_text))
       end
 
       protected
 
-      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
-      # their width.
-      # @param new_text [String]
-      # @return [String]
-      def preprocess_text(new_text)
-        new_text = new_text.to_s
-        new_text.length > max_text_length ? new_text[0, max_text_length] : new_text
-      end
-
       # @param key [String]
       # @return [Boolean]
       def handle_text_input_key(key)
@@ -102,32 +151,121 @@ module Tuile
         true
       end
 
+      # @return [void]
+      def on_text_mutated
+        adjust_left_column
+      end
+
+      # @return [void]
+      def on_caret_mutated
+        adjust_left_column
+      end
+
       # @return [void]
       def on_width_changed
         super
-        return if @text.length <= max_text_length
-
-        @text = @text[0, [max_text_length, 0].max]
-        @caret = @caret.clamp(0, @text.length)
-        @on_change&.call(@text)
+        adjust_left_column
       end
 
-      private
+      # What the field paints in place of {#text}: one display character per
+      # {#text} character, in order. `column_at` measures `display_text[0, i]` as
+      # the rendering of `text[0, i]`, so an override that changes the character
+      # count — or reorders — desynchronizes the caret from the display. Nothing
+      # enforces it at runtime; a subclass pins it with a spec.
+      # @return [String] {#text} itself, unless a subclass substitutes.
+      def display_text = @text
 
-      # Maximum number of characters {#text} can hold given current width.
-      # @return [Integer]
-      def max_text_length = (rect.width - 1).clamp(0, nil)
+      private
 
       # @param char [String]
-      # @return [Boolean]
+      # @return [Boolean] always true — a field at {#max_text_length} swallows the
+      #   key rather than declining it, so typing can never fall through to a
+      #   scope-wide binding.
       def insert(char)
-        return false if @text.length >= max_text_length
+        return true if @max_text_length && @text.length >= @max_text_length
 
         new_text = @text.dup.insert(@caret, char)
         @caret += 1
         self.text = new_text
         true
       end
+
+      # @param index [Integer] a {#text} index in `0..text.length`.
+      # @return [Integer] the column it sits at. An index landing inside a
+      #   grapheme cluster measures the whole cluster, putting the caret just
+      #   past it.
+      def column_at(index) = columns_of(display_text[0, index] || "")
+
+      # @param column [Integer] a text column (0 is the first glyph).
+      # @return [Integer] the nearest {#text} index — a column falling in a wide
+      #   glyph's right half resolves past it.
+      def index_at(column)
+        col = 0
+        i = 0
+        display_text.each_grapheme_cluster do |g|
+          w = Buffer.display_width(g)
+          return i if column < col + ((w + 1) / 2)
+
+          col += w
+          i += g.length
+        end
+        i
+      end
+
+      # @return [Integer] total display width of {#text}.
+      def text_columns = column_at(@text.length)
+
+      # @return [String] the windowed text, padded with spaces to `rect.width`.
+      #   A wide glyph straddling the right edge is dropped rather than painted
+      #   as a half glyph.
+      def visible_text
+        right = @left_column + rect.width
+        visible = +""
+        width = 0
+        col = 0
+        display_text.each_grapheme_cluster do |g|
+          start = col
+          col += Buffer.display_width(g)
+          next if start < @left_column
+          break if col > right
+
+          visible << g
+          width = col - @left_column
+        end
+        visible << (" " * (rect.width - width))
+      end
+
+      # Scrolls the minimum needed to keep the caret's column visible.
+      # @return [void]
+      def adjust_left_column
+        return unless rect.width.positive?
+
+        col = column_at(@caret)
+        @left_column = col if col < @left_column
+        @left_column = col - rect.width + 1 if col > @left_column + rect.width - 1
+        # The caret may park one column past the last glyph, so the scrollable
+        # range runs one column past the text.
+        @left_column = snap_to_glyph_start(@left_column.clamp(0, [text_columns - rect.width + 1, 0].max))
+      end
+
+      # @param column [Integer]
+      # @return [Integer] the smallest glyph-boundary column `>= column`, so the
+      #   window never opens on a wide glyph's right half.
+      #
+      # Snapping *right* is the only safe direction, and not because it shows
+      # more: the caret's own column is always a glyph boundary, so the next
+      # boundary at or after `left_column` can never overshoot it. Snapping left
+      # instead pulls the window's right edge inward, which strands the caret
+      # outside it whenever wide glyphs exactly fill a narrow field.
+      def snap_to_glyph_start(column)
+        col = 0
+        display_text.each_grapheme_cluster do |g|
+          return col if col >= column
+
+          col += Buffer.display_width(g)
+        end
+        col
+      end
     end
   end
 end

data/lib/tuile/component/text_view.rb

@@ -3,31 +3,25 @@
 module Tuile
   class Component
     # A read-only viewer for prose: chunks of formatted text that scroll
-    # vertically. Shape-wise a hybrid between {Label} (string-shaped content
-    # via {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
+    # vertically. Shape-wise a hybrid between {Label} (string content via
+    # {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
     #
-    # Text is modeled as a {StyledString}: embedded `\n` are hard line breaks,
-    # lines wider than the viewport are word-wrapped via {StyledString#wrap}
-    # (style spans are preserved across wrap boundaries — unlike the older
-    # ANSI-as-bytes wrapping, color does *not* get dropped on continuation
-    # rows). {#text=} accepts a {String} (parsed via {StyledString.parse},
-    # so embedded ANSI is honored) or a {StyledString} directly; {#text}
-    # always returns the {StyledString}.
+    # Text is a {StyledString}: embedded `\n` are hard line breaks, longer lines
+    # are word-wrapped via {StyledString#wrap} with style spans preserved across
+    # wrap boundaries. {#text=} takes a {String} (parsed via {StyledString.parse},
+    # honoring embedded ANSI) or a {StyledString}; {#text} always returns the
+    # {StyledString}.
     #
-    # For incremental updates pick the right primitive: {#append} (aliased
-    # as `<<`) is verbatim and stream-friendly — chunks are concatenated
-    # straight onto the buffer, with embedded `\n` becoming hard breaks.
-    # {#add_line} is the "log entry" convenience — it starts the content on
-    # a fresh line by inserting a leading `\n` when the buffer is non-empty.
-    # {#remove_last_n_lines} pops hard lines back off the tail — the
-    # inverse of building up a region with {#append} / {#add_line}, so a
-    # caller streaming reformattable content (e.g. partially-rendered
-    # Markdown that may need to retract its last paragraph) can replace
-    # the tail without rewriting the whole text. Turn on {#auto_scroll}
-    # to keep the latest content in view.
+    # Pick the right incremental primitive: {#append} (aliased `<<`) concatenates
+    # a chunk verbatim onto the buffer (stream-friendly, `\n` → hard breaks);
+    # {#add_line} starts the chunk on a fresh line (the "log entry" convenience);
+    # {#remove_last_n_lines} pops hard lines off the tail, so a caller streaming
+    # reformattable content can retract and rewrite it; {#replace} / {#insert}
+    # splice a range in place. Turn on {#auto_scroll} to keep the latest content
+    # in view.
     #
-    # TextView is meant to be the content of a {Window} — focus indication and
-    # keyboard-hint surfacing rely on the surrounding window chrome.
+    # Meant to be the content of a {Window} — focus indication and keyboard-hint
+    # surfacing rely on the surrounding window chrome.
     class TextView < Component
       def initialize
         super
@@ -55,21 +49,14 @@ module Tuile
         @auto_scroll = false
         @follow = true
         @scrollbar_visibility = :gone
-        # The view always has at least one region — an implicit default. It
-        # owns whatever hard lines exist that no later region claims. App
-        # code that never calls {#create_region} sees the same behavior as
-        # before (a single region containing everything); apps that do call
-        # {#create_region} stack additional regions at the spatial tail.
+        # Always ≥1 region; the implicit default owns any hard lines no
+        # app-created region claims. See {Region}.
         @regions = [Region.send(:new, self)]
       end
 
-      # @return [StyledString] the current text. Defaults to an empty
-      #   {StyledString}. Internally the text is stored as an array of hard
-      #   lines so {#append} can stay O(appended) instead of re-scanning the
-      #   whole buffer; the joined {StyledString} returned here is
-      #   reconstructed on first read after a mutation and cached, so
-      #   repeated reads are O(1) but the first read after {#append} pays
-      #   O(total spans).
+      # @return [StyledString] the current text (empty by default). Rebuilt
+      #   lazily on the first read after a mutation (O(total spans)), then
+      #   cached — repeated reads are O(1).
       def text
         @text ||= build_text
       end
@@ -144,19 +131,12 @@ module Tuile
       # @return [Boolean] true iff {#text} is empty (no hard lines).
       def empty? = @hard_lines.empty?
 
-      # Appends `str` verbatim. Embedded `\n` characters become hard line
-      # breaks; otherwise the text is concatenated onto the current last
-      # hard line. Designed for streaming use (e.g. an LLM chat window
-      # receiving partial messages — feed each chunk straight in). Accepts
-      # the same input forms as {#text=}; empty/`nil` input is a no-op.
-      #
-      # For the "add an entry on a new line" pattern use {#add_line}.
-      #
-      # Cost is O(appended + width-of-current-last-hard-line) — the
-      # previously last hard line is re-wrapped (because the extension may
-      # cause it to wrap differently), any additional hard lines created by
-      # embedded `\n` are wrapped fresh. The cached {#text} is invalidated
-      # and rebuilt on demand.
+      # Appends `str` verbatim. Embedded `\n` become hard line breaks; otherwise
+      # the text is concatenated onto the current last hard line. Designed for
+      # streaming use (feed each partial chunk straight in). Accepts the same
+      # input forms as {#text=}; empty/`nil` is a no-op. For the "entry on a new
+      # line" pattern use {#add_line}. Cost is O(appended + width of the last
+      # hard line), which is re-wrapped since the extension may wrap differently.
       # @param str [String, StyledString, nil]
       # @return [void]
       def append(str)
@@ -221,19 +201,11 @@ module Tuile
         end
       end
 
-      # Drops the last `n` hard lines from the buffer. The inverse of
-      # building up a tail region with {#append} / {#add_line}: a caller
-      # streaming partially-rendered content whose tail must occasionally
-      # be retracted (e.g. Markdown-to-ANSI where a new token reformats
-      # the table being built) can call `remove_last_n_lines(k)` followed
-      # by `append(new_tail)` to replace the damaged region in place.
-      #
-      # `n == 0` and the empty-buffer case are no-ops (no invalidation).
-      # `n >= hard-line count` empties the buffer.
-      #
-      # Operates on **hard lines** (the `\n`-delimited entries the
-      # buffer stores), not on wrapped physical rows — same granularity
-      # as {#add_line}. Cost is O(rendered-rows of the popped lines).
+      # Drops the last `n` hard lines from the buffer — the inverse of building
+      # up a tail with {#append} / {#add_line}, so a caller can `remove` then
+      # `append` to rewrite a damaged tail in place. Operates on **hard lines**
+      # (the `\n`-delimited entries), not wrapped physical rows. `n == 0` and the
+      # empty buffer are no-ops; `n >= hard-line count` empties the buffer.
       # @param n [Integer] number of hard lines to drop; must be >= 0.
       # @raise [TypeError] if `n` isn't an `Integer`.
       # @raise [ArgumentError] if `n` is negative.
@@ -266,40 +238,21 @@ module Tuile
         invalidate
       end
 
-      # Replaces a contiguous range of hard lines with the parsed content
-      # of `str`. The replacement is parsed exactly like {#text=} and
-      # {#append}: a {String} is run through {StyledString.parse} (so
-      # embedded ANSI is honored), a {StyledString} is used as-is, `nil`
-      # behaves like an empty replacement (the range is deleted). Embedded
-      # `"\n"` in the replacement produces multiple hard lines, so a single
-      # `replace` can grow or shrink the buffer.
+      # Replaces a contiguous range of hard lines with the parsed content of
+      # `str` (parsed like {#text=}: `String` → {StyledString.parse}, `nil` →
+      # empty, so `nil` deletes the range). Embedded `"\n"` yields multiple hard
+      # lines, so one `replace` can grow or shrink the buffer. `range` selects
+      # which hard lines to swap out:
       #
-      # `range` selects which hard lines to swap out:
-      #
-      # - an `Integer` `n` is shorthand for `n..n` (replace one existing
-      #   line — `n` must be in `[0, hard-line count)`);
-      # - a non-empty `Range` of hard-line indices replaces those lines;
-      # - an empty `Range` (e.g. `2...2`, or the canonical end-insertion
-      #   `hard_lines.size...hard_lines.size`) is *insertion* at that
-      #   position — no lines are removed. {#insert} is a thin alias for
-      #   this case.
-      #
-      # Endpoints must be non-negative integers; `begin` may equal
-      # `hard-line count` (insertion at the end), `end` may not exceed
-      # `hard-line count - 1`. `nil` endpoints (beginless / endless ranges)
-      # are not accepted.
-      #
-      # Cost is roughly `O(from + length + new content)`: the splice
-      # updates only the affected slice of the physical-row buffer, using
-      # the per-hard-line wrap-count cache to locate the starting offset
-      # without re-wrapping preceding lines. Lines outside the splice are
-      # never re-wrapped. {#top_line} is clamped if the new line count
-      # puts it past the end; {#auto_scroll} pins it to the bottom as
-      # usual. The call is a no-op (no invalidation) when the parsed
-      # replacement equals the covered range (vacuously true for an empty
-      # range plus empty replacement, so `replace(n...n, "")` is a cheap
-      # no-op).
+      # - an `Integer` `n` is shorthand for `n..n` (replace one existing line);
+      # - a non-empty `Range` replaces those lines;
+      # - an empty `Range` (e.g. `2...2`, or `size...size` at the end) is
+      #   *insertion* at that position — nothing removed. {#insert} aliases this.
       #
+      # Splices in place — only the affected slice of the physical-row buffer is
+      # touched, no preceding lines re-wrapped (cost O(from + length + new
+      # content)). A no-op when the replacement equals the covered range, so
+      # `replace(n...n, "")` is cheap.
       # @param range [Range, Integer] hard-line indices to replace.
       # @param str [String, StyledString, nil] replacement content.
       # @raise [TypeError] if `range` is neither an `Integer` nor a `Range`,
@@ -417,6 +370,8 @@ module Tuile
       # 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_line}, so content and blank rows inherit
+      # {Component#effective_bg_color} (a {#bg_color} set here or on an ancestor).
       # @return [void]
       def repaint
         return if rect.empty?
@@ -426,7 +381,7 @@ module Tuile
                     end
         (0...rect.height).each do |row|
           line = paintable_line(row + @top_line, row, scrollbar)
-          screen.buffer.set_line(rect.left, rect.top + row, line)
+          draw_line(rect.left, rect.top + row, line)
         end
       end
 
@@ -645,19 +600,12 @@ module Tuile
         invalidate
       end
 
-      # Adjusts region line counts after a {@hard_lines} splice that
-      # removed `removed_count` lines at index `from` and inserted
-      # `added_count` in their place. Two passes:
-      #
-      # 1. Subtract each region's overlap with the removed range (uses
-      #    the original counts to compute positions). Remember the first
-      #    region that lost lines — that's the natural home for the
-      #    replacement content.
-      # 2. Credit `added_count` to that region. For pure insertions (no
-      #    removal), there's no "first overlapping region" to pick from;
-      #    walk regions and credit the latest one starting at `from` (the
-      #    boundary tiebreaker matches the spatial-tail-routing of
-      #    {#append}). Past-the-end inserts fall back to the tail region.
+      # Adjusts region line counts after a {@hard_lines} splice that removed
+      # `removed_count` lines at `from` and inserted `added_count`. Subtracts
+      # each region's overlap with the removed range, then credits the added
+      # lines to the first region that lost lines. Pure insertions have no such
+      # region — they credit the latest region starting at `from`, matching
+      # {#append}'s spatial-tail routing (past-the-end falls back to the tail).
       # @param from [Integer]
       # @param removed_count [Integer]
       # @param added_count [Integer]
@@ -956,14 +904,9 @@ module Tuile
         end
 
         # Verbatim append into this region's tail. Same semantics as
-        # {TextView#append} but scoped to the region: embedded `"\n"`
-        # creates new hard lines within the region, no-leading-newline
-        # input extends the region's last hard line. Empty / `nil` input
-        # is a no-op (but still raises when detached). When the region is
-        # the spatial tail of the view, this uses the incremental
-        # {TextView#append} path; mid-document regions splice the affected
-        # slice of the physical-row buffer (lines outside the region are
-        # not re-wrapped).
+        # {TextView#append} but scoped: embedded `"\n"` creates new hard lines
+        # within the region, other input extends the region's last hard line.
+        # Empty / `nil` is a no-op (but still raises when detached).
         # @param str [String, StyledString, nil]
         # @raise [RuntimeError] when the region is detached.
         # @return [void]

data/lib/tuile/component/window.rb

@@ -13,12 +13,14 @@ module Tuile
     # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Component::HasContent
+      include Component::HasCaption
 
-      # @param caption [String]
-      def initialize(caption = "")
+      # @param caption [String, StyledString, nil] the border title, coerced
+      #   the same way {HasCaption#caption=} coerces it.
+      def initialize(caption = nil)
         super()
         @border_right = 1
-        @caption = caption
+        self.caption = caption
         @content = nil
         # Optional bottom-row widget slot (e.g. a search field), spanning the
         # full inner width; and optional bottom-border chrome text embedded in
@@ -75,10 +77,12 @@ module Tuile
         end
 
         old = @footer
-        old&.parent = nil
+        # Same slot-swap order as HasContent#content=: notified last, so the
+        # focus repair cascades into the new occupant rather than the old.
+        detach_child(old) unless old.nil?
         @footer = new_footer
         unless new_footer.nil?
-          new_footer.parent = self
+          add_child(new_footer) # appended: the footer paints over the border row
           new_footer.invalidate
           layout_footer
         end
@@ -86,11 +90,6 @@ module Tuile
         on_child_removed(old) unless old.nil?
       end
 
-      # @return [Array<Component>]
-      def children
-        @footer.nil? ? super : super + [@footer]
-      end
-
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
@@ -122,16 +121,6 @@ module Tuile
         layout(content)
       end
 
-      # @return [String] the current caption, empty by default.
-      attr_reader :caption
-
-      # Sets new caption and repaints the window.
-      # @param new_caption [String]
-      def caption=(new_caption)
-        @caption = new_caption
-        invalidate
-      end
-
       # Fully repaints the window: both frame and contents.
       #
       # Window deliberately paints over its entire rect (border around the
@@ -150,14 +139,6 @@ module Tuile
         repaint_border
       end
 
-      # @param key [String, nil]
-      # @return [void]
-      def key_shortcut=(key)
-        super
-        # The shortcut key is shown in the caption — repaint.
-        invalidate
-      end
-
       protected
 
       # @param content [Component]
@@ -166,9 +147,12 @@ module Tuile
         content.rect = Rect.new(rect.left + 1, rect.top + 1, rect.width - 1 - @border_right, rect.height - 2)
       end
 
-      # Paints the window border into the {Screen#buffer}. Title is clipped to
-      # the inner width so the box never overflows {#rect}; when the window is
-      # active the whole border is drawn in {Theme#active_border_color}.
+      # Paints the window border via {Component#draw_line}/{Component#draw_char},
+      # so the border cells inherit {Component#effective_bg_color} — a
+      # {Component#bg_color} on the window tints border and content alike. Both
+      # border lines are clipped by *display* width, so no caption overflows the
+      # box; when the window is active the whole border — the caption's own
+      # colors included — is drawn in {Theme#active_border_color}.
       # @return [void]
       def repaint_border
         return if rect.empty?
@@ -178,19 +162,28 @@ module Tuile
         top = rect.top
         left = rect.left
         inner_w = [w - 2, 0].max
-        title = frame_caption.to_s
-        title = title[0, inner_w] if title.length > inner_w
-        dashes = "─" * (inner_w - title.length)
 
         fg = active? ? screen.theme.active_border_color : nil
         bar = StyledString::Style.new(fg: fg)
-        buf = screen.buffer
-        buf.set_line(left, top, StyledString.styled("┌#{title}#{dashes}┐", fg: fg))
+        draw_line(left, top, top_border(inner_w, fg).slice(0, w))
         (1..(h - 2)).each do |dy|
-          buf.set_char(left, top + dy, "│", bar)
-          buf.set_char(left + w - 1, top + dy, "│", bar)
+          draw_char(left, top + dy, "│", bar)
+          draw_char(left + w - 1, top + dy, "│", bar)
         end
-        buf.set_line(left, top + h - 1, bottom_border(inner_w, fg)) if h >= 2
+        draw_line(left, top + h - 1, bottom_border(inner_w, fg).slice(0, w)) if h >= 2
+      end
+
+      # Builds the top border line: corners, {#caption} embedded at its own
+      # width, dashes filling the remainder. The caption keeps its own styling
+      # unless `fg` is set — an active window's border claims it.
+      # @param inner_w [Integer] the border's interior width.
+      # @param fg [Color, nil] the active-border color, or nil when inactive.
+      # @return [StyledString]
+      def top_border(inner_w, fg)
+        title = caption.slice(0, inner_w)
+        title = title.with_fg(fg) if fg
+        dashes = StyledString.styled("─" * (inner_w - title.display_width), fg: fg)
+        StyledString.styled("┌", fg: fg) + title + dashes + StyledString.styled("┐", fg: fg)
       end
 
       # Builds the bottom border line. The corners take the border color; the
@@ -212,14 +205,6 @@ module Tuile
         StyledString.styled("└", fg: fg) + interior + StyledString.styled("┘", fg: fg)
       end
 
-      # The caption text as it appears in the rendered border, including the
-      # shortcut prefix when {#key_shortcut} is set.
-      # @return [String]
-      def frame_caption
-        c = @caption || ""
-        key_shortcut.nil? ? c : "[#{key_shortcut}]-#{c}"
-      end
-
       private
 
       # Positions the footer over the bottom border row, spanning the full