charming 0.2.3 → 0.4.0

data/lib/charming/controller/key_dispatch.rb

@@ -16,8 +16,8 @@ module Charming
     #
     # Tiers differ in how they terminate: the palette, overlay, sidebar, and binding
     # tiers consume the key outright once their condition holds, while the component
-    # tiers only consume it when the component reports :handled and otherwise let it
-    # fall through to the next tier.
+    # tiers only consume it when the component reports a handled result and otherwise
+    # let it fall through to the next tier.
     class KeyDispatch
       def initialize(controller)
         @controller = controller
@@ -42,7 +42,7 @@ module Charming
       attr_reader :controller
 
       def palette_open?
-        controller.command_palette_open?
+        controller.respond_to?(:command_palette_open?) && controller.command_palette_open?
       end
 
       def palette_response
@@ -75,12 +75,12 @@ module Charming
 
       # An overlay consumes the key whether or not the component handled it.
       def overlay_response
-        controller.send(:dispatch_to_focused_component)
+        controller.component_dispatch.dispatch_to_focused_component
         response
       end
 
       def sidebar_focused?
-        controller.sidebar_focused?
+        controller.respond_to?(:sidebar_focused?) && controller.sidebar_focused?
       end
 
       def sidebar_response
@@ -98,11 +98,11 @@ module Charming
       end
 
       def component_claimed?
-        controller.send(:dispatch_to_focused_component) == :handled
+        controller.component_dispatch.dispatch_to_focused_component == :handled
       end
 
       def ring_claimed?
-        controller.send(:dispatch_tab_traversal) == :handled
+        controller.component_dispatch.dispatch_tab_traversal == :handled
       end
 
       def response

data/lib/charming/controller/rendering.rb

@@ -15,13 +15,29 @@ module Charming
       end
 
       # Wraps *body* (a string) in the controller's configured layout, if any. When no layout is set
-      # the body is returned as-is.
+      # the body is returned as-is. Render artifacts from every view rendered (body first, layout
+      # last) accumulate on the controller for the dispatch to commit.
       def render_with_layout(body)
         rendered = render_body(body)
+        collect_render_artifacts(body)
         layout = self.class.layout
         return rendered unless layout
 
-        render_body(layout_body(layout, body, rendered))
+        layout_view = layout_body(layout, body, rendered)
+        render_body(layout_view).tap { collect_render_artifacts(layout_view) }
+      end
+
+      # Accumulates the render artifacts *body* stashed during its render, if any. Strings
+      # and template-less bodies carry none.
+      def collect_render_artifacts(body)
+        return unless body.respond_to?(:render_artifacts)
+
+        dispatch_render_artifacts.concat(body.render_artifacts)
+      end
+
+      # The render artifacts accumulated during this dispatch, in render order.
+      def dispatch_render_artifacts
+        @dispatch_render_artifacts ||= []
       end
 
       # Builds the layout wrapper for *body* / *rendered* content. String/Symbol layouts are
@@ -96,9 +112,9 @@ module Charming
       def conventional_view_constant_path(name)
         parts = name.to_s.split("/")
         action = parts.pop
-        view_name = "#{ActiveSupport::Inflector.camelize(action.to_s)}View"
+        view_name = "#{Internal::Inflections.camelize(action.to_s)}View"
 
-        parts.map { |part| ActiveSupport::Inflector.camelize(part) } + [view_name]
+        parts.map { |part| Internal::Inflections.camelize(part) } + [view_name]
       end
 
       # Returns the default template path for a given *action* (e.g., "home/show" for HomeController#show).
@@ -108,8 +124,8 @@ module Charming
 
       # Returns the underscored controller path (e.g., "home" for HomeController) used for view lookup.
       def controller_template_path
-        controller_name = ActiveSupport::Inflector.demodulize(self.class.name).delete_suffix("Controller")
-        ActiveSupport::Inflector.underscore(controller_name)
+        controller_name = Internal::Inflections.demodulize(self.class.name).delete_suffix("Controller")
+        Internal::Inflections.underscore(controller_name)
       end
     end
   end

data/lib/charming/controller/session_state.rb

@@ -4,22 +4,32 @@ module Charming
   class Controller
     # Session-state helpers mixed into Controller: accessing the application session hash, lazy
     # state-object lookup by name/class, form builder invocation, and async task submission.
+    #
+    # State-lifetime rule of thumb: controller ivars for screen-lifetime, `state` objects for
+    # app-lifetime, session-persisted values (`persist_session`) for restart-lifetime.
     module SessionState
