muxr 0.1.11 → 0.2.0

data/lib/muxr/terminal.rb

@@ -1,3 +1,6 @@
+require_relative "image_store"
+require_relative "history_row"
+
 module Muxr
   # A minimal VT100/ANSI terminal emulator. It maintains a fixed grid of cells
   # plus a cursor and parser state. Bytes fed from a PTY are interpreted into
@@ -10,7 +13,13 @@ module Muxr
     REVERSE   = 4
     DIM       = 8
 
-    SCROLLBACK_MAX = 5000
+    SCROLLBACK_DEFAULT = 50_000
+    SCROLLBACK_BOUNDS = 100..500_000
+
+    ALT_SCREEN_MODES = [47, 1047, 1049].freeze
+    MOUSE_TRACKING_MODES = [1000, 1002, 1003].freeze
+    MOUSE_SGR_MODE = 1006
+    APP_CURSOR_KEYS_MODE = 1
 
     # Codepoint ranges that occupy two display columns (East Asian Wide /
     # Fullwidth per UAX #11, plus the common emoji blocks). A wide glyph is
@@ -62,21 +71,130 @@ module Muxr
       0xE0100..0xE01EF    # variation selectors supplement
     ].freeze
 
+    # East Asian *Ambiguous* width (UAX #11 class "A"): codepoints that some
+    # terminals draw one column wide and others two, depending on the font and
+    # the terminal's "ambiguous-as-wide" setting. This is where muxr and the
+    # outer terminal most often disagree — and the disagreement is exactly what
+    # corrupts in-place animations (Claude Code's ⏺/✻/❯ spinner, ·, …, ●, arrows).
+    # We don't hardcode a width for them: #char_width consults `ambiguous_wide`,
+    # which the width probe (see WidthProbe / the client handshake) sets to
+    # match the actual outer terminal. Curated to the BMP symbol/punctuation
+    # ranges that show up in practice rather than the full UAX #11 table.
+    AMBIGUOUS_RANGES = [
+      0x00A1..0x00A1, 0x00A4..0x00A4, 0x00A7..0x00A8, 0x00AA..0x00AA,
+      0x00AD..0x00AE, 0x00B0..0x00B4, 0x00B6..0x00BA, 0x00BC..0x00BF,
+      0x00C6..0x00C6, 0x00D0..0x00D0, 0x00D7..0x00D8, 0x00DE..0x00E1,
+      0x00E6..0x00E6, 0x00E8..0x00EA, 0x00EC..0x00ED, 0x00F0..0x00F0,
+      0x00F2..0x00F3, 0x00F7..0x00FA, 0x00FC..0x00FC, 0x00FE..0x00FE,
+      0x2010..0x2010, 0x2013..0x2016, 0x2018..0x2019, 0x201C..0x201D,
+      0x2020..0x2022, 0x2024..0x2027, 0x2030..0x2030, 0x2032..0x2033,
+      0x2035..0x2035, 0x203B..0x203B, 0x203E..0x203E, 0x2074..0x2074,
+      0x207F..0x207F, 0x2081..0x2084, 0x20AC..0x20AC, 0x2103..0x2103,
+      0x2105..0x2105, 0x2109..0x2109, 0x2113..0x2113, 0x2116..0x2116,
+      0x2121..0x2122, 0x2126..0x2126, 0x212B..0x212B, 0x2153..0x2154,
+      0x215B..0x215E, 0x2160..0x216B, 0x2170..0x2179, 0x2189..0x2189,
+      0x2190..0x2199, 0x21B8..0x21B9, 0x21D2..0x21D2, 0x21D4..0x21D4,
+      0x21E7..0x21E7, 0x2200..0x2200, 0x2202..0x2203, 0x2207..0x2208,
+      0x220B..0x220B, 0x220F..0x220F, 0x2211..0x2211, 0x2215..0x2215,
+      0x221A..0x221A, 0x221D..0x2220, 0x2223..0x2223, 0x2225..0x2225,
+      0x2227..0x222C, 0x222E..0x222E, 0x2234..0x2237, 0x223C..0x223D,
+      0x2248..0x2248, 0x224C..0x224C, 0x2252..0x2252, 0x2260..0x2261,
+      0x2264..0x2267, 0x226A..0x226B, 0x226E..0x226F, 0x2282..0x2283,
+      0x2286..0x2287, 0x2295..0x2295, 0x2299..0x2299, 0x22A5..0x22A5,
+      0x22BF..0x22BF, 0x2312..0x2312, 0x2460..0x24E9, 0x24EB..0x24FF,
+      # NOTE: the box-drawing / block-element band 0x2500-0x259F is excluded here
+      # because it gets its own measured class — see BOX_RANGES / box_wide.
+      # Geometric shapes (0x25A0+) are fair game.
+      0x25A0..0x25A1,
+      0x25A3..0x25A9, 0x25B2..0x25B3, 0x25B6..0x25B7, 0x25BC..0x25BD,
+      0x25C0..0x25C1, 0x25C6..0x25C8, 0x25CB..0x25CB, 0x25CE..0x25D1,
+      0x25E2..0x25E5, 0x25EF..0x25EF, 0x2605..0x2606, 0x2609..0x2609,
+      0x260E..0x260F, 0x261C..0x261C, 0x261E..0x261E, 0x2640..0x2640,
+      0x2642..0x2642, 0x2660..0x2661, 0x2663..0x2665, 0x2667..0x266A,
+      0x266C..0x266D, 0x266F..0x266F, 0x269E..0x269F, 0x26BF..0x26BF,
+      0x26C6..0x26CD, 0x26CF..0x26D3, 0x26D5..0x26E1, 0x273D..0x273D,
+      0x2776..0x277F, 0xFFFD..0xFFFD
+    ].freeze
+
+    # Box-drawing and block elements. Much of this band is formally East Asian
+    # Ambiguous, so a terminal set to draw ambiguous glyphs wide draws these two
+    # columns wide too — but plenty of terminals special-case the band and keep
+    # it narrow even then, so it can't ride on `ambiguous_wide`. It gets its own
+    # probed verdict (`box_wide`) instead of a guess, because Renderer's
+    # contiguity shortcut trusts this band and a wrong guess here shifts every
+    # subsequent cell on the line: it's the band TUI borders are built from, and
+    # Claude Code's UI is mostly borders.
+    BOX_RANGES = [0x2500..0x259F].freeze
+
+    class << self
+      # Whether the outer terminal draws East Asian Ambiguous glyphs two columns
+      # wide. Set per attach by the width probe (default narrow, matching most
+      # modern terminals). Covers the long tail of ambiguous glyphs the probe
+      # doesn't sample individually.
+      attr_accessor :ambiguous_wide
+      # Whether the outer terminal draws the box-drawing / block band two columns
+      # wide. Set per attach by the width probe; default narrow, which is what
+      # nearly every terminal does.
+      attr_accessor :box_wide
+      # Exact per-codepoint widths the probe measured against the live terminal,
+      # cp => 1|2. These WIN over every heuristic below, because a direct
+      # measurement is ground truth. This is what catches glyphs whose width no
+      # class captures — Claude Code's ⏺/✻/❯, which a font may draw two columns
+      # wide via emoji presentation even when the terminal's ambiguous setting
+      # is narrow (the exact case the class toggle alone would miss).
+      attr_reader :width_overrides
+      attr_reader :scrollback_max
+    end
+    # Both are process-global: the server hosts exactly one session / outer
+    # terminal at a time, and both #char_width call sites (the emulator and the
+    # Renderer) must agree.
+    self.ambiguous_wide = false
+    self.box_wide = false
+    @width_overrides = {}
+
+    def self.width_overrides=(map)
+      @width_overrides = map || {}
+    end
+
+    def self.scrollback_max=(rows)
+      n = rows.to_i
+      @scrollback_max = n.positive? ? n.clamp(SCROLLBACK_BOUNDS) : SCROLLBACK_DEFAULT
+    end
+    self.scrollback_max = ENV["MUXR_SCROLLBACK"]
+
     # Display width of a codepoint in terminal columns: 0 (combining /
