ruvim 0.3.0 → 0.6.0

data/lib/ruvim/screen.rb

@@ -26,7 +26,7 @@ module RuVim
 
       rects = window_rects(editor, text_rows:, text_cols:)
       if (current_rect = rects[editor.current_window_id])
-        editor.current_window_view_height_hint = [current_rect[:height].to_i, 1].max
+        editor.current_window_view_height_hint = [current_rect[:height], 1].max
       end
       editor.window_order.each do |win_id|
         win = editor.windows.fetch(win_id)
@@ -69,7 +69,12 @@ module RuVim
             end
       cursor_row, cursor_col = cursor_screen_position(editor, text_rows, rects)
       out << "\e[#{cursor_row};#{cursor_col}H"
-      out << "\e[?25h"
+      if cursor_use_terminal?(editor)
+        out << "\e[6 q"
+        out << "\e[?25h"
+      else
+        out << "\e[?25l"
+      end
       @last_frame = frame.merge(cursor_row:, cursor_col:)
       @terminal.write(out)
     end
@@ -80,7 +85,7 @@ module RuVim
       text_rows = [text_rows, 1].max
       text_cols = [text_cols, 1].max
       rect = window_rects(editor, text_rows:, text_cols:)[editor.current_window_id]
-      height = [rect ? rect[:height].to_i : text_rows, 1].max
+      height = [rect ? rect[:height] : text_rows, 1].max
       editor.current_window_view_height_hint = height if editor.respond_to?(:current_window_view_height_hint=)
       height
     rescue StandardError
@@ -105,6 +110,8 @@ module RuVim
           lines[status_row + 1] = truncate("#{cmd.prefix}#{cmd.text}", cols)
         elsif editor.message_error?
           lines[status_row + 1] = error_message_line(editor.message.to_s, cols)
+        elsif !editor.message.to_s.empty?
+          lines[status_row + 1] = truncate(editor.message.to_s, cols)
         end
       end
 
@@ -275,15 +282,48 @@ module RuVim
     end
 
     def render_text_line(text, editor, buffer_row:, window:, buffer:, width:)
+      # Ultra-fast path: plain ASCII line with no highlighting — skip Cell creation entirely
+      if can_bulk_render_line?(text, editor, buffer_row:, window:, buffer:)
+        return bulk_render_line(text, width, col_offset: window.col_offset)
+      end
+
       tabstop = tabstop_for(editor, window, buffer)
       cells, display_col = RuVim::TextMetrics.clip_cells_for_width(text, width, source_col_start: window.col_offset, tabstop:)
       render_cells(cells, display_col, editor, buffer_row:, window:, buffer:, width:, source_line: buffer.line_at(buffer_row),
                    source_col_offset: window.col_offset, leading_display_prefix: "")
     end
 
+    def can_bulk_render_line?(text, editor, buffer_row:, window:, buffer:)
+      return false if editor.current_window_id == window.id && window.cursor_y == buffer_row
+      return false if editor.current_window_id == window.id && editor.visual_active?
+      return false if !!editor.effective_option("cursorline", window:, buffer:)
+      return false if !!editor.effective_option("list", window:, buffer:)
+      return false unless colorcolumn_display_cols(editor, window, buffer).empty?
+      return false if text.include?("\t")
+      return false unless text.ascii_only?
+      return false if text.match?(/[\x00-\x1f\x7f]/)  # control chars need sanitizing
+
+      source_text = text[window.col_offset..].to_s
+      return false unless search_highlight_source_cols(editor, source_text, source_col_offset: window.col_offset).empty?
+      return false unless syntax_highlight_source_cols(editor, window, buffer, source_text, source_col_offset: window.col_offset).empty?
+
+      true
+    end
+
+    def bulk_render_line(text, width, col_offset:)
+      clipped = text[col_offset, width].to_s
+      clipped + (" " * [width - clipped.length, 0].max)
+    end
+
     def render_text_segment(source_line, editor, buffer_row:, window:, buffer:, width:, source_col_start:, display_prefix: "")
+      prefix = display_prefix
+
+      # Bulk path: no prefix, printable ASCII, no highlighting
+      if prefix.empty? && can_bulk_render_line?(source_line, editor, buffer_row:, window:, buffer:)
+        return bulk_render_line(source_line, width, col_offset: source_col_start)
+      end
+
       tabstop = tabstop_for(editor, window, buffer)
