shoko 0.1.3 → 0.1.5

data/lib/shoko/adapters/ui/components/ui/overlay_layout.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../../../../shared/terminal/ansi'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Components
+        module Ui
+          # Calculates overlay dimensions based on viewport bounds.
+          class OverlaySizing
+            def initialize(width_ratio:, width_padding:, min_width:, height_ratio:, height_padding:, min_height:)
+              @width_ratio = width_ratio
+              @width_padding = width_padding
+              @min_width = min_width
+              @height_ratio = height_ratio
+              @height_padding = height_padding
+              @min_height = min_height
+            end
+
+            def width_for(total_width)
+              clamp_dimension(total_width, ratio: @width_ratio, padding: @width_padding, min: @min_width)
+            end
+
+            def height_for(total_height)
+              clamp_dimension(total_height, ratio: @height_ratio, padding: @height_padding, min: @min_height)
+            end
+
+            private
+
+            def clamp_dimension(total, ratio:, padding:, min:)
+              base = [(total * ratio).floor, total - padding].min
+              upper = total - padding
+              lower = [min, upper].min
+              base.clamp(lower, upper)
+            end
+          end
+
+          # Provides centered overlay placement and frame geometry helpers.
+          class OverlayLayout
+            attr_reader :origin_x, :origin_y, :width, :height
+
+            def initialize(origin_x:, origin_y:, width:, height:)
+              @origin_x = origin_x
+              @origin_y = origin_y
+              @width = width
+              @height = height
+            end
+
+            def self.centered(bounds, width:, height:)
+              origin_x = [(bounds.width - width) / 2, 1].max + 1
+              origin_y = [(bounds.height - height) / 2, 1].max + 1
+              new(origin_x: origin_x, origin_y: origin_y, width: width, height: height)
+            end
+
+            # Backward-compatible accessors used by some overlays.
+            def start_col
+              origin_x
+            end
+
+            def start_row
+              origin_y
+            end
+
+            def inner_x
+              origin_x + 1
+            end
+
+            def inner_y
+              origin_y + 1
+            end
+
+            def inner_width
+              width - 2
+            end
+
+            def inner_height
+              height - 2
+            end
+
+            def fill_background(surface, bounds, background:)
+              reset = Shoko::Shared::Terminal::Ansi::RESET
+              height.times do |offset|
+                surface.write(bounds, origin_y + offset, origin_x, "#{background}#{' ' * width}#{reset}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/components/ui/text_utils.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../../../../shared/terminal/text_metrics'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Components
+        module Ui
+          # Shared text layout utilities for terminal UI rendering.
+          module TextUtils
+            module_function
+
+            def wrap_text(text, width)
+              t = (text || '').to_s
+              w = width.to_i
+              return [''] if t.empty?
+              return [''] if w <= 0
+
+              Shoko::Shared::Terminal::TextMetrics.wrap_cells(t, w)
+            end
+
+            def truncate_text(text, max_length)
+              str = (text || '').to_s
+              w = max_length.to_i
+              return '' if w <= 0
+
+              return str if Shoko::Shared::Terminal::TextMetrics.visible_length(str) <= w
+
+              ellipsis = '...'
+              ellipsis_w = Shoko::Shared::Terminal::TextMetrics.visible_length(ellipsis)
+              return Shoko::Shared::Terminal::TextMetrics.truncate_to(str, w) if ellipsis_w >= w
+
+              base = Shoko::Shared::Terminal::TextMetrics.truncate_to(str, w - ellipsis_w)
+              base + ellipsis
+            end
+
+            def pad_right(text, width, pad: ' ')
+              Shoko::Shared::Terminal::TextMetrics.pad_right(text.to_s, width.to_i, pad: pad)
+            end
+
+            def pad_left(text, width, pad: ' ')
+              Shoko::Shared::Terminal::TextMetrics.pad_left(text.to_s, width.to_i, pad: pad)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/constants/highlighting.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Ui
+      module Constants
+        # Text highlighting patterns used by reading renderers.
+        module Highlighting
+          HIGHLIGHT_WORDS = [
+            'Chinese poets', 'philosophers', 'Taoyuen-ming', 'celebrated', 'fragrance',
+            'plum-blossoms', 'Linwosing', 'Chowmushih'
+          ].freeze
+          HIGHLIGHT_PATTERNS = Regexp.union(HIGHLIGHT_WORDS)
+          # Matches basic quoted spans for optional highlighting. Supports:
+          # - ASCII quotes: "..." and '...'
+          # - Curly quotes: “...” and ‘...’
+          # - Guillemets: «...» and ‹...›
+          QUOTE_PATTERNS = /(["“„«‹][^"“”„«»‹›]*["”»›])|(['‘‚][^'‘’‚]*['’])/
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/constants/messages.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Ui
+      module Constants
+        module Messages
+          BOOKMARK_ADDED = 'Bookmark added!'
+          BOOKMARK_DELETED = 'Bookmark deleted!'
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/constants/themes.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative '../../../shared/terminal/ansi'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Constants
+        # Theme palettes used by the terminal render style system.
+        module Themes
+          DEFAULT_PALETTE = {
+            primary: Shoko::Shared::Terminal::Ansi::DEFAULT_FG,
+            accent: Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN,
+            heading: Shoko::Shared::Terminal::Ansi::BRIGHT_GREEN,
+            dim: "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}",
+            quote: "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}",
+            code: Shoko::Shared::Terminal::Ansi::YELLOW,
+            separator: "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}",
+            prefix: "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}",
+          }.freeze
+
+          THEMES = {
+            default: DEFAULT_PALETTE,
+            standard: DEFAULT_PALETTE,
+            gray: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::LIGHT_GREY,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_WHITE,
+              quote: Shoko::Shared::Terminal::Ansi::GRAY
+            ).freeze,
+            sepia: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::YELLOW,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_YELLOW,
+              dim: Shoko::Shared::Terminal::Ansi::DIM,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_YELLOW
+            ).freeze,
+            grass: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::GREEN,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_GREEN,
+              quote: Shoko::Shared::Terminal::Ansi::GREEN
+            ).freeze,
+            cherry: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::RED,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_RED,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_RED
+            ).freeze,
+            sky: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::BLUE,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_BLUE,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_BLUE
+            ).freeze,
+            solarized: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::CYAN,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN
+            ).freeze,
+            gruvbox: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::YELLOW,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_GREEN,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_YELLOW
+            ).freeze,
+            nord: DEFAULT_PALETTE.merge(
+              primary: Shoko::Shared::Terminal::Ansi::BRIGHT_BLUE,
+              accent: Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN,
+              quote: Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN
+            ).freeze,
+          }.freeze
+
+          module_function
+
+          def palette_for(theme)
+            theme_key = theme&.to_sym
+            base = DEFAULT_PALETTE
+            return base unless theme_key
+
+            THEMES[theme_key] || base
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/constants/ui_constants.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative '../../../shared/terminal/ansi'
+require_relative '../../../shared/ui_constraints'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Constants
+        # Centralized UI color and style definitions
+        module Ui
+          # Dimensions
+          MIN_WIDTH = Shoko::Shared::UiConstraints::MIN_TERMINAL_WIDTH
+          MIN_HEIGHT = Shoko::Shared::UiConstraints::MIN_TERMINAL_HEIGHT
+
+          # Base Colors
+          COLOR_TEXT_PRIMARY = Shoko::Shared::Terminal::Ansi::DEFAULT_FG
+          COLOR_TEXT_SECONDARY = "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}".freeze
+          COLOR_TEXT_DIM = "#{Shoko::Shared::Terminal::Ansi::DEFAULT_FG}#{Shoko::Shared::Terminal::Ansi::DIM}".freeze
+          COLOR_TEXT_ACCENT = Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN
+          COLOR_TEXT_SUCCESS = Shoko::Shared::Terminal::Ansi::GREEN
+          COLOR_TEXT_WARNING = Shoko::Shared::Terminal::Ansi::YELLOW
+          COLOR_TEXT_ERROR = Shoko::Shared::Terminal::Ansi::RED
+
+          # Backgrounds
+          BG_PRIMARY = Shoko::Shared::Terminal::Ansi::BG_DARK
+          BG_ACCENT = Shoko::Shared::Terminal::Ansi::BG_BRIGHT_YELLOW
+
+          # Borders & Dividers
+          BORDER_PRIMARY = Shoko::Shared::Terminal::Ansi::GRAY
+          BORDER_ACCENT = Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN
+
+          # Selections & Highlights
+          SELECTION_POINTER = '▸ '
+          SELECTION_FG = Shoko::Shared::Terminal::Ansi::BLACK
+          SELECTION_POINTER_COLOR = Shoko::Shared::Terminal::Ansi::BRIGHT_GREEN
+          SELECTION_HIGHLIGHT = Shoko::Shared::Terminal::Ansi::BRIGHT_WHITE
+
+          # Overlay/Highlight backgrounds
+          HIGHLIGHT_BG_LIGHT = "\e[48;2;230;230;234m"
+          HIGHLIGHT_BG_DARK = "\e[48;2;52;56;70m"
+          HIGHLIGHT_BG_ACTIVE = HIGHLIGHT_BG_DARK
+          HIGHLIGHT_BG_SAVED = HIGHLIGHT_BG_DARK
+
+          # Popup menu colors
+          POPUP_BG_DEFAULT = Shoko::Shared::Terminal::Ansi::BG_SLATE
+          POPUP_BG_SELECTED = Shoko::Shared::Terminal::Ansi::BG_SOFT_GREEN
+          POPUP_FG_DEFAULT = COLOR_TEXT_PRIMARY
+          POPUP_FG_SELECTED = Shoko::Shared::Terminal::Ansi::BLACK
+
+          # Tooltip menu colors
+          # Keep palette close to LazyVim-style popup menus:
+          # muted slate base, subtle gray-blue selection, low-saturation foreground.
+          TOOLTIP_GLASS_BG_DEFAULT = "\e[48;2;30;30;46m"
+          TOOLTIP_GLASS_BG_SELECTED = "\e[48;2;69;71;90m"
+          TOOLTIP_GLASS_FG_DEFAULT = "\e[38;2;56;60;78m#{Shoko::Shared::Terminal::Ansi::DIM}"
+          TOOLTIP_GLASS_FG_SELECTED = "\e[38;2;92;98;122m#{Shoko::Shared::Terminal::Ansi::DIM}"
+
+          TOOLTIP_BG_DEFAULT = TOOLTIP_GLASS_BG_DEFAULT
+          TOOLTIP_BG_SELECTED = TOOLTIP_GLASS_BG_SELECTED
+          TOOLTIP_FG_DEFAULT = "\e[38;2;205;214;244m"
+          TOOLTIP_FG_SELECTED = "\e[38;2;220;227;252m"
+
+          # Annotation editor overlay colors
+          ANNOTATION_PANEL_BG_LIGHT = "\e[48;2;230;230;234m"
+          ANNOTATION_PANEL_BG_DARK = "\e[48;2;88;88;88m"
+          ANNOTATION_HEADER_FG_LIGHT = Shoko::Shared::Terminal::Ansi::DEFAULT_FG
+          ANNOTATION_HEADER_FG_DARK = "\e[38;2;255;135;135m"
+          ANNOTATION_PANEL_BG = ANNOTATION_PANEL_BG_DARK
+          ANNOTATION_HEADER_FG = ANNOTATION_HEADER_FG_DARK
+
+          # Toast notification colors
+          TOAST_ACCENT = "\e[38;2;135;255;135m"
+          TOAST_FG = Shoko::Shared::Terminal::Ansi::DEFAULT_FG
+
+          # Icons
+          ICON_BOOK = '󰂺'
+          ICON_RECENT = '󰁯'
+          ICON_ANNOTATION = '󰠮'
+          ICON_SETTINGS = ''
+          ICON_QUIT = '󰿅'
+          ICON_OPEN = '󰷏'
+          ICON_TOC = '📖'
+          ICON_BOOKMARK = '🔖'
+          ICON_HELP = '❓'
+          ICON_SEARCH = ''
+          ICON_REFRESH = ''
+
+          SIDEBAR_BG = Shoko::Shared::Terminal::Ansi::BG_DARK
+          SIDEBAR_SELECTION_BG = Shoko::Shared::Terminal::Ansi::BG_BLUE
+          SIDEBAR_SELECTION_FG = Shoko::Shared::Terminal::Ansi::BRIGHT_WHITE
+
+          BUTTON_BG_ACTIVE = Shoko::Shared::Terminal::Ansi::BG_BRIGHT_GREEN
+          BUTTON_FG_ACTIVE = Shoko::Shared::Terminal::Ansi::BLACK
+          BUTTON_BG_INACTIVE = Shoko::Shared::Terminal::Ansi::BG_GREY
+          BUTTON_FG_INACTIVE = Shoko::Shared::Terminal::Ansi::WHITE
+
+          # Menu-specific slate/cyan editorial tokens.
+          MENU_SURFACE_BG_LIGHT = "\e[48;2;242;245;248m"
+          MENU_SURFACE_BG_DARK = "\e[48;2;26;32;40m"
+          MENU_SURFACE_BG = MENU_SURFACE_BG_DARK
+
+          MENU_TITLE_FG_LIGHT = "\e[38;2;11;79;107m"
+          MENU_TITLE_FG_DARK = Shoko::Shared::Terminal::Ansi::BRIGHT_CYAN
+          MENU_TITLE_FG = MENU_TITLE_FG_DARK
+
+          MENU_MUTED_FG_LIGHT = "\e[38;2;94;108;124m"
+          MENU_MUTED_FG_DARK = COLOR_TEXT_DIM
+          MENU_MUTED_FG = MENU_MUTED_FG_DARK
+
+          MENU_DIVIDER_FG_LIGHT = "\e[38;2;138;150;166m"
+          MENU_DIVIDER_FG_DARK = Shoko::Shared::Terminal::Ansi::GRAY
+          MENU_DIVIDER_FG = MENU_DIVIDER_FG_DARK
+
+          MENU_SELECTION_FG_LIGHT = "\e[38;2;8;101;143m"
+          MENU_SELECTION_FG_DARK = COLOR_TEXT_ACCENT
+          MENU_SELECTION_FG = MENU_SELECTION_FG_DARK
+
+          MENU_HEADER_BG_LIGHT = "\e[48;2;225;236;244m"
+          MENU_HEADER_BG_DARK = "\e[48;2;18;44;58m"
+          MENU_HEADER_BG = MENU_HEADER_BG_DARK
+
+          MENU_SELECTION_BG_LIGHT = "\e[48;2;208;232;246m"
+          MENU_SELECTION_BG_DARK = "\e[48;2;23;63;83m"
+          MENU_SELECTION_BG = MENU_SELECTION_BG_DARK
+
+          MENU_SELECTION_TEXT_LIGHT = "\e[38;2;6;67;95m"
+          MENU_SELECTION_TEXT_DARK = "\e[38;2;180;235;255m"
+          MENU_SELECTION_TEXT = MENU_SELECTION_TEXT_DARK
+
+          def self.apply_color_mode(mode)
+            light = mode.to_sym == :light
+            set_const(:HIGHLIGHT_BG_ACTIVE, light ? HIGHLIGHT_BG_LIGHT : HIGHLIGHT_BG_DARK)
+            set_const(:HIGHLIGHT_BG_SAVED, light ? HIGHLIGHT_BG_LIGHT : HIGHLIGHT_BG_DARK)
+            set_const(:ANNOTATION_PANEL_BG, light ? ANNOTATION_PANEL_BG_LIGHT : ANNOTATION_PANEL_BG_DARK)
+            set_const(:ANNOTATION_HEADER_FG, light ? ANNOTATION_HEADER_FG_LIGHT : ANNOTATION_HEADER_FG_DARK)
+            set_const(:MENU_SURFACE_BG, light ? MENU_SURFACE_BG_LIGHT : MENU_SURFACE_BG_DARK)
+            set_const(:MENU_TITLE_FG, light ? MENU_TITLE_FG_LIGHT : MENU_TITLE_FG_DARK)
+            set_const(:MENU_MUTED_FG, light ? MENU_MUTED_FG_LIGHT : MENU_MUTED_FG_DARK)
+            set_const(:MENU_DIVIDER_FG, light ? MENU_DIVIDER_FG_LIGHT : MENU_DIVIDER_FG_DARK)
+            set_const(:MENU_SELECTION_FG, light ? MENU_SELECTION_FG_LIGHT : MENU_SELECTION_FG_DARK)
+            set_const(:MENU_HEADER_BG, light ? MENU_HEADER_BG_LIGHT : MENU_HEADER_BG_DARK)
+            set_const(:MENU_SELECTION_BG, light ? MENU_SELECTION_BG_LIGHT : MENU_SELECTION_BG_DARK)
+            set_const(:MENU_SELECTION_TEXT, light ? MENU_SELECTION_TEXT_LIGHT : MENU_SELECTION_TEXT_DARK)
+          end
+
+          def self.set_const(name, value)
+            remove_const(name) if const_defined?(name)
+            const_set(name, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/dependency_sets.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Ui
+      # Typed dependencies used by reader-facing UI adapters.
+      ReaderUiDependencies = Data.define(
+        :observer_registry,
+        :terminal_service,
+        :ui_state_reader,
+        :reader_state_reader,
+        :sidebar_state_reader,
+        :config_reader,
+        :render_state_writer,
+        :rendered_content_reader,
+        :notification_service,
+        :logger,
+        :coordinate_service,
+        :view_model_builder_factory,
+        :layout_service,
+        :layout_metrics,
+        :page_calculator,
+        :wrapping_service,
+        :formatting_service,
+        :kitty_image_renderer,
+        :runtime_config,
+        :reader_launch_state,
+        :document,
+        :annotation_service
+      )
+
+      # Typed dependencies used by menu-facing UI adapters.
+      MenuUiDependencies = Data.define(
+        :menu_state_reader,
+        :menu_state_writer,
+        :reader_state_reader,
+        :sidebar_state_reader,
+        :config_reader,
+        :runtime_config,
+        :dictionary_availability,
+        :dictionary_storage,
+        :annotation_service,
+        :catalog_service,
+        :reader_launch_state,
+        :document
+      )
+    end
+  end
+end

data/lib/shoko/adapters/ui/menu_visual_profile.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Ui
+      # Immutable visual-profile data passed from composition to menu components.
+      MenuVisualProfile = Data.define(:color_mode, :ascii_icons)
+    end
+  end
+end

data/lib/shoko/adapters/ui/render_registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Shoko
+  module Adapters
+    module Ui
+      # Lightweight registry for per-frame render metadata (rendered line geometry).
+      # This keeps large, frequently-updated hashes out of the global state store.
+      class RenderRegistry
+        class << self
+          # Replace the global instance (used by tests).
+          def install(instance)
+            @current = instance
+          end
+        end
+
+        def initialize
+          @monitor = Monitor.new
+          @rendered_lines = {}
+        end
+
+        def write(lines)
+          return unless lines
+
+          @monitor.synchronize do
+            # Store the hash directly; callers control lifecycle per-frame.
+            @rendered_lines = lines
+          end
+        end
+
+        def clear
+          @monitor.synchronize { @rendered_lines = {} }
+        end
+
+        def lines
+          @monitor.synchronize { @rendered_lines }
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/rendering/frame_coordinator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../components/surface'
+require_relative '../components/screens/loading_overlay_component'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Rendering
+        # Coordinates frame lifecycle and provides a consistent surface + bounds
+        # for rendering. Centralizes start_frame/end_frame and terminal size updates.
+        class FrameCoordinator
+          def initialize(terminal_service:, state_writer:, ui_state_reader:)
+            @terminal_service = terminal_service
+            @state_writer = state_writer
+            @ui_state_reader = ui_state_reader
+          end
+
+          # Yields a prepared [surface, bounds, width, height] within a started frame.
+          # Ensures end_frame is called, even on errors.
+          def with_frame
+            height, width = @terminal_service.size
+            @terminal_service.start_frame(width: width, height: height)
+            @state_writer.update_terminal_size(width, height)
+            surface = build_surface
+            bounds = Shoko::Adapters::Ui::Components::Rect.new(x: 1, y: 1, width: width, height: height)
+            yield(surface, bounds, width, height)
+          ensure
+            @terminal_service.end_frame
+          end
+
+          # Renders the loading overlay component in a standalone frame.
+          def render_loading_overlay
+            height, width = @terminal_service.size
+            @terminal_service.start_frame(width: width, height: height)
+            surface = build_surface
+            bounds = Shoko::Adapters::Ui::Components::Rect.new(x: 1, y: 1, width: width, height: height)
+            overlay = Shoko::Adapters::Ui::Components::Screens::LoadingOverlayComponent.new(
+              ui_state_reader: @ui_state_reader
+            )
+            overlay.render(surface, bounds)
+          ensure
+            @terminal_service.end_frame
+          end
+
+          private
+
+          def build_surface
+            Shoko::Adapters::Ui::Components::Surface.new(@terminal_service.output)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/ui/rendering/line/config_helpers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../../../../core/ports/outbound/config_reader'
+
+module Shoko
+  module Adapters
+    module Ui
+      module Components
+        module Reading
+          # Shared helpers for resolving configuration values from the state store.
+          # Accepts either a config_reader port or a rendering context with config_reader.
+          module ConfigHelpers
+            module_function
+
+            def config_reader_from(config)
+              return nil unless config
+              return config if config.is_a?(Shoko::Core::Ports::Outbound::ConfigReader)
+              if config.is_a?(Struct)
+                return config_reader_from(config[:config_reader]) if config.members.include?(:config_reader)
+                return config if config.members.include?(:line_spacing)
+              end
+              if config.is_a?(Data)
+                values = config.to_h
+                return config_reader_from(values[:config_reader]) if values.key?(:config_reader)
+              end
+              if config.is_a?(Hash)
+                reader = config[:config_reader] || config['config_reader']
+                return config_reader_from(reader) if reader
+              end
+
+              raise ArgumentError, 'config must implement Core::Ports::Outbound::ConfigReader'
+            end
+
+            def line_spacing(config)
+              reader = config_reader_from(config)
+              return Shoko::Core::Models::ReaderSettings::DEFAULT_LINE_SPACING unless reader
+
+              reader.line_spacing || Shoko::Core::Models::ReaderSettings::DEFAULT_LINE_SPACING
+            end
+
+            def highlight_quotes?(config_reader)
+              return true unless config_reader
+
+              value = config_reader.highlight_quotes
+              value.nil? || value
+            end
+
+            def highlight_keywords?(config_reader)
+              return false unless config_reader
+
+              !!config_reader.highlight_keywords
+            end
+          end
+        end
+      end
+    end
+  end
+end