-    # zero-width), 2 (East Asian wide / emoji), or 1 (everything else). The
-    # Renderer uses this to advance its emit cursor by the right number of
-    # columns; #put_char uses it to lay glyphs into the grid.
+    # zero-width), 2 (East Asian wide / emoji, plus anything the probe measured
+    # or Ambiguous when the probed terminal draws those wide), or 1 (everything
+    # else). The Renderer uses this to advance its emit cursor by the right
+    # number of columns; #put_char uses it to lay glyphs into the grid.
     def self.char_width(cp)
       return 1 if cp < 0x0300
       return 0 if ZERO_WIDTH_RANGES.any? { |r| r.cover?(cp) }
+      ov = @width_overrides[cp]
+      return ov if ov
       return 2 if WIDE_RANGES.any? { |r| r.cover?(cp) }
+      return 2 if @ambiguous_wide && AMBIGUOUS_RANGES.any? { |r| r.cover?(cp) }
+      return 2 if @box_wide && BOX_RANGES.any? { |r| r.cover?(cp) }
       1
     end
 
-    # Cap on the OSC payload we buffer before parsing. URLs in OSC 8 can be
-    # long but rarely exceed a few hundred bytes; 4 KiB lets the parser stay
-    # tolerant of weird inputs without giving an attacker an unbounded sink.
-    OSC_MAX_LEN = 4096
+    # Cap on the OSC payload we buffer before parsing. URLs in OSC 8 rarely
+    # exceed a few hundred bytes, but OSC 52 clipboard writes (a vim yank, etc.)
+    # carry the base64 of whatever the inner program copied, so the cap doubles
+    # as the practical clipboard size limit. 100 KiB stays bounded per parser
+    # (it's freed on finalize) while comfortably fitting normal yanks; a payload
+    # longer than this is truncated rather than copied wholesale.
+    OSC_MAX_LEN = 100 * 1024
+
+    # Cap on the outbound notification queue (bell + notification OSCs). While a
+    # client is attached the Application drains it every read, so it stays tiny;
+    # the cap only matters for a detached session, where nobody is listening and
+    # a noisy inner program would otherwise grow it without bound.
+    NOTIFY_MAX = 64 * 1024
+
+    GRAPHICS_MAX_LEN = 8 * 1024 * 1024
+
+    IMAGE_LINK_PREFIX = "8;id=muxr-img-"
 
     # Match plain-text URLs the inner program printed without wrapping them
     # in OSC 8. We stamp the matching cells with a synthetic hyperlink so the
@@ -102,9 +220,18 @@ module Muxr
     # program (which left ?2026h open) cannot wedge the pane indefinitely.
     SYNC_TIMEOUT = 0.2
 
+    BLANK_CHAR = " ".freeze
+    CONTINUATION_CHAR = "".freeze
+    ASCII_CHARS = (0...128).map { |cp| cp.chr.freeze }.freeze
+
+    def self.intern_char(ch)
+      return CONTINUATION_CHAR if ch.empty?
+      ch.bytesize == 1 ? ASCII_CHARS[ch.getbyte(0)] : ch
+    end
+
     Cell = Struct.new(:char, :fg, :bg, :attrs, :hyperlink) do
       def reset!
-        self.char = " "
+        self.char = BLANK_CHAR
         self.fg = nil
         self.bg = nil
         self.attrs = 0
@@ -122,9 +249,12 @@ module Muxr
 
     attr_reader :rows, :cols, :cursor_row, :cursor_col, :view_offset
 
-    def initialize(rows: 24, cols: 80)
+    def initialize(rows: 24, cols: 80, image_store: nil)
       @rows = rows
       @cols = cols
+      @image_store = image_store || ImageStore.new
+      @parser_apc = +""
+      @graphics_pending = nil
       @buffer = Array.new(rows) { Array.new(cols) { blank_cell } }
       @cursor_row = 0
       @cursor_col = 0
@@ -135,6 +265,7 @@ module Muxr
       @autowrap_pending = false
       @scroll_top = 0
       @scroll_bottom = rows - 1