-      prefix = display_prefix.to_s
       prefix_w = RuVim::DisplayWidth.display_width(prefix, tabstop:)
       avail = [width - prefix_w, 0].max
       cells, display_col = RuVim::TextMetrics.clip_cells_for_width(source_line[source_col_start..].to_s, avail, source_col_start:, tabstop:)
@@ -295,7 +335,6 @@ module RuVim
         body
       else
         prefix_render = RuVim::TextMetrics.pad_plain_to_screen_width(prefix, [width, 0].max, tabstop:)[0...prefix.length].to_s
-        # body already includes padding for avail; prepend the visible prefix and trim to width.
         out = prefix_render + body
         out
       end
@@ -319,28 +358,38 @@ module RuVim
       leading_prefix_width = RuVim::DisplayWidth.display_width(leading_display_prefix.to_s, tabstop:)
       display_pos = leading_prefix_width
 
-      cells.each do |cell|
-        ch = display_glyph_for_cell(cell, source_line, list_enabled:, listchars:, tab_seen:, trail_from:)
-        buffer_col = cell.source_col
-        selected = selected_in_visual?(visual, buffer_row, buffer_col)
-        cursor_here = (editor.current_window_id == window.id && window.cursor_y == buffer_row && window.cursor_x == buffer_col)
-        colorcolumn_here = colorcolumns[display_pos]
-        if cursor_here
-          highlighted << cursor_cell_render(editor, ch)
-        elsif selected
-          highlighted << "\e[7m#{ch}\e[m"
-        elsif search_cols[buffer_col]
-          highlighted << "#{search_bg_seq(editor)}#{ch}\e[m"
-        elsif colorcolumn_here
-          highlighted << "#{colorcolumn_bg_seq(editor)}#{ch}\e[m"
-        elsif cursorline_enabled
-          highlighted << "#{cursorline_bg_seq(editor)}#{ch}\e[m"
-        elsif (syntax_color = syntax_cols[buffer_col])
-          highlighted << "#{syntax_color}#{ch}\e[m"
-        else
-          highlighted << ch
+      # Fast path: no highlighting needed — bulk output glyphs
+      if !current_line && !visual && !cursorline_enabled &&
+         !list_enabled && search_cols.empty? &&
+         syntax_cols.empty? && colorcolumns.empty?
+        cells.each do |cell|
+          highlighted << cell.glyph
+          display_pos += [cell.display_width, 1].max
+        end
+      else
+        cells.each do |cell|
+          ch = display_glyph_for_cell(cell, source_line, list_enabled, listchars, tab_seen, trail_from)
+          buffer_col = cell.source_col
+          selected = selected_in_visual?(visual, buffer_row, buffer_col)
+          cursor_here = (current_line && window.cursor_x == buffer_col)
+          colorcolumn_here = colorcolumns[display_pos]
+          if cursor_here
+            highlighted << cursor_cell_render(editor, ch)
+          elsif selected
+            highlighted << "\e[7m#{ch}\e[m"
+          elsif search_cols[buffer_col]
+            highlighted << "#{search_bg_seq(editor)}#{ch}\e[m"
+          elsif colorcolumn_here
+            highlighted << "#{colorcolumn_bg_seq(editor)}#{ch}\e[m"
+          elsif cursorline_enabled
+            highlighted << "#{cursorline_bg_seq(editor)}#{ch}\e[m"
+          elsif (syntax_color = syntax_cols[buffer_col])
+            highlighted << "#{syntax_color}#{ch}\e[m"
+          else
+            highlighted << ch
+          end
+          display_pos += [cell.display_width, 1].max
         end
-        display_pos += [cell.display_width.to_i, 1].max
       end
 
       if editor.current_window_id == window.id && window.cursor_y == buffer_row
@@ -379,7 +428,7 @@ module RuVim
 
       base = RuVim::TextMetrics.screen_col_for_char_index(source_line, cursor_x, tabstop:) -
              RuVim::TextMetrics.screen_col_for_char_index(source_line, source_col_offset, tabstop:)
-      extra = [cursor_x.to_i - source_line.to_s.length, 0].max
+      extra = [cursor_x - source_line.length, 0].max
       leading_prefix_width + [base, 0].max + extra
     end
 
@@ -411,7 +460,7 @@ module RuVim
         raw_lines << (row < buffer.line_count ? buffer.line_at(row) : nil)
       end
 
-      non_nil = raw_lines.compact
+      non_nil = raw_lines.compact.map { |l| RuVim::TextMetrics.terminal_safe_text(l) }
       context = rich_view_context(editor, window, buffer)
       formatted = RuVim::RichView.render_visible_lines(editor, non_nil, context: context)
       fmt_idx = 0
