charming 0.2.1 → 0.2.2

data/lib/charming/image/source.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Charming
+  module Image
+    # Source owns an image's bytes, its stable id, and its transmit state — the "engine" half of the
+    # image feature, analogous to {Charming::Audio::Player}. Keep it in `session` (built once) rather
+    # than rebuilt per render, so {transmitted?} reliably gates the one-time transmission.
+    #
+    # It dispatches to the active {Protocol} (chosen by its {Terminal}) to build the out-of-band
+    # {Transmit} and the in-frame placeholder block, and is a no-op on terminals without graphics
+    # support, letting {Charming::Components::Image} fall back gracefully.
+    class Source
+      # *path* or *data* supplies the (PNG) bytes — exactly one is required. *id* overrides the
+      # derived image id. *terminal* is the protocol-detection seam (injectable for specs).
+      def initialize(path: nil, data: nil, id: nil, terminal: Terminal.new)
+        raise ArgumentError, "provide either path: or data:" unless path || data
+
+        @path = path
+        @data = data
+        @id = id
+        @terminal = terminal
+        @transmitted = false
+      end
+
+      # The protocol-detection seam, exposed so the component can ask {supports_graphics?}.
+      attr_reader :terminal
+
+      # The stable 32-bit image id (kept within 24 bits so the placeholder foreground colour fully
+      # encodes it). Derived from a digest of the bytes unless an explicit id was given.
+      def image_id
+        @image_id ||= @id || derive_id
+      end
+
+      # True when the host terminal supports a graphics protocol.
+      def supports_graphics?
+        @terminal.supports_graphics?
+      end
+
+      # Builds the out-of-band {Transmit} for a *rows*×*cols* placement, or nil when graphics are
+      # unsupported. The {Runtime} flushes it to the backend; {Charming::Escape.register} collects it.
+      def transmit(rows:, cols:)
+        return unless protocol
+
+        Transmit.new(image_id: image_id, payload: protocol.transmit(image_id: image_id, png_bytes: bytes, rows: rows, cols: cols))
+      end
+
+      # The in-frame placeholder block sized *rows*×*cols*, or "" when graphics are unsupported.
+      def placement(rows:, cols:)
+        return "" unless protocol
+
+        protocol.placeholder_block(image_id: image_id, rows: rows, cols: cols)
+      end
+
+      # True once {mark_transmitted} has recorded that the image was sent to the terminal.
+      def transmitted?
+        @transmitted
+      end
+
+      # Records that the image has been transmitted, so it is not re-sent on later renders.
+      def mark_transmitted
+        @transmitted = true
+      end
+
+      private
+
+      # The encoder module for the detected protocol, or nil when none applies.
+      def protocol
+        @protocol = Protocol.for(@terminal.protocol) unless defined?(@protocol)
+        @protocol
+      end
+
+      # The raw image bytes, read once from *path* (binary) or taken from *data*.
+      def bytes
+        @bytes ||= @data || File.binread(@path)
+      end
+
+      # A stable, nonzero 24-bit id derived from the image bytes.
+      def derive_id
+        (Digest::SHA256.digest(bytes).unpack1("N") % 0xFFFFFE) + 1
+      end
+    end
+  end
+end

