reflex-terminal 0.1.0

data/.github/workflows/release-gem.yml

@@ -0,0 +1,60 @@
+name: Release Gem
+
+on:
+  push:
+    tags: ['v[0-9]*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: macos-latest
+
+    steps:
+      - name: ruby 3.2
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup gems
+        run: bundle install
+
+      - name: setup dependencies
+        run: "ruby -I.github/workflows -rutils -e 'setup_dependencies'"
+
+      - name: packages
+        run: bundle exec rake packages
+
+      - name: setup zig
+        if: github.event.repository.name == 'reflex-terminal'
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
+      - name: test
+        run: bundle exec rake test
+
+      - name: create gem
+        id: gem
+        run: |
+          bundle exec rake gem
+          echo path=$(ruby -e 'print Dir.glob("*.gem").first') >> $GITHUB_OUTPUT
+
+      - name: create github release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ruby -I.github/workflows -rutils -e 'release(*ARGV)' ./${{ steps.gem.outputs.path }}
+
+      - name: upload to rubygems
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          bundle exec rake upload

data/.github/workflows/tag.yml

@@ -0,0 +1,35 @@
+name: Tag
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ruby 3.2
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.PAT }}
+
+      - name: setup dependencies
+        run: "ruby -I.github/workflows -rutils -e 'setup_dependencies only: :xot'"
+
+      - name: setup user name and email
+        run: |
+          git config --global user.email "xordog@gmail.com"
+          git config --global user.name "xord"
+
+      - name: tag versions
+        run: "ruby -I.github/workflows -rutils -e 'tag_versions'"
+
+      - name: push tags
+        run: git push origin --tags

data/.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: macos-latest
+
+    steps:
+      - name: ruby 3.2
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup gems
+        run: bundle install
+
+      - name: setup dependencies
+        run: "ruby -I.github/workflows -rutils -e 'setup_dependencies'"
+
+      - name: packages
+        run: bundle exec rake verbose packages
+
+      - name: setup zig
+        if: github.event.repository.name == 'reflex-terminal'
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+
+      - name: vendor
+        run: bundle exec rake vendor
+
+      - name: lib
+        run: bundle exec rake verbose lib
+
+      - name: ext
+        run: bundle exec rake verbose ext
+
+      - name: test
+        run: bundle exec rake verbose test

data/.github/workflows/utils.rb