-      # Returns the application session hash for this controller. All persistent state (focus,
-      # sidebar index, command palette, user state objects) lives here.
+      # Returns the application session hash for this controller. The session holds state that
+      # must outlive a screen: `state` objects, app-global UI state (focus rings, sidebar index,
+      # command palette), and values persisted across restarts via `persist_session`.
+      # In development and test the hash is wrapped in an Internal::SessionGuard so access
+      # from a task executor thread raises CrossThreadAccess; production returns the raw hash.
       def session
-        application.session
+        return application.session if Charming.env.production?
+
+        @session_guard ||= Internal::SessionGuard.new(application.session, self)
       end
 
       # Stores the named layout panes from the latest render so mouse events can be hit-tested
-      # against the same focus slots used by Tab traversal.
+      # against the same focus slots used by Tab traversal. Kept on the controller instance:
+      # mouse targets describe the latest render, not persistent state. Internal — called only
+      # from the dispatch pipeline's artifact commit; app code should not call this.
       def register_mouse_targets(targets)
-        session[:mouse_targets] = targets
+        @mouse_targets = targets
       end
 
       # Returns the named layout panes from the latest render.
       def mouse_targets
-        session.fetch(:mouse_targets, [])
+        @mouse_targets || []
       end
 
       # Returns the named session-backed state object, creating it on first access. *name* is a
@@ -30,36 +40,54 @@ module Charming
         session[:states][name.to_sym] ||= state_class.new(**attributes)
       end
 
-      # Returns the named mutable widget-state hash stored under `session[:component_state]`,
-      # seeding it from *defaults* on first access. This is the blessed way to keep an interactive
-      # component's state across ephemeral controller instances: store only JSON-safe primitives,
-      # rebuild the component from the hash each event, and write changed values back after
-      # `handle_key`. (Live component objects don't belong in the session — `save_session` drops
-      # anything that can't survive a JSON round-trip.)
+      # Deprecated. Returns the named mutable widget-state hash stored under
+      # `session[:component_state]`, seeding it from *defaults* on first access.
+      # Persistent controllers make this unnecessary: memoize the component in an ivar
+      # (`@query ||= Components::TextInput.new(...)`) for screen-lifetime state instead.
       def component_state(name, **defaults)
+        Charming.deprecate(
+          "component_state is deprecated. Persistent controllers keep components for the screen's " \
+            "lifetime — memoize them in ivars (`@query ||= Components::TextInput.new(...)`).",
+          category: :component_state
+        )
         session[:component_state] ||= {}
         session[:component_state][name.to_sym] ||= defaults
       end
 
-      # Builds a Form component scoped to the named form slot in `session[:forms]`. The block is
-      # evaluated against a Form::Builder (or invoked with the builder as its argument for arity-1 blocks)
-      # and returns a Form component pre-bound to the per-form mutable state hash.
+      # Builds a Form component scoped to the named form slot. The form's mutable state hash
+      # lives on the controller instance: it survives events on this screen and is discarded
+      # on navigation. Clear it after a successful submit with `reset_form`.
       def form(name, &block)
-        session[:forms] ||= {}
-        form_state = session[:forms][name.to_sym] ||= {}
         builder = Components::Form::Builder.new(theme: theme)
         block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
-        builder.build(state: form_state, theme: theme)
+        builder.build(state: form_states[name.to_sym] ||= {}, theme: theme)
+      end
+
+      # Clears the named form's stored state (e.g. after a successful submit, or when the
+      # form should re-seed from fresh defaults).
+      def reset_form(name)
+        form_states.delete(name.to_sym)
+      end
+
+      # The per-controller store of form state hashes, keyed by form name.
+      def form_states
+        @form_states ||= {}
       end
 
       # Submits a background task with the given *name*. The block is executed by the configured
       # task executor; its return value (or any raised exception) is delivered to the controller
       # as a TaskEvent dispatched to the matching `on_task` handler.
       #
