tuile 0.2.0 → 0.4.0

data/lib/tuile/component/text_view.rb

@@ -0,0 +1,456 @@
+# frozen_string_literal: true
+
+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).
+    #
+    # 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}.
+    #
+    # 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.
+    #
+    # TextView is 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
+        # `@hard_lines` is the logical model — one entry per `\n`-delimited
+        # line of the original text, width-independent. `@physical_lines` is
+        # the rendered view — each hard line word-wrapped to `wrap_width`
+        # and padded with trailing blanks, so painting a row is a lookup.
+        # Resizing rebuilds `@physical_lines` from `@hard_lines`; `#append`
+        # extends both.
+        @hard_lines = []
+        @physical_lines = []
+        @text = StyledString::EMPTY
+        @content_size = Size::ZERO
+        @blank_line = StyledString::EMPTY
+        @top_line = 0
+        @auto_scroll = false
+        @scrollbar_visibility = :gone
+      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).
+      def text
+        @text ||= build_text
+      end
+
+      # @return [Integer] index of the first visible physical line.
+      attr_reader :top_line
+
+      # @return [Symbol] `:gone` or `:visible`.
+      attr_reader :scrollbar_visibility
+
+      # @return [Boolean] if true, mutating the text scrolls the viewport so
+      #   the last line stays in view. Default `false`.
+      attr_reader :auto_scroll
+
+      # Replaces the text. Embedded `\n` characters become hard line breaks.
+      # A `String` is parsed via {StyledString.parse} (so embedded ANSI is
+      # honored); a `StyledString` is used as-is; `nil` is coerced to an
+      # empty {StyledString}.
+      # @param value [String, StyledString, nil]
+      # @return [void]
+      def text=(value)
+        new_text = StyledString.parse(value)
+        return if text == new_text
+
+        @text = new_text
+        @hard_lines = new_text.empty? ? [] : new_text.lines
+        @content_size = compute_content_size
+        rewrap
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # @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.
+      # @param str [String, StyledString, nil]
+      # @return [void]
+      def append(str)
+        screen.check_locked
+        appended = StyledString.parse(str)
+        return if appended.empty?
+
+        new_segments = appended.lines
+        width = wrap_width
+
+        if empty?
+          new_segments.each do |hl|
+            @hard_lines << hl
+            append_physical_lines(hl, width)
+          end
+        else
+          extension = new_segments.first
+          unless extension.empty?
+            old_last = @hard_lines.pop
+            drop_physical_rows_for(old_last, width)
+            extended = old_last + extension
+            @hard_lines << extended
+            append_physical_lines(extended, width)
+          end
+          new_segments[1..].each do |hl|
+            @hard_lines << hl
+            append_physical_lines(hl, width)
+          end
+        end
+
+        @text = nil
+        @content_size = compute_content_size
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # Verbatim append, returning `self` for chainability (`view << a << b`).
+      # @param str [String, StyledString, nil]
+      # @return [self]
+      def <<(str)
+        append(str)
+        self
+      end
+
+      # Appends `str` as a new entry: starts a fresh hard line first (when
+      # the buffer is non-empty) and then appends `str`. Equivalent to
+      # `append("\n" + str)` on a non-empty buffer, or `append(str)` on an
+      # empty one. `nil` and `""` produce a blank entry on a non-empty
+      # buffer and a no-op on an empty buffer (matches the old `append`
+      # semantics for "log line" callers).
+      # @param str [String, StyledString, nil]
+      # @return [void]
+      def add_line(str)
+        parsed = StyledString.parse(str)
+        if empty?
+          append(parsed)
+        else
+          append(StyledString.plain("\n") + parsed)
+        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).
+      # @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.
+      # @return [void]
+      def remove_last_n_lines(n)
+        raise TypeError, "expected Integer, got #{n.inspect}" unless n.is_a?(Integer)
+        raise ArgumentError, "n must not be negative, got #{n}" if n.negative?
+
+        screen.check_locked
+        return if n.zero? || empty?
+
+        width = wrap_width
+        to_drop = [n, @hard_lines.size].min
+        to_drop.times do
+          popped = @hard_lines.pop
+          drop_physical_rows_for(popped, width)
+        end
+
+        @text = nil
+        @content_size = compute_content_size
+        @top_line = top_line_max if @top_line > top_line_max
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # Clears the text. Equivalent to `text = ""`.
+      # @return [void]
+      def clear
+        self.text = StyledString::EMPTY
+      end
+
+      # @param new_top_line [Integer] 0 or greater. Not clamped against the
+      #   number of lines (matches {List#top_line=}).
+      # @return [void]
+      def top_line=(new_top_line)
+        raise TypeError, "expected Integer, got #{new_top_line.inspect}" unless new_top_line.is_a? Integer
+        raise ArgumentError, "top_line must not be negative, got #{new_top_line}" if new_top_line.negative?
+        return if @top_line == new_top_line
+
+        @top_line = new_top_line
+        invalidate
+      end
+
+      # @param value [Symbol] `:gone` or `:visible`.
+      # @return [void]
+      def scrollbar_visibility=(value)
+        raise ArgumentError, "expected :gone or :visible, got #{value.inspect}" unless %i[gone visible].include?(value)
+        return if @scrollbar_visibility == value
+
+        @scrollbar_visibility = value
+        rewrap
+        invalidate
+      end
+
+      # Sets `auto_scroll`. If true, immediately scrolls to the bottom.
+      # @param value [Boolean]
+      # @return [void]
+      def auto_scroll=(value)
+        @auto_scroll = value ? true : false
+        update_top_line_if_auto_scroll
+      end
+
+      def focusable? = true
+
+      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)
+        return false unless active?
+        return true if super
+
+        case key
+        when *Keys::DOWN_ARROWS then move_top_line_by(1)
+        when *Keys::UP_ARROWS   then move_top_line_by(-1)
+        when Keys::PAGE_DOWN    then move_top_line_by(viewport_lines)
+        when Keys::PAGE_UP      then move_top_line_by(-viewport_lines)
+        when Keys::CTRL_D       then move_top_line_by(viewport_lines / 2)
+        when Keys::CTRL_U       then move_top_line_by(-viewport_lines / 2)
+        when *Keys::HOMES, "g"  then move_top_line_to(0)
+        when *Keys::ENDS_, "G"  then move_top_line_to(top_line_max)
+        else return false
+        end
+        true
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        case event.button
+        when :scroll_down then move_top_line_by(4)
+        when :scroll_up   then move_top_line_by(-4)
+        end
+      end
+
+      # Paints the text into {#rect}.
+      #
+      # 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.
+      # @return [void]
+      def repaint
+        return if rect.empty?
+
+        scrollbar = if scrollbar_visible?
+                      VerticalScrollBar.new(rect.height, line_count: @physical_lines.size, top_line: @top_line)
+                    end
+        (0...rect.height).each do |row|
+          line = paintable_line(row + @top_line, row, scrollbar)
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + row), line
+        end
+      end
+
+      protected
+
+      # Rewraps the text on width changes. Wrap width depends on
+      # {#rect}`.width` and the scrollbar gutter, both of which trigger
+      # this hook.
+      # @return [void]
+      def on_width_changed
+        super
+        rewrap
+      end
+
+      private
+
+      # @return [Integer] number of visible lines.
+      def viewport_lines = rect.height
+
+      # @return [Integer] the max value of {#top_line} for scroll-key clamping.
+      def top_line_max = (@physical_lines.size - viewport_lines).clamp(0, nil)
+
+      # Recomputes {@physical_lines} for the current text and wrap width,
+      # pre-padding every line to `wrap_width` so {#paintable_line} is just
+      # a lookup + optional scrollbar-char append at paint time (and the
+      # rendered ANSI is cached on each line via {StyledString#to_ansi}'s
+      # memoization, so re-painting on scroll is near-free). Clamps
+      # {@top_line} if the new line count puts it out of range.
+      # @return [void]
+      def rewrap
+        width = wrap_width
+        @blank_line = pad_to(StyledString::EMPTY, width)
+        @physical_lines = []
+        @hard_lines.each { |hl| append_physical_lines(hl, width) }
+        @top_line = top_line_max if @top_line > top_line_max
+      end
+
+      # Wraps `hard_line` at `width` and appends the padded physical lines
+      # to {@physical_lines}. Empty hard lines (e.g. from a `"\n\n"` run)
+      # and degenerate `width <= 0` both emit a single {@blank_line} row,
+      # matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # would have produced for those cases.
+      # @param hard_line [StyledString] one hard-broken line (no embedded `"\n"`).
+      # @param width [Integer]
+      # @return [void]
+      def append_physical_lines(hard_line, width)
+        if hard_line.empty? || width <= 0
+          @physical_lines << @blank_line
+        else
+          hard_line.wrap(width).each { |line| @physical_lines << pad_to(line, width) }
+        end
+      end
+
+      # Pops from {@physical_lines} the rows that `hard_line` previously
+      # contributed (the inverse of {#append_physical_lines} for the same
+      # input). Used by {#append} when extending the last hard line: its
+      # old wrapped rows are dropped, then the extended hard line is
+      # re-wrapped and appended.
+      # @param hard_line [StyledString]
+      # @param width [Integer]
+      # @return [void]
+      def drop_physical_rows_for(hard_line, width)
+        count = hard_line.empty? || width <= 0 ? 1 : hard_line.wrap(width).size
+        count.times { @physical_lines.pop }
+      end
+
+      # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
+      # default-styled `"\n"` between hard lines. Called from the {#text}
+      # reader when the cache is cold. Cost is O(total spans).
+      # @return [StyledString]
+      def build_text
+        return StyledString::EMPTY if @hard_lines.empty?
+        return @hard_lines.first if @hard_lines.size == 1
+
+        newline = StyledString::Span.new(text: "\n", style: StyledString::Style::DEFAULT)
+        spans = []
+        @hard_lines.each_with_index do |hl, i|
+          spans << newline if i.positive?
+          spans.concat(hl.spans)
+        end
+        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.
+      def wrap_width
+        return 0 if rect.width <= 0
+
+        rect.width - (scrollbar_visible? ? 1 : 0)
+      end
+
+      # @param delta [Integer] negative scrolls up, positive scrolls down.
+      # @return [void]
+      def move_top_line_by(delta)
+        move_top_line_to(@top_line + delta)
+      end
+
+      # @param target [Integer] desired top line; clamped to `[0, top_line_max]`.
+      # @return [void]
+      def move_top_line_to(target)
+        clamped = target.clamp(0, top_line_max)
+        self.top_line = clamped unless @top_line == clamped
+      end
+
+      # @return [void]
+      def update_top_line_if_auto_scroll
+        return unless @auto_scroll
+
+        target = (@physical_lines.size - viewport_lines).clamp(0, nil)
+        self.top_line = target if @top_line != target
+      end
+
+      # @return [Boolean]
+      def scrollbar_visible?
+        return false if rect.empty?
+
+        @scrollbar_visibility == :visible
+      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 line [StyledString]
+      # @param width [Integer]
+      # @return [StyledString]
+      def pad_to(line, width)
+        return StyledString::EMPTY if width <= 0
+
+        diff = width - line.display_width
+        return line if diff <= 0
+
+        line + StyledString.plain(" " * diff)
+      end
+
+      # @param index [Integer] 0-based index into `@physical_lines`.
+      # @param row_in_viewport [Integer] 0-based row within the viewport.
+      # @param scrollbar [VerticalScrollBar, nil]
+      # @return [String] paintable ANSI-encoded line exactly `rect.width`
+      #   columns wide. Body lines come pre-padded from {#rewrap}, so this
+      #   reduces to a memoized {StyledString#to_ansi} read plus an
+      #   ASCII-string concat of the scrollbar glyph when one is present.
+      def paintable_line(index, row_in_viewport, scrollbar)
+        line = @physical_lines[index] || @blank_line
+        return line.to_ansi unless scrollbar
+
+        line.to_ansi + scrollbar.scrollbar_char(row_in_viewport)
+      end
+    end
+  end
+end

