muxr 0.1.4 → 0.1.6

data/lib/muxr/foreground_command.rb

@@ -0,0 +1,86 @@
+module Muxr
+  # Looks up the foreground command running inside a PTY by walking from the
+  # shell's pid → its tpgid (foreground process group on the controlling tty)
+  # → that process's command name. Hides the result when the shell itself is
+  # foreground so titles aren't full of "bash" / "zsh" noise.
+  #
+  # Two platform paths:
+  #   Linux: /proc/<pid>/stat (no fork — runs fast even on the main thread,
+  #          though Application uses a background thread anyway)
+  #   macOS: ps -o tpgid=,pgid= -p <pid> + ps -o comm= -p <tpgid>. Two
+  #          fork+execs, ~10–20ms total — exactly the reason callers run
+  #          this off the event-loop thread.
+  #
+  # Returns the command name string or nil. nil also covers "couldn't read"
+  # so callers degrade silently rather than risk showing stale data.
+  module ForegroundCommand
+    # Command names we never want to surface — these are the empty-prompt
+    # case. If a user genuinely runs `bash` inside `bash` we'll under-report
+    # rather than mis-report.
+    SHELLS = %w[bash zsh fish sh dash ksh tcsh csh].freeze
+
+    module_function
+
+    def lookup(pid)
+      return nil unless pid.is_a?(Integer) && pid > 0
+      tpgid, pgid =
+        if File.exist?("/proc/#{pid}/stat")
+          linux_tpgid(pid)
+        else
+          macos_tpgid(pid)
+        end
+      return nil unless tpgid && pgid
+      return nil if tpgid <= 0
+      return nil if tpgid == pgid # shell is its own foreground — empty prompt
+
+      name =
+        if File.exist?("/proc/#{tpgid}/comm")
+          File.read("/proc/#{tpgid}/comm").strip
+        else
+          `ps -o comm= -p #{tpgid} 2>/dev/null`.strip
+        end
+      normalize(name)
+    rescue StandardError
+      nil
+    end
+
+    # Public for testing — strips path/dash/whitespace and filters shells.
+    def normalize(name)
+      return nil if name.nil? || name.empty?
+      name = name.strip
+      name = name.sub(/\A-/, "") # login shells appear as "-bash"
+      name = File.basename(name)
+      return nil if name.empty?
+      return nil if SHELLS.include?(name)
+      name
+    end
+
+    # Public for testing — parses Linux /proc/<pid>/stat into [tpgid, pgid].
+    # The comm field can contain spaces and parens, so we slice from the
+    # last ')' rather than splitting from the start.
+    def parse_linux_stat(raw)
+      idx = raw.rindex(")")
+      return [nil, nil] unless idx
+      tail = raw[(idx + 2)..]
+      return [nil, nil] unless tail
+      fields = tail.split(" ")
+      # After the closing paren the fields are:
+      #   state(0) ppid(1) pgrp(2) session(3) tty_nr(4) tpgid(5) ...
+      pgid  = fields[2]&.to_i
+      tpgid = fields[5]&.to_i
+      [tpgid, pgid]
+    end
+
+    def linux_tpgid(pid)
+      raw = File.read("/proc/#{pid}/stat")
+      parse_linux_stat(raw)
+    end
+
+    def macos_tpgid(pid)
+      out = `ps -o tpgid=,pgid= -p #{pid} 2>/dev/null`.strip
+      return [nil, nil] if out.empty?
+      tpgid, pgid = out.split.map(&:to_i)
+      [tpgid, pgid]
+    end
+  end
+end

data/lib/muxr/input_handler.rb

@@ -1,21 +1,67 @@
 module Muxr
-  # Translates raw keystrokes into either commands (when the Ctrl-a prefix is
-  # active) or passthrough bytes to the focused pane. The handler is a small
-  # state machine: :idle → :prefix → :idle, with a separate :command branch
-  # for the ":"-driven mini-command line.
+  # Translates raw keystrokes into either commands or pane input. Two top-level
+  # modes:
+  #
+  #   :normal       Default. Single-key bindings (hjkl navigation, t/g/m for
+  #                 layouts, c/K for create/kill, etc.) act directly without
+  #                 any prefix. `i` drops into passthrough.
+  #
+  #   :passthrough  Historical mode: every key is forwarded to the focused
+  #                 pane unless prefixed by Ctrl-a. `Ctrl-a Esc` returns to
+  #                 normal mode.
+  #
+  # Plus the sub-states pre-existing from before modes existed:
+  #   :prefix, :command, :confirm_quit, :help, :scrollback, :selection.
+  #
+  # One-shot sub-states (prefix, command, confirm_quit, help) return to
+  # @base_mode (whichever of :normal/:passthrough is active) when they
+  # finish. :scrollback and :selection also return to @base_mode so that
+  # exiting back from a scroll/yank lands you back in passthrough if that's
+  # where you came from.
   class InputHandler
     PREFIX = "\x01".freeze # Ctrl-a
 
