charming 0.2.0 → 0.2.2

data/lib/charming/presentation/view.rb

@@ -57,14 +57,16 @@ module Charming
       apply_style(content, style)
     end
 
-    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
-    def row(*items, gap: 0)
-      UI.join_horizontal(*items, gap: gap)
+    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports `gap:`
+    # spacing and cross-axis `align:` (`:top`/`:center`/`:bottom` or a 0.0–1.0 fraction).
+    def row(*items, gap: 0, align: :top)
+      UI.join_horizontal(*items, gap: gap, align: align)
     end
 
-    # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
-    def column(*items, gap: 0)
-      UI.join_vertical(*items, gap: gap)
+    # Stacks items vertically using the UI rendering engine. Supports `gap:` spacing and
+    # cross-axis `align:` (`:left`/`:center`/`:right` or a 0.0–1.0 fraction).
+    def column(*items, gap: 0, align: :left)
+      UI.join_vertical(*items, gap: gap, align: align)
     end
 
     # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.

data/lib/charming/response.rb

@@ -4,20 +4,25 @@ module Charming
   # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another route, or quit.
   # Rails-style factories (`render`, `navigate`, `quit`) serve as the public API and map to :kind values
   # that the Runtime interprets at the end of each event loop iteration.
-  Response = Data.define(:kind, :body, :path) do
-    # Factory constructing a Render response for displaying *body* text on the current screen.
-    def self.render(body)
-      new(kind: :render, body: body, path: nil)
+  #
+  # *escapes* carries any out-of-band terminal sequences (image transmissions, clipboard writes,
+  # notifications, window-title changes) gathered during the dispatch. The Runtime flushes them straight
+  # to the backend, bypassing the line-based frame pipeline. It is empty for ordinary responses.
+  Response = Data.define(:kind, :body, :path, :escapes) do
+    # Factory constructing a Render response for displaying *body* text on the current screen. *escapes*
+    # is the list of out-of-band sequences gathered during the dispatch (defaults to none).
+    def self.render(body, escapes: [])
+      new(kind: :render, body: body, path: nil, escapes: escapes)
     end
 
     # Factory constructing a NavigateResponse routing to the named *path* (string).
     def self.navigate(path)
-      new(kind: :navigate, body: "", path: path)
+      new(kind: :navigate, body: "", path: path, escapes: [])
     end
 
     # Factory constructing a QuitResponse signalling termination of the top-level event loop.
     def self.quit
-      new(kind: :quit, body: "", path: nil)
+      new(kind: :quit, body: "", path: nil, escapes: [])
     end
 
     # Returns `true` when this response is navigating to another screen or route.

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

@@ -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,38 +18,187 @@ 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
     # (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_signal_handlers
+      install_exit_hook
       with_raw_input do
-        render(resolve_response(dispatch(@route.action)))
-        loop do
-          event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
-          next unless event
+        render(initial_response)
+        @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
+    end
+
+    private
 
-          response = dispatch_event(event)
-          next unless response
-          break if response.quit?
+    attr_reader :screen
+
+    # 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
 
-          response = resolve_response(response)
-          break if response.quit?
+    # 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
+      response = nil
+      escapes = Escape.collecting { response = resolve_response(dispatch(@route.action)) }
+      attach_escapes(response, escapes)
+    rescue => e
+      error_response(e)
+    end
 
-          render(response)
-        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. 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 = nil
+      escapes = Escape.collecting do
+        response = dispatch_event(event)
+        response = resolve_response(response) if response
       end
-    ensure
-      @task_executor&.shutdown(timeout: 0.0)
-      restore_terminal
+      return flush_pending if response.nil?
+      return :quit if response.quit?
+
+      hold_response(response, escapes)
+      flush ? flush_pending : nil
+    rescue => e
+      @pending_response = nil
+      render(error_response(e))
+      nil
     end
 
-    private
+    # 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
 
-    attr_reader :screen
+    # 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)
+      return unless event.is_a?(Events::KeyEvent)
+      return :quit if Charming.key_of(event) == :q
+
+      @error = nil
+      render(initial_response)
+      nil
+    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
+
+    # 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_handlers = {}
+      QUIT_SIGNALS.each { |signal| trap_signal(signal) { @interrupted = true } }
+      install_suspend_handlers if @backend.respond_to?(:suspend)
+    end
+
+    # 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
+      @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.
+    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.
@@ -72,6 +221,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 +237,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.
@@ -105,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
 
@@ -120,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
+    # 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)
 
-      now = clock_now
-      timer[:next_at] = now + timer.fetch(:binding).interval
-      Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
+      response.escapes&.each { |sequence| @backend.write_escape(sequence) }
     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