+      @saved_primary = nil
       @parser_state = :ground
       @parser_params = +""
       @parser_osc = +""
@@ -162,7 +293,33 @@ module Muxr
       # \e[200~…\e[201~ paste markers the outer terminal wraps around a paste
       # or strip them — see Application#send_to_focused.
       @bracketed_paste = false
+      @mouse_tracking = []
+      @mouse_sgr = false
+      @app_cursor_keys = false
+      @selection_screen_only = false
+      # Whether the inner program wants its cursor shown (DECTCEM, DEC private
+      # mode 25). Claude Code and other Ink UIs hide the cursor (\e[?25l) for
+      # the whole render and only show it (\e[?25h) at a text-input prompt —
+      # the Renderer consults this so we don't paint a stray block cursor on
+      # top of an animating progress line.
+      @cursor_visible = true
       @pending_replies = +"".b
+      # Out-of-band bytes the emulator owes the OUTER terminal (not the inner
+      # program): the bell and desktop-notification OSCs (OSC 9, OSC 777) that
+      # Claude Code emits to get your attention. We don't model these on the
+      # grid — they're forwarded verbatim so the user's real terminal rings /
+      # raises the notification, even when the emitting pane isn't focused.
+      # The Application drains this in consume_pane_io. Capped so a detached
+      # session (nobody to forward to) can't grow it without bound.
+      @pending_notifications = +"".b
+      # The most recent clipboard write the inner program requested via OSC 52
+      # (`\e]52;c;<base64>\a` — what vim/tmux/Ghostty emit on a "copy to system
+      # clipboard" yank), already base64-decoded to raw bytes. Not grid state;
+      # the Application drains it in consume_pane_io and pipes it to pbcopy.
+      # Last-write-wins (a clipboard holds one value) so this can't grow without
+      # bound, and it's drained even while detached since pbcopy is local to the
+      # server host and doesn't need an attached client.
+      @pending_clipboard = nil
       @search_query = nil
       @search_direction = :forward
       @search_matches = []
@@ -208,6 +365,50 @@ module Muxr
       @bracketed_paste
     end
 
+    # True iff the inner program currently wants its cursor shown (DEC private
+    # mode 25, DECTCEM). The Renderer suppresses the focused pane's cursor when
+    # this is false so a hidden-cursor UI (Claude Code mid-render, a spinner)
+    # doesn't get a phantom block painted at its last write position.
+    def cursor_visible?
+      @cursor_visible
+    end
+
+    def alt_screen?
+      !@saved_primary.nil?
+    end
+
+    def mouse_tracking?
+      !@mouse_tracking.empty?
+    end
+
+    def mouse_encoding
+      @mouse_sgr ? :sgr : :x10
+    end
+
+    def app_cursor_keys?
+      @app_cursor_keys
+    end
+
+    # Bytes the emulator owes the OUTER terminal: bell + desktop-notification
+    # OSCs the inner program emitted. The Application drains this after each
+    # read and forwards it to the attached client so the user's real terminal
+    # rings / notifies. Returns nil when empty (mirrors take_pending_replies!).
+    def take_pending_notifications!
+      return nil if @pending_notifications.empty?
+      data = @pending_notifications
+      @pending_notifications = +"".b
+      data
+    end
+
+    # The latest OSC 52 clipboard write (raw, already base64-decoded), or nil if
+    # the inner program hasn't asked to set the clipboard since the last drain.
+    # The Application pulls this in consume_pane_io and hands it to pbcopy.
+    def take_pending_clipboard!
+      data = @pending_clipboard
+      @pending_clipboard = nil
+      data
+    end
+
     attr_reader :selection_mode
 
     def cell(r, c)
@@ -228,6 +429,192 @@ module Muxr
       lines.join("\n")
     end
 
