charming 0.2.1 → 0.2.2

data/lib/charming/runtime.rb

@@ -6,7 +6,7 @@ module Charming
   # reads keyboard, mouse, timer, and task events, dispatching them to
   # controllers, rendering responses, and tearing down cleanly on exit.
   class Runtime
-    DEFAULT_READ_TIMEOUT = 0.05
+    DEFAULT_READ_TIMEOUT = Internal::EventLoop::DEFAULT_READ_TIMEOUT
 
     def initialize(application, backend: nil, renderer: nil, clock: nil, task_executor: nil)
       @application = application
@@ -18,7 +18,8 @@ module Charming
       @application.task_executor = @task_executor
       @route = @application.routes.resolve("/")
       @screen = backend_screen
-      @timers = build_timers
+      @coalesce_input = @application.respond_to?(:coalesce_input?) && @application.coalesce_input?
+      @event_loop = build_event_loop
     end
 
     # Runs the event loop: enters alt-screen, dispatches incoming events
@@ -27,59 +28,87 @@ module Charming
     # actions render an ErrorScreen instead of crashing the terminal.
     def run
       setup_terminal
-      install_interrupt_handler
+      install_signal_handlers
+      install_exit_hook
       with_raw_input do
         render(initial_response)
-        loop do
-          break if @interrupted
-
-          event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
-          unless event
-            break if backend_exhausted?
-            next
-          end
-          break if process(event) == :quit
-        end
+        @event_loop.run { |event, more_ready| process(event, flush: !more_ready) }
+      ensure
+        restore_signal_handlers
+        @task_executor&.shutdown(timeout: 2.0)
+        @application.save_session if @application.respond_to?(:save_session)
+        restore_terminal
       end
-    ensure
-      restore_interrupt_handler
-      @task_executor&.shutdown(timeout: 2.0)
-      @application.save_session if @application.respond_to?(:save_session)
-      restore_terminal
     end
 
     private
 
     attr_reader :screen
 
-    # The first frame's response — the root route's action, with errors caught.
+    # Builds the event pump, wiring in the current controller's timer bindings and
+    # an interrupt check backed by the SIGINT flag set in install_interrupt_handler.
+    def build_event_loop
+      Internal::EventLoop.new(
+        backend: @backend,
+        clock: @clock,
+        task_queue: @task_queue,
+        timer_bindings: @route.controller_class.timer_bindings.values,
+        coalesce_input: @coalesce_input,
+        interrupted: -> { @interrupted }
+      )
+    end
+
+    # The first frame's response — the root route's action, with errors caught. Out-of-band escape
+    # sequences registered while rendering are collected and attached to the response.
     def initial_response
-      resolve_response(dispatch(@route.action))
+      response = nil
+      escapes = Escape.collecting { response = resolve_response(dispatch(@route.action)) }
+      attach_escapes(response, escapes)
     rescue => e
       error_response(e)
     end
 
     # Handles a single event. Returns :quit to stop the loop, nil otherwise.
     # While an error screen is showing, only key events are honored: q quits,
-    # any other key dismisses and re-renders the current route.
-    def process(event)
+    # any other key dismisses and re-renders the current route. When *flush* is
+    # false (more events are already due), the response is held so a burst of
+    # task/timer events paints once with the final state; held escapes are
+    # carried forward in order so none are lost.
+    def process(event, flush: true)
       return process_error_event(event) if @error
       return :quit if unbound_interrupt?(event)
 
-      response = dispatch_event(event)
-      return unless response
-      return :quit if response.quit?
-
-      response = resolve_response(response)
+      response = nil
+      escapes = Escape.collecting do
+        response = dispatch_event(event)
+        response = resolve_response(response) if response
+      end
+      return flush_pending if response.nil?
       return :quit if response.quit?
 
-      render(response)
-      nil
+      hold_response(response, escapes)
+      flush ? flush_pending : nil
     rescue => e
+      @pending_response = nil
       render(error_response(e))
       nil
     end
 
