echoes 0.3.0 → 0.4.0

data/lib/echoes/svg_color.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Echoes
+  # SVG color parser for the CG fast-path renderer. Returns
+  # [r, g, b, a] (each 0..1), :none ("don't paint this stroke/fill"),
+  # or nil ("unsupported — bail to WKWebView").
+  module SvgColor
+    # 20 CSS / SVG named colors covering the common cases. Anything
+    # outside this set returns nil so the caller falls through to
+    # the WKWebView renderer (which has the full CSS palette).
+    NAMED = {
+      'black'       => [  0,   0,   0],
+      'white'       => [255, 255, 255],
+      'red'         => [255,   0,   0],
+      'green'       => [  0, 128,   0],
+      'blue'        => [  0,   0, 255],
+      'yellow'      => [255, 255,   0],
+      'cyan'        => [  0, 255, 255],
+      'aqua'        => [  0, 255, 255],
+      'magenta'     => [255,   0, 255],
+      'fuchsia'     => [255,   0, 255],
+      'gray'        => [128, 128, 128],
+      'grey'        => [128, 128, 128],
+      'orange'      => [255, 165,   0],
+      'purple'      => [128,   0, 128],
+      'pink'        => [255, 192, 203],
+      'brown'       => [165,  42,  42],
+      'lime'        => [  0, 255,   0],
+      'navy'        => [  0,   0, 128],
+      'teal'        => [  0, 128, 128],
+      'silver'      => [192, 192, 192],
+      'maroon'      => [128,   0,   0],
+      'olive'       => [128, 128,   0],
+    }.freeze
+
+    HEX_RE = /\A#([0-9a-f]{3,8})\z/i
+    RGB_RE = /\Argba?\(\s*([^)]*)\)\z/i
+
+    module_function
+
+    def parse(str, current_color: [0.0, 0.0, 0.0, 1.0])
+      return nil if str.nil?
+      s = str.strip
+      return nil if s.empty?
+
+      down = s.downcase
+      return :none                if down == 'none'
+      return current_color.dup    if down == 'currentcolor'
+      return [0.0, 0.0, 0.0, 0.0] if down == 'transparent'
+
+      if (m = NAMED[down])
+        return [m[0] / 255.0, m[1] / 255.0, m[2] / 255.0, 1.0]
+      end
+
+      if (m = HEX_RE.match(s))
+        return parse_hex(m[1])
+      end
+
+      if (m = RGB_RE.match(s))
+        return parse_rgb_func(m[1])
+      end
+
+      nil
+    end
+
+    def parse_hex(hex)
+      case hex.length
+      when 3
+        r, g, b = hex.chars.map { |c| (c + c).to_i(16) }
+        [r / 255.0, g / 255.0, b / 255.0, 1.0]
+      when 4
+        r, g, b, a = hex.chars.map { |c| (c + c).to_i(16) }
+        [r / 255.0, g / 255.0, b / 255.0, a / 255.0]
+      when 6
+        r = hex[0, 2].to_i(16)
+        g = hex[2, 2].to_i(16)
+        b = hex[4, 2].to_i(16)
+        [r / 255.0, g / 255.0, b / 255.0, 1.0]
+      when 8
+        r = hex[0, 2].to_i(16)
+        g = hex[2, 2].to_i(16)
+        b = hex[4, 2].to_i(16)
+        a = hex[6, 2].to_i(16)
+        [r / 255.0, g / 255.0, b / 255.0, a / 255.0]
+      else
+        nil
+      end
+    end
+
+    # Parse the body of `rgb(...)` or `rgba(...)`. Components can be
+    # int 0..255 or `N%` (0..100). Alpha (if present) is a plain
+    # 0..1 float, not a percentage.
+    def parse_rgb_func(inner)
+      parts = inner.split(',').map(&:strip)
+      return nil unless parts.size == 3 || parts.size == 4
+      rgb = parts[0, 3].map { |p| parse_component(p) }
+      return nil if rgb.any?(&:nil?)
+      a = if parts.size == 4
+            f = Float(parts[3]) rescue nil
+            return nil if f.nil?
+            f.clamp(0.0, 1.0)
+          else
+            1.0
+          end
+      [*rgb, a]
+    end
+
+    def parse_component(p)
+      if p.end_with?('%')
+        f = Float(p[0..-2]) rescue nil
+        return nil if f.nil?
+        (f / 100.0).clamp(0.0, 1.0)
+      else
+        i = Integer(p, 10) rescue nil
+        return nil if i.nil?
+        (i / 255.0).clamp(0.0, 1.0)
+      end
+    end
+  end
+end