+    def dump_history_text
+      screen = @saved_primary ? @saved_primary[:buffer] : @buffer
+      lines = (@scrollback + screen).map { |row| row_search_text(row)[0].rstrip }
+      lines.pop while lines.last&.empty?
+      lines.empty? ? "" : lines.join("\n") << "\n"
+    end
+
+    # Serialize the live grid as a self-contained ANSI repaint: feeding these
+    # bytes to a blank emulator of the same size reproduces this screen exactly.
+    # Seeds a mirrored copy of the pane in another muxr server, which then keeps
+    # up from the raw PTY byte stream alone.
+    def dump_ansi
+      out = +""
+      out << primary_repaint if @saved_primary
+      out << "\e[0m\e[H\e[2J"
+      emit_grid(out, @buffer)
+      out << dump_modes
+      out << "\e[#{@cursor_row + 1};#{@cursor_col + 1}H"
+      out << (@cursor_visible ? "\e[?25h" : "\e[?25l")
+      out << self.class.sgr(Cell.new(" ", @fg, @bg, @attrs, nil))
+      out
+    end
+
+    # Modes a repaint has to carry alongside the cells. The scroll region is
+    # the load-bearing one: a full-screen program sets DECSTBM once and then
+    # relies on plain index/reverse-index to scroll only that band, so a copy
+    # of this screen that missed it scrolls the whole display instead.
+    # DECSTBM homes the cursor, hence emitting this before the final position.
+    def dump_modes
+      out = +""
+      unless @scroll_top.zero? && @scroll_bottom == @rows - 1
+        out << "\e[#{@scroll_top + 1};#{@scroll_bottom + 1}r"
+      end
+      out << "\e[?2004h" if @bracketed_paste
+      out << "\e[?1h" if @app_cursor_keys
+      @mouse_tracking.each { |mode| out << "\e[?#{mode}h" }
+      out << "\e[?#{MOUSE_SGR_MODE}h" if @mouse_sgr
+      out
+    end
+
+    # Everything a blank emulator needs to become this one, including the
+    # history above the screen. Only used when a pane moves between servers —
+    # dropping scrollback there would put exactly the kind of hole in the
+    # timeline that #resize goes out of its way to avoid.
+    def dump_transfer
+      {
+        "rows"       => @rows,
+        "cols"       => @cols,
+        "screen"     => dump_ansi,
+        "scrollback" => @scrollback.map { |row| row_ansi(row) }
+      }
+    end
+
+    def restore_transfer!(state)
+      restore_scrollback!(state["scrollback"])
+      feed(state["screen"].to_s)
+    end
+
+    # Rebuild the scrollback ring by replaying each row through a one-row
+    # emulator, which keeps the cell attributes the ANSI encoding carries
+    # without duplicating the parser here.
+    def restore_scrollback!(lines)
+      return if lines.nil? || lines.empty?
+      scratch = self.class.new(rows: 1, cols: @cols)
+      @scrollback = lines.last(self.class.scrollback_max).map do |line|
+        scratch.feed("\e[0m\e[H\e[2K")
+        scratch.feed(line.to_s)
+        pack_row(Array.new(@cols) { |c| scratch.cell(0, c) })
+      end
+      @view_offset = 0
+    end
+
+    def row_ansi(row)
+      return row.to_ansi if row.is_a?(HistoryRow)
+      last = last_significant_column(row)
+      return "" if last.nil?
+      out = +""
+      _sgr, link = emit_row(out, row, last, nil, nil)
+      out << "\e]8;;\e\\" if link
+      out
+    end
+
+    def emit_grid(out, buffer)
+      sgr = nil
+      link = nil
+      buffer.each_with_index do |row, r|
+        last = last_significant_column(row)
+        next if last.nil?
+        out << "\e[#{r + 1};1H"
+        sgr, link = emit_row(out, row, last, sgr, link)
+      end
+      out << "\e]8;;\e\\" if link
+      out << "\e[0m"
+    end
+
+    def primary_repaint
+      out = +"\e[0m\e[H\e[2J"
+      emit_grid(out, @saved_primary[:buffer])
+      row, col = @saved_primary[:cursor]
+      out << "\e[#{row + 1};#{col + 1}H\e[?1049h"
+      out
+    end
+
+    # Append cells 0..last of +row+ to +out+, carrying the caller's current SGR
+    # and hyperlink so a multi-row dump only re-states them when they change.
+    # Returns the state it left the stream in.
+    def emit_row(out, row, last, sgr, link)
+      skip = 0
+      (0..last).each do |c|
+        if skip.positive?
+          skip -= 1
+          next
+        end
+        cell = row[c] || blank_cell
+        char = cell.char.to_s
+        if (s = self.class.sgr(cell)) != sgr
+          out << s
+          sgr = s
+        end
+        if cell.hyperlink != link
+          out << "\e]8;;\e\\" if link
+          out << "\e]#{cell.hyperlink}\e\\" if cell.hyperlink
+          link = cell.hyperlink
+        end
+        if char.empty?
+          out << " "
+        else
+          out << char
+          skip = 1 if self.class.char_width(char.codepoints.first) == 2
+        end
+      end
+      [sgr, link]
+    end
+
+    # Rightmost cell in +row+ that differs from a freshly-erased one, or nil
+    # when the whole row is blank. A dump opens with \e[2J, so blank tails
+    # (the common case) cost nothing on the wire.
+    def last_significant_column(row)
+      (row.length - 1).downto(0) do |c|
+        cell = row[c]
+        next if cell.nil?
+        next if cell.fg.nil? && cell.bg.nil? && cell.attrs.to_i.zero? &&
+                cell.hyperlink.nil? && (cell.char == " " || cell.char == "")
+        return c
+      end
+      nil
+    end
+
+    # SGR prelude that puts a terminal into the cell's colors and attributes.
+    # Shared with the Renderer's diff-emit so a snapshot and an incremental
+    # frame describe the same cell identically.
+    def self.sgr(cell)
+      sgr_for(cell.fg, cell.bg, cell.attrs)
+    end
+
+    def self.sgr_for(fg, bg, attrs)
+      attrs = attrs.to_i
+      parts = ["0"]
+      parts << "1" if (attrs & BOLD) != 0
+      parts << "2" if (attrs & DIM) != 0
+      parts << "4" if (attrs & UNDERLINE) != 0
+      parts << "7" if (attrs & REVERSE) != 0
+      append_color(parts, fg, true)
+      append_color(parts, bg, false)
+      "\e[#{parts.join(';')}m"
+    end
+
+    def self.append_color(parts, color, fg)
+      return if color.nil?
+      case color
+      when Integer
+        if color < 8
+          parts << ((fg ? 30 : 40) + color).to_s
+        else
+          parts << ((fg ? 90 : 100) + (color - 8)).to_s
+        end
+      when Array
+        case color[0]
+        when :c256
+          parts << "#{fg ? 38 : 48};5;#{color[1]}"
+        when :rgb
+          parts << "#{fg ? 38 : 48};2;#{color[1]};#{color[2]};#{color[3]}"
+        end
+      end
+    end
+
     # Returns the Cell that should be visible at (r, c) given the current
     # scrollback view_offset. When view_offset == 0 this is the live grid.
     # When view_offset > 0, rows in the top of the visible area are sourced
@@ -237,8 +624,7 @@ module Muxr
       idx = @scrollback.size - @view_offset + r
       if idx < @scrollback.size
         row = @scrollback[idx]
-        return blank_cell if row.nil? || c >= row.length
-        row[c]
+        (row && row[c]) || blank_cell
       else
         @buffer[idx - @scrollback.size][c]
       end
@@ -280,10 +666,23 @@ module Muxr
       !@selection_anchor.nil?
     end
 
+    def confine_selection_to_screen!(confined)
+      @selection_screen_only = confined
+      set_view_offset(0) if confined
+    end
+
+    def selection_confined_to_screen?
+      @selection_screen_only
+    end
+
+    def selection_floor
+      @selection_screen_only ? @scrollback.size : 0
+    end
+
     # Place the moving cursor at a viewport position without dropping an
     # anchor — the user is still navigating, not yet selecting.
     def place_selection_cursor(r, c)
-      tr = timeline_row_for_visible(r).clamp(0, timeline_size - 1)
+      tr = timeline_row_for_visible(r).clamp(selection_floor, timeline_size - 1)
       tc = c.clamp(0, @cols - 1)
       @selection_cursor = [tr, tc]
       @selection_anchor = nil