@@ -456,7 +505,7 @@ module RuVim
     def render_rich_view_line_sc(text, width:, skip_sc:)
       # Phase 1: skip `skip_sc` display columns
       # Collect ANSI sequences encountered during skip so active styles carry over.
-      chars = text.to_s
+      chars = text
       pos = 0
       skipped = 0
       len = chars.length
@@ -546,9 +595,9 @@ module RuVim
     end
 
     def ensure_visible_under_wrap(editor, window, buffer, height:, content_w:)
-      return if height.to_i <= 0 || buffer.line_count <= 0
+      return if height <= 0 || buffer.line_count <= 0
 
-      window.row_offset = [[window.row_offset.to_i, 0].max, buffer.line_count - 1].min
+      window.row_offset = [[window.row_offset, 0].max, buffer.line_count - 1].min
       return if window.cursor_y < window.row_offset
 
       cursor_line = buffer.line_at(window.cursor_y)
@@ -641,7 +690,6 @@ module RuVim
       linebreak = !!editor.effective_option("linebreak", window:, buffer:)
       showbreak = editor.effective_option("showbreak", window:, buffer:).to_s
       breakindent = !!editor.effective_option("breakindent", window:, buffer:)
-      line = line.to_s
       return [{ source_col_start: 0, display_prefix: "" }] if line.empty?
 
       cache_key = [line.object_id, line.length, line.hash, width, tabstop, linebreak, showbreak, breakindent]
@@ -652,7 +700,10 @@ module RuVim
       indent_prefix = breakindent ? wrapped_indent_prefix(line, tabstop:, max_width: [width - RuVim::DisplayWidth.display_width(showbreak, tabstop:), 0].max) : ""
       segs = compute_wrapped_segments(line, width:, tabstop:, linebreak:, showbreak:, indent_prefix:)
       @wrapped_segments_cache[cache_key] = segs
-      @wrapped_segments_cache.shift while @wrapped_segments_cache.length > WRAP_SEGMENTS_CACHE_LIMIT
+      if @wrapped_segments_cache.length > WRAP_SEGMENTS_CACHE_LIMIT
+        trim = @wrapped_segments_cache.length - WRAP_SEGMENTS_CACHE_LIMIT / 2
+        trim.times { @wrapped_segments_cache.shift }
+      end
       segs
     end
 
@@ -679,7 +730,7 @@ module RuVim
         end
 
         segs << { source_col_start: start_col, display_prefix: display_prefix }.freeze
-        next_start = cells.last.source_col.to_i + 1
+        next_start = cells.last.source_col + 1
         if linebreak
           next_start += 1 while next_start < line.length && line[next_start] == " "
         end
@@ -693,7 +744,7 @@ module RuVim
     end
 
     def wrapped_segment_index(segs, cursor_x)
-      x = cursor_x.to_i
+      x = cursor_x
       seg_index = 0
       segs.each_with_index do |seg, i|
         nxt = segs[i + 1]
@@ -723,7 +774,7 @@ module RuVim
       ""
     end
 
-    def display_glyph_for_cell(cell, source_line, list_enabled:, listchars:, tab_seen:, trail_from:)
+    def display_glyph_for_cell(cell, source_line, list_enabled, listchars, tab_seen, trail_from)
       return cell.glyph unless list_enabled
 
       src = source_line[cell.source_col]
@@ -742,7 +793,7 @@ module RuVim
     end
 
     def parse_listchars(raw)
-      raw_key = raw.to_s
+      raw_key = raw
       @listchars_cache ||= {}
       return @listchars_cache[raw_key] if @listchars_cache.key?(raw_key)
 
@@ -786,6 +837,12 @@ module RuVim
     end
 
     def number_column_width(editor, window, buffer)
+      labels = buffer.options["gutter_labels"]
+      if labels && !labels.empty?
+        max_w = labels.map { |l| RuVim::DisplayWidth.display_width(l.to_s) }.max || 0
+        return max_w
+      end
+
       sign_w = sign_column_width(editor, window, buffer)
       enabled = editor.effective_option("number", window:, buffer:) || editor.effective_option("relativenumber", window:, buffer:)
       return sign_w unless enabled
@@ -817,6 +874,15 @@ module RuVim
     end
 
     def render_gutter_prefix(editor, window, buffer, buffer_row, width)