+    # Single-key bindings in normal mode. Same actions as their Ctrl-a-
+    # prefixed counterparts in passthrough, just without the prefix.
+    # Value forms:
+    #   :symbol            → @app.public_send(:symbol)
+    #   [:symbol, *args]   → @app.public_send(:symbol, *args)
+    NORMAL_BINDINGS = {
+      "c"  => :new_pane,
+      "K"  => :close_focused,
+      "t"  => [:set_layout, :tall],
+      "g"  => [:set_layout, :grid],
+      "m"  => [:set_layout, :monocle],
+      "\t" => :cycle_layout,
+      "\r" => :promote_master,
+      "\n" => :promote_master,
+      "h"  => [:focus_direction, :left],
+      "j"  => [:focus_direction, :down],
+      "k"  => [:focus_direction, :up],
+      "l"  => [:focus_direction, :right],
+      "a"  => :focus_last,
+      "~"  => :toggle_drawer,
+      "C"  => :toggle_claude_drawer,
+      "P"  => :toggle_private_focused,
+      "d"  => :detach,
+      "?"  => :show_help,
+      "q"  => :quit_immediate,
+      "s"  => :enter_scrollback,
+      "]"  => :paste_from_buffer
+    }.freeze
+
     PREFIX_BINDINGS = {
       "c"    => :new_pane,
       "n"    => :focus_next,
       "p"    => :focus_prev,
       "a"    => :focus_last,
-      "k"    => :close_focused,
+      "K"    => :close_focused,
       "\t"   => :cycle_layout,
       "\r"   => :promote_master,
       "\n"   => :promote_master,
       "~"    => :toggle_drawer,
+      "C"    => :toggle_claude_drawer,
+      "P"    => :toggle_private_focused,
       "d"    => :detach,
       "?"    => :show_help,
       "q"    => :quit_immediate,
@@ -67,8 +113,10 @@ module Muxr
       "u"    => :half_up,
       "\x06" => :full_down, # Ctrl-f
       "\x02" => :full_up,   # Ctrl-b
-      "f"    => :full_down,
-      " "    => :full_down
+      "f"    => :full_down
+      # NOTE: space is intentionally absent here — it's a top-level toggle
+      # for linear selection (see handle_selection_input), mirroring vim's
+      # `v` so the right thumb has a one-key way to anchor/release.
     }.freeze
 
     SELECTION_YANK = ["\r", "\n", "y"].freeze
@@ -76,22 +124,22 @@ module Muxr
 
     DIGIT_RE = /\A[1-9]\z/.freeze
 
-    attr_reader :state, :command_buffer
+    attr_reader :state, :command_buffer, :base_mode
 
     def initialize(app)
       @app = app
-      @state = :idle
+      @state = :normal
+      @base_mode = :normal
       @command_buffer = +""
     end
 
     def feed(data)
       remaining = data
       until remaining.empty?
-        if @state == :idle
-          # Fast path for pass-through: forward everything up to the next
-          # Ctrl-a as a single chunk so a large paste doesn't turn into one
-          # PTY write per byte. PREFIX is single-byte ASCII (\x01) and never
-          # appears mid-UTF-8, so byte/char index match.
+        if @state == :passthrough
+          # Fast path: batch everything up to the next Ctrl-a as one chunk so
+          # a large paste doesn't turn into one PTY write per byte. PREFIX is
+          # single-byte ASCII (\x01) and never appears mid-UTF-8.
           idx = remaining.index(PREFIX)
           if idx.nil?
             @app.send_to_focused(remaining)
@@ -106,9 +154,11 @@ module Muxr
         ch = remaining[0]
         remaining = remaining[1..] || ""
         case @state
+        when :normal
+          handle_normal(ch)
         when :help
           @app.dismiss_help
-          @state = :idle
+          @state = @base_mode
         when :confirm_quit
           handle_confirm_quit(ch)
         when :prefix
@@ -139,40 +189,96 @@ module Muxr
       @state = :selection
     end
 
