potty 0.0.1

data/lib/potty/application.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative 'theme'
+require_relative 'window_manager'
+require_relative 'layout'
+require_relative 'keys'
+require_relative 'surface'
+require_relative 'surfaces/curses_surface'
+require_relative 'surfaces/inline_surface'
+
+module Potty
+  # Main application wrapper: owns the view stack, the tick loop, and a
+  # Surface (the render target). Mode picks the surface:
+  #   :curses (default) — full-screen curses display, input via getch.
+  #   :inline           — N lines redrawn in place under the cursor via ANSI,
+  #                        no init_screen, terminal stays cooked (input
+  #                        ignored; host drives quit). Good for progress UIs.
+  class Application
+    attr_reader :theme, :window_manager, :view_stack, :surface
+
+    # When set (milliseconds), the event loop wakes every interval even
+    # without input, advancing time-based widgets (Animator, Countdown).
+    # Leave nil for a purely blocking, input-driven loop (the default).
+    # ~33-50ms gives smooth animation. Required for :inline.
+    attr_accessor :tick_interval
+
+    def initialize(mode: :curses, lines: nil, theme: nil)
+      @view_stack = []
+      @running = false
+      @theme = theme || Theme.new
+      @mode = mode
+      @lines = lines
+      # Kept for back-compat: curses-mode consumers that draw straight to
+      # window_manager.stdscr or read its dimensions.
+      @window_manager = (mode == :curses ? WindowManager.new : nil)
+      @surface = nil
+      @tick_interval = nil
+    end
+
+    # Start the application with root view
+    def run(root_view)
+      @surface = build_surface
+      @surface.start
+      push_view(root_view)
+      @running = true
+      event_loop
+    ensure
+      @surface&.finalize
+    end
+
+    # View navigation
+    def push_view(view)
+      @view_stack.last&.deactivate
+      @view_stack.push(view)
+      view.activate(self)
+      refresh_all
+    end
+
+    def pop_view
+      return if @view_stack.size <= 1
+
+      view = @view_stack.pop
+      view.deactivate
+      @view_stack.last&.activate(self)
+      refresh_all
+    end
+
+    def quit
+      @running = false
+    end
+
+    def refresh_all
+      @surface.erase
+      current_view&.render
+      @surface.present
+    end
+    alias redraw refresh_all
+
+    # Advance time-based widgets and repaint. Called automatically each
+    # event-loop frame; also public so a host that drives its own loop can
+    # pump animation/countdowns itself.
+    def tick
+      current_view&.tick(Time.now)
+      refresh_all
+    end
+
+    # Suspend the surface for an external process (e.g., shelling out).
+    def suspend
+      @surface&.finalize
+    end
+
+    # Resume after suspension.
+    def resume
+      @surface&.start
+      current_view&.activate(self)
+      refresh_all
+    end
+
+    private
+
+    def build_surface
+      case @mode
+      when :inline
+        Surfaces::InlineSurface.new(theme: @theme, lines: @lines, tick_interval: @tick_interval || 40)
+      else
+        Surfaces::CursesSurface.new(@window_manager, @theme, tick_interval: @tick_interval)
+      end
+    end
+
+    def event_loop
+      while @running
+        ch = @surface.read_key
+
+        case ch
+        when nil # tick timeout / no input this cycle
+          # fall through to tick
+        when Keys::CTRL_C
+          raise Interrupt
+        when Keys::ESC
+          unless current_view&.handle_escape
+            pop_view if @view_stack.size > 1
+          end
+        else
+          current_view&.handle_key(ch)
+        end
+
+        tick
+      end
+    end
+
+    def current_view
+      @view_stack.last
+    end
+  end
+end

data/lib/potty/border.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Potty
+  # Box-drawing helper shared by any widget that needs a frame (List,
+  # Panel, Modal, etc.) instead of each one hand-rolling corner glyphs.
+  module Border
+    STYLES = {
+      single:  { tl: "\u250C", tr: "\u2510", bl: "\u2514", br: "\u2518", h: "\u2500", v: "\u2502" },
+      rounded: { tl: "\u256D", tr: "\u256E", bl: "\u2570", br: "\u256F", h: "\u2500", v: "\u2502" },
+      double:  { tl: "\u2554", tr: "\u2557", bl: "\u255A", br: "\u255D", h: "\u2550", v: "\u2551" },
+      heavy:   { tl: "\u250F", tr: "\u2513", bl: "\u2517", br: "\u251B", h: "\u2501", v: "\u2503" }
+    }.freeze
+
+    module_function
+
+    # Draw a border around rect on window. `attr` is a resolved curses
+    # attribute (e.g. theme[:dim]); `title`, if given, is centered on the
+    # top edge.
+    def draw(window, rect, style: :single, attr: 0, title: nil)
+      return if rect.width < 2 || rect.height < 2
+
+      s = STYLES[style] || STYLES[:single]
+      inner = rect.width - 2
+
+      window.attron(attr) do
+        window.setpos(rect.y, rect.x)
+        window.addstr(s[:tl] + s[:h] * inner + s[:tr])
+
+        (1...(rect.height - 1)).each do |dy|
+          window.setpos(rect.y + dy, rect.x)
+          window.addstr(s[:v])
+          window.setpos(rect.y + dy, rect.x + rect.width - 1)
+          window.addstr(s[:v])
+        end
+
+        window.setpos(rect.y + rect.height - 1, rect.x)
+        window.addstr(s[:bl] + s[:h] * inner + s[:br])
+      end
+
+      draw_title(window, rect, title, attr, inner) if title && !title.to_s.empty?
+    end
+
+    def draw_title(window, rect, title, attr, inner)
+      label = " #{title} "
+      label = label[0, inner] || '' if label.length > inner
+      x = rect.x + 1 + [(inner - label.length) / 2, 0].max
+      window.setpos(rect.y, x)
+      window.attron(attr) { window.addstr(label) }
+    end
+  end
+end