+    # Returns *response* with *escapes* appended, or unchanged when none were collected.
+    def attach_escapes(response, escapes)
+      return response if escapes.nil? || escapes.empty?
 
-    # 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) }
-    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
-
-      (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.
@@ -182,14 +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)
@@ -198,9 +365,15 @@ 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)
       @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

data/lib/charming/tasks/task.rb

@@ -1,12 +1,32 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Charming
   module Tasks
     # Task is the unit of work submitted to a task executor. It pairs a *name* (used by
-    # `on_task` handlers to route the result) with a *block* to invoke on the executor.
-    Task = Data.define(:name, :block) do
-      # Invokes the task's block in the executor's thread and returns its value (or raises).
-      def call = block.call
+    # `on_task` handlers to route the result) with a *block* to invoke on the executor,
+    # plus an optional *timeout* in seconds.
+    Task = Data.define(:name, :block, :timeout) do
+      def initialize(name:, block:, timeout: nil)
+        super
+      end
+
+      # Invokes the task's block, passing *progress* when the block accepts an argument.
+      # Enforces the timeout (raising Tasks::Cancelled) when one was configured.
+      def call(progress = nil)
+        return invoke(progress) unless timeout
+
+        Timeout.timeout(timeout, Cancelled, "task #{name} timed out after #{timeout}s") do
+          invoke(progress)
+        end
+      end
+
+      private
+
+      def invoke(progress)
+        block.arity.zero? ? block.call : block.call(progress)
+      end
     end
   end
 end

data/lib/charming/tasks/threaded_executor.rb

@@ -5,30 +5,53 @@ module Charming
     # ThreadedExecutor runs submitted tasks on background Ruby threads. Each submission
     # creates a new thread that invokes the block and pushes the resulting TaskEvent
     # onto the shared *queue*. Threads are tracked so `shutdown` can wait (or kill)
-    # in-flight work.
+    # in-flight work, and tracked by name so `cancel` can interrupt a specific task.
     class ThreadedExecutor
       # *queue* is the thread-safe Queue (typically `runtime.@task_queue`) into which
       # completed TaskEvents are pushed.
       def initialize(queue)
         @queue = queue
         @threads = []
+        @threads_by_name = {}
         @mutex = Mutex.new
+        @shutting_down = false
       end
 
       # Wraps *block* in a Task and spawns a new thread to invoke it. The thread's
       # return value (or rescued exception) is pushed onto the queue as a TaskEvent.
-      # Returns nil immediately.
-      def submit(name, &block)
-        task = Task.new(name: name.to_sym, block: block)
-        thread = Thread.new(task) { |t| @queue << run(t) }
-        @mutex.synchronize { @threads << thread }
+      # Blocks that accept an argument receive a Progress reporter. *timeout* (seconds)
+      # cancels the task when exceeded. Returns nil immediately. Raises if called after
+      # shutdown has begun.
+      def submit(name, timeout: nil, &block)
+        task = Task.new(name: name.to_sym, block: block, timeout: timeout)
+        @mutex.synchronize do
+          raise "cannot submit task after shutdown" if @shutting_down
+
+          thread = Thread.new(task) { |t| @queue << run(t) }
+          @threads << thread
+          @threads_by_name[task.name] = thread
+        end
+        nil
+      end
+
+      # Cancels the named in-flight task by raising Tasks::Cancelled in its thread.
+      # The task completes with a TaskEvent whose error is the Cancelled exception.
+      # No-op when the task isn't running.
+      def cancel(name)
+        thread = @mutex.synchronize { @threads_by_name[name.to_sym] }
+        return unless thread&.alive?
+
+        thread.raise(Cancelled, "task #{name} cancelled")
         nil
       end
 
       # Waits up to *timeout* seconds for in-flight threads to finish, then kills any
-      # remaining live threads. Used by Runtime during teardown.
-      def shutdown(timeout: 0.0)
-        threads = @mutex.synchronize { @threads.dup }
+      # remaining live threads. Refuses new submissions once called.
+      def shutdown(timeout: 2.0)
+        threads = @mutex.synchronize do
+          @shutting_down = true
+          @threads.dup
+        end
         threads.each { |thread| thread.join(timeout) }
         threads.each do |thread|
           next unless thread.alive?
@@ -40,9 +63,10 @@ module Charming
 
       private
 
-      # Invokes the task's block and wraps the result (or rescued exception) in a TaskEvent.
+      # Invokes the task's block (passing a Progress reporter) and wraps the result
+      # (or rescued 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