+    # Drop into passthrough — every key reaches the focused pane until the
+    # user issues Ctrl-a Esc.
+    def enter_passthrough_mode
+      @state = :passthrough
+      @base_mode = :passthrough
+    end
+
+    # Return to normal mode. Used by the `Ctrl-a Esc` binding from
+    # passthrough — explicitly resets @base_mode so the user genuinely
+    # leaves passthrough.
+    def enter_normal_mode
+      @state = :normal
+      @base_mode = :normal
+    end
+
+    # Exit a sub-state (scrollback, selection-yank) and resume the mode the
+    # user was in before they entered scrollback. Preserves @base_mode so
+    # a passthrough → scrollback → exit round-trip lands back in passthrough.
     def enter_idle_mode
-      @state = :idle
+      @state = @base_mode
     end
 
     def cancel
-      @state = :idle
+      @state = @base_mode
       @command_buffer = +""
     end
 
     private
 
+    def handle_normal(ch)
+      if ch == "i"
+        # Internal state flip happens here so a bare FakeApp in tests still
+        # transitions; the Application callback redundantly flips state
+        # (idempotent) and adds the user-visible flash.
+        enter_passthrough_mode
+        @app.enter_passthrough_mode
+        return
+      end
+      if ch == ":"
+        @state = :command
+        @command_buffer = +""
+        return
+      end
+      if DIGIT_RE.match?(ch)
+        @app.focus_pane_number(ch.to_i)
+        return
+      end
+
+      action = NORMAL_BINDINGS[ch]
+      case action
+      when Symbol
+        @app.public_send(action)
+      when Array
+        @app.public_send(*action)
+      end
+      # Unknown key: ignore. Avoids accidental side-effects when the user
+      # mistypes — same rationale as scrollback mode.
+    end
+
     def handle_prefix(ch)
       action = PREFIX_BINDINGS[ch]
       case
+      when ch == "\e"
+        # Ctrl-a Esc → return to normal mode. Flip state directly so tests
+        # with a bare FakeApp transition; the Application callback is
+        # idempotent and adds the flash message.
+        enter_normal_mode
+        @app.enter_normal_mode
       when ch == ":"
         @state = :command
         @command_buffer = +""
       when ch == PREFIX
         @app.send_to_focused(PREFIX)
-        @state = :idle
+        @state = @base_mode
       when DIGIT_RE.match?(ch)
         @app.focus_pane_number(ch.to_i)
-        @state = :idle
+        @state = @base_mode
       when action
         @app.public_send(action)
-        @state = :idle if @state == :prefix
+        # The action may have set a new state (confirm_quit, scrollback,
+        # help). Only revert to base mode if we're still in :prefix.
+        @state = @base_mode if @state == :prefix
       else
-        # Unknown prefix-key: return to idle silently.
-        @state = :idle
+        # Unknown prefix key: return to base mode silently.
+        @state = @base_mode
       end
     end
 
     def handle_confirm_quit(ch)
-      @state = :idle
+      @state = @base_mode
       if ch == "y" || ch == "Y"
         @app.confirm_quit
       else
@@ -182,7 +288,7 @@ module Muxr
 
     def handle_scrollback_input(ch)
       if SCROLLBACK_EXITS.include?(ch)
-        @state = :idle
+        enter_idle_mode
         @app.exit_scrollback
         return
       end
@@ -206,7 +312,7 @@ module Muxr
         return
       end
       case ch
-      when "v"
+      when "v", " "
         @app.toggle_selection(:linear)
         return
       when "\x16" # Ctrl-v
@@ -223,11 +329,11 @@ module Muxr
       when "\r", "\n"
         cmd = @command_buffer.dup
         @command_buffer = +""
-        @state = :idle
+        @state = @base_mode
         @app.run_command(cmd)
       when "\e"
         @command_buffer = +""
-        @state = :idle
+        @state = @base_mode
         @app.invalidate
       when "\x7f", "\b"
         @command_buffer.chop!

data/lib/muxr/key_parser.rb