data/lib/potty/events.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Potty
+  # A tiny event-emitter mixin so widgets can be wired together
+  # declaratively. Any includer gains `on`/`off`/`emit`. Widgets emit
+  # semantic events (`:change`, `:focus`, `:select`, `:press`, …) that a
+  # consumer subscribes to with blocks — letting a View stitch its pieces
+  # together without each widget needing a bespoke callback setter:
+  #
+  #   input.on(:change)  { |text| preview.text = text }
+  #   toggle.on(:change) { |on|   advanced.visible = on }
+  #   button.on(:press)  { app.pop_view }
+  #
+  # `on` returns self, so subscriptions chain. Multiple listeners per event
+  # are supported and fire in registration order.
+  module Events
+    def on(event, &block)
+      return self unless block
+
+      (@listeners ||= {})[event.to_sym] ||= []
+      @listeners[event.to_sym] << block
+      self
+    end
+
+    # Remove listeners for one event, or all events when called bare.
+    def off(event = nil)
+      @listeners ||= {}
+      event ? @listeners.delete(event.to_sym) : @listeners.clear
+      self
+    end
+
+    # Fire an event to its listeners. Returns true if any listener ran.
+    def emit(event, *args)
+      list = (@listeners ||= {})[event.to_sym]
+      return false if list.nil? || list.empty?
+
+      list.each { |cb| cb.call(*args) }
+      true
+    end
+
+    def listeners?(event)
+      list = (@listeners ||= {})[event.to_sym]
+      !(list.nil? || list.empty?)
+    end
+  end
+end

data/lib/potty/keys.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+module Potty
+  # Named key codes, so widget input handling reads in intent rather than
+  # magic integers. Special keys resolve through Curses with fallbacks to
+  # the conventional ncurses values, for portability across curses builds.
+  #
+  # (END_ carries a trailing underscore because END is a Ruby keyword.)
+  module Keys
+    # Control / ASCII
+    CTRL_C    = 3
+    CTRL_A    = 1
+    CTRL_E    = 5
+    CTRL_D    = 4
+    TAB       = 9
+    ENTER     = 10
+    RETURN    = 13
+    ESC       = 27
+    SPACE     = 32
+    CTRL_H    = 8
+    DEL_ASCII = 127
+
+    def self.const_or(path, fallback)
+      Curses::Key.const_defined?(path) ? Curses::Key.const_get(path) : fallback
+    end
+
+    # Arrows / navigation (curses-resolved with ncurses fallbacks)
+    UP        = const_or(:UP, 259)
+    DOWN      = const_or(:DOWN, 258)
+    LEFT      = const_or(:LEFT, 260)
+    RIGHT     = const_or(:RIGHT, 261)
+    HOME      = const_or(:HOME, 262)
+    END_      = const_or(:END, 360)
+    DELETE    = const_or(:DC, 330)
+    BACKSPACE = const_or(:BACKSPACE, 263)
+    SHIFT_TAB = const_or(:BTAB, 353)
+    RESIZE    = const_or(:RESIZE, 410)
+
+    # Common groupings
+    ENTERS     = [ENTER, RETURN].freeze
+    BACKSPACES = [DEL_ASCII, CTRL_H, BACKSPACE].freeze
+
+    module_function
+
+    # Normalize a curses #getch result to an integer key code. Ruby's
+    # curses returns a String for ordinary printable input and an Integer
+    # for control/function keys — normalizing here lets all widget
+    # handle_key logic rely on numeric codes. Passes nil (tick timeout)
+    # and Integers through unchanged.
+    def code(ch)
+      return ch unless ch.is_a?(String)
+      return nil if ch.empty?
+
+      ch.ord
+    end
+
+    def enter?(ch)
+      ENTERS.include?(ch)
+    end
+
+    def backspace?(ch)
+      BACKSPACES.include?(ch)
+    end
+
+    def printable?(ch)
+      ch.is_a?(Integer) && ch >= SPACE && ch <= DEL_ASCII - 1
+    end
+  end
+end

