rubyterm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20a2cc824f4577e989c6088109c8834f87ce4f4cc0ac665c675d491c4d41d26c
+  data.tar.gz: b1f1aec85cf6371a0849cd751fa66c2574e7000ab7ce239b732a83a4ab98e772
+SHA512:
+  metadata.gz: 0326e398a563a39696b46ed2c2bf0747083a73b191be8cc29ac0d691a5f7fb496954eaee316d18575dc49dc9ae38fa37e5ebf92d4f9b11c980021989eceba51c
+  data.tar.gz: 0f8ba682ebce7530c59202637ca5e2c8c103473b489c947eb86173d8ef6fb5ae0e817ffa08830a0aa9d609409aa1aaa54003793f9e8348007f45b7631e000fff

data/README.md

@@ -0,0 +1,144 @@
+# rubyterm
+
+A terminal emulator written **entirely in Ruby** — including a pure-Ruby
+X11 client to talk to the X server. There is no C extension and no libvte;
+the escape-sequence interpreter, the screen buffer, the rendering and the
+X11 protocol handling are all Ruby.
+
+It is still rough and opinionated, but it now runs as an installable gem
+with a `rubyterm` executable, renders with a damage-driven pipeline
+(scrollback, text selection/copy, truecolor and UTF-8 all work), and is
+split into a reusable terminal *engine* that can be driven without X11 at
+all.
+
+> **You probably don't want to depend on this yet.** Escape-code coverage
+> is partial (VT100/VT102 plus a useful chunk of xterm), font handling is
+> basic, and the keymap is limited. Full-screen apps mostly work; some will
+> still misbehave. I have specific ideas about direction, so if you'd like
+> to contribute, **talk to me first** (vidar@hokstad.com) or fork — I won't
+> promise to merge changes we haven't discussed.
+
+## Architecture
+
+The code is deliberately small and split along clean seams so the pieces
+are independently usable and testable:
+
+- **Engine** — the escape interpreter (`Term`), the damage tracker
+  (`TrackChanges`), the columnar screen buffer (`TermBuffer`) and the
+  escape/UTF-8 parsers. No pixels, no X11; drivable headlessly.
+- **Backends** — anything implementing the small drawing interface:
+  - `Window` — the pure-Ruby X11 backend (the real terminal);
+  - `AnsiBackend` — re-emits to an ANSI/escape stream (run a terminal
+    inside another terminal; see `examples/terminal_in_terminal.rb`);
+  - `BitmapWindow` — rasterises glyphs with skrift into an in-memory RGB
+    buffer (headless rendering / visual testing, PNG output).
+- **Application** — `RubyTerm` (in `lib/rubyterm/app.rb`), which owns the
+  X window, the pty controller and the input/blink/flush threads and wires
+  the engine to the X11 backend. `bin/rubyterm` runs it.
+
+Rendering is **damage-driven**: writing a cell only mutates the buffer and
+bumps a per-cell generation; a flush walks the damage and redraws just the
+changed cells. A flood of output (an accidental `cat` of a large file) is
+*jump-scrolled* — interpreted across many chunks and painted once.
+
+For the full picture and the rationale behind the layering, see:
+
+- [`docs/architecture-review.md`](docs/architecture-review.md) — the
+  architecture critique, the phased refactoring plan, and the Ruby
+  performance notes (with measured results).
+- [`docs/seams.md`](docs/seams.md) — the layer seams: the screen-operation
+  API and the backend drawing protocol.
+
+## Installation
+
+Dependencies are managed with Bundler; `skrift` and `skrift-x11` are
+developed alongside this project and are referenced as local path gems in
+the `Gemfile`.
+
+```bash
+bundle install
+```
+
+## Running
+
+```bash
+bundle exec rubyterm                 # start a terminal running your $SHELL
+bundle exec rubyterm bash -lc htop   # ...or run a specific command
+```
+
+With some luck you'll get a terminal window. Once the gem (and its
+dependencies) are installed system-wide, the `rubyterm` executable can be
+run directly.
+
+## Configuration
+
+Configuration is read from `~/.config/rterm/config.toml` (TOML). See
+[`example-config.toml`](example-config.toml) for a complete example. If the
+file is absent, defaults are used.
+
+- **`shell`** — path to the shell to launch. Defaults to `$SHELL`, then
+  `/bin/sh`. Example: `shell = "/bin/bash"`.
+- **`fonts`** — fonts to use, in priority order; later fonts cover glyphs
+  missing from earlier ones. Each entry may be a direct path
+  (`"~/fonts/MyFont.ttf"`), a file in `~/.local/share/fonts/`, or a name
+  resolved via `fc-match` (`"monospace"`, `"monospace:weight=bold"`).
+- **`fontsize`** — font size in points (e.g. `fontsize = 24`).
+- **`deccolm`** — how the 80/132-column DECCOLM switch is realised:
+  `"font"` (rescale the glyph cell, the default) or `"window"` (ask the WM
+  to resize).
+
+```toml
+shell = "/bin/zsh"
+fonts = [
+  "FiraCode-Regular.ttf",   # programming font
+  "unifont-15.0.06.ttf",    # Unicode fallback
+  "monospace"               # system fallback
+]
+fontsize = 24
+```
+
+## Development
+
+```bash
+rake test          # the minitest unit/integration suite
+rake run           # run the terminal (alias for bin/rubyterm)
+```
+
+There is a deterministic **test harness** for terminal correctness: it
+runs cases through the engine and an oracle (tmux), diffs the resulting
+screen state, and gates regressions with a ratchet. It can also record and
+replay real applications, and run an instrumented live terminal with a
+debug socket.
+
+```bash
+ruby harness/cli.rb run   --case cases/synthetic/dch.bin --oracle tmux
+ruby harness/cli.rb sweep --cases cases --oracle tmux --ratchet ratchet.json
+```
+
+- [`docs/harness.md`](docs/harness.md) — the harness guide, and
+  [`docs/harness-quickstart.md`](docs/harness-quickstart.md) — from a glitch
+  to a minimal repro.
+- [`docs/state-schema.md`](docs/state-schema.md) — the JSON terminal-state
+  dump schema.
+- [`docs/debugging-live-render.md`](docs/debugging-live-render.md) —
+  debugging live-terminal display corruption.
+- [`docs/bench-baseline.md`](docs/bench-baseline.md) — the performance
+  baseline used to gate the optimisation work.
+
+## Direction
+
+Where I want to take this:
+
+- Keep the engine fully decoupled from the pty and X11 so Ruby applications
+  can instantiate a "terminal" with an IO object as its interface — the
+  first consumer being my own text editor — and package the engine as a
+  gem. (The split exists; the gem and the editor migration are in progress.)
+- Make the terminal complete enough to run most Unix command-line tools: a
+  reasonably complete, Unicode-aware xterm/VT100.
+- Keep the code **small but understandable**. Terseness is valued only
+  while it preserves readability.
+
+## Resources
+
+- xterm control sequences: <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
+- XFree86 control sequences: <https://www.xfree86.org/current/ctlseqs.html>