@@ -0,0 +1,89 @@
+module Muxr
+  # Translates an array of "keys" entries (a mix of literal text and vim-style
+  # named keys like "<esc>") into a stream of byte segments tagged by kind.
+  #
+  # Each input element is either:
+  #
+  #   - Literal text (UTF-8) — emitted as [:literal, bytes].
+  #   - A named key wrapped in angle brackets like "<esc>", "<c-c>", "<up>" —
+  #     emitted as [:special, bytes] using the appropriate control sequence.
+  #
+  # The tagged form lets callers wrap *only* literal segments in
+  # bracketed-paste markers when desired. Concatenating the bytes of all
+  # segments gives the raw byte stream to write to the PTY.
+  module KeyParser
+    NAMED_KEY_RE = /\A<([^<>]+)>\z/.freeze
+
+    # CSI = ESC [ , SS3 = ESC O — both standard xterm key encodings.
+    CSI = "\e[".b.freeze
+    SS3 = "\eO".b.freeze
+
+    # Single canonical map. Keys are lowercased; aliases live alongside their
+    # canonical forms. Values are ASCII byte strings.
+    NAMED_KEYS = {
+      "esc"      => "\e".b,
+      "escape"   => "\e".b,
+      "enter"    => "\r".b,
+      "cr"       => "\r".b,
+      "return"   => "\r".b,
+      "tab"      => "\t".b,
+      "s-tab"    => "#{CSI}Z".b,
+      "bs"       => "\x7f".b, # what real backspace keys send through a PTY
+      "backspace"=> "\x7f".b,
+      "space"    => " ".b,
+      "up"       => "#{CSI}A".b,
+      "down"     => "#{CSI}B".b,
+      "right"    => "#{CSI}C".b,
+      "left"     => "#{CSI}D".b,
+      "home"     => "#{CSI}H".b,
+      "end"      => "#{CSI}F".b,
+      "pageup"   => "#{CSI}5~".b,
+      "pagedown" => "#{CSI}6~".b,
+      "f1"       => "#{SS3}P".b,
+      "f2"       => "#{SS3}Q".b,
+      "f3"       => "#{SS3}R".b,
+      "f4"       => "#{SS3}S".b,
+      "f5"       => "#{CSI}15~".b,
+      "f6"       => "#{CSI}17~".b,
+      "f7"       => "#{CSI}18~".b,
+      "f8"       => "#{CSI}19~".b,
+      "f9"       => "#{CSI}20~".b,
+      "f10"      => "#{CSI}21~".b,
+      "f11"      => "#{CSI}23~".b,
+      "f12"      => "#{CSI}24~".b
+    }.freeze
+
+    CTRL_RE = /\Ac-([a-z])\z/.freeze
+
+    module_function
+
+    # Returns an array of [kind, bytes] pairs. Raises Dispatcher::Error on a
+    # non-array input or an unrecognized `<name>`.
+    def translate(entries)
+      raise Dispatcher::Error.new("`keys` must be an array of strings") unless entries.is_a?(Array)
+
+      entries.map do |entry|
+        raise Dispatcher::Error.new("`keys` entries must be strings") unless entry.is_a?(String)
+        classify(entry)
+      end
+    end
+
+    def classify(entry)
+      m = NAMED_KEY_RE.match(entry)
+      return [:literal, entry.b] unless m
+
+      name = m[1].downcase
+      bytes = NAMED_KEYS[name] || ctrl_bytes(name)
+      raise Dispatcher::Error.new("unknown named key #{entry.inspect}") unless bytes
+
+      [:special, bytes]
+    end
+
+    def ctrl_bytes(name)
+      m = CTRL_RE.match(name)
+      return nil unless m
+      # <c-a>=0x01 .. <c-z>=0x1A
+      (m[1].ord - "a".ord + 1).chr.b
+    end
+  end
+end

data/lib/muxr/layout_manager.rb

@@ -87,5 +87,64 @@ module Muxr
     def monocle(count, area, _focused_index = 0)
       Array.new(count) { Rect.new(area.x, area.y, area.w, area.h) }
     end
