shoko 0.1.3 → 0.1.5

data/lib/shoko/adapters/input/controllers/reader/event_loop.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Encapsulates the main reader event loop.
+          class EventLoop
+            NOTIFICATION_POLL_INTERVAL = 0.1
+            BLINK_POLL_INTERVAL = 0.1
+
+            def initialize(controller, reader_state, metrics_start_time, instrumentation, clock:)
+              @controller = controller
+              @reader_state = reader_state
+              @metrics_start_time = metrics_start_time
+              @instrumentation = instrumentation
+              raise ArgumentError, 'clock is required' if clock.nil?
+
+              @clock = clock
+              @tti_recorded = false
+            end
+
+            def run
+              @controller.perform_first_paint
+              startup_reference = @metrics_start_time
+
+              initial_running = running?
+              log_debug('reader.event_loop.start', running: initial_running)
+
+              unless initial_running
+                log_debug('reader.event_loop.immediate_exit', reason: 'running? was false at loop start')
+                return
+              end
+
+              while running?
+                notification_active = toast_message_active?
+                blink_active = annotation_editor_active?
+                keys = if notification_active || blink_active
+                         @controller.read_input_keys(timeout: blink_poll_interval(notification_active))
+                       else
+                         @controller.read_input_keys
+                       end
+                record_tti(startup_reference, keys)
+                if keys.empty?
+                  @controller.draw_screen if notification_active || blink_active
+                  next
+                end
+
+                @controller.dispatch_input_keys(keys)
+                @controller.draw_screen
+              end
+
+              log_debug('reader.event_loop.exit', reason: 'running? became false')
+            end
+
+            private
+
+            def running?
+              @reader_state.running?
+            end
+
+            def record_tti(startup_reference, keys)
+              return if @tti_recorded
+              return unless startup_reference && keys.any?
+
+              @instrumentation&.record_metric(
+                'render.tti',
+                monotonic_now - startup_reference,
+                0
+              )
+              @tti_recorded = true
+            end
+
+            def toast_message_active?
+              message = @reader_state.message
+              message && !message.to_s.empty?
+            end
+
+            def annotation_editor_active?
+              @controller.annotation_editor_active?
+            end
+
+            def blink_poll_interval(notification_active)
+              notification_active ? NOTIFICATION_POLL_INTERVAL : BLINK_POLL_INTERVAL
+            end
+
+            def log_debug(event, **data)
+              @controller.logger&.debug(event, **data)
+            end
+
+            def monotonic_now
+              @clock.monotonic_now
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/input_router.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Routes input to the correct subsystem based on current reader overlays/modes.
+          class InputRouter
+            def initialize(reader_state_reader:, input_controller:, ui_controller:, key_classifier: nil)
+              @reader_state_reader = reader_state_reader
+              @input_controller = input_controller
+              @ui_controller = ui_controller
+              @key_classifier = key_classifier
+            end
+
+            def dispatch_input_keys(keys)
+              if annotations_overlay_active? && !annotation_editor_visible?
+                @input_controller.handle_annotations_overlay_input(keys)
+              elsif dictionary_visible? && cancel_key_pressed?(keys)
+                @ui_controller.close_dictionary
+              elsif in_book_search_visible? && cancel_key_pressed?(keys)
+                @ui_controller.close_in_book_search
+              elsif popup_menu_visible?
+                @input_controller.handle_popup_menu_input(keys)
+              else
+                keys.each { |key| @input_controller.handle_key(key) }
+              end
+            end
+
+            def annotation_editor_active?
+              annotation_editor_visible?
+            end
+
+            private
+
+            def annotations_overlay_active?
+              @ui_controller.annotations_overlay_visible?
+            end
+
+            def annotation_editor_visible?
+              @ui_controller.annotation_editor_visible?
+            end
+
+            def popup_menu_visible?
+              popup_menu = @reader_state_reader.popup_menu
+              popup_menu&.visible
+            end
+
+            def dictionary_visible?
+              @ui_controller.dictionary_visible?
+            end
+
+            def in_book_search_visible?
+              @ui_controller.in_book_search_visible?
+            end
+
+            def cancel_key_pressed?(keys)
+              return false unless @key_classifier
+
+              Array(keys).any? { |key| @key_classifier.cancel_key?(key) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/intent_executor_bridge.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative '../../../../core/ports/outbound/reader_intent_executor'
+require_relative '../../../../core/ports/inbound/reader_intent_handler'
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Adapter-owned execution bridge for reader intent dispatch.
+          class IntentExecutorBridge
+            include Shoko::Core::Ports::Outbound::ReaderIntentExecutor
+
+            INTENT_DISPATCH = {
+              annotation_editor_backspace: [:annotation_editor_backspace, false],
+              annotation_editor_cancel: [:annotation_editor_cancel, false],
+              annotation_editor_enter: [:annotation_editor_enter, false],
+              annotation_editor_insert_char_if_printable: [:annotation_editor_insert_char_if_printable, true],
+              annotation_editor_move_down: [:annotation_editor_move_down, false],
+              annotation_editor_move_left: [:annotation_editor_move_left, false],
+              annotation_editor_move_right: [:annotation_editor_move_right, false],
+              annotation_editor_move_up: [:annotation_editor_move_up, false],
+              annotation_editor_save: [:annotation_editor_save, false],
+              decrease_line_spacing: [:decrease_line_spacing, false],
+              dictionary_backspace: [:dictionary_backspace, false],
+              dictionary_cancel: [:dictionary_cancel, false],
+              dictionary_confirm: [:dictionary_confirm, false],
+              dictionary_cycle_pair: [:dictionary_cycle_pair, false],
+              dictionary_cycle_result: [:dictionary_cycle_result, false],
+              dictionary_insert_char_if_printable: [:dictionary_insert_char_if_printable, true],
+              dictionary_scroll_down: [:dictionary_scroll_down, false],
+              dictionary_scroll_up: [:dictionary_scroll_up, false],
+              dictionary_swap_languages: [:dictionary_swap_languages, false],
+              dictionary_toggle_fuzzy: [:dictionary_toggle_fuzzy, false],
+              handle_popup_action_key: [:handle_popup_action_key, true],
+              handle_popup_cancel: [:handle_popup_cancel, true],
+              handle_popup_navigation: [:handle_popup_navigation, true],
+              help_exit_to_read: [:help_exit_to_read, false],
+              in_book_search_backspace: [:in_book_search_backspace, false],
+              in_book_search_cancel: [:in_book_search_cancel, false],
+              in_book_search_confirm: [:in_book_search_confirm, false],
+              in_book_search_down: [:in_book_search_down, false],
+              in_book_search_insert_char_if_printable: [:in_book_search_insert_char_if_printable, true],
+              in_book_search_up: [:in_book_search_up, false],
+              increase_line_spacing: [:increase_line_spacing, false],
+              invalidate_pagination_cache: [:invalidate_pagination_cache, false],
+              open_annotations: [:open_annotations, false],
+              open_annotations_tab: [:open_annotations_tab, false],
+              open_bookmarks: [:open_bookmarks, false],
+              open_in_book_search: [:open_in_book_search, false],
+              open_toc: [:open_toc, false],
+              quit_application: [:quit_application, false],
+              quit_to_menu: [:quit_to_menu, false],
+              read_confirm_or_sidebar: [:read_confirm_or_sidebar, false],
+              read_scroll_down_or_sidebar: [:read_scroll_down_or_sidebar, false],
+              read_scroll_up_or_sidebar: [:read_scroll_up_or_sidebar, false],
+              read_space_or_sidebar_toggle: [:read_space_or_sidebar_toggle, false],
+              rebuild_pagination: [:rebuild_pagination, false],
+              show_help: [:show_help, false],
+              toggle_page_numbering_mode: [:toggle_page_numbering_mode, false],
+              toggle_view_mode: [:toggle_view_mode, false]
+            }.freeze
+
+            def initialize(reader_controller:)
+              @reader_controller = reader_controller
+              validate_dispatch_contract!
+              validate_controller_methods!
+            end
+
+            def execute(intent_symbol:, payload: nil)
+              key = payload&.key
+              intent = intent_symbol.to_sym
+              entry = INTENT_DISPATCH[intent]
+              raise ArgumentError, "Unsupported reader intent: #{intent_symbol}" unless entry
+
+              method_name, pass_key = entry
+              args = pass_key ? [key] : []
+              @reader_controller.public_send(method_name, *args)
+            end
+
+            private
+
+            def validate_dispatch_contract!
+              expected = Shoko::Core::Ports::Inbound::ReaderIntentHandler::INTENT_SYMBOLS.sort
+              actual = INTENT_DISPATCH.keys.sort
+              return if expected == actual
+
+              missing = expected - actual
+              extra = actual - expected
+              raise ArgumentError, "Reader intent dispatch mismatch missing=#{missing.inspect} extra=#{extra.inspect}"
+            end
+
+            def validate_controller_methods!
+              missing = INTENT_DISPATCH.values.map(&:first).uniq.reject do |method_name|
+                @reader_controller.respond_to?(method_name, true)
+              end
+              return if missing.empty?
+
+              raise ArgumentError, "Reader controller missing dispatch methods: #{missing.join(', ')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/lifecycle_runner.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative 'startup_sequence'
+require_relative '../../../../core/ports/outbound/async_executor'
+require_relative '../../../../core/ports/outbound/background_worker_builder'
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Manages reader runtime startup/shutdown and background worker lifecycle.
+          class LifecycleRunner
+            def initialize(controller, terminal_session:,
+                           background_worker: nil, background_worker_builder: nil,
+                           async_executor: nil, instrumentation_service: nil,
+                           logger: nil, pagination_cache_preloader: nil)
+              @controller = controller
+              @terminal_session = terminal_session
+              @background_worker = background_worker
+              @background_worker_builder = background_worker_builder
+              @async_executor = async_executor
+              @instrumentation_service = instrumentation_service
+              @logger = logger
+              @pagination_cache_preloader = pagination_cache_preloader
+            end
+
+            attr_reader :background_worker
+
+            def ensure_background_worker(name: 'reader-background')
+              return @background_worker if @background_worker
+
+              if worker_executor?(@async_executor)
+                @background_worker = @async_executor
+                return @background_worker
+              end
+
+              builder = @background_worker_builder
+              unless builder.is_a?(Shoko::Core::Ports::Outbound::BackgroundWorkerBuilder)
+                raise Shoko::ConfigurationError, 'background_worker_builder is required and must implement Core::Ports::Outbound::BackgroundWorkerBuilder'
+              end
+
+              @background_worker = builder.build(logger: @logger, name: name)
+              @async_executor = @background_worker if inline_executor?(@async_executor)
+              @background_worker
+            end
+
+            def run
+              ensure_background_worker
+              @terminal_session.setup
+              @controller.mark_metrics_start!
+              StartupSequence.new(
+                terminal_session: @terminal_session,
+                async_executor: @async_executor,
+                instrumentation_service: @instrumentation_service,
+                state_controller: @controller.state_controller,
+                pagination_cache_preloader: @pagination_cache_preloader
+              ).start(@controller)
+              @controller.main_loop
+            rescue Shoko::FatalExternalInputError => e
+              log_fatal_external_input(e)
+              @controller.process_control&.terminate(2)
+            ensure
+              cleanup_session_observers
+              shutdown_background_worker
+              @terminal_session.cleanup
+            end
+
+            def cleanup_session_observers
+              @controller.cleanup_observers
+            end
+
+            def shutdown_background_worker
+              @background_worker&.shutdown
+            ensure
+              @background_worker = nil
+            end
+
+            def worker_executor?(executor)
+              return false unless executor
+
+              executor.is_a?(Shoko::Core::Ports::Outbound::AsyncExecutor) && !inline_executor?(executor)
+            end
+
+            def inline_executor?(executor)
+              return false unless executor
+              return false unless defined?(Shoko::Core::Services::InlineExecutor)
+
+              executor.is_a?(Shoko::Core::Services::InlineExecutor)
+            end
+
+            def log_fatal_external_input(error)
+              @controller.logger&.error(
+                fatal_event_id_for(error),
+                error: error.class.name,
+                message: error.message
+              )
+            end
+
+            def fatal_event_id_for(error)
+              case error
+              when Shoko::MalformedBookInputError
+                'fatal.external_input.book'
+              when Shoko::MalformedMetadataInputError
+                'fatal.external_input.metadata'
+              when Shoko::MalformedDictionaryInputError
+                'fatal.external_input.dictionary'
+              else
+                'fatal.external_input.unknown'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/render_metrics.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Tracks startup rendering milestones and records first-paint metrics.
+          class RenderMetrics
+            def initialize(instrumentation:, metrics_start_time_reader:, document_reader:, clock:)
+              @instrumentation = instrumentation
+              @metrics_start_time_reader = metrics_start_time_reader
+              @document_reader = document_reader
+              raise ArgumentError, 'clock is required' if clock.nil?
+
+              @clock = clock
+            end
+
+            def perform_first_paint(draw_screen:)
+              @instrumentation&.time('render.first_paint') { draw_screen.call }
+              metrics_start_time = @metrics_start_time_reader.call
+              unless metrics_start_time
+                @instrumentation&.cancel_trace
+                return
+              end
+
+              first_paint_completed_at = monotonic_now
+              ttfp = first_paint_completed_at - metrics_start_time
+              @instrumentation&.record_metric('render.first_paint.ttfp', ttfp, 0)
+              @instrumentation&.record_trace('render.first_paint.ttfp', ttfp)
+              open_type = if cache_hit?
+                            'warm'
+                          else
+                            'cold'
+                          end
+              @instrumentation&.complete_trace(open_type:, total_duration: ttfp)
+            end
+
+            private
+
+            def cache_hit?
+              doc = @document_reader.call
+              doc&.cached? == true
+            end
+
+            def monotonic_now
+              @clock.monotonic_now
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/render_requester_bridge.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../../../../core/ports/outbound/reader_render_requester'
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Adapter bridge that translates render requests into controller redraw calls.
+          class RenderRequesterBridge
+            include Shoko::Core::Ports::Outbound::ReaderRenderRequester
+
+            def initialize(controller:, logger: nil)
+              @controller = controller
+              @logger = logger
+            end
+
+            def request_render(reason:)
+              @controller.force_redraw
+              @controller.draw_screen
+            rescue RuntimeError, SystemCallError, IOError, ArgumentError => e
+              @logger&.debug('reader.render_request.failed',
+                             reason: reason,
+                             error: e.class.name,
+                             message: e.message)
+              raise Shoko::Core::Ports::Outbound::ReaderRenderRequester::RenderRequestError,
+                    "Render request failed (#{reason}): #{e.message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/startup_loader.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../../../../core/ports/outbound/document_loader'
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Handles reader startup data loading and preloaded-document validation.
+          class StartupLoader
+            def initialize(path:, document_loader:, reader_launch_state:, state_writer:, document_matches_path:,
+                           logger: nil)
+              @path = path
+              unless document_loader.is_a?(Shoko::Core::Ports::Outbound::DocumentLoader)
+                raise ArgumentError, 'document_loader must implement Core::Ports::Outbound::DocumentLoader'
+              end
+              @document_loader = document_loader
+              @reader_launch_state = reader_launch_state
+              @state_writer = state_writer
+              @document_matches_path = document_matches_path
+              @logger = logger
+            end
+
+            def validate_preloaded_document(existing, target_path)
+              return nil unless existing
+
+              return existing if @document_matches_path.call(existing, target_path)
+
+              nil
+            end
+
+            def load_document(current_doc:, on_loaded:)
+              return current_doc if current_doc
+
+              doc = @document_loader.load(path: @path)
+              @reader_launch_state.set_preloaded_document(doc) if @reader_launch_state
+              @state_writer.update_pagination_state(total_chapters: doc&.chapter_count || 0)
+              on_loaded.call(doc)
+              doc
+            end
+
+            def load_saved_state(state_controller:)
+              state_controller.load_progress
+              state_controller.load_bookmarks
+              state_controller.refresh_annotations
+            end
+
+            def apply_pending_jump(jump_handler:)
+              jump_handler.apply
+            rescue Shoko::FatalExternalInputError
+              raise
+            rescue Shoko::Error => e
+              @logger&.debug('Pending jump apply failed', error: e.message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/input/controllers/reader/startup_sequence.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Input
+      module Controllers
+        module Reader
+          # Orchestrates reader startup: progress restore, preload, and async warmup tasks.
+          class StartupSequence
+            def initialize(terminal_session:, async_executor:,
+                           instrumentation_service: nil, state_controller: nil,
+                           pagination_cache_preloader: nil)
+              @terminal_session = terminal_session
+              @async_executor = async_executor
+              @instrumentation_service = instrumentation_service
+              @state_controller = state_controller
+              @pagination_cache_preloader = pagination_cache_preloader
+            end
+
+            def start(controller)
+              wrap_with_instrumentation(@instrumentation_service, 'startup.reader') do
+                doc = controller.doc
+
+                height, width = @terminal_session.size
+
+                @state_controller&.load_progress
+                controller.pagination_coordinator&.apply_pending_progress_if_ready
+
+                if doc&.cached?
+                  result = @pagination_cache_preloader&.preload(doc, width:, height:)
+                  controller.clear_defer_page_map! if result && result.status == :hit
+                end
+
+                controller.perform_initial_calculations_if_needed if controller.pending_initial_calculation?
+                controller.schedule_background_page_map_build if controller.defer_page_map?
+
+                submit_background_job do
+                  next unless @state_controller
+
+                  @state_controller.load_bookmarks
+                  @state_controller.refresh_annotations
+                end
+              end
+            end
+
+            private
+
+            def wrap_with_instrumentation(instrumentation, metric, &)
+              if instrumentation
+                instrumentation.time(metric, &)
+              else
+                yield
+              end
+            end
+
+            def submit_background_job(&)
+              @async_executor.submit(&)
+            end
+          end
+        end
+      end
+    end
+  end
+end