charming 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6b9e1f0689d7ebe1c6ab12b622339c8826bc3e1f44013e8b3c3d7e6e07be98a
-  data.tar.gz: d1aecf5b432f95241693509d597ca92c39b29549e3a9209be3e49421906fe60c
+  metadata.gz: 71b370eac77c67126921d7347a0d23f834f23774626c111445e9abdef73555d9
+  data.tar.gz: c8dd983f46183c2fbdb22f9c30753b4f1443d8de2989a4e7f90016f397aa12e4
 SHA512:
-  metadata.gz: 3440e877894c5a6146582165c7a8dd68c9d409799f8e99b517077c753f6f29ba5905346088bb5594d1a140bae1f5ba8f861f76b2f45c11ade91f0658b0108932
-  data.tar.gz: 0cede340d3d193c12acd7441868097987174dc96e85a0c9248a18b922dd0df341ebd7f8d305ee901df703b1553a5966aab611ddde9aa3e07e8ac5db2cca52cd7
+  metadata.gz: 2ee80f1c214001c8f91b36ba308f0e2f67aecbc258e7ff3ce63de2eb04093a405a0a23c3174cac6c3a1c6a98746b5353e66dd8179aebab4fe60ad35132603f19
+  data.tar.gz: 5242fbc9ad41ca1c0dbebbb070bb33cbdd1279955f81aa2f067954a1b11ffdd1b9cb7b90321285fa17e795c31d3fff32c7e052e95dee7e7c90318e19d252fba1

data/README.md

@@ -2,7 +2,7 @@
 
 A Rails-inspired terminal user interface framework for **Ruby 4+**.
 
-Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, cross-platform audio playback, and testable terminal backends.
+Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, cross-platform audio playback, inline image display (Kitty graphics protocol), system clipboard / desktop notifications / window title, braille charts and sparklines, and testable terminal backends.
 
 ## Project Status
 

data/lib/charming/application.rb

@@ -10,6 +10,7 @@ module Charming
   class Application
     LOGGER_READER = Object.new.freeze
     THEME_READER = Object.new.freeze
+    COALESCE_READER = Object.new.freeze
 
     class << self
       # Registers or returns the app's Router. Accepts an optional block to define
@@ -108,6 +109,27 @@ module Charming
         nil
       end
 
+      # When true, the runtime collapses bursts of identical key events — the flood a terminal
+      # emits while a key is held (OS auto-repeat) — into a single dispatch, so holding a key
+      # can't queue a backlog that keeps acting after release. Off by default: it also merges
+      # intentional fast repeats of the same key (e.g. tab tab), so enable it only for
+      # movement-style apps. Pass a boolean to set; call without args to read (inherited).
+      def coalesce_input(value = COALESCE_READER)
+        return configured_coalesce_input if value == COALESCE_READER
+
+        @coalesce_input = value
+      end
+
+      # The mouse motion reporting mode: :drag (default) reports movement only while
+      # a button is held; :all also reports buttonless hover movement. Pass a symbol
+      # to set; call without args to read (inherited).
+      def mouse_motion(value = COALESCE_READER)
+        return configured_mouse_motion if value == COALESCE_READER
+        raise ArgumentError, "mouse_motion must be :drag or :all" unless %i[drag all].include?(value)
+
+        @mouse_motion = value
+      end
+
       private
 
       def configured_logger
@@ -117,6 +139,20 @@ module Charming
         @logger = Logger.new(File::NULL)
       end
 
+      def configured_coalesce_input
+        return @coalesce_input if instance_variable_defined?(:@coalesce_input)
+        return superclass.coalesce_input if superclass.respond_to?(:coalesce_input)
+
+        false
+      end
+
+      def configured_mouse_motion
+        return @mouse_motion if instance_variable_defined?(:@mouse_motion)
+        return superclass.mouse_motion if superclass.respond_to?(:mouse_motion)
+
+        :drag
+      end
+
       # Expands a relative theme path against the app root (or the current working directory
       # when no root is configured). Returns *path* unchanged when it is already absolute.
       def resolve_theme_path(path)
