shoko 0.1.3 → 0.1.5

data/lib/shoko/adapters/output/kitty/kitty_image_renderer.rb

@@ -2,237 +2,226 @@
 
 require 'digest/sha1'
 
-require_relative '../../book_sources/epub/epub_resource_loader.rb'
+require_relative 'resource_loader'
 require_relative 'image_transcoder'
 require_relative 'kitty_graphics'
 
 module Shoko
-  module Adapters::Output::Kitty
-    # Stateful renderer that transmits images once per session and then places
-    # them on screen using the Kitty graphics protocol.
-    class KittyImageRenderer
-      MAX_ID = 4_294_967_295
-      PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b
-      DEFAULT_CELL_ASPECT = 0.5 # width/height ratio for typical terminal cells
-
-      def initialize(resource_loader: EpubResourceLoader.new, transcoder: ImageTranscoder.new)
-        @resource_loader = resource_loader
-        @transcoder = transcoder
-        @transmitted = {}
-        @dimensions = {}
-      end
-
-      def enabled?(config_store)
-        KittyGraphics.enabled_for?(config_store)
-      rescue StandardError
-        false
-      end
-
-      def render(output:, book_sha:, epub_path:, chapter_entry_path:, src:, row:, col:, cols:, rows:,
-                 placement_id:, **options)
-        z = options.fetch(:z, nil)
-        return false unless output
-        return false unless epub_path && File.file?(epub_path)
-
-        entry_path = EpubResourceLoader.resolve_chapter_relative(chapter_entry_path, src)
-        return false unless entry_path
-
-        image_id = image_id_for(book_sha, epub_path, entry_path)
-        return false unless ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
-
-        fit = fit_geometry(image_id, cols.to_i, rows.to_i)
-
-        place_seq = KittyGraphics.place(image_id,
-                                        placement_id: clamp_id(placement_id),
-                                        cols: fit[:cols],
-                                        rows: fit[:rows],
-                                        quiet: true,
-                                        z: z)
-        abs_row = row.to_i + fit[:row_offset]
-        abs_col = col.to_i + fit[:col_offset]
-        if output.respond_to?(:raw)
-          output.raw(TerminalOutput::ANSI.move(abs_row, abs_col) + place_seq)
-        elsif output.respond_to?(:print)
-          output.print(TerminalOutput::ANSI.move(abs_row, abs_col) + place_seq)
-        elsif output.respond_to?(:write)
-          output.write(abs_row, abs_col, place_seq)
-        else
-          return false
-        end
-        true
-      rescue StandardError
-        false
-      end
-
-      # Ensure the image is transmitted and has a virtual placement for Unicode placeholders.
-      # Returns the image_id on success, otherwise nil.
-      def prepare_virtual(output:, book_sha:, epub_path:, chapter_entry_path:, src:, cols:, rows:, placement_id: nil,
-                          **options)
-        z = options.fetch(:z, nil)
-        return nil unless output
-        return nil unless epub_path && File.file?(epub_path)
-
-        entry_path = EpubResourceLoader.resolve_chapter_relative(chapter_entry_path, src)
-        return nil unless entry_path
-
-        image_id = image_id_for(book_sha, epub_path, entry_path)
-        return nil unless ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
-        return nil unless ensure_virtual_placement(output,
-                                                   image_id,
-                                                   cols.to_i,
-                                                   rows.to_i,
-                                                   placement_id: placement_id,
-                                                   z: z)
-
-        image_id
-      rescue StandardError
-        nil
-      end
-
-      private
-
-      def ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
-        return :cached if @transmitted[image_id]
-
-        cache_key = png_cache_key(entry_path)
-        bytes = @resource_loader.fetch(book_sha: book_sha,
-                                       epub_path: epub_path,
-                                       entry_path: entry_path,
-                                       cache_key: cache_key,
-                                       persist: false)
-        png_bytes = @transcoder.to_png(bytes)
-        return nil unless png_bytes
-
-        dims = png_dimensions(png_bytes)
-        @dimensions[image_id] = dims if dims
-
-        @resource_loader.store(book_sha: book_sha, entry_path: cache_key, bytes: png_bytes)
-
-        KittyGraphics.transmit_png(image_id, png_bytes, quiet: true).each do |seq|
-          emit_raw(output, seq)
-        end
-
-        @transmitted[image_id] = true
-        :transmitted
-      end
-
-      def ensure_virtual_placement(output, image_id, cols, rows, placement_id: nil, **options)
-        z = options.fetch(:z, nil)
-        cols_i = cols.to_i
-        rows_i = rows.to_i
-        return false if cols_i <= 0 || rows_i <= 0
-
-        place_id = placement_id.to_i
-        place_id = clamp_id(place_id) if place_id.positive?
-        seq = KittyGraphics.virtual_place(image_id,
-                                          cols: cols_i,
-                                          rows: rows_i,
-                                          placement_id: place_id,
-                                          quiet: true,
-                                          z: z)
-        emit_raw(output, seq)
-        true
-      rescue StandardError
-        false
-      end
-
-      def emit_raw(output, seq)
-        if output.respond_to?(:raw)
-          output.raw(seq)
-        elsif output.respond_to?(:print)
-          output.print(seq)
-        elsif output.respond_to?(:write)
-          output.write(1, 1, seq)
-        end
-      rescue StandardError
-        nil
-      end
-
-      def fit_geometry(image_id, max_cols, max_rows)
-        cols_i = max_cols.to_i
-        rows_i = max_rows.to_i
-        cols_i = 1 if cols_i <= 0
-        rows_i = 1 if rows_i <= 0
-
-        dims = @dimensions[image_id]
-        return { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 } unless dims
-
-        img_w = dims[:width].to_i
-        img_h = dims[:height].to_i
-        return { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 } if img_w <= 0 || img_h <= 0
-
-        aspect = img_w.to_f / img_h
-        cell_aspect = DEFAULT_CELL_ASPECT
-
-        cols_for_rows = (rows_i.to_f * aspect / cell_aspect)
-        target_cols = cols_for_rows.floor
-        target_cols = 1 if target_cols <= 0
-
-        if target_cols <= cols_i
-          fit_cols = target_cols
-          fit_rows = rows_i
-        else
-          fit_cols = cols_i
-          rows_for_cols = (cols_i.to_f * cell_aspect / aspect)
-          fit_rows = rows_for_cols.floor
-          fit_rows = 1 if fit_rows <= 0
-          fit_rows = rows_i if fit_rows > rows_i
-        end
-
-        col_offset = ((cols_i - fit_cols) / 2.0).floor
-        col_offset = 0 if col_offset.negative?
-
-        row_offset = 0
-
-        { cols: fit_cols, rows: fit_rows, col_offset: col_offset, row_offset: row_offset }
-      rescue StandardError
-        { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 }
-      end
-
-      def png_dimensions(bytes)
-        data = bytes.to_s.b
-        return nil unless data.start_with?(PNG_SIGNATURE)
-
-        # PNG signature (8) + length (4) + type (4) + width (4) + height (4)
-        return nil unless data.bytesize >= 24
-        return nil unless data.byteslice(12, 4) == 'IHDR'
-
-        width = data.byteslice(16, 4).unpack1('N')
-        height = data.byteslice(20, 4).unpack1('N')
-        return nil if width.to_i <= 0 || height.to_i <= 0
-
-        { width: width.to_i, height: height.to_i }
-      rescue StandardError
-        nil
-      end
-
-      def png_cache_key(entry_path)
-        "#{entry_path}|kitty_png_v1"
-      rescue StandardError
-        "#{entry_path}|kitty_png_v1"
-      end
-
-      def image_id_for(book_sha, epub_path, entry_path)
-        seed = "#{book_sha}|#{epub_path}|#{entry_path}"
-        hashed_id(seed)
-      end
-
-      def hashed_id(seed)
-        raw = Digest::SHA1.digest(seed.to_s)
-        int = raw.unpack1('N')
-        int.zero? ? 1 : int
-      rescue StandardError
-        1
-      end
-
-      def clamp_id(value)
-        int = value.to_i
-        int = 1 if int <= 0
-        if int > MAX_ID
-          int %= MAX_ID
-          int = 1 if int.zero?
+  module Adapters
+    module Output
+      module Kitty
+        # Stateful renderer that transmits images once per session and then places
+        # them on screen using the Kitty graphics protocol.
+        class KittyImageRenderer
+          MAX_ID = 4_294_967_295
+          PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b
+          DEFAULT_CELL_ASPECT = 0.5 # width/height ratio for typical terminal cells
+
+          def initialize(resource_loader: ResourceLoader.new,
+                         transcoder: ImageTranscoder.new)
+            @resource_loader = resource_loader
+            @transcoder = transcoder
+            @transmitted = {}
+            @dimensions = {}
+          end
+
+          def enabled?(config_store)
+            KittyGraphics.enabled_for?(config_store)
+          rescue Shoko::Error
+            raise
+          end
+
+          def render(output:, book_sha:, epub_path:, chapter_entry_path:, src:, row:, col:, cols:, rows:,
+                     placement_id:, **options)
+            z = options.fetch(:z, nil)
+            return false unless output
+            return false unless epub_path && File.file?(epub_path)
+
+            entry_path = @resource_loader.resolve_chapter_relative(chapter_entry_path, src)
+            return false unless entry_path
+
+            image_id = image_id_for(book_sha, epub_path, entry_path)
+            return false unless ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
+
+            fit = fit_geometry(image_id, cols.to_i, rows.to_i)
+
+            place_seq = KittyGraphics.place(image_id,
+                                            placement_id: clamp_id(placement_id),
+                                            cols: fit[:cols],
+                                            rows: fit[:rows],
+                                            quiet: true,
+                                            z: z)
+            abs_row = row.to_i + fit[:row_offset]
+            abs_col = col.to_i + fit[:col_offset]
+            emit_raw(output, TerminalOutput::ANSI.move(abs_row, abs_col) + place_seq)
+            true
+          rescue Shoko::Error
+            raise
+          end
+
+          # Ensure the image is transmitted and has a virtual placement for Unicode placeholders.
+          # Returns the image_id on success, otherwise nil.
+          def prepare_virtual(output:, book_sha:, epub_path:, chapter_entry_path:, src:, cols:, rows:, placement_id: nil,
+                              **options)
+            z = options.fetch(:z, nil)
+            return nil unless output
+            return nil unless epub_path && File.file?(epub_path)
+
+            entry_path = @resource_loader.resolve_chapter_relative(chapter_entry_path, src)
+            return nil unless entry_path
+
+            image_id = image_id_for(book_sha, epub_path, entry_path)
+            return nil unless ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
+            return nil unless ensure_virtual_placement(output,
+                                                       image_id,
+                                                       cols.to_i,
+                                                       rows.to_i,
+                                                       placement_id: placement_id,
+                                                       z: z)
+
+            image_id
+          rescue Shoko::Error
+            raise
+          end
+
+          private
+
+          def ensure_transmitted(output, image_id, book_sha, epub_path, entry_path)
+            return :cached if @transmitted[image_id]
+
+            cache_key = png_cache_key(entry_path)
+            bytes = @resource_loader.fetch(book_sha: book_sha,
+                                           epub_path: epub_path,
+                                           entry_path: entry_path,
+                                           cache_key: cache_key,
+                                           persist: false)
+            png_bytes = @transcoder.to_png(bytes)
+            return nil unless png_bytes
+
+            dims = png_dimensions(png_bytes)
+            @dimensions[image_id] = dims if dims
+
+            @resource_loader.store(book_sha: book_sha, entry_path: cache_key, bytes: png_bytes)
+
+            KittyGraphics.transmit_png(image_id, png_bytes, quiet: true).each do |seq|
+              emit_raw(output, seq)
+            end
+
+            @transmitted[image_id] = true
+            :transmitted
+          end
+
+          def ensure_virtual_placement(output, image_id, cols, rows, placement_id: nil, **options)
+            z = options.fetch(:z, nil)
+            cols_i = cols.to_i
+            rows_i = rows.to_i
+            return false if cols_i <= 0 || rows_i <= 0
+
+            place_id = placement_id.to_i
+            place_id = clamp_id(place_id) if place_id.positive?
+            seq = KittyGraphics.virtual_place(image_id,
+                                              cols: cols_i,
+                                              rows: rows_i,
+                                              placement_id: place_id,
+                                              quiet: true,
+                                              z: z)
+            emit_raw(output, seq)
+            true
+          rescue Shoko::Error
+            raise
+          end
+
+          def emit_raw(output, seq)
+            output.raw(seq)
+          rescue Shoko::Error
+            raise
+          end
+
+          def fit_geometry(image_id, max_cols, max_rows)
+            cols_i = max_cols.to_i
+            rows_i = max_rows.to_i
+            cols_i = 1 if cols_i <= 0
+            rows_i = 1 if rows_i <= 0
+
+            dims = @dimensions[image_id]
+            return { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 } unless dims
+
+            img_w = dims[:width].to_i
+            img_h = dims[:height].to_i
+            return { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 } if img_w <= 0 || img_h <= 0
+
+            aspect = img_w.to_f / img_h
+            cell_aspect = DEFAULT_CELL_ASPECT
+
+            cols_for_rows = (rows_i.to_f * aspect / cell_aspect)
+            target_cols = cols_for_rows.floor
+            target_cols = 1 if target_cols <= 0
+
+            if target_cols <= cols_i
+              fit_cols = target_cols
+              fit_rows = rows_i
+            else
+              fit_cols = cols_i
+              rows_for_cols = (cols_i.to_f * cell_aspect / aspect)
+              fit_rows = rows_for_cols.floor
+              fit_rows = 1 if fit_rows <= 0
+              fit_rows = rows_i if fit_rows > rows_i
+            end
+
+            col_offset = ((cols_i - fit_cols) / 2.0).floor
+            col_offset = 0 if col_offset.negative?
+
+            row_offset = 0
+
+            { cols: fit_cols, rows: fit_rows, col_offset: col_offset, row_offset: row_offset }
+          rescue Shoko::Error
+            { cols: cols_i, rows: rows_i, col_offset: 0, row_offset: 0 }
+          end
+
+          def png_dimensions(bytes)
+            data = bytes.to_s.b
+            return nil unless data.start_with?(PNG_SIGNATURE)
+
+            # PNG signature (8) + length (4) + type (4) + width (4) + height (4)
+            return nil unless data.bytesize >= 24
+            return nil unless data.byteslice(12, 4) == 'IHDR'
+
+            width = data.byteslice(16, 4).unpack1('N')
+            height = data.byteslice(20, 4).unpack1('N')
+            return nil if width.to_i <= 0 || height.to_i <= 0
+
+            { width: width.to_i, height: height.to_i }
+          rescue Shoko::Error
+            raise
+          end
+
+          def png_cache_key(entry_path)
+            "#{entry_path}|kitty_png_v1"
+          rescue Shoko::Error
+            "#{entry_path}|kitty_png_v1"
+          end
+
+          def image_id_for(book_sha, epub_path, entry_path)
+            seed = "#{book_sha}|#{epub_path}|#{entry_path}"
+            hashed_id(seed)
+          end
+
+          def hashed_id(seed)
+            raw = Digest::SHA1.digest(seed.to_s)
+            int = raw.unpack1('N') & 0xFF_FF_FF
+            int.zero? ? 1 : int
+          end
+
+          def clamp_id(value)
+            int = value.to_i
+            int = 1 if int <= 0
+            if int > MAX_ID
+              int %= MAX_ID
+              int = 1 if int.zero?
+            end
+            int
+          end
         end