@@ -317,7 +716,7 @@ module Muxr
     def move_selection_cursor_by(dr, dc)
       return unless @selection_cursor
       tr, tc = @selection_cursor
-      ntr = (tr + dr).clamp(0, timeline_size - 1)
+      ntr = (tr + dr).clamp(selection_floor, timeline_size - 1)
       ntc = (tc + dc).clamp(0, @cols - 1)
       return if ntr == tr && ntc == tc
       @selection_cursor = [ntr, ntc]
@@ -327,7 +726,7 @@ module Muxr
 
     def selection_cursor_to(tr, tc)
       return unless @selection_cursor
-      ntr = tr.clamp(0, timeline_size - 1)
+      ntr = tr.clamp(selection_floor, timeline_size - 1)
       ntc = tc.clamp(0, @cols - 1)
       @selection_cursor = [ntr, ntc]
       ensure_selection_cursor_visible
@@ -368,7 +767,7 @@ module Muxr
            when :bottom then @rows - 1
            end
       return if vr.nil?
-      tr = timeline_row_for_visible(vr).clamp(0, timeline_size - 1)
+      tr = timeline_row_for_visible(vr).clamp(selection_floor, timeline_size - 1)
       selection_cursor_to(tr, first_non_blank_col(tr))
     end
 
@@ -585,16 +984,15 @@ module Muxr
 
     def resize(rows, cols)
       return if rows == @rows && cols == @cols
-      new_buf = Array.new(rows) { Array.new(cols) { blank_cell } }
-      keep_rows = [rows, @rows].min
-      keep_cols = [cols, @cols].min
-      src_start = @rows - keep_rows
-      keep_rows.times do |i|
-        keep_cols.times do |j|
-          new_buf[i][j].copy_from(@buffer[src_start + i][j])
-        end
+      was = [@rows, @cols]
+      shape = [rows, cols]
+      if (primary = @saved_primary)
+        primary[:buffer] = refit(primary[:buffer], was, shape, history: true)
+        primary[:cursor] = clamp_within(primary[:cursor], shape)
+        primary[:saved_cursor] = clamp_within(primary[:saved_cursor], shape)
+        primary[:scroll] = [0, rows - 1]
       end
-      @buffer = new_buf
+      @buffer = refit(@buffer, was, shape, history: primary.nil?)
       @rows = rows
       @cols = cols
       @scroll_top = 0
@@ -614,18 +1012,18 @@ module Muxr
       @feed_remainder = +"".b
       str = bytes.dup.force_encoding(Encoding::UTF_8)
       unless str.valid_encoding?
-        # Find the longest valid UTF-8 prefix and stash the remainder for the
-        # next feed call so multi-byte characters don't get garbled across PTY
-        # read boundaries.
-        raw = bytes.bytes
-        while raw.any?
-          candidate = raw.pack("C*").force_encoding(Encoding::UTF_8)
-          break if candidate.valid_encoding?
-          @feed_remainder = ([raw.last] + @feed_remainder.bytes).pack("C*").b
-          raw.pop
+        # Hold back only a genuinely truncated multi-byte character at the very
+        # end, so a glyph split across PTY read boundaries still joins up. Any
+        # other malformed byte is substituted rather than deferred: deferring it
+        # would prepend the same bad byte to every later feed, so the stream
+        # could never become valid and the pane would stall forever.
+        hold = incomplete_tail_length(bytes)
+        if hold.positive?
+          @feed_remainder = bytes.byteslice(bytes.bytesize - hold, hold).b
+          bytes = bytes.byteslice(0, bytes.bytesize - hold)
         end
-        str = raw.pack("C*").force_encoding(Encoding::UTF_8)
-        # Bail out completely if we couldn't decode anything yet.
+        str = bytes.dup.force_encoding(Encoding::UTF_8)
+        str = str.scrub("�") unless str.valid_encoding?
         return if str.empty?
       end
       str.each_char { |c| process_char(c) }
@@ -633,6 +1031,24 @@ module Muxr
       @dirty = true
     end
 
+    # Byte length of an incomplete UTF-8 character at the end of +bytes+, or 0
+    # when the tail isn't a truncated character. A UTF-8 character is at most 4
+    # bytes, so only the last 3 can be waiting on continuation bytes.
+    def incomplete_tail_length(bytes)
+      max = [3, bytes.bytesize].min
+      (1..max).each do |back|
+        b = bytes.getbyte(bytes.bytesize - back)
+        return 0 if b < 0x80
+        next if b < 0xc0
+        needed = if b >= 0xf0 then 4
+                 elsif b >= 0xe0 then 3
+                 else 2
+                 end
+        return needed > back ? back : 0
+      end
+      0
+    end
+
     # Walk the buffer (plus the last scrollback row so wraps across the
     # scrollback boundary still join), find plain-text URLs, and stamp the
     # covering cells with an OSC 8 hyperlink carrying an `id=` parameter.
@@ -641,8 +1057,9 @@ module Muxr
     # a wrapped URL like https://very.long.example.com/path-that-wraps would
     # be detected as two truncated URLs on consecutive lines.
     def detect_urls!
+      history = @scrollback.last if @saved_primary.nil? && @scrollback.any?
       rows = []
-      rows << @scrollback.last if @scrollback.any?
+      rows << history if history
       rows.concat(@buffer)
 
       rows.each do |row|
@@ -689,22 +1106,49 @@ module Muxr
 
         pos = end_off
       end
+
+      history&.repack!
     end
 
     private
 
     def blank_cell
-      Cell.new(" ", nil, nil, 0, nil)
+      Cell.new(BLANK_CHAR, nil, nil, 0, nil)
     end
 