-      # Blocks that accept an argument receive a Tasks::Progress reporter whose `report`
-      # calls dispatch the matching `on_task_progress` handler. *timeout:* (seconds)
-      # cancels the task with Tasks::Cancelled when exceeded.
-      def run_task(name, timeout: nil, &block)
+      # Blocks that accept an argument receive a Tasks::Context: `ctx[key]` reads inputs from
+      # the *with:* hash (deep-frozen at submit time) and `ctx.report(...)` dispatches the
+      # matching `on_task_progress` handler. *timeout:* (seconds) cancels the task with
+      # Tasks::Cancelled when exceeded.
+      #
+      # Task blocks receive data in via *with:* and return data out as the block value; they
+      # touch nothing else. The `on_task` handler on the loop thread is the only place task
+      # results become state.
+      def run_task(name, timeout: nil, with: {}, &block)
+        block = task_block_wrapper(block, Internal::DeepFreeze.call(with))
         return application.task_executor.submit(name, timeout: timeout, &block) if timeout
 
         # Without a timeout, use the plain signature so simple custom executors
@@ -73,6 +101,19 @@ module Charming
         executor = application.task_executor
         executor.cancel(name) if executor.respond_to?(:cancel)
       end
+
+      private
+
+      # Wraps the task block so it receives a Tasks::Context carrying the *with* data
+      # plus the executor's progress reporter. The wrapper's arity is always 1, so the
+      # executor hands it the reporter; the original block's arity decides whether the
+      # context is passed on (lambdas stay strict).
+      def task_block_wrapper(block, data)
+        proc do |progress|
+          context = Tasks::Context.new(data, progress)
+          block.arity.zero? ? block.call : block.call(context)
+        end
+      end
     end
   end
 end

data/lib/charming/controller/timers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Timer control helpers mixed into Controller. Controllers are ephemeral, so
+    # starting and stopping named timers is delegated to the runtime-owned
+    # TimerControl exposed on the application (a null object outside a runtime).
+    module Timers
+      # Schedules the named declared timer. Idempotent while the timer is running.
+      def start_timer(name)
+        application.timer_control.start(name)
+      end
+
+      # Unschedules the named timer. Idempotent when it is not running.
+      def stop_timer(name)
+        application.timer_control.stop(name)
+      end
+
+      # True while the named timer is scheduled.
+      def timer_running?(name)
+        application.timer_control.running?(name)
+      end
+    end
+  end
+end

data/lib/charming/controller.rb

@@ -2,10 +2,20 @@
 
 module Charming
   # Controller is the base class for all controller implementations in a Charming application.
-  # It provides the action dispatch pipeline, key/command/timer/task bindings, sidebar navigation,
-  # command palette management, and view rendering with layout composition.
+  # It provides the action dispatch pipeline, key/timer/task bindings, component-event
+  # declarations, and view rendering with layout composition. The sidebar and command
+  # palette are opt-in: see Charming::Shell::Sidebar and Charming::Shell::Palette.
+  #
+  # Controllers are persistent per screen: the Runtime constructs one instance when a route is
+  # entered and dispatches every event for that screen at it, so instance variables live for the
+  # screen's lifetime. Use ivars for screen-lifetime state, `state(name, Klass)` objects for
+  # app-lifetime state, and session persistence for restart-lifetime state.
   class Controller
-    TimerBinding = Data.define(:name, :interval, :action)
+    TimerBinding = Data.define(:name, :interval, :action, :autostart) do
+      def initialize(name:, interval:, action:, autostart: true)
+        super
+      end
+    end
     TaskBinding = Data.define(:name, :action)
 
     extend ClassMethods
@@ -13,106 +23,136 @@ module Charming
     include Rendering
     include SessionState
     include FocusManagement
-    include SidebarNavigation
-    include CommandPalette
-    include ComponentDispatching
     include Dispatching
     include Terminal
+    include Timers
 
     attr_reader :application, :event, :params, :screen, :route
 
-    # Initializes the controller with its parent application and optional event.
-    # Defaults to an 80x24 screen when no backend size is available.
-    def initialize(application:, event: nil, params: {}, screen: nil, route: nil)
+    # Initializes the controller with its parent application. The Runtime constructs one
+    # instance per route entry; *event:* is deprecated — pass events to the dispatch
+    # methods instead. Defaults to an 80x24 screen when no backend size is available.
+    def initialize(application:, params: {}, screen: nil, route: nil, event: nil)
+      if event
+        Charming.deprecate(
+          "Controller.new(event:) is deprecated. Construct the controller once and pass events " \
+            "to the dispatch methods (e.g. dispatch_key(event)).",
+          category: :controller_new_event
+        )
+      end
       @application = application
       @event = event
       @params = params
       @screen = screen || Screen.new(width: 80, height: 24)
       @route = route
       @response = nil