+    # Replaces the held response with *response*, prepending any escapes held
+    # from earlier events in the burst so they still flush in order.
+    def hold_response(response, escapes)
+      held = @pending_response&.escapes || []
+      @pending_response = response.with(escapes: held + response.escapes + escapes)
+    end
+
+    # Renders the held response, if any. Always returns nil (the loop's "keep going").
+    def flush_pending
+      response = @pending_response
+      @pending_response = nil
+      render(response) if response
+      nil
+    end
+
     # Error-mode event handling: q quits, any other key dismisses the error
     # and re-dispatches the current route's action. Timer/task events are ignored.
     def process_error_event(event)
@@ -91,13 +120,6 @@ module Charming
       nil
     end
 
-    # True when the backend reports it has no more events to deliver (test backends
-    # only — the TTY backend never exhausts). Prevents the loop from spinning forever
-    # in tests that forget a trailing quit event.
-    def backend_exhausted?
-      @backend.respond_to?(:exhausted?) && @backend.exhausted?
-    end
-
     # True for a Ctrl+C key press that the current controller has no binding for —
     # the runtime treats it as quit so apps always have an escape hatch. Controllers
     # can take over by binding "ctrl+c" themselves.
@@ -108,20 +130,66 @@ module Charming
       @route.controller_class.key_bindings[:"ctrl+c"].nil?
     end
 
-    # Traps SIGINT so Ctrl+C (when delivered as a signal rather than a key) exits the
-    # loop cleanly through the ensure block instead of crashing mid-frame.
-    def install_interrupt_handler
+    # Signals that should exit the loop cleanly through the ensure block (restoring
+    # the terminal) instead of killing the process mid-frame.
+    QUIT_SIGNALS = %w[INT TERM HUP].freeze
+
+    # Traps quit signals to set the interrupt flag the event loop checks, and —
+    # when the backend supports it — SIGTSTP/SIGCONT for shell suspend/resume.
+    def install_signal_handlers
       @interrupted = false
-      @previous_int_handler = Signal.trap("INT") { @interrupted = true }
-    rescue ArgumentError
-      @previous_int_handler = nil
+      @previous_handlers = {}
+      QUIT_SIGNALS.each { |signal| trap_signal(signal) { @interrupted = true } }
+      install_suspend_handlers if @backend.respond_to?(:suspend)
     end
 
-    # Restores the previous SIGINT handler installed before the runtime started.
-    def restore_interrupt_handler
-      Signal.trap("INT", @previous_int_handler || "DEFAULT")
+    # Ctrl+Z: return the terminal to its normal state, stop the process, and on
+    # SIGCONT re-enter the TUI and force a repaint via the backend's resize path.
+    def install_suspend_handlers
+      trap_signal("TSTP") { suspend }
+      trap_signal("CONT") { resume }
+    end
+
+    # Traps *signal*, remembering the previous handler for teardown. Platforms
+    # without the signal (or restricted environments) are silently skipped.
+    def trap_signal(signal, &block)
+      @previous_handlers[signal] = Signal.trap(signal, &block)
     rescue ArgumentError