-    # Parse the just-completed OSC payload. We only care about OSC 8
-    # (hyperlinks): `8;params;URI`. An empty URI closes the active link.
+    # Queue bytes for the outer terminal (bell / notification OSC). Dropped once
+    # the buffer is full so a detached, never-drained session can't grow without
+    # bound — see NOTIFY_MAX.
+    def queue_notification(bytes)
+      return if @pending_notifications.bytesize >= NOTIFY_MAX
+      @pending_notifications << bytes
+    end
+
+    # Parse the just-completed OSC payload. We care about three families:
+    #   OSC 8  (hyperlinks): `8;params;URI` — modeled on the grid (below).
+    #   OSC 52 (clipboard): `52;<targets>;<base64>` — decoded and queued for
+    #     pbcopy (a vim yank with OSC 52 enabled lands here).
+    #   OSC 9 / OSC 777 (desktop notifications) — not grid state; forwarded to
+    #     the outer terminal verbatim so the user's real terminal raises the
+    #     notification. Claude Code emits these (alongside the bell) when it
+    #     wants your attention.
     # Anything else (window-title OSC 0/1/2, palette OSC 4, …) is silently
     # consumed — the emulator doesn't model it.
     def finalize_osc
       payload = @parser_osc
       @parser_osc = +""
       return if payload.empty?
+      if payload.start_with?("9;", "777;")
+        # Re-wrap with a BEL terminator (universally accepted) — the original
+        # ST/BEL was consumed by the parser. The OUTPUT path carries raw bytes,
+        # so this reaches the outer terminal unchanged.
+        queue_notification("\e]#{payload}\a")
+        return
+      end
+      if payload.start_with?("52;")
+        finalize_clipboard(payload)
+        return
+      end
       return unless payload.start_with?("8;")
       parts = payload.split(";", 3)
       uri = parts[2]
@@ -715,6 +1159,107 @@ module Muxr
       end
     end
 
+    # Decode an OSC 52 clipboard write and stash it for the Application to pipe
+    # to pbcopy. The payload is `52;<targets>;<base64>`; <targets> selects which
+    # X-style clipboard ("c" clipboard, "p" primary, …) and is irrelevant here
+    # since the host has one system clipboard. A base64 of "?" is a *query*
+    # ("tell me the clipboard"), and an empty body is a clear request — we honor
+    # neither (we can't safely read the host clipboard, and silently wiping it on
+    # an inner program's whim would be surprising), so both are dropped.
+    def finalize_clipboard(payload)
+      b64 = payload.split(";", 3)[2]
+      return if b64.nil? || b64.empty? || b64 == "?"
+      decoded = b64.unpack1("m")
+      @pending_clipboard = decoded unless decoded.nil? || decoded.empty?
+    end
+
+    def finalize_apc
+      payload = @parser_apc
+      @parser_apc = +""
+      return unless payload.start_with?("G")
+      control, _, data = payload[1..].partition(";")
+      opts = parse_graphics_keys(control)
+      return reply_graphics_query(opts) if opts["a"] == "q"
+      if @graphics_pending
+        @graphics_pending[:data] << data
+      else
+        @graphics_pending = { opts: opts, data: +data }
+      end
+      return if opts["m"] == "1"
+      image = @graphics_pending
+      @graphics_pending = nil
+      save_graphics(image)
+    end
+
+    def parse_graphics_keys(control)
+      control.split(",").each_with_object({}) do |pair, acc|
+        key, _, value = pair.partition("=")
+        acc[key] = value unless key.empty?
+      end
+    end
+
+    def reply_graphics_query(opts)
+      ids = %w[i I].filter_map { |k| "#{k}=#{opts[k]}" if opts[k] }
+      ids << "i=0" if ids.empty?
+      @pending_replies << "\e_G#{ids.join(',')};OK\e\\"
+    end
+
+    def save_graphics(image)
+      bytes = graphics_bytes(image[:opts], image[:data])
+      return if bytes.nil? || bytes.empty?
+      announce_image(@image_store.write(bytes), bytes)
+    rescue SystemCallError
+      write_announcement("[image: could not be saved]", nil)
+    end
+
+    def graphics_bytes(opts, data)
+      raw = decode_graphics_data(opts, data)
+      return nil if raw.nil? || raw.empty?
+      case opts["f"] || "32"
+      when "100" then raw
+      when "24"  then ImageStore.encode_png(raw, opts["s"].to_i, opts["v"].to_i, 3)
+      when "32"  then ImageStore.encode_png(raw, opts["s"].to_i, opts["v"].to_i, 4)
+      end
+    end
+
+    def decode_graphics_data(opts, data)
+      return nil if data.empty?
+      decoded = data.unpack1("m")
+      return decoded unless %w[f t].include?(opts["t"])
+      return nil unless decoded && File.file?(decoded)
+      File.binread(decoded)
+    rescue SystemCallError
+      nil
+    end
+
+    def announce_image(path, bytes)
+      width, height = ImageStore.png_dimensions(bytes)
+      size = width && height ? " #{width}×#{height}" : ""
+      write_announcement("[image#{size} → #{abbreviate_home(path)}]", path)
+    end
+
+    def write_announcement(text, path)
+      if @cursor_col.positive? || @autowrap_pending
+        @cursor_col = 0
+        line_feed
+        @autowrap_pending = false
+      end
+      saved_hyperlink = @current_hyperlink
+      if path
+        link = "#{IMAGE_LINK_PREFIX}#{path.hash.abs.to_s(16)};file://#{path}"
+        @current_hyperlink = (@hyperlink_intern[link] ||= link.freeze)
+      end
+      text.each_char { |c| put_char(c) }
+      @current_hyperlink = saved_hyperlink
+      @cursor_col = 0
+      @autowrap_pending = false
+      line_feed
+    end
+
+    def abbreviate_home(path)
+      path.start_with?(Dir.home) ? path.sub(Dir.home, "~") : path
+    end
+
     def process_char(ch)
       b = ch.ord
       case @parser_state
@@ -739,6 +1284,23 @@ module Muxr
         # payload on slightly buggy emitters.
         finalize_osc
         @parser_state = :ground
+      when :apc
+        if b == 0x9c
+          finalize_apc
+          @parser_state = :ground
+        elsif b == 0x1b
+          @parser_state = :apc_esc
+        elsif @parser_apc.bytesize < GRAPHICS_MAX_LEN
+          @parser_apc << ch
+        end
+      when :apc_esc
+        finalize_apc
+        @parser_state = :ground
+      when :string_discard
+        @parser_state = :string_discard_esc if b == 0x1b
+        @parser_state = :ground if b == 0x9c
+      when :string_discard_esc
+        @parser_state = :ground
       when :charset
         @parser_state = :ground
       end