data/lib/charming/image/terminal.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Charming
+  module Image
+    # Terminal detects which terminal graphics protocol the host emulator supports, from
+    # environment variables. It is the single detection seam: the rest of the image engine
+    # dispatches on {protocol}. Injectable (`env:`) so specs never depend on the real terminal,
+    # mirroring {Charming::Audio::System}.
+    #
+    # Phase 1 detects only the Kitty graphics protocol (Ghostty + Kitty). Other terminals report
+    # `:none`, letting {Charming::Components::Image} fall back gracefully. Future protocols
+    # (iTerm2, Sixel, half-block) slot in here without touching {Source} or the component.
+    class Terminal
+      # *env* is the environment hash probed for terminal identity (defaults to the process env).
+      def initialize(env: ENV)
+        @env = env
+      end
+
+      # The supported graphics protocol as a symbol: `:kitty` for Kitty/Ghostty, else `:none`.
+      def protocol
+        return :kitty if kitty?
+
+        :none
+      end
+
+      # True when a real graphics protocol is available (i.e. {protocol} is not `:none`).
+      def supports_graphics?
+        protocol != :none
+      end
+
+      private
+
+      # True when the host terminal speaks the Kitty graphics protocol (Kitty or Ghostty).
+      def kitty?
+        present?("KITTY_WINDOW_ID") ||
+          term.match?(/kitty|ghostty/i) ||
+          @env["TERM_PROGRAM"].to_s.casecmp?("ghostty") ||
+          present?("GHOSTTY_RESOURCES_DIR")
+      end
+
+      # The `TERM` value as a string (never nil).
+      def term
+        @env["TERM"].to_s
+      end
+
+      # True when *key* is set to a non-empty value in the environment.
+      def present?(key)
+        !@env[key].to_s.empty?
+      end
+    end
+  end
+end

data/lib/charming/image/transmit.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Charming
+  module Image
+    # Transmit is a single out-of-band terminal graphics payload: the escape-sequence string that
+    # transmits an image (and creates its virtual placement) for a given *image_id*. It travels on
+    # {Response}#graphics and is written verbatim to the backend by the {Runtime}, bypassing the
+    # line-based frame pipeline. *image_id* is retained for deduplication and spec assertions.
+    Transmit = Data.define(:image_id, :payload)
+  end
+end

data/lib/charming/image.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Charming
+  # Image provides terminal image display. Unlike {Charming::Audio} (which spawns an out-of-band
+  # process and never touches the TTY), images must be written *into* the terminal — but the
+  # framework's renderer is line-based and width-measured, and would shred raw image escape
+  # sequences. So images use the Kitty graphics protocol's *Unicode placeholders*: the image bytes
+  # are transmitted once out-of-band (see {Charming::Image::Transmit} and the {Runtime}'s graphics
+  # flush), then placed by printing ordinary width-1 placeholder cells that ride the normal frame
+  # pipeline (see {Charming::Image::Protocol::Kitty}).
+  #
+  # The engine here ({Source}, {Terminal}, {Protocol}) mirrors {Charming::Audio}'s split; the view
+  # is {Charming::Components::Image}. Terminal support is detected via {Terminal}; Phase 1 targets
+  # Ghostty/Kitty and degrades to a fallback string elsewhere.
+  #
+  # Image transmissions ride the shared out-of-band {Charming::Escape} channel: {Transmit} responds
+  # to `#payload`, so the component registers it via `Charming::Escape.register` and the {Runtime}
+  # flushes it before the frame.
+  module Image
+  end
+end