@@ -163,6 +199,18 @@ module Charming
       session[:theme] = name.to_sym
     end
 
+    # Whether the runtime should coalesce held-key auto-repeat for this app (see the class-level
+    # `coalesce_input` DSL). Read by the Runtime at startup.
+    def coalesce_input?
+      self.class.coalesce_input == true
+    end
+
+    # The mouse motion reporting mode for this app (see the class-level `mouse_motion`
+    # DSL). Read by the Runtime at startup.
+    def mouse_motion
+      self.class.mouse_motion
+    end
+
     private
 
     # Loads the persisted session JSON (symbolizing keys), or {} when absent/invalid.

data/lib/charming/controller/key_dispatch.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # KeyDispatch resolves which handler claims a key event — the capture/bubble
+    # ladder a browser would own in a web MVC app. Priority order:
+    #
+    # 1. Command palette (when open) consumes everything.
+    # 2. A focused text-capturing component (TextInput, TextArea, Form, …) gets
+    #    printable characters BEFORE key bindings — typing "q" into a field must
+    #    insert a q, not quit the app.
+    # 3. Global key bindings.
+    # 4. An overlay focus scope (a pushed modal) captures all remaining keys.
+    # 5. Sidebar keys (when focused), content bindings, then the focused component —
+    #    which sees Tab before ring traversal so forms can do field navigation.
+    #
+    # Tiers differ in how they terminate: the palette, overlay, sidebar, and binding
+    # tiers consume the key outright once their condition holds, while the component
+    # tiers only consume it when the component reports :handled and otherwise let it
+    # fall through to the next tier.
+    class KeyDispatch
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # Runs the ladder for the controller's current event. Returns the winning
+      # tier's response, or nil when no tier claims the key.
+      def call
+        return palette_response if palette_open?
+        return response if typed_text_claimed?
+        return binding_response(global_action) if global_action
+        return overlay_response if overlay?
+        return sidebar_response if sidebar_focused?
+        return binding_response(content_action) if content_action
+        return response if component_or_ring_claimed?
+
+        nil
+      end
+
+      private
+
+      attr_reader :controller
+
+      def palette_open?
+        controller.command_palette_open?
+      end
+
+      def palette_response
+        controller.send(:dispatch_command_palette_key)
+      end
+
+      # True when a printable character was typed into a focused text-capturing
+      # component and the component consumed it.
+      def typed_text_claimed?
+        controller.send(:printable_text_event?) &&
+          controller.send(:focused_component_captures_text?) &&
+          component_claimed?
+      end
+
+      def global_action
+        controller.send(:global_key_action)
+      end
+
+      def content_action
+        controller.send(:content_key_action)
+      end
+
+      def binding_response(action)
+        controller.dispatch(action)
+      end
+
+      def overlay?
+        controller.focus.overlay?
+      end
+
+      # An overlay consumes the key whether or not the component handled it.
+      def overlay_response
+        controller.send(:dispatch_to_focused_component)
+        response
+      end
+
+      def sidebar_focused?
+        controller.sidebar_focused?
+      end
+
+      def sidebar_response
+        controller.send(:dispatch_sidebar_key)
+      end
+
+      # Text-capturing components own their remaining keys — Tab included, so forms
+      # do field navigation. Everything else keeps ring traversal ahead of the component.
+      def component_or_ring_claimed?
+        if controller.send(:focused_component_captures_text?)
+          component_claimed? || ring_claimed?
+        else
+          ring_claimed? || component_claimed?
+        end
+      end
+
+      def component_claimed?
+        controller.send(:dispatch_to_focused_component) == :handled
+      end
+
+      def ring_claimed?
+        controller.send(:dispatch_tab_traversal) == :handled
+      end
+
+      def response
+        controller.send(:response)
+      end
+    end
+  end
+end

data/lib/charming/controller/session_state.rb