-        int
       end
     end
   end

data/lib/shoko/adapters/output/kitty/kitty_unicode_placeholders.rb

@@ -1,138 +1,13 @@
 # frozen_string_literal: true
 
+require_relative '../../../shared/terminal/kitty_unicode_placeholders'
+
 module Shoko
   module Adapters
     module Output
       module Kitty
-        # Helpers for emitting Kitty Unicode image placeholders (U+10EEEE) with diacritics.
-        # See: https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders
-        module KittyUnicodePlaceholders
-      module_function
-
-      PLACEHOLDER_CHAR = "\u{10EEEE}"
-      RESET_FG = "\e[39m"
-      RESET_UNDERLINE = "\e[59m"
-      DIACRITIC_CODEPOINTS_PATH = ::File.join(__dir__, 'kitty_unicode_placeholders_diacritic_codepoints.txt')
-
-      def line(image_id:, grid:, placement_id: nil)
-        key = cache_key(image_id, grid, placement_id)
-        return '' unless key
-
-        cache = (@line_cache ||= {})
-        cache.fetch(key) { cache[key] = render_line(key) }
-      end
-
-      def diacritics
-        @diacritics ||= build_diacritics
-      end
-
-      def foreground(image_id)
-        rgb_sgr(image_id, sgr: 38, cache: (@fg_cache ||= {}))
-      end
-
-      def underline(placement_id)
-        rgb_sgr(placement_id, sgr: 58, cache: (@ul_cache ||= {}))
-      end
-
-      def build_diacritics
-        codepoints = load_diacritic_codepoints
-        loaded = codepoints.map { |hex| [Integer(hex, 16)].pack('U') }.freeze
-        raise ArgumentError, 'not enough diacritics to support Kitty placeholders' if loaded.length < 256
-
-        loaded
-      end
-
-      def cache_key(image_id, grid, placement_id)
-        image_i = positive_integer(image_id)
-        grid_i = valid_grid(grid)
-        return unless image_i && grid_i
-
-        placement_i = (integer_or_nil(placement_id) || 0).clamp(0, 0xFF_FF_FF)
-        (image_i << 40) | (placement_i << 16) | grid_i
-      end
-
-      def integer_or_nil(value)
-        Integer(value)
-      rescue ArgumentError, TypeError
-        nil
-      end
-
-      def load_diacritic_codepoints
-        ::File.read(DIACRITIC_CODEPOINTS_PATH, encoding: Encoding::UTF_8).split
-      end
-
-      def positive_integer(value)
-        int = integer_or_nil(value)
-        return unless int&.positive?
-
-        int & 0xFFFF_FFFF
-      end
-
-      def valid_grid(value)
-        grid_i = integer_or_nil(value)
-        return unless grid_i && (0..0xFFFF).cover?(grid_i) && (1..255).cover?(grid_i & 0xFF)
-
-        grid_i
-      end
-
-      def placeholder_cells(key)
-        marks = diacritics
-        cols = key & 0xFF
-        first = PLACEHOLDER_CHAR + marks.fetch((key >> 8) & 0xFF) + marks.fetch(0) + msb_diacritic(marks, key)
-        first + (cols > 1 ? (PLACEHOLDER_CHAR * (cols - 1)) : '')
-      end
-
-      def msb_diacritic(marks, key)
-        msb = (key >> 64) & 0xFF
-        msb.zero? ? '' : marks.fetch(msb)
-      end
-
-      def render_line(key)
-        cells = placeholder_cells(key)
-        wrap_sequences(key, cells)
-      end
-
-      def wrap_sequences(key, cells)
-        image_id = (key >> 40) & 0xFFFF_FFFF
-        placement_id = (key >> 16) & 0xFF_FF_FF
-        fg = foreground(image_id)
-
-        return "#{fg}#{cells}#{RESET_FG}" unless placement_id.positive?
-
-        "#{fg}#{underline(placement_id)}#{cells}#{RESET_FG}#{RESET_UNDERLINE}"
-      end
-
-      def rgb_sgr(value, sgr:, cache:)
-        bits = integer_or_nil(value)
-        return '' unless bits
-
-        bits &= 0xFF_FF_FF
-        cache.fetch(bits) { cache[bits] = build_rgb_sgr(sgr, bits) }
-      end
-
-      def build_rgb_sgr(sgr, bits)
-        red = (bits >> 16) & 0xFF
-        green = (bits >> 8) & 0xFF
-        blue = bits & 0xFF
-        "\e[#{sgr};2;#{red};#{green};#{blue}m"
-      end
-
-      private_class_method :build_diacritics,
-                           :build_rgb_sgr,
-                           :cache_key,
-                           :diacritics,
-                           :foreground,
-                           :integer_or_nil,
-                           :load_diacritic_codepoints,
-                           :msb_diacritic,
-                           :placeholder_cells,
-                           :positive_integer,
-                           :render_line,
-                           :rgb_sgr,
-                           :underline,
-                           :valid_grid,
-                           :wrap_sequences
-        end
+        # Adapter alias to canonical shared implementation.
+        KittyUnicodePlaceholders = Shoko::Shared::Terminal::KittyUnicodePlaceholders
       end
     end
   end

data/lib/shoko/adapters/output/kitty/resource_loader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Output
+      module Kitty
+        # Loader contract used by Kitty image rendering.
+        class ResourceLoader
+          def initialize(loader:)
+            @loader = loader
+          end
+
+          def resolve_chapter_relative(chapter_entry_path, src)
+            @loader.class.resolve_chapter_relative(chapter_entry_path, src)
+          end
+
+          def fetch(book_sha:, epub_path:, entry_path:, cache_key:, persist:)
+            @loader.fetch(
+              book_sha: book_sha,
+              epub_path: epub_path,
+              entry_path: entry_path,
+              cache_key: cache_key,
+              persist: persist
+            )
+          end
+
+          def store(book_sha:, entry_path:, bytes:)
+            @loader.store(book_sha: book_sha, entry_path: entry_path, bytes: bytes)
+          end
+        end
+      end
+    end
+  end
+end