echoes 0.2.0 → 0.3.0

data/lib/echoes/iterm2_images.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Echoes
+  # iTerm2 inline-image protocol (OSC 1337 with the `File=` verb).
+  # Wire format:
+  #
+  #   \e]1337;File=<key=value>[;<key=value>...]:<base64-payload>\a
+  #
+  # Most of the heavy lifting (NSBitmapImageRep PNG/JPEG/TIFF/GIF
+  # decode, RGBA pixmap storage on the screen, blit through the
+  # multicell renderer) is already shipped for the Kitty graphics
+  # protocol — this module just parses the OSC 1337 envelope and
+  # delegates to Echoes::KittyGraphics::AppKitPng /
+  # Screen#put_kitty_image.
+  #
+  # Out of scope (follow-ups, if anyone hits them):
+  #   - `inline=0` (save to disk / clipboard) — we ignore these.
+  #   - `preserveAspectRatio=0` (non-uniform stretch) — we always
+  #     preserve aspect; user can request explicit `width=` + `height=`.
+  #   - The `name=`-base64 metadata — useful for "Save As" UIs we
+  #     don't have.
+  module Iterm2Images
+    module_function
+
+    # Top-level entry point. `rest` is everything between
+    # `\e]1337;` and the terminating BEL/ST. Returns truthy on
+    # successful image display; nil otherwise (silently).
+    def handle(rest, screen:, writer: nil)
+      verb_args = rest.to_s
+      return nil unless verb_args.start_with?('File=')
+
+      params_str, payload_b64 = verb_args.byteslice(5..).split(':', 2)
+      return nil if payload_b64.nil? || payload_b64.empty?
+
+      params = parse_params(params_str || '')
+
+      # iTerm2 only inlines images when `inline=1`. Absent means
+      # "save to disk", which we don't support — bail.
+      return nil unless params['inline'] == '1'
+
+      bytes = decode_payload(payload_b64)
+      return nil unless bytes
+
+      image = decode_image(bytes)
+      return nil unless image
+
+      cells_w, cells_h = compute_cell_dimensions(params, image, screen)
+      screen.put_kitty_image(
+        rgba:    image[:rgba],
+        width:   image[:width],
+        height:  image[:height],
+        cells_w: cells_w,
+        cells_h: cells_h,
+      )
+      true
+    end
+
+    # Parse "k1=v1;k2=v2" into {"k1"=>"v1", "k2"=>"v2"}.
+    def parse_params(str)
+      out = {}
+      str.split(';').each do |pair|
+        k, v = pair.split('=', 2)
+        next if k.nil? || k.empty?
+        out[k] = (v || '').to_s
+      end
+      out
+    end
+
+    # Tolerant base64 decode (allows wrapped / whitespace payloads).
+    # Mirrors KittyGraphics.decode_payload to keep the two paths
+    # symmetric.
+    def decode_payload(b64)
+      cleaned = b64.to_s.delete("\r\n\t ")
+      return nil if cleaned.empty?
+      cleaned.unpack1('m0')
+    rescue ArgumentError
+      nil
+    end
+
+    # Bytes → {rgba:, width:, height:}. Despite the name,
+    # AppKitPng handles every format NSBitmapImageRep recognizes
+    # (PNG / JPEG / GIF / TIFF / BMP) because it draws the
+    # decoded CGImage into a known RGBA8 CGBitmapContext.
+    def decode_image(bytes)
+      require_relative 'kitty_graphics_appkit'
+      KittyGraphics::AppKitPng.decode(bytes)
+    end
+
+    # Translate the wire's `width=` / `height=` into cell counts
+    # for the renderer. Supported forms (per iTerm2 docs):
+    #   N      — N character cells
+    #   Npx    — N pixels; rounded up to a whole cell
+    #   N%     — N% of the screen dimension
+    #   auto   — natural pixel size / cell pixel size (default)
+    # nil or unrecognized → `auto`.
+    def compute_cell_dimensions(params, image, screen)
+      cell_w_px = screen.cell_pixel_width.to_f
+      cell_h_px = screen.cell_pixel_height.to_f
+      cells_w = parse_dim(params['width'],
+                          natural_px: image[:width],
+                          cell_px:    cell_w_px,
+                          screen_size: screen.cols)
+      cells_h = parse_dim(params['height'],
+                          natural_px: image[:height],
+                          cell_px:    cell_h_px,
+                          screen_size: screen.rows)
+      [cells_w, cells_h]
+    end
+
+    def parse_dim(value, natural_px:, cell_px:, screen_size:)
+      return nil if value.nil? || value.empty? || value == 'auto'
+      if value.end_with?('px')
+        return nil if cell_px <= 0
+        (value.to_f / cell_px).ceil
+      elsif value.end_with?('%')
+        (screen_size * value.to_f / 100.0).ceil
+      else
+        value.to_i
+      end
+    end
+  end
+end

