echoes 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 840cfd55fa04459db94048feb0ace4ac1fcd24afe1be90782f90ad10ee849c3f
-  data.tar.gz: 93f77b0d7360472791d898ceef10049a72019ef3facacbe73280648f740eb929
+  metadata.gz: 988274d532cf54ecb84bae874115f635b993e6817c259c41811b33265c55d725
+  data.tar.gz: 73f6868b563a851c1d171908f92ad7cf6ad8dd046f101c178f826a18790f8d0f
 SHA512:
-  metadata.gz: 68c56c9b24cf3bd2456cea2b559bff0d7e4a25df9562561c6d29b79b0a9f54b171074f5dcc6cbf0731336037821ddd641f95295f1bfc81ae158e080089be2210
-  data.tar.gz: 9f86318197b4796b239013d626fdbf0e2214a5fa343c215c56518fdd77f25bce3c04995929840b496dbb1d8fa61bd3c769db4eb794ea45a7d47fa6808c97b1ca
+  metadata.gz: 5120ced363551ab708776569564b96754c70d7dfe06056b3c97e0b3749e24b4fd87e060f126cacea6de655fb9b78dd1910a22eb49988b772aace46b6e0a5d99f
+  data.tar.gz: 7131de98f47c8a16d7ae6aeaef86a74af5d58412fa9c2d2b4948ee03734c97ed63d4329e186dbf83c1d4765ae148141119a20a55e4b1facfc26a7db181346dd7

data/README.md

@@ -52,6 +52,37 @@ bundle exec exe/echoes -t  # TTY mode
   Insert mode, `:w`, `:q`, search, visual mode, undo — the full vim
   surface. The dialog opens at the active pane's pwd.
 
+## Terminal features
+
+- **Images** — Kitty graphics protocol (PNG via `f=100`, raw RGB /
+  RGBA via `f=24` / `f=32`, zlib-compressed payloads with `o=z`,
+  file-path transmission via `t=f` / `t=t`, sub-cell pixel offsets,
+  placements with `q=` / `a=p` / `a=d`, `z=` for layering — negative
+  `z` blits the image beneath cell text, the default `z=0` and any
+  positive value blit on top) and iTerm2 inline images
+  (OSC 1337 `File=` with PNG / JPEG / TIFF / GIF). **SVG** is also
+  rendered by both protocols — detected by content-sniffing the
+  payload, rasterized at the cell footprint requested (`c=`/`r=` for
+  Kitty, `width=`/`height=` for iTerm2). Path-only SVGs (paths,
+  basic shapes, `<g>`, transforms) go through a native CoreGraphics
+  fast path — synchronous, no XPC. SVGs containing `<text>`,
+  `<filter>`, gradients, `<use>`, etc. fall through transparently
+  to a WKWebView backend (slower first paint, but full CSS / SVG
+  surface). JavaScript is disabled and external resources blocked
+  on both paths.
+- **Desktop notifications** — OSC 9 (`\e]9;message\a`, iTerm2 style)
+  and OSC 777 (`\e]777;notify;title;message\a`, VTE style) deliver
+  to the macOS Notification Center.
+- **Programming-font ligatures** — `=>`, `!=`, `<=`, `->`, etc. shape
+  through Core Text when the active font (Fira Code, JetBrains Mono,
+  …) ships them.
+- **Synchronized output (DEC 2026)** — full-frame updates from tmux,
+  Neovim, and IDEs land atomically instead of tearing.
+- **Find** — Cmd+F opens the search bar; while it's focused, Cmd+R
+  toggles regex mode and Cmd+I toggles case-insensitive matching.
+- **Pane capture** — a running program can snapshot its own pane to
+  disk as raster PNG or vector PDF via `\e]7772;capture` (see below).
+
 ## Keyboard shortcuts
 
 | Shortcut                  | Action                                  |
@@ -72,14 +103,84 @@ bundle exec exe/echoes -t  # TTY mode
 | Cmd+Shift+C               | Toggle copy mode                        |
 | Cmd+Ctrl+F                | Enter / leave full screen               |
 