data/lib/potty/layout.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Potty
+  # Layout engine for positioning and sizing widgets
+  class Layout
+    # Rectangle representing position and size
+    Rect = Struct.new(:x, :y, :width, :height) do
+      def to_s
+        "Rect(x=#{x}, y=#{y}, w=#{width}, h=#{height})"
+      end
+    end
+
+    # Vertical stack layout
+    def self.stack(container_rect, widgets, spacing: 0)
+      y = container_rect.y
+      widgets.map do |widget|
+        height = widget.preferred_height(container_rect.width)
+        rect = Rect.new(container_rect.x, y, container_rect.width, height)
+        y += height + spacing
+        rect
+      end
+    end
+
+    # Horizontal split
+    def self.split_horizontal(container_rect, ratio: 0.5)
+      split_x = container_rect.x + (container_rect.width * ratio).to_i
+      left = Rect.new(
+        container_rect.x,
+        container_rect.y,
+        split_x - container_rect.x,
+        container_rect.height
+      )
+      right = Rect.new(
+        split_x,
+        container_rect.y,
+        container_rect.width - (split_x - container_rect.x),
+        container_rect.height
+      )
+      [left, right]
+    end
+
+    # Fill available space
+    def self.fill(container_rect)
+      container_rect.dup
+    end
+  end
+end

data/lib/potty/sprite.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Potty
+  # A named sequence of multiline string frames. Pure data — holds no
+  # curses state and no timing state; an Animator drives playback.
+  #
+  # Each frame is a multiline string. Lines may differ in length and a
+  # frame may contain trailing blank lines (preserved via split("\n", -1)).
+  class Sprite
+    attr_reader :name, :frames, :fps, :mode
+
+    # name   - identifier used to select this sprite on an Animator
+    # frames - array of multiline strings, one per animation frame
+    # fps    - default playback rate in frames per second
+    # mode   - :loop (wrap forever) or :once (stop on the last frame)
+    def initialize(name, frames:, fps: 8, mode: :loop)
+      raise ArgumentError, 'frames must not be empty' if frames.nil? || frames.empty?
+      raise ArgumentError, "mode must be :loop or :once, got #{mode.inspect}" unless %i[loop once].include?(mode)
+
+      @name = name.to_sym
+      @frames = frames.dup.freeze
+      @fps = fps
+      @mode = mode
+    end
+
+    def frame_count
+      @frames.size
+    end
+
+    def frame(index)
+      @frames[index]
+    end
+
+    # Lines of a frame, preserving trailing blank lines.
+    def frame_lines(index)
+      (@frames[index] || '').split("\n", -1)
+    end
+
+    # Rows in the tallest frame.
+    def height
+      @frames.map { |f| f.split("\n", -1).size }.max
+    end
+
+    # Columns in the widest line across all frames.
+    def width
+      @frames.flat_map { |f| f.split("\n", -1).map(&:length) }.max
+    end
+  end
+end

data/lib/potty/sprites/sample.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../sprite'
+
+module Potty
+  module Sprites
+    # Tiny demo sprites that exercise the Animator API out of the box.
+    # These are NOT the claudepilot pilot - that mascot lives in the
+    # consuming app. They exist so the primitive has something to show and
+    # so consumers have a copy-paste template.
+    module Sample
+      module_function
+
+      # Looping braille spinner. Single-cell, good for inline "busy" hints.
+      def spinner
+        Sprite.new(:spinner,
+                   frames: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C",
+                            "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
+                   fps: 12, mode: :loop)
+      end
+
+      # A little plane taxiing across the field, played once.
+      def plane
+        Sprite.new(:plane,
+                   frames: [
+                     "\u2708        ",
+                     "  \u2708      ",
+                     "    \u2708    ",
+                     "      \u2708  ",
+                     "        \u2708"
+                   ],
+                   fps: 6, mode: :once)
+      end
+    end
+  end
+end

data/lib/potty/style.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Potty
+  # A semantic, render-target-agnostic description of how to draw text:
+  # symbolic colours (:cyan, :default, :bright_black, …) plus attributes.
+  # A Surface resolves a Style to concrete output — curses attributes on a
+  # CursesSurface, ANSI SGR codes on an InlineSurface — so the same widget
+  # renders to either target unchanged.
+  Style = Struct.new(:fg, :bg, :bold, :underline, :reverse, keyword_init: true) do
+    def bold?      = !!bold
+    def underline? = !!underline
+    def reverse?   = !!reverse
+  end
+end

