ratatui_ruby 1.0.0 → 1.1.0

data/sig/ratatui_ruby/backend/window_size.rbs

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Backend
+    class WindowSize < Data
+      attr_reader columns_rows: Layout::Size
+      attr_reader pixels: Layout::Size
+
+      def self.new: (columns_rows: Layout::Size, pixels: Layout::Size) -> instance
+    end
+  end
+end

data/sig/ratatui_ruby/backend.rbs

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Backend
+    def self.window_size: () -> WindowSize?
+  end
+end

data/sig/ratatui_ruby/event.rbs

@@ -111,6 +111,11 @@ module RatatuiRuby
       def drag?: () -> bool
       def scroll_up?: () -> bool
       def scroll_down?: () -> bool
+      def left?: () -> bool
+      def right?: () -> bool
+      def middle?: () -> bool
+      def to_sym: () -> Symbol
+      def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :mouse, kind: String, x: Integer, y: Integer, button: String, modifiers: Array[String] }
     end
 
@@ -119,6 +124,8 @@ module RatatuiRuby
       attr_reader height: Integer
 
       def initialize: (width: Integer, height: Integer) -> void
+      def to_sym: () -> Symbol
+      def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :resize, width: Integer, height: Integer }
     end
 

data/sig/ratatui_ruby/layout/alignment.rbs

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    module HorizontalAlignment
+      LEFT: :left
+      CENTER: :center
+      RIGHT: :right
+      ALL: Array[:left | :center | :right]
+    end
+
+    module VerticalAlignment
+      TOP: :top
+      CENTER: :center
+      BOTTOM: :bottom
+      ALL: Array[:top | :center | :bottom]
+    end
+
+    Alignment: singleton(HorizontalAlignment)
+  end
+end

data/sig/ratatui_ruby/ratatui_ruby.rbs

@@ -102,6 +102,8 @@ module RatatuiRuby
   def self._get_terminal_size: () -> Hash[String, Integer]
   def self._get_viewport_type: () -> String
   def self.insert_before: (Integer height, ?widget? widget) ?{ () -> widget } -> void
+  def self._frame_count: () -> Integer
+  def self.frame_count: () -> Integer
 
   # Color conversion (internal, Rust FFI)
   def self._color_from_u32: (Integer) -> String

data/sig/ratatui_ruby/terminal/capabilities.rbs

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Terminal
+    # Environment-based terminal capability detection.
+    # Provides class methods for detecting terminal capabilities.
+    module Capabilities
+      def tty?: () -> bool
+      def dumb?: () -> bool
+      def no_color?: () -> bool
+      def force_color?: () -> bool
+      def interactive?: () -> bool
+      def available_color_count: () -> Integer
+      def color_support: () -> (:none | :basic | :ansi256 | :truecolor)
+      def supports_keyboard_enhancement?: () -> bool
+      def force_color_output: (bool enable) -> void
+
+      private
+
+      # FFI methods (defined in Rust, exposed on Terminal singleton)
+      def _available_color_count: () -> Integer
+      def _supports_keyboard_enhancement: () -> bool
+      def _force_color_output: (bool enable) -> void
+    end
+
+    extend Capabilities
+
+    private
+
+    # FFI singleton method for Backend.window_size
+    def self._terminal_window_size: () -> [Integer, Integer, Integer, Integer]?
+  end
+end

data/sig/ratatui_ruby/terminal/viewport.rbs

@@ -2,7 +2,21 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 module RatatuiRuby
-  module Terminal
+  class Terminal
+    @viewport: Terminal::Viewport
+    @terminal_id: Integer
+
+    attr_reader terminal_id: Integer
+
+    def initialize: (?viewport: (Terminal::Viewport | :fullscreen | :inline)?, ?height: Integer?) -> void
+    def size: () -> Layout::Rect
+
+    # Private native methods (defined in Rust)
+    def self._init_test_terminal_instance: (Integer width, Integer height, String viewport_type, Integer? viewport_height) -> Integer
+    def self._get_terminal_size_instance: (Integer terminal_id) -> Layout::Rect
+
+    private def resolve_viewport: ((Terminal::Viewport | :fullscreen | :inline)? viewport, Integer? height) -> Terminal::Viewport
+
     class Viewport < Data
       attr_reader type: Symbol
       attr_reader height: Integer?