data/lib/echoes/kitty_graphics.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Echoes
+  # Minimum-viable Kitty graphics protocol decoder. Wire format:
+  #
+  #   \e_G<comma-separated-options>;<base64-payload>\e\
+  #
+  # Parser hands us the body (sans `\e_G…\e\\` framing) split into
+  # `meta` and the still-base64 `payload`. We accumulate chunks
+  # keyed by image id (m=1 = more, m=0 = last), base64-decode the
+  # full payload, decode PNG (f=100, the default) into RGBA via
+  # AppKit, then either cache the image (a=t) or display it via
+  # `screen.put_kitty_image` (a=T or a=p).
+  #
+  # State lives on the parser (per-pane) — not module globals —
+  # so chunks from different panes don't collide.
+  module KittyGraphics
+    CHUNK_LIMIT_BYTES = 16 * 1024 * 1024
+    CACHE_LIMIT       = 16   # most-recent N images, LRU
+    DEFAULT_FORMAT    = '100'.freeze  # PNG
+
+    module_function
+
+    # Parse "a=T,f=100,i=1" into {"a"=>"T", "f"=>"100", "i"=>"1"}.
+    # Keys with no `=` map to '' so the caller can still tell they
+    # were present.
+    def parse_options(meta)
+      out = {}
+      meta.to_s.split(',').each do |pair|
+        k, v = pair.split('=', 2)
+        next if k.nil? || k.empty?
+        out[k] = (v || '').to_s
+      end
+      out
+    end
+
+    # Add one APC chunk's payload to the per-id buffer. Returns the
+    # full assembled payload + final-options Hash when this chunk
+    # closes the image (m=0 or no m=); returns nil while more
+    # chunks are still expected.
+    def assemble_chunk(state, meta, payload)
+      opts = parse_options(meta)
+      id   = opts['i'] || opts['I'] || ''
+      more = opts['m'] == '1'
+
+      buf = state[:chunks][id]
+      if buf
+        # Subsequent chunk: append payload, update saved-options
+        # only with newly-seen non-id keys (Kitty's spec: only `m`
+        # / `q` / `S` / size differ across chunks).
+        return nil if buf[1].bytesize + payload.bytesize > CHUNK_LIMIT_BYTES
+        buf[0]['m'] = opts['m'] if opts.key?('m')
+        buf[0]['q'] = opts['q'] if opts.key?('q')
+        buf[1] << payload
+      else
+        # First chunk: stash both options and payload.
+        return nil if payload.bytesize > CHUNK_LIMIT_BYTES
+        buf = [opts, +"".b]
+        buf[1] << payload
+        state[:chunks][id] = buf
+      end
+
+      return nil if more
+
+      state[:chunks].delete(id)
+      [buf[0], buf[1]]
+    end
+
+    # Top-level dispatcher — one call per APC frame.
+    def handle_chunk(state, meta, payload, screen:, writer:)
+      assembled = assemble_chunk(state, meta, payload)
+      return unless assembled
+      opts, b64 = assembled
+
+      action = opts['a'].to_s
+      action = 'T' if action.empty?  # default action
+
+      case action
+      when 'T', 't'
+        bytes = decode_payload(b64)
+        return respond(writer, opts, error: 'EBADPNG') unless bytes
+
+        # Transmission medium (`t=…`):
+        #   d (default) — payload is the image bytes (already decoded above)
+        #   f          — payload is an absolute file path; we read it
+        #   t          — same as `f`, then delete the file (temp file)
+        #   s          — shared memory; not supported
+        bytes = resolve_transmission(bytes, opts)
+        return respond(writer, opts, error: 'ENOENT') unless bytes
+
+        # Compression (`o=…`):
+        #   (unset) — payload is uncompressed
+        #   z       — payload is raw zlib (deflate). kitten icat
+        #             defaults to o=z for any non-PNG transmission,
+        #             so this is the common case in the wild.
+        bytes = inflate_if_needed(bytes, opts['o'])
+        return respond(writer, opts, error: 'EBADDATA') unless bytes
+
+        image = decode_image(bytes, opts['f'] || DEFAULT_FORMAT, opts)
+        return respond(writer, opts, error: 'EBADPNG') unless image
+
+        cache_image(state, opts['i'] || opts['I'] || '', image)
+        if action == 'T'
+          display_image(screen, image, opts)
+        end
+        respond(writer, opts, ok: true)
+
+      when 'p'
+        id    = opts['i'] || opts['I'] || ''
+        image = state[:cache][id]
+        if image
+          display_image(screen, image, opts)
+          respond(writer, opts, ok: true)
+        else
+          respond(writer, opts, error: 'ENOENT')
+        end
+
+      when 'd'
+        # kitty spec: a=d deletes placements (lowercase d-selector)
+        # or placements + images (uppercase selector). Default
+        # selector is 'a' (all placements on the visible screen).
+        #
+        # Supported selectors (subset; expand as use cases arrive):
+        #   d=a / d=A  — all placements; uppercase also flushes
+        #                 the bitmap cache so the next a=p has to
+        #                 re-decode.
+        #   d=i / d=I  — placements matching i= / I=; uppercase
+        #                 also flushes that one cache entry.
+        #   (omitted)  — treated as d=a per spec.
+        sel    = (opts['d'] || 'a').to_s
+        target = opts['i'] || opts['I']
+        upper  = sel == sel.upcase && !sel.empty?
+        case sel.downcase
+        when 'a', ''
+          screen.placements.clear if screen.respond_to?(:placements)
+          state[:cache].clear if upper
+        when 'i', 'n'
+          if target && !target.empty?
+            if screen.respond_to?(:placements)
+              screen.placements.reject! { |pl| pl[:image_id] == target }
+            end
+            state[:cache].delete(target) if upper
+          end
+        end
+        respond(writer, opts, ok: true)
+
+      when 'q'
+        # Capability probe. kitten icat (and others) send a tiny
+        # dummy frame with a=q before transmitting real images;
+        # they read the OK/error reply to decide whether the
+        # terminal supports the protocol. We don't decode the
+        # payload — just answer whether we'd accept this
+        # format / transmission / compression combo.
+        if supported_format?(opts['f']) &&
+           supported_transmission?(opts['t']) &&
+           supported_compression?(opts['o'])
+          respond(writer, opts, ok: true)
+        else
+          respond(writer, opts, error: 'EBADF')
+        end
+      end
+    end
+
+    def supported_format?(f)
+      case f.to_s
+      when '', '100', '24', '32' then true
+      else false
+      end
+    end
+
+    def supported_transmission?(t)
+      case t.to_s
+      when '', 'd', 'f', 't' then true   # direct, file, tempfile
+      else false                          # 's' (shared mem) etc.
+      end
+    end
+
+    def supported_compression?(o)
+      case o.to_s
+      when '', 'z' then true   # uncompressed, or raw zlib
+      else false
+      end
+    end
+
+    # Raw-zlib inflate when the wire says `o=z`. Returns the
+    # original bytes when no compression was applied, or nil on a
+    # corrupt stream (so the caller can answer EBADDATA).
+    def inflate_if_needed(bytes, compression)
+      case compression.to_s
+      when ''  then bytes
+      when 'z' then Zlib::Inflate.inflate(bytes)
+      else          nil
+      end
+    rescue Zlib::Error
+      nil
+    end
+
+    # Tolerant base64 decode: strips whitespace (some clients
+    # line-wrap APC payloads) and returns nil on invalid input.
+    # Avoids `require 'base64'` (no longer in default gems on
+    # Ruby 3.4+) by going through `String#unpack1('m0')`.
+    #
+    # The kitty spec explicitly permits omitted padding, and
+    # `kitten icat --transfer-mode stream` splits its base64 at
+    # arbitrary byte boundaries — the *assembled* payload across
+    # all m=1 chunks can therefore end mid-quad. Pad to a multiple
+    # of 4 before strict decode so we don't silently EBADPNG.
+    def decode_payload(b64)
+      cleaned = b64.to_s.delete("\r\n\t ")
+      return ''.b if cleaned.empty?
+      pad = (4 - cleaned.bytesize % 4) % 4
+      cleaned += '=' * pad if pad > 0
+      cleaned.unpack1('m0')
+    rescue ArgumentError
+      nil
+    end
+
+    # Read image bytes off the filesystem when the wire requested
+    # `t=f` or `t=t`. Returns nil on missing / unreadable file or
+    # any read error. For `t=t` the file is unlinked after a
+    # successful read; the kitty client uses this when sending a
+    # one-shot tempfile it owns.
+    def resolve_transmission(decoded_payload, opts)
+      case opts['t'].to_s
+      when '', 'd'
+        decoded_payload
+      when 'f', 't'
+        path = decoded_payload.dup.force_encoding('UTF-8')
+        return nil if path.empty? || !File.file?(path) || !File.readable?(path)
+        data = File.binread(path)
+        File.delete(path) if opts['t'] == 't'
+        data
+      else
+        nil  # 's' / anything else — not supported
+      end
+    rescue StandardError
+      nil
+    end
+
+    # Decode an image payload to {rgba:, width:, height:}.
+    #   f=100 / unset — PNG (and anything else NSBitmapImageRep
+    #                   eats: JPEG, GIF, TIFF, BMP)
+    #   f=24          — raw RGB packed, dims from s= / v=
+    #   f=32          — raw RGBA packed, dims from s= / v=
+    def decode_image(bytes, format, opts = {})
+      case format.to_s
+      when '100', ''
+        decode_png(bytes)
+      when '24'
+        load_appkit
+        AppKitPng.from_rgb(bytes, opts['s'].to_i, opts['v'].to_i)
+      when '32'
+        load_appkit
+        AppKitPng.from_rgba(bytes, opts['s'].to_i, opts['v'].to_i)
+      end
+    end
+
+    # PNG → {rgba:, width:, height:}. Implemented in
+    # kitty_graphics_appkit.rb; loaded lazily so non-GUI tests
+    # (which don't link AppKit) still pass.
+    def decode_png(bytes)
+      load_appkit
+      AppKitPng.decode(bytes)
+    end
+
+    def load_appkit
+      require_relative 'kitty_graphics_appkit'
+    end
+
+    def cache_image(state, id, image)
+      return if id.empty?
+      state[:cache].delete(id)         # touch (LRU)
+      state[:cache][id] = image
+      state[:cache].shift while state[:cache].size > CACHE_LIMIT
+    end
+
+    def display_image(screen, image, opts)
+      return unless screen.respond_to?(:put_kitty_image)
+      raw_id = opts['i'].to_s
+      raw_id = opts['I'].to_s if raw_id.empty?
+      screen.put_kitty_image(
+        rgba:             image[:rgba],
+        width:            image[:width],
+        height:           image[:height],
+        cells_w:          (opts['c'] && !opts['c'].empty?) ? opts['c'].to_i : nil,
+        cells_h:          (opts['r'] && !opts['r'].empty?) ? opts['r'].to_i : nil,
+        # Sub-cell pixel offsets for fine alignment. The kitty spec
+        # caps these at one cell minus one pixel; we let them
+        # through as-is — the renderer clips at the cell rect, so
+        # anything larger just gets cropped.
+        px_x_offset:      opts['X'].to_i,
+        px_y_offset:      opts['Y'].to_i,
+        suppress_cursor:  opts['C'] == '1',
+        image_id:         raw_id.empty? ? nil : raw_id,
+      )
+    end
+
+    # Spec: q=0 verbose, q=1 suppress success, q=2 suppress all.
+    # We always carry `i=`/`I=` back so the client can correlate.
+    def respond(writer, opts, ok: false, error: nil)
+      return unless writer
+      quiet = opts['q'].to_s
+      return if quiet == '2'
+      return if quiet == '1' && ok
+
+      id_part =
+        if (id = opts['i']) && !id.empty? then "i=#{id}"
+        elsif (n = opts['I']) && !n.empty? then "I=#{n}"
+        else ''
+        end
+      msg = ok ? 'OK' : error.to_s
+      writer.call("\e_G#{id_part};#{msg}\e\\")
+    rescue StandardError
+      # Writing to a closed pty etc. — never let response failure
+      # break the pane.
+    end
+  end
+end