+## Configuration
+
+Echoes reads `~/.config/echoes/echoes.conf` at startup. The file is
+plain Ruby `instance_eval`'d against `Echoes.config`; every setter
+below has the same name as its config attribute.
+
+```ruby
+font_family    "JetBrains Mono"
+font_size      14.0
+rows           24
+cols           80
+shell          "/bin/zsh"
+scrollback_limit  10_000
+tab_position   :top                # or :bottom
+window_title   "Echoes"
+foreground     "#e0e0e0"
+background     "#1a1a2e"
+cursor_color   "#b58900"
+selection_color "#586e75"
+```
+
+### Profiles (color themes)
+
+Two profiles ship built-in (Solarized Dark, Solarized Light), so the
+View → Profile submenu has alternatives without any config. Declare
+your own — or re-declare a built-in by the same name to override it.
+Switching at runtime through the menu repaints the palette, fg/bg,
+selection, and cursor without a restart.
+
+```ruby
+profile "Tokyo Night" do
+  foreground   "#c0caf5"
+  background   "#1a1b26"
+  cursor_color "#c0caf5"
+  selection_color "#283457"
+  color_palette %w[
+    #15161e #f7768e #9ece6a #e0af68 #7aa2f7 #bb9af7 #7dcfff #a9b1d6
+    #414868 #f7768e #9ece6a #e0af68 #7aa2f7 #bb9af7 #7dcfff #c0caf5
+  ]
+end
+
+default_profile "Tokyo Night"
+```
+
+### Custom keybinds
+
+Override any menu shortcut by action symbol. Pass an empty string to
+disable a default shortcut entirely.
+
+```ruby
+keybind "Cmd+Shift+T", :new_tab
+keybind "Cmd+K",       :toggle_find
+keybind "",            :toggle_pointer    # disable the default
+```
+
+Available actions (one per menu item): `:new_window`, `:new_tab`,
+`:close_tab`, `:close_pane`, `:edit_file`, `:split_right`, `:split_down`,
+`:select_next_pane`, `:select_previous_pane`, `:show_next_tab`,
+`:show_previous_tab`, `:increase_font_size`, `:decrease_font_size`,
+`:reset_font_size`, `:toggle_find`, `:find_next`, `:find_previous`,
+`:toggle_pointer`, `:toggle_copy_mode`.
+
+Modifier names are case-insensitive and accept the obvious aliases:
+`Cmd`/`Command`/`Super`, `Ctrl`/`Control`, `Opt`/`Option`/`Alt`, `Shift`.
+
 ## OSC extensions
 
-Echoes recognizes a private OSC namespace under code `7772`. Other
-terminals ignore unknown OSC codes, so emitters degrade gracefully.
+### Echoes private namespace (OSC 7772)
+
+All Echoes-specific escape sequences live under OSC code `7772`.
+Other terminals ignore unknown OSC codes, so emitters degrade
+gracefully.
+
+**Background painting** (pane-scoped):
 
 ```
 \e]7772;bg-color;#rrggbb\a
-\e]7772;bg-gradient;type=linear:angle=N:colors=#rrggbb,#rrggbb\a
+\e]7772;bg-gradient;type=linear:angle=N:colors=#rrggbb,#rrggbb[,...]\a
 \e]7772;bg-fill;color=#rrggbb:rect=row1,col1,row2,col2\a
 \e]7772;bg-clear\a
 ```
@@ -89,15 +190,54 @@ slide layout (header bar, sidebar, accent stripe) on top of a base
 `bg-color` or `bg-gradient`. `bg-clear` wipes both the base layer
 and all fills.
 
-OSC 66 is also extended:
+**Multicell glyphs** (OSC-66-shaped, with Echoes-only knobs):
+
+```
+\e]7772;multicell;<key=value:...>;<text>\a
+```
+
+Accepts the standard kitty `s/w/n/d/v/h` keys plus:
+
+- `f=Family Name` — render the glyph(s) in a specific font.
+  Proportional fonts (Helvetica, Noto Serif, …) are measured
+  per-glyph at layout time so the cells reserved match the actual
+  rendered width — `Hello` in Noto Serif at 2× lays out cleanly
+  without overflow or gaps.
+- `flip=h|v|hv` — mirror the rendered glyph(s) horizontally,
+  vertically, or both. Handy for direction-having emojis (e.g.
+  flipping 🐇 to face the other way).
+
+`h=` (halign) is honored for non-fractional / proportional text:
+the whole string lands in an `s × source_chars` cell block with
+the renderer's center / right-align math applied.
 