-      nil
+      @previous_handlers.delete(signal)
+    end
+
+    # Restores every signal handler that was replaced when the runtime started.
+    def restore_signal_handlers
+      (@previous_handlers || {}).each do |signal, previous|
+        Signal.trap(signal, previous || "DEFAULT")
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Restores the terminal for the shell and stops the process (the untrappable
+    # SIGSTOP), so Ctrl+Z behaves like it does in any well-behaved TUI.
+    def suspend
+      @backend.suspend
+      Process.kill("STOP", Process.pid)
+    end
+
+    # Re-enters the TUI after a foreground `fg`: raw mode and alt screen come back,
+    # the renderer cache is dropped, and the backend's resize path triggers a repaint.
+    def resume
+      @backend.resume
+      @renderer.invalidate if @renderer.respond_to?(:invalidate)
+      @backend.notify_resize if @backend.respond_to?(:notify_resize)
+    end
+
+    # Registers a process-exit fallback so an unexpected death (an exception that
+    # skips run's ensure, or an exit from within a handler) still restores the
+    # terminal. restore_terminal is idempotent, so the normal path stays cheap.
+    def install_exit_hook
+      return if @exit_hook_installed
+
+      @exit_hook_installed = true
+      at_exit { restore_terminal }
     end
 
     # Records *error*, logs its backtrace, and builds a centered ErrorScreen response.
@@ -208,12 +276,13 @@ module Charming
     end
 
     # Follows navigation responses: resolves the new route from the router,
-    # resets timers for the new route, and dispatches that route's action.
+    # reschedules the event loop's timers for the new controller, and
+    # dispatches that route's action.
     def resolve_response(response)
       return response unless response.navigate?
 
       @route = @application.routes.resolve(response.path)
-      @timers = build_timers
+      @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
       dispatch(@route.action)
     end
 
@@ -223,51 +292,27 @@ module Charming
       Screen.new(width: width, height: height)
     end
 
-    # Renders the body portion of a response through the renderer.
+    # Renders a response: first flushes any out-of-band escape sequences (image transmissions,
+    # clipboard writes, notifications, title changes) straight to the backend — ahead of the frame so
+    # image data is registered before its placeholder cells reference it — then renders the body.
     def render(response)
+      flush_escapes(response)
       @renderer.render(response.body)
     end
 
-    # Builds the initial set of timer states from controller bindings and the current clock time.
-    def build_timers
-      now = clock_now
-      @route.controller_class.timer_bindings.values.map do |binding|
-        {binding: binding, next_at: now + binding.interval}
-      end
-    end
-
-    # Returns a TimerEvent for the first due timer and advances its next fire time.
-    # Returns nil if no timers are ready or registered.
-    def next_timer_event
-      timer = due_timer
-      return unless timer
-
-      now = clock_now
-      timer[:next_at] = now + timer.fetch(:binding).interval
-      Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
-    end
-
-    # Pops a task event from the thread-safe queue if one is available.
-    # Non-blocking — returns nil immediately when the queue is empty.
-    def next_task_event
-      @task_queue.pop(true)
-    rescue ThreadError
-      nil
-    end
+    # Writes a response's out-of-band escape sequences to the backend, ahead of the frame. No-op for
+    # backends that don't support them or responses that carry none.
+    def flush_escapes(response)
+      return unless @backend.respond_to?(:write_escape)
 
-    # Returns timer values due at or before `now`, sorted by next fire time.
-    def due_timer
-      now = clock_now
-      @timers.select { |timer| timer.fetch(:next_at) <= now }.min_by { |timer| timer.fetch(:next_at) }
+      response.escapes&.each { |sequence| @backend.write_escape(sequence) }
     end
 
-    # Computes how long to block waiting for input based on when the next timer is due,
-    # clamped between 0 and DEFAULT_READ_TIMEOUT (0.05s). Returns DEFAULT when no timers exist.
-    def read_timeout
-      next_at = @timers.map { |timer| timer.fetch(:next_at) }.min
-      return DEFAULT_READ_TIMEOUT unless next_at
+    # Returns *response* with *escapes* appended, or unchanged when none were collected.
+    def attach_escapes(response, escapes)
+      return response if escapes.nil? || escapes.empty?
 
-      (next_at - clock_now).clamp(0, DEFAULT_READ_TIMEOUT)
+      response.with(escapes: response.escapes + escapes)
     end
 
     # Constructs a task executor: supports explicit instances, callable factories, or the default Threaded executor.
@@ -285,16 +330,33 @@ module Charming
     end
 
     # Enters an alternative screen buffer, hides the cursor, and installs
-    # a terminal resize signal handler if supported by the backend.
+    # a terminal resize signal handler if supported by the backend. Also asks
+    # the terminal for its background color so adaptive colors resolve correctly.
     def setup_terminal
+      detect_background
       @backend.enter_alt_screen
       @backend.hide_cursor
-      @backend.enable_mouse_tracking if @backend.respond_to?(:enable_mouse_tracking)
+      @backend.enable_mouse_tracking(motion: mouse_motion) if @backend.respond_to?(:enable_mouse_tracking)
       @backend.enable_bracketed_paste if @backend.respond_to?(:enable_bracketed_paste)
       @backend.enable_focus_reporting if @backend.respond_to?(:enable_focus_reporting)
       @backend.install_resize_handler if @backend.respond_to?(:install_resize_handler)
     end
 
+    # The app's configured mouse motion mode (:drag unless the app opts into :all hover).
+    def mouse_motion
+      @application.respond_to?(:mouse_motion) ? @application.mouse_motion : :drag
+    end
+
+    # Feeds the terminal's OSC 11 background reply (when the backend can obtain
+    # one) into UI::Background so adaptive colors resolve against reality rather
+    # than the dark-background default.
+    def detect_background
+      return unless @backend.respond_to?(:query_background_color)
+
+      background = @backend.query_background_color
+      UI::Background.assume = background if background
+    end
+
     # Keeps input raw/no-echo across rendering and dispatch, not just during reads.
     def with_raw_input(&block)
       return yield unless @backend.respond_to?(:with_raw_input)
@@ -303,8 +365,12 @@ module Charming
     end
 
     # Restores terminal state: reinstalls any previous resize handler, shows
-    # the cursor, and leaves the alternative screen buffer.
+    # the cursor, and leaves the alternative screen buffer. Idempotent — runs
+    # once whether reached from run's ensure or the at_exit fallback.
     def restore_terminal
+      return if @restored
+
+      @restored = true
       @backend.restore_resize_handler if @backend.respond_to?(:restore_resize_handler)
       @backend.disable_focus_reporting if @backend.respond_to?(:disable_focus_reporting)
       @backend.disable_bracketed_paste if @backend.respond_to?(:disable_bracketed_paste)

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - pando
@@ -201,10 +201,13 @@ files:
 - lib/charming/controller/dispatching.rb
 - lib/charming/controller/focus.rb
 - lib/charming/controller/focus_management.rb
+- lib/charming/controller/key_dispatch.rb
 - lib/charming/controller/rendering.rb
 - lib/charming/controller/session_state.rb
 - lib/charming/controller/sidebar_navigation.rb
+- lib/charming/controller/terminal.rb
 - lib/charming/database/commands.rb
+- lib/charming/escape.rb
 - lib/charming/events/focus_event.rb
 - lib/charming/events/key_event.rb
 - lib/charming/events/mouse_event.rb
@@ -233,6 +236,7 @@ files:
 - lib/charming/generators/templates/app/application_record.template
 - lib/charming/generators/templates/app/application_state.template
 - lib/charming/generators/templates/app/database_config.template
+- lib/charming/generators/templates/app/dot_rspec.template
 - lib/charming/generators/templates/app/executable.template
 - lib/charming/generators/templates/app/gemspec.template
 - lib/charming/generators/templates/app/home_controller.template
@@ -261,11 +265,19 @@ files:
 - lib/charming/generators/templates/screen/view.rb.template
 - lib/charming/generators/templates/view/view.rb.template
 - lib/charming/generators/view_generator.rb
+- lib/charming/image.rb
+- lib/charming/image/protocol.rb
+- lib/charming/image/protocol/kitty.rb
+- lib/charming/image/source.rb
+- lib/charming/image/terminal.rb
+- lib/charming/image/transmit.rb
+- lib/charming/internal/event_loop.rb
 - lib/charming/internal/renderer/differential.rb
 - lib/charming/internal/renderer/full_repaint.rb
 - lib/charming/internal/terminal/adapter.rb
 - lib/charming/internal/terminal/key_normalizer.rb
 - lib/charming/internal/terminal/memory_backend.rb
+- lib/charming/internal/terminal/modified_key_parser.rb
 - lib/charming/internal/terminal/mouse_parser.rb
 - lib/charming/internal/terminal/tty_backend.rb
 - lib/charming/presentation/component.rb
@@ -274,32 +286,41 @@ files:
 - lib/charming/presentation/components/autocomplete.rb
 - lib/charming/presentation/components/badge.rb
 - lib/charming/presentation/components/breadcrumbs.rb
+- lib/charming/presentation/components/chart.rb
 - lib/charming/presentation/components/command_palette.rb
 - lib/charming/presentation/components/command_palette_modal.rb
 - lib/charming/presentation/components/empty_state.rb
 - lib/charming/presentation/components/error_screen.rb
+- lib/charming/presentation/components/filepicker.rb
 - lib/charming/presentation/components/form.rb
 - lib/charming/presentation/components/form/builder.rb
 - lib/charming/presentation/components/form/confirm.rb
 - lib/charming/presentation/components/form/field.rb
 - lib/charming/presentation/components/form/input.rb
+- lib/charming/presentation/components/form/multiselect.rb
 - lib/charming/presentation/components/form/note.rb
 - lib/charming/presentation/components/form/select.rb
 - lib/charming/presentation/components/form/textarea.rb
 - lib/charming/presentation/components/fuzzy_matcher.rb
 - lib/charming/presentation/components/help_overlay.rb
+- lib/charming/presentation/components/image.rb
 - lib/charming/presentation/components/keyboard_handler.rb
 - lib/charming/presentation/components/list.rb
 - lib/charming/presentation/components/markdown.rb
 - lib/charming/presentation/components/modal.rb
 - lib/charming/presentation/components/multi_select_list.rb
+- lib/charming/presentation/components/paginator.rb
 - lib/charming/presentation/components/progressbar.rb
+- lib/charming/presentation/components/sparkline.rb
 - lib/charming/presentation/components/spinner.rb
 - lib/charming/presentation/components/status_bar.rb
+- lib/charming/presentation/components/stopwatch.rb
 - lib/charming/presentation/components/tab_bar.rb
 - lib/charming/presentation/components/table.rb
 - lib/charming/presentation/components/text_area.rb
 - lib/charming/presentation/components/text_input.rb
+- lib/charming/presentation/components/time_display.rb
+- lib/charming/presentation/components/timer.rb
 - lib/charming/presentation/components/toast.rb
 - lib/charming/presentation/components/tree.rb
 - lib/charming/presentation/components/viewport.rb
@@ -322,19 +343,23 @@ files:
 - lib/charming/presentation/markdown/style_config.rb
 - lib/charming/presentation/markdown/syntax_highlighter.rb
 - lib/charming/presentation/markdown/table_renderer.rb
-- lib/charming/presentation/markdown/text_wrapper.rb
 - lib/charming/presentation/markdown/url_resolver.rb
 - lib/charming/presentation/template_view.rb
 - lib/charming/presentation/templates.rb
 - lib/charming/presentation/templates/erb_handler.rb
 - lib/charming/presentation/ui.rb
+- lib/charming/presentation/ui/adaptive_color.rb
 - lib/charming/presentation/ui/ansi_codes.rb
 - lib/charming/presentation/ui/ansi_slicer.rb
+- lib/charming/presentation/ui/background.rb
 - lib/charming/presentation/ui/border.rb
 - lib/charming/presentation/ui/border_painter.rb
+- lib/charming/presentation/ui/braille_canvas.rb
 - lib/charming/presentation/ui/canvas.rb
 - lib/charming/presentation/ui/color_support.rb
+- lib/charming/presentation/ui/gradient.rb
 - lib/charming/presentation/ui/style.rb
+- lib/charming/presentation/ui/text_wrapper.rb
 - lib/charming/presentation/ui/theme.rb
 - lib/charming/presentation/ui/themes/catppuccin-latte.json
 - lib/charming/presentation/ui/themes/catppuccin-mocha.json
@@ -342,6 +367,7 @@ files:
 - lib/charming/presentation/ui/themes/nord.json
 - lib/charming/presentation/ui/themes/phosphor.json
 - lib/charming/presentation/ui/themes/tokyonight.json
+- lib/charming/presentation/ui/truncate.rb
 - lib/charming/presentation/ui/width.rb
 - lib/charming/presentation/view.rb
 - lib/charming/response.rb
@@ -377,7 +403,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A Rails-inspired TUI framework for Ruby.
 test_files: []