data/lib/echoes/kitty_graphics_appkit.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+require_relative 'objc'
+
+module Echoes
+  module KittyGraphics
+    # AppKit + CoreGraphics-backed PNG decoder, isolated in its own
+    # file so headless tests don't pull CoreGraphics into the
+    # process. Decoding takes raw PNG bytes through
+    # NSBitmapImageRep → CGImage → CGBitmapContext (RGBA8 layout we
+    # control), then reads the bitmap context's backing buffer as a
+    # Ruby string. Format conversion (palette PNG, 16-bit, etc.) is
+    # handled inside CoreGraphics so we always get RGBA8 out.
+    module AppKitPng
+      CG = Fiddle.dlopen('/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics')
+
+      P = ObjC::P
+      D = ObjC::D
+      L = ObjC::L
+      I = ObjC::I
+      V = ObjC::V
+
+      ColorSpaceCreateDeviceRGB = Fiddle::Function.new(
+        CG['CGColorSpaceCreateDeviceRGB'], [], P
+      )
+      ColorSpaceRelease = Fiddle::Function.new(
+        CG['CGColorSpaceRelease'], [P], V
+      )
+      # CGBitmapContextCreate(data, w, h, bitsPerComp, bytesPerRow, cs, bitmapInfo)
+      BitmapContextCreate = Fiddle::Function.new(
+        CG['CGBitmapContextCreate'], [P, L, L, L, L, P, I], P
+      )
+      # CGContextDrawImage(ctx, rect, image) — CGRect inlined as 4 doubles
+      ContextDrawImage = Fiddle::Function.new(
+        CG['CGContextDrawImage'], [P, D, D, D, D, P], V
+      )
+      ContextRelease = Fiddle::Function.new(
+        CG['CGContextRelease'], [P], V
+      )
+      # CGDataProviderCreateWithData(info, data, size, releaseCallback)
+      DataProviderCreateWithData = Fiddle::Function.new(
+        CG['CGDataProviderCreateWithData'], [P, P, L, P], P
+      )
+      DataProviderRelease = Fiddle::Function.new(
+        CG['CGDataProviderRelease'], [P], V
+      )
+      # CGImageCreate(w, h, bpc, bpp, bpr, cs, bitmapInfo, provider, decode, interp, intent)
+      ImageCreate = Fiddle::Function.new(
+        CG['CGImageCreate'], [L, L, L, L, L, P, I, P, P, I, I], P
+      )
+      ImageRelease = Fiddle::Function.new(
+        CG['CGImageRelease'], [P], V
+      )
+
+      # kCGImageAlphaNone — source RGB has no alpha channel (24bpp)
+      ALPHA_NONE               = 0
+      # kCGImageAlphaPremultipliedLast (RGBA byte order, alpha last)
+      ALPHA_PREMULTIPLIED_LAST = 1
+
+      module_function
+
+      def decode(bytes)
+        return nil if bytes.nil? || bytes.bytesize.zero?
+
+        ns_data = ObjC::MSG_PTR_1L.call(
+          ObjC.cls('NSData'), ObjC.sel('dataWithBytes:length:'),
+          Fiddle::Pointer[bytes], bytes.bytesize
+        )
+        return nil if ns_data.null?
+
+        rep = ObjC::MSG_PTR_1.call(
+          ObjC.cls('NSBitmapImageRep'),
+          ObjC.sel('imageRepWithData:'),
+          ns_data
+        )
+        return nil if rep.null?
+
+        width  = ObjC::MSG_RET_L.call(rep, ObjC.sel('pixelsWide'))
+        height = ObjC::MSG_RET_L.call(rep, ObjC.sel('pixelsHigh'))
+        return nil if width <= 0 || height <= 0
+
+        cgimage = ObjC::MSG_PTR.call(rep, ObjC.sel('CGImage'))
+        return nil if cgimage.null?
+
+        bytes_per_row = width * 4
+        buf = Fiddle::Pointer.malloc(width * height * 4, Fiddle::RUBY_FREE)
+        cs  = ColorSpaceCreateDeviceRGB.call
+        begin
+          ctx = BitmapContextCreate.call(
+            buf, width, height, 8, bytes_per_row, cs,
+            ALPHA_PREMULTIPLIED_LAST
+          )
+          return nil if ctx.null?
+          begin
+            # CoreGraphics' coordinate system has y up; PNGs decode
+            # top-down. The renderer expects pixel row 0 at the top,
+            # which matches CGContextDrawImage's natural output here
+            # because the bitmap context we created has the same
+            # orientation we'll later read from.
+            ContextDrawImage.call(ctx, 0.0, 0.0, width.to_f, height.to_f, cgimage)
+            rgba = buf.to_str(width * height * 4)
+            {rgba: rgba, width: width, height: height}
+          ensure
+            ContextRelease.call(ctx)
+          end
+        ensure
+          ColorSpaceRelease.call(cs)
+        end
+      end
+
+      # Raw 24-bit RGB → RGBA8. The wire carries width*height*3
+      # bytes; we wrap them in a CGImage (kCGImageAlphaNone, 24bpp)
+      # and draw into a fresh kCGImageAlphaPremultipliedLast context.
+      # CG fills the alpha channel with 0xFF for us, so the renderer
+      # sees the same RGBA8 shape PNGs produce.
+      def from_rgb(bytes, width, height)
+        return nil if bytes.nil? || width <= 0 || height <= 0
+        return nil if bytes.bytesize != width * height * 3
+        draw_into_rgba(bytes, width, height,
+                       bits_per_pixel: 24,
+                       bytes_per_row:  width * 3,
+                       source_bitmap_info: ALPHA_NONE)
+      end
+
+      # Raw 32-bit RGBA → RGBA8 (premultiplied). The wire carries
+      # width*height*4 bytes; treated as alpha-premultiplied to
+      # match the PNG path's output exactly.
+      def from_rgba(bytes, width, height)
+        return nil if bytes.nil? || width <= 0 || height <= 0
+        return nil if bytes.bytesize != width * height * 4
+        draw_into_rgba(bytes, width, height,
+                       bits_per_pixel: 32,
+                       bytes_per_row:  width * 4,
+                       source_bitmap_info: ALPHA_PREMULTIPLIED_LAST)
+      end
+
+      # Wrap raw pixel bytes in a CGImage, draw into a fresh
+      # premultiplied-RGBA8 CGBitmapContext. We keep a Ruby
+      # reference to `bytes` so the GC can't collect it while CG
+      # still holds the data-provider pointer.
+      def draw_into_rgba(bytes, width, height,
+                          bits_per_pixel:, bytes_per_row:, source_bitmap_info:)
+        src_ptr  = Fiddle::Pointer[bytes]
+        provider = DataProviderCreateWithData.call(nil, src_ptr, bytes.bytesize, nil)
+        return nil if provider.null?
+        cs = ColorSpaceCreateDeviceRGB.call
+        begin
+          cgimage = ImageCreate.call(width, height, 8, bits_per_pixel, bytes_per_row,
+                                     cs, source_bitmap_info, provider, nil, 0, 0)
+          return nil if cgimage.null?
+          begin
+            buf = Fiddle::Pointer.malloc(width * height * 4, Fiddle::RUBY_FREE)
+            ctx = BitmapContextCreate.call(buf, width, height, 8, width * 4, cs,
+                                           ALPHA_PREMULTIPLIED_LAST)
+            return nil if ctx.null?
+            begin
+              ContextDrawImage.call(ctx, 0.0, 0.0, width.to_f, height.to_f, cgimage)
+              rgba = buf.to_str(width * height * 4)
+              {rgba: rgba, width: width, height: height}
+            ensure
+              ContextRelease.call(ctx)
+            end
+          ensure
+            ImageRelease.call(cgimage)
+          end
+        ensure
+          ColorSpaceRelease.call(cs)
+          DataProviderRelease.call(provider)
+        end
+      end
+    end
+  end
+end