-- `f=Family Name` selects a font family for the multicell glyph.
-  Proportional fonts are measured per-glyph at layout time so the
-  cells reserved match the actual rendered width — `Hello` in Noto
-  Serif at 2× lays out cleanly without overflow or gaps.
-- `h=` (halign) is honored for non-fractional / proportional text:
-  the whole string lands in a `s × source_chars` cell block, with
-  the renderer's existing center / right-align math applied.
+These knobs are routed through OSC 7772 rather than OSC 66 so a
+future kitty-spec extension claiming the same param names can't
+collide with ours.
+
+**Pane snapshots, multi-display, child windows**:
+
+```
+\e]7772;capture;<absolute-path.png|.pdf>\a
+\e]7772;display-info\a
+\e]7772;open-window;display=N:program=<base64-argv>:fullscreen=yes|no\a
+```
+
+- `capture` writes a snapshot of the active pane to disk. `.png`
+  rasterizes via `NSBitmapImageRep`; anything else (default `.pdf`)
+  saves vector — usually smaller and crisper because text and
+  background gradients stay resolution-independent.
+- `display-info` is a sync query: the host replies on the same pty
+  with `\e]7772;display-info;<json>\a`, where `<json>` is an array
+  of `{index, w, h, primary, current}` per `NSScreen`. A presentation
+  tool uses `current` to pick "anywhere but here" for a second-screen
+  slide window.
+- `open-window` spawns a child program in a new Echoes window on the
+  chosen display. `program` is the argv JSON-encoded then
+  base64-wrapped (e.g. `Base64.strict_encode64(JSON.dump(argv))`).
+  `fullscreen=yes` uses a borderless, above-menu-bar window covering
+  the full screen frame; otherwise the visible frame with default
+  chrome.
 
 A small Ruby helper (`Echoes::Client`) lets in-pane Ruby tools emit
 these without hand-rolling escape sequences:
@@ -108,9 +248,36 @@ require 'echoes/client'
 Echoes::Client.bg_gradient(from: '#1a1a2e', to: '#16213e', angle: 90)
 Echoes::Client.bg_fill('#ff6b35', row1: 0, col1: 0, row2: 2, col2: 79)
 Echoes::Client.styled_text("Title", scale: 3, family: "Helvetica Neue")