data/tasks/bump/bump_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "repository"
+require_relative "changelog"
+
+# Base class for version bump workflows.
+# Subclasses implement the template methods: prepare, release_on_branch, finalize.
+class BumpWorkflow
+  def initialize(gem:, repository: Repository.new)
+    @gem = gem
+    @repository = repository
+  end
+
+  def call(segment)
+    @repository.assert_can_bump!(segment)
+    @target = @gem.version.next(segment)
+
+    prepare(segment)
+    release_on_branch
+    finalize
+  end
+
+  attr_reader :target
+
+  private def release_on_branch
+    changelog = Changelog.new
+    @commit_message = changelog.commit_message(target)
+    changelog.release(target)
+    @gem.update_version(target)
+    generate_ci_manifests
+    @repository.commit_all(@commit_message)
+  end
+
+  private def generate_ci_manifests
+    Rake::Task["sourcehut:build:manifest"].reenable
+    Rake::Task["sourcehut:build"].reenable
+    Rake::Task["sourcehut"].reenable
+    Rake::Task["sourcehut"].invoke
+  end
+
+  # Template methods for subclasses
+  private def prepare(segment) = nil
+  private def finalize = nil
+end

data/tasks/bump/changelog.rb

@@ -37,6 +37,54 @@ class Changelog
     nil
   end
 
+  # Removes entries from [Unreleased] that were released in the given version.
+  # Used when creating a release branch from trunk.
+  def prune_released_entries(released_entries)
+    content = File.read(@path)
+
+    header = Header.parse(content)
+    unreleased = UnreleasedSection.parse(content)
+    links = Links.from_markdown(content)
+
+    raise "Could not parse CHANGELOG.md" unless header && unreleased && links
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links.to_s)
+
+    pruned = unreleased.without_entries(released_entries)
+
+    File.write(@path, "#{header}#{pruned}\n\n#{history}\n#{links}")
+    nil
+  end
+
+  # Imports a release section from another branch's changelog.
+  # Adds the version section to history and dedupes from [Unreleased].
+  # Uses "first wins" — if entry already deduped, doesn't re-add it.
+  def import_release(version, release_changelog_content)
+    release_section = extract_version_section(release_changelog_content, version)
+    return unless release_section
+
+    content = File.read(@path)
+
+    header = Header.parse(content)
+    unreleased = UnreleasedSection.parse(content)
+    links = Links.from_markdown(content)
+
+    raise "Could not parse CHANGELOG.md" unless header && unreleased && links
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links.to_s)
+
+    # Add the release section to history (inserted in version order)
+    history.add(release_section)
+    links.release(version)
+
+    # Dedupe from [Unreleased] (first-wins: if already gone, no-op)
+    release_entries = release_section.lines.select { |l| l.strip.start_with?("- ") }.map(&:strip)
+    pruned = unreleased.without_entries(release_entries)
+
+    File.write(@path, "#{header}#{pruned}\n\n#{history}\n#{links}")
+    nil
+  end
+
   def commit_message(version)
     content = File.read(@path)
     unreleased = UnreleasedSection.parse(content)
@@ -44,4 +92,13 @@ class Changelog
 
     "chore: release v#{version}\n\n#{unreleased.commit_body}"
   end
+
+  private def extract_version_section(changelog_content, version)
+    # Match the version heading and capture until the next version heading or links section
+    pattern = /^## \[#{Regexp.escape(version.to_s)}\][^\n]*\n(.*?)(?=^## \[|\n\[Unreleased\]:)/m
+    match = changelog_content.match(pattern)
+    return nil unless match
+
+    "## [#{version}]#{match[0].split("\n", 2).first.split(']', 2).last}\n#{match[1]}"
+  end
 end

data/tasks/bump/patch_release.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "bump_workflow"
+
+# PatchRelease performs a patch release on the current release branch.
+class PatchRelease < BumpWorkflow
+  private def prepare(segment)
+    puts "Bumping #{segment}: #{@gem.version} -> #{target}"
+  end
+
+  private def finalize
+    puts "\nCommitted. Push and run: bundle exec rake release"
+  end
+end

data/tasks/bump/release_branch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# ReleaseBranch represents a release/X.Y branch for a version series.
+class ReleaseBranch < Data.define(:major, :minor)
+  def self.for_version(semver)
+    new(semver.major, semver.minor)
+  end
+
+  def name
+    "release/#{major}.#{minor}"
+  end
+end