@@ -30,6 +30,17 @@ module Charming
         session[:states][name.to_sym] ||= state_class.new(**attributes)
       end
 
+      # Returns the named mutable widget-state hash stored under `session[:component_state]`,
+      # seeding it from *defaults* on first access. This is the blessed way to keep an interactive
+      # component's state across ephemeral controller instances: store only JSON-safe primitives,
+      # rebuild the component from the hash each event, and write changed values back after
+      # `handle_key`. (Live component objects don't belong in the session — `save_session` drops
+      # anything that can't survive a JSON round-trip.)
+      def component_state(name, **defaults)
+        session[:component_state] ||= {}
+        session[:component_state][name.to_sym] ||= defaults
+      end
+
       # Builds a Form component scoped to the named form slot in `session[:forms]`. The block is
       # evaluated against a Form::Builder (or invoked with the builder as its argument for arity-1 blocks)
       # and returns a Form component pre-bound to the per-form mutable state hash.

data/lib/charming/controller/terminal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Terminal mixes imperative out-of-band terminal effects into Controller: writing the system
+    # clipboard, raising desktop notifications, ringing the bell, and setting the window title. Each
+    # registers an {Charming::Escape} sequence onto the dispatch's collection; the Runtime flushes it
+    # to the backend before the next frame. They compose freely with a normal `render` — e.g.
+    # `def copy_url; copy(state.url); notify("Copied!"); render(:show); end`.
+    module Terminal
+      # Writes *text* to the system clipboard (OSC 52). *target* selects the selection (`"c"`
+      # clipboard, `"p"` primary). Works across Ghostty/Kitty/iTerm2 (and tmux with passthrough).
+      def copy(text, target: "c")
+        Escape.register(Escape.clipboard(text, target: target))
+      end
+
+      # Raises a desktop notification showing *body* (and *title* when given).
+      def notify(body, title: nil)
+        Escape.register(Escape.notification(body, title: title))
+      end
+
+      # Rings the terminal bell.
+      def bell
+        Escape.register(Escape.bell)
+      end
+
+      # Sets the terminal window/tab title to *text* (OSC 0).
+      def set_title(text)
+        Escape.register(Escape.title(text))
+      end
+    end
+  end
+end

data/lib/charming/controller.rb

@@ -17,6 +17,7 @@ module Charming
     include CommandPalette
     include ComponentDispatching
     include Dispatching
+    include Terminal
 
     attr_reader :application, :event, :params, :screen, :route
 
@@ -39,51 +40,21 @@ module Charming
       response || render("")
     end
 
-    # Key event dispatch, in priority order:
-    # 1. Command palette (when open) consumes everything.
-    # 2. A focused text-capturing component (TextInput, TextArea, Form, …) gets
-    #    printable characters BEFORE key bindings — typing "q" into a field must
-    #    insert a q, not quit the app.
-    # 3. Global key bindings.
-    # 4. An overlay focus scope (a pushed modal) captures all remaining keys.
-    # 5. Sidebar keys (when focused), content bindings, then the focused component —
-    #    which sees Tab before ring traversal so forms can do field navigation.
+    # Key event dispatch. The precedence ladder (palette → focused text capture →
+    # global bindings → overlay → sidebar/content/component) lives in KeyDispatch.
     def dispatch_key
-      return dispatch_command_palette_key if command_palette_open?
-
-      if printable_text_event? && focused_component_captures_text?
-        return response if dispatch_to_focused_component == :handled
-      end
-
-      return dispatch(global_key_action) if global_key_action
-
-      if focus.overlay?
-        dispatch_to_focused_component
-        return response
-      end
-
-      return dispatch_sidebar_key if sidebar_focused?
-      return dispatch(content_key_action) if content_key_action
-
-      # Text-capturing components (forms, editors) own their remaining keys — Tab
-      # included, so forms do field navigation. Everything else keeps ring traversal
-      # ahead of the component.
-      if focused_component_captures_text?
-        return response if dispatch_to_focused_component == :handled
-        return response if dispatch_tab_traversal == :handled
-      else
-        return response if dispatch_tab_traversal == :handled
-        return response if dispatch_to_focused_component == :handled
-      end
-      nil
+      KeyDispatch.new(self).call
     end
 