+      labels = buffer.options["gutter_labels"]
+      if labels
+        return " " * width if buffer_row.nil?
+
+        label = (labels[buffer_row] || "").ljust(width)[0, width]
+        color = line_number_fg_seq(editor, current_line: false)
+        return "#{color}#{label}\e[m"
+      end
+
       prefix = line_number_prefix(editor, window, buffer, buffer_row, width)
       return prefix if prefix.empty?
       return prefix if buffer_row.nil?
@@ -871,15 +937,19 @@ module RuVim
     end
 
     def search_bg_seq(editor)
-      truecolor_enabled?(editor) ? "\e[48;2;255;215;0m" : "\e[43m"
+      term_color(editor, "\e[48;2;255;215;0m", "\e[43m")
     end
 
     def colorcolumn_bg_seq(editor)
-      truecolor_enabled?(editor) ? "\e[48;2;72;72;72m" : "\e[48;5;238m"
+      term_color(editor, "\e[48;2;72;72;72m", "\e[48;5;238m")
     end
 
     def cursorline_bg_seq(editor)
-      truecolor_enabled?(editor) ? "\e[48;2;58;58;58m" : "\e[48;5;236m"
+      term_color(editor, "\e[48;2;58;58;58m", "\e[48;5;236m")
+    end
+
+    def term_color(editor, truecolor_seq, fallback_seq)
+      truecolor_enabled?(editor) ? truecolor_seq : fallback_seq
     end
 
     def line_number_fg_seq(editor, current_line: false)
@@ -911,34 +981,15 @@ module RuVim
 
       path = buffer.display_name
       mod = buffer.modified? ? " [+]" : ""
-      stream = stream_status_token(buffer)
-      loading = file_loading_status_token(buffer)
+      stream = buffer.stream_status ? " [#{buffer.stream_status}]" : ""
+      cmd = buffer.stream_command ? " #{buffer.stream_command}" : ""
       tab = tab_status_token(editor)
-      msg = editor.message_error? ? "" : editor.message.to_s
-      left = "#{mode} #{path}#{mod}#{stream}#{loading}"
+      left = "#{mode} #{path}#{mod}#{stream}#{cmd}"
       right = " #{window.cursor_y + 1}:#{window.cursor_x + 1}#{tab} "
       body_width = [width - right.length, 0].max
-      "#{compose_status_body(left, msg, body_width)}#{right}"
+      "#{left.ljust(body_width)[0, body_width]}#{right}"
     end
 
-    def stream_status_token(buffer)
-      return "" unless buffer.respond_to?(:stream_state)
-      return "" unless buffer.kind == :stream
-
-      state = (buffer.stream_state || :live).to_s
-      " [stdin/#{state}]"
-    end
-
-    def file_loading_status_token(buffer)
-      return "" unless buffer.respond_to?(:loading_state)
-      return "" unless buffer.file_buffer?
-
-      state = buffer.loading_state
-      return "" unless state
-      return "" if state.to_sym == :closed
-
-      " [load/#{state}]"
-    end
 
     def tab_status_token(editor)
       return "" if editor.tabpage_count <= 1
@@ -946,20 +997,6 @@ module RuVim
       " tab:#{editor.current_tabpage_number}/#{editor.tabpage_count}"
     end
 
-    def compose_status_body(left, msg, width)
-      w = [width.to_i, 0].max
-      return "" if w.zero?
-      return left.ljust(w)[0, w] if msg.to_s.empty?
-
-      msg_part = " | #{msg}"
-      if msg_part.length >= w
-        return msg_part[0, w]
-      end
-
-      left_budget = w - msg_part.length
-      "#{left.ljust(left_budget)[0, left_budget]}#{msg_part}"
-    end
-
     def truncate(str, width)
       safe = RuVim::TextMetrics.terminal_safe_text(str)
       RuVim::TextMetrics.pad_plain_to_screen_width(safe, width)
@@ -977,6 +1014,16 @@ module RuVim
       "\e[7m"
     end
 
+    # Insert/command-line: show terminal bar cursor; otherwise: hide terminal cursor, use cell rendering
+    def cursor_use_terminal?(editor)
+      case editor.mode
+      when :insert, :command_line
+        true
+      else
+        false
+      end
+    end
+
     def cursor_screen_position(editor, text_rows, rects)
       window = editor.current_window
 
@@ -1028,12 +1075,12 @@ module RuVim
                             RuVim::TextMetrics.screen_col_for_char_index(line, window.col_offset, tabstop:)
         col = rect[:left] + gutter_w + [prefix_screen_col, 0].max + extra_virtual
       end