data/lib/tuile/component/window.rb

@@ -8,8 +8,9 @@ module Tuile
     #
     # The window's `content` is unset by default; assign one via {#content=}.
     #
-    # Window is considered invisible if {#rect} is empty or one of left/top is
-    # negative. The window won't draw when invisible.
+    # Window is considered invisible if {#rect} is empty. The window won't
+    # draw when invisible. (Repaint of detached windows is short-circuited
+    # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Component::HasContent
 
@@ -90,9 +91,9 @@ module Tuile
       # @param value [Boolean]
       # @return [void]
       def scrollbar=(value)
-        unless content.is_a?(Component::List)
+        unless content.respond_to?(:scrollbar_visibility=)
           raise Tuile::Error,
-                "scrollbar= requires a Component::List as content, got #{content.inspect}"
+                "scrollbar= requires a content component that supports scrollbar_visibility=, got #{content.inspect}"
         end
 
         content.scrollbar_visibility = value ? :visible : :gone
@@ -125,12 +126,6 @@ module Tuile
         Size.new(inner_w + 2, inner_h + 2)
       end
 
-      # @return [Boolean] true if {#rect} is off screen and the window won't
-      #   paint.
-      def visible?
-        !@rect.empty? && !@rect.top.negative? && !@rect.left.negative?
-      end
-
       # Fully repaints the window: both frame and contents.
       #
       # Window deliberately paints over its entire rect (border around the