@@ -749,7 +1311,7 @@ module Muxr
       when 0x1b
         @parser_state = :escape
       when 0x07 # BEL
-        # ignore
+        queue_notification("\a")
       when 0x08 # BS
         @cursor_col -= 1 if @cursor_col > 0
         @autowrap_pending = false
@@ -777,13 +1339,18 @@ module Muxr
       when 0x5d # ]
         @parser_state = :osc
         @parser_osc = +""
+      when 0x5f # _
+        @parser_state = :apc
+        @parser_apc = +""
+      when 0x50, 0x58, 0x5e # P X ^
+        @parser_state = :string_discard
       when 0x28, 0x29, 0x2a, 0x2b # ( ) * +
         @parser_state = :charset
       when 0x37 # 7  save cursor
         @saved_cursor = [@cursor_row, @cursor_col]
         @parser_state = :ground
       when 0x38 # 8  restore cursor
-        @cursor_row, @cursor_col = @saved_cursor
+        restore_cursor
         @parser_state = :ground
       when 0x44 # D  index
         line_feed
@@ -861,6 +1428,8 @@ module Muxr
         #   2004 (Bracketed Paste) — whether the inner program wants pastes
         #        wrapped in \e[200~…\e[201~; the Application strips those
         #        markers when it's off (see Application#send_to_focused).
+        #   25   (DECTCEM) — cursor show/hide; the Renderer honors it so a
+        #        hidden-cursor UI doesn't get a phantom block painted on it.
         if final == "h" || final == "l"
           enabled = (final == "h")
           params = csi_params
@@ -869,6 +1438,10 @@ module Muxr
             @sync_started_at = enabled ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
           end
           @bracketed_paste = enabled if params.include?(2004)
+          @cursor_visible = enabled if params.include?(25)
+          @app_cursor_keys = enabled if params.include?(APP_CURSOR_KEYS_MODE)
+          apply_mouse_modes(params, enabled)
+          apply_screen_modes(params, enabled)
         end
         return
       end
@@ -944,7 +1517,7 @@ module Muxr
       when "s"
         @saved_cursor = [@cursor_row, @cursor_col]
       when "u"
-        @cursor_row, @cursor_col = @saved_cursor
+        restore_cursor
       when "n"
         # DSR — Device Status Report. `\e[5n` asks if the terminal is OK,
         # `\e[6n` (CPR) asks for the cursor position. The reply rides back
@@ -961,6 +1534,74 @@ module Muxr
       end
     end
 
+    def apply_mouse_modes(params, enabled)
+      (params & MOUSE_TRACKING_MODES).each do |mode|
+        enabled ? (@mouse_tracking |= [mode]) : @mouse_tracking.delete(mode)
+      end
+      @mouse_sgr = enabled if params.include?(MOUSE_SGR_MODE)
+    end
+
+    def apply_screen_modes(params, enabled)
+      if params.include?(1048)
+        enabled ? @saved_cursor = [@cursor_row, @cursor_col] : restore_cursor
+      end
+      return if (params & ALT_SCREEN_MODES).empty?
+      enabled ? enter_alt_screen : leave_alt_screen
+    end
+
+    def enter_alt_screen
+      return if @saved_primary
+      scroll_to_bottom
+      @saved_primary = {
+        buffer: @buffer,
+        cursor: [@cursor_row, @cursor_col],
+        saved_cursor: @saved_cursor,
+        scroll: [@scroll_top, @scroll_bottom],
+        fg: @fg,
+        bg: @bg,
+        attrs: @attrs,
+        hyperlink: @current_hyperlink
+      }
+      @buffer = Array.new(@rows) { Array.new(@cols) { blank_cell } }
+      @scroll_top = 0
+      @scroll_bottom = @rows - 1
+      @saved_cursor = [@cursor_row, @cursor_col]
+      @autowrap_pending = false
+      @dirty = true
+    end
+
+    def leave_alt_screen
+      primary = @saved_primary
+      return unless primary
+      @saved_primary = nil
+      @buffer = primary[:buffer]
+      @cursor_row, @cursor_col = clamp_to_grid(primary[:cursor])
+      @saved_cursor = clamp_to_grid(primary[:saved_cursor])
+      @scroll_top = primary[:scroll][0].clamp(0, @rows - 1)
+      @scroll_bottom = primary[:scroll][1].clamp(@scroll_top, @rows - 1)
+      @fg = primary[:fg]
+      @bg = primary[:bg]
+      @attrs = primary[:attrs]
+      @current_hyperlink = primary[:hyperlink]
+      @autowrap_pending = false
+      @dirty = true
+    end
+
+    def clamp_to_grid(position)
+      clamp_within(position, [@rows, @cols])
+    end
+
+    def clamp_within(position, shape)
+      [position[0].clamp(0, shape[0] - 1), position[1].clamp(0, shape[1] - 1)]
+    end
+
+    def restore_cursor
+      row, col = @saved_cursor
+      @cursor_row = row.clamp(0, @rows - 1)
+      @cursor_col = col.clamp(0, @cols - 1)
+      @autowrap_pending = false
+    end
+
     def put_char(ch)
       width = self.class.char_width(ch.ord)
 
@@ -1001,7 +1642,7 @@ module Muxr
     end
 
     def write_cell(cell, ch)
-      cell.char = ch
+      cell.char = self.class.intern_char(ch)
       cell.fg = @fg
       cell.bg = @bg
       cell.attrs = @attrs
@@ -1035,35 +1676,67 @@ module Muxr
       # Only the default full-screen region contributes to scrollback. Partial
       # regions (vi/less status lines) scroll inner content that's not really
       # "off the top of the screen" and shouldn't pollute history.
