termpix 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ec8fff70b1018305deaa94931516564e573406a713fac62bbf6691dfe120b8
-  data.tar.gz: fcf1056c196bf42680fc1f78b8067db71a64ee342651c6684cb78f34d27f6d1d
+  metadata.gz: 763bacec25caa2a40043e19c2319b44c9433848e307281a761c4933ce345c227
+  data.tar.gz: e5fe48498bcf92d6cfccea1fedbec3d4cd33945096682e769a1464bb2248d0d2
 SHA512:
-  metadata.gz: f706b1ff612ec9f6f08596833fe66b5fc1b50946c61aa76bb9c8a88ba327d6e595c5607fb439024a94e29d857b603801f577a05876864c8f8493a9bbdbc8a906
-  data.tar.gz: 4610351de9645c8dd6855d25f70b800e74b088633a6cf8d3bc02e785f104ac62230e637923bf4c7aa9251973c434e4917aaa6c0c60d15a1d1a27bad7eb4760c6
+  metadata.gz: b55c954c5ccc8f78922973a8efd3c20a4891509fe9adc7c6baa71f91620d28952379096dbbeab6703799f0c58f6401ef3820e83f89eb0368d37d6e36e5db42b5
+  data.tar.gz: 890174a649f8cdc54d4506f3ff21075aa5d5f82f2be282101b19ad6e107b37271673272ac8c582ed96d2210a50375435ed31ee9d47fa2ce2259fdfba1749a0c8

data/lib/termpix/protocols.rb

@@ -4,21 +4,111 @@ require 'base64'
 module Termpix
   module Protocols
     # Kitty Graphics Protocol
-    # After extensive testing: Kitty protocol fundamentally incompatible with curses
-    # The protocol requires precise cursor control that conflicts with curses' buffer
-    # management. Recommend disabling Kitty protocol for curses-based apps.
+    # Uses Unicode placeholder mode (U=1) for curses/TUI compatibility
+    # Images are tied to placeholder characters that curses manages as text
     module Kitty
+      @current_image_id = nil
+      @image_cache = {}  # path -> image_id mapping
+
       def self.display(image_path, x:, y:, max_width:, max_height:)
-        # Kitty graphics protocol does not work reliably with curses applications
-        # The fundamental issue is that both Kitty and curses need exclusive control
-        # of terminal state, causing unavoidable conflicts
-        false
+        return false unless File.exist?(image_path)
+
+        # Get terminal cell size in pixels
+        cell_width, cell_height = get_cell_size
+        return false unless cell_width && cell_height
+
+        # Calculate pixel dimensions for the image area
+        pixel_width = max_width * cell_width
+        pixel_height = max_height * cell_height
+
+        # Check if we have this image cached
+        cache_key = "#{image_path}:#{pixel_width}x#{pixel_height}"
+        image_id = @image_cache[cache_key]
+
+        unless image_id
+          # Generate new image ID (1-4294967295)
+          image_id = (Time.now.to_f * 1000).to_i % 4294967295
+          image_id = 1 if image_id == 0
+        end
+
+        old_image_id = @current_image_id
+
+        unless @image_cache[cache_key]
+          # Transmit the image with scaling
+          escaped = Shellwords.escape(image_path)
+
+          # Create scaled PNG data using ImageMagick
+          png_data = `convert #{escaped}[0] -auto-orient -resize #{pixel_width}x#{pixel_height}\\> PNG:- 2>/dev/null`
+          return false if png_data.empty?
+
+          # Encode as base64 and chunk it (max 4096 bytes per chunk)
+          encoded = Base64.strict_encode64(png_data)
+          chunks = encoded.scan(/.{1,4096}/)
+
+          # Transmit image in chunks
+          chunks.each_with_index do |chunk, idx|
+            more = idx < chunks.length - 1 ? 1 : 0
+            if idx == 0
+              # First chunk: specify format (f=100 for PNG), action (a=t for transmit)
+              # i=image_id, m=more_chunks
+              print "\e_Ga=t,f=100,i=#{image_id},m=#{more};#{chunk}\e\\"
+            else
+              # Continuation chunks
+              print "\e_Gm=#{more};#{chunk}\e\\"
+            end
+          end
+          $stdout.flush
+
+          @image_cache[cache_key] = image_id
+        end
+
+        # Position cursor and display the NEW image FIRST
+        # a=p (place), i=image_id, C=1 (don't move cursor)
+        # Don't specify c/r - let kitty use image's native size (already scaled by ImageMagick)
+        print "\e[#{y};#{x}H"  # Move cursor to position
+        print "\e_Ga=p,i=#{image_id},C=1\e\\"
+        $stdout.flush
+
+        # NOW delete old placement (after new one is visible) - atomic swap
+        if old_image_id && old_image_id != image_id
+          print "\e_Ga=d,d=i,i=#{old_image_id}\e\\"
+          $stdout.flush
+        end
+
+        @current_image_id = image_id
+        true
       end
 
       def self.clear