@@ -143,7 +138,7 @@ module Tuile
       # cycle.
       # @return [void]
       def repaint
-        return unless visible?
+        return if rect.empty?
 
         super
         repaint_border
@@ -168,7 +163,7 @@ module Tuile
       # Paints the window border.
       # @return [void]
       def repaint_border
-        return unless visible?
+        return if rect.empty?
 
         frame = build_frame(frame_caption)
         frame = Rainbow(frame).green if active?

data/lib/tuile/component.rb

@@ -4,8 +4,10 @@ module Tuile
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   #
-  # Component is considered invisible if {#rect} is empty or one of left/top is
-  # negative. The component won't draw when invisible.
+  # Painting is gated by attachment: a detached component (one whose {#root}
+  # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
+  # any stale invalidation entries are filtered out at drain time. Subclasses
+  # can paint freely in {#repaint} without re-asserting attachment.
   class Component
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
@@ -66,9 +68,11 @@ module Tuile
     # responsibility for {#rect}. Everything else should call super.
     #
     # A component must not draw outside of {#rect}.
+    #
+    # Only called when the component is attached.
     # @return [void]
     def repaint
-      return if rect.empty? || rect.left.negative? || rect.top.negative?
+      return if rect.empty?
       return if children.any? && children_tile_rect?
 
       clear_background