data/lib/charming/internal/event_loop.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # EventLoop pumps events for a Charming runtime: it delivers the next due
+    # event — completed background tasks first, then due timers, then terminal
+    # input (with optional held-key coalescing) — to the block passed to {#run},
+    # until the block returns :quit, the interrupt check trips, or a test
+    # backend runs out of events. It knows nothing about controllers, routes,
+    # or rendering; deciding what an event *means* belongs to its caller.
+    class EventLoop
+      DEFAULT_READ_TIMEOUT = 0.05
+
+      # *timer_bindings* is the list of controller timer bindings (each
+      # responding to `name` and `interval`) to schedule. *interrupted* is a
+      # callable checked every iteration so a signal handler can stop the loop.
+      def initialize(backend:, clock:, task_queue:, timer_bindings: [], coalesce_input: false, interrupted: -> { false })
+        @backend = backend
+        @clock = clock
+        @task_queue = task_queue
+        @coalesce_input = coalesce_input
+        @interrupted = interrupted
+        @timers = build_timers(timer_bindings)
+        @pending_event = nil
+      end
+
+      # Pumps events, yielding each to the caller together with a flag saying
+      # whether another event is already due (letting the caller coalesce a
+      # burst into one repaint). Stops when the block returns :quit, when the
+      # interrupt check returns true, or when a test backend is exhausted.
+      # Closes the task queue on the way out so producer threads can't block on
+      # a loop that is no longer draining them.
+      def run
+        loop do
+          break if @interrupted.call
+
+          event = next_event
+          unless event
+            break if backend_exhausted?
+            next
+          end
+          break if yield(event, more_ready?) == :quit
+        end
+      ensure
+        @task_queue.close
+      end
+
+      # Replaces the scheduled timers — called when navigation lands on a
+      # controller with different timer bindings.
+      def reset_timers(timer_bindings)
+        @timers = build_timers(timer_bindings)
+      end
+
+      private
+
+      # The next due event in priority order: task results, then timers, then input.
+      def next_event
+        next_task_event || next_timer_event || next_input_event
+      end
+
+      # True when another task result is already queued. Only the task queue is
+      # considered: timer ticks drive animations and must each paint, and key
+      # floods are handled separately by input coalescing.
+      def more_ready?
+        !@task_queue.empty?
+      end
+
+      # Pops a task event from the thread-safe queue if one is available.
+      # Non-blocking — returns nil immediately when the queue is empty.
+      def next_task_event
+        @task_queue.pop(true)
+      rescue ThreadError
+        nil
+      end
+
+      # Returns a TimerEvent for the first due timer and advances its next fire
+      # time. Returns nil if no timers are ready or registered.
+      def next_timer_event
+        timer = due_timer
+        return unless timer
+
+        now = clock_now
+        timer[:next_at] = now + timer.fetch(:binding).interval
+        Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
+      end
+
+      # Reads the next input event, consuming a stashed event first, then
+      # collapsing any auto-repeat burst behind it.
+      def next_input_event
+        event = @pending_event
+        @pending_event = nil
+        event ||= @backend.read_event(timeout: read_timeout)
+        return event unless event && @coalesce_input
+
+        coalesce(event)
+      end
+
+      # Collapses a run of identical key events — the flood the terminal emits while
+      # a key is held down — into a single delivered event, so holding a key can't
+      # queue a backlog that keeps acting after release. The first non-matching event
+      # encountered is stashed for the next loop iteration, so distinct keys and
+      # non-key events (resize/paste/mouse) are never lost. Only KeyEvents are
+      # coalesced; everything else passes straight through.
+      def coalesce(event)
+        return event unless event.is_a?(Events::KeyEvent)
+
+        # Only read while input is *immediately* available, so the drain never blocks
+        # on an empty buffer (input_pending? is a true 0s check).
+        while @backend.input_pending?
+          nxt = @backend.read_event(timeout: 0)
+          break unless nxt
+          next if nxt == event # identical auto-repeat — discard the older one, keep draining
+
+          @pending_event = nxt
+          break
+        end
+        event
+      end
+
+      # Computes how long to block waiting for input based on when the next timer
+      # is due, clamped between 0 and DEFAULT_READ_TIMEOUT. Returns DEFAULT when
+      # no timers exist.
+      def read_timeout
+        return DEFAULT_READ_TIMEOUT if @timers.empty?
+
+        next_at = @timers.map { |timer| timer.fetch(:next_at) }.min
+        (next_at - clock_now).clamp(0, DEFAULT_READ_TIMEOUT)
+      end
+
+      # Returns the timer due at or before now with the earliest fire time.
+      def due_timer
+        now = clock_now
+        @timers.select { |timer| timer.fetch(:next_at) <= now }.min_by { |timer| timer.fetch(:next_at) }
+      end
+
+      # Builds timer states from bindings, scheduling each one interval from now.
+      def build_timers(timer_bindings)
+        now = clock_now
+        timer_bindings.map { |binding| {binding: binding, next_at: now + binding.interval} }
+      end
+
+      # True when the backend reports it has no more events to deliver (test
+      # backends only — the TTY backend never exhausts). Prevents the loop from
+      # spinning forever in tests that forget a trailing quit event.
+      def backend_exhausted?
+        @backend.respond_to?(:exhausted?) && @backend.exhausted?
+      end
+
+      # Returns current clock time.
+      def clock_now
+        @clock.call
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/adapter.rb

