rigortype 0.1.16 → 0.1.18

data/lib/rigor/cli/options.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/buffer_binding"
+
+module Rigor
+  class CLI
+    # Shared option plumbing for the subcommands.
+    #
+    # Today it owns the editor-mode surface that `rigor check` and
+    # `rigor type-of` both expose: the `--tmp-file` / `--instead-of` flag
+    # pair and the buffer-binding resolution that validates it. That
+    # resolution used to be copied verbatim into both `Rigor::CLI` and
+    # `TypeOfCommand`, so a fix to one (the paired-flag check, the
+    # readability check, the error wording) could silently miss the
+    # other. Centralising it keeps the two editor-mode entry points in
+    # lockstep.
+    module Options
+      module_function
+
+      # Defines the `--tmp-file` / `--instead-of` editor-mode flag pair
+      # on `parser`, writing into `options`.
+      def add_editor_mode(parser, options)
+        parser.on("--tmp-file=PATH",
+                  "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+          options[:tmp_file] = value
+        end
+        parser.on("--instead-of=PATH",
+                  "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+          options[:instead_of] = value
+        end
+      end
+
+      # Resolves the editor-mode buffer binding from parsed `options`:
+      # returns nil when neither editor-mode flag is set, a
+      # `Analysis::BufferBinding` when the pair is valid, or
+      # `:usage_error` (after writing the reason to `err`) when the flags
+      # are unpaired or the temp file is unreadable.
+      def resolve_buffer_binding(options, err:)
+        tmp = options[:tmp_file]
+        instead = options[:instead_of]
+        return nil if tmp.nil? && instead.nil?
+
+        if tmp.nil? || instead.nil?
+          err.puts("--tmp-file and --instead-of must appear together")
+          return :usage_error
+        end
+
+        unless File.file?(tmp)
+          err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+          return :usage_error
+        end
+
+        Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugin_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 module Rigor
   class CLI
     # `rigor plugin` (singular) — discover and read the plugin source
@@ -44,7 +46,7 @@ module Rigor
     # will not resolve — read them from the same environment that ran
     # the command (`rigor plugin print` inlines the body for exactly
     # this case: it works with no file-reading tool at all).
-    class PluginCommand
+    class PluginCommand < Command
       USAGE = <<~USAGE
         Usage: rigor plugin <subcommand> [args]
 
@@ -72,12 +74,6 @@ module Rigor
       PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
       EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         subcommand = @argv.shift || "list"

data/lib/rigor/cli/plugins_command.rb

@@ -9,6 +9,7 @@ require_relative "../plugin/services"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "plugins_renderer"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -60,15 +61,9 @@ module Rigor
     #   the RBS environment without conflict (requires constructing
     #   the Environment, which is heavier than the loader-only
     #   pass this slice does).
-    class PluginsCommand # rubocop:disable Metrics/ClassLength
+    class PluginsCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor plugins [options]"
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/prism_colorizer.rb

@@ -41,12 +41,19 @@ module Rigor
       # @return [String] the source with ANSI colour escapes, or
       #   the input unchanged when lexing surfaces an error.
       def colorize(source)
+        # Sources read under a POSIX locale arrive tagged US-ASCII even
+        # when they carry UTF-8 bytes; retag so the token regexes below
+        # do not raise on multibyte comments.
+        source = source.dup.force_encoding(Encoding::UTF_8) unless source.encoding == Encoding::UTF_8
         result = Prism.lex(source)
         return source unless result.errors.empty?
 
         render(source, result.value)
       end
 
+      # Prism token offsets are BYTE offsets — slice with byteslice, or
+      # any multibyte character earlier in the source shifts every
+      # subsequent token boundary.
       def render(source, lexed)
         out = +""
         offset = 0
@@ -54,15 +61,15 @@ module Rigor
         lexed.each do |entry|
           token = entry.first
           location = token.location
-          out << source[offset...location.start_offset]
+          out << (source.byteslice(offset, [location.start_offset - offset, 0].max) || "")
           break if token.type == :EOF
 
-          text = source[location.start_offset...location.end_offset]
+          text = source.byteslice(location.start_offset, location.end_offset - location.start_offset) || ""
           out << paint(text, effective_category(token.type, previous_type))
           offset = location.end_offset
           previous_type = token.type
         end
-        out << (source[offset..] || "")
+        out << (source.byteslice(offset, source.bytesize - offset) || "")
         out
       end
 

data/lib/rigor/cli/renderable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+module Rigor
+  class CLI
+    # Output-format dispatch shared by the `--format text|json` renderers.
+    #
+    # Each renderer included this and then implemented `render_text` /
+    # `render_json`; the `render(data, format:)` entry point — route by
+    # the format string, raise one consistent `OptionParser::InvalidArgument`
+    # on anything else — was copied verbatim into every one. Centralising
+    # it keeps the unsupported-format wording and the text/json contract
+    # in a single place as new renderers and formats are added.
+    module Renderable
+      def render(data, format:)
+        case format
+        when "text" then render_text(data)
+        when "json" then render_json(data)
+        else
+          raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/sig_gen_command.rb

@@ -4,6 +4,7 @@ require "optionparser"
 
 require_relative "../configuration"
 require_relative "../sig_gen"
+require_relative "command"
 
 module Rigor
   class CLI
@@ -34,19 +35,13 @@ module Rigor
     # `--params=observed-strict` stays reserved-but-inert until
     # the capability-role catalog ships (rejected with a usage
     # error so the surface stays stable).
-    class SigGenCommand
+    class SigGenCommand < Command
       USAGE = "Usage: rigor sig-gen [options] [paths]"
 
       VALID_MODES = %w[print diff write].freeze
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
-      def initialize(argv:, out:, err:)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         options = parse_options

data/lib/rigor/cli/skill_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 require "optparse"
 
 module Rigor
@@ -29,7 +31,7 @@ module Rigor
     #                                as input to a Read tool.
     #
     # `rigor skill` with no subcommand is an alias for `list`.
-    class SkillCommand
+    class SkillCommand < Command
       USAGE = <<~USAGE
         Usage: rigor skill <subcommand> [args]
 
@@ -48,12 +50,6 @@ module Rigor
       # `lib/rigor/cli/skill_command.rb` that is three directories up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
-      def initialize(argv:, out: $stdout, err: $stderr)
-        @argv = argv
-        @out = out
-        @err = err
-      end
-
       # @return [Integer] CLI exit status.
       def run
         subcommand = @argv.shift || "list"

data/lib/rigor/cli/trace_command.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+require "prism"
+
+require_relative "../configuration"
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../inference/flow_tracer"
+require_relative "../inference/scope_indexer"
+require_relative "command"
+require_relative "trace_renderer"
+
+module Rigor
+  class CLI
+    # Executes the `rigor trace` command: re-runs the inference engine
+    # over one file under {Rigor::Inference::FlowTracer} and replays the
+    # recorded event stream — scope binds, union formation, method
+    # dispatch, and (with `--verbose`) every expression enter/result —
+    # as a step-through terminal animation. A teaching probe: it shows
+    # HOW Rigor arrives at a type, where `rigor type-of` shows only the
+    # answer.
+    #
+    # The tracer is observational; this command never changes what
+    # `rigor check` would infer for the same file.
+    class TraceCommand < Command
+      USAGE = "Usage: rigor trace [options] FILE"
+
+      # Default frame kinds: the three teachable moments. :enter/:result
+      # add one frame per literal and drown the signal; `--verbose`
+      # opts into them.
+      DEFAULT_KINDS = %i[bind union dispatch].freeze
+      VERBOSE_KINDS = (%i[enter result] + DEFAULT_KINDS).freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        file = @argv.first
+        if file.nil? || @argv.size != 1
+          @err.puts(USAGE)
+          return CLI::EXIT_USAGE
+        end
+        return 1 unless file_exists?(file)
+
+        execute(file: file, options: options)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", delay: nil, verbose: false, line: nil, config: nil }
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text (animation) or json (raw event stream)") do |value|
+            options[:format] = value
+          end
+          opts.on("--delay=SECONDS", Float,
+                  "Autoplay with SECONDS between frames (default: step on key press)") do |value|
+            options[:delay] = value
+          end
+          opts.on("--line=N", Integer, "Only replay events whose source range starts on line N") do |value|
+            options[:line] = value
+          end
+          opts.on("--verbose", "Include every expression enter/result frame") { options[:verbose] = true }
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def execute(file:, options:)
+        configuration = Configuration.load(options.fetch(:config))
+        source = File.read(file, encoding: Encoding::UTF_8)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
+        return 1 if parse_errors?(parse_result, file)
+
+        events = record_events(parse_result.value, file, configuration)
+        frames = filter(events, options)
+
+        if options.fetch(:format) == "json"
+          @out.puts(JSON.pretty_generate(frames.map { |event| event_to_h(event) }))
+          return 0
+        end
+
+        if frames.empty?
+          @out.puts("trace: no events to replay (try --verbose)")
+          return 0
+        end
+
+        interactive = @out.respond_to?(:tty?) && @out.tty?
+        TraceRenderer.new(out: @out, source: source, file: file)
+                     .play(frames, delay: options.fetch(:delay), interactive: interactive)
+        0
+      end
+
+      # Mirrors the single-file path `rigor type-of` takes: a
+      # project-aware environment, an empty seed scope, one
+      # statement-level evaluation of the whole program — but recorded
+      # under the FlowTracer.
+      def record_events(root, file, configuration)
+        environment = Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
+        scope = Scope.empty(environment: environment, source_path: file)
+        Inference::FlowTracer.record { scope.evaluate(root) }
+      end
+
+      def filter(events, options)
+        kinds = options.fetch(:verbose) ? VERBOSE_KINDS : DEFAULT_KINDS
+        frames = events.select { |event| kinds.include?(event.kind) }
+        line = options.fetch(:line)
+        frames = frames.select { |event| event.location && event.location[:start_line] == line } if line
+        frames
+      end
+
+      def event_to_h(event)
+        {
+          kind: event.kind,
+          depth: event.depth,
+          location: event.location,
+          stack: event.stack,
+          data: event.data
+        }
+      end
+
+      def file_exists?(file)
+        return true if File.file?(file)
+
+        @err.puts("trace: file not found: #{file}")
+        false
+      end
+
+      def parse_errors?(result, file)
+        return false if result.errors.empty?
+
+        result.errors.each { |error| @err.puts("#{file}:#{error.location.start_line}: #{error.message}") }
+        true
+      end
+    end
+  end
+end

data/lib/rigor/cli/trace_renderer.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require_relative "prism_colorizer"
+
+module Rigor
+  class CLI
+    # Replays a `Rigor::Inference::FlowTracer` event stream as a terminal
+    # animation for `rigor trace`. Each frame draws a box-drawn screen:
+    # the source panel (syntax-coloured, current node range underlined)
+    # side-by-side with the scope panel (locals accumulated from :bind
+    # events), and an event panel describing the current step and the
+    # expression stack.
+    #
+    # The frame is fitted to the measured terminal: the source panel
+    # scrolls vertically (a window centred on the line under evaluation)
+    # instead of overflowing the screen height, over-long rows are
+    # clipped with an ellipsis instead of wrapping, and the event panel
+    # keeps a minimum height of {EVENT_PANE_MIN} rows so the narration
+    # never collapses to a sliver.
+    #
+    # Pure ANSI + `io/console` (both stdlib) per ADR-0's zero-runtime-
+    # dependency policy. When the output is not a TTY the frames are
+    # printed sequentially without cursor control against a default
+    # 80×24 layout, which keeps the renderer deterministic under test.
+    class TraceRenderer
+      RESET = "\e[0m"
+      DIM = "\e[90m"
+      BOLD = "\e[1m"
+      HIGHLIGHT = "\e[7m" # reverse video for the frame's source range
+
+      EVENT_PANE_MIN = 2     # minimum event-panel rows
+      SCOPE_WIDTH_MIN = 19   # minimum scope-column width
+      BODY_HEIGHT_MIN = 3    # never shrink the source window below this
+      DEFAULT_SIZE = [24, 80].freeze
+
+      # @param out [IO]
+      # @param source [String] the traced file's source.
+      # @param file [String] display path.
+      def initialize(out:, source:, file:)
+        @out = out
+        @source = source
+        @file = file
+        @lines = source.lines.map(&:chomp)
+      end
+
+      # @param events [Array<Rigor::Inference::FlowTracer::Event>] the
+      #   pre-filtered frame list (the command owns kind filtering).
+      # @param delay [Float, nil] seconds between frames (autoplay);
+      #   nil = step on key press when interactive.
+      # @param interactive [Boolean] whether to clear/redraw and wait.
+      def play(events, delay: nil, interactive: false)
+        @rows, @cols = interactive ? terminal_size : DEFAULT_SIZE
+        @interactive = interactive
+        locals_per_frame = accumulate_locals(events)
+        events.each_with_index do |event, index|
+          @out.print("\e[H\e[2J") if interactive
+          render_frame(event, index: index, total: events.size, locals: locals_per_frame[index])
+          @out.puts unless interactive
+          next if index == events.size - 1
+
+          if delay
+            sleep(delay)
+          elsif interactive
+            break unless next_frame?
+          end
+        end
+      end
+
+      private
+
+      # `IO.console` reflects the controlling terminal even when stdout
+      # is, say, a StringIO under test — which is why the measured size
+      # is only used for interactive replays.
+      def terminal_size
+        require "io/console"
+        size = IO.console&.winsize
+        return size if size && size[0].positive? && size[1].positive?
+
+        DEFAULT_SIZE
+      rescue LoadError, SystemCallError
+        DEFAULT_SIZE
+      end
+
+      # Replays :bind events into a per-frame snapshot of the locals
+      # panel, so frame N shows exactly the bindings visible after the
+      # first N events.
+      def accumulate_locals(events)
+        locals = {}
+        events.map do |event|
+          locals[event.data[:name]] = event.data[:type] if event.kind == :bind
+          locals.dup
+        end
+      end
+
+      def render_frame(event, index:, total:, locals:)
+        inner = @cols - 3 # three vertical borders
+        lines = event_pane_lines(event, inner - 1)
+        body_height = body_height_for(lines.size)
+
+        source_rows = source_panel_rows(event)
+        left_width, right_width = column_widths(source_rows, inner)
+        source_rows = clip_rows(scroll_window(source_rows, body_height), left_width)
+        scope_rows = fit_rows(scope_panel_rows(locals), body_height, right_width)
+
+        @out.puts(top_border(left_width, right_width))
+        body_rows(source_rows, scope_rows, left_width, right_width)
+        @out.puts(divider(left_width, right_width, label: " step #{index + 1}/#{total} · #{event.kind} "))
+        lines.each { |line| @out.puts(boxed_line(line, left_width + right_width + 1)) }
+        @out.puts(bottom_border(left_width + right_width + 1))
+      end
+
+      # Screen budget: borders (3 rows) + event pane + the key-hint row
+      # when stepping interactively; whatever remains belongs to the
+      # source/scope body, floored at {BODY_HEIGHT_MIN}.
+      def body_height_for(event_rows)
+        chrome = 3 + event_rows + (@interactive ? 1 : 0)
+        [@rows - chrome, BODY_HEIGHT_MIN].max
+      end
+
+      # The event pane keeps at least {EVENT_PANE_MIN} rows (padding with
+      # blanks) so the bottom of the frame is visually stable across
+      # event kinds; over-long lines are clipped to the frame width.
+      def event_pane_lines(event, max_width)
+        lines = [describe_event(event), stack_line(event)].compact
+        lines << "" while lines.size < EVENT_PANE_MIN
+        lines.map { |line| clip(line, max_width) }
+      end
+
+      # Source rows win the width contest; the scope column keeps its
+      # minimum and absorbs whatever the source does not need.
+      def column_widths(source_rows, inner)
+        left_need = (source_rows.map { |raw, _| raw.length }.max || 0) + 1
+        left_width = left_need.clamp(24, [inner - SCOPE_WIDTH_MIN, 24].max)
+        [left_width, [inner - left_width, SCOPE_WIDTH_MIN].max]
+      end
+
+      # Vertical scroll: when the panel is taller than the window, keep
+      # a slice centred on the row under evaluation (the `▶` row, which
+      # the marker row directly follows).
+      def scroll_window(rows, height)
+        return rows if rows.size <= height
+
+        focus = rows.index { |raw, _| raw.start_with?("▶") } || 0
+        start = (focus - (height / 2)).clamp(0, rows.size - height)
+        rows[start, height]
+      end
+
+      def clip_rows(rows, width)
+        rows.map do |raw, painted|
+          next [raw, painted] if raw.length <= width
+
+          # Re-paint from the clipped raw text — clipping the painted
+          # string directly would cut ANSI escapes in half.
+          clipped = clip(raw, width)
+          [clipped, repaint_clipped(clipped)]
+        end
+      end
+
+      # A clipped row loses its highlight/marker alignment guarantees, so
+      # it is repainted with plain syntax colouring (gutter dimmed).
+      def repaint_clipped(clipped)
+        gutter = clipped[0, 6]
+        rest = clipped[6..] || ""
+        DIM + gutter + RESET + PrismColorizer.colorize(rest).chomp
+      end
+
+      def fit_rows(rows, height, width)
+        rows = rows[0, height - 1] + ["  … (+#{rows.size - height + 1} more)"] if rows.size > height
+        rows.map { |row| clip(row, width) }
+      end
+
+      def clip(text, width)
+        return text if text.length <= width
+
+        "#{text[0, [width - 1, 0].max]}…"
+      end
+
+      # Each row is `[raw_text, painted_text]` so width math runs on the
+      # escape-free string. The row under the event's source range gets a
+      # `▔▔▔` marker row injected after it.
+      def source_panel_rows(event)
+        rows = []
+        location = event.location
+        @lines.each_with_index do |line, i|
+          number = i + 1
+          current = location && number == location[:start_line]
+          gutter = "#{current ? '▶' : ' '}#{number.to_s.rjust(3)}  "
+          raw = gutter + line
+          painted = (current ? BOLD + gutter + RESET : DIM + gutter + RESET) + paint_line(line, location, number)
+          rows << [raw, painted]
+          rows << marker_row(gutter.length, line, location) if current
+        end
+        rows
+      end
+
+      def marker_row(gutter_width, line, location)
+        before, slice, = split_at_range(line, location)
+        indent = " " * (gutter_width + before.length)
+        width = [slice.length, 1].max
+        [indent + ("▔" * width), indent + BOLD + ("▔" * width) + RESET]
+      end
+
+      # Highlights the in-range slice with reverse video; everything else
+      # gets Prism syntax colouring. The highlight is applied on the raw
+      # slice (not the colorized string) so byte offsets stay honest.
+      def paint_line(line, location, number)
+        return PrismColorizer.colorize(line) unless location && number == location[:start_line]
+
+        before, slice, after = split_at_range(line, location)
+        return PrismColorizer.colorize(line) if slice.empty?
+
+        PrismColorizer.colorize(before).chomp +
+          HIGHLIGHT + slice + RESET +
+          PrismColorizer.colorize(after).chomp
+      end
+
+      # Prism columns are BYTE columns — split the line with byteslice
+      # so a multibyte character earlier on the line cannot shift (or
+      # overrun) the highlight range. Returns `[before, slice, after]`.
+      def split_at_range(line, location)
+        from = [location[:start_column], line.bytesize].min
+        to = location[:end_line] == location[:start_line] ? [location[:end_column], line.bytesize].min : line.bytesize
+        to = from if to < from
+        [line.byteslice(0, from), line.byteslice(from, to - from), line.byteslice(to, line.bytesize - to) || ""]
+      end
+
+      def scope_panel_rows(locals)
+        return [" (no locals yet)"] if locals.empty?
+
+        width = locals.keys.map(&:length).max
+        locals.map { |name, type| format(" %-#{width}s : %s", name, type) }
+      end
+
+      def describe_event(event)
+        data = event.data
+        case event.kind
+        when :bind then "bind     #{data[:name]} ← #{data[:type]}"
+        when :union then "union    #{data[:members].join(' | ')}  →  #{data[:type]}"
+        when :dispatch then describe_dispatch(data)
+        when :enter then "eval     #{data[:node]}"
+        when :result then "result   #{data[:node]}  →  #{data[:type]}"
+        else "#{event.kind}  #{data.inspect}"
+        end
+      end
+
+      def describe_dispatch(data)
+        call = "#{data[:receiver]} ##{data[:method]}(#{data[:args].join(', ')})"
+        return "dispatch #{call}  →  #{data[:type]}" if data[:resolved]
+
+        "dispatch #{call}  →  no rule matched (fail-soft → Dynamic[top])"
+      end
+
+      def stack_line(event)
+        return nil if event.stack.empty?
+
+        "stack    #{event.stack.join(' › ')}"
+      end
+
+      # -- box drawing ---------------------------------------------------
+
+      def top_border(left, right)
+        "┌#{pad_label("─ #{@file} ", left)}┬#{pad_label('─ scope ', right)}┐"
+      end
+
+      # Pads `label` with `─` to exactly `width` cells (truncating an
+      # over-long label so the frame never breaks).
+      def pad_label(label, width)
+        label = "#{label[0, width - 2]} " if label.length > width
+        label + ("─" * [width - label.length, 0].max)
+      end
+
+      def body_rows(source_rows, scope_rows, left, right)
+        [source_rows.size, scope_rows.size].max.times do |i|
+          raw, painted = source_rows[i] || ["", ""]
+          scope = scope_rows[i] || ""
+          @out.puts("│#{painted}#{' ' * [left - raw.length, 0].max}│#{scope}#{' ' * [right - scope.length, 0].max}│")
+        end
+      end
+
+      def divider(left, right, label:)
+        "├#{pad_label(label, left)}┴#{'─' * right}┤"
+      end
+
+      def boxed_line(text, width)
+        "│ #{text}#{' ' * [width - text.length - 1, 0].max}│"
+      end
+
+      def bottom_border(width)
+        "└#{'─' * width}┘"
+      end
+
+      # Single-keystroke stepping via stdlib io/console; falls back to
+      # line-buffered Enter when raw mode is unavailable (e.g. pipes that
+      # still claim to be TTYs). Returns false when the user quits.
+      def next_frame?
+        @out.print("#{DIM}  [any key: next · q: quit]#{RESET}")
+        key = read_key
+        @out.print("\r\e[K")
+        key != "q"
+      end
+
+      def read_key
+        require "io/console"
+        $stdin.getch
+      rescue LoadError, Errno::ENOTTY, Errno::ENODEV
+        $stdin.gets&.strip
+      end
+    end
+  end
+end