@@ -251,8 +255,16 @@ module Tuile
 
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
+    #
+    # No-op when the component is not {#attached?} — a detached component has
+    # no place on the screen to paint to, so {Screen} must never end up
+    # repainting it. Callers don't need to guard their own `invalidate` calls;
+    # mutating a detached component (e.g. setting `lines=` on a {List} sitting
+    # inside a closed {Component::Popup}) is silent.
     # @return [void]
     def invalidate
+      return unless attached?
+
       screen.invalidate(self)
     end
 

data/lib/tuile/keys.rb

@@ -42,19 +42,71 @@ module Tuile
     # @return [String]
     PAGE_DOWN = "\e[6~"
     # @return [String]
-    BACKSPACE = ""
+    BACKSPACE = "\x7f"
     # @return [String]
     DELETE = "\e[3~"
+
+    # Ctrl+letter sends bytes 0x01..0x1a. Note that {CTRL_H} == `"\b"`,
+    # {CTRL_I} == {TAB}, {CTRL_J} == `"\n"`, and {CTRL_M} == {ENTER} —
+    # terminals deliver these key combinations indistinguishably from the
+    # corresponding named keys.
+    # @return [String]
+    CTRL_A = "\x01"
+    # @return [String]
+    CTRL_B = "\x02"
+    # @return [String]
+    CTRL_C = "\x03"
+    # @return [String]
+    CTRL_D = "\x04"
+    # @return [String]
+    CTRL_E = "\x05"
+    # @return [String]
+    CTRL_F = "\x06"
+    # @return [String]
+    CTRL_G = "\x07"
     # @return [String]
     CTRL_H = "\b"
