charming 0.2.0 → 0.2.1

data/lib/charming/presentation/ui/color_support.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # ColorSupport detects the terminal's color capability and downconverts colors so
+    # themes written in truecolor degrade gracefully on less-capable terminals.
+    #
+    # Levels (best to worst): :truecolor, :color256, :color16, :none.
+    #
+    # Detection honors NO_COLOR, then COLORTERM (truecolor/24bit), then TERM.
+    # `UI::ColorSupport.level = :color256` overrides detection (useful in tests and
+    # for user preference).
+    module ColorSupport
+      LEVELS = %i[none color16 color256 truecolor].freeze
+
+      # The 6-level RGB ramp used by the xterm 256-color cube (indices 16-231).
+      CUBE_LEVELS = [0, 95, 135, 175, 215, 255].freeze
+
+      module_function
+
+      # The active color level: the explicit override or the detected level (memoized).
+      def level
+        @level ||= detect(ENV)
+      end
+
+      # Overrides the detected level (nil resets to auto-detection on next access).
+      def level=(value)
+        raise ArgumentError, "unknown color level: #{value.inspect}" if value && !LEVELS.include?(value)
+
+        @level = value
+      end
+
+      # Detects the color capability from an environment hash.
+      def detect(env)
+        return :none if env["NO_COLOR"] && !env["NO_COLOR"].empty?
+        return :truecolor if %w[truecolor 24bit].include?(env["COLORTERM"])
+
+        term = env["TERM"].to_s
+        return :none if term.empty? || term == "dumb"
+        return :truecolor if term.include?("direct")
+        return :color256 if term.include?("256color")
+
+        :color16
+      end
+
+      # True when the active level is at least *required* (e.g., `at_least?(:color256)`).
+      def at_least?(required)
+        LEVELS.index(level) >= LEVELS.index(required)
+      end
+
+      # Converts "#rrggbb" to the nearest xterm 256-color index (cube or grayscale ramp).
+      def hex_to_256(hex)
+        r, g, b = hex_components(hex)
+        cube = cube_index(r, g, b)
+        gray = gray_index(r, g, b)
+        (color_distance([r, g, b], index_to_rgb(cube)) <= color_distance([r, g, b], index_to_rgb(gray))) ? cube : gray
+      end
+
+      # Converts "#rrggbb" to the nearest of the 16 basic ANSI colors, returned as the
+      # SGR foreground code (30-37 or 90-97).
+      def hex_to_16(hex)
+        rgb = hex_components(hex)
+        best = basic_palette.min_by { |_code, basic_rgb| color_distance(rgb, basic_rgb) }
+        best.first
+      end
+
+      # Converts a 256-color index to the nearest basic ANSI SGR foreground code.
+      def index_to_16(index)
+        rgb = index_to_rgb(index)
+        best = basic_palette.min_by { |_code, basic_rgb| color_distance(rgb, basic_rgb) }
+        best.first
+      end
+
+      # -- conversion internals ----------------------------------------------------
+
+      def hex_components(hex)
+        digits = hex.to_s.delete_prefix("#")
+        [digits[0..1].to_i(16), digits[2..3].to_i(16), digits[4..5].to_i(16)]
+      end
+
+      # Index in the 6x6x6 cube (16-231) closest to the RGB triple.
+      def cube_index(r, g, b)
+        16 + (36 * nearest_cube_level(r)) + (6 * nearest_cube_level(g)) + nearest_cube_level(b)
+      end
+
+      # Index in the grayscale ramp (232-255) closest to the RGB triple's luminance.
+      def gray_index(r, g, b)
+        gray = ((r + g + b) / 3.0).round
+        step = ((gray - 8) / 10.0).round.clamp(0, 23)
+        232 + step
+      end
+
+      def nearest_cube_level(component)
+        CUBE_LEVELS.each_index.min_by { |index| (CUBE_LEVELS[index] - component).abs }
+      end
+
+      # The RGB triple a 256-color *index* renders as.
+      def index_to_rgb(index)
+        if index >= 232
+          gray = 8 + (index - 232) * 10
+          [gray, gray, gray]
+        elsif index >= 16
+          offset = index - 16
+          [CUBE_LEVELS[offset / 36], CUBE_LEVELS[(offset / 6) % 6], CUBE_LEVELS[offset % 6]]
+        else
+          basic_palette.find { |code, _| basic_index_for_code(code) == index }&.last || [0, 0, 0]
+        end
+      end
+
+      def color_distance(a, b)
+        (a[0] - b[0])**2 + (a[1] - b[1])**2 + (a[2] - b[2])**2
+      end
+
+      # The 16 basic ANSI colors as [SGR foreground code, RGB] pairs.
+      def basic_palette
+        @basic_palette ||= {
+          30 => [0, 0, 0], 31 => [205, 49, 49], 32 => [13, 188, 121], 33 => [229, 229, 16],
+          34 => [36, 114, 200], 35 => [188, 63, 188], 36 => [17, 168, 205], 37 => [229, 229, 229],
+          90 => [102, 102, 102], 91 => [241, 76, 76], 92 => [35, 209, 139], 93 => [245, 245, 67],
+          94 => [59, 142, 234], 95 => [214, 112, 214], 96 => [41, 184, 219], 97 => [255, 255, 255]
+        }
+      end
+
+      def basic_index_for_code(code)
+        (code < 90) ? code - 30 : code - 90 + 8
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui/theme.rb