-      if @scroll_top.zero? && @scroll_bottom == @rows - 1
-        @scrollback << @buffer[0]
-        if @scrollback.size > SCROLLBACK_MAX
-          @scrollback.shift
-          # Selection coordinates are timeline-indexed; an eviction shifts the
-          # whole timeline down by one. Track that or selection points at the
-          # wrong row.
-          if @selection_anchor
-            @selection_anchor[0] = [@selection_anchor[0] - 1, 0].max
-            @selection_cursor[0] = [@selection_cursor[0] - 1, 0].max
-          end
-          unless @search_matches.empty?
-            @search_matches.each { |m| m[0] -= 1 }
-            @search_matches.reject! { |m| m[0] < 0 }
-            @search_current = nil if @search_current && @search_current >= @search_matches.length
-          end
+      push_scrollback(@buffer[0]) if history_scrolls?
+      @buffer[@scroll_top, @scroll_bottom - @scroll_top + 1] =
+        @buffer[(@scroll_top + 1)..@scroll_bottom] + [Array.new(@cols) { blank_cell }]
+    end
+
+    def refit(buffer, old_shape, new_shape, history:)
+      old_rows, old_cols = old_shape
+      rows, cols = new_shape
+      grid = Array.new(rows) { Array.new(cols) { blank_cell } }
+      keep_rows = [rows, old_rows].min
+      keep_cols = [cols, old_cols].min
+      src_start = old_rows - keep_rows
+      src_start.times { |i| push_scrollback(buffer[i]) } if history
+      keep_rows.times do |i|
+        keep_cols.times do |j|
+          grid[i][j].copy_from(buffer[src_start + i][j])
         end
-        # Keep the user's view frozen on the same content when new rows arrive
-        # while they're scrolled back.
-        if @view_offset.positive?
-          @view_offset = (@view_offset + 1).clamp(0, @scrollback.size)
+      end
+      grid
+    end
+
+    def pack_row(row)
+      last = last_significant_column(row)
+      last += 1 if last && row[last + 1] && wide_lead?(row[last])
+      HistoryRow.pack(row, last)
+    end
+
+    def wide_lead?(cell)
+      ch = cell.char
+      !ch.empty? && self.class.char_width(ch.ord) == 2
+    end
+
+    def history_scrolls?
+      @saved_primary.nil? && @scroll_top.zero? && @scroll_bottom == @rows - 1
+    end
+
+    def push_scrollback(row)
+      @scrollback << pack_row(row)
+      if @scrollback.size > self.class.scrollback_max
+        @scrollback.shift
+        # Selection coordinates are timeline-indexed; an eviction shifts the
+        # whole timeline down by one. Track that or selection points at the
+        # wrong row.
+        if @selection_anchor
+          @selection_anchor[0] = [@selection_anchor[0] - 1, 0].max
+          @selection_cursor[0] = [@selection_cursor[0] - 1, 0].max
+        end
+        unless @search_matches.empty?
+          @search_matches.each { |m| m[0] -= 1 }
+          @search_matches.reject! { |m| m[0] < 0 }
+          @search_current = nil if @search_current && @search_current >= @search_matches.length
         end
       end
-      @buffer[@scroll_top, @scroll_bottom - @scroll_top + 1] =
-        @buffer[(@scroll_top + 1)..@scroll_bottom] + [Array.new(@cols) { blank_cell }]
+      # Keep the user's view frozen on the same content when new rows arrive
+      # while they're scrolled back.
+      return unless @view_offset.positive?
+      @view_offset = (@view_offset + 1).clamp(0, @scrollback.size)
     end
 
     def set_view_offset(v)
-      new_v = v.clamp(0, @scrollback.size)
+      new_v = @saved_primary ? 0 : v.clamp(0, @scrollback.size)
       return if new_v == @view_offset
       @view_offset = new_v
       @dirty = true
@@ -1154,6 +1827,20 @@ module Muxr
       end
     end
 
+    def row_search_text(row)
+      return row.search_text(@cols) if row.is_a?(HistoryRow)
+      line = String.new(capacity: @cols)
+      col_at = []
+      @cols.times do |c|
+        ch = row[c]&.char
+        next if ch == ""
+        ch = BLANK_CHAR if ch.nil?
+        ch.each_char { col_at << c }
+        line << ch
+      end
+      [line, col_at]
+    end
+
     def collect_matches(query)
       case_sensitive = query.match?(/[A-Z]/)
       needle = case_sensitive ? query : query.downcase
@@ -1161,25 +1848,13 @@ module Muxr
       timeline_size.times do |tr|
         row = timeline_row(tr)
         next if row.nil?
-        # Build the row text and a parallel codepoint→column map so matches can
-        # be reported in column coordinates even when wide glyphs (one cell, two
-        # columns) and combining marks (multi-codepoint, one cell) break the
-        # 1:1 char-index↔column relationship. For all-ASCII rows col_at[i] == i,
-        # so this is identical to the old behavior on the common path.
-        line = String.new(capacity: @cols)
-        col_at = []
-        @cols.times do |c|
-          ch = row[c]&.char
-          next if ch == "" # wide continuation half — occupies no text slot
-          ch = " " if ch.nil?
-          ch.each_char { col_at << c }
-          line << ch
-        end
+        line, col_at = row_search_text(row)
         haystack = case_sensitive ? line : line.downcase
         start = 0
         while (idx = haystack.index(needle, start))
           last = idx + needle.length - 1
-          matches << [tr, col_at[idx], col_at[last] || col_at.last || idx]
+          matches << [tr, col_at ? col_at[idx] : idx,
+                      col_at ? (col_at[last] || col_at.last || idx) : last]
           # Advance past the start of this match so overlapping needles
           # ("aa" in "aaaa") still emit one match per starting position.
           start = idx + 1
@@ -1413,6 +2088,7 @@ module Muxr
     end
 
     def reset_terminal
+      @saved_primary = nil
       @buffer = Array.new(@rows) { Array.new(@cols) { blank_cell } }
       @cursor_row = 0
       @cursor_col = 0
@@ -1423,6 +2099,7 @@ module Muxr
       @scroll_bottom = @rows - 1
       @autowrap_pending = false
       @current_hyperlink = nil
+      @cursor_visible = true
     end
   end
 end