-    # @return [Array<String>]
-    BACKSPACES = [BACKSPACE, CTRL_H].freeze
     # @return [String]
-    CTRL_U = ""
+    CTRL_I = "\t"
+    # @return [String]
+    CTRL_J = "\n"
+    # @return [String]
+    CTRL_K = "\x0b"
+    # @return [String]
+    CTRL_L = "\x0c"
+    # @return [String]
+    CTRL_M = "\r"
+    # @return [String]
+    CTRL_N = "\x0e"
+    # @return [String]
+    CTRL_O = "\x0f"
+    # @return [String]
+    CTRL_P = "\x10"
     # @return [String]
-    CTRL_D = ""
+    CTRL_Q = "\x11"
     # @return [String]
-    ENTER = "
+    CTRL_R = "\x12"
+    # @return [String]
+    CTRL_S = "\x13"
+    # @return [String]
+    CTRL_T = "\x14"
+    # @return [String]
+    CTRL_U = "\x15"
+    # @return [String]
+    CTRL_V = "\x16"
+    # @return [String]
+    CTRL_W = "\x17"
+    # @return [String]
+    CTRL_X = "\x18"
+    # @return [String]
+    CTRL_Y = "\x19"
+    # @return [String]
+    CTRL_Z = "\x1a"
+
+    # @return [Array<String>]
+    BACKSPACES = [BACKSPACE, CTRL_H].freeze
+    # @return [String]
+    ENTER = "\r"
     # @return [String]
     TAB = "\t"
     # The terminal sequence emitted by Shift+Tab in xterm-style terminals
@@ -62,6 +114,22 @@ module Tuile
     # @return [String]
     SHIFT_TAB = "\e[Z"
 
+    # True iff `key` is a single printable character — a one-character string
+    # whose codepoint is not in Unicode's C (Other) category. Rejects multi-
+    # character escape sequences ({UP_ARROW}, mouse events, …), control bytes
+    # ({TAB}, {ENTER}, {ESC}, {CTRL_A}..{CTRL_Z}, {BACKSPACE}), and the empty
+    # string; accepts ASCII letters/digits/punctuation/space *and* non-ASCII
+    # printables like "é".
+    #
+    # Used by {Screen#register_global_shortcut} to reject keys that would
+    # collide with typing, and by {Tuile::Component::TextField} to decide
+    # whether to insert a key at the caret.
+    # @param key [String]
+    # @return [Boolean]
+    def self.printable?(key)
+      key.length == 1 && !key.match?(/\p{C}/)
+    end
+
     # Grabs a key from stdin and returns it. Blocks until the key is obtained.
     # Reads a full ESC key sequence; see constants above for some values returned
     # by this function.
@@ -72,11 +140,26 @@ module Tuile
 
       # Escape sequence. Try to read more data.
       begin
-        # Read 6 chars: mouse events are e.g. `\e[Mxyz`
-        char += $stdin.read_nonblock(6)
+        # Read up to 5 bytes: that's the maximum tail length of any escape
+        # sequence Tuile recognizes after the initial \e (X10 mouse `[Mbxy`,
+        # CTRL+arrow `[1;5D`, etc.). Reading 6 here would over-read into the
+        # next sequence on tight mouse-event bursts — we'd silently steal
+        # the next event's leading \e and the rest of it would surface as
+        # individual printable keypresses in focused inputs.
+        char += $stdin.read_nonblock(5)
       rescue IO::EAGAINWaitReadable
         # The "ESC" key pressed => only the \e char is emitted.
+        return char
+      end
+
+      # If `read_nonblock` returned a partial X10 mouse-report prefix (the
+      # sequence is fixed-length: 3 bytes after `\e[M`), drain the remainder
+      # with a blocking read so the parser downstream sees a complete event
+      # instead of leaking tail bytes as keypresses.
+      if char.start_with?("\e[M") && char.bytesize < 6
+        char += $stdin.read(6 - char.bytesize)
       end
+
       char
     end
   end