shoko 0.1.0

data/lib/shoko/core/services/pagination/pagination_cache_preloader.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative '../pagination'
+require_relative '../../../adapters/output/kitty/kitty_graphics.rb'
+
+module Shoko::Core::Services::Pagination
+    # Centralises the logic for hydrating dynamic pagination from the cache.
+    class PaginationCachePreloader
+      # Preload outcome with an optional cache key.
+      Result = Struct.new(:status, :key, keyword_init: true)
+      # Requested terminal dimensions (before defaults are applied).
+      Dimensions = Struct.new(:width, :height, keyword_init: true)
+      # Layout metadata used for pagination cache lookups.
+      LayoutSpec = Struct.new(:key, :width, :height, :view_mode, :line_spacing, :kitty_images, keyword_init: true)
+      private_constant :Result, :Dimensions, :LayoutSpec
+
+      def initialize(state:, page_calculator:, pagination_cache:)
+        @state = state
+        @page_calculator = page_calculator
+        @pagination_cache = pagination_cache
+      end
+
+      def preload(doc, width:, height:)
+        guard = guard_preload(doc)
+        return guard if guard
+
+        dimensions = resolve_dimensions(Dimensions.new(width: width, height: height))
+        layout, miss_key = resolve_layout(doc, dimensions)
+        return Result.new(status: :miss, key: miss_key) unless layout
+
+        apply_layout_config(layout)
+        cached_pages = load_cached_pages(doc, layout.key)
+        return Result.new(status: :miss, key: layout.key) unless cached_pages
+
+        hydrate_from_cache(cached_pages, dimensions)
+        Result.new(status: :hit, key: layout.key)
+      rescue StandardError => e
+        log_failure(e)
+        Result.new(status: :error)
+      end
+
+      private
+
+      attr_reader :state, :page_calculator, :pagination_cache
+
+      def guard_preload(doc)
+        return Result.new(status: :invalid) unless doc
+        return Result.new(status: :unavailable) unless dynamic_mode?
+
+        Result.new(status: :no_calculator) unless page_calculator
+      end
+
+      def resolve_dimensions(requested)
+        width = requested.width || state.get(%i[ui terminal_width]) || 80
+        height = requested.height || state.get(%i[ui terminal_height]) || 24
+        Dimensions.new(width: width, height: height)
+      end
+
+      def resolve_layout(doc, dimensions)
+        layout = build_layout_spec(dimensions)
+        miss_key = layout.key
+        return [layout, miss_key] if pagination_cache.exists_for_document?(doc, layout.key)
+
+        [find_fallback_layout(doc, layout), miss_key]
+      end
+
+      def dynamic_mode?
+        Shoko::Application::Selectors::ConfigSelectors.page_numbering_mode(state) == :dynamic
+      end
+
+      def build_layout_spec(dimensions)
+        view_mode = current_view_mode
+        line_spacing = current_line_spacing
+        kitty_images = Shoko::Adapters::Output::Kitty::KittyGraphics.enabled_for?(state)
+        key = pagination_cache.layout_key(
+          dimensions.width,
+          dimensions.height,
+          view_mode,
+          line_spacing,
+          kitty_images: kitty_images
+        )
+        LayoutSpec.new(
+          key: key,
+          width: dimensions.width,
+          height: dimensions.height,
+          view_mode: view_mode,
+          line_spacing: line_spacing,
+          kitty_images: kitty_images
+        )
+      end
+
+      def apply_layout_config(layout)
+        state.apply_terminal_dimensions(layout.width, layout.height)
+        update_config(layout)
+      end
+
+      def update_config(layout)
+        updates = {}
+        updates[%i[config view_mode]] = layout.view_mode if layout.view_mode
+        updates[%i[config line_spacing]] = layout.line_spacing if layout.line_spacing
+        state.update(updates) unless updates.empty?
+      end
+
+      def load_cached_pages(doc, key)
+        cached_pages = pagination_cache.load_for_document(doc, key)
+        cached_pages if cached_pages&.any?
+      end
+
+      def hydrate_from_cache(cached_pages, dimensions)
+        page_calculator.hydrate_from_cache(
+          cached_pages,
+          state: state,
+          width: dimensions.width,
+          height: dimensions.height
+        )
+        page_calculator.apply_pending_precise_restore!(state)
+      end
+
+      def log_failure(error)
+        logger = begin
+          state.resolve(:logger)
+        rescue StandardError
+          nil
+        end
+        logger&.debug('PaginationCachePreloader: failed', error: error.message)
+      end
+
+      def find_fallback_layout(doc, layout)
+        keys = pagination_cache.layout_keys_for_document(doc)
+        return nil if keys.empty?
+
+        preferred = preferred_key(keys, layout)
+        return nil unless preferred
+
+        layout_from_key(preferred)
+      end
+
+      def preferred_key(keys, layout)
+        keys.find { |candidate| layout_key_matches?(candidate, layout) }
+      end
+
+      def layout_key_matches?(candidate, layout)
+        parsed = pagination_cache.parse_layout_key(candidate)
+        return false unless parsed
+
+        parsed[:view_mode] == layout.view_mode &&
+          parsed[:line_spacing] == layout.line_spacing &&
+          parsed[:kitty_images] == layout.kitty_images
+      end
+
+      def layout_from_key(key)
+        parsed = pagination_cache.parse_layout_key(key)
+        return nil unless parsed
+
+        LayoutSpec.new(
+          key: key,
+          width: parsed[:width],
+          height: parsed[:height],
+          view_mode: parsed[:view_mode],
+          line_spacing: parsed[:line_spacing],
+          kitty_images: parsed[:kitty_images]
+        )
+      end
+
+      def current_view_mode
+        Shoko::Application::Selectors::ConfigSelectors.view_mode(state)
+      end
+
+      def current_line_spacing
+        Shoko::Application::Selectors::ConfigSelectors.line_spacing(state)
+      end
+    end
+end