+      @loop_thread = Thread.current
+    end
+
+    # Records the loop thread that owns this controller. Construction captures the
+    # constructing thread; the Runtime re-captures when the event loop starts, covering
+    # runtimes built on one thread and run on another. Internal — called by Runtime.
+    def capture_loop_thread!
+      @loop_thread = Thread.current
+    end
+
+    # Asserts the current thread is this controller's loop thread. The mutation funnels
+    # (session, render/navigate/quit, focus, component_for) call this so task-block
+    # access from an executor thread trips immediately. Raises CrossThreadAccess in
+    # development and test; logs a warning in production. Internal — called by the
+    # funnels and the session guard.
+    def assert_loop_thread!(operation)
+      return if Thread.current.equal?(@loop_thread)
+
+      message = "A task thread called #{self.class.name || "an anonymous controller"}##{operation}. " \
+        "Task blocks receive data in via `with:` and return data out as the block value. " \
+        "Touch the controller, session, and components only on the loop thread — in the `on_task` handler."
+      raise CrossThreadAccess, message unless Charming.env.production?
+
+      logger.warn(message)
+    end
+
+    # Lifecycle hook called once after this controller becomes the active screen's
+    # controller, before the first action dispatch. Start per-screen resources here.
+    def screen_entered
+    end
+
+    # Lifecycle hook called before this controller is discarded — on navigation away or
+    # at quit. Stop per-screen resources here.
+    def screen_exited
+    end
+
+    # Replaces the screen dimensions after a terminal resize, keeping the live controller
+    # instance (and its ivars) across the resize.
+    def update_screen(screen)
+      @screen = screen
     end
 
     # Dispatches a named action on this controller (e.g. :show), running all
     # before/around/after hooks and rescue_from handlers.
-    def dispatch(action)
-      run_action_with_hooks(action)
-      render_default_action if response.nil? && auto_render_after?(action)
-      response || render("")
+    def dispatch(action, event: nil)
+      with_dispatch_state(event) do
+        run_action_with_hooks(action)
+        render_default_action if response.nil? && auto_render_after?(action)
+        response || render("")
+      end
     end
 
     # Key event dispatch. The precedence ladder (palette → focused text capture →
     # global bindings → overlay → sidebar/content/component) lives in KeyDispatch.
-    def dispatch_key
-      KeyDispatch.new(self).call
+    def dispatch_key(event = nil)
+      with_dispatch_state(event) { KeyDispatch.new(self).call }
     end
 
     # Timer event dispatcher: looks up the named action in timer bindings and runs it
     # with the full hook chain. Unlike #dispatch there is no render("") fallback — a
     # timer action that renders nothing yields a nil response, so silent ticks skip
     # the repaint instead of blanking the screen.
-    def dispatch_timer
-      b = self.class.timer_bindings[event.name.to_sym]
-      return nil unless b
-
-      run_action_with_hooks(b.action)
-      response
+    def dispatch_timer(event = nil)
+      with_dispatch_state(event) { timer_response }
     end
 
     # Task event dispatcher: looks up the handler in task bindings.
-    def dispatch_task
-      b = self.class.task_bindings[event.name.to_sym]
-      b ? dispatch(b.action) : nil
+    def dispatch_task(event = nil)
+      with_dispatch_state(event) { task_response(self.class.task_bindings) }
     end
 
     # Task progress dispatcher: looks up the handler in task progress bindings.
-    def dispatch_task_progress
-      b = self.class.task_progress_bindings[event.name.to_sym]
-      b ? dispatch(b.action) : nil
+    def dispatch_task_progress(event = nil)
+      with_dispatch_state(event) { task_response(self.class.task_progress_bindings) }
     end
 
     # Paste event dispatcher: forwards pasted text to the focused component's
     # `handle_paste` (TextInput, TextArea, Form text fields, and Autocomplete support it).
-    def dispatch_paste
-      slot = focus.current
-      return nil unless slot && respond_to?(slot, true)
-
-      component = send(slot)
-      return nil unless component.respond_to?(:handle_paste)
-
-      result = component.handle_paste(event)
-      return nil if result.nil?
-
-      dispatch_component_result(slot, result)
-      response
+    def dispatch_paste(event = nil)
+      with_dispatch_state(event) { paste_response }
     end
 
     # Mouse event dispatcher: command palette (if open) wins, then sidebar clicks
     # (route rows navigate directly), then named layout panes/components.