+Echoes::Client.capture("/tmp/slide.pdf")
 Echoes::Client.bg_clear
 ```
 
+`Echoes::Client.styled_text` auto-routes: OSC 66 when only standard
+knobs are used (portable), OSC 7772 `;multicell` when an Echoes-only
+knob like `family:` is set.
+
+### Compatibility with other terminals
+
+| Code                 | Use                                                       |
+|----------------------|-----------------------------------------------------------|
+| OSC 4 / 10 / 11 / 12 | Get/set 256-color palette + default fg / bg / cursor      |
+| OSC 7                | Working directory (`file://host/path`)                    |
+| OSC 9                | iTerm2-style notification — `\e]9;message\a`              |
+| OSC 52               | Clipboard read/write                                      |
+| OSC 66               | Kitty multicell (standard `s/w/n/d/v/h` only)             |
+| OSC 133              | Semantic prompts (FinalTerm / iTerm2 style)               |
+| OSC 777              | VTE-style notification — `\e]777;notify;title;message\a`  |
+| OSC 1337             | iTerm2 inline images — `\e]1337;File=<args>:<base64>\a`   |
+| APC `_G…`            | Kitty graphics protocol (PNG, raw RGB/RGBA, zlib, file)   |
+| (sniffed)            | SVG payloads — auto-detected in both image protocols      |
+| DECSET 2026          | Synchronized output                                       |
+
+OSC 9 / OSC 777 notifications go through `terminal-notifier` when it's
+on `$PATH`, otherwise fall back to `osascript`'s `display notification`
+primitive. Echoes-only knobs that would otherwise extend OSC 66 (font
+family, mirror flips) live on OSC 7772 `;multicell` instead, so portable
+emitters can keep OSC 66 strictly kitty-spec compatible.
+
 ## Development
 
 ```sh

data/lib/echoes/gui.rb

@@ -1040,6 +1040,19 @@ module Echoes
       draw_pane_background(screen.background, px, py, pane_cols, pane_rows) if screen.background
       draw_pane_fills(screen.bg_fills, px, py, pane_cols, pane_rows) if screen.bg_fills && !screen.bg_fills.empty?
 
+      # Kitty graphics z<0 placements blit BEFORE cells, so cell glyphs
+      # (and explicit cell bg fills) draw on top. Sorted ascending by
+      # z so a less-negative z stacks atop a more-negative one. Cells
+      # with the default (transparent) bg skip the fill rect — the
+      # placement shows through; cells with an explicit ANSI bg paint
+      # opaque and occlude the placement at those cells.
+      below = screen.placements.select { |pl| pl[:z_index].to_i < 0 }
+      if !below.empty?
+        below.sort_by { |pl| pl[:z_index].to_i }.each do |pl|
+          blit_kitty_placement(pl, px, py, pane_rows)
+        end
+      end
+
       pane_rows.times do |r|
         y = py + r * @cell_height
         next if y + @cell_height < dirty_min_y || y > dirty_max_y
@@ -1308,15 +1321,17 @@ module Echoes
         flush_run.call
       end
 
-      # Re-blit kitty graphics placements ON TOP of the rendered
-      # cells. Anchors are stored as logical cell coords on the
-      # Screen; we convert to pixels here using current cell
-      # metrics so font-size and pane-resize changes pick up the
-      # right pixel position automatically — placements need no
-      # bookkeeping when @cell_width / @cell_height shift.
-      screen.placements.each do |pl|
-        blit_kitty_placement(pl, px, py, pane_rows)
-      end
+      # Re-blit kitty graphics z>=0 placements ON TOP of the rendered
+      # cells. (z<0 placements were drawn above before the cell loop,
+      # so cell text appears in front of them.) Anchors are stored as
+      # logical cell coords on the Screen; we convert to pixels here
+      # using current cell metrics so font-size and pane-resize changes
+      # pick up the right pixel position automatically — placements
+      # need no bookkeeping when @cell_width / @cell_height shift.
+      screen.placements
+        .select { |pl| pl[:z_index].to_i >= 0 }
+        .sort_by { |pl| pl[:z_index].to_i }
+        .each { |pl| blit_kitty_placement(pl, px, py, pane_rows) }
 
       # Draw cursor or copy mode cursor
       if copy_mode&.active

data/lib/echoes/iterm2_images.rb

@@ -41,7 +41,11 @@ module Echoes
       bytes = decode_payload(payload_b64)
       return nil unless bytes
 
-      image = decode_image(bytes)
+      image = if svg?(bytes)
+                decode_svg(bytes, params, screen)
+              else
+                decode_image(bytes)
+              end
       return nil unless image
 
       cells_w, cells_h = compute_cell_dimensions(params, image, screen)
@@ -86,6 +90,57 @@ module Echoes
       KittyGraphics::AppKitPng.decode(bytes)
     end
 
+    # SVG → {rgba:, width:, height:}. Computes the target pixel size
+    # from the wire-format width / height (cells, px, or %) before
+    # rasterizing, because the renderer needs an explicit target —
+    # vector input has no intrinsic raster dimensions.
+    def decode_svg(bytes, params, screen)
+      require_relative 'svg_renderer'
+      w, h = svg_target_pixels(params, screen, bytes)
+      SvgRenderer.rasterize(bytes, width: w, height: h)
+    end
+
+    def svg?(bytes)
+      require_relative 'svg_sniffer'
+      SvgSniffer.svg?(bytes)
+    end
+
+    # Pick the rasterization target. Priority:
+    #   1. Explicit wire dim from the client (cells × cell_px, Npx, or %)
+    #   2. Intrinsic width/height/viewBox parsed from the <svg> tag
+    #   3. 512² fallback
+    # Capped at 4096 per axis so a runaway `viewBox="0 0 1e6 1e6"`
+    # can't ask for gigabyte buffers.
+    def svg_target_pixels(params, screen, bytes)
+      cell_w = screen.cell_pixel_width.to_f
+      cell_h = screen.cell_pixel_height.to_f
+      w = svg_dim_to_pixels(params['width'],  cell_w, screen.cols)
+      h = svg_dim_to_pixels(params['height'], cell_h, screen.rows)
+      if w.nil? || h.nil?
+        iw, ih = SvgSniffer.intrinsic_size(bytes)
+        w ||= iw if iw
+        h ||= ih if ih
+      end
+      w ||= 512
+      h ||= 512
+      [w.clamp(1, 4096), h.clamp(1, 4096)]
+    end
+
+    def svg_dim_to_pixels(value, cell_px, screen_size)
+      return nil if value.nil? || value.empty? || value == 'auto'
+      if value.end_with?('px')
+        n = value.to_f
+        n.positive? ? n.round : nil
+      elsif value.end_with?('%')
+        return nil if cell_px <= 0
+        (screen_size * value.to_f / 100.0 * cell_px).round
+      else
+        return nil if cell_px <= 0
+        n = value.to_f
+        n.positive? ? (n * cell_px).round : nil
+      end
+    end
+
     # Translate the wire's `width=` / `height=` into cell counts
     # for the renderer. Supported forms (per iTerm2 docs):
     #   N      — N character cells

data/lib/echoes/kitty_graphics.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'zlib'
+require_relative 'svg_sniffer'
 
 module Echoes
   # Minimum-viable Kitty graphics protocol decoder. Wire format:
@@ -98,7 +99,7 @@ module Echoes
         bytes = inflate_if_needed(bytes, opts['o'])
         return respond(writer, opts, error: 'EBADDATA') unless bytes
 
-        image = decode_image(bytes, opts['f'] || DEFAULT_FORMAT, opts)
+        image = decode_image(bytes, opts['f'] || DEFAULT_FORMAT, opts, screen: screen)
         return respond(writer, opts, error: 'EBADPNG') unless image
 
         cache_image(state, opts['i'] || opts['I'] || '', image)
@@ -240,11 +241,13 @@ module Echoes
     end
 
     # Decode an image payload to {rgba:, width:, height:}.
+    #   <sniffed SVG> — render via WKWebView regardless of f=
     #   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 = {})
+    def decode_image(bytes, format, opts = {}, screen: nil)
+      return decode_svg(bytes, opts, screen) if SvgSniffer.svg?(bytes)
       case format.to_s
       when '100', ''
         decode_png(bytes)
@@ -257,6 +260,44 @@ module Echoes
       end
     end
 
+    # SVG → {rgba:, width:, height:}. Picks the rasterization target
+    # before handing off to SvgRenderer (vector input has no intrinsic
+    # raster size, so the renderer needs explicit pixel dims).
+    def decode_svg(bytes, opts, screen)
+      require_relative 'svg_renderer'
+      w, h = svg_target_pixels(opts, screen, bytes)
+      SvgRenderer.rasterize(bytes, width: w, height: h)
+    end
+
+    # Priority: explicit pixels (s= / v=) → explicit cells (c= / r=)
+    # × cell pixel size → SVG intrinsic → 512² fallback. Capped at
+    # 4096 per axis so a runaway `viewBox="0 0 1e6 1e6"` can't ask
+    # for gigabyte buffers.
+    def svg_target_pixels(opts, screen, bytes)
+      cell_w = screen&.cell_pixel_width.to_f
+      cell_h = screen&.cell_pixel_height.to_f
+      w = svg_explicit_pixels(opts['s'], opts['c'], cell_w)
+      h = svg_explicit_pixels(opts['v'], opts['r'], cell_h)
+      if w.nil? || h.nil?
+        iw, ih = SvgSniffer.intrinsic_size(bytes)
+        w ||= iw if iw
+        h ||= ih if ih
+      end
+      w ||= 512
+      h ||= 512
+      [w.clamp(1, 4096), h.clamp(1, 4096)]
+    end
+
+    def svg_explicit_pixels(px_val, cell_val, cell_px)
+      if px_val && !px_val.empty? && px_val.to_i > 0
+        return px_val.to_i
+      end
+      if cell_val && !cell_val.empty? && cell_val.to_i > 0 && cell_px > 0
+        return (cell_val.to_i * cell_px).round
+      end
+      nil
+    end
+
     # PNG → {rgba:, width:, height:}. Implemented in
     # kitty_graphics_appkit.rb; loaded lazily so non-GUI tests
     # (which don't link AppKit) still pass.
@@ -294,6 +335,10 @@ module Echoes
         px_y_offset:      opts['Y'].to_i,
         suppress_cursor:  opts['C'] == '1',
         image_id:         raw_id.empty? ? nil : raw_id,
+        # z<0 layers the image beneath cell text (the GUI splits the
+        # placement blit into pre-cell and post-cell passes by z sign);
+        # z>=0 (the spec default of 0 included) layers on top.
+        z_index:          opts['z'].to_i,
       )
     end
 

data/lib/echoes/kitty_graphics_appkit.rb

@@ -83,6 +83,20 @@ module Echoes
         cgimage = ObjC::MSG_PTR.call(rep, ObjC.sel('CGImage'))
         return nil if cgimage.null?
 
+        cgimage_to_rgba(cgimage, width, height)
+      end
+
+      # Draw a CGImage into a fresh premultiplied-RGBA8 bitmap context
+      # and return the raw pixel buffer as {rgba:, width:, height:}.
+      # Shared between the PNG decoder and SvgRenderer (which gets its
+      # CGImage from a WKWebView snapshot rather than NSBitmapImageRep).
+      # Returns nil if the bitmap context can't be allocated.
+      #
+      # 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.
+      def cgimage_to_rgba(cgimage, width, height)
         bytes_per_row = width * 4
         buf = Fiddle::Pointer.malloc(width * height * 4, Fiddle::RUBY_FREE)
         cs  = ColorSpaceCreateDeviceRGB.call
@@ -93,11 +107,6 @@ module Echoes
           )
           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}

data/lib/echoes/objc.rb

@@ -174,12 +174,59 @@ module Echoes
     CGContextRestoreGState      = Fiddle::Function.new(COREGRAPHICS['CGContextRestoreGState'], [P], V)
     CGContextTranslateCTM       = Fiddle::Function.new(COREGRAPHICS['CGContextTranslateCTM'], [P, D, D], V)
     CGContextScaleCTM           = Fiddle::Function.new(COREGRAPHICS['CGContextScaleCTM'], [P, D, D], V)
+    CGContextRotateCTM          = Fiddle::Function.new(COREGRAPHICS['CGContextRotateCTM'], [P, D], V)
+    # CGAffineTransform inlined as 6 doubles (a, b, c, d, tx, ty).
+    CGContextConcatCTM          = Fiddle::Function.new(COREGRAPHICS['CGContextConcatCTM'], [P, D, D, D, D, D, D], V)
+    CGContextClearRect          = Fiddle::Function.new(COREGRAPHICS['CGContextClearRect'], [P, D, D, D, D], V)
     CGImageRelease              = Fiddle::Function.new(COREGRAPHICS['CGImageRelease'], [P], V)
     CGContextRelease            = Fiddle::Function.new(COREGRAPHICS['CGContextRelease'], [P], V)
 
+    # Path construction
+    CGContextBeginPath          = Fiddle::Function.new(COREGRAPHICS['CGContextBeginPath'], [P], V)
+    CGContextMoveToPoint        = Fiddle::Function.new(COREGRAPHICS['CGContextMoveToPoint'], [P, D, D], V)
+    CGContextAddLineToPoint     = Fiddle::Function.new(COREGRAPHICS['CGContextAddLineToPoint'], [P, D, D], V)
+    CGContextAddCurveToPoint    = Fiddle::Function.new(COREGRAPHICS['CGContextAddCurveToPoint'], [P, D, D, D, D, D, D], V)
+    CGContextAddQuadCurveToPoint = Fiddle::Function.new(COREGRAPHICS['CGContextAddQuadCurveToPoint'], [P, D, D, D, D], V)
+    # CGContextAddArc(ctx, x, y, radius, startAngle, endAngle, clockwise)
+    CGContextAddArc             = Fiddle::Function.new(COREGRAPHICS['CGContextAddArc'], [P, D, D, D, D, D, I], V)
+    CGContextClosePath          = Fiddle::Function.new(COREGRAPHICS['CGContextClosePath'], [P], V)
+
+    # Paint state
+    CGContextSetRGBFillColor    = Fiddle::Function.new(COREGRAPHICS['CGContextSetRGBFillColor'], [P, D, D, D, D], V)
+    CGContextSetRGBStrokeColor  = Fiddle::Function.new(COREGRAPHICS['CGContextSetRGBStrokeColor'], [P, D, D, D, D], V)
+    CGContextSetAlpha           = Fiddle::Function.new(COREGRAPHICS['CGContextSetAlpha'], [P, D], V)
+    CGContextSetLineWidth       = Fiddle::Function.new(COREGRAPHICS['CGContextSetLineWidth'], [P, D], V)
+    CGContextSetLineCap         = Fiddle::Function.new(COREGRAPHICS['CGContextSetLineCap'], [P, I], V)
+    CGContextSetLineJoin        = Fiddle::Function.new(COREGRAPHICS['CGContextSetLineJoin'], [P, I], V)
+    CGContextSetMiterLimit      = Fiddle::Function.new(COREGRAPHICS['CGContextSetMiterLimit'], [P, D], V)
+
+    # Path rasterization
+    CGContextFillPath           = Fiddle::Function.new(COREGRAPHICS['CGContextFillPath'], [P], V)
+    CGContextEOFillPath         = Fiddle::Function.new(COREGRAPHICS['CGContextEOFillPath'], [P], V)
+    CGContextStrokePath         = Fiddle::Function.new(COREGRAPHICS['CGContextStrokePath'], [P], V)
+    # CGContextDrawPath(ctx, mode) — mode picks fill / EO-fill / stroke / fill+stroke.
+    CGContextDrawPath           = Fiddle::Function.new(COREGRAPHICS['CGContextDrawPath'], [P, I], V)
+
     # kCGImageAlphaPremultipliedLast | kCGBitmapByteOrderDefault
     KCGImageAlphaPremultipliedLast = 1
 
+    # CGPathDrawingMode
+    KCG_PATH_FILL          = 0
+    KCG_PATH_EO_FILL       = 1
+    KCG_PATH_STROKE        = 2
+    KCG_PATH_FILL_STROKE   = 3
+    KCG_PATH_EO_FILL_STROKE = 4
+
+    # CGLineCap
+    KCG_LINE_CAP_BUTT    = 0
+    KCG_LINE_CAP_ROUND   = 1
+    KCG_LINE_CAP_SQUARE  = 2
+
+    # CGLineJoin
+    KCG_LINE_JOIN_MITER = 0
+    KCG_LINE_JOIN_ROUND = 1
+    KCG_LINE_JOIN_BEVEL = 2
+
     # CoreText framework
     CORETEXT = Fiddle.dlopen('/System/Library/Frameworks/CoreText.framework/CoreText')
 

data/lib/echoes/screen.rb

@@ -235,7 +235,7 @@ module Echoes
     # rather than introducing a parallel `:image` key.
     def put_kitty_image(rgba:, width:, height:, cells_w: nil, cells_h: nil,
                          px_x_offset: 0, px_y_offset: 0,
-                         suppress_cursor: false, image_id: nil)
+                         suppress_cursor: false, image_id: nil, z_index: 0)
       return if rgba.nil? || width <= 0 || height <= 0
       return if @cell_pixel_width.to_f <= 0 || @cell_pixel_height.to_f <= 0
 
@@ -314,6 +314,7 @@ module Echoes
         cell_rows:  mc_rows,
         x_off:      px_x_offset.to_i,
         y_off:      px_y_offset.to_i,
+        z_index:    z_index.to_i,
         image:      {rgba: rgba, width: width, height: height},
       }