muxr 0.1.11 → 0.2.0

data/lib/muxr/version.rb

@@ -1,3 +1,3 @@
 module Muxr
-  VERSION = "0.1.11"
+  VERSION = "0.2.0"
 end

data/lib/muxr/width_probe.rb

@@ -0,0 +1,121 @@
+module Muxr
+  # Measures how the *outer* terminal actually draws glyphs whose width muxr
+  # would otherwise have to guess, so the emulator and Renderer can be tuned to
+  # match it instead of disagreeing (the disagreement is what corrupts in-place
+  # animations — see Terminal::AMBIGUOUS_RANGES and Renderer#contiguous_after?).
+  #
+  # The technique is the classic cursor-position probe: print a test glyph at a
+  # known column, ask the terminal where its cursor landed with DSR-CPR
+  # (`\e[6n` → `\e[<row>;<col>R`), and the column delta is the glyph's real
+  # display width. This only works against a live TTY in raw mode, which is why
+  # it runs in the client (the piece that owns the terminal) and ships its
+  # verdict to the server in the HELLO handshake.
+  module WidthProbe
+    # Formal East Asian Ambiguous glyphs (all > U+0300 so the class toggle can
+    # actually reach them). A terminal in "ambiguous = wide" mode draws all of
+    # these two columns wide; a narrow terminal draws them one. We sample several
+    # and take a majority vote — the verdict configures Terminal.ambiguous_wide,
+    # which covers the long tail of ambiguous glyphs we don't sample by hand.
+    AMBIGUOUS_SAMPLES = ["…", "●", "→", "★", "◆"].freeze
+
+    # Specific glyphs whose width no Unicode class reliably predicts because a
+    # font may give them emoji presentation (drawn two wide) regardless of the
+    # terminal's ambiguous setting. These are exactly the glyphs Claude Code's
+    # UI animates in place. We measure each one individually and record its
+    # exact width as a per-codepoint override — ground truth beats any heuristic.
+    GLYPH_SAMPLES = ["⏺", "✻", "❯", "✦", "✳", "◼", "▪"].freeze
+
+    # Box-drawing and block elements (Terminal::BOX_RANGES). Formally Ambiguous,
+    # but many terminals keep them narrow even in ambiguous-as-wide mode, so the
+    # AMBIGUOUS_SAMPLES verdict can't speak for them. They need their own vote
+    # because Renderer#contiguous_after? relies on this band being narrow to skip
+    # cursor repositioning — if the terminal actually draws them wide, every
+    # glyph after one on the same line lands a column off, which is what mangles
+    # a border-heavy TUI like Claude Code.
+    BOX_SAMPLES = ["─", "│", "█", "▌"].freeze
+
+    # Overall wall-clock budget for the whole probe. A terminal that never
+    # answers DSR (rare, but possible over flaky ttys / odd emulators) must not
+    # wedge attach — we give up and fall back to defaults.
+    TIMEOUT = 0.3
+
+    # Probe the terminal reachable via +out+ (writable) and +input+ (readable),
+    # which must already be in raw mode. Returns a capabilities hash suitable
+    # for Protocol.encode_caps, e.g. {ambiguous: 2, glyphs: {0x23FA => 2}}.
+    # Returns {} when the terminal doesn't answer (callers treat that as "use
+    # defaults").
+    def self.run(out: $stdout, input: $stdin, timeout: TIMEOUT)
+      deadline = now + timeout
+      caps = {}
+
+      amb = AMBIGUOUS_SAMPLES.filter_map { |g| measure(g, out, input, deadline) }
+      # No answers at all → terminal doesn't speak CPR; don't claim to know.
+      return caps if amb.empty?
+      wide = amb.count { |w| w >= 2 }
+      caps[:ambiguous] = wide > (amb.length - wide) ? 2 : 1
+
+      box = BOX_SAMPLES.filter_map { |g| measure(g, out, input, deadline) }
+      unless box.empty?
+        box_wide = box.count { |w| w >= 2 }
+        caps[:box] = box_wide > (box.length - box_wide) ? 2 : 1
+      end
+
+      glyphs = {}
+      GLYPH_SAMPLES.each do |g|
+        w = measure(g, out, input, deadline)
+        # Clamp to the 1/2 the grid understands; ignore non-answers and any
+        # zero-advance oddity (an unrenderable glyph the terminal swallowed).
+        glyphs[g.ord] = (w >= 2 ? 2 : 1) if w && w >= 1
+      end
+      caps[:glyphs] = glyphs unless glyphs.empty?
+      caps
+    ensure
+      # Wipe whatever the probe painted; the server's first frame repaints all.
+      out.write("\e[H\e[2J")
+      out.flush
+    end
+
+    # Print +glyph+ at column 1 of the home row, then read the cursor column.
+    # Returns the glyph's display width (col - 1) or nil if no CPR came back in
+    # time. Latin-1 / ASCII control bytes in the glyph would skew the result,
+    # so callers pass only printable test glyphs.
+    def self.measure(glyph, out, input, deadline)
+      out.write("\e[H#{glyph}\e[6n")
+      out.flush
+      col = read_cpr_col(input, deadline)
+      return nil unless col
+      col - 1
+    end
+
+    # Read a DSR-CPR reply (`\e[<row>;<col>R`, optionally `\e[?<row>;<col>R`)
+    # from +input+, honoring the shared deadline. Bytes that aren't part of the
+    # reply (none are expected this early in attach) are discarded. Returns the
+    # column, or nil on timeout / closed input.
+    def self.read_cpr_col(input, deadline)
+      buf = +"".b
+      loop do
+        remaining = deadline - now
+        return nil if remaining <= 0
+        ready, = IO.select([input], nil, nil, remaining)
+        return nil unless ready
+        begin
+          chunk = input.read_nonblock(64)
+        rescue IO::WaitReadable
+          next
+        rescue EOFError, IOError, Errno::EIO
+          return nil
+        end
+        buf << chunk
+        if (m = buf.match(/\e\[\??\d+;(\d+)R/))
+          return m[1].to_i
+        end
+        # Guard against a stream that never contains a terminator.
+        return nil if buf.bytesize > 256
+      end
+    end
+
+    def self.now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/muxr/window.rb

@@ -5,8 +5,10 @@ module Muxr
   class Window
     LAYOUTS = LayoutManager::LAYOUTS
 
-    attr_accessor :name, :layout, :master_index
-    attr_reader :panes, :focused_index
+    RATIO_STEP = 0.05
+
+    attr_accessor :name, :layout, :master_index, :synchronized
+    attr_reader :panes, :focused_index, :master_ratio, :master_count
 
     def initialize(name: "main")
       @name = name
@@ -14,7 +16,30 @@ module Muxr
       @focused_index = 0
       @last_focused_pane = nil
       @master_index = 0
-      @layout = :spiral
+      @layout = :auto
+      @master_ratio = LayoutManager::DEFAULT_RATIO
+      @master_count = 1
+      @synchronized = false
+    end
+
+    def master_ratio=(value)
+      @master_ratio = value.to_f.clamp(LayoutManager::RATIO_BOUNDS).round(2)
+    end
+
+    def master_count=(value)
+      @master_count = [value.to_i, 1].max
+    end
+
+    def adjust_master_ratio(delta)
+      self.master_ratio = @master_ratio + delta
+    end
+
+    def adjust_master_count(delta)
+      self.master_count = (@master_count + delta).clamp(1, [@panes.length, 1].max)
+    end
+
+    def layout_options
+      { master_index: @master_index, ratio: @master_ratio, nmaster: @master_count }
     end
 
     # Setter records the outgoing focused pane (by reference) so focus_last can
@@ -100,6 +125,7 @@ module Muxr
     end
 
     def cycle_layout
+      @zoom_return = nil
       i = LAYOUTS.index(@layout) || 0
       @layout = LAYOUTS[(i + 1) % LAYOUTS.length]
     end
@@ -107,9 +133,30 @@ module Muxr
     def set_layout(layout)
       layout = layout.to_sym
       raise ArgumentError, "Unknown layout: #{layout}" unless LAYOUTS.include?(layout)
+      @zoom_return = nil
       @layout = layout
     end
 
+    def zoomed?
+      !@zoom_return.nil?
+    end
+
+    attr_reader :zoom_return
+
+    def toggle_zoom
+      if zoomed?
+        @layout = @zoom_return
+        @zoom_return = nil
+      elsif @layout != :monocle
+        @zoom_return = @layout
+        @layout = :monocle
+      end
+    end
+
+    def resting_layout
+      @zoom_return || @layout
+    end
+
     def clamp_indices!
       if @panes.empty?
         @focused_index = 0

data/lib/muxr.rb

@@ -1,16 +1,24 @@
 require_relative "muxr/version"
 require_relative "muxr/pty_process"
+require_relative "muxr/image_store"
+require_relative "muxr/mouse_report"
 require_relative "muxr/terminal"
+require_relative "muxr/remote_pane"
 require_relative "muxr/pane"
+require_relative "muxr/pane_transfer"
 require_relative "muxr/drawer"
 require_relative "muxr/foreground_command"
 require_relative "muxr/layout_manager"
 require_relative "muxr/window"
 require_relative "muxr/session"
+require_relative "muxr/session_directory"
+require_relative "muxr/pane_picker"
 require_relative "muxr/renderer"
 require_relative "muxr/input_handler"
 require_relative "muxr/command_dispatcher"
+require_relative "muxr/config"
 require_relative "muxr/protocol"
+require_relative "muxr/width_probe"
 require_relative "muxr/control_server"
 require_relative "muxr/application"
 require_relative "muxr/client"

data/muxr.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.4"
 
   spec.metadata = {
+    "homepage_uri"          => "https://roelbondoc.github.io/muxr/",
     "source_code_uri"       => "https://github.com/roelbondoc/muxr",
     "bug_tracker_uri"       => "https://github.com/roelbondoc/muxr/issues",
     "changelog_uri"         => "https://github.com/roelbondoc/muxr/blob/main/CHANGELOG.md",
@@ -39,6 +40,15 @@ Gem::Specification.new do |spec|
   ]
   spec.require_paths = ["lib"]
 
+  spec.post_install_message = <<~MSG
+    muxr ships a Claude Code skill for driving sessions over MCP. To install it
+    into ~/.claude/skills and print the `claude mcp add` line for the bridge:
+
+        muxr --install-skill
+
+    Re-run it after each `gem update muxr` to refresh the skill contents.
+  MSG
+
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "rake", "~> 13.0"
 end

data/skills/muxr-control/SKILL.md

@@ -3,9 +3,11 @@ name: muxr-control
 description: |
   Use when driving a muxr terminal session — running commands across panes,
   watching long-running processes, capturing terminal output, setting up
-  layouts, or working with the muxr drawer. Triggers when MUXR_SESSION is
-  set in the environment, or when the user asks to "run X in pane Y",
-  "what does pane N show", "switch the muxr layout", etc.
+  layouts, working with the muxr drawer, or driving a full-screen TUI app
+  (vim, a notebook, lazygit) that is already running inside a pane.
+  Triggers when MUXR_SESSION is set in the environment, or when the user
+  asks to "run X in pane Y", "what does pane N show", "drive the editor in
+  pane 1", "switch the muxr layout", etc.
 ---
 
 # muxr-control
@@ -21,7 +23,8 @@ settle — without taking control of the user's keyboard.
 Before doing anything else, call **`muxr_session_get`** and
 **`muxr_panes_list`**. These are cheap, idempotent reads. They tell you:
 
-- The session name, layout (tall / grid / monocle), and current dimensions.
+- The session name, current layout, the full `available_layouts` list, and
+  the session dimensions.
 - Each pane's stable id (6 hex chars, e.g. `a3f9b2`), its 1-based slot
   number as shown on screen (`#1`, `#2`, …), its cwd, and whether it's the
   focused or master pane.
@@ -42,6 +45,13 @@ the user says "the second pane", look it up in `muxr_panes_list` and pass
 the id you find at slot 2 — don't pass `2` directly even though it works,
 because by the time the call lands the slots may have changed.
 
+A pane the human has named with `:rename` shows the name in place of the id
+(`#1 api`), and `muxr_panes_list` reports it as `name`. When the user refers
+to a pane by that name ("run the tests in `api`"), you may pass the name as
+`pane`. A name that is ambiguous, or that has since been changed, is refused
+rather than guessed, so the id is still the safer choice for any call you
+make after a list.
+
 ## Recipes
 
 ### Run a command and get its output
@@ -70,7 +80,7 @@ the shell has redrawn the prompt, and you'll miss the output entirely.
 - **Long builds** (npm install, cargo build): bump `timeout_ms` to
   `120000` or higher. Default is 30s.
 
-### Wait without sending anything
+### Wait for something already running
 
 ```
 muxr_pane_run({ "pane": "a3f9b2", "input": "", "append_enter": false,
@@ -78,7 +88,19 @@ muxr_pane_run({ "pane": "a3f9b2", "input": "", "append_enter": false,
 ```
 
 Useful when the user has already typed a command and you want to capture
-its output once it finishes.
+its output once it finishes — but **only if output is still coming.**
+
+The idle timer is gated on having seen output at all: `pane.run` resolves
+early only once the pane has emitted *something* and then gone quiet. On a
+pane that stays silent for the whole wait, the only exit is the deadline,
+so the call blocks for the full `timeout_ms` and returns
+`timed_out: true` — which looks like a failure but just means "nothing
+happened." A 30s timeout on an already-finished command costs you 30s.
+
+So for a pane that may already be quiet, **poll with `muxr_pane_read`
+instead** — it returns instantly, has no side effects, and re-reading a
+few times is cheaper than one mis-sized wait. Reserve `pane.run` for input
+you expect to produce output.
 
 ### Send multi-line input (paste mode)
 
@@ -115,6 +137,79 @@ Avoid doing this unsolicited — the human owns the layout. Only restructure
 when the user explicitly asks ("set up a dev environment", "split this
 into 3 panes").
 
+## Driving a full-screen TUI app
+
+A pane may hold a full-screen application (vim, euporie, lazygit, htop, a
+TUI notebook) rather than a shell prompt. Everything below is about those;
+shells are more forgiving.
+
+### One key per call. Never batch repeats.
+
+Both `pane.send_input` and `pane.run` concatenate the entire `keys` array
+into one payload and hand it to the PTY in a **single write**, with no
+pacing between keys. A shell's line editor handles that fine. An app that
+kicks off async work per keypress often does not: sending
+`["<c-r>", "<c-r>", … ]` nine times to a TUI notebook produced **three**
+actions, not nine — the rest were swallowed while the app was mid-render.
+Sending the same key one call at a time worked every time.
+
+Batching is safe for a *heterogeneous* scripted sequence where each key
+does something different and cheap:
+
+```
+muxr_pane_send_input({ "pane": "a3f9b2",
+                       "keys": ["G", "o", "hello world", "<esc>", ":w", "<enter>"] })
+```
+
+Batching is **not** safe for "do this N times." Loop the call instead, and
+confirm the app actually advanced between iterations (see below).
+
+### The status bar is ground truth, not the layout
+
+Infer app state from whatever the app *prints* about itself — the status
+line, a mode indicator, an execution counter — never from where borders or
+highlights appear to be drawn. Box-drawing and reverse-video regions are
+easy to misread, and the cell/buffer/pane you think is selected is
+routinely not the one you think. If the app tells you `Cell 9`, believe
+that over a box that looks like it surrounds cell 8.
+
+This is also how you verify the previous point: read the indicator, send
+one key, re-read, confirm it moved.
+
+### Use the `cursor` field to find focus in a dialog
+
+`pane.read` and `pane.run` both return `cursor: {row, col}`. In a modal
+dialog from prompt_toolkit, ncurses, and friends, the cursor parks on the
+**focused widget** — so it is the reliable way to tell which of
+`[ Yes ] [ No ] [ Cancel ]` is armed, when the rendered text gives you
+nothing to go on.
+
+The safe gesture for any dialog you did not expect:
+
+1. `pane_read` — note `cursor`.
+2. Send one `<tab>` or `<right>`.
+3. Re-read and confirm the cursor **moved**.
+4. Only then press `<enter>`.
+
+Use cursor **deltas**, never absolute column arithmetic. `text` is trimmed
+of trailing whitespace per row, and double-width glyphs (box-drawing,
+block elements, emoji — heavily used by TUI dialogs) desync any attempt to
+map a `col` onto an index into the row string. Two adjacent buttons in one
+real dialog reported cols 63 and 75.
+
+### Scroll with the app's own keys, not muxr scrollback
+
+`pane.read` is viewport-only, and a full-screen app *owns* its viewport: it
+paints one screenful and keeps the rest in its own internal buffer. Content
+below the fold is invisible to `pane.read` **and** absent from muxr's
+scrollback, because it was never emitted as scrolled-off terminal output.
+`Ctrl-a [` will not find it.
+
+So to see the rest, drive the app's own scroll binding (euporie `]`/`}`,
+vim `Ctrl-d`, less `space`) and re-read. Corollary: a command's output can
+be sitting in the pane, already complete, and still absent from your last
+read — check the app's own indicator before concluding a step didn't run.
+
 ## Gotchas
 
 ### Reading is cheap. Writing is destructive.
@@ -140,6 +235,9 @@ not in the response. If you need older output, ask the user to scroll
 the pane up first (they have `Ctrl-a [` for scrollback mode), or watch
 the pane via `muxr_pane_run` while the command is running.
 
+If the pane holds a full-screen app, `Ctrl-a [` won't help either — see
+"Scroll with the app's own keys" above.
+
 ### Private panes
 
 The user can mark any pane *private* with `Ctrl-a P` (status bar shows
@@ -158,6 +256,41 @@ is no `muxr_pane_unmark_private` tool.
 (they're layout ops, not content ops) — useful if the user asks to
 "bring my private pane to the front" without exposing it.
 
+### Borrowed panes belong to another session
+
+A pane the user attached from another muxr session (`A` / `C-a A`) shows
+up in `muxr_panes_list` with an `"origin"` of `"<session>:<pane id>"`,
+and in the pane title as `@work:6021b5`. It behaves like any other pane
+for reads and input — those reach the real shell, in the session that
+owns it — with two differences worth knowing:
+
+- `muxr_pane_kill` only detaches the mirror. The shell keeps running in
+  its home session. If the user asks you to kill it, say that's what
+  happened rather than reporting the process gone.
+- It can vanish without dying: if the owning session goes away, or the
+  pane is moved somewhere else, it disappears from `muxr_panes_list`.
+  Re-read the list rather than assuming a stale id.
+- Its size is negotiated with the owner, so `muxr_layout_set` may not
+  give it the dimensions you'd expect from the layout alone.
+
+Anything you type there is visible to whoever is looking at the owning
+session, live. Treat it the way you'd treat a shared screen.
+
+A pane the user *moved* here (rather than shared) has no `origin` — it is
+an ordinary local pane, even though the shell inside it has been running
+since before it arrived. Don't assume a pane's history started in this
+session.
+
+### You are running in one of these panes
+
+`MUXR_PANE` in your environment is the id of the pane hosting you. The
+bridge refuses `muxr_pane_read`, `muxr_pane_send_input`, `muxr_pane_run`
+and `muxr_pane_kill` on that id — driving your own pty feeds your output
+back to you, and reading it just returns your own UI. Check `MUXR_PANE`
+before picking a target, and don't try to route around the refusal by
+re-running the command in a pane you then read; ask the user to open
+another pane if you need somewhere to work.
+
 ### The drawer might be Claude itself
 
 If the bridge sees the env var `MUXR_DRAWER_SELF=1` it refuses
@@ -166,6 +299,21 @@ muxr drawer and the call would recurse into your own pty. If you get
 that error, that's why: you can still drive the surrounding tiled panes
 normally, you just can't toggle/read the drawer that's hosting you.
 
+### The session you reach may not be the one in your env
+
+A pane can be moved between sessions while its shell keeps running, so
+`MUXR_SESSION` can name a session you have since left. The bridge follows
+`MUXR_PANE` to whichever server actually owns you and re-checks every ten
+seconds — so trust `muxr_session_get` over the environment if the two
+disagree, and re-list panes rather than reusing ids you cached from a
+session you are no longer in.
+
+### No tools at all means no session
+
+If `muxr_*` tools aren't listed, this claude isn't inside muxr (or its
+server isn't running). The bridge advertises nothing rather than failing
+to start. Nothing to fix — just don't claim you can drive panes.
+
 ### Don't toggle the drawer just to peek
 
 `muxr_drawer_read` works without showing the drawer. Toggling it to
@@ -180,8 +328,10 @@ If a tool call returns `isError: true`, the text usually starts with
 - `muxr error -32602: pane: no pane with id "…"` — the pane has been
   killed, or you passed a stale id from before a kill/promote. Refetch
   `muxr_panes_list`.
-- `muxr error -32602: layout: unknown layout` — valid layouts are
-  `tall`, `grid`, `monocle`.
+- `muxr error -32602: layout: unknown layout` — the ten valid layouts are
+  `tall`, `wide`, `columns`, `rows`, `grid`, `spiral`, `centered`, `stack`,
+  `monocle`, `auto`. `muxr_session_get` returns the live list in
+  `available_layouts`; trust that over any list written down here.
 
 ## Naming muxr in conversation
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: muxr
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.2.0
 platform: ruby
 authors:
 - Roel Bondoc
@@ -59,19 +59,28 @@ files:
 - lib/muxr/application.rb
 - lib/muxr/client.rb
 - lib/muxr/command_dispatcher.rb
+- lib/muxr/config.rb
 - lib/muxr/control_server.rb
 - lib/muxr/drawer.rb
 - lib/muxr/foreground_command.rb
+- lib/muxr/history_row.rb
+- lib/muxr/image_store.rb
 - lib/muxr/input_handler.rb
 - lib/muxr/key_parser.rb
 - lib/muxr/layout_manager.rb
+- lib/muxr/mouse_report.rb
 - lib/muxr/pane.rb
+- lib/muxr/pane_picker.rb
+- lib/muxr/pane_transfer.rb
 - lib/muxr/protocol.rb
 - lib/muxr/pty_process.rb
+- lib/muxr/remote_pane.rb
 - lib/muxr/renderer.rb
 - lib/muxr/session.rb
+- lib/muxr/session_directory.rb
 - lib/muxr/terminal.rb
 - lib/muxr/version.rb
+- lib/muxr/width_probe.rb
 - lib/muxr/window.rb
 - muxr.gemspec
 - skills/muxr-control/SKILL.md
@@ -79,11 +88,19 @@ homepage: https://github.com/roelbondoc/muxr
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://roelbondoc.github.io/muxr/
   source_code_uri: https://github.com/roelbondoc/muxr
   bug_tracker_uri: https://github.com/roelbondoc/muxr/issues
   changelog_uri: https://github.com/roelbondoc/muxr/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
+post_install_message: |
+  muxr ships a Claude Code skill for driving sessions over MCP. To install it
+  into ~/.claude/skills and print the `claude mcp add` line for the bridge:
+
+      muxr --install-skill
+
+  Re-run it after each `gem update muxr` to refresh the skill contents.
 rdoc_options: []
 require_paths:
 - lib