-    def dispatch_mouse
-      return dispatch_command_palette_mouse if command_palette_open?
-
-      sidebar_response = dispatch_sidebar_mouse
-      return sidebar_response if sidebar_response
-
-      dispatch_component_mouse
+    def dispatch_mouse(event = nil)
+      with_dispatch_state(event) { mouse_response }
     end
 
     # Renders a body or template wrapped in the controller's layout. Out-of-band escape sequences
     # registered while rendering (e.g. image transmissions) are collected by the Runtime around the
     # whole dispatch and attached to the response.
     def render(body = "", **assigns)
+      assert_loop_thread!(:render)
       body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
-      @response = Response.render(render_with_layout(body))
+      assign_response(Response.render(render_with_layout(body)), "render")
     end
 
     def render_view(view_class, **assigns)
-      @response = Response.render(render_with_layout(view_class.new(**template_assigns(assigns))))
+      assert_loop_thread!(:render_view)
+      assign_response(Response.render(render_with_layout(view_class.new(**template_assigns(assigns)))), "render_view(#{view_class})")
     end
 
     # Renders a template from `app/views` by name, applying the controller's layout. *name* is the
     # template path (e.g., "home/show") and additional keyword *assigns* are forwarded to the view.
     def render_template(name, **assigns)
-      @response = Response.render(render_with_layout(template_body(name, **assigns)))
+      assert_loop_thread!(:render_template)
+      assign_response(Response.render(render_with_layout(template_body(name, **assigns))), "render_template(#{name.inspect})")
     end
 
     # Returns the active theme for this request, delegated to the application.
@@ -131,25 +171,178 @@ module Charming
       application.logger
     end
 
-    # Opens the theme picker (a CommandPalette populated with the registered themes) and renders.
-    def open_theme_palette
-      session[:command_palette] = command_palette_state(:themes)
-      focus.push_scope([:command_palette], origin: :command_palette)
-      render_default_action
-    end
-
-    # Navigates to the given URL path.
-    def navigate_to(path)
-      @response = Response.navigate(path)
+    # Navigates to the screen registered under *name* in config/routes.rb, passing
+    # *params* through to the target controller (e.g. `navigate :project, id: project.id`).
+    def navigate(name, **params)
+      assert_loop_thread!(:navigate)
+      assign_response(Response.navigate(name, **params), "navigate to :#{name}")
     end
 
     # Exits the application — sets a quit response that terminates the event loop.
     def quit
-      @response = Response.quit
+      assert_loop_thread!(:quit)
+      assign_response(Response.quit, "quit")
+    end
+
+    # The component-dispatch collaborator: forwards key/mouse/paste events to focused
+    # components and translates their results into controller action calls.
+    def component_dispatch
+      @component_dispatch ||= ComponentDispatch.new(self)
+    end
+
+    # Returns the component registered for the focus *slot*, or nil. Declared slots
+    # (`slot :name { ... }`) resolve first, memoized per controller; undeclared slots
+    # fall back to the same-named method convention. Every dispatch path fetches
+    # components through here, so the slot convention is greppable in one place.
+    def component_for(slot)
+      assert_loop_thread!(:component_for)
+      return declared_slot(slot.to_sym) if self.class.slot_definitions.key?(slot.to_sym)
+
+      legacy_slot_component(slot)
     end
 
     private
 
     attr_reader :response