@@ -0,0 +1,127 @@
+require 'shellwords'
+
+ALL_REPO        = 'xord/all'
+ALL_DIR         = '../all'
+ALL_FETCH_DEPTH = 100
+
+RENAMES = {reflex: 'reflexion'}
+
+def sh(cmd)
+  puts cmd
+  system cmd
+end
+
+def setup_dependencies(only: nil)
+  gemspec_path = `git ls-files`.lines(chomp: true).find {|l| l =~ /\.gemspec$/}
+  return unless gemspec_path
+
+  gemspec = File.read gemspec_path
+  name    = File.basename gemspec_path, '.gemspec'
+
+  exts = File.readlines('Rakefile')
+    .map {|l| l[%r|^\s*require\W+([\w\-\_]+)/extension\W+$|, 1]}
+    .compact
+    .reject {|ext| ext == name}
+  exts = exts & [only].flatten.map(&:to_s) if only
+  return if exts.empty?
+
+  unless setup_dependencies_via_monorepo(exts)
+    setup_dependencies_via_each_repo_by_version(gemspec, exts)
+  end
+
+  exts.each {|ext| sh %( cd ../#{ext} && rake ext )}
+end
+
+def setup_dependencies_via_monorepo(exts)
+  return false unless checkout_monorepo
+  exts.each {|ext| sh %( ln -snf all/#{ext} ../#{ext} )}
+  true
+end
+
+def checkout_monorepo()
+  uuid = `git log -1 --format=%B`[/^\[\[([0-9a-fA-F-]+)\]\]$/, 1]
+  return false unless uuid
+
+  commit = setup_monorepo uuid
+  return false unless commit
+
+  Dir.chdir(ALL_DIR) {sh %( git checkout -q #{commit} )}
+  true
+end
+
+def setup_monorepo(uuid)
+  unless File.directory? ALL_DIR
+    url = "https://github.com/#{ALL_REPO}.git"
+    sh %( git clone --no-tags --depth #{ALL_FETCH_DEPTH} #{url} #{ALL_DIR} )
+  end
+  loop do
+    commit = find_monorepo_commit uuid
+    return commit if commit
+
+    deepened = Dir.chdir ALL_DIR do
+      before = `git rev-list --count HEAD`.to_i
+      sh %( git fetch --deepen #{ALL_FETCH_DEPTH} )
+      `git rev-list --count HEAD`.to_i > before
+    end
+    return nil unless deepened
+  end
+end
+
+def find_monorepo_commit(uuid)
+  Dir.chdir ALL_DIR do
+    out = `git log origin/HEAD -F --grep="[[#{uuid}]]" --format=%H -1`.strip
+    out.empty? ? nil : out
+  end
+end
+
+def setup_dependencies_via_each_repo_by_version(gemspec, exts)
+  exts.each do |ext|
+    gem   = RENAMES[ext.to_sym].then {|s| s || ext}
+    ver   = gemspec[/add_dependency.*['"]#{gem}['"].*['"]\s*~>\s*([\d\.]+)\s*['"]/, 1]
+    opts  = '-c advice.detachedHead=false --depth 1'
+    clone = "git clone #{opts} https://github.com/xord/#{ext}.git ../#{ext}"
+
+    # 'rake subtree:push' pushes all subrepos, so cloning by new tag
+    # often fails before tagging each new tag
+    sh %( #{clone} --branch v#{ver} || #{clone} )
+  end
+end
+
+def tag_versions()
+  changes = changelogs
+  tags    = `git tag`.lines chomp: true
+  vers    = `git log --oneline ./VERSION`
+    .lines(chomp: true)
+    .map {|line| line.split.first[/^\w+$/]}
+    .map {|sha| [`git cat-file -p #{sha}:./VERSION 2>/dev/null`[/[\d\.]+/], sha]}
+    .select {|ver, sha| ver && sha}
+    .reverse
+    .to_h
+
+  vers.to_a.reverse.each do |ver, sha|
+    tag = "v#{ver}"
+    break if tags.include?(tag)
+    sh %( git tag -a -m \"#{changes[tag]&.gsub '"', '\\"'}\" #{tag} #{sha} )
+  end
+end
+
+def release(*paths)
+  tag   = ENV['GITHUB_REF']&.sub(%r|^refs/tags/|, '') || raise('GITHUB_REF tag not set')
+  notes = (changelogs[tag] || '').shellescape
+  paths = paths.flatten.join ' '
+
+  sh(%( gh release create #{tag} #{paths} --notes #{notes} )) ||
+    sh(%( gh release upload #{tag} #{paths} --clobber )) ||
+    raise('failed to upload to releases')
+end
+
+def changelogs()
+  File.read('ChangeLog.md')
+    .split(/^\s*##\s*\[\s*(v[\d\.]+)\s*\].*$/)
+    .slice(1..)
+    .each_slice(2)
+    .to_h
+    .transform_values(&:strip!)
+rescue Errno::ENOENT
+  raise 'failed to get changelogs'
+end

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contribution Guide
+
+Thank you for your interest in contributing!
+However, this repository does not accept pull requests.
+Instead, please submit your changes to the [xord/all](https://github.com/xord/all) monorepo, which serves as the primary repository for all our main libraries.
+
+For any questions, feel free to open an issue.

data/ChangeLog.md

@@ -0,0 +1,6 @@
+# reflex-terminal ChangeLog
+
+
+## [v0.1.0] - 2026-08-04
+
+- Initial release

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'test-unit'
+gem 'yard'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xord.org
+
+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,100 @@
+# Reflex Terminal - A terminal emulator for Reflex
+
+**Status: Usable, but the API is not stable yet.**
+
+reflex-terminal provides a terminal emulator for the
+[Reflex](https://github.com/xord/reflex) GUI toolkit:
+
+- `Reflex::Terminal` — a headless terminal emulator model. It spawns a shell
+  on a PTY and maintains the screen state (cells, colors, scrollback, reflow
+  on resize) using [libghostty-vt](https://libghostty.tip.ghostty.org/),
+  the terminal emulation core extracted from
+  [Ghostty](https://github.com/ghostty-org/ghostty).
+- `Reflex::TerminalView` — a `Reflex::View` that renders a `Terminal` and
+  feeds keyboard / mouse input into it.
+
+Full-screen programs work: emacs and mouse-driven terminal multiplexers run
+in it, with colors, CJK text, reflow on resize and scrollback.
+
+## Usage
+
+```ruby
+require 'reflex-terminal'
+
+win = Reflex::Window.new {
+  title 'Terminal'
+  frame 100, 100, 720, 450
+}
+win.add Reflex::TerminalView.new
+win.show
+
+Reflex.start
+```
+
+See `examples/terminal.rb`.
+
+### Without a child process
+
+A `Terminal` does not have to run a shell. Feed it bytes and it renders
+whatever speaks terminal escape sequences — a build log, a recorded
+session — with its colors and cursor motion applied:
+
+```ruby
+t = Reflex::Terminal.new 120, 40
+t.feed File.binread('build.log')
+t.update
+puts t.lines
+```
+
+Driving an interactive program over your own transport takes one more call:
+`#read_pending_input` hands back the bytes the terminal wants to send
+upstream, which are the query responses it generates on its own plus any
+encoded key and mouse events.
+
+## Requirements
+
+- macOS, Linux or Windows
+- Ruby 3.0+
+- [Zig](https://ziglang.org/) **0.16.0** — required to build libghostty-vt
+  from source into `vendor/ghostty/`. On macOS `rake packages` installs it
+  through Homebrew; elsewhere take the 0.16.0 build for your platform from
+  the [downloads page](https://ziglang.org/download/) and put it on `PATH`,
+  since packaged versions rarely match the one the pinned ghostty commit
+  asks for.
+
+## Build
+
+```bash
+$ rake packages   # macOS: installs zig through Homebrew
+$ rake ext        # clones + builds libghostty-vt (first time only), then the extension
+$ rake test
+```
+
+## Limitations
+
+- No input method support, so Japanese and other composed text cannot be
+  typed. Reflex hands key events straight to the view without going through
+  the platform's input context, which is where composition would start.
+- On Linux, `TerminalView` needs a font handed to it (`font:` with a
+  `Rays::Font` or a path). Rays cannot look one up by name there, so the
+  default font name does not resolve.
+- On Windows, the single-string form of `Terminal#spawn` cannot contain
+  quotes. It runs through `cmd.exe /c`, which does not understand the
+  backslash escaping that the command line is built with. Pass the command
+  as separate arguments instead.
+- No image protocols (Kitty graphics, Sixel).
+- No selection or copy UI. `#lines` and `#each_history_line` return the text.
+
+## Updating the vendored libghostty-vt
+
+libghostty-vt is under active development and has no standalone releases yet
+(ghostty release tags up to v1.3.1 do not contain the terminal C APIs), so
+this gem pins a verified commit of ghostty's main branch: see the `commit:`
+given to `use_external_library` in `Rakefile`. To update:
+
+1. Bump that commit (check `minimum_zig_version` in ghostty's
+   `build.zig.zon` still matches the installed Zig)
+2. `rake vendor:ghostty:update`
+3. `rake ext test`
+
+Once libghostty-vt gets standalone releases, switch the pin to a release tag.

data/Rakefile

@@ -0,0 +1,44 @@
+# -*- mode: ruby -*-
+
+
+%w[../xot ../rucy ../rays ../reflex .]
+  .map  {|s| File.expand_path "#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'rucy/rake'
+
+require 'xot/extension'
+require 'rucy/extension'
+require 'rays/extension'
+require 'reflex/extension'
+require 'reflex-terminal/extension'
+
+
+EXTENSIONS  = [Xot, Rucy, Rays, Reflex, ReflexTerminal]
+TESTS_ALONE = []
+
+install_packages osx: %w[zig]
+
+use_external_library 'https://github.com/ghostty-org/ghostty',
+  # libghostty-vt is not released as a standalone library yet, so pin a
+  # verified commit on ghostty's main branch. (Release tags up to v1.3.1 do
+  # not contain the terminal/render C APIs.) Bump intentionally, then run
+  # 'rake vendor:ghostty:update' and re-run the tests.
+  commit:  '2de5e7d38e1354759211722a8687c0815d2cf02c',# requires Zig 0.16.0
+  incdirs: 'zig-out/include',
+  srcdirs: 'NOSRC',
+  defs:    'GHOSTTY_STATIC',
+  &proc {
+    opts  = '-Demit-lib-vt -Doptimize=ReleaseFast'
+    opts += ' -Dtarget=x86_64-windows-gnu' if win32?
+    sh %( zig build #{opts} )
+    sh %( mv zig-out/lib/libghostty-vt.a zig-out/lib/libghostty-vt-static.a ) unless win32?
+  }
+
+default_tasks :ext
+use_bundler
+build_native_library
+build_ruby_extension
+test_ruby_extension unless github_actions? && win32?
+generate_documents
+build_ruby_gem

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/examples/terminal.rb

@@ -0,0 +1,101 @@
+%w[xot rucy rays reflex reflex-terminal]
+  .map  {|s| File.expand_path "../../#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'reflex-terminal'
+
+
+def copy(terminal)
+  text = terminal.selected_text
+  Reflex::Clipboard.text = text unless text.empty?
+end
+
+def copyable?(terminal)
+  terminal.selection?
+end
+
+def paste(terminal)
+  text = Reflex::Clipboard.text
+  return if text.to_s.empty?
+  terminal.scroll_to 0 if terminal.scroll != 0
+  terminal.paste text
+end
+
+def pasteable?()
+  !Reflex::Clipboard.text.to_s.empty?
+end
+
+
+terminal    = Reflex::Terminal.new.spawn
+view        = Reflex::TerminalView.new terminal: terminal, font_size: 24
+shortcut    = Xot.osx? ? %i[command] : %i[control shift]
+taken       = []
+flash       = 0
+flash_timer = nil
+
+view.after :on_draw do |e|
+  next if flash <= 0
+  e.painter.fill 1, flash
+  e.painter.rect e.bounds
+  flash *= 0.9
+  flash  = 0 if flash < 0.01
+end
+
+view.before :on_key_down do |e|
+  # locks are states the keyboard is left in rather than keys held for
+  # the stroke, so a shortcut has to match with them left out
+  next unless e.modifiers(locks: false).sort == shortcut.sort
+
+  case e.code
+  when Reflex::KEY_C then copy terminal
+  when Reflex::KEY_V then paste terminal
+  else next
+  end
+
+  # the press is taken, so its release has to be taken with it or the
+  # child is told a key went up that it never saw go down. The modifier
+  # can be let go first, so the key itself is what has to be remembered
+  taken |= [e.code]
+  :skip
+end
+
+view.before :on_key_up do |e|
+  :skip if taken.delete e.code
+end
+
+# on the release, not the press: a native menu runs an event loop of its
+# own and swallows the mouse up, which would leave the window believing the
+# button was still down and every later drag starting where it was clicked
+view.before :on_pointer_up do |e|
+  next unless e.right?
+  m = Reflex::Menu.new
+
+  c = m.add Reflex::Menu.new('Copy')
+  c.on(:show)  {|e| c.enable copyable?(terminal)}
+  c.on(:click) {|e| copy terminal}
+
+  p = m.add Reflex::Menu.new('Paste')
+  p.on(:show)  {|e| p.enable pasteable?}
+  p.on(:click) {|e| paste terminal}
+
+  m.popup view, e.x, e.y
+end
+
+view.on :bell do |e|
+  flash = 0.8
+
+  flash_timer&.stop
+  flash_timer = view.interval do
+    view.redraw
+    flash_timer.stop if flash <= 0
+  end
+end
+
+win = Reflex::Window.new do
+  title 'Terminal Example'
+  frame 100, 100, 720, 450
+end
+win.add view
+win.show
+
+Reflex.start

data/ext/reflex-terminal/defs.h

@@ -0,0 +1,17 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __REFLEX_TERMINAL_EXT_DEFS_H__
+#define __REFLEX_TERMINAL_EXT_DEFS_H__
+
+
+#include <rucy.h>
+#include "reflex/defs.h"
+#include "reflex/ruby/defs.h"
+
+
+using namespace Xot::Types;
+
+using namespace Rucy;
+
+
+#endif//EOH

data/ext/reflex-terminal/extconf.rb

@@ -0,0 +1,29 @@
+%w[../xot ../rucy ../rays ../reflex .]
+  .map  {|s| File.expand_path "../../#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'mkmf'
+require 'xot/extconf'
+require 'xot/extension'
+require 'rucy/extension'
+require 'rays/extension'
+require 'reflex/extension'
+require 'reflex-terminal/extension'
+
+
+Xot::ExtConf.new Xot, Rucy, Rays, Reflex, ReflexTerminal do
+  setup do
+    vendor = File.expand_path '../../vendor/ghostty', __dir__
+
+    headers    << 'ruby.h'
+    defs       << 'GHOSTTY_STATIC'
+    inc_dirs   << "#{vendor}/zig-out/include"
+    lib_dirs   << "#{vendor}/zig-out/lib"
+    local_libs << 'util'  if linux?
+    local_libs << 'ntdll' if win32?
+    local_libs << 'ghostty-vt-static'
+    $LDFLAGS   << ' -Wl,--out-implib=libreflex-terminal.dll.a' if mingw? || cygwin?
+  end
+
+  create_makefile 'reflex_terminal_ext'
+end

data/ext/reflex-terminal/native.cpp

@@ -0,0 +1,19 @@
+#include "defs.h"
+
+
+void Init_reflex_terminal ();
+void Init_reflex_terminal_renderer ();
+
+
+extern "C" void
+Init_reflex_terminal_ext ()
+{
+	RUCY_TRY
+
+	Rucy::init();
+
+	Init_reflex_terminal();
+	Init_reflex_terminal_renderer();
+
+	RUCY_CATCH
+}