data/lib/shoko/core/services/pagination/pagination_coordinator.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative '../pagination'
+require_relative 'page_info_calculator'
+require_relative 'pagination_orchestrator'
+
+module Shoko::Core::Services::Pagination
+    # Coordinates pagination-related workflows for the reader.
+    class PaginationCoordinator
+      # Aggregated pagination dependencies.
+      Dependencies = Struct.new(
+        :state,
+        :doc,
+        :page_calculator,
+        :layout_service,
+        :terminal_service,
+        :pagination_cache,
+        :frame_coordinator,
+        :ui_controller,
+        :render_callback,
+        :background_worker_provider,
+        keyword_init: true
+      )
+
+      # State flags for deferred pagination behavior.
+      Flags = Struct.new(:pending_initial_calculation, :defer_page_map, keyword_init: true)
+
+      def initialize(dependencies:)
+        @deps = dependencies
+        @orchestrator = PaginationOrchestrator.new(
+          terminal_service: dependencies.terminal_service,
+          pagination_cache: dependencies.pagination_cache,
+          frame_coordinator: dependencies.frame_coordinator
+        )
+        @flags = Flags.new(pending_initial_calculation: true, defer_page_map: false)
+        seed_flags
+      end
+
+      def pending_initial_calculation?
+        @flags.pending_initial_calculation
+      end
+
+      def defer_page_map?
+        @flags.defer_page_map
+      end
+
+      def clear_defer_page_map!
+        @flags.defer_page_map = false
+      end
+
+      def perform_initial_calculations_if_needed
+        perform_initial_calculations_with_progress if pending_initial_calculation? && !preloaded_page_data?
+        @flags.pending_initial_calculation = false
+      end
+
+      def schedule_background_page_map_build
+        return unless defer_page_map?
+
+        submit_background_job { build_page_map_in_background }
+      rescue StandardError
+        @flags.defer_page_map = false
+      end
+
+      def refresh_after_resize(width:, height:)
+        return if defer_page_map?
+
+        session(dimensions: [width, height])&.refresh_after_resize
+      end
+
+      def rebuild_after_config_change
+        session(dimensions: terminal_dimensions)&.rebuild_after_config_change
+      rescue StandardError
+        nil
+      end
+
+      def rebuild_dynamic
+        result = session&.rebuild_dynamic
+        render_callback&.call
+        result
+      end
+
+      def rebuild_pagination(_key = nil)
+        rebuild_dynamic
+      end
+
+      def invalidate_cache
+        result = session(dimensions: terminal_dimensions)&.invalidate_cache || :missing
+        apply_invalidate_message(result)
+        :handled
+      end
+
+      def invalidate_pagination_cache(_key = nil)
+        invalidate_cache
+      end
+
+      def page_info
+        calculator = PageInfoCalculator.new(
+          dependencies: PageInfoCalculator::Dependencies.new(
+            state: deps.state,
+            doc: deps.doc,
+            page_calculator: deps.page_calculator,
+            layout_service: deps.layout_service,
+            terminal_service: deps.terminal_service,
+            pagination_orchestrator: @orchestrator
+          ),
+          defer_page_map: defer_page_map?
+        )
+        calculator.calculate
+      rescue StandardError
+        { type: :single, current: 0, total: 0 }
+      end
+
+      private
+
+      attr_reader :deps
+
+      def render_callback
+        deps.render_callback
+      end
+
+      def background_worker
+        provider = deps.background_worker_provider
+        provider&.call
+      end
+
+      def terminal_dimensions
+        height, width = deps.terminal_service.size
+        [width, height]
+      end
+
+      def session(dimensions: nil)
+        @orchestrator.session(
+          doc: deps.doc,
+          state: deps.state,
+          page_calculator: deps.page_calculator,
+          dimensions: dimensions
+        )
+      end
+
+      def perform_initial_calculations_with_progress
+        return unless deps.doc
+
+        session = session(dimensions: terminal_dimensions)
+        return unless session
+
+        session.initial_build
+        render_callback&.call
+      end
+
+      def build_page_map_in_background
+        session(dimensions: terminal_dimensions)&.build_full_map
+        @flags.defer_page_map = false
+        render_callback&.call
+      rescue StandardError
+        @flags.defer_page_map = false
+      end
+
+      def submit_background_job(&)
+        worker = background_worker
+        if worker
+          worker.submit(&)
+        else
+          Thread.new do
+            yield
+          rescue StandardError
+            # ignore background failures
+          end
+        end
+      end
+
+      def preloaded_page_data?
+        if Shoko::Application::Selectors::ConfigSelectors.page_numbering_mode(deps.state) == :dynamic
+          return deps.page_calculator&.total_pages&.positive?
+        end
+
+        deps.state.get(%i[reader total_pages]).to_i.positive?
+      end
+
+      def seed_flags
+        return unless deps.doc.respond_to?(:cached?) && deps.doc.cached?
+
+        @flags.pending_initial_calculation = false
+        @flags.defer_page_map = true
+        return unless deps.page_calculator && deps.page_calculator.total_pages.to_i.positive?
+
+        @flags.defer_page_map = false
+      end
+
+      def apply_invalidate_message(result)
+        return unless deps.ui_controller
+
+        case result
+        when :deleted
+          deps.ui_controller.set_message('Pagination cache cleared')
+        when :missing
+          deps.ui_controller.set_message('No pagination cache for this layout')
+        else
+          deps.ui_controller.set_message('Failed to clear pagination cache')
+        end
+      end
+    end
+end

