shoko 0.1.0

data/lib/shoko/adapters/output/formatting/wrapping_service.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require_relative '../../../core/services/base_service.rb'
+require_relative '../../../core/services/pagination/internal/chapter_cache.rb'
+require_relative '../terminal/text_metrics.rb'
+
+module Shoko
+  module Adapters
+    module Output
+      module Formatting
+        # Service responsible for wrapping chapter lines to a column width.
+        # Uses the shared ChapterCache to avoid recomputation across frames.
+        class WrappingService < BaseService
+          WINDOW_CACHE_LIMIT = 200
+
+          def initialize(dependencies)
+            super
+            @chapter_cache = Shoko::Core::Services::Pagination::Internal::ChapterCache.new
+            @window_cache = Hash.new { |h, k| h[k] = { store: {}, order: [] } }
+          end
+
+        # Wrap raw lines for a chapter to the given width.
+        # Falls back to a local wrapper if cache is unavailable.
+        #
+        # @param lines [Array<String>] raw chapter lines
+        # @param chapter_index [Integer] chapter index for caching keying
+        # @param width [Integer] column width
+        # @return [Array<String>] wrapped lines
+        def wrap_lines(lines, chapter_index, width)
+          return [] if lines.nil? || width.to_i < 10
+
+          formatted = fetch_formatted_lines(chapter_index, width, 0, lines.length)
+          return formatted if formatted
+
+          cache = begin
+            registered?(:chapter_cache) ? resolve(:chapter_cache) : @chapter_cache
+          rescue StandardError
+            @chapter_cache
+          end
+          cache.get_wrapped_lines(chapter_index, lines, width)
+        end
+
+        # Wrap only a window of text sufficient for immediate display.
+        # This avoids wrapping the entire chapter on first render.
+        #
+        # @param lines [Array<String>] raw chapter lines
+        # @param chapter_index [Integer] chapter index (for caching semantics if needed)
+        # @param width [Integer] column width
+        # @param start [Integer] wrapped-lines start offset
+        # @param length [Integer] number of wrapped lines to return
+        # @return [Array<String>] slice of wrapped lines covering the requested window
+        def wrap_window(lines, chapter_index, width, start, length)
+          width_i = width.to_i
+          length_i = length.to_i
+          start_i = start.to_i
+          return [] if lines.nil? || width_i <= 0 || length_i <= 0
+
+          formatted = fetch_formatted_lines(chapter_index, width_i, start_i, length_i)
+          return formatted if formatted
+
+          target_end = [start_i, 0].max + length_i - 1
+          key = [lines.object_id, chapter_index, width_i]
+          cached = @window_cache[key][:store][[start_i, length_i]]
+          return cached if cached
+
+          wrapped = []
+
+          lines.each do |line|
+            break if wrapped.length >= (target_end + 1)
+
+            next if line.nil?
+
+            if line.strip.empty?
+              wrapped << ''
+              next
+            end
+
+            segments = Shoko::Adapters::Output::Terminal::TextMetrics.wrap_plain_text(line, width_i)
+            wrapped.concat(segments)
+          end
+
+          start_index = [start_i, 0].max
+          return [] if start_index >= wrapped.length
+
+          slice = wrapped[start_index, length_i] || []
+          cache_put(key, [start_i, length_i], slice)
+          slice
+        end
+
+        def prefetch_windows(lines, chapter_index, width, start, length)
+          wrap_window(lines, chapter_index, width, start, length)
+        end
+
+        # Wrap the visible window and prefetch ±N pages around it in the background.
+        # This centralizes the behavior that was previously embedded in ReaderController.
+        #
+        # @param doc [Object] document responding to #get_chapter(index)
+        # @param chapter_index [Integer]
+        # @param col_width [Integer]
+        # @param offset [Integer] wrapped-line offset
+        # @param display_height [Integer] lines per page
+        # @param pre_pages [Integer,nil] optional number of pages to prefetch; defaults from config
+        # @return [Array<String>] visible wrapped lines for the requested window
+        def fetch_window_and_prefetch(doc, chapter_index, col_width, offset, display_height,
+                                      pre_pages = nil)
+          return [] unless doc && display_height.to_i.positive?
+
+          chapter = doc.get_chapter(chapter_index)
+          return [] unless chapter
+
+          lines = chapter.lines || []
+          start_i = [offset.to_i, 0].max
+          length_i = display_height.to_i
+
+          visible = wrap_window(lines, chapter_index, col_width, start_i, length_i)
+
+          begin
+            pages = pre_pages
+            if pages.nil?
+              st = resolve(:state_store) if registered?(:state_store)
+              pages = begin
+                st.get(%i[config prefetch_pages]) if st.respond_to?(:get)
+              rescue StandardError
+                nil
+              end
+            end
+            pages = pages.nil? ? 20 : pages.to_i
+            pages = pages.clamp(0, 200)
+            window = pages * length_i
+            prefetch_start = [start_i - window, 0].max
+            prefetch_end   = start_i + window + (length_i - 1)
+            prefetch_len   = prefetch_end - prefetch_start + 1
+            enqueue_prefetch(chapter_index, col_width, prefetch_start, prefetch_len, lines)
+          rescue StandardError
+            # best-effort prefetch
+          end
+
+          visible
+        end
+
+        # Clear all cached wrapped lines
+        def clear_cache
+          @chapter_cache = Shoko::Core::Services::Pagination::Internal::ChapterCache.new
+          @window_cache.clear
+        end
+
+        # Clear cache entries for a given width
+        def clear_cache_for_width(width)
+          width_i = width.to_i
+          @chapter_cache.clear_cache_for_width(width_i)
+          @window_cache.delete_if do |key, _|
+            key.is_a?(Array) ? key[2] == width_i : key.to_s.end_with?("_#{width_i}")
+          end
+        end
+
+        protected
+
+        def required_dependencies
+          []
+        end
+
+        private
+
+        # No-op private helpers retained for compatibility-free interface.
+
+        def cache_put(key, subkey, value)
+          entry = @window_cache[key]
+          store = entry[:store]
+          order = entry[:order]
+          unless store.key?(subkey)
+            order << subkey
+            if order.length > WINDOW_CACHE_LIMIT
+              oldest = order.shift
+              store.delete(oldest)
+            end
+          end
+          store[subkey] = value
+        end
+
+        def fetch_formatted_lines(chapter_index, width, offset, length)
+          return unless registered?(:formatting_service)
+
+          document = begin
+            resolve(:document)
+          rescue StandardError
+            nil
+          end
+          return unless document
+
+          formatting = resolve(:formatting_service)
+          lines = formatting.wrap_window(document, chapter_index, width, offset: offset, length: length)
+          return unless lines && !lines.empty?
+
+          lines.map { |line| line.respond_to?(:text) ? line.text : line }
+        rescue StandardError
+          nil
+        end
+
+        def enqueue_prefetch(chapter_index, col_width, prefetch_start, prefetch_len, lines)
+          worker = background_worker
+          job = lambda do
+            prefetch_windows(lines, chapter_index, col_width, prefetch_start, prefetch_len)
+          end
+          if worker
+            worker.submit(&job)
+          else
+            Thread.new do
+              job.call
+            rescue StandardError
+              # ignore background failures
+            end
+          end
+        rescue StandardError
+          # ignore background failures
+        end
+
+        def background_worker
+          return nil unless registered?(:background_worker)
+
+          resolve(:background_worker)
+        rescue StandardError
+          nil
+        end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/output/instrumentation_service.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative '../../core/services/base_service.rb'
+
+module Shoko
+  module Adapters::Output
+      # Provides a single facade for performance monitoring and tracing so that
+      # higher layers do not talk to infrastructure modules directly.
+      class InstrumentationService < BaseService
+        def initialize(dependencies)
+          super
+          @monitor = resolve_optional(:performance_monitor)
+          @tracer  = resolve_optional(:perf_tracer)
+        end
+
+        def time(metric, &)
+          raise ArgumentError, 'block required for #time' unless block_given?
+          return yield unless @monitor.respond_to?(:time)
+
+          @monitor.time(metric, &)
+        end
+
+        def record_metric(name, value, count = 1)
+          @monitor&.record_metric(name, value, count)
+        end
+
+        def record_trace(metric, value)
+          @tracer&.record(metric, value)
+        end
+
+        def complete_trace(**payload)
+          @tracer&.complete(**payload)
+        end
+
+        def cancel_trace
+          @tracer&.cancel
+        end
+
+        def start_trace(path)
+          @tracer.respond_to?(:start_open) ? @tracer.start_open(path) : nil
+        end
+
+        private
+
+        def resolve_optional(name)
+          resolve(name)
+        rescue StandardError
+          nil
+        end
+      end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Shoko
+  module Adapters::Output::Kitty
+    # Converts common raster image formats to PNG bytes so they can be rendered
+    # by the Kitty graphics protocol.
+    #
+    # This is invoked only when Kitty images are enabled and an image is about
+    # to be rendered; it is not part of the default import pipeline.
+    class ImageTranscoder
+      PNG_HEADER = "\x89PNG\r\n\x1a\n".b
+
+      def initialize(command: nil)
+        @command = command || default_command
+      end
+
+      def available?
+        !@command.nil?
+      end
+
+      # @param bytes [String] original image bytes
+      # @return [String,nil] PNG bytes
+      def to_png(bytes)
+        data = String(bytes).dup
+        data.force_encoding(Encoding::BINARY)
+        return nil if data.empty?
+        return data if png?(data)
+        return nil unless available?
+
+        stdout, _stderr, status = Open3.capture3(*@command, stdin_data: data)
+        return nil unless status.success?
+
+        out = String(stdout).dup
+        out.force_encoding(Encoding::BINARY)
+        return nil unless png?(out)
+
+        out
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def png?(bytes)
+        bytes.to_s.b.start_with?(PNG_HEADER)
+      rescue StandardError
+        false
+      end
+
+      def default_command
+        return ['magick', '-', 'png:-'] if executable_in_path?('magick')
+        return ['convert', '-', 'png:-'] if executable_in_path?('convert')
+
+        nil
+      end
+
+      def executable_in_path?(name)
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+          next false if dir.to_s.empty?
+
+          path = File.join(dir, name)
+          File.file?(path) && File.executable?(path)
+        end
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Shoko
+  module Adapters::Output::Kitty
+    # Minimal support for the Kitty graphics protocol.
+    #
+    # This module intentionally keeps all logic in-process (no external commands)
+    # and suppresses terminal responses (q=2) to avoid corrupting raw input reads.
+    module KittyGraphics
+      module_function
+
+      ESC = "\e"
+      APC_START = "#{ESC}_G".freeze
+      APC_END = "#{ESC}\\".freeze
+      MAX_CHUNK_BYTES = 4096
+
+      def supported?
+        return true if env_present?('KITTY_WINDOW_ID')
+        return true if ENV.fetch('TERM', '').include?('kitty')
+        return true if ENV.fetch('TERM_PROGRAM', '') == 'kitty'
+
+        false
+      rescue StandardError
+        false
+      end
+
+      def enabled_for?(config_store)
+        return false unless supported?
+        return false unless config_store.respond_to?(:get)
+
+        !!config_store.get(%i[config kitty_images])
+      rescue StandardError
+        false
+      end
+
+      def transmit_png(image_id, png_bytes, quiet: true)
+        bytes = String(png_bytes).dup
+        bytes.force_encoding(Encoding::BINARY)
+        payload = Base64.strict_encode64(bytes)
+        chunks = chunk_payload(payload)
+        chunks.map.with_index do |chunk, index|
+          more = index < chunks.length - 1 ? 1 : 0
+          keys = if index.zero?
+                   { a: 't', f: 100, t: 'd', i: image_id.to_i, m: more }
+                 else
+                   { m: more }
+                 end
+          keys[:q] = 2 if quiet
+          control = serialize_keys(keys)
+          "#{APC_START}#{control};#{chunk}#{APC_END}"
+        end
+      end
+
+      def place(image_id, placement_id:, cols:, rows:, quiet: true, **options)
+        z = options.fetch(:z, nil)
+        keys = {
+          a: 'p',
+          i: image_id.to_i,
+          p: placement_id.to_i,
+          c: cols.to_i,
+          r: rows.to_i,
+          C: 1,
+        }
+        keys[:q] = 2 if quiet
+        keys[:z] = z.to_i if z
+        "#{APC_START}#{serialize_keys(keys)}#{APC_END}"
+      end
+
+      def virtual_place(image_id, cols:, rows:, placement_id: nil, quiet: true, **options)
+        z = options.fetch(:z, nil)
+        keys = {
+          a: 'p',
+          U: 1,
+          i: image_id.to_i,
+          p: placement_id.to_i,
+          c: cols.to_i,
+          r: rows.to_i,
+          C: 1,
+        }
+        keys.delete(:p) if placement_id.to_i <= 0
+        keys[:q] = 2 if quiet
+        keys[:z] = z.to_i if z
+        "#{APC_START}#{serialize_keys(keys)}#{APC_END}"
+      end
+
+      def delete_visible(quiet: true)
+        keys = { a: 'd' }
+        keys[:q] = 2 if quiet
+        "#{APC_START}#{serialize_keys(keys)}#{APC_END}"
+      end
+
+      def chunk_payload(payload)
+        return [] if payload.nil? || payload.empty?
+
+        max = MAX_CHUNK_BYTES
+        payload.scan(/.{1,#{max}}/m)
+      end
+      private_class_method :chunk_payload
+
+      def serialize_keys(hash)
+        hash.map { |k, v| "#{k}=#{v}" }.join(',')
+      end
+      private_class_method :serialize_keys
+
+      def env_present?(key)
+        value = ENV[key].to_s
+        !value.empty?
+      end
+      private_class_method :env_present?
+    end
+  end
+end

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

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+require_relative '../../book_sources/epub/epub_resource_loader.rb'
+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?
+        end
+        int
+      end
+    end
+  end
+end