termvas 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5863ee4752675b2b9b5c77b5e4bf0d0a4864911c7976ce661d21e468dd92e0b6
+  data.tar.gz: 3b850fdefa94a1e8707e320717f72bd9a2822c1142fc098ba0c64e2c0d520d88
+SHA512:
+  metadata.gz: 7aed972961ce1dd18f54e9973ec4952becc545c35178bf87bd9f838694e018e49921bbf01cc6cd7d60b552e5890af0b77458269471dd758ac2d4da3192719ea9
+  data.tar.gz: 285deddc562970d9e952fb35fd76ebc4a2d4b8ef7926e2d7dfd0f69e339f6c14edf634e001b2023af9e5604389f7bf5252cb37f0df93b4e0dd07c734739169fe

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-23
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# Termvas
+
+[![Gem version](https://badge.fury.io/rb/termvas.svg)](https://rubygems.org/gems/termvas)
+[![Downloads](https://img.shields.io/gem/dt/termvas?label=downloads)](https://rubygems.org/gems/termvas)
+[![CI](https://github.com/rbgfx/termvas/actions/workflows/ci.yml/badge.svg)](https://github.com/rbgfx/termvas/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-750014.svg)](LICENSE.txt)
+
+> A terminal display backend for Ruby graphics.
+
+Termvas presents RGBA frames in terminals through half blocks, Kitty, iTerm2,
+or Sixel output. It also parses keyboard and mouse input for interactive
+applications.
+
+**[Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Terminal notes](#terminal-notes) · [Development](#development)**
+
+## Features
+
+- Automatic protocol detection with a manual override.
+- Half-block output that works in ordinary ANSI terminals.
+- Kitty, iTerm2, and Sixel image protocols.
+- Image viewing and frame-sequence playback commands.
+- Split-safe CSI, keyboard, wheel, and SGR mouse input parsing.
+- Nearest-neighbor fitting for frames larger than the terminal.
+- Idempotent alternate-screen and cursor restoration.
+
+## Installation
+
+Add Termvas to your Gemfile:
+
+~~~ruby
+gem "termvas"
+~~~
+
+Then run:
+
+~~~sh
+bundle install
+~~~
+
+Or install the released gem:
+
+~~~sh
+gem install termvas
+~~~
+
+## Quick start
+
+Inspect the current terminal and display an image:
+
+~~~sh
+termvas doctor
+termvas view image.png
+termvas play frames/*.png --fps 10
+~~~
+
+Use the backend from Ruby:
+
+~~~ruby
+require "termvas"
+
+backend = Termvas::Backend.new(320, 180, protocol: :blocks)
+backend.set_pixels(rgba_bytes, 320, 180)
+backend.close
+~~~
+
+The backend expects top-down RGBA8 bytes. Set
+<code>TERMVAS_PROTOCOL</code> to force a protocol.
+
+## Terminal notes
+
+<code>fit: :contain</code> is the default and reduces oversized frames to the
+terminal cell area. Use <code>fit: :none</code> to keep the source size.
+
+Inside tmux, Kitty and Sixel output uses DCS passthrough and requires
+<code>allow-passthrough on</code> in tmux.
+
+## Development
+
+~~~sh
+bundle install
+bundle exec rake verify
+~~~
+
+See [docs/keys.md](docs/keys.md) for the input event mapping.
+
+## License
+
+[MIT](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.ruby_opts = %w[-I../rbgl/lib -I../larb/lib -I../tessel/lib]
+end
+
+task default: :spec
+task verify: :spec

data/docs/keys.md

@@ -0,0 +1,10 @@
+# Terminal input
+
+`Termvas::InputParser` emits `key_press` events. Printable bytes include a
+`char`; Ctrl-C emits `key: :close`. CSI and SS3 arrows, Home/End, Insert,
+Delete, Page Up/Down, F1-F4, and SGR mouse events are supported.
+
+CSI modifier parameters and SGR mouse modifier bits become `:shift`, `:alt`,
+and `:control`. SGR wheel events become `scroll` events with `dx` and `dy`;
+the parser reports one logical wheel step per terminal event. Terminals do not
+report key release events, so Termvas emits presses only.

data/exe/termvas

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "termvas"
+
+command = ARGV.shift
+if command == "doctor"
+  puts "protocol: #{Termvas::Detector.protocol}"
+  puts "terminal: #{ENV['TERM'] || 'unknown'}"
+  puts "size: #{IO.console&.winsize&.join('x') || 'unknown'}"
+elsif %w[view play].include?(command)
+  require "tessel"
+  fps = 10.0
+  protocol = :auto
+  OptionParser.new do |options|
+    options.on("--fps N", Float) { |value| fps = value }
+    options.on("--protocol NAME") { |value| protocol = value.to_sym }
+  end.parse!(ARGV)
+  raise ArgumentError, "fps must be positive" unless fps.positive?
+  raise ArgumentError, "at least one image is required" if ARGV.empty?
+  files = ARGV.flat_map { |path| File.directory?(path) ? Dir[File.join(path, "*.png")].sort : path }
+  files = [files.first] if command == "view"
+  raise ArgumentError, "at least one image is required" if files.empty?
+  backend = nil
+  files.each do |path|
+    image = Tessel.read(path)
+    rows, columns = IO.console&.winsize || [24, 80]
+    width, height = Termvas::Scaler.contain(image.width, image.height, columns, rows)
+    bytes, = Termvas::Scaler.nearest(image.bytes, image.width, image.height, width, height)
+    backend ||= Termvas::Backend.new(width, height, protocol: protocol, alt_screen: command == "play")
+    backend.set_pixels(bytes, width, height)
+    sleep(1.0 / fps) if command == "play"
+  end
+else
+  warn "usage: termvas doctor | view IMAGE [--protocol NAME] | play IMAGE... [--fps N]"
+  exit 1
+end
+backend&.close if defined?(backend)

data/lib/termvas/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Termvas
+  VERSION = "0.1.0"
+end

data/lib/termvas.rb

@@ -0,0 +1,526 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "zlib"
+require "rbgl"
+
+require_relative "termvas/version"
+
+module Termvas
+  class Error < StandardError; end
+
+  module Scaler
+    module_function
+
+    def contain(width, height, columns, rows)
+      raise ArgumentError, "dimensions must be positive" unless [width, height, columns, rows].all?(&:positive?)
+      scale = [1.0, columns.to_f / width, (rows * 2).to_f / height].min
+      [[(width * scale).floor, 1].max, [[((height * scale).floor / 2) * 2, 2].max, rows * 2].min]
+    end
+
+    def nearest(bytes, width, height, target_width, target_height)
+      width, height, target_width, target_height = [width, height, target_width, target_height].map(&:to_i)
+      raise ArgumentError, "dimensions must be positive" unless [width, height, target_width, target_height].all?(&:positive?)
+      bytes = String.try_convert(bytes)
+      raise ArgumentError, "pixel buffer must be a String" unless bytes
+      expected_size = width * height * 4
+      raise ArgumentError, "pixel buffer size mismatch" unless bytes.bytesize == expected_size
+      return [bytes, width, height] if width == target_width && height == target_height
+      output = "".b
+      target_height.times do |y|
+        source_y = y * height / target_height
+        target_width.times do |x|
+          source_x = x * width / target_width
+          output << bytes.byteslice((source_y * width + source_x) * 4, 4)
+        end
+      end
+      [output, target_width, target_height]
+    end
+  end
+
+  module Encoders
+    module Blocks
+      module_function
+
+      def encode(bytes, width, height, previous: nil)
+        cells = "\e[H".dup
+        (0...height).step(2) do |y|
+          current = nil
+          width.times do |x|
+            top = bytes.byteslice((y * width + x) * 4, 4) || "\0\0\0\0".b
+            bottom = bytes.byteslice(((y + 1) * width + x) * 4, 4) || "\0\0\0\0".b
+            old_top = previous&.byteslice((y * width + x) * 4, 4)
+            old_bottom = previous&.byteslice(((y + 1) * width + x) * 4, 4)
+            if previous && old_top == top && old_bottom == bottom
+              cells << "\e[C"
+              next
+            end
+            if current != [top, bottom]
+              cells << "\e[38;2;#{top.getbyte(0)};#{top.getbyte(1)};#{top.getbyte(2)}m"
+              cells << "\e[48;2;#{bottom.getbyte(0)};#{bottom.getbyte(1)};#{bottom.getbyte(2)}m"
+              current = [top, bottom]
+            end
+            cells << "▀"
+          end
+          cells << "\e[0m\r\n"
+        end
+        cells
+      end
+    end
+
+    module Kitty
+      module_function
+
+      def encode(bytes, width, height, id: 1, compress: true)
+        payload = compress ? Zlib::Deflate.deflate(bytes) : bytes
+        encoded = [payload].pack("m0")
+        chunks = encoded.scan(/.{1,4096}/m)
+        chunks.each_with_index.map do |chunk, index|
+          more = index == chunks.length - 1 ? 0 : 1
+          control = "a=T,f=32,s=#{width},v=#{height},i=#{id},q=2,m=#{more}"
+          control << ",o=z" if compress
+          "\e_G#{control};#{chunk}\e\\"
+        end.join
+      end
+    end
+
+    module ITerm2
+      module_function
+
+      def encode(png_bytes, width:, height:)
+        "\e[H\e]1337;File=inline=1;width=#{width}px;height=#{height}px;preserveAspectRatio=1:#{[png_bytes].pack("m0")}\a"
+      end
+    end
+
+    module Sixel
+      module_function
+
+      def encode(bytes, width, height, palette: nil, quantize: :fixed)
+        quantize = quantize.to_sym
+        raise ArgumentError, "unsupported Sixel quantizer: #{quantize}" unless %i[fixed median_cut].include?(quantize)
+        if quantize == :median_cut
+          raise ArgumentError, "palette cannot be combined with median cut" if palette
+          palette, quantized = Quantizer.median_cut(bytes, colors: 256)
+        end
+        fixed_palette = palette.nil?
+        palette ||= default_palette
+        indices = if quantized
+          quantized.bytes
+        else
+          bytes.bytes.each_slice(4).map do |r, g, b, _a|
+          if fixed_palette
+            red = (r * 5.0 / 255).round
+            green = (g * 5.0 / 255).round
+            blue = (b * 5.0 / 255).round
+            cube = red * 36 + green * 6 + blue
+            gray = ((r + g + b) / 3.0 * 39 / 255).round
+            cube_color = palette[cube]
+            gray_color = palette[216 + gray]
+            cube_distance = [r, g, b].zip(cube_color).sum { |a, c| (a - c)**2 }
+            gray_distance = [r, g, b].zip(gray_color).sum { |a, c| (a - c)**2 }
+            cube_distance <= gray_distance ? cube : 216 + gray
+          else
+            palette.each_index.min_by { |index| [r, g, b].zip(palette[index]).sum { |a, c| (a - c)**2 } }
+          end
+          end
+        end.pack("C*")
+        output = +"\ePq"
+        palette.each_with_index { |(r, g, b), index| output << "##{index};2;#{r * 100 / 255};#{g * 100 / 255};#{b * 100 / 255}" }
+        (0...height).step(6) do |band|
+          palette.each_index do |index|
+            output << "##{index}"
+            x = 0
+            while x < width
+              run = 0
+              while x + run < width && sixel_column(indices, width, x + run, band, index) == sixel_column(indices, width, x, band, index)
+                run += 1
+              end
+              column = sixel_column(indices, width, x, band, index)
+              if run > 3
+                output << "!#{run}#{(63 + column).chr}"
+              else
+                output << (63 + column).chr * run
+              end
+              x += run
+            end
+            output << "$"
+          end
+          output << "-" if band + 6 < height
+        end
+        output << "\e\\"
+      end
+
+      def sixel_column(indices, width, x, y, index)
+        value = 0
+        6.times do |offset|
+          next unless indices.getbyte((y + offset) * width + x) == index
+          value |= 1 << offset
+        end
+        value
+      end
+      private_class_method :sixel_column
+
+      def default_palette
+        6.times.flat_map { |r| 6.times.flat_map { |g| 6.times.map { |b| [r * 51, g * 51, b * 51] } } } + Array.new(40) { |index| value = index * 255 / 39; [value, value, value] }
+      end
+      private_class_method :default_palette
+    end
+  end
+
+  module Quantizer
+    module_function
+
+    def median_cut(bytes, colors: 256)
+      colors = Integer(colors)
+      raise ArgumentError, "colors must be positive" unless colors.positive?
+      pixels = bytes.bytes.each_slice(4).map { |red, green, blue, _alpha| [red, green, blue] }
+      return [[], "".b] if pixels.empty?
+
+      boxes = [pixels]
+      while boxes.length < colors
+        index = boxes.each_index.max_by { |box_index| split_range(boxes[box_index]) }
+        box = boxes[index]
+        break if box.length < 2
+
+        axis = widest_axis(box)
+        sorted = box.sort_by { |pixel| pixel[axis] }
+        midpoint = sorted.length / 2
+        boxes[index] = sorted.first(midpoint)
+        boxes << sorted.drop(midpoint)
+      end
+
+      palette = boxes.map do |box|
+        box.transpose.map { |channel| (channel.sum.to_f / channel.length).round }
+      end
+      indices = pixels.map do |pixel|
+        palette.each_index.min_by { |index| pixel.zip(palette[index]).sum { |left, right| (left - right)**2 } }
+      end.pack("C*")
+      [palette, indices]
+    end
+
+    def split_range(box)
+      ranges = 3.times.map { |axis| box.map { |pixel| pixel[axis] }.max - box.map { |pixel| pixel[axis] }.min }
+      ranges.max * box.length
+    end
+    private_class_method :split_range
+
+    def widest_axis(box)
+      3.times.max_by { |axis| box.map { |pixel| pixel[axis] }.max - box.map { |pixel| pixel[axis] }.min }
+    end
+    private_class_method :widest_axis
+  end
+
+  class InputParser
+    CSI_KEYS = { "A" => :up, "B" => :down, "C" => :right, "D" => :left, "H" => :home, "F" => :end }.freeze
+    CSI_TILDE_KEYS = { 1 => :home, 2 => :insert, 3 => :delete, 4 => :end, 5 => :page_up, 6 => :page_down }.freeze
+
+    def initialize
+      @buffer = "".b
+    end
+
+    def feed(bytes)
+      @buffer << bytes
+      events = []
+      loop do
+        if @buffer.start_with?("\e[<")
+          match = @buffer.match(/\A\e\[<([0-9]+);([0-9]+);([0-9]+)([Mm])/
+          )
+          break unless match
+          @buffer = @buffer.byteslice(match[0].bytesize..).to_s.b
+          button = match[1].to_i
+          event = { x: match[2].to_i - 1, y: match[3].to_i - 1, modifiers: mouse_modifiers(button) }
+          if button & 64 != 0
+            event.merge!(type: :scroll, dx: 0.0, dy: (button & 1).zero? ? 1.0 : -1.0)
+          elsif button & 32 != 0
+            event.merge!(type: :mouse_move, button: button & 3)
+          else
+            event.merge!(type: match[4] == "M" ? :mouse_press : :mouse_release, button: button & 3)
+          end
+          events << event
+        elsif @buffer.start_with?("\e[")
+          match = @buffer.match(/\A\e\[([0-9;]*)([A-Za-z~])/)
+          break unless match
+          @buffer = @buffer.byteslice(match[0].bytesize..).to_s.b
+          parameters = match[1].split(";").reject(&:empty?).map(&:to_i)
+          key = if match[2] == "~"
+            CSI_TILDE_KEYS[parameters.first] || :unknown
+          elsif match[2] == "Z"
+            :tab
+          else
+            CSI_KEYS[match[2]] || match[2].to_sym
+          end
+          event = { type: :key_press, key: key }
+          modifiers = match[2] == "Z" ? [:shift] : csi_modifiers(parameters[1] || 1)
+          event[:modifiers] = modifiers unless modifiers.empty?
+          events << event
+        elsif @buffer.start_with?("\eO")
+          break if @buffer.bytesize < 3
+          key = { "P" => :f1, "Q" => :f2, "R" => :f3, "S" => :f4 }[@buffer.getbyte(2).chr] || @buffer.getbyte(2).chr.to_sym
+          @buffer = @buffer.byteslice(3..).to_s.b
+          events << { type: :key_press, key: key }
+        elsif @buffer.start_with?("\e")
+          break if @buffer.bytesize < 2
+          @buffer = @buffer.byteslice(1..).to_s.b
+          events << { type: :key_press, key: :escape }
+        else
+          byte = @buffer.getbyte(0)
+          break unless byte
+          @buffer = @buffer.byteslice(1..).to_s.b
+          key = case byte
+          when 3 then :close
+          when 9 then :tab
+          when 13 then :enter
+          when 127 then :backspace
+          when 32..126 then byte.chr.to_sym
+          else next
+          end
+          events << { type: :key_press, key: key, char: byte.chr }
+        end
+      end
+      events
+    end
+
+    def flush
+      return [] if @buffer.empty?
+      @buffer = "".b
+      [{ type: :key_press, key: :escape }]
+    end
+
+    private
+
+    def csi_modifiers(value)
+      modifier_bits(value.to_i - 1)
+    end
+
+    def mouse_modifiers(button)
+      modifier_bits((button >> 2) & 7)
+    end
+
+    def modifier_bits(value)
+      [[:shift, 1], [:alt, 2], [:control, 4]].filter_map { |name, bit| name if value & bit != 0 }
+    end
+  end
+
+  class Detector
+    def self.protocol(env = ENV)
+      forced = env["TERMVAS_PROTOCOL"]
+      return forced.to_sym if forced
+      return :kitty if env["TERM"] == "xterm-kitty" || env["KITTY_WINDOW_ID"] || %w[WezTerm ghostty].include?(env["TERM_PROGRAM"])
+      return :iterm2 if env["TERM_PROGRAM"] == "iTerm.app"
+      :blocks
+    end
+  end
+
+  class Terminal
+    attr_reader :input, :output
+
+    def initialize(input: $stdin, output: $stdout, alt_screen: true, tmux: false)
+      @input = input
+      @output = output
+      @alt_screen = alt_screen
+      @closed = false
+      @opened = false
+      @raw = false
+      @tmux = tmux
+      @resized = false
+      @signal_handlers = {}
+    end
+
+    def size
+      rows, columns = @input.winsize
+      return [columns, rows] if rows.to_i.positive? && columns.to_i.positive?
+
+      fallback_size
+    rescue Errno::ENOTTY, IOError, NoMethodError
+      fallback_size
+    end
+
+    def open
+      return self if @opened
+      @opened = true
+      @mouse_tracking = false
+      if @input.respond_to?(:tty?) && @input.tty?
+        if @input.respond_to?(:raw!)
+          @input.raw!
+          @raw = true
+        end
+        @output.write("\e[?1000h\e[?1003h\e[?1006h")
+        @mouse_tracking = true
+      end
+      install_signal_handlers
+      @output.write("\e[?1049h") if @alt_screen
+      @output.write("\e[?25l")
+      @output.flush
+      at_exit { restore }
+      self
+    end
+
+    def write(value)
+      value = "\ePtmux;\e#{value.gsub("\e", "\e\e")}\e\\" if @tmux
+      @output.write(value)
+      @output.flush
+    end
+
+    def restore
+      return if @closed
+      @closed = true
+      restore_signal_handlers
+      begin
+        @output.write("\e[?25h\e[?1000l\e[?1003l\e[?1006l") if @mouse_tracking
+        @output.write("\e[?25h") unless @mouse_tracking
+        @output.write("\e[?1049l") if @alt_screen
+        @output.flush
+      ensure
+        @input.cooked! if @raw
+        @raw = false
+      end
+    end
+
+    alias close restore
+
+    def resized?
+      resized = @resized
+      @resized = false
+      resized
+    end
+
+    private
+
+    def install_signal_handlers
+      handlers = { "WINCH" => proc { @resized = true }, "INT" => proc { restore }, "TERM" => proc { restore } }
+      exit_codes = { "INT" => 130, "TERM" => 143 }
+      handlers.each do |signal, handler|
+        previous = nil
+        previous = Signal.trap(signal) do |number|
+          handler.call
+          previous.call(number) if previous.respond_to?(:call)
+          exit(exit_codes[signal]) if exit_codes.key?(signal)
+        end
+        @signal_handlers[signal] = previous
+      end
+    rescue ArgumentError, Errno::EINVAL
+      restore_signal_handlers
+    end
+
+    def restore_signal_handlers
+      @signal_handlers.each { |signal, previous| Signal.trap(signal, previous) }
+      @signal_handlers.clear
+    rescue ArgumentError, Errno::EINVAL
+      @signal_handlers.clear
+    end
+
+    def fallback_size
+      columns = Integer(ENV.fetch("COLUMNS", 80))
+      rows = Integer(ENV.fetch("LINES", 24))
+      [columns.positive? ? columns : 80, rows.positive? ? rows : 24]
+    rescue ArgumentError, TypeError
+      [80, 24]
+    end
+  end
+
+  class Backend < RBGL::GUI::Backend
+    attr_reader :width, :height, :protocol
+
+    def initialize(width, height, protocol: :auto, fit: :contain, max_fps: 30, quantize: :fixed, tmux: :auto, output: $stdout, input: $stdin, alt_screen: true, **_options)
+      super(Integer(width), Integer(height), "Termvas")
+      @protocol = protocol == :auto ? Detector.protocol : protocol.to_sym
+      @quantize = quantize.to_sym
+      tmux = ENV.key?("TMUX") if tmux == :auto
+      tmux &&= %i[kitty sixel].include?(@protocol)
+      raise ArgumentError, "unsupported terminal protocol: #{@protocol}" unless %i[blocks kitty iterm2 sixel].include?(@protocol)
+      @fit = fit.to_sym
+      raise ArgumentError, "fit must be :contain or :none" unless %i[contain none].include?(@fit)
+      @max_fps = max_fps.nil? ? nil : Float(max_fps)
+      raise ArgumentError, "max_fps must be positive" if @max_fps && !@max_fps.positive?
+      @terminal = Terminal.new(input: input, output: output, alt_screen: alt_screen, tmux: tmux)
+      @output = output
+      @input = input
+      @closed = false
+      @previous = nil
+      @parser = InputParser.new
+      @last_frame_at = nil
+      @terminal.open
+    end
+
+    def open = (@terminal.open; self)
+
+    def present(framebuffer)
+      set_pixels(framebuffer.respond_to?(:to_rgba_bytes) ? framebuffer.to_rgba_bytes : framebuffer, framebuffer.width, framebuffer.height)
+    end
+
+    def set_pixels(bytes, width = @width, height = @height)
+      bytes = validate_rgba_buffer(bytes, width, height)
+      width, height = Integer(width), Integer(height)
+      if @fit == :contain
+        columns, rows = @terminal.size
+        target_width, target_height = Scaler.contain(width, height, columns, rows)
+        bytes, width, height = Scaler.nearest(bytes, width, height, target_width, target_height)
+      end
+      @previous = nil if @previous_size && @previous_size != [width, height]
+      return if @previous == bytes
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if @last_frame_at && @max_fps && now - @last_frame_at < 1.0 / @max_fps
+
+      encoded = case @protocol
+      when :kitty then Encoders::Kitty.encode(bytes, width, height)
+      when :iterm2
+        require "tessel"
+        Encoders::ITerm2.encode(Tessel::PNG.encode(Tessel::Image.from_rgba(width, height, bytes)), width: width, height: height)
+      when :sixel then Encoders::Sixel.encode(bytes, width, height, quantize: @quantize)
+      else Encoders::Blocks.encode(bytes, width, height, previous: @previous)
+      end
+      @terminal.write(encoded)
+      @previous = bytes.dup
+      @previous_size = [width, height]
+      @last_frame_at = now
+    end
+
+    def poll_events
+      return [] unless @input.respond_to?(:read_nonblock)
+      resize = if @terminal.resized?
+        columns, rows = @terminal.size
+        { type: :resize, columns: columns, rows: rows }
+      end
+      bytes = @input.read_nonblock(4096, exception: false)
+      events = bytes.is_a?(String) ? @parser.feed(bytes) : []
+      events = map_mouse_events(events)
+      events.unshift(resize) if resize
+      if events.any? { |event| event[:key] == :close }
+        @closed = true
+        @terminal.close
+      end
+      events
+    rescue IOError, Errno::EIO
+      []
+    end
+
+    def should_close?
+      @closed
+    end
+
+    def close
+      return if @closed
+      @closed = true
+      @terminal.close
+    end
+
+    private
+
+    def map_mouse_events(events)
+      return events unless @previous_size
+
+      columns, rows = @terminal.size
+      display_width = [@previous_size[0], columns].min
+      display_height = [@previous_size[1], rows * 2].min
+      events.filter_map do |event|
+        next event unless event.key?(:x) && event.key?(:y)
+
+        x = event[:x] * display_width.to_f / columns
+        y = event[:y] * display_height.to_f / rows
+        next if x >= display_width || y >= display_height
+
+        event.merge(x: x, y: y)
+      end
+    end
+  end
+end

data/sig/termvas.rbs

@@ -0,0 +1,4 @@
+module Termvas
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: termvas
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ydah
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbgl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: Half block, Kitty, iTerm2, and Sixel terminal output with input parsing.
+email:
+- t.yudai92@gmail.com
+executables:
+- termvas
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/keys.md
+- exe/termvas
+- lib/termvas.rb
+- lib/termvas/version.rb
+- sig/termvas.rbs
+homepage: https://github.com/rbgfx/termvas
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rbgfx/termvas
+  source_code_uri: https://github.com/rbgfx/termvas/tree/main
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Terminal backend for Ruby graphics
+test_files: []