-      min_row = [rect[:top].to_i, 1].max
-      max_row = [rect[:top].to_i + [rect[:height].to_i, 1].max - 1, min_row].max
-      min_col = [rect[:left].to_i, 1].max
-      max_col = [rect[:left].to_i + [rect[:width].to_i, 1].max - 1, min_col].max
-      row = [[row.to_i, min_row].max, max_row].min
-      col = [[col.to_i, min_col].max, max_col].min
+      min_row = [rect[:top], 1].max
+      max_row = [rect[:top] + [rect[:height], 1].max - 1, min_row].max
+      min_col = [rect[:left], 1].max
+      max_col = [rect[:left] + [rect[:width], 1].max - 1, min_col].max
+      row = [[row, min_row].max, max_row].min
+      col = [[col, min_col].max, max_col].min
       [row, col]
     end
 
@@ -1130,6 +1177,7 @@ module RuVim
       search = editor.last_search
       return {} unless search && search[:pattern]
       return {} unless editor.effective_option("hlsearch")
+      return {} if editor.hlsearch_suppressed?
 
       regex = build_screen_search_regex(editor, search[:pattern])
       cols = {}
@@ -1177,7 +1225,10 @@ module RuVim
 
       cols = RuVim::Highlighter.color_columns(filetype, source_line_text)
       @syntax_color_cache[key] = cols
-      @syntax_color_cache.shift while @syntax_color_cache.length > SYNTAX_CACHE_LIMIT
+      if @syntax_color_cache.length > SYNTAX_CACHE_LIMIT
+        trim = @syntax_color_cache.length - SYNTAX_CACHE_LIMIT / 2
+        trim.times { @syntax_color_cache.shift }
+      end
       cols
     end
   end

data/lib/ruvim/stream/file_load.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RuVim
+  class Stream::FileLoad < Stream
+    CHUNK_BYTES = 1 * 1024 * 1024
+    FLUSH_BYTES = 32 * 1024 * 1024
+
+    attr_accessor :thread, :io
+
+    def initialize(io:, file_size:, buffer_id:, queue:, stop_handler: nil, &notify)
+      super(stop_handler: stop_handler)
+      @io = io
+      @state = :live
+      @thread = Thread.new do
+        pending_bytes = "".b
+        ended_with_newline = false
+        loaded_bytes = io.pos
+        loop do
+          chunk = io.readpartial(CHUNK_BYTES)
+          next if chunk.nil? || chunk.empty?
+
+          loaded_bytes += chunk.bytesize
+          ended_with_newline = chunk.end_with?("\n")
+          pending_bytes << chunk
+          next if pending_bytes.bytesize < FLUSH_BYTES
+
+          last_nl = pending_bytes.rindex("\n".b)
+          if last_nl
+            send_bytes = pending_bytes[0..last_nl]
+            pending_bytes = pending_bytes[(last_nl + 1)..] || "".b
+          else
+            send_bytes = pending_bytes
+            pending_bytes = "".b
+          end
+          decoded = Buffer.decode_text(send_bytes)
+          parts = decoded.split("\n", -1)
+          head = parts.shift || ""
+          queue << { type: :file_lines, buffer_id: buffer_id, head: head, lines: parts, loaded_bytes: loaded_bytes, file_size: file_size }
+          notify.call
+        end
+      rescue EOFError
+        unless pending_bytes.empty?
+          decoded = Buffer.decode_text(pending_bytes)
+          parts = decoded.split("\n", -1)
+          head = parts.shift || ""
+          queue << { type: :file_lines, buffer_id: buffer_id, head: head, lines: parts }
+          notify.call
+        end
+        queue << { type: :file_eof, buffer_id: buffer_id, ended_with_newline: ended_with_newline }
+        notify.call
+      rescue StandardError => e
+        queue << { type: :file_error, buffer_id: buffer_id, error: e.message.to_s }
+        notify.call
+      ensure
+        begin
+          io.close unless io.closed?
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    def status
+      case @state
+      when :live then "load"
+      when :error then "load/error"
+      end
+    end
+
+    def stop!
+      io = @io; @io = nil
+      begin
+        io&.close unless io&.closed?
+      rescue StandardError
+        nil
+      end
+      thread = @thread; @thread = nil
+      if thread&.alive?
+        thread.kill
+        thread.join(0.05)
+      end
+      @state = :closed
+    end
+  end
+end