@@ -109,6 +109,13 @@ module Charming
       end
       alias_method :[], :style
 
+      # Returns a new Theme with *overrides* (token name → style spec hash) merged over
+      # this theme's tokens. Override colors are literal (hex strings, named symbols, or
+      # 256 indexes) — the parent's palette names are already resolved.
+      def merge(overrides, background: @background)
+        self.class.new(@tokens.merge(symbolize_keys(overrides.to_h)), background: background)
+      end
+
       def method_missing(name, ...)
         return style(name) if @tokens.key?(name)
 

data/lib/charming/presentation/ui/themes/catppuccin-latte.json

@@ -0,0 +1,35 @@
+{
+  "name": "Catppuccin Latte",
+  "id": "catppuccin-latte",
+  "background": "background",
+  "palette": {
+    "text": "#4C4F69",
+    "subtext": "#6C6F85",
+    "overlay": "#9CA0B0",
+    "background": "#EFF1F5",
+    "surface": "#CCD0DA",
+    "mauve": "#8839EF",
+    "peach": "#FE640B",
+    "sky": "#04A5E5",
+    "lavender": "#7287FD",
+    "green": "#40A02B",
+    "yellow": "#DF8E1D",
+    "red": "#D20F39"
+  },
+  "styles": {
+    "text": {"foreground": "text", "background": "background"},
+    "muted": {"foreground": "subtext", "background": "background"},
+    "title": {"foreground": "mauve", "background": "background", "bold": true},
+    "selected": {"foreground": "text", "background": "surface", "bold": true},
+    "header": {"foreground": "text", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "overlay"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "overlay"}, "padding": [1, 1]},
+    "main": {"foreground": "text", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "overlay", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "overlay"}, "padding": [0, 1]},
+    "modal": {"foreground": "text", "background": "background", "border": {"style": "rounded", "foreground": "lavender"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "border": {"foreground": "overlay", "background": "background"},
+    "info": {"foreground": "sky", "background": "background"},
+    "warn": {"foreground": "peach", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/catppuccin-mocha.json

@@ -0,0 +1,35 @@
+{
+  "name": "Catppuccin Mocha",
+  "id": "catppuccin-mocha",
+  "background": "background",
+  "palette": {
+    "text": "#CDD6F4",
+    "subtext": "#A6ADC8",
+    "overlay": "#6C7086",
+    "background": "#1E1E2E",
+    "surface": "#313244",
+    "mauve": "#CBA6F7",
+    "peach": "#FAB387",
+    "sky": "#89DCEB",
+    "lavender": "#B4BEFE",
+    "green": "#A6E3A1",
+    "yellow": "#F9E2AF",
+    "red": "#F38BA8"
+  },
+  "styles": {
+    "text": {"foreground": "text", "background": "background"},
+    "muted": {"foreground": "subtext", "background": "background"},
+    "title": {"foreground": "mauve", "background": "background", "bold": true},
+    "selected": {"foreground": "text", "background": "surface", "bold": true},
+    "header": {"foreground": "text", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "overlay"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "overlay"}, "padding": [1, 1]},
+    "main": {"foreground": "text", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "overlay", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "overlay"}, "padding": [0, 1]},
+    "modal": {"foreground": "text", "background": "background", "border": {"style": "rounded", "foreground": "lavender"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "mauve", "background": "background", "bold": true},
+    "border": {"foreground": "overlay", "background": "background"},
+    "info": {"foreground": "sky", "background": "background"},
+    "warn": {"foreground": "peach", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/gruvbox-dark.json

@@ -0,0 +1,33 @@
+{
+  "name": "Gruvbox Dark",
+  "id": "gruvbox-dark",
+  "background": "background",
+  "palette": {
+    "fg": "#EBDBB2",
+    "gray": "#928374",
+    "background": "#282828",
+    "surface": "#3C3836",
+    "yellow": "#FABD2F",
+    "orange": "#FE8019",
+    "aqua": "#8EC07C",
+    "blue": "#83A598",
+    "green": "#B8BB26",
+    "red": "#FB4934"
+  },
+  "styles": {
+    "text": {"foreground": "fg", "background": "background"},
+    "muted": {"foreground": "gray", "background": "background"},
+    "title": {"foreground": "yellow", "background": "background", "bold": true},
+    "selected": {"foreground": "fg", "background": "surface", "bold": true},
+    "header": {"foreground": "fg", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "gray"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "orange", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "gray"}, "padding": [1, 1]},
+    "main": {"foreground": "fg", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "gray", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "gray"}, "padding": [0, 1]},
+    "modal": {"foreground": "fg", "background": "background", "border": {"style": "rounded", "foreground": "yellow"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "orange", "background": "background", "bold": true},
+    "border": {"foreground": "gray", "background": "background"},
+    "info": {"foreground": "blue", "background": "background"},
+    "warn": {"foreground": "orange", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/nord.json

@@ -0,0 +1,32 @@
+{
+  "name": "Nord",
+  "id": "nord",
+  "background": "background",
+  "palette": {
+    "snow": "#D8DEE9",
+    "comment": "#616E88",
+    "background": "#2E3440",
+    "surface": "#3B4252",
+    "frost_blue": "#88C0D0",
+    "frost_deep": "#81A1C1",
+    "aurora_yellow": "#EBCB8B",
+    "aurora_green": "#A3BE8C",
+    "aurora_red": "#BF616A"
+  },
+  "styles": {
+    "text": {"foreground": "snow", "background": "background"},
+    "muted": {"foreground": "comment", "background": "background"},
+    "title": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "selected": {"foreground": "snow", "background": "surface", "bold": true},
+    "header": {"foreground": "snow", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "comment"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "comment"}, "padding": [1, 1]},
+    "main": {"foreground": "snow", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "comment", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "comment"}, "padding": [0, 1]},
+    "modal": {"foreground": "snow", "background": "background", "border": {"style": "rounded", "foreground": "frost_blue"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "frost_blue", "background": "background", "bold": true},
+    "border": {"foreground": "comment", "background": "background"},
+    "info": {"foreground": "frost_deep", "background": "background"},
+    "warn": {"foreground": "aurora_yellow", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/themes/tokyonight.json

@@ -0,0 +1,34 @@
+{
+  "name": "Tokyo Night",
+  "id": "tokyonight",
+  "background": "background",
+  "palette": {
+    "fg": "#C0CAF5",
+    "comment": "#565F89",
+    "background": "#1A1B26",
+    "surface": "#292E42",
+    "blue": "#7AA2F7",
+    "cyan": "#7DCFFF",
+    "yellow": "#E0AF68",
+    "magenta": "#BB9AF7",
+    "green": "#9ECE6A",
+    "red": "#F7768E",
+    "orange": "#FF9E64"
+  },
+  "styles": {
+    "text": {"foreground": "fg", "background": "background"},
+    "muted": {"foreground": "comment", "background": "background"},
+    "title": {"foreground": "blue", "background": "background", "bold": true},
+    "selected": {"foreground": "fg", "background": "surface", "bold": true},
+    "header": {"foreground": "fg", "background": "background", "border": {"style": "normal", "sides": ["bottom"], "foreground": "comment"}, "padding": [0, 1]},
+    "header_accent": {"foreground": "magenta", "background": "background", "bold": true},
+    "sidebar": {"background": "background", "border": {"style": "normal", "sides": ["right"], "foreground": "comment"}, "padding": [1, 1]},
+    "main": {"foreground": "fg", "background": "background", "padding": [1, 2]},
+    "footer": {"foreground": "comment", "background": "background", "border": {"style": "normal", "sides": ["top"], "foreground": "comment"}, "padding": [0, 1]},
+    "modal": {"foreground": "fg", "background": "background", "border": {"style": "rounded", "foreground": "magenta"}, "padding": [1, 2]},
+    "palette_accent": {"foreground": "magenta", "background": "background", "bold": true},
+    "border": {"foreground": "comment", "background": "background"},
+    "info": {"foreground": "cyan", "background": "background"},
+    "warn": {"foreground": "yellow", "background": "background"}
+  }
+}

data/lib/charming/presentation/ui/width.rb

@@ -8,12 +8,37 @@ module Charming
     # ANSI escape sequences. It delegates to `Unicode::DisplayWidth` while automatically stripping
     # formatting codes so layout primitives can calculate exact character positions.
     module Width
-      ANSI_PATTERN = /\e\[[0-9;]*m/
+      # Matches OSC sequences (e.g. OSC 8 hyperlinks, terminated by BEL or ST),
+      # CSI sequences (SGR colors/attributes, cursor movement), and single-character
+      # Fe escapes. The OSC branch must come first and the Fe class must exclude
+      # "[" and "]", or "\e]" would match as a bare Fe escape and leave the OSC
+      # payload counted as visible text.
+      ANSI_PATTERN = /\e(?:\][^\a]*?(?:\a|\e\\)|\[[0-9;?]*[@-~]|[@-Z\\^_])/
+
+      # A grapheme cluster containing either codepoint renders as a single emoji
+      # (double-width) cell in a terminal: U+200D ZWJ joins a multi-glyph emoji
+      # sequence, and U+FE0F (VS16) requests emoji presentation. The
+      # unicode-display_width tables disagree with terminals here — e.g. "⚔️"
+      # measures 1 and "🧙‍♂️" measures 3 — so we pin such clusters to 2.
+      EMOJI_PRESENTATION = /[\u200D\uFE0F]/
+
+      # Onig's \X matches one extended grapheme cluster, keeping multi-codepoint
+      # emoji together so each is measured (and later sliced) as one unit.
+      GRAPHEME = /\X/
 
       module_function
 
       def measure(value)
-        Unicode::DisplayWidth.of(strip_ansi(value.to_s))
+        stripped = strip_ansi(value.to_s)
+        return Unicode::DisplayWidth.of(stripped) unless stripped.match?(EMOJI_PRESENTATION)
+
+        stripped.scan(GRAPHEME).sum { |cluster| cluster_width(cluster) }
+      end
+
+      def cluster_width(cluster)
+        return 2 if cluster.match?(EMOJI_PRESENTATION)
+
+        Unicode::DisplayWidth.of(cluster)
       end
 
       def strip_ansi(value)

data/lib/charming/router.rb

@@ -47,7 +47,7 @@ module Charming
       route = Route.new(
         path: path,
         controller_class: constantize(controller_constant_name(controller_name)),
-        action: action.to_sym,
+        action: (action || "show").to_sym,
         title: title || derive_title(path),
         params: {}
       )

data/lib/charming/runtime.rb

@@ -23,27 +23,28 @@ module Charming
 
     # Runs the event loop: enters alt-screen, dispatches incoming events
     # (key, mouse, timer, async task), renders controller responses, and
-    # restores terminal state on exit.
+    # restores terminal state on exit. Unhandled exceptions from controller
+    # actions render an ErrorScreen instead of crashing the terminal.
     def run
       setup_terminal
+      install_interrupt_handler
       with_raw_input do
-        render(resolve_response(dispatch(@route.action)))
+        render(initial_response)
         loop do
-          event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
-          next unless event
-
-          response = dispatch_event(event)
-          next unless response
-          break if response.quit?
-
-          response = resolve_response(response)
-          break if response.quit?
+          break if @interrupted
 
-          render(response)
+          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
       end
     ensure
-      @task_executor&.shutdown(timeout: 0.0)
+      restore_interrupt_handler
+      @task_executor&.shutdown(timeout: 2.0)
+      @application.save_session if @application.respond_to?(:save_session)
       restore_terminal
     end
 
@@ -51,6 +52,86 @@ module Charming
 
     attr_reader :screen
 
+    # The first frame's response — the root route's action, with errors caught.
+    def initial_response
+      resolve_response(dispatch(@route.action))
+    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)
+      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)
+      return :quit if response.quit?
+
+      render(response)
+      nil
+    rescue => e
+      render(error_response(e))
+      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)
+      return unless event.is_a?(Events::KeyEvent)
+      return :quit if Charming.key_of(event) == :q
+
+      @error = nil
+      render(initial_response)
+      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.
+    def unbound_interrupt?(event)
+      return false unless event.is_a?(Events::KeyEvent)
+      return false unless event.ctrl && event.key == :c
+
+      @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
+      @interrupted = false
+      @previous_int_handler = Signal.trap("INT") { @interrupted = true }
+    rescue ArgumentError
+      @previous_int_handler = nil
+    end
+
+    # Restores the previous SIGINT handler installed before the runtime started.
+    def restore_interrupt_handler
+      Signal.trap("INT", @previous_int_handler || "DEFAULT")
+    rescue ArgumentError
+      nil
+    end
+
+    # Records *error*, logs its backtrace, and builds a centered ErrorScreen response.
+    def error_response(error)
+      @error = error
+      @application.logger.error("#{error.class}: #{error.message}\n#{Array(error.backtrace).join("\n")}")
+      panel = Components::ErrorScreen.new(error: error, theme: @application.theme).render
+      Response.render(UI.center(panel, width: screen.width, height: screen.height))
+    end
+
     # Dispatches an action on the current route's controller with an optional event.
     # Entry point from the event loop into controllers.
     def dispatch(action, event: nil)
@@ -72,6 +153,11 @@ module Charming
       controller(event: event).dispatch_task
     end
 
+    # Dispatches a task progress report to the current route's controller.
+    def dispatch_task_progress(event)
+      controller(event: event).dispatch_task_progress
+    end
+
     # Dispatches a mouse action (click, drag, scroll) to the current route's controller.
     def dispatch_mouse(event)
       controller(event: event).dispatch_mouse
@@ -83,17 +169,34 @@ module Charming
       @route.controller_class.new(application: @application, event: event, params: @route.params, screen: screen, route: @route)
     end
 
-    # Type-based dispatcher: routes resize, task, timer, mouse, and key events
-    # to the appropriate handler. Falls back to key dispatch for unclassified events.
+    # Type-based dispatcher: routes resize, task, progress, timer, mouse, paste, and key
+    # events to the appropriate handler. Falls back to key dispatch for unclassified events.
     def dispatch_event(event)
       return dispatch_resize(event) if event.is_a?(Events::ResizeEvent)
       return dispatch_task(event) if event.is_a?(Events::TaskEvent)
+      return dispatch_task_progress(event) if event.is_a?(Events::TaskProgressEvent)
       return dispatch_timer(event) if event.is_a?(Events::TimerEvent)
       return dispatch_mouse(event) if event.is_a?(Events::MouseEvent)
+      return dispatch_paste(event) if event.is_a?(Events::PasteEvent)
+      return dispatch_focus_change(event) if event.is_a?(Events::FocusEvent)
 
       dispatch_key(event)
     end
 
+    # Dispatches a terminal focus change to the controller's optional `focus_changed`
+    # action. Ignored when the controller doesn't define one.
+    def dispatch_focus_change(event)
+      ctrl = controller(event: event)
+      return nil unless ctrl.respond_to?(:focus_changed)
+
+      ctrl.dispatch(:focus_changed)
+    end
+
+    # Dispatches pasted text to the current route's controller.
+    def dispatch_paste(event)
+      controller(event: event).dispatch_paste
+    end
+
     # Dispatches a resize event: updates screen dimensions and re-renders the current action.
     # The renderer's cached previous frame is invalidated and the backend is cleared so the
     # new-dimension frame paints onto a clean alt-screen instead of overlaying stale rows.
@@ -187,6 +290,8 @@ module Charming
       @backend.enter_alt_screen
       @backend.hide_cursor
       @backend.enable_mouse_tracking 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
 
@@ -201,6 +306,8 @@ module Charming
     # the cursor, and leaves the alternative screen buffer.
     def restore_terminal
       @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)
       @backend.disable_mouse_tracking if @backend.respond_to?(:disable_mouse_tracking)
       @backend.show_cursor
       @backend.leave_alt_screen

data/lib/charming/tasks/cancelled.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Charming
+  module Tasks
+    # Cancelled is raised inside a task thread when the controller calls
+    # `cancel_task(name)` or the task exceeds its `timeout:`. The task completes with
+    # a TaskEvent whose error is this exception, so `on_task` handlers can detect it
+    # via `event.error.is_a?(Charming::Tasks::Cancelled)`.
+    class Cancelled < StandardError; end
+  end
+end

data/lib/charming/tasks/inline_executor.rb

@@ -13,13 +13,19 @@ module Charming
       end
 
       # Wraps *block* in a Task, invokes it immediately, and pushes the resulting
-      # TaskEvent (value or error) onto the queue. Returns nil.
-      def submit(name, &block)
-        task = Task.new(name: name.to_sym, block: block)
+      # TaskEvent (value or error) onto the queue. Blocks that accept an argument
+      # receive a Progress reporter (its events are queued before the completion event).
+      # Returns nil.
+      def submit(name, timeout: nil, &block)
+        task = Task.new(name: name.to_sym, block: block, timeout: timeout)
         @queue << run(task)
         nil
       end
 
+      # No-op: inline tasks have always finished by the time cancel could be called.
+      def cancel(name)
+      end
+
       # No-op stub for the shutdown contract; nothing to join since tasks run on the caller.
       def shutdown(timeout: 0.0)
       end
@@ -28,7 +34,7 @@ module Charming
 
       # Invokes the task's block and wraps the result (or raised exception) in a TaskEvent.
       def run(task)
-        Events::TaskEvent.new(name: task.name, value: task.call)
+        Events::TaskEvent.new(name: task.name, value: task.call(Progress.new(@queue, task.name)))
       rescue StandardError, ScriptError => e
         Events::TaskEvent.new(name: task.name, error: e)
       end

data/lib/charming/tasks/progress.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Charming
+  module Tasks
+    # Progress is the reporter handed to task blocks that accept an argument:
+    #
+    #   run_task(:import) do |progress|
+    #     rows.each_with_index do |row, i|
+    #       import(row)
+    #       progress.report(i + 1, of: rows.length, message: row.name)
+    #     end
+    #   end
+    #
+    # Each `report` pushes a TaskProgressEvent onto the runtime queue, which dispatches
+    # it to the controller's matching `on_task_progress` handler.
+    class Progress
+      def initialize(queue, name)
+        @queue = queue
+        @name = name
+      end
+
+      # Reports progress: *current* units done, optionally *of:* a total and with a
+      # human-readable *message:*.
+      def report(current, of: nil, message: nil)
+        @queue << Events::TaskProgressEvent.new(name: @name, current: current, total: of, message: message)
+        nil
+      end
+    end
+  end
+end