-    # Timer event dispatcher: looks up the named action in timer bindings.
+    # Timer event dispatcher: looks up the named action in timer bindings and runs it
+    # with the full hook chain. Unlike #dispatch there is no render("") fallback — a
+    # timer action that renders nothing yields a nil response, so silent ticks skip
+    # the repaint instead of blanking the screen.
     def dispatch_timer
       b = self.class.timer_bindings[event.name.to_sym]
       return nil unless b
 
-      public_send(b.action)
+      run_action_with_hooks(b.action)
       response
     end
 
@@ -126,7 +97,9 @@ module Charming
       dispatch_component_mouse
     end
 
-    # Renders a body or template wrapped in the controller's layout.
+    # Renders a body or template wrapped in the controller's layout. Out-of-band escape sequences
+    # registered while rendering (e.g. image transmissions) are collected by the Runtime around the
+    # whole dispatch and attached to the response.
     def render(body = "", **assigns)
       body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
       @response = Response.render(render_with_layout(body))

data/lib/charming/escape.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Charming
+  # Escape is the out-of-band terminal channel: escape sequences written straight to the terminal,
+  # *before* each frame, bypassing the line-based renderer (which measures width and would shred raw
+  # control sequences). It is the shared substrate for several primitives — image transmissions
+  # ({Charming::Image::Transmit}), clipboard writes, desktop notifications, and the window title.
+  #
+  # Sequences are gathered during an event's dispatch via a thread-local collector ({collecting} /
+  # {register}) and attached to the {Response}; the {Runtime} flushes them through
+  # `backend.write_escape`. Any object that responds to `#payload` (a string) can ride the channel;
+  # the builders here return {Sequence} value objects and sanitize interpolated text so user content
+  # can't break out of the sequence.
+  module Escape
+    # A single out-of-band sequence. *payload* is the literal escape string written to the terminal.
+    Sequence = Data.define(:payload)
+
+    # Thread-local key under which the active collection bucket is stored.
+    BUCKET_KEY = :charming_escape_bucket
+
+    class << self
+      # Runs *block* with a fresh collection bucket active and returns the bucket — the {Sequence}s
+      # registered via {register} during the block. The block's own return value is ignored (capture
+      # it via a closure). Nesting is supported: an inner collection shadows the outer.
+      def collecting
+        previous = Thread.current[BUCKET_KEY]
+        bucket = []
+        Thread.current[BUCKET_KEY] = bucket
+        yield
+        bucket
+      ensure
+        Thread.current[BUCKET_KEY] = previous
+      end
+
+      # Registers *sequence* with the active collection bucket so it is flushed to the backend. A
+      # no-op (outside a collection, or when *sequence* is nil) so callers can register freely.
+      def register(sequence)
+        return sequence unless sequence
+
+        Thread.current[BUCKET_KEY]&.push(sequence)
+        sequence
+      end
+
+      # Builds an OSC 52 clipboard-write sequence setting the *target* selection (`"c"` clipboard,
+      # `"p"` primary) to *text*. The text is base64-encoded, so any bytes are safe.
+      def clipboard(text, target: "c")
+        Sequence.new(payload: "\e]52;#{target};#{[text.to_s].pack("m0")}\a")
+      end
+
+      # Builds a desktop-notification sequence: OSC 777 (`title` + `body`) when a *title* is given,
+      # else OSC 9 (body only) — the broadly supported baseline (Ghostty, iTerm2, Kitty).
+      def notification(body, title: nil)
+        payload =
+          if title
+            "\e]777;notify;#{sanitize(title)};#{sanitize(body)}\e\\"
+          else
+            "\e]9;#{sanitize(body)}\a"
+          end
+        Sequence.new(payload: payload)
+      end
+
+      # Builds a terminal-bell sequence (BEL).
+      def bell
+        Sequence.new(payload: "\a")
+      end
+
+      # Builds an OSC 0 sequence setting the terminal window (and icon) title to *text*.
+      def title(text)
+        Sequence.new(payload: "\e]0;#{sanitize(text)}\a")
+      end
+
+      private
+
+      # Strips C0 control characters (incl. ESC and BEL) so interpolated user text can't terminate
+      # or inject into the surrounding escape sequence.
+      def sanitize(text)
+        text.to_s.gsub(/[\x00-\x1f\x7f]/, "")
+      end
+    end
+  end
+end