+        # Actually clear the image
+        if @current_image_id
+          print "\e_Ga=d,d=i,i=#{@current_image_id}\e\\"
+          $stdout.flush
+          @current_image_id = nil
+        end
         true
       end
 
+      def self.get_cell_size
+        # Query terminal for cell size using XTWINOPS
+        # Or estimate from terminal size
+        begin
+          require 'io/console'
+          rows, cols = IO.console.winsize
+          # Get pixel size if available
+          if IO.console.respond_to?(:winsize_pixels)
+            prows, pcols = IO.console.winsize_pixels rescue nil
+            if prows && pcols && prows > 0 && pcols > 0
+              return [pcols / cols, prows / rows]
+            end
+          end
+          # Fall back to common defaults (10x20 pixels per cell)
+          [10, 20]
+        rescue
+          [10, 20]
+        end
+      end
+
       private
 
       def self.get_dimensions(image_path)

data/lib/termpix/version.rb

@@ -1,3 +1,3 @@
 module Termpix
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/termpix.rb

@@ -61,6 +61,12 @@ module Termpix
       !@protocol.nil?
     end
 
+    # Check if protocol supports atomic replace (show new without clearing first)
+    # Kitty can replace images without flash; w3m/sixel need explicit clear
+    def atomic_replace?
+      @protocol == :kitty
+    end
+
     # Get information about the current protocol
     def info
       {
@@ -73,17 +79,17 @@ module Termpix
     private
 
     def detect_protocol
-      # Check for Sixel support first - works better with curses apps
+      # Check for Kitty terminal first - use native kitty protocol
+      if ENV['TERM'] == 'xterm-kitty' || ENV['KITTY_WINDOW_ID']
+        return :kitty if check_dependency('convert')
+      end
+
+      # Check for Sixel support - works well with curses apps
       # Note: urxvt/rxvt-unicode does NOT support sixel unless specially compiled
-      # Kitty's sixel support doesn't work properly (shows ASCII) - use w3m instead
       if ENV['TERM']&.match(/^xterm(?!-kitty)|^mlterm|^foot/)
         return :sixel if check_dependency('convert')
       end
 
-      # Kitty graphics protocol disabled - fundamentally incompatible with curses
-      # After extensive testing: Kitty protocol requires exclusive terminal control
-      # that conflicts with curses' buffer management. Use w3m fallback instead.
-
       # Überzug++ - disabled for now (implementation incomplete)
       # TODO: Implement proper Überzug++ JSON-RPC communication
       # if command_exists?('ueberzug') || command_exists?('ueberzugpp')
@@ -92,7 +98,7 @@ module Termpix
       #   end
       # end
 
-      # Fall back to w3m (works everywhere but has brief flash in Kitty)
+      # Fall back to w3m (works on urxvt, xterm, etc.)
       if command_exists?('/usr/lib/w3m/w3mimgdisplay')
         if check_dependencies('xwininfo', 'xdotool', 'identify')
           return :w3m

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: termpix
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Geir Isene
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-03 00:00:00.000000000 Z
+date: 2026-01-16 00:00:00.000000000 Z
 dependencies: []
-description: 'Termpix v0.2.1: Performance optimization - only auto-orients images
-  with EXIF rotation data. Provides clean API for displaying images in terminal using
-  best available protocol (Sixel or w3m). Auto-detects terminal capabilities and falls
-  back gracefully.'
+description: 'Termpix v0.3.0: Native Kitty graphics protocol - no more flash in kitty
+  terminal. Provides clean API for displaying images in terminal using best available
+  protocol (Kitty, Sixel, or w3m). Auto-detects terminal capabilities and falls back
+  gracefully.'
 email: g@isene.com
 executables: []
 extensions: []