@@ -26,6 +26,14 @@ module Charming
           raise NotImplementedError, "#{self.class} must implement #read_event"
         end
 
+        # True when at least one input event is immediately available to read without blocking.
+        # The runtime uses this to drain held-key auto-repeat without stalling on the final,
+        # empty read. Defaults to false so a backend that can't answer simply opts out of
+        # coalescing (the runtime then dispatches each event individually).
+        def input_pending?
+          false
+        end
+
         # Returns the current terminal dimensions as [width, height] in cells.
         def size
           raise NotImplementedError, "#{self.class} must implement #size"
@@ -72,6 +80,12 @@ module Charming
         def write_lines(line_changes, frame: nil)
           raise NotImplementedError, "#{self.class} must implement #write_lines"
         end
+
+        # Writes an out-of-band escape sequence (image transmission, clipboard write, notification,
+        # window title) straight to the terminal, bypassing the line-based frame pipeline. *sequence*
+        # responds to `payload` (the escape-sequence string). Defaults to a no-op so backends opt in.
+        def write_escape(sequence)
+        end
       end
     end
   end

data/lib/charming/internal/terminal/key_normalizer.rb

@@ -17,9 +17,17 @@ module Charming
         end
 
         # Converts a raw *keypress* string into a KeyEvent. Returns nil when *keypress* is nil.
+        # Modified CSI sequences (shift/alt/ctrl arrows, function keys) and ESC-prefixed alt
+        # chords are decoded first; everything else goes through tty-reader's key table.
         def normalize(keypress)
           return nil unless keypress
 
+          modified = ModifiedKeyParser.parse(keypress)
+          return modified if modified
+
+          alt = alt_prefixed_event(keypress)
+          return alt if alt
+
           key_name = @reader.console.keys[keypress]
           return character_event(keypress) unless key_name
 
@@ -28,6 +36,18 @@ module Charming
 
         private
 
+        # Decodes "\e<key>" (Alt held while pressing <key>) by normalizing the inner
+        # key and flagging alt. Bare escapes and CSI/SS3 sequences are left alone.
+        def alt_prefixed_event(keypress)
+          return nil unless keypress.start_with?("\e") && keypress.length >= 2
+          return nil if ["[", "O", "\e"].include?(keypress[1])
+
+          inner = normalize(keypress[1..])
+          return nil unless inner
+
+          Events::KeyEvent.new(key: inner.key, char: inner.char, ctrl: inner.ctrl, alt: true, shift: inner.shift)
+        end
+
         # Builds a KeyEvent for a raw character keypress (no semantic name was matched).
         def character_event(keypress)
           Events::KeyEvent.new(key: keypress.to_sym, char: keypress)

data/lib/charming/internal/terminal/memory_backend.rb

@@ -16,6 +16,9 @@ module Charming
         # The array of recorded operation tuples: [:method_name, *args].
         attr_reader :operations
 
+        # The array of out-of-band escape sequences written via `write_escape`.
+        attr_reader :escapes
+
         # *events* is the queue of pre-seeded events to return from `read_event`.
         # *width*/*height* set the initial terminal dimensions reported by `size`.
         def initialize(events: [], width: 80, height: 24)
@@ -24,6 +27,7 @@ module Charming
           @height = height
           @frames = []
           @operations = []
+          @escapes = []
           @mouse_enabled = false
         end
 
@@ -39,6 +43,12 @@ module Charming
           @events.empty?
         end
 
+        # True when a pre-seeded event is still queued (mirrors a TTY with bytes ready). Lets
+        # the runtime's held-key coalescing drain seeded repeats in specs.
+        def input_pending?
+          !@events.empty?
+        end
+
         # Stores *frame* as the current frame and appends it to `frames`.
         def write_frame(frame)
           @current_frame = frame
