przn 0.4.0 → 0.6.0

data/lib/przn/image_util.rb

@@ -67,6 +67,14 @@ module Przn
         ENV['TERM_PROGRAM'] == 'Echoes'
     end
 
+    # Echoes-specific gate for OSC 7772 features (cell-alpha slide fades,
+    # bg-color / bg-gradient, hide-pointer). Strictly checked by
+    # TERM_PROGRAM since the OSC is private — other terminals would
+    # silently drop it but the renderer still spends time emitting bytes.
+    def echoes_terminal?
+      ENV['TERM_PROGRAM'] == 'Echoes'
+    end
+
     PNG_MAGIC = "\x89PNG\r\n\x1a\n".b.freeze
 
     def png?(path)
@@ -85,10 +93,65 @@ module Przn
       "\e_Ga=t,t=f,f=100,i=#{image_id},q=2;#{encoded}\e\\"
     end
 
+    # Kitty Graphics Protocol: upload arbitrary image bytes inline via
+    # the direct-data transmission mode (`t=d`). Used by the shape-
+    # drawing tags (`<rect>`, `<circle>`, `<line>`, …) which build a
+    # tiny self-contained SVG document per shape and ship it here.
+    # Echoes content-sniffs the payload and routes SVGs through its
+    # native CoreGraphics rasterizer (sub-millisecond for path-only
+    # SVGs — the case shape primitives always hit). `f=100` is the
+    # default PNG format code; the sniffer overrides it for SVG.
+    def kitty_upload_inline(bytes, image_id:)
+      encoded = [bytes.to_s].pack('m0')
+      "\e_Ga=t,t=d,f=100,i=#{image_id},q=2;#{encoded}\e\\"
+    end
+
     # Kitty Graphics Protocol: place a previously-uploaded image at the
     # current cursor position, scaled to fit `cols` x `rows` cells.
-    def kitty_place(image_id:, cols:, rows:)
-      "\e_Ga=p,i=#{image_id},c=#{cols},r=#{rows},q=2\e\\"
+    # `z` sets the z-index — negative values draw the image behind
+    # text cells (used by slide background images at z: -1).
+    # `x_off` / `y_off` add a sub-cell pixel offset from the top-left
+    # of the anchor cell — this is how `<img>` gets 1-px positioning
+    # without snapping to the cell grid. Omitted (or 0) means anchor
+    # to the cell's own top-left.
+    # `C=1` (suppress cursor movement / wrap / scroll) is always set
+    # — przn is a presentation tool, never the kind of context that
+    # wants an image landing near the bottom to scroll prior rows
+    # off-screen; oversize placements clip at the pane edge instead.
+    def kitty_place(image_id:, cols:, rows:, z: nil, x_off: 0, y_off: 0)
+      params = +"a=p,i=#{image_id},c=#{cols},r=#{rows},C=1,q=2"
+      params << ",X=#{x_off}" if x_off && x_off > 0
+      params << ",Y=#{y_off}" if y_off && y_off > 0
+      params << ",z=#{z}" if z
+      "\e_G#{params}\e\\"
+    end
+
+    # Kitty Graphics Protocol: delete every placement for a specific
+    # image id while keeping the stored image data alive (lowercase
+    # `d=i`). Used to wipe the previous slide's background image
+    # before placing a new one, without forcing a re-upload.
+    def kitty_delete_placements(image_id:)
+      "\e_Ga=d,d=i,i=#{image_id},q=2\e\\"
+    end
+
+    # Kitty Graphics Protocol: delete every placement on the screen
+    # while keeping the stored image data alive (lowercase `d=a`).
+    # Called at the start of each slide render to wipe the previous
+    # slide's `<img>` / shape placements; the new slide re-emits its
+    # own placements so cached images need only the small placement
+    # command, not a re-transmission.
+    def kitty_delete_all_placements
+      "\e_Ga=d,d=a,q=2\e\\"
+    end
+
+    # Kitty Graphics Protocol: delete every placement and free the
+    # stored image data. Used on quit so previously-rendered images
+    # don't leak through onto the user's restored shell screen
+    # (placements aren't tied to the alt-screen buffer in most
+    # kitty-protocol implementations, so leaving the alt screen
+    # alone isn't enough to hide them). `q=2` suppresses the OK reply.
+    def kitty_clear_all
+      "\e_Ga=d,d=A,q=2\e\\"
     end
 
     # Sixel via img2sixel