data/lib/ruvim/stream/follow.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RuVim
+  class Stream::Follow < Stream
+    attr_accessor :watcher, :backend
+
+    def initialize(path:, buffer_id:, queue:, stop_handler: nil, &notify)
+      super(stop_handler: stop_handler)
+      @state = :live
+      @watcher = FileWatcher.create(path) do |type, data|
+        case type
+        when :data
+          queue << { type: :follow_data, buffer_id: buffer_id, data: data }
+        when :truncated
+          queue << { type: :follow_truncated, buffer_id: buffer_id }
+        when :deleted
+          queue << { type: :follow_deleted, buffer_id: buffer_id }
+        end
+        notify.call
+      end
+      @backend = @watcher.backend
+      @watcher.start
+    end
+
+    def status
+      case @state
+      when :live
+        @backend == :inotify ? "follow/i" : "follow"
+      when :error then "follow/error"
+      end
+    end
+
+    def stop!
+      watcher = @watcher; @watcher = nil
+      watcher&.stop
+      @backend = nil
+      @state = nil
+    end
+  end
+end

data/lib/ruvim/stream/git.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RuVim
+  class Stream::Git < Stream
+    attr_accessor :io, :thread
+
+    def initialize(cmd:, root:, buffer_id:, queue:, stop_handler: nil, &notify)
+      super(stop_handler: stop_handler)
+      @io = nil
+      stream = self
+      @thread = Thread.new do
+        IO.popen(cmd, chdir: root, err: [:child, :out]) do |io|
+          stream.io = io
+          while (chunk = io.read(4096))
+            queue << { type: :stream_data, buffer_id: buffer_id, data: Buffer.decode_text(chunk) }
+            notify.call
+          end
+        end
+        stream.io = nil
+        queue << { type: :stream_eof, buffer_id: buffer_id }
+        notify.call
+      rescue StandardError => e
+        stream.io = nil
+        queue << { type: :stream_error, buffer_id: buffer_id, error: e.message.to_s }
+        notify.call
+      end
+    end
+
+    def stop!
+      io = @io; @io = nil
+      begin
+        io&.close unless io&.closed?
+      rescue IOError
+        nil
+      end
+      thread = @thread; @thread = nil
+      if thread&.alive?
+        thread.kill
+        thread.join(0.05)
+      end
+    end
+  end
+end

data/lib/ruvim/stream/run.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "pty"
+
+module RuVim
+  class Stream::Run < Stream
+    attr_accessor :io, :pid, :thread, :command, :exit_status
+
+    def initialize(command:, buffer_id:, queue:, stop_handler: nil, &notify)
+      super(stop_handler: stop_handler)
+      @command = command
+      @io = nil
+      @pid = nil
+      @exit_status = nil
+      @state = :live
+      stream = self
+      @thread = Thread.new do
+        shell = ENV["SHELL"].to_s
+        shell = "/bin/sh" if shell.empty?
+        PTY.spawn(shell, "-c", command) do |r, _w, pid|
+          stream.io = r
+          stream.pid = pid
+          begin
+            while (chunk = r.readpartial(4096))
+              text = Buffer.decode_text(chunk).delete("\r")
+              queue << { type: :stream_data, buffer_id: buffer_id, data: text }
+              notify.call
+            end
+          rescue EOFError, Errno::EIO
+            # expected: PTY raises EIO when child process exits
+          end
+          _status = Process.waitpid2(pid)[1] rescue nil
+          stream.io = nil
+          queue << { type: :stream_eof, buffer_id: buffer_id, status: _status }
+          notify.call
+        end
+      rescue StandardError => e
+        stream.io = nil
+        queue << { type: :stream_error, buffer_id: buffer_id, error: e.message.to_s }
+        notify.call
+      end
+    end
+
+    def status
+      case @state
+      when :live then "run"
+      when :closed
+        code = @exit_status&.exitstatus
+        code ? "run/exit #{code}" : "run/EOF"
+      when :error then "run/error"
+      end
+    end
+
+    def stop!
+      pid = @pid; @pid = nil
+      if pid
+        Process.kill(:TERM, pid) rescue nil
+        Process.waitpid(pid) rescue nil
+      end
+      io = @io; @io = nil
+      begin
+        io&.close unless io&.closed?
+      rescue IOError
+        nil
+      end
+      thread = @thread; @thread = nil
+      if thread&.alive?
+        thread.kill
+        thread.join(0.05)
+      end
+      @state = :closed
+    end
+  end
+end