data/tasks/bump/release_from_trunk.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "bump_workflow"
+require_relative "release_branch"
+
+# ReleaseFromTrunk creates a release branch, releases there, syncs trunk, returns to release branch.
+class ReleaseFromTrunk < BumpWorkflow
+  private def prepare(segment)
+    @branch = ReleaseBranch.for_version(target)
+
+    puts "Creating release branch: #{@branch.name}"
+    puts "Bumping #{segment}: #{@gem.version} -> #{target}"
+
+    @repository.create_branch(@branch.name)
+  end
+
+  private def release_on_branch
+    super
+    puts "\nCommitted on #{@branch.name}."
+
+    # Capture for trunk import
+    @released_changelog_content = File.read("CHANGELOG.md")
+  end
+
+  private def finalize
+    sync_trunk
+    return_to_release_branch
+  end
+
+  private def sync_trunk
+    @repository.checkout("trunk")
+    trunk_changelog = Changelog.new
+    trunk_changelog.import_release(target, @released_changelog_content)
+    @gem.update_version(target)
+    generate_ci_manifests
+    @repository.commit_all("chore: import v#{target} to trunk")
+    puts "Committed on trunk."
+  end
+
+  private def return_to_release_branch
+    @repository.checkout(@branch.name)
+    puts "\nBack on #{@branch.name}. Review, push both branches, then: bundle exec rake release"
+  end
+end

data/tasks/bump/repository.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "shellwords"
+require "tmpdir"
+
+class Repository
+  TRUNK = "trunk"
+
+  def on_trunk? = current_branch == TRUNK
+
+  def current_branch
+    `git branch --show-current`.strip
+  end
+
+  def create_branch(name)
+    system("git checkout -b #{name}", exception: true)
+  end
+
+  def checkout(name)
+    system("git checkout #{name}", exception: true)
+  end
+
+  def assert_can_bump!(segment)
+    assert_pristine!
+
+    if on_trunk? && segment == :patch
+      raise ArgumentError, "Cannot bump:patch from trunk. Use a release branch."
+    end
+
+    if !on_trunk? && [:minor, :major].include?(segment)
+      raise ArgumentError, "Cannot bump:#{segment} from #{current_branch}. Switch to trunk first."
+    end
+  end
+
+  def assert_pristine!
+    return if `git status --porcelain`.strip.empty?
+
+    raise ArgumentError, "Working tree is not clean. Commit or stash changes first."
+  end
+
+  def commit_all(message)
+    msg_file = File.join(Dir.tmpdir, "ratatui_ruby_commit_msg_#{$$}.txt")
+    system("git add -A", exception: true)
+    File.write(msg_file, message)
+    system("git commit -F #{msg_file.shellescape}", exception: true)
+  ensure
+    File.delete(msg_file) if msg_file && File.exist?(msg_file)
+  end
+end

data/tasks/bump/ruby_gem.rb

@@ -5,45 +5,25 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 
+# RubyGem knows how to update its version: manifests, lockfiles.
 class RubyGem
-  def initialize(manifests:, lockfile:, changelog:)
+  def initialize(manifests:, lockfile:)
     raise ArgumentError, "Must have exactly one primary manifest" unless manifests.count(&:primary) == 1
     @manifests = manifests
     @lockfile = lockfile
-    @changelog = changelog
   end
 
   def version
     @manifests.find(&:primary).version
   end
 
-  def bump(segment)
-    target = version.next(segment)
-    commit_message = @changelog.commit_message(target)
-
-    puts "Bumping #{segment}: #{version} -> #{target}"
-    @changelog.release(target)
-    @manifests.each { |manifest| manifest.write(target) }
-    @lockfile.refresh
-
-    puts_commit_message(commit_message)
-  end
-
-  def set(version_string)
-    target = SemVer.parse(version_string)
-    commit_message = @changelog.commit_message(target)
-
-    puts "Setting version: #{version} -> #{target}"
-    @changelog.release(target)
+  def update_version(target)
     @manifests.each { |manifest| manifest.write(target) }
     @lockfile.refresh
-
-    puts_commit_message(commit_message)
+    refresh_bundler_lockfile
   end
 
-  private def puts_commit_message(message)
-    puts "=" * 80
-    puts message
-    puts "=" * 80
+  private def refresh_bundler_lockfile
+    system("bundle install", exception: true)
   end
 end

data/tasks/bump/sem_ver.rb

@@ -22,6 +22,10 @@ class SemVer
     @prerelease = prerelease
   end
 
+  def major = @segments[0]
+  def minor = @segments[1]
+  def patch = @segments[2]
+
   def next(segment)
     index = SEGMENTS.index(segment)
     raise ArgumentError, "Invalid segment: #{segment}" unless index

data/tasks/bump/unreleased_section.rb

@@ -53,4 +53,21 @@ class UnreleasedSection
       .map { |line| formatter.wrap(line, 72) }
       .join("\n\n")
   end