data/lib/charming/events/mouse_event.rb

@@ -10,11 +10,12 @@ module Charming
     }.freeze
     private_constant :MOUSE_BUTTON_MAP
 
-    # MouseEvent represents a mouse input event. *button* encodes which button or action was triggered (left,
-    # right, scroll), while *x* and *y* provide the cursor position. Modifier booleans (*ctrl*, *alt*, *shift*)
-    # capture key state at the time of the event.
-    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift) do
-      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false)
+    # MouseEvent represents a mouse input event. *button* encodes which button or action was
+    # triggered (left, right, scroll), while *x* and *y* provide the cursor position. Modifier
+    # booleans (*ctrl*, *alt*, *shift*) capture key state at the time of the event. *motion*
+    # marks drag/hover movement and *release* marks an SGR button release.
+    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift, :motion, :release) do
+      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false, motion: false, release: false)
         super
       end
 
@@ -23,9 +24,9 @@ module Charming
         MOUSE_BUTTON_MAP.fetch(button, :unknown)
       end
 
-      # Returns `true` when the current event is a click (left, middle, or right button).
+      # Returns `true` for a button press (left, middle, or right) — not a release, drag, or hover.
       def click?
-        %i[left middle right].include?(button_name)
+        !motion && !release? && %i[left middle right].include?(button_name)
       end
 
       # Returns `true` when the button name maps to either direction of scroll.
@@ -33,9 +34,21 @@ module Charming
         %i[scroll_up scroll_down].include?(button_name)
       end
 
-      # Returns `true` when the current event is a mouse release action.
+      # Returns `true` for a button release: the SGR release marker, or the legacy
+      # button-3 release code on a non-motion event. (During motion, button 3
+      # means "no button held", not a release.)
       def release?
-        button_name == :release
+        release || (!motion && button_name == :release)
+      end
+
+      # Returns `true` for any mouse movement report (drag or hover).
+      def motion?
+        motion
+      end
+
+      # Returns `true` when the mouse moved with a button held down.
+      def drag?
+        motion && %i[left middle right].include?(button_name)
       end
     end
   end

data/lib/charming/generators/app_generator.rb

@@ -13,6 +13,7 @@ module Charming
       BASE_FILE_TEMPLATES = [
         ["Gemfile", "app/Gemfile.template", false],
         ["Rakefile", "app/Rakefile.template", false],
+        [".rspec", "app/dot_rspec.template", false],
         ["README.md", "app/README.md.template", false],
         ["%<name>s.gemspec", "app/gemspec.template", false],
         ["exe/%<name>s", "app/executable.template", true],
@@ -183,10 +184,10 @@ module Charming
 
       # The body of the home controller's private `home` helper, prefixed by a blank line.
       def controller_helpers
-        "\n\n    private\n" \
+        "\n\n    private\n\n" \
           "    def home\n" \
           "      state(:home, HomeState)\n" \
-          "    end"
+          "    end\n"
       end
 
       # The `require_relative "../config/database"` line when the app is database-configured.

data/lib/charming/generators/templates/app/Gemfile.template

@@ -3,3 +3,9 @@
 source "https://rubygems.org"
 
 gemspec
+
+group :development, :test do
+  gem "irb"     # `charming console` (not a default gem on Ruby 4.0+)
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+end

data/lib/charming/generators/templates/app/dot_rspec.template

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

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

@@ -0,0 +1,126 @@
+# 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
+
+        # 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