charming 0.2.1 → 0.2.3

data/lib/charming/image/protocol/kitty.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Charming
+  module Image
+    module Protocol
+      # Kitty encodes images for the Kitty graphics protocol using *Unicode placeholders* (virtual
+      # placement) — the technique that lets a cell-based TUI display images without the raw image
+      # escapes ever entering the width-measured, line-diffed frame.
+      #
+      # Two halves:
+      #
+      # * {transmit} builds the out-of-band escape (APC `\e_G…\e\`) that ships the PNG bytes and
+      #   creates a virtual placement sized to rows×cols. It is base64-encoded and chunked to
+      #   ≤4096 bytes per the protocol, and uses `q=2` to suppress terminal responses (which would
+      #   otherwise leak into the input stream). This must NOT go through the frame pipeline — the
+      #   width layer's Fe-escape rule strips the `\e_` introducer and would corrupt it.
+      #
+      # * {placeholder_block} builds the in-frame cells: each is the placeholder code point
+      #   {PLACEHOLDER} plus a row and a column diacritic ({DIACRITICS}); the image id is carried in
+      #   the cells' foreground colour. The colour is a hand-built, *exact* truecolour SGR — it must
+      #   never be routed through {Charming::UI} styling, whose colour downconversion would mangle
+      #   the id on non-truecolour terminals.
+      module Kitty
+        # The Kitty image placeholder code point. Renders as a width-1 cell that the terminal
+        # replaces with image pixels; combining diacritics on it encode the cell's row/column.
+        PLACEHOLDER = [0x10EEEE].pack("U")
+
+        # Maximum base64 payload bytes per APC chunk, per the Kitty graphics protocol.
+        CHUNK_SIZE = 4096
+
+        # The ordered combining diacritics that encode a cell's row/column index (the value at
+        # index N marks position N). Sourced verbatim from Kitty's `rowcolumn-diacritics.txt`.
+        DIACRITIC_CODEPOINTS = [
+          0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F, 0x0346, 0x034A, 0x034B, 0x034C,
+          0x0350, 0x0351, 0x0352, 0x0357, 0x035B, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368, 0x0369,
+          0x036A, 0x036B, 0x036C, 0x036D, 0x036E, 0x036F, 0x0483, 0x0484, 0x0485, 0x0486, 0x0487, 0x0592,
+          0x0593, 0x0594, 0x0595, 0x0597, 0x0598, 0x0599, 0x059C, 0x059D, 0x059E, 0x059F, 0x05A0, 0x05A1,
+          0x05A8, 0x05A9, 0x05AB, 0x05AC, 0x05AF, 0x05C4, 0x0610, 0x0611, 0x0612, 0x0613, 0x0614, 0x0615,
+          0x0616, 0x0617, 0x0657, 0x0658, 0x0659, 0x065A, 0x065B, 0x065D, 0x065E, 0x06D6, 0x06D7, 0x06D8,
+          0x06D9, 0x06DA, 0x06DB, 0x06DC, 0x06DF, 0x06E0, 0x06E1, 0x06E2, 0x06E4, 0x06E7, 0x06E8, 0x06EB,
+          0x06EC, 0x0730, 0x0732, 0x0733, 0x0735, 0x0736, 0x073A, 0x073D, 0x073F, 0x0740, 0x0741, 0x0743,
+          0x0745, 0x0747, 0x0749, 0x074A, 0x07EB, 0x07EC, 0x07ED, 0x07EE, 0x07EF, 0x07F0, 0x07F1, 0x07F3,
+          0x0816, 0x0817, 0x0818, 0x0819, 0x081B, 0x081C, 0x081D, 0x081E, 0x081F, 0x0820, 0x0821, 0x0822,
+          0x0823, 0x0825, 0x0826, 0x0827, 0x0829, 0x082A, 0x082B, 0x082C, 0x082D, 0x0951, 0x0953, 0x0954,
+          0x0F82, 0x0F83, 0x0F86, 0x0F87, 0x135D, 0x135E, 0x135F, 0x17DD, 0x193A, 0x1A17, 0x1A75, 0x1A76,
+          0x1A77, 0x1A78, 0x1A79, 0x1A7A, 0x1A7B, 0x1A7C, 0x1B6B, 0x1B6D, 0x1B6E, 0x1B6F, 0x1B70, 0x1B71,
+          0x1B72, 0x1B73, 0x1CD0, 0x1CD1, 0x1CD2, 0x1CDA, 0x1CDB, 0x1CE0, 0x1DC0, 0x1DC1, 0x1DC3, 0x1DC4,
+          0x1DC5, 0x1DC6, 0x1DC7, 0x1DC8, 0x1DC9, 0x1DCB, 0x1DCC, 0x1DD1, 0x1DD2, 0x1DD3, 0x1DD4, 0x1DD5,
+          0x1DD6, 0x1DD7, 0x1DD8, 0x1DD9, 0x1DDA, 0x1DDB, 0x1DDC, 0x1DDD, 0x1DDE, 0x1DDF, 0x1DE0, 0x1DE1,
+          0x1DE2, 0x1DE3, 0x1DE4, 0x1DE5, 0x1DE6, 0x1DFE, 0x20D0, 0x20D1, 0x20D4, 0x20D5, 0x20D6, 0x20D7,
+          0x20DB, 0x20DC, 0x20E1, 0x20E7, 0x20E9, 0x20F0, 0x2CEF, 0x2CF0, 0x2CF1, 0x2DE0, 0x2DE1, 0x2DE2,
+          0x2DE3, 0x2DE4, 0x2DE5, 0x2DE6, 0x2DE7, 0x2DE8, 0x2DE9, 0x2DEA, 0x2DEB, 0x2DEC, 0x2DED, 0x2DEE,
+          0x2DEF, 0x2DF0, 0x2DF1, 0x2DF2, 0x2DF3, 0x2DF4, 0x2DF5, 0x2DF6, 0x2DF7, 0x2DF8, 0x2DF9, 0x2DFA,
+          0x2DFB, 0x2DFC, 0x2DFD, 0x2DFE, 0x2DFF, 0xA66F, 0xA67C, 0xA67D, 0xA6F0, 0xA6F1, 0xA8E0, 0xA8E1,
+          0xA8E2, 0xA8E3, 0xA8E4, 0xA8E5, 0xA8E6, 0xA8E7, 0xA8E8, 0xA8E9, 0xA8EA, 0xA8EB, 0xA8EC, 0xA8ED,
+          0xA8EE, 0xA8EF, 0xA8F0, 0xA8F1, 0xAAB0, 0xAAB2, 0xAAB3, 0xAAB7, 0xAAB8, 0xAABE, 0xAABF, 0xAAC1,
+          0xFE20, 0xFE21, 0xFE22, 0xFE23, 0xFE24, 0xFE25, 0xFE26, 0x10A0F, 0x10A38, 0x1D185, 0x1D186, 0x1D187,
+          0x1D188, 0x1D189, 0x1D1AA, 0x1D1AB, 0x1D1AC, 0x1D1AD, 0x1D242, 0x1D243, 0x1D244
+        ].freeze
+
+        # The diacritics as encoded UTF-8 strings, indexed by row/column number.
+        DIACRITICS = DIACRITIC_CODEPOINTS.map { |cp| [cp].pack("U") }.freeze
+
+        module_function
+
+        # Builds the out-of-band transmit payload for *png_bytes* under *image_id*, creating a virtual
+        # placement sized *rows*×*cols* cells. Returns a single string: a chunked `a=t` transmit
+        # followed by an `a=p,U=1` virtual placement, ready to write straight to the terminal.
+        def transmit(image_id:, png_bytes:, rows:, cols:)
+          transmit_image(image_id, png_bytes) + create_placement(image_id, rows: rows, cols: cols)
+        end
+
+        # Builds the in-frame placeholder block: *rows* lines of *cols* cells each, every cell a
+        # {PLACEHOLDER} plus its row/column diacritics, with the *image_id* carried in an exact
+        # truecolour foreground SGR. Each line measures exactly *cols* display columns.
+        def placeholder_block(image_id:, rows:, cols:)
+          ensure_in_range!(rows, cols)
+          prefix = foreground(image_id)
+          Array.new(rows) do |row|
+            cells = Array.new(cols) { |col| PLACEHOLDER + DIACRITICS[row] + DIACRITICS[col] }.join
+            "#{prefix}#{cells}\e[0m"
+          end.join("\n")
+        end
+
+        # Builds the `a=d,d=I` escape that deletes *image_id*'s placements AND frees its data from
+        # terminal memory (lowercase `d=i` would keep the data resident). Long-lived apps that cycle
+        # many images must emit this when evicting, or the terminal's image storage grows unbounded.
+        def delete(image_id:)
+          "\e_Ga=d,d=I,i=#{image_id},q=2\e\\"
+        end
+
+        # The chunked `a=t` (transmit) escapes carrying the base64 PNG data directly (`f=100,t=d`).
+        # Control keys ride only the first chunk; `m=1` flags more-to-come, `m=0` the last.
+        def transmit_image(image_id, png_bytes)
+          chunks = chunk(encode(png_bytes))
+          chunks.each_with_index.map do |chunk, index|
+            last = index == chunks.length - 1
+            control = (index == 0) ? "a=t,f=100,t=d,i=#{image_id},q=2," : ""
+            "\e_G#{control}m=#{last ? 0 : 1};#{chunk}\e\\"
+          end.join
+        end
+
+        # The `a=p,U=1` escape creating a virtual placement for *image_id* sized *cols*×*rows* cells.
+        def create_placement(image_id, rows:, cols:)
+          "\e_Ga=p,U=1,i=#{image_id},c=#{cols},r=#{rows},q=2\e\\"
+        end
+
+        # The exact truecolour foreground SGR encoding *image_id*'s low 24 bits (no downconversion).
+        def foreground(image_id)
+          "\e[38;2;#{(image_id >> 16) & 0xFF};#{(image_id >> 8) & 0xFF};#{image_id & 0xFF}m"
+        end
+
+        # Strict base64 (no newlines) of *bytes*, via String#pack so no library require is needed.
+        def encode(bytes)
+          [bytes].pack("m0")
+        end
+
+        # Splits *data* into ≤{CHUNK_SIZE}-byte chunks (always at least one, even when empty).
+        def chunk(data)
+          data.scan(/.{1,#{CHUNK_SIZE}}/mo).then { |parts| parts.empty? ? [""] : parts }
+        end
+
+        # Raises when *rows*/*cols* exceed the available diacritics (the encodable cell range).
+        def ensure_in_range!(rows, cols)
+          max = DIACRITICS.length
+          return if rows <= max && cols <= max
+
+          raise ArgumentError, "image is at most #{max} cells per dimension (got #{rows}x#{cols})"
+        end
+      end
+    end
+  end
+end

data/lib/charming/image/protocol.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Charming
+  module Image
+    # Protocol namespaces the terminal-graphics encoders and dispatches to one by name. Each encoder
+    # (e.g. {Protocol::Kitty}) exposes the same surface — `transmit(...)` for the out-of-band payload
+    # and `placeholder_block(...)` for the in-frame cells — so {Source} stays protocol-agnostic.
+    module Protocol
+      # Returns the encoder module for *name* (a {Terminal#protocol} symbol), or nil when no encoder
+      # applies (e.g. `:none`).
+      def self.for(name)
+        case name
+        when :kitty then Kitty
+        end
+      end
+    end
+  end
+end

data/lib/charming/image/source.rb

@@ -0,0 +1,95 @@
+# 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
+
+      # Builds the out-of-band {Transmit} that frees the image from terminal memory, or nil when
+      # graphics are unsupported. Re-arms {transmitted?} so a later render retransmits. Callers
+      # evicting an image register this the same way as {transmit}.
+      def release
+        return unless protocol
+
+        @transmitted = false
+        Transmit.new(image_id: image_id, payload: protocol.delete(image_id: image_id))
+      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