+
+    # Returns the memoized component for a declared slot, instance_exec'ing the factory
+    # on first access so it can read params and state. Factories that return nil are
+    # memoized as nil (the key? check distinguishes "not built" from "built as nil").
+    def declared_slot(name)
+      @slots ||= {}
+      return @slots[name] if @slots.key?(name)
+
+      @slots[name] = instance_exec(&self.class.slot_definitions[name])
+    end
+
+    # Resolves an undeclared slot via the legacy same-named-method convention, warning
+    # once per controller class and slot. Returns nil (without warning) when no such
+    # method exists — pane names like :sidebar are slots without components.
+    def legacy_slot_component(name)
+      return nil unless respond_to?(name, true)
+
+      Charming.deprecate(
+        "#{self.class.name || "An anonymous controller"} resolves slot :#{name} via a private method. " \
+          "Declare it instead: `slot :#{name} { ... }`. The convention is removed at 1.0.",
+        category: :"undeclared_slot_#{self.class.name}_#{name}"
+      )
+      send(name)
+    end
+
+    # The single funnel through which every response is assigned. Raises
+    # DoubleRenderError when a response was already set during this dispatch —
+    # a second assignment would silently discard the first. Render responses carry
+    # the dispatch's merged render artifacts (focus slots, mouse targets) for the
+    # commit at dispatch exit.
+    def assign_response(value, attempted)
+      raise DoubleRenderError, double_render_message(attempted) if response
+
+      @response = attach_render_artifacts(value)
+    end
+
+    # Attaches the merged render artifacts to a render response when any view rendered
+    # a layout this dispatch. Non-render responses and layout-less renders carry none.
+    def attach_render_artifacts(value)
+      return value unless value.kind == :render
+      return value if dispatch_render_artifacts.empty?
+
+      value.with(artifacts: RenderArtifacts.merge(dispatch_render_artifacts))
+    end
+
+    # Commits the response's render artifacts: validates focus slots against the slot
+    # registry, defines the layout focus scope, and registers mouse targets. Runs once
+    # per dispatch, at the outermost exit — a dispatch that raises mid-render commits
+    # nothing, so the previous frame's registrations stay live with what's on screen.
+    def commit_render_artifacts
+      artifacts = response&.artifacts
+      return unless artifacts
+
+      register_layout_focus(artifacts.focus_slots)
+      register_mouse_targets(artifacts.mouse_targets)
+    end
+
+    # Builds the DoubleRenderError message, naming the action, the response
+    # already set, the one attempted, and the fix.
+    def double_render_message(attempted)
+      "#{dispatch_context} set the response twice in one dispatch: " \
+        "first #{describe_response(response)}, then #{attempted}. " \
+        "Set the response once per dispatch: remove the first call or restructure the action."
+    end
+
+    # The controller and action for error messages (e.g. "HomeController#show").
+    def dispatch_context
+      name = self.class.name || "Anonymous controller"
+      @current_action ? "#{name}##{@current_action}" : name
+    end
+
+    # A one-word description of a response for error messages.
+    def describe_response(response)
+      (response.kind == :navigate) ? "navigate to :#{response.name}" : response.kind.to_s
+    end
+
+    # Sets per-dispatch state (the event) around the block, then clears @response and
+    # @event when the outermost dispatch exits, so per-dispatch state cannot leak
+    # between events. Nested dispatches (a key binding calling #dispatch) keep it.
+    # The outermost dispatch also clears @response on entry, so a response set outside
+    # any dispatch (e.g. in screen_entered) is discarded instead of tripping the
+    # DoubleRenderError guard on the next dispatch's first render. At the outermost
+    # exit, a rendered response's artifacts commit; an exception skips the commit.
+    def with_dispatch_state(event)
+      @event = event if event
+      @dispatch_depth = @dispatch_depth.to_i + 1
+      if @dispatch_depth == 1
+        @response = nil
+        dispatch_render_artifacts.clear
+        validate_slot_registrations_once
+      end
+      yield.tap { commit_render_artifacts if @dispatch_depth == 1 }
+    ensure
+      @dispatch_depth -= 1
+      if @dispatch_depth.zero?
+        @response = nil
+        @event = nil
+      end
+    end
+
+    # The timer binding's response, or nil when the ticked timer has no binding.
+    def timer_response
+      binding = self.class.timer_bindings[event.name.to_sym]
+      return nil unless binding
+
+      run_action_with_hooks(binding.action)
+      response
+    end
+
+    # The task binding's response, or nil when the event name has no binding.
+    def task_response(bindings)
+      binding = bindings[event.name.to_sym]
+      binding ? dispatch(binding.action) : nil
+    end
+
+    # Forwards the paste event to the focused component and dispatches its result.
+    def paste_response
+      slot = focus.current
+      component = slot && component_for(slot)
+      return nil unless component&.respond_to?(:handle_paste)
+
+      result = component.handle_paste(event)
+      return nil if result.nil?
+
+      component_dispatch.dispatch_component_result(slot, result)
+      response
+    end
+
+    # Routes the mouse event: palette first (when the app includes the shell palette),
+    # then sidebar (likewise), then named panes/components.
+    def mouse_response
+      return dispatch_command_palette_mouse if respond_to?(:command_palette_open?) && command_palette_open?
+
+      if respond_to?(:dispatch_sidebar_mouse, true)
+        sidebar_response = dispatch_sidebar_mouse
+        return sidebar_response if sidebar_response
+      end
+
+      component_dispatch.dispatch_component_mouse
+    end
   end
 end

data/lib/charming/cross_thread_access.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when controller machinery is called from a task executor thread. Task blocks
+  # receive data in via `run_task`'s `with:` and return data out as the block value; the
+  # controller, session, and components belong to the loop thread. Raised in development
+  # and test; production logs a warning instead.
+  class CrossThreadAccess < Error; end
+end