+
+    # Return the index of the closest pane in `direction` (:left/:right/:up/:down)
+    # from the focused pane. Pure function over the rect list — does not know
+    # about the layout that produced the rects.
+    #
+    # Selection rule: among panes strictly on the requested side, prefer the
+    # one with the largest perpendicular overlap with the focused pane;
+    # tie-break by smallest axis-distance, then by smallest center offset.
+    # Returns nil when nothing qualifies (e.g. focused is the rightmost pane
+    # and direction is :right, or monocle where every rect is identical).
+    def neighbor(rects, focused_index, direction)
+      return nil if rects.nil? || rects.empty?
+      return nil unless focused_index.is_a?(Integer)
+      return nil unless focused_index.between?(0, rects.length - 1)
+      focused = rects[focused_index]
+      return nil unless focused
+
+      best = nil
+      rects.each_with_index do |rect, idx|
+        next if idx == focused_index || rect.nil?
+
+        case direction
+        when :right
+          next unless rect.x >= focused.x + focused.w
+          axis_dist = rect.x - (focused.x + focused.w)
+          overlap   = overlap_extent(focused.y, focused.h, rect.y, rect.h)
+          center    = ((rect.y + rect.h / 2.0) - (focused.y + focused.h / 2.0)).abs
+        when :left
+          next unless rect.x + rect.w <= focused.x
+          axis_dist = focused.x - (rect.x + rect.w)
+          overlap   = overlap_extent(focused.y, focused.h, rect.y, rect.h)
+          center    = ((rect.y + rect.h / 2.0) - (focused.y + focused.h / 2.0)).abs
+        when :down
+          next unless rect.y >= focused.y + focused.h
+          axis_dist = rect.y - (focused.y + focused.h)
+          overlap   = overlap_extent(focused.x, focused.w, rect.x, rect.w)
+          center    = ((rect.x + rect.w / 2.0) - (focused.x + focused.w / 2.0)).abs
+        when :up
+          next unless rect.y + rect.h <= focused.y
+          axis_dist = focused.y - (rect.y + rect.h)
+          overlap   = overlap_extent(focused.x, focused.w, rect.x, rect.w)
+          center    = ((rect.x + rect.w / 2.0) - (focused.x + focused.w / 2.0)).abs
+        else
+          return nil
+        end
+
+        score = [-overlap, axis_dist, center]
+        if best.nil? || (score <=> best[0]) < 0
+          best = [score, idx]
+        end
+      end
+      best && best[1]
+    end
+
+    def overlap_extent(a_start, a_size, b_start, b_size)
+      finish = [a_start + a_size, b_start + b_size].min
+      start  = [a_start, b_start].max
+      [finish - start, 0].max
+    end
   end
 end

data/lib/muxr/pane.rb

@@ -1,19 +1,66 @@
+require "securerandom"
+
 module Muxr
   # A Pane bundles a Terminal emulator buffer with the PTYProcess running the
   # shell that feeds it. The Window keeps a list of panes; the Renderer asks
   # each pane for its current grid contents and cursor position.
+  #
+  # Each pane has a stable 6-hex id generated at creation. The id survives
+  # promote_to_master and other array reshuffles (since it lives on the Pane,
+  # not on the index) and is persisted in the session JSON so it also survives
+  # a full cold restart. The drawer pane uses the symbol `:drawer` as its id;
+  # the MCP control surface treats it specially and never lists it under
+  # `panes.list`.
   class Pane
     attr_reader :id, :terminal, :process
     attr_accessor :rect
+    # Last value written by Application's foreground poller thread. nil when
+    # the shell itself is foreground (the common empty-prompt case) or when
+    # the lookup hasn't run / couldn't read. Renderer surfaces this in the
+    # pane title.
+    attr_accessor :foreground_command
 
-    def initialize(id:, rows: 24, cols: 80, cwd: nil, command: nil, process: nil)
-      @id = id
+    def initialize(id: nil, rows: 24, cols: 80, cwd: nil, command: nil, env_overrides: nil, process: nil)
+      @id = id || SecureRandom.hex(3)
       @rows = rows
       @cols = cols
       @terminal = Terminal.new(rows: rows, cols: cols)
-      @process = process || PTYProcess.new(rows: rows, cols: cols, cwd: cwd, command: command)
+      @process = process || PTYProcess.new(
+        rows: rows,
+        cols: cols,
+        cwd: cwd,
+        command: command,
+        env_overrides: env_overrides || {}
+      )
       @rect = nil
       @initial_cwd = cwd || @process.cwd
+      @private_flag = false
+      @foreground_command = nil
+    end
+
+    def pid
+      @process.pid
+    end
+
+    # Private panes are invisible to the MCP control surface — their cwd is
+    # stripped from panes.list and pane.read/send_input/run/subscribe/kill
+    # all refuse. Toggled by the human via Ctrl-a P or `:private`. Never
+    # settable from the control surface itself (so a misbehaving MCP client
+    # can't unmark a pane it shouldn't see).
+    def private?
+      @private_flag
+    end
+
+    def mark_private!
+      @private_flag = true
+    end
+
+    def mark_public!
+      @private_flag = false
+    end
+
+    def toggle_private!
+      @private_flag = !@private_flag
     end
 
     def io
@@ -51,6 +98,16 @@ module Muxr
         @terminal.feed(chunk)
         total += chunk.bytesize
       end
+      # The emulator may owe the inner program a reply (DSR / CPR — see
+      # Terminal#take_pending_replies!). Ship it back through the PTY's
+      # input side as if it had been typed. Failure here is non-fatal: the
+      # process can have exited between read and write.
+      if (reply = @terminal.take_pending_replies!)
+        begin
+          @process.write(reply)
+        rescue Errno::EIO, Errno::EPIPE
+        end
+      end
       total.positive? ? total : nil
     end