data/bin/record

@@ -0,0 +1,3 @@
+#!/bin/env ruby
+
+exec(%{ruby harness/cli.rb record --out /tmp/#{ARGV[0].gsub("/","_")}.rec -- #{ARGV.join(" ")}})

data/bin/rubyterm

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Make the gem's own lib/ importable when run straight from a checkout
+# (when installed as a gem, rubygems already has it on the load path).
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "rubyterm"
+
+RubyTerm.new(ARGV).run(ARGV)

data/example-config.toml

@@ -0,0 +1,61 @@
+
+
+# You can give a single font, or an array.
+# If the name is a valid path, we try to open
+# it directly, after expansion (so ~ works).
+#
+# We also check ~/.local/share/fonts/[string]
+#
+# If we don't find a file that way, we execute:
+#
+#     fc-match --format='%{file}\n' $string
+#
+# If you want to force a fc-match (e.g. to
+# allow config file substitutions to take
+# precedence) then leave out the extension
+# E.g. if you have "Space Mono.ttf" in your
+# .local/share/fonts directory, and put "Space Mono"
+# below, we will run fc-match (and likely, but
+# not necessarily, find the same font).
+#
+# You can also include fc-match options.
+# This *includes* using '-s' or other options
+# that returns a list.
+#
+# *BE CAREFUL*, as if a glyph is unavailable
+# in a given font, we will look through each
+# font in turn until we either find it or
+# reach the end of the list, and this can get
+# slow
+#
+#
+fonts = [
+  #"Topaznew.ttf",
+  #"WP BoxDrawing.ttf",
+  # FIXME: Figure out why substitution fails for these:
+  "FiraCode-Regular.ttf", # Can't handle MD headings
+# "NovaMono for Powerline.ttf", # Seriously broken
+#  "ProFont For Powerline.ttf", # Can't handle '#' comments
+  "unifont-15.0.06.ttf", # Unifont has "almost everything" but scales badly
+
+  # FIXME: The fc-match seems to fail
+  "monospace",
+]
+
+fontsize = 32
+
+shell="/home/vidarh/bin/rsh"
+
+# DECCOLM (the 80/132-column switch, ESC [ ? 3 h / l) is supported. Choose
+# how the column change is realised:
+#
+#   "font"   - (default) rescale the glyph cell so the new column count
+#              fits the current window; the window keeps its size and the
+#              row count is preserved. Reliable everywhere.
+#   "window" - ask the window manager to resize the window to fit the new
+#              column count at the current font. Most "native", but depends
+#              on the WM honouring the resize request.
+#   "off"    - ignore the column switch entirely (apps that send ESC[?3h/l
+#              cannot resize/rescale your terminal).
+#
+#deccolm = "font"

data/lib/ansibackend.rb

@@ -0,0 +1,155 @@
+require_relative 'termbuffer' # flag constants (BOLD, UNDERLINE, ...)
+
+# A rendering backend that emits ANSI escape sequences instead of painting
+# pixels: a drop-in for WindowAdapter (it satisfies the same draw / scroll /
+# clear / clear_line / insert_lines / delete_lines interface the run-batcher
+# in TrackChanges drives, plus the cell-metric and scrollback hooks Term
+# queries). It turns the terminal's damage stream - changed runs of cells,
+# plus scroll/clear ops - into the minimal escape sequences that reproduce
+# the screen on a real terminal. This is the "render economically to a
+# terminal, like Emacs" backend, and the basis for letting a TUI app render
+# to a terminal OR an X11 window from the same code.
+#
+# Colours arrive already resolved to 24-bit RGB (Term#fg/#bg), so they are
+# emitted as truecolor SGR. The run-batcher only hands us cells that
+# changed, so only changed runs are emitted (CUP + minimal SGR + text). The
+# cursor overlay (a cell drawn with the CURSOR background) is recognised and
+# turned into a real cursor position rather than a coloured cell.
+class AnsiBackend
+  CURSOR_BG = 0xff00ff # must match Term::CURSOR
+
+  # flag bit -> SGR set-code
+  SGR_FLAGS = {
+    BOLD => 1, FAINT => 2, ITALICS => 3, UNDERLINE => 4, BLINK => 5,
+    RAPID_BLINK => 6, INVERSE => 7, INVISIBLE => 8, CROSSED_OUT => 9,
+    DBL_UNDERLINE => 21, OVERLINE => 53,
+  }.freeze
+
+  # origin_row/origin_col place the rendered screen at an offset on the
+  # real terminal, so the same Term core can be drawn into a sub-window
+  # (a terminal-in-a-terminal / multiplexer pane). With a non-zero origin,
+  # full-screen erase becomes a per-row erase of just the sub-window.
+  def initialize(cols, rows, origin_row: 0, origin_col: 0)
+    @cols, @rows = cols, rows
+    @origin_row, @origin_col = origin_row, origin_col
+    @out = +"".b
+    reset_state
+  end
+
+  def reset_state
+    @cx = @cy = nil          # tracked cursor (nil = unknown -> force CUP)
+    @fg = @bg = @flags = nil # tracked SGR (nil = unknown)
+    @region = nil
+    @cursor_pos = nil
+  end
+
+  # # cell metrics: a text cell is one character
+  def char_w = 1
+  def char_h = 1
+  def scrollback_mode = false
+  def scrollback_anchor; end
+  def set_columns(_); end
+
+  # The escape sequence produced so far, with a trailing reposition to the
+  # cursor overlay if one was seen. Non-destructive.
+  def output
+    @cursor_pos ? @out + cup(@cursor_pos[1], @cursor_pos[0]) : @out.dup
+  end
+
+  # Take the output and reset the buffer for the next frame. The trailing
+  # cursor reposition moved the real terminal cursor, so forget the tracked
+  # position (the next frame's first draw must re-issue a CUP). SGR/region
+  # state persists - the real terminal keeps it between frames.
+  def take
+    s = output
+    @out = +"".b
+    @cursor_pos = nil
+    @cx = @cy = nil
+    s
+  end
+
+  def draw(x, y, str, fg, bg, flags, _lineattrs = nil)
+    if bg == CURSOR_BG
+      @cursor_pos = [x, y] # cursor overlay - the real cursor shows position
+      return
+    end
+    move(y, x)
+    @out << sgr(fg, bg, flags)
+    @out << str
+    @cx = x + str.length
+    @cy = y
+  end
+
+  def clear
+    reset_state
+    if @origin_row.zero? && @origin_col.zero?
+      @out << "\e[H\e[2J"
+      @cx = @cy = 0 # \e[H homes the cursor
+    else
+      # Erase only this sub-window's rows, not the whole real screen. This
+      # leaves the cursor at the last erased row, so @cx/@cy stay nil
+      # (reset_state) and the next draw re-issues a CUP.
+      @rows.times { |y| @out << cup(y, 0) << "\e[2K" }
+    end
+  end
+
+  def clear_line(y, from_x, to_x = nil)
+    if to_x
+      # Erase to start (from_x is 0 in practice): emit EL-1 rather than
+      # synthesising spaces, so the replay's clear_to_start reproduces the
+      # exact same cells (raw default attributes, not a resolved \e[0m).
+      move(y, to_x)
+      @out << "\e[1K"
+    else
+      move(y, from_x)
+      @out << "\e[0K" # erase to end of line (buffer truncates the row)
+    end
+  end
+
+  def scroll_up(scroll_start, scroll_end)
+    set_region(scroll_start, scroll_end)
+    @out << "\e[S" # scroll the region up one line
+  end
+
+  def insert_lines(y, num, maxy)
+    set_region(@region ? @region[0] : 0, maxy)
+    move(y, 0)
+    @out << "\e[#{num}L"
+  end
+
+  def delete_lines(y, num, maxy)
+    set_region(@region ? @region[0] : 0, maxy)
+    move(y, 0)
+    @out << "\e[#{num}M"
+  end
+
+  private
+
+  def cup(row, col) = "\e[#{row + 1 + @origin_row};#{col + 1 + @origin_col}H"
+
+  def move(y, x)
+    return if @cx == x && @cy == y
+    @out << cup(y, x)
+    @cx, @cy = x, y
+  end
+
+  def set_region(top, bot)
+    return if @region == [top, bot]
+    @out << "\e[#{top + 1 + @origin_row};#{bot + 1 + @origin_row}r"
+    @region = [top, bot]
+    @cx = @cy = nil # DECSTBM homes the cursor
+  end
+
+  # Reset + set everything explicitly on any change. Correct and compact for
+  # uniform runs (one SGR per changed run); skipped entirely when the run's
+  # attributes match the current terminal state.
+  def sgr(fg, bg, flags)
+    return "" if fg == @fg && bg == @bg && flags == @flags
+    @fg, @bg, @flags = fg, bg, flags
+    codes = [0]
+    SGR_FLAGS.each { |bit, code| codes << code if flags & bit != 0 }
+    codes.concat([38, 2, (fg >> 16) & 0xff, (fg >> 8) & 0xff, fg & 0xff])
+    codes.concat([48, 2, (bg >> 16) & 0xff, (bg >> 8) & 0xff, bg & 0xff])
+    "\e[#{codes.join(';')}m"
+  end
+end

data/lib/bitmapwindow.rb

@@ -0,0 +1,176 @@
+require 'skrift'
+require 'zlib'
+
+# A third implementation of the drawing interface WindowAdapter targets
+# (alongside the X11 Window and the harness's VirtualWindow): it rasterises
+# real glyphs with skrift and composites them into an in-memory RGB buffer.
+# Wrapped by WindowAdapter it is a full "bitmap backend" - the same Term
+# core, rendered to a pixel buffer with no X server - useful for headless
+# visual testing and for embedding the terminal anywhere a bitmap can go.
+#
+#   win = BitmapWindow.new(80, 24)
+#   adapter = WindowAdapter.new(win, host)   # host: term_width/blink_state...
+#   ... feed the terminal ...
+#   win.save_png("screen.png")
+class BitmapWindow
+  attr_reader :width, :height, :pixels
+
+  DEFAULT_FONT = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"
+
+  def initialize(cols, rows, font: DEFAULT_FONT, size: 16,
+                 fg: 0xcccccc, bg: 0x000000)
+    @font = Font.load(font)
+    @sft = SFT.new(@font)
+    @sft.x_scale = size
+    @sft.y_scale = size
+    lm = @sft.lmetrics
+    @char_h   = (lm.ascender - lm.descender + lm.line_gap).ceil
+    @baseline = lm.ascender.round
+    @char_w   = @sft.gmetrics(@sft.lookup("M".ord)).advance_width.round
+    @cols, @rows = cols, rows
+    @fg, @bg = fg, bg
+    @glyphs = {}
+    resize(cols * @char_w, rows * @char_h)
+  end
+
+  def char_w = @char_w
+  def char_h = @char_h
+
+  def resize(w, h)
+    @width, @height = w, h
+    @pixels = Array.new(@width * @height, @bg)
+  end
+
+  # # Window interface used by WindowAdapter / the host loop
+
+  # Live-loop hooks: a bitmap has no separate front buffer / event channel.
+  def dirty!        = nil
+  def flush         = nil
+  def copy_buffer   = nil
+  def map_window    = nil
+  def set_buffer(_) = nil
+  def scrollback_mode  = false
+  def scrollback_count = 0
+
+  def fillrect(x, y, w, h, col)
+    x0 = x.clamp(0, @width); x1 = (x + w).clamp(0, @width)
+    y0 = y.clamp(0, @height); y1 = (y + h).clamp(0, @height)
+    (y0...y1).each do |py|
+      base = py * @width
+      (x0...x1).each { |px| @pixels[base + px] = col }
+    end
+  end
+
+  def clear(x, y, w, h)  = fillrect(x, y, w, h, @bg)
+  def draw_line(x, y, w, col) = fillrect(x, y, w, 1, col)
+
+  # x,y are pixel coordinates (WindowAdapter has already multiplied by the
+  # cell size). lineattrs (double width/height) is rendered as normal width
+  # for now - it does not affect correctness of the text, only its scale.
+  def draw(x, y, str, fg, bg, _lineattrs = nil)
+    fillrect(x, y, str.length * @char_w, @char_h, bg)
+    str.each_char.with_index do |ch, i|
+      next if ch == " "
+      blit_glyph(ch.ord, x + i * @char_w, y, fg)
+    end
+  end
+
+  # Mirror Window#scroll_up / #scroll_down: move a block of pixel rows and
+  # clear the vacated strip (geometry comes from WindowAdapter).
+  def scroll_up(srcy, w, h, step)
+    move_rows(srcy, srcy - step, h)
+    clear(0, srcy + h - step, @width, step + 1)
+  end
+
+  def scroll_down(srcy, w, h, step)
+    move_rows(srcy, srcy + step, h)
+    clear(0, srcy, @width, step)
+  end
+
+  # # Output
+
+  def save_png(path)
+    raw = +"".b
+    @height.times do |y|
+      raw << "\0"               # filter: none
+      base = y * @width
+      @width.times do |x|
+        p = @pixels[base + x]
+        raw << ((p >> 16) & 0xff).chr << ((p >> 8) & 0xff).chr << (p & 0xff).chr
+      end
+    end
+    png = +"\x89PNG\r\n\x1a\n".b
+    png << png_chunk("IHDR", [@width, @height, 8, 2, 0, 0, 0].pack("NNC5"))
+    png << png_chunk("IDAT", Zlib::Deflate.deflate(raw))
+    png << png_chunk("IEND", "")
+    File.binwrite(path, png)
+    path
+  end
+
+  private
+
+  def png_chunk(type, data)
+    body = type.b + data.b
+    [data.bytesize].pack("N") + body + [Zlib.crc32(body)].pack("N")
+  end
+
+  # Overlap-safe block copy of +h+ pixel rows from srcy to dsty.
+  def move_rows(srcy, dsty, h)
+    rows = (0...h).to_a
+    rows.reverse! if dsty > srcy   # copy bottom-up when shifting down
+    rows.each do |i|
+      sy = srcy + i; dy = dsty + i
+      next if sy < 0 || sy >= @height || dy < 0 || dy >= @height
+      @pixels[dy * @width, @width] = @pixels[sy * @width, @width]
+    end
+  end
+
+  def blit_glyph(codepoint, cx, cy, fg)
+    alpha, gw, gh, lsb, yoff = glyph(codepoint)
+    return unless alpha
+    gx = cx + lsb
+    gy = cy + @baseline - yoff
+    gh.times do |row|
+      py = gy + row
+      next if py < 0 || py >= @height
+      base = py * @width
+      grow = row * gw
+      gw.times do |col|
+        a = alpha[grow + col]
+        next if a.nil? || a.zero?
+        px = gx + col
+        next if px < 0 || px >= @width
+        idx = base + px
+        @pixels[idx] = blend(@pixels[idx], fg, a)
+      end
+    end
+  end
+
+  # fg over dst, coverage a (0-255).
+  def blend(dst, fg, a)
+    ia = 255 - a
+    r = ((fg >> 16 & 0xff) * a + (dst >> 16 & 0xff) * ia) / 255
+    g = ((fg >> 8 & 0xff) * a + (dst >> 8 & 0xff) * ia) / 255
+    b = ((fg & 0xff) * a + (dst & 0xff) * ia) / 255
+    (r << 16) | (g << 8) | b
+  end
+
+  # [alpha_bytes, width, height, left_bearing, y_offset] for a codepoint,
+  # cached; or [nil] if it has no outline (e.g. space).
+  def glyph(codepoint)
+    @glyphs[codepoint] ||= begin
+      gid = @sft.lookup(codepoint)
+      m = gid && @sft.gmetrics(gid)
+      if m.nil? || m.min_width.nil? || m.min_height.nil?
+        [nil]
+      else
+        img = Image.new((m.min_width + 3) & ~3, m.min_height)
+        if @sft.render(gid, img) && img.pixels
+          [img.pixels, img.width, img.height, m.left_side_bearing.round, m.y_offset]
+        else
+          [nil]
+        end
+      end
+    end
+  end
+end

data/lib/charsets.rb

@@ -0,0 +1,52 @@
+
+# FIXME:
+# This is the start of defining character sets as per
+# the vt102/vt200 specs
+#
+# They should be wrapped in modules and split out with other relevant
+# data in a separate gem.
+#
+# These objects are expected to act as a Hash, and provide a value
+# for anything passed in, translating only those keys that are different
+#
+
+  DefaultCharset  = Hash.new{|_,k| k }.freeze # Identity
+
+  # Line drawings.
+  # http://fileformats.archiveteam.org/wiki/DEC_Special_Graphics_Character_Set
+  GraphicsCharset = {
+    0x5f => "\u00A0",
+    0x60 => "\u25c6",
+    0x61 => "\u2592",
+    0x62 => "\u2409",
+    0x63 => "\u240C",
+    0x64 => "\u240d",
+    0x65 => "\u240A",
+    0x66 => "\u00B0",
+    0x67 => "\u00B1",
+    0x68 => "\u2424",
+    0x69 => "\u240B",
+    0x6A => "\u2518",
+    0x6B => "\u2510",
+    0x6C => "\u250C",
+    0x6D => "\u2514",
+    0x6E => "\u253C",
+    0x6f => "\u23BA",
+    0x70 => "\u23BB",
+    0x71 => "\u2500",
+    0x72 => "\u23BC",
+    0x73 => "\u23BD",
+    0x74 => "\u251c",
+    0x75 => "\u2524",
+    0x76 => "\u2534",
+    0x77 => "\u252c",
+    0x78 => "\u2502",
+    0x79 => "\u2264",
+    0x7A => "\u2265",
+    0x7B => "\u03C0",
+    0x7C => "\u2260",
+    0x7D => "\u00A3",
+    0x7E => "\u00b7",
+  }
+  GraphicsCharset.default_proc = ->(_,k) {k}
+  GraphicsCharset.freeze

data/lib/controller.rb

@@ -0,0 +1,80 @@
+#
+#  A spawned command that is controlling the terminal window,
+#  and on request receives events (mouse buttons etc.
+#
+class Controller
+  def initialize(term, config = {})
+    @term = term
+    @config = config
+    @shell = determine_shell
+  end
+
+  def determine_shell
+    # Try config file first, then ENV["SHELL"], then fallback to /bin/sh
+    @config[:shell] || ENV["SHELL"] || "/bin/sh"
+  end
+
+  def run(*args)
+    cmd = args.empty? ? @shell : [@shell, '-c', args.join(' ')]
+    @master, @wr, @pid = *PTY.spawn(*cmd)
+
+    Thread.new do
+      loop do
+        begin
+          @term.write(self.read)
+          Thread.pass
+        rescue Errno::EIO
+          # The child closed the pty (it exited): EIO on read is normal
+          # here. Exit with the child's status.
+          # FIXME: Not sure if this really belongs *here*?
+          exit(Process.wait(@pid))
+        end
+      end
+    end
+  end
+
+  def read
+    @master.read_nonblock(128)
+  rescue IO::EAGAINWaitReadable
+    IO.select([@master], [], [], nil)
+    retry
+  end
+
+  # Device Attributes replies. Each query has a distinct reply *type*;
+  # sending the wrong type (e.g. the DA3 DCS below in answer to a DA1/DA2
+  # query) makes hosts like tmux fail to consume it, so it leaks into the
+  # pane as visible text.
+  #
+  # DA1 (CSI c): identify as a VT100 with Advanced Video Option.
+  def device_attr_primary   = @wr.write("\e[?1;2c")
+  # DA2 (CSI > c): terminal id 0 (VT100), firmware version, cartridge 0.
+  def device_attr_secondary = @wr.write("\e[>0;10;1c")
+  # DA3 (CSI = c): DECRPTUI unit id, a DCS string (! | DDDDDDDD ST).
+  def device_attr_tertiary  = @wr.write("\x1bP!|00000000\x1b\\")
+
+  def report_size(w, h) = (@master.winsize = [h, w])
+  def report_position(x, y) = @wr.write("\e[#{y + 1};#{x + 1}R")
+
+  # These are semantically different, though practically similar
+  # *currently*. These are separate so they can be treated differently
+  # (bracketed etc.) in the future
+  def paste(data)    = @wr.write(data)
+  def keypress(data) = @wr.write(data)
+
+  def mouse_report(mode, event, x, y, release)
+    case mode
+    when :digits then mouse_digits(event, x, y, release)
+    else # Currently only x10
+      mouse_x10(event, x, y)
+    end
+  end
+
+  def mouse_digits(event, x, y, release)
+    @wr.write("\e[<#{event};#{x + 1};#{y + 1}#{release ? "m" : "M"}")
+  end
+
+  def mouse_x10(event, x, y)
+    raise "FIXME; untested and likely broken; Test w/htop"
+    @wr.write("\e[M#{event.to_i.chr}#{x.chr}#{y.chr}")
+  end
+end