potty 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 025204ee0b4853237fc9ea15a4714261d6583e827077cc38fd34dbe635f186c6
+  data.tar.gz: ffc7a323d75589bbf073a70b136aec36f65a1a4ce4126d9c7a7986cabe484672
+SHA512:
+  metadata.gz: b0534b15973e60c6fde7848fd7ff1d93db9e47f7f2b8bb3fa3b6e24cedefa36dfffb1c6c22b6d9fdc8e43a174a50be526c5b82cbb20793dfa9d772ff65d3bbda
+  data.tar.gz: 1863a5f74f255b034dcb1f86dd23067c3823be15967f359249cc1d4f6c3b0ab54a959c7b18221c3a82c45f4cf573cf483ef63425cdef0196f734d0a2ce24da59

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to potty are documented here. The format is loosely based
+on [Keep a Changelog](https://keepachangelog.com/), and the project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.0.1] - 2026-05-30
+
+Initial public release. (Developed privately under the working name `cursed`,
+which was already taken on RubyGems; renamed to `potty` for release.)
+
+### Added
+- **Application / View / Widget framework** — a view stack with push/pop
+  navigation, focus cycling (Tab/Shift+Tab, recursing into containers), a tick
+  loop for time-driven widgets, and suspend/resume.
+- **Render-target Surface abstraction** — the same widget tree renders to a
+  full-screen curses display (`:curses`, default) or an inline ANSI region
+  redrawn in place under the cursor (`:inline`), via `Application.new(mode:)`.
+- **Composition** — `Container`, `VBox`, `HBox`, and bordered `Panel`, with a
+  shared `Border` helper (single/rounded/double/heavy).
+- **Widgets** — `List` (+ `ActionItem`/`SeparatorItem`/`InputItem`/
+  `ColoredFieldsItem`), `Label`, `Button`, `TextInput`, `Toggle`, `RadioGroup`,
+  `CheckboxGroup`, `Spinner`, `Countdown`, `FlashMessage`, `StatusBar`,
+  `ProgressBar`.
+- **Animation** — `Sprite` + `Animator` (loop/once, fps, on_complete).
+- **Events** — an `on`/`emit` mixin so widgets emit semantic events
+  (`:change`, `:press`, `:select`, `:focus`, `:complete`, `:expire`).
+- **Theming** — a semantic palette (`theme.style`) resolved per surface;
+  transparent (terminal-default) backgrounds; injectable custom palette.
+- **`Keys`** — named key codes with `getch` String/Integer normalization.
+- A self-demonstrating `bin/potty_demo`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TwilightCoders
+
+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,270 @@
+# potty
+
+A curses-based terminal UI framework for Ruby. Build full-screen TUIs from a
+tree of composable widgets, with view-stack navigation, a focus model, theming,
+and frame-based animation.
+
+```
+┌─────────────────────────────────┐
+│ → Say hello                     │
+│   Configure                     │
+│   Quit                          │
+└─────────────────────────────────┘
+ ↑↓: Navigate         HELLO         ESC: Quit
+```
+
+> **Status:** early release (`0.0.1`). The API is young and evolving under real
+> consumers. Expect additive change.
+
+## Installation
+
+Requires the `curses` gem (a native extension) and a real terminal. Not yet
+published to RubyGems — depend on it via git or a local path:
+
+```ruby
+# Gemfile
+gem 'potty', github: 'TwilightCoders/potty'
+# or, for local development:
+gem 'potty', path: '../potty'
+```
+
+```ruby
+require 'potty'
+```
+
+## Quick start
+
+A `Potty::Application` runs a stack of `Potty::View`s. A view builds a tree of
+widgets in `build_layout` and reacts to input. Subclass `View`, hand the app a
+root view, and call `run`:
+
+```ruby
+require 'potty'
+
+class HelloView < Potty::View
+  def build_layout
+    @flash = Potty::Widgets::FlashMessage.new(app)
+
+    @list = Potty::Widgets::List.new(app)
+    @list.items = [
+      Potty::Widgets::ActionItem.new('Say hello') { flash_success('Hello!') },
+      Potty::Widgets::ActionItem.new('Quit')      { app.quit }
+    ]
+
+    @status = Potty::Widgets::StatusBar.new(app)
+    @status.left_text   = '↑↓: Navigate'
+    @status.center_text = 'HELLO'
+    @status.right_text  = 'ESC: Quit'
+
+    @widgets = [@flash, @list, @status]
+    @list.focus
+  end
+
+  def handle_escape
+    app.quit
+    true
+  end
+end
+
+app = Potty::Application.new
+app.run(HelloView.new(app))
+```
+
+For a guided tour of the whole widget set, run the bundled demo in a real
+terminal:
+
+```bash
+bin/potty_demo     # from a checkout
+potty_demo         # when the gem is installed
+```
+
+It's a single self-demonstrating dashboard: one composed layout (so it shows
+off the layout system by *being* it) whose form controls reconfigure the demo
+live — the Border radio restyles the very panels you're looking at, the Title
+field renames the header, the checkboxes show/hide the live animation. See
+[`examples/test_view.rb`](examples/test_view.rb) for a smaller example.
+
+## Core concepts
+
+### Application
+
+`Potty::Application` owns the curses lifecycle and the event loop.
+
+- `run(root_view)` — set up curses, push the root view, loop until `quit`.
+- `push_view(view)` / `pop_view` — navigate a stack of views (e.g. drilling
+  into a submenu and back). ESC pops by default unless the view's
+  `handle_escape` consumes it.
+- `quit` — stop the loop.
+- `suspend` / `resume` — tear down and rebuild curses so you can shell out to an
+  external process (an editor, a pager) and come back cleanly.
+- `tick_interval=` — see [Animation & ticking](#animation--ticking).
+
+### View
+
+Subclass `Potty::View` and override:
+
+- `build_layout` — construct widgets into `@widgets` and call `focus` on the
+  initial one. Called once at construction.
+- `handle_escape` — return `true` to consume ESC (e.g. `app.quit` or a confirm),
+  `false` to let the app pop the view.
+- optionally `on_activate` / `on_deactivate` — run when the view becomes
+  (in)active on the stack; a good place to rebuild dynamic lists.
+
+The view routes keys to the focused widget first, then cycles focus with
+**Tab / Shift+Tab** across widgets whose `can_focus?` is true (recursing into
+containers). `flash_success`, `flash_error`, and `flash_info` post messages to a
+`FlashMessage` widget in the tree. Widgets are laid out top-to-bottom by
+[`Layout`](#layout), unless you nest them in [containers](#containers--composition).
+
+### Events
+
+Every widget mixes in `Potty::Events`, so you can wire a UI together
+declaratively instead of subclassing for one-off behavior. Widgets emit semantic
+events; subscribe with `on`:
+
+```ruby
+name.on(:change)   { |text| greeting.text = "Hello, #{text}" }
+notify.on(:change) { |on|   features.visible = on }
+save.on(:press)    { app.pop_view }
+```
+
+Emitted events: `:focus`/`:blur` (any widget), `:change` (`TextInput`, `Toggle`,
+`RadioGroup`, `CheckboxGroup`), `:select`/`:activate` (`List`), `:press`
+(`Button`), `:expire` (`Countdown`), `:complete` (`Animator`, `Spinner`). `on`
+returns self and supports multiple listeners. Keys are named in `Potty::Keys`
+(`ENTER`, `ESC`, `TAB`, `UP`, …) — no magic integers in your `handle_key`.
+
+### Containers & composition
+
+A `View`'s `@widgets` is laid out as a vertical stack, but any entry can be a
+container holding more widgets — so you get nesting, columns, and framed panels.
+Render, tick, and focus traversal all recurse.
+
+- **`VBox`** / **`HBox`** — vertical stack / equal-width columns (`spacing:`).
+- **`Panel`** — bordered, optionally titled container (`title:`, `style:`,
+  `color:`) that insets its children.
+
+```ruby
+Potty::Widgets::Panel.new(app, title: 'Settings').add(
+  Potty::Widgets::Label.new(app, text: 'Name'),
+  Potty::Widgets::TextInput.new(app),
+  Potty::Widgets::Button.new(app, label: 'Save')
+)
+```
+
+### Widgets
+
+Every widget inherits `Potty::Widgets::Base` and implements as much of this
+contract as it needs:
+
+| Method | Purpose |
+| --- | --- |
+| `preferred_height(width)` | rows the widget wants (drives stack layout) |
+| `layout(rect)` / `on_layout` | receive assigned position+size |
+| `render(window)` | draw onto the curses window |
+| `handle_key(ch)` | handle input; return `true` if consumed |
+| `tick(now)` | per-frame update (time-driven widgets only) |
+| `can_focus?` / `focus` / `blur` | focus participation |
+| `show` / `hide` | visibility |
+
+#### Widget catalog
+
+- **`List`** — scrollable list of heterogeneous `ListItem`s. Delegates unhandled
+  keys to the selected item (how `InputItem` captures typing). Item types:
+  `ActionItem` (callback on Enter), `DisabledItem` / `SeparatorItem` (skipped by
+  selection), `InputItem` (inline editable row), and `ColoredFieldsItem`
+  (multi-color segments via `render_custom`).
+- **`Label`** — static, non-focusable single-line text. `text:`, `color:`,
+  `bold:`.
+- **`Button`** — focusable; Space/Enter emits `:press`. `on_press:` shortcut.
+- **`TextInput`** — single-line editable field. Block cursor when focused, dim
+  placeholder, horizontal scroll. `text` / `text=`, `placeholder`,
+  `max_length`, emits `:change` (snapshot). ASCII input.
+- **`Toggle`** — boolean `[●]`/`[○]`; Space/Enter flips. `value` / `value=`,
+  `label`, emits `:change`.
+- **`RadioGroup`** — N mutually exclusive `{value, label}` options; arrows move a
+  cursor, Space/Enter commits. `selected` / `selected=`, emits `:change`.
+- **`CheckboxGroup`** — multi-select sibling of `RadioGroup`; Space/Enter toggles
+  the cursor row. `selected`, `selected?`, emits `:change` (selected values).
+- **`Spinner`** — single-line activity indicator: animated braille glyph + live
+  `label` + trailing state. `complete!(:success/:failure/:cancelled)` freezes the
+  glyph and flips color (idempotent); emits `:complete`. Tick-driven.
+- **`Countdown`** — passive display counting down N seconds, emits `:expire`.
+  Tick-driven (see below).
+- **`FlashMessage`** — transient success/error/warning/info banner with timeout.
+- **`StatusBar`** — bottom bar with `left_text` / `center_text` / `right_text`.
+- **`ProgressBar`** — pure-string bar using Unicode eighth-blocks for sub-cell
+  resolution; `render(0.0..1.0)` returns a string (usable on a curses window or
+  plain stdout).
+
+### Layout
+
+`Potty::Layout` is pure geometry over a `Rect(x, y, width, height)`:
+
+- `Layout.stack(container, widgets, spacing:)` — vertical stack (the default a
+  view uses), querying each widget's `preferred_height`.
+- `Layout.split_horizontal(container, ratio:)` — left/right split.
+- `Layout.fill(container)` — full container.
+
+### Theme
+
+`Potty::Theme` maps semantic names to curses color pairs: `:normal`,
+`:selected`, `:disabled`, `:success`, `:error`, `:warning`, `:info`, `:dim`,
+`:header`, `:status`.
+
+```ruby
+theme[:error]                       # color-pair attr
+theme.attr(:selected, bold: true)   # attr with A_BOLD / A_UNDERLINE OR'd in
+```
+
+## Animation & ticking
+
+The event loop normally blocks on input. To drive animations and countdowns,
+give the app a tick interval — the loop then wakes every N milliseconds, fans a
+single shared `Time.now` out to every widget's `tick(now)`, and repaints.
+
+```ruby
+app = Potty::Application.new
+app.tick_interval = 40   # ms; ≈25fps. nil (default) = blocking, input-only.
+app.run(view)
+```
+
+`Potty::Sprite` is a named sequence of multiline-string frames; `Potty::Animator`
+is a widget that plays sprites by elapsed-time / fps, with `:loop` and `:once`
+modes (`:once` fires `on_complete`).
+
+```ruby
+class LoaderView < Potty::View
+  def build_layout
+    @spinner = Potty::Animator.new(app, centered: true, color: :info)
+    @spinner << Potty::Sprites::Sample.spinner   # first sprite auto-plays
+    @label   = Potty::Widgets::Label.new(app, text: 'Loading…', color: :info)
+    @widgets = [@spinner, @label]
+  end
+end
+
+app = Potty::Application.new
+app.tick_interval = 40
+app.run(LoaderView.new(app))
+```
+
+`add_sprite` (`<<`) registers more sprites; `play(:name)` swaps and restarts.
+Define your own `Sprite.new(:name, frames: [...], fps:, mode:)`;
+`Potty::Sprites::Sample` (`spinner`, `plane`) is a template to copy.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec                       # full suite
+bundle exec rspec spec/potty/animator_spec.rb:42   # a single example
+ruby examples/test_view.rb              # interactive demo (needs a real TTY)
+```
+
+Tests cover the pure-logic surface — input handling, frame timing (via an
+injected clock), layout, rendering assertions through fake windows — so the
+suite runs without `init_screen` or a real terminal.
+
+## License
+
+MIT.

data/bin/potty_demo

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# potty_demo - a self-demonstrating dashboard. Run it in a real terminal:
+#   bin/potty_demo        (from a checkout)
+#   potty_demo            (when the gem is installed)
+#
+# It's meta: the whole screen is one composed layout (so it demonstrates the
+# layout system by *being* it), and the form widgets on the left are wired to
+# reconfigure the demo itself live - the Border radio restyles the very panels
+# you're looking at, the Title field renames the header, the checkboxes show or
+# hide the live widgets on the right.
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'potty'
+
+module PottyDemo
+  class Dashboard < Potty::View
+    BORDER_STYLES = %i[single rounded double heavy].freeze
+
+    def build_layout
+      @flash  = Potty::Widgets::FlashMessage.new(app)
+      @header = Potty::Widgets::Label.new(app, text: header_for(''), color: :header, bold: true)
+
+      build_controls
+      build_live
+      wire_events
+
+      @controls_panel = Potty::Widgets::Panel.new(app, title: 'Controls', color: :info).add(
+        Potty::Widgets::Label.new(app, text: 'Title', color: :dim),  @title_in,
+        Potty::Widgets::Label.new(app, text: 'Border', color: :dim), @style_rg,
+        @animate,
+        Potty::Widgets::Label.new(app, text: 'Show', color: :dim),   @show,
+        @salute
+      )
+      @live_panel = Potty::Widgets::Panel.new(app, title: 'Live', color: :info).add(@anim, @spin, @clock)
+      @columns = Potty::Widgets::HBox.new(app, spacing: 1).add(@controls_panel, @live_panel)
+
+      @status = Potty::Widgets::StatusBar.new(app)
+      @status.left_text   = 'Tab: field   Space/Enter: act'
+      @status.center_text = 'CURSED'
+      @status.right_text  = 'ESC: quit'
+
+      @widgets = [@flash, @header, @columns, @status]
+      @title_in.focus
+    end
+
+    def handle_escape
+      app.quit
+      true
+    end
+
+    private
+
+    def build_controls
+      @title_in = Potty::Widgets::TextInput.new(app, placeholder: 'name this demo')
+      @style_rg = Potty::Widgets::RadioGroup.new(app,
+        options: BORDER_STYLES.map { |s| { value: s, label: s.to_s } })
+      @animate  = Potty::Widgets::Toggle.new(app, label: 'Fly the plane', value: true)
+      @show     = Potty::Widgets::CheckboxGroup.new(app,
+        options: [{ value: :anim, label: 'Animation' },
+                  { value: :spin, label: 'Spinner' },
+                  { value: :clock, label: 'Countdown' }],
+        selected: %i[anim spin clock])
+      @salute   = Potty::Widgets::Button.new(app, label: 'Salute', color: :success)
+    end
+
+    def build_live
+      @anim = Potty::Animator.new(app, color: :info, centered: true)
+      @anim << Potty::Sprites::Sample.plane     # plays once, then loops the spinner
+      @anim << Potty::Sprites::Sample.spinner
+      @anim.on(:complete) { @anim.play(:spinner) }
+
+      @spin  = Potty::Widgets::Spinner.new(app, label: 'rendering frames', prefix: '')
+      @clock = Potty::Widgets::Countdown.new(app, seconds: 9,
+        format: ->(r) { "auto-salute in #{r}s" })
+    end
+
+    # Every control reconfigures the demo you're looking at.
+    def wire_events
+      @title_in.on(:change) { |t| @header.text = header_for(t) }
+
+      @style_rg.on(:change) do |style|
+        [@controls_panel, @live_panel].each { |p| p.style = style }
+        flash_info("border: #{style}")
+      end
+
+      @animate.on(:change) { |on| on ? @anim.resume : @anim.stop }
+
+      @show.on(:change) do |sel|
+        @anim.visible  = sel.include?(:anim)
+        @spin.visible  = sel.include?(:spin)
+        @clock.visible = sel.include?(:clock)
+      end
+
+      @salute.on(:press) { salute! }
+      @clock.on(:expire) { salute!; @clock.start } # recurring
+    end
+
+    def salute!
+      @anim.play(:plane)
+      flash_success('o7')
+    end
+
+    def header_for(title)
+      title = title.strip
+      base = title.empty? ? 'a TUI kit that demos itself' : title
+      "potty - #{base}"
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  begin
+    app = Potty::Application.new
+    app.tick_interval = 40 # ~25fps so animation/countdown advance
+    app.run(PottyDemo::Dashboard.new(app))
+  rescue Interrupt
+    puts "\nInterrupted."
+    exit 130
+  rescue StandardError => e
+    warn "Error: #{e.message}"
+    warn e.backtrace if ENV['DEBUG']
+    exit 1
+  end
+end

data/examples/test_view.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../lib/potty'
+
+module Potty
+  module Examples
+    # Simple test view to verify curses setup
+    class TestView < Potty::View
+      def build_layout
+        @flash = Widgets::FlashMessage.new(app)
+
+        @list = Widgets::List.new(app)
+        @list.items = build_test_items
+        @list.on_activate = proc { |item| handle_activation(item) }
+
+        @status = Widgets::StatusBar.new(app)
+        @status.left_text = "\u2191\u2193: Navigate"
+        @status.center_text = "CURSES TEST"
+        @status.right_text = "ESC: Quit"
+
+        @widgets = [@flash, @list, @status]
+        @list.focus
+      end
+
+      def build_test_items
+        items = []
+
+        items << Widgets::SeparatorItem.new("\u2501\u2501 TEST ITEMS \u2501\u2501")
+
+        items << Widgets::ActionItem.new("Show success message") do
+          flash_success("This is a success message!")
+        end
+
+        items << Widgets::ActionItem.new("Show error message") do
+          flash_error("This is an error message!")
+        end
+
+        items << Widgets::ActionItem.new("Show info message") do
+          flash_info("This is an info message!")
+        end
+
+        items << Widgets::SeparatorItem.new
+
+        items << Widgets::DisabledItem.new("This item is disabled")
+
+        items << Widgets::SeparatorItem.new("\u2501\u2501 INPUT TEST \u2501\u2501")
+
+        items << Widgets::InputItem.new("Type something", default: "") do |value|
+          flash_success("You typed: #{value}")
+        end
+
+        items << Widgets::SeparatorItem.new
+
+        items << Widgets::ActionItem.new("Quit application") do
+          app.quit
+        end
+
+        items
+      end
+
+      def handle_activation(item)
+        # Item handles its own activation
+      end
+
+      def handle_escape
+        app.quit
+        true
+      end
+    end
+  end
+end
+
+# Run the test if executed directly
+if __FILE__ == $0
+  begin
+    app = Potty::Application.new
+    root_view = Potty::Examples::TestView.new(app)
+    app.run(root_view)
+  rescue Interrupt
+    puts "\nInterrupted. Exiting..."
+    exit 130
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+    puts e.backtrace if ENV['DEBUG']
+    exit 1
+  end
+end

data/lib/potty/animator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'widgets/base'
+require_relative 'sprite'
+
+module Potty
+  # Frame-based animation widget. Holds one or more named Sprites and
+  # advances the active one at its fps on each tick. Being a Widget, it
+  # composes into a View tree like anything else.
+  #
+  # Playback is time-driven: tick(now) advances the frame only when enough
+  # wall-clock time has elapsed for the active sprite's fps. The Application
+  # event loop supplies `now`; tests can supply it too, which makes the whole
+  # thing deterministic.
+  class Animator < Widgets::Base
+    attr_reader :current, :frame_index
+    attr_accessor :color, :on_complete, :centered
+
+    def initialize(app, color: :normal, centered: false)
+      super(app)
+      @sprites = {}
+      @current = nil          # active sprite name (Symbol)
+      @frame_index = 0
+      @last_advance = nil     # Time of the last frame advance
+      @playing = false
+      @color = color
+      @centered = centered
+      @on_complete = nil      # called with self when a :once sprite finishes
+    end
+
+    # Register a sprite. The first one added becomes active and starts playing.
+    def add_sprite(sprite)
+      @sprites[sprite.name] = sprite
+      play(sprite.name) if @current.nil?
+      self
+    end
+    alias << add_sprite
+
+    def sprite
+      @sprites[@current]
+    end
+
+    def sprite_names
+      @sprites.keys
+    end
+
+    # Switch the active sprite and (re)start playback from frame 0.
+    # Pass reset: false to keep the current frame index (e.g. crossfade).
+    def play(name, reset: true)
+      name = name.to_sym
+      return self unless @sprites.key?(name)
+
+      @current = name
+      if reset
+        @frame_index = 0
+        @last_advance = nil
+      end
+      @playing = true
+      self
+    end
+
+    def stop
+      @playing = false
+      self
+    end
+
+    def resume
+      @playing = true
+      self
+    end
+
+    def playing?
+      @playing
+    end
+
+    def preferred_height(_width)
+      sprite ? sprite.height : 0
+    end
+
+    def tick(now)
+      return unless @playing && sprite
+
+      @last_advance ||= now
+      frame_duration = 1.0 / sprite.fps
+      elapsed = now - @last_advance
+      return if elapsed < frame_duration
+
+      # Catch up if the loop ran slow, but never overshoot a :once endpoint.
+      steps = (elapsed / frame_duration).floor
+      @last_advance += steps * frame_duration
+      advance(steps)
+    end
+
+    def render(window)
+      return unless @visible && @rect && sprite
+
+      attr = theme[@color]
+      sprite.frame_lines(@frame_index).each_with_index do |line, row|
+        y = @rect.y + row
+        break if y >= @rect.y + @rect.height
+
+        x = @rect.x
+        x += [(@rect.width - line.length) / 2, 0].max if @centered
+        clipped = line[0, @rect.width] || ''
+        window.setpos(y, x)
+        window.attron(attr) { window.addstr(clipped) }
+      end
+    end
+
+    private
+
+    def advance(steps)
+      case sprite.mode
+      when :once
+        @frame_index += steps
+        if @frame_index >= sprite.frame_count - 1
+          @frame_index = sprite.frame_count - 1
+          @playing = false
+          @on_complete&.call(self)
+          emit(:complete, self)
+        end
+      else # :loop
+        @frame_index = (@frame_index + steps) % sprite.frame_count
+      end
+    end
+  end
+end