data/lib/shoko/core/services/pagination/pagination_orchestrator.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require_relative '../pagination'
+require_relative '../../../adapters/output/kitty/kitty_graphics.rb'
+
+module Shoko::Core::Services::Pagination
+    # Handles pagination builds (dynamic/absolute) and progress overlay.
+    # Keeps heavy orchestration out of ReaderController while preserving behavior.
+    class PaginationOrchestrator
+      # Factory for selecting per-mode pagination strategies.
+      module StrategyFactory
+        module_function
+
+        def select(session)
+          mode = Shoko::Application::Selectors::ConfigSelectors.page_numbering_mode(session.state)
+          mode == :dynamic ? DynamicStrategy : AbsoluteStrategy
+        end
+      end
+
+      # Base strategy type for pagination operations.
+      class Strategy
+        def initialize(session)
+          @session = session
+        end
+
+        private
+
+        attr_reader :session
+      end
+
+      # Dynamic pagination behavior.
+      class DynamicStrategy < Strategy
+        def build_full_map(progress: nil)
+          session.build_dynamic_map(progress: progress)
+          nil
+        end
+
+        def build_initial_map(progress:)
+          build_full_map(progress: progress)
+        end
+
+        def refresh_after_resize
+          session.build_dynamic_map
+          session.clamp_dynamic_index!
+        end
+
+        def rebuild_after_config_change
+          payload = session.pending_progress_payload
+          session.state.dispatch(Shoko::Application::Actions::UpdateSelectionsAction.new(pending_progress: payload))
+          session.build_dynamic_map
+          session.clamp_dynamic_index!
+        end
+
+        def rebuild_dynamic(progress:)
+          payload = session.pending_progress_payload
+          session.with_loading('Rebuilding pagination…') do
+            session.state.dispatch(Shoko::Application::Actions::UpdateSelectionsAction.new(pending_progress: payload))
+            session.build_dynamic_map(progress: progress)
+          end
+          :handled
+        end
+      end
+
+      # Absolute pagination behavior.
+      class AbsoluteStrategy < Strategy
+        def build_full_map(progress: nil)
+          session.build_absolute_map(progress: progress)
+        end
+
+        def build_initial_map(progress:)
+          build_full_map(progress: progress)
+        end
+
+        def refresh_after_resize
+          session.build_absolute_map
+        end
+
+        def rebuild_after_config_change
+          session.build_absolute_map
+        end
+
+        def rebuild_dynamic(progress:)
+          :pass
+        end
+      end
+
+      # Aggregates pagination inputs and exposes a per-document session API.
+      class PaginationSession
+        attr_reader :doc, :state, :page_calculator, :dimensions
+
+        def initialize(doc:, state:, page_calculator:, dimensions:, pagination_cache:, frame_coordinator:)
+          @doc = doc
+          @state = state
+          @page_calculator = page_calculator
+          @dimensions = dimensions
+          @pagination_cache = pagination_cache
+          @frame_coordinator = frame_coordinator
+        end
+
+        def build_full_map!(progress: nil, &block)
+          progress ||= block
+          strategy.build_full_map(progress: progress)
+        end
+
+        def build_full_map(progress: nil, &)
+          build_full_map!(progress: progress, &)
+        end
+
+        def refresh_after_resize
+          strategy.refresh_after_resize
+        end
+
+        def rebuild_after_config_change
+          strategy.rebuild_after_config_change
+        end
+
+        # Performs the initial pagination calculation with a loading overlay.
+        # Returns a hash with optional :page_map_cache for absolute mode.
+        def initial_build
+          cache = nil
+          with_loading('Calculating pages...') do
+            map = strategy.build_initial_map(progress: progress_callback)
+            cache = map ? build_absolute_cache_entry(map) : nil
+          end
+          { page_map_cache: cache }
+        end
+
+        # Rebuilds dynamic pagination with a loading overlay and precise restore.
+        def rebuild_dynamic
+          strategy.rebuild_dynamic(progress: progress_callback)
+        end
+
+        # Remove the cached pagination entry for the supplied dimensions.
+        #
+        # @return [Symbol] :deleted when cache entry removed, :missing when no entry existed,
+        #   :error when removal fails.
+        def invalidate_cache
+          return :missing unless doc && @pagination_cache
+
+          key = @pagination_cache.layout_key(width, height, view_mode, line_spacing, kitty_images: kitty_images?)
+          return :missing unless key && @pagination_cache.exists_for_document?(doc, key)
+
+          @pagination_cache.delete_for_document(doc, key)
+          :deleted
+        rescue StandardError
+          :error
+        end
+
+        def width
+          dimensions[0]
+        end
+
+        def height
+          dimensions[1]
+        end
+
+        def view_mode
+          Shoko::Application::Selectors::ConfigSelectors.view_mode(state)
+        end
+
+        def line_spacing
+          Shoko::Application::Selectors::ConfigSelectors.line_spacing(state)
+        end
+
+        def kitty_images?
+          Shoko::Adapters::Output::Kitty::KittyGraphics.enabled_for?(state)
+        end
+
+        def pending_progress_payload
+          current_chapter = state.get(%i[reader current_chapter]) || 0
+          current_index = state.get(%i[reader current_page_index]).to_i
+          page = page_calculator.get_page(current_index)
+          {
+            chapter_index: current_chapter,
+            line_offset: page ? page[:start_line] : 0,
+          }
+        end
+
+        def build_dynamic_map(progress: nil)
+          Shoko::Adapters::Monitoring::PerfTracer.measure('pagination.build') do
+            page_calculator.build_dynamic_map!(width, height, doc, state) do |done, total|
+              progress&.call(done, total)
+            end
+          end
+          page_calculator.apply_pending_precise_restore!(state)
+        end
+
+        def build_absolute_map(progress: nil)
+          Shoko::Adapters::Monitoring::PerfTracer.measure('pagination.build') do
+            page_calculator.build_absolute_map!(width, height, doc, state) do |done, total|
+              progress&.call(done, total)
+            end
+          end
+        end
+
+        def clamp_dynamic_index!
+          total = page_calculator.total_pages.to_i
+          return if total <= 0
+
+          current = state.get(%i[reader current_page_index]).to_i
+          clamped = current.clamp(0, total - 1)
+          state.dispatch(
+            Shoko::Application::Actions::UpdatePageAction.new(current_page_index: clamped)
+          )
+        end
+
+        def progress_callback
+          ->(done, total) { update_progress(done, total) }
+        end
+
+        def with_loading(message)
+          begin_loading(message)
+          yield
+        ensure
+          end_loading
+        end
+
+        def begin_loading(message)
+          state.dispatch(Shoko::Application::Actions::UpdateUILoadingAction.new(
+                           loading_active: true,
+                           loading_message: message,
+                           loading_progress: 0.0
+                         ))
+          @frame_coordinator&.render_loading_overlay
+        end
+
+        def end_loading
+          state.dispatch(Shoko::Application::Actions::UpdateUILoadingAction.new(
+                           loading_active: false,
+                           loading_message: nil
+                         ))
+        end
+
+        def update_progress(done, total)
+          progress = Shoko::Core::Services::ProgressHelper.ratio(done, total)
+          state.dispatch(Shoko::Application::Actions::UpdateUILoadingAction.new(
+                           loading_progress: progress
+                         ))
+          @frame_coordinator&.render_loading_overlay
+        end
+
+        def build_absolute_cache_entry(page_map)
+          key = @pagination_cache&.layout_key(
+            width,
+            height,
+            view_mode,
+            line_spacing,
+            kitty_images: kitty_images?
+          )
+          {
+            key: key,
+            map: page_map,
+            total: Array(page_map).sum,
+          }
+        end
+
+        private
+
+        def strategy
+          @strategy ||= StrategyFactory.select(self).new(self)
+        end
+      end
+
+      def initialize(terminal_service:, pagination_cache: nil, frame_coordinator: nil)
+        @terminal_service = terminal_service
+        @pagination_cache = pagination_cache
+        @frame_coordinator = frame_coordinator
+      end
+
+      def session(doc:, state:, page_calculator:, dimensions: nil)
+        return nil unless doc && page_calculator
+
+        dims = dimensions || terminal_dimensions
+        PaginationSession.new(
+          doc: doc,
+          state: state,
+          page_calculator: page_calculator,
+          dimensions: dims,
+          pagination_cache: @pagination_cache,
+          frame_coordinator: @frame_coordinator
+        )
+      end
+
+      private
+
+      def terminal_dimensions
+        height, width = @terminal_service.size
+        [width, height]
+      end
+    end
+end

data/lib/shoko/core/services/pagination.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module Services
+      module Pagination
+      end
+    end
+  end
+end

data/lib/shoko/core/services/progress_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module Services
+      # Utility helpers for normalizing progress metrics across menu and reader flows.
+      module ProgressHelper
+      module_function
+
+      # Normalize partial progress against a total, guarding against zero denominators.
+      #
+      # @param done [Numeric]
+      # @param total [Numeric]
+      # @return [Float]
+      def ratio(done, total)
+        denom = [total.to_f, 1.0].max
+        done.to_f / denom
+      end
+      end
+    end
+  end
+end