data/lib/echoes/objc.rb

@@ -35,6 +35,7 @@ module Echoes
     MSG_PTR_2     = new_msg([P, P, P, P], P)         # id = msg(id, SEL, id, id)
     MSG_PTR_L     = new_msg([P, P, L], P)            # id = msg(id, SEL, long)
     MSG_PTR_1L    = new_msg([P, P, P, L], P)           # id = msg(id, SEL, id, long)
+    MSG_PTR_L_1   = new_msg([P, P, L, P], P)           # id = msg(id, SEL, long, id)
     MSG_VOID      = new_msg([P, P], V)               # void = msg(id, SEL)
     MSG_VOID_1    = new_msg([P, P, P], V)            # void = msg(id, SEL, id)
     MSG_VOID_2    = new_msg([P, P, P, P], V)         # void = msg(id, SEL, id, id)
@@ -157,6 +158,7 @@ module Echoes
     NSForegroundColorAttributeName = appkit_const('NSForegroundColorAttributeName')
     NSUnderlineStyleAttributeName      = appkit_const('NSUnderlineStyleAttributeName')
     NSStrikethroughStyleAttributeName  = appkit_const('NSStrikethroughStyleAttributeName')
+    NSLigatureAttributeName            = appkit_const('NSLigatureAttributeName')
     NSPasteboardTypeString         = appkit_const('NSPasteboardTypeString')
     NSPasteboardTypeFileURL        = appkit_const('NSPasteboardTypeFileURL')