data/lib/echoes/svg_path_parser.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Echoes
+  # Tokenizer / parser for the `<path d="...">` mini-language.
+  # Returns an ordered list of `[cmd_symbol, [args…]]` tuples.
+  #
+  # Uppercase cmd_symbols (:M, :L, :C, …) are absolute; lowercase
+  # (:m, :l, :c, …) are relative — the renderer applies the
+  # absolute-vs-relative interpretation since both forms have the
+  # same operand counts.
+  #
+  # Returns nil on:
+  #   - empty / nil input
+  #   - first command isn't M or m (spec violation; no current point)
+  #   - unknown command letter
+  #   - operand-count mismatch (e.g. trailing partial group)
+  #   - any tokenizer leftover (unrecognized character)
+  module SvgPathParser
+    # Operand count per command, per spec.
+    OPERAND_COUNT = {
+      M: 2, m: 2,
+      L: 2, l: 2,
+      H: 1, h: 1,
+      V: 1, v: 1,
+      C: 6, c: 6,
+      S: 4, s: 4,
+      Q: 4, q: 4,
+      T: 2, t: 2,
+      A: 7, a: 7,
+      Z: 0, z: 0,
+    }.freeze
+
+    # Implicit continuation: after consuming a command's operands, if
+    # there are more numbers without a new command letter, reuse the
+    # last command — except M/m, where the implicit continuation is
+    # L/l per spec ("Subsequent pairs are treated as implicit lineto
+    # commands").
+    IMPLICIT_CONTINUATION = {M: :L, m: :l}.freeze
+
+    # Token regex: matches a command letter (excluding E/e which are
+    # reserved for scientific-notation exponents) OR a number.
+    # Number form: optional sign, then digits-and-optional-decimal or
+    # leading-decimal, with optional scientific notation. Whitespace
+    # and commas between tokens are silently skipped by the scanner.
+    TOKEN_RE = /
+      ([MmLlHhVvCcSsQqTtAaZz]) |
+      ([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)
+    /x
+
+    module_function
+
+    def parse(d)
+      return nil if d.nil?
+      tokens = tokenize(d)
+      return nil if tokens.nil? || tokens.empty?
+
+      # First token must be M or m.
+      first = tokens.first
+      return nil unless first.is_a?(Symbol) && (first == :M || first == :m)
+
+      ops = []
+      i = 0
+      last_cmd = nil
+      while i < tokens.size
+        tok = tokens[i]
+        if tok.is_a?(Symbol)
+          cmd = tok
+          i += 1
+        else
+          return nil unless last_cmd
+          cmd = IMPLICIT_CONTINUATION[last_cmd] || last_cmd
+        end
+
+        arity = OPERAND_COUNT[cmd]
+        return nil unless arity
+
+        if arity.zero?
+          ops << [cmd, []]
+          last_cmd = cmd
+          next
+        end
+
+        args = tokens[i, arity]
+        return nil if args.size < arity
+        return nil if args.any? { |t| t.is_a?(Symbol) }
+
+        ops << [cmd, args]
+        i += arity
+        last_cmd = cmd
+      end
+
+      ops
+    end
+
+    # Scan the string for tokens, ensuring we account for every
+    # non-whitespace, non-comma character. If any junk is left,
+    # returns nil so the caller can bail.
+    def tokenize(d)
+      tokens = []
+      pos = 0
+      bytes = d.b
+      while pos < bytes.length
+        # Skip separators (whitespace, comma).
+        if (m = /\G[\s,]+/.match(bytes, pos))
+          pos = m.end(0)
+          next
+        end
+        m = TOKEN_RE.match(bytes, pos)
+        return nil unless m && m.begin(0) == pos
+        if m[1]
+          tokens << m[1].to_sym
+        else
+          tokens << m[2].to_f
+        end
+        pos = m.end(0)
+      end
+      tokens
+    end
+  end
+end

data/lib/echoes/svg_renderer.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+require_relative 'objc'
+require_relative 'kitty_graphics_appkit'
+
+module Echoes
+  # SVG → RGBA8 rasterizer backed by WKWebView. The Kitty graphics
+  # and iTerm2 inline-image protocols both detect SVG payloads via
+  # SvgSniffer and route here instead of NSBitmapImageRep (which
+  # can't decode vector formats).
+  #
+  # WebKit's snapshot API is async, but the decoders are synchronous.
+  # We bridge by pumping a nested NSRunLoop until the completion
+  # handler fires, with a hard per-call timeout so a runaway SVG
+  # can't hang the GUI. Re-entrant calls during the pump are
+  # short-circuited by a recursion guard.
+  #
+  # JavaScript is disabled and baseURL is nil so the SVG sandbox
+  # can't execute scripts or fetch external resources.
+  module SvgRenderer
+    WEBKIT     = Fiddle.dlopen('/System/Library/Frameworks/WebKit.framework/WebKit')
+    LIBSYSTEM  = Fiddle.dlopen('/usr/lib/libSystem.B.dylib')
+    COREGRAPHICS = Fiddle.dlopen('/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics')
+
+    P = ObjC::P
+    D = ObjC::D
+    L = ObjC::L
+    I = ObjC::I
+    V = ObjC::V
+
+    # `initWithFrame:configuration:` — CGRect (4 doubles) + id.
+    MSG_PTR_RECT_1 = ObjC.new_msg([P, P, D, D, D, D, P], P)
+
+    # CG functions for snapshot pixel-dim lookup.
+    CGImageGetWidth  = Fiddle::Function.new(COREGRAPHICS['CGImageGetWidth'],  [P], L)
+    CGImageGetHeight = Fiddle::Function.new(COREGRAPHICS['CGImageGetHeight'], [P], L)
+
+    # Foundation exports NSDefaultRunLoopMode as an NSString* symbol.
+    # Same dereference-the-symbol trick as ObjC.appkit_const, just
+    # against Foundation instead of AppKit.
+    NS_DEFAULT_RUN_LOOP_MODE = begin
+      sym_ptr = Fiddle::Pointer.new(ObjC::FOUNDATION['NSDefaultRunLoopMode'])
+      Fiddle::Pointer.new(sym_ptr[0, Fiddle::SIZEOF_VOIDP].unpack1('J'))
+    end
+
+    # Objective-C global block plumbing. Snapshot's completion handler
+    # is `void (^)(NSImage *, NSError *)`, which we fabricate via Fiddle
+    # by building a Block_layout struct that points at a Fiddle closure.
+    # Global blocks live forever and never copy/dispose, so the layout
+    # is minimal.
+    NS_CONCRETE_GLOBAL_BLOCK = Fiddle::Pointer.new(LIBSYSTEM['_NSConcreteGlobalBlock'])
+    BLOCK_HAS_STRET = 1 << 29     # not set
+    BLOCK_HAS_SIGNATURE = 1 << 30 # not set; we omit the type signature
+    BLOCK_IS_GLOBAL = 1 << 28
+
+    @rendering = false
+    @web_view = nil
+    @configuration = nil
+    @delegate_class = nil
+    @delegate_instance = nil
+
+    # Snapshot completion handler state, captured by the global block's
+    # invoke closure. Per-call values are stashed in instance variables
+    # because the block can only carry a stable function pointer.
+    @snap_image = nil
+    @snap_error = false
+    @snap_done = false
+    @nav_done = false
+    @nav_error = false
+
+    # Build the global block once at module load. The same block is
+    # passed to every takeSnapshotWithConfiguration: call; the per-call
+    # result is read back through module state.
+    @snap_invoke_closure = Fiddle::Closure::BlockCaller.new(
+      V, [P, P, P]
+    ) do |_block, image_ptr, error_ptr|
+      @snap_image = image_ptr.null? ? nil : image_ptr
+      @snap_error = !error_ptr.null?
+      @snap_done = true
+    end
+
+    @snap_block_descriptor = Fiddle::Pointer.malloc(16, Fiddle::RUBY_FREE)
+    @snap_block_descriptor[0, 8]  = [0].pack('Q')   # reserved
+    @snap_block_descriptor[8, 8]  = [32].pack('Q')  # sizeof(Block_layout)
+
+    @snap_block = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+    @snap_block[0, 8]  = [NS_CONCRETE_GLOBAL_BLOCK.to_i].pack('Q')
+    @snap_block[8, 4]  = [BLOCK_IS_GLOBAL].pack('l')
+    @snap_block[12, 4] = [0].pack('l')
+    @snap_block[16, 8] = [@snap_invoke_closure.to_i].pack('Q')
+    @snap_block[24, 8] = [@snap_block_descriptor.to_i].pack('Q')
+
+    class << self
+      # Returns {rgba:, width:, height:} or nil. `width` and `height`
+      # are the target pixel dimensions for the rasterized output;
+      # the renderer respects them via the WKWebView frame, but the
+      # final pixel count may exceed them on Retina displays (we use
+      # whatever the snapshot reports back).
+      #
+      # Tries the native CoreGraphics renderer first (fast, synchronous,
+      # no WebContent XPC process); falls back to WKWebView when the
+      # SVG uses anything outside that subset (text, filters, gradients,
+      # etc.) — see SvgCgRenderer for the precise contract.
+      def rasterize(svg_bytes, width:, height:)
+        return nil if svg_bytes.nil? || svg_bytes.empty?
+        return nil if width <= 0 || height <= 0
+        return nil if @rendering   # recursion guard — nested runloop can re-enter
+        @rendering = true
+
+        begin
+          require_relative 'svg_cg_renderer'
+          fast = SvgCgRenderer.rasterize(svg_bytes, width: width, height: height)
+          return fast if fast
+
+          ensure_setup
+          html = build_html(svg_bytes)
+
+          ObjC::MSG_VOID_2D.call(@web_view, ObjC.sel('setFrameSize:'),
+                                 width.to_f, height.to_f)
+
+          @nav_done = false
+          @nav_error = false
+          @snap_done = false
+          @snap_error = false
+          @snap_image = nil
+
+          ObjC::MSG_VOID_2.call(@web_view, ObjC.sel('loadHTMLString:baseURL:'),
+                                ObjC.nsstring(html), Fiddle::Pointer.new(0))
+
+          return nil unless pump_until(2.0) { @nav_done }
+          return nil if @nav_error
+
+          snap_config = build_snapshot_config(width, height)
+          ObjC::MSG_VOID_2.call(@web_view,
+                                ObjC.sel('takeSnapshotWithConfiguration:completionHandler:'),
+                                snap_config, @snap_block)
+
+          return nil unless pump_until(2.0) { @snap_done }
+          return nil if @snap_error || @snap_image.nil?
+
+          cgimage = ns_image_to_cgimage(@snap_image, width, height)
+          return nil if cgimage.nil? || cgimage.null?
+
+          w_px = CGImageGetWidth.call(cgimage)
+          h_px = CGImageGetHeight.call(cgimage)
+          return nil if w_px <= 0 || h_px <= 0
+
+          KittyGraphics::AppKitPng.cgimage_to_rgba(cgimage, w_px, h_px)
+        rescue StandardError => e
+          warn "echoes SvgRenderer: #{e.class}: #{e.message}"
+          nil
+        ensure
+          @rendering = false
+        end
+      end
+
+      private
+
+      def ensure_setup
+        return if @web_view
+        @configuration = ObjC::MSG_PTR.call(ObjC.cls('WKWebViewConfiguration'),
+                                             ObjC.sel('alloc'))
+        @configuration = ObjC::MSG_PTR.call(@configuration, ObjC.sel('init'))
+        ObjC.retain(@configuration)
+
+        prefs = ObjC::MSG_PTR.call(@configuration, ObjC.sel('preferences'))
+        ObjC::MSG_VOID_I.call(prefs, ObjC.sel('setJavaScriptEnabled:'), 0)
+
+        # macOS 11+ moved JS control to defaultWebpagePreferences; set
+        # both for forward/backward compatibility. The selector is a
+        # no-op on older systems (NSObject swallows it via msgSend),
+        # so the old setJavaScriptEnabled: is the actual guarantee.
+        wpp_sel = ObjC.sel('defaultWebpagePreferences')
+        if ObjC::MSG_RET_L.call(@configuration, ObjC.sel('respondsToSelector:'),
+                                wpp_sel) != 0
+          wpp = ObjC::MSG_PTR.call(@configuration, wpp_sel)
+          unless wpp.null?
+            ObjC::MSG_VOID_I.call(wpp, ObjC.sel('setAllowsContentJavaScript:'), 0)
+            ObjC::MSG_VOID_1.call(@configuration,
+                                   ObjC.sel('setDefaultWebpagePreferences:'), wpp)
+          end
+        end
+
+        @delegate_class = build_delegate_class
+        @delegate_instance = ObjC::MSG_PTR.call(@delegate_class, ObjC.sel('alloc'))
+        @delegate_instance = ObjC::MSG_PTR.call(@delegate_instance, ObjC.sel('init'))
+        ObjC.retain(@delegate_instance)
+
+        @web_view = ObjC::MSG_PTR.call(ObjC.cls('WKWebView'), ObjC.sel('alloc'))
+        @web_view = MSG_PTR_RECT_1.call(@web_view,
+                                         ObjC.sel('initWithFrame:configuration:'),
+                                         0.0, 0.0, 1.0, 1.0, @configuration)
+        ObjC.retain(@web_view)
+        ObjC::MSG_VOID_1.call(@web_view, ObjC.sel('setNavigationDelegate:'),
+                              @delegate_instance)
+      end
+
+      def build_delegate_class
+        finish = Fiddle::Closure::BlockCaller.new(V, [P, P, P, P]) do |_s, _c, _wv, _nav|
+          @nav_done = true
+        end
+        fail_nav = Fiddle::Closure::BlockCaller.new(V, [P, P, P, P, P]) do |_s, _c, _wv, _nav, _err|
+          @nav_done = true
+          @nav_error = true
+        end
+        fail_prov = Fiddle::Closure::BlockCaller.new(V, [P, P, P, P, P]) do |_s, _c, _wv, _nav, _err|
+          @nav_done = true
+          @nav_error = true
+        end
+        # Hold strong refs so Fiddle doesn't GC the closure thunks.
+        @delegate_closures = [finish, fail_nav, fail_prov]
+
+        ObjC.define_class('EchoesSvgNavDelegate', 'NSObject', {
+          'webView:didFinishNavigation:' => ['v@:@@', finish],
+          'webView:didFailNavigation:withError:' => ['v@:@@@', fail_nav],
+          'webView:didFailProvisionalNavigation:withError:' => ['v@:@@@', fail_prov],
+        })
+      end
+
+      def build_snapshot_config(width, height)
+        cfg = ObjC::MSG_PTR.call(ObjC.cls('WKSnapshotConfiguration'), ObjC.sel('alloc'))
+        cfg = ObjC::MSG_PTR.call(cfg, ObjC.sel('init'))
+        # Default rect = view bounds; default snapshotWidth = view width.
+        # We just leave both at defaults so the snapshot matches the
+        # frame we set on the web view.
+        cfg
+      end
+
+      def build_html(svg_bytes)
+        svg = svg_bytes.dup.force_encoding(Encoding::UTF_8)
+        # Replace invalid byte sequences so a malformed SVG doesn't
+        # crash NSString creation.
+        svg = svg.scrub('')
+        <<~HTML
+          <!doctype html>
+          <html><head><style>
+          html, body { margin: 0; padding: 0; background: transparent; width: 100%; height: 100%; overflow: hidden; }
+          svg { display: block; width: 100%; height: 100%; }
+          </style></head><body>#{svg}</body></html>
+        HTML
+      end
+
+      def ns_image_to_cgimage(ns_image, width, height)
+        rect_buf = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+        rect_buf[0, 32] = [0.0, 0.0, width.to_f, height.to_f].pack('d4')
+        ObjC::MSG_PTR_3.call(ns_image,
+                              ObjC.sel('CGImageForProposedRect:context:hints:'),
+                              rect_buf, Fiddle::Pointer.new(0), Fiddle::Pointer.new(0))
+      end
+
+      # Pump the main run loop briefly until the block returns true or
+      # the deadline expires. Returns true if the condition was met,
+      # false on timeout. Uses 50 ms slices so the runloop stays
+      # responsive to other events (timer ticks, IO callbacks) while
+      # we wait.
+      def pump_until(timeout_s)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_s
+        rl = ObjC::MSG_PTR.call(ObjC.cls('NSRunLoop'), ObjC.sel('currentRunLoop'))
+        until yield
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          date = ObjC::MSG_PTR_D.call(ObjC.cls('NSDate'),
+                                       ObjC.sel('dateWithTimeIntervalSinceNow:'),
+                                       0.05)
+          ObjC::MSG_VOID_2.call(rl, ObjC.sel('runMode:beforeDate:'),
+                                 NS_DEFAULT_RUN_LOOP_MODE, date)
+        end
+        true
+      end
+    end
+  end
+end

data/lib/echoes/svg_sniffer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Echoes
+  # Detect SVG payloads in arbitrary image bytes. Used by the Kitty
+  # graphics and iTerm2 inline-image decoders to fork off to the
+  # SvgRenderer instead of NSBitmapImageRep (which is raster-only).
+  module SvgSniffer
+    # Skip optional UTF-8 BOM, whitespace, an XML prologue, and a
+    # DOCTYPE before the `<svg` element. Case-insensitive so `<SVG`
+    # and `<Svg` both match. `n` flag forces ASCII-8BIT so we can
+    # match against the binary payloads the decoders hand us.
+    SVG_RE = /\A(?:\xEF\xBB\xBF)?\s*(?:<\?xml[^>]*\?>\s*)?(?:<!DOCTYPE\s+svg[^>]*>\s*)?<svg\b/imn
+
+    # Capture the leading `<svg ...>` opening tag so intrinsic_size can
+    # work on just the attribute soup, ignoring the rest of the document.
+    OPEN_SVG_RE = /<svg\b([^>]*)>/imn
+
+    # Numeric attribute on the SVG root, optionally suffixed with a CSS
+    # length unit. We extract the number; unit conversion is best-effort
+    # (px / pt / unitless treated as pixels; em / % yield nil because
+    # they need layout context we don't have).
+    DIM_RE = /\A\s*([0-9]*\.?[0-9]+)\s*([a-z%]*)\s*\z/i
+
+    module_function
+
+    def svg?(bytes)
+      return false if bytes.nil? || bytes.empty?
+      head = bytes.byteslice(0, 4096).b
+      SVG_RE.match?(head)
+    end
+
+    # Returns [width_px, height_px] or nil. Parses the <svg> tag's
+    # width/height attributes first; falls back to viewBox dimensions
+    # if either is missing or non-pixel.
+    def intrinsic_size(bytes)
+      return nil if bytes.nil? || bytes.empty?
+      head = bytes.byteslice(0, 4096).b
+      m = OPEN_SVG_RE.match(head)
+      return nil unless m
+      attrs = m[1].to_s
+
+      w = parse_dim(extract_attr(attrs, 'width'))
+      h = parse_dim(extract_attr(attrs, 'height'))
+
+      if w.nil? || h.nil?
+        vb = extract_attr(attrs, 'viewBox')
+        if vb
+          parts = vb.strip.split(/[\s,]+/)
+          if parts.size == 4
+            vw = parts[2].to_f
+            vh = parts[3].to_f
+            w ||= vw if vw.positive?
+            h ||= vh if vh.positive?
+          end
+        end
+      end
+
+      return nil unless w && h && w.positive? && h.positive?
+      [w.round, h.round]
+    end
+
+    def extract_attr(attrs, name)
+      m = attrs.match(/\s#{name}\s*=\s*["']([^"']*)["']/i)
+      m && m[1]
+    end
+
+    def parse_dim(str)
+      return nil if str.nil? || str.empty?
+      m = DIM_RE.match(str)
+      return nil unless m
+      unit = m[2].downcase
+      # Unitless / px / pt are treated as pixels (pt is technically
+      # 1.333px but the difference is invisible at typical SVG sizes
+      # and we'd be guessing the renderer's DPI anyway). em / % need
+      # layout context, so we punt.
+      return nil if unit == 'em' || unit == '%'
+      n = m[1].to_f
+      n.positive? ? n : nil
+    end
+  end
+end

data/lib/echoes/svg_transform.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Echoes
+  # SVG `transform=` attribute parser. Returns an ordered list of
+  # `[op_symbol, [args…]]` tuples, or nil for unknown functions /
+  # malformed input. Caller applies them left-to-right via CG's CTM
+  # setters (CGContextTranslateCTM, ScaleCTM, RotateCTM, ConcatCTM).
+  module SvgTransform
+    FN_RE = /([a-zA-Z]+)\s*\(([^)]*)\)/
+    NUM_RE = /-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/
+
+    module_function
+
+    def parse(str)
+      return nil if str.nil? || str.strip.empty?
+      ops = []
+      str.scan(FN_RE) do |name, body|
+        nums = body.scan(NUM_RE).map(&:to_f)
+        op = build(name.downcase, nums)
+        return nil if op.nil?
+        ops << op
+      end
+      return nil if ops.empty?
+      ops
+    end
+
+    def build(name, nums)
+      case name
+      when 'translate'
+        return nil unless (1..2).cover?(nums.size)
+        [:translate, [nums[0], nums[1] || 0.0]]
+      when 'scale'
+        return nil unless (1..2).cover?(nums.size)
+        [:scale, [nums[0], nums[1] || nums[0]]]
+      when 'rotate'
+        return nil unless [1, 3].include?(nums.size)
+        deg = nums[0]
+        cx, cy = nums.size == 3 ? [nums[1], nums[2]] : [0.0, 0.0]
+        [:rotate, [deg, cx, cy]]
+      when 'matrix'
+        return nil unless nums.size == 6
+        [:matrix, nums]
+      when 'skewx'
+        return nil unless nums.size == 1
+        [:skewx, [nums[0]]]
+      when 'skewy'
+        return nil unless nums.size == 1
+        [:skewy, [nums[0]]]
+      else
+        nil
+      end
+    end
+  end
+end