@@ -55,6 +65,13 @@ module Charming
           @operations << [:write_lines, line_changes]
         end
 
+        # Records an out-of-band escape sequence, appending it to `escapes` and recording the
+        # operation (so specs can assert both its content and its ordering relative to frames).
+        def write_escape(sequence)
+          @escapes << sequence
+          @operations << [:write_escape, sequence]
+        end
+
         # Records an enter-alt-screen operation.
         def enter_alt_screen
           @operations << :enter_alt_screen
@@ -90,10 +107,11 @@ module Charming
           [@width, @height]
         end
 
-        # Marks the backend as having mouse tracking enabled and records the operation.
-        def enable_mouse_tracking
+        # Marks the backend as having mouse tracking enabled and records the operation
+        # with the requested motion mode (:drag or :all).
+        def enable_mouse_tracking(motion: :drag)
           @mouse_enabled = true
-          @operations << :enable_mouse_tracking
+          @operations << [:enable_mouse_tracking, motion]
         end
 
         # Marks the backend as having mouse tracking disabled and records the operation.

data/lib/charming/internal/terminal/modified_key_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # ModifiedKeyParser decodes xterm CSI sequences that carry a modifier
+      # parameter — "\e[1;2A" (shift+up), "\e[3;5~" (ctrl+delete) — which
+      # tty-reader's key table does not cover. The modifier parameter encodes
+      # 1 + (1 shift | 2 alt | 4 ctrl | 8 meta); meta is treated as alt.
+      class ModifiedKeyParser
+        # "\e[1;<mod><final>" — arrows, home/end, and the SS3-style F1-F4 finals.
+        LETTER_PATTERN = /\A\e\[1;(\d+)([A-DFHPQRS])\z/
+
+        # "\e[<code>;<mod>~" — insert/delete, page keys, home/end, F5-F12.
+        TILDE_PATTERN = /\A\e\[(\d+);(\d+)~\z/
+
+        LETTER_KEYS = {
+          "A" => :up, "B" => :down, "C" => :right, "D" => :left,
+          "F" => :end, "H" => :home,
+          "P" => :f1, "Q" => :f2, "R" => :f3, "S" => :f4
+        }.freeze
+
+        TILDE_KEYS = {
+          1 => :home, 2 => :insert, 3 => :delete, 4 => :end,
+          5 => :page_up, 6 => :page_down, 7 => :home, 8 => :end,
+          15 => :f5, 17 => :f6, 18 => :f7, 19 => :f8,
+          20 => :f9, 21 => :f10, 23 => :f11, 24 => :f12
+        }.freeze
+
+        SHIFT_BIT = 1
+        ALT_BIT = 2
+        CTRL_BIT = 4
+        META_BIT = 8
+
+        # Parses *raw* into a KeyEvent with modifier flags, or nil when it is not
+        # a modified CSI sequence.
+        def self.parse(raw)
+          return nil unless raw.is_a?(String)
+
+          if (match = raw.match(LETTER_PATTERN))
+            build_event(LETTER_KEYS[match[2]], match[1].to_i)
+          elsif (match = raw.match(TILDE_PATTERN))
+            build_event(TILDE_KEYS[match[1].to_i], match[2].to_i)
+          end
+        end
+
+        def self.build_event(key, modifier_param)
+          return nil unless key
+
+          bits = modifier_param - 1
+          Events::KeyEvent.new(
+            key: key,
+            shift: bits.anybits?(SHIFT_BIT),
+            alt: bits.anybits?(ALT_BIT | META_BIT),
+            ctrl: bits.anybits?(CTRL_BIT)
+          )
+        end
+
+        private_class_method :build_event
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/mouse_parser.rb

@@ -5,21 +5,23 @@ module Charming
     module Terminal
       # MouseParser parses raw terminal escape sequences into MouseEvent objects.
       # Supports both modern SGR sequences (the most common, used by current terminals)
-      # and the older 3-byte legacy sequences. The public API is class methods; no
-      # instance state is required.
+      # and the older 3-byte legacy sequences. Both encodings pack modifiers and motion
+      # into the button code: bit 2 shift, bit 3 alt/meta, bit 4 ctrl, bit 5 motion.
+      # SGR signals release with a final "m" instead of "M". The public API is class
+      # methods; no instance state is required.
       class MouseParser
-        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row[mode]M"
-        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(M|m)/
+        # Matches an SGR-encoded mouse sequence: "\e[<button;col;row" + "M" (press) or "m" (release).
+        SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)(M|m)/
 
         # Matches the legacy 3-byte mouse sequence: "\e[M" followed by 3 bytes.
         LEGACY_PATTERN = /\e\[M(.{3})/
 
-        # Maps raw button codes to semantic symbols used by MouseEvent#button_name.
-        BUTTON_MAP = {
-          0 => :left, 1 => :middle, 2 => :right, 3 => :release,
-          64 => :scroll_up, 65 => :scroll_down,
-          66 => :scroll_up, 67 => :scroll_down
-        }.freeze
+        # Button-code bits for modifier keys and motion (shared by SGR and legacy).
+        SHIFT_BIT = 4
+        ALT_BIT = 8
+        CTRL_BIT = 16
+        MOTION_BIT = 32
+        FLAG_BITS = SHIFT_BIT | ALT_BIT | CTRL_BIT | MOTION_BIT
 
         # Returns true when *raw* looks like a recognizable mouse sequence (SGR or legacy).
         # Lets the TTYBackend short-circuit and dispatch to MouseParser without allocation.
@@ -41,23 +43,13 @@ module Charming
           nil
         end
 
-        # Parses an SGR-format mouse sequence. Decodes button code, 1-based (col, row),
-        # the modifier "C" (ctrl) and "M" (shift) suffix, and the highlight alt (256-color)
-        # sequence as a heuristic for the alt modifier.
+        # Parses an SGR-format mouse sequence: button code with flag bits, 1-based
+        # (col, row), and the press/release final byte.
         def self.parse_sgr(raw)
           match = raw.match(SGR_PATTERN)
           return nil unless match
 
-          button_code = match[1].to_i
-          col = match[2].to_i - 1
-          row = match[3].to_i - 1
-          mode = match[4]
-
-          ctrl = mode == "C"
-          alt = raw.include?("\e[38;5;")
-          shift = mode == "M"
-
-          Events::MouseEvent.new(button: button_code, x: col, y: row, ctrl: ctrl, alt: alt, shift: shift)
+          build_event(match[1].to_i, match[2].to_i - 1, match[3].to_i - 1, release: match[4] == "m")
         end
 
         # Parses a legacy 3-byte mouse sequence. Each of the 3 bytes has 32 subtracted
@@ -69,12 +61,25 @@ module Charming
           bytes = match[1].bytes
           return nil unless bytes.length == 3
 
-          button_code = bytes[0] - 32
-          col = bytes[1] - 32
-          row = bytes[2] - 32
+          build_event(bytes[0] - 32, bytes[1] - 32, bytes[2] - 32, release: false)
+        end
 
-          Events::MouseEvent.new(button: button_code, x: col, y: row)
+        # Builds a MouseEvent from a raw button *code*, splitting out the modifier
+        # and motion flag bits so `button` carries only the button/wheel identity.
+        def self.build_event(code, x, y, release:)
+          Events::MouseEvent.new(
+            button: code & ~FLAG_BITS,
+            x: x,
+            y: y,
+            shift: code.anybits?(SHIFT_BIT),
+            alt: code.anybits?(ALT_BIT),
+            ctrl: code.anybits?(CTRL_BIT),
+            motion: code.anybits?(MOTION_BIT),
+            release: release
+          )
         end
+
+        private_class_method :build_event
       end
     end
   end