data/lib/przn/kitty_text.rb

@@ -19,8 +19,9 @@ module Przn
     # 66, which renders without the flip / custom font on any kitty-
     # compatible terminal (better than emitting an OSC 7772 frame the
     # terminal would ignore entirely).
-    def sized(text, s:, h: nil, v: nil, n: nil, d: nil, f: nil, flip: nil)
+    def sized(text, s:, h: nil, v: nil, n: nil, d: nil, f: nil, flip: nil, w: nil)
       params = +"s=#{s}"
+      params << ":w=#{w}" if w
       params << ":n=#{n}" if n
       params << ":d=#{d}" if d
       params << ":h=#{h}" if h

data/lib/przn/mermaid_renderer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'tmpdir'
+require 'fileutils'
+require 'shellwords'
+
+module Przn
+  # Shell-out wrapper around the Mermaid CLI (`mmdc`). Given a Mermaid
+  # source string, returns the path to a rendered PNG — cached for the
+  # life of the session in a tmpdir keyed by SHA256 of the source so
+  # the same diagram on multiple slides (or after `r` reload) shells
+  # out exactly once.
+  #
+  # The PNG is rendered with `-b transparent` so the slide background
+  # (theme `bg`, gradient, image) shows through. Width is fixed at
+  # 1600 px so the rendered image is high-res enough for any cell
+  # placement; the Kitty Graphics protocol scales to whatever cell
+  # rect the placement carves out.
+  #
+  # When `mmdc` is missing or the render fails for any reason, returns
+  # nil and the caller falls back to rendering the source as a plain
+  # fenced block.
+  module MermaidRenderer
+    CANVAS_WIDTH_PX = 1600
+
+    @cache = {}
+    @cache_mutex = Mutex.new
+    @tmpdir = nil
+    @tmpdir_mutex = Mutex.new
+
+    module_function
+
+    # Returns the path to a rendered PNG, or nil if rendering failed.
+    # `theme` defaults to mermaid's `default`; future hook for a theme
+    # knob (theme.yml `mermaid.theme`).
+    def render(source, theme: 'default')
+      return nil if source.nil? || source.strip.empty?
+      key = Digest::SHA256.hexdigest("#{theme}:#{source}")
+      cached = @cache_mutex.synchronize { @cache[key] }
+      return cached if cached
+
+      dir = ensure_tmpdir
+      in_path  = File.join(dir, "#{key}.mmd")
+      out_path = File.join(dir, "#{key}.png")
+      File.write(in_path, source)
+
+      cmd = ['mmdc',
+             '--quiet',
+             '-i', in_path,
+             '-o', out_path,
+             '-t', theme,
+             '-b', 'transparent',
+             '-w', CANVAS_WIDTH_PX.to_s]
+      ok = system(*cmd, out: File::NULL, err: File::NULL)
+
+      return nil unless ok && File.exist?(out_path) && File.size(out_path).positive?
+
+      @cache_mutex.synchronize { @cache[key] = out_path }
+      out_path
+    rescue StandardError
+      nil
+    end
+
+    # Bare check for whether the CLI is reachable. Used by the
+    # renderer to decide whether to even try (or to short-circuit to
+    # the plain-fence fallback).
+    def available?
+      return @available unless @available.nil?
+      @available = system('mmdc', '--version', out: File::NULL, err: File::NULL)
+    end
+
+    def reset!
+      @cache_mutex.synchronize { @cache.clear }
+      @tmpdir_mutex.synchronize do
+        FileUtils.remove_entry(@tmpdir) if @tmpdir && File.directory?(@tmpdir)
+        @tmpdir = nil
+      end
+      @available = nil
+    end
+
+    def ensure_tmpdir
+      @tmpdir_mutex.synchronize do
+        @tmpdir ||= Dir.mktmpdir('przn-mermaid-')
+      end
+    end
+  end
+end