data/lib/potty/surface.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Potty
+  # Abstract render target. Widgets draw against a Surface (setpos / addstr /
+  # attron) and the concrete subclass decides how that reaches the terminal:
+  # CursesSurface paints a curses screen; InlineSurface writes ANSI to stdout.
+  # The component tree describes *what*; the surface decides *how*.
+  class Surface
+    # [rows, cols] of the drawable area.
+    def size
+      raise NotImplementedError
+    end
+
+    # Acquire / release the terminal.
+    def start; end
+    def finalize; end
+
+    # Frame lifecycle: erase the buffer, widgets draw, then present flushes.
+    def erase
+      raise NotImplementedError
+    end
+
+    def setpos(_row, _col)
+      raise NotImplementedError
+    end
+
+    def addstr(_str)
+      raise NotImplementedError
+    end
+
+    # Apply a style around the block's draws. Accepts a Potty::Style or a
+    # raw integer (a legacy curses attribute) — see CursesSurface.
+    def attron(_style_or_attr)
+      yield if block_given?
+    end
+
+    def present
+      raise NotImplementedError
+    end
+
+    # One integer key code, or nil if there was no input this cycle.
+    def read_key
+      nil
+    end
+  end
+end

data/lib/potty/surfaces/curses_surface.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'curses'
+require_relative '../surface'
+require_relative '../theme'
+require_relative '../keys'
+
+module Potty
+  module Surfaces
+    # The default render target: a full-screen curses display. Wraps the
+    # WindowManager / stdscr so existing widgets draw exactly as before.
+    #
+    # attron accepts EITHER a Potty::Style (resolved to a colour pair +
+    # attributes) OR a raw integer (a legacy curses attribute, passed
+    # through). That dual acceptance is what lets un-migrated widgets — and
+    # direct-to-window consumers like a host's own paint code — keep working
+    # untouched while new widgets go render-target-agnostic.
+    class CursesSurface < Surface
+      def initialize(window_manager, theme, tick_interval: nil)
+        super()
+        @wm = window_manager
+        @theme = theme
+        @tick_interval = tick_interval
+        @next_pair = theme.palette.size + 1 # leave 1..N for theme[]'s pairs
+        @pairs = nil
+      end
+
+      def start
+        # See ESCDELAY notes in Theme/Application history: the env var is only
+        # honoured by newer ncurses, so also set it via Curses.ESCDELAY=.
+        ENV['ESCDELAY'] ||= '250'
+        @wm.setup(::Curses.init_screen)
+        ::Curses.ESCDELAY = 250 if ::Curses.respond_to?(:ESCDELAY=)
+        ::Curses.curs_set(0)
+        ::Curses.noecho
+        ::Curses.cbreak
+        stdscr.keypad(true)
+        stdscr.timeout = @tick_interval if @tick_interval
+        @theme.setup_colors if ::Curses.has_colors?
+      end
+
+      def finalize
+        ::Curses.close_screen
+      end
+
+      def size
+        [@wm.max_y, @wm.max_x]
+      end
+
+      def erase
+        stdscr.erase
+      end
+
+      def setpos(row, col)
+        stdscr.setpos(row, col)
+      end
+
+      def addstr(str)
+        stdscr.addstr(str)
+      end
+
+      def attron(style_or_attr, &block)
+        stdscr.attron(curses_attr(style_or_attr), &block)
+      end
+
+      def present
+        @wm.refresh_all
+      end
+
+      def read_key
+        Keys.code(stdscr.getch)
+      end
+
+      private
+
+      def stdscr
+        @wm.stdscr
+      end
+
+      def curses_attr(value)
+        return value if value.is_a?(Integer) # legacy curses attribute
+        return 0 unless value.is_a?(Potty::Style)
+
+        attr = color_pair(value.fg, value.bg)
+        attr |= ::Curses::A_BOLD      if value.bold?
+        attr |= ::Curses::A_UNDERLINE if value.underline?
+        attr |= ::Curses::A_REVERSE   if value.reverse?
+        attr
+      end
+
+      def color_pair(fg, bg)
+        return 0 unless ::Curses.has_colors?
+
+        (@pairs ||= seed_pairs)
+        @pairs[[fg, bg]] ||= allocate_pair(fg, bg)
+      end
+
+      # Reuse the pairs Theme already allocated for its palette combos so we
+      # don't burn a second pair on every colour we share with theme[].
+      def seed_pairs
+        map = {}
+        @theme.palette.each { |name, c| map[[c[:fg], c[:bg]]] = @theme[name] }
+        map
+      end
+
+      def allocate_pair(fg, bg)
+        n = @next_pair
+        @next_pair += 1
+        ::Curses.init_pair(n, Theme::COLORS.fetch(fg, -1), Theme::COLORS.fetch(bg, -1))
+        ::Curses.color_pair(n)
+      end
+    end
+  end
+end