+
+  # Returns all changelog entry lines (lines starting with "- ")
+  def entries
+    @content.lines.select { |line| line.strip.start_with?("- ") }.map(&:strip)
+  end
+
+  # Returns a new UnreleasedSection with entries removed that appear in the given list.
+  def without_entries(entries_to_remove)
+    return self if entries_to_remove.empty?
+
+    new_lines = @content.lines.reject do |line|
+      stripped = line.strip
+      entries_to_remove.include?(stripped)
+    end
+
+    self.class.new(new_lines.join)
+  end
 end

data/tasks/bump.rake

@@ -11,10 +11,11 @@ require_relative "bump/sem_ver"
 require_relative "bump/manifest"
 require_relative "bump/cargo_lockfile"
 require_relative "bump/ruby_gem"
-require_relative "bump/changelog"
+require_relative "bump/release_from_trunk"
+require_relative "bump/patch_release"
 
 namespace :bump do
-  ratatuiRuby = RubyGem.new(
+  gem = RubyGem.new(
     manifests: [
       Manifest.new(
         path: "lib/ratatui_ruby/version.rb",
@@ -31,21 +32,30 @@ namespace :bump do
       path: "ext/ratatui_ruby/Cargo.lock",
       dir: "ext/ratatui_ruby",
       name: "ratatui_ruby"
-    ),
-    changelog: Changelog.new
+    )
   )
 
-  SemVer::SEGMENTS.each do |segment|
-    desc "Bump #{segment} version"
-    task segment do
-      ratatuiRuby.bump(segment)
-      Rake::Task["sourcehut"].invoke
-    end
+  desc "Bump major version"
+  task :major do
+    ReleaseFromTrunk.new(gem:).call(:major)
+  end
+
+  desc "Bump minor version"
+  task :minor do
+    ReleaseFromTrunk.new(gem:).call(:minor)
+  end
+
+  desc "Bump patch version"
+  task :patch do
+    PatchRelease.new(gem:).call(:patch)
   end
 
   desc "Set exact version (e.g. rake bump:exact[0.1.0])"
   task :exact, [:version] do |_, args|
-    ratatuiRuby.set(args[:version])
+    target = SemVer.parse(args[:version])
+    changelog = Changelog.new
+    changelog.release(target)
+    gem.update_version(target)
     Rake::Task["sourcehut"].invoke
   end
 end

data/tasks/doc/documentation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "pathname"
+require_relative "source_file"
+
+# All documentation files in the project.
+#
+# Projects contain many files. Only some are documentation: Ruby source with
+# RDoc, Markdown guides, RDoc text files. Finding them manually is tedious.
+# Missing files means missing broken links.
+#
+# Documentation enumerates all relevant files. It excludes vendor and temp
+# directories. It wraps each path in a SourceFile for link extraction.
+#
+# === Example
+#
+#   docs = Documentation.new("/project/root")
+#   docs.each do |file|
+#     file.links.each { |link| puts link.raw }
+#   end
+#   docs.count  # => 392
+#
+class Documentation
+  include Enumerable
+
+  # File extensions to scan for links.
+  EXTENSIONS = %w[rb md rdoc].freeze
+
+  # Directories to skip.
+  EXCLUDES = %w[/vendor/ /tmp/].freeze
+
+  # Creates a new Documentation collection.
+  #
+  # [root] Project root directory to scan.
+  def initialize(root)
+    @root = Pathname.new(root)
+  end
+
+  # Yields each SourceFile in the project.
+  def each(&)
+    files.each(&)
+  end
+
+  private def files # :nodoc:
+    @files ||= EXTENSIONS.flat_map { |ext| glob(ext) }
+  end
+
+  private def glob(extension) # :nodoc:
+    Dir.glob(@root.join("**/*.#{extension}")).filter_map do |path|
+      next if EXCLUDES.any? { |exclude| path.include?(exclude) }
+      SourceFile.new(path, @root)
+    end
+  end
+end

data/tasks/doc/link/file_url.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "../problem"
+
+# A <tt>file://</tt> URL in documentation.
+#
+# IDEs generate these links for local file access. They work on your machine.
+# They break for everyone else. Published docs cannot contain local paths.
+#
+# FileUrl always returns a Problem. There is no valid use case for
+# <tt>file://</tt> URLs in published documentation.
+#
+# === Example
+#
+#   link = FileUrl.new("file:///path/to/file.rb", 10, source_file)
+#   link.problem(root)  # => Problem (always)
+#
+class FileUrl < Link
+  # Returns a Problem. <tt>file://</tt> URLs never work in published docs.
+  #
+  # [_root] Unused. Present for interface compatibility.
+  def problem(_root)
+    Problem.new(self, "file:// URLs won't work when published")
+  end
+end