charming 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 651009e81e5bb2eb02b2df432b5e399773150691413f2519a6888160b60bd1ca
-  data.tar.gz: 8aa3bf4aebc1abab7890eec9b68791d4ed0fd354cffb982cc40f2cf4f261f70c
+  metadata.gz: 523be6b8c824b1f82ce8eb6151f276a90a81f111d9811f0339fec63ce64ad98b
+  data.tar.gz: 72009cdace9af96c2295ea34ceaa1dfbaa78a2654399ca7bc62773b4343ceed5
 SHA512:
-  metadata.gz: d4276dd6ef588077877b4d4d44758a9c176161fccddd22a5d74161f8615ee38f3c8078872a0ccbca6c8d73e83c994f7e0221f45f75348b9b81bef507a35ff491
-  data.tar.gz: 595008aad5caa6c524e872593b8554b588c8018592aca1ead16820200c31dec67cb1189e338658e902abafa9033612780441ed71bb57bcdb8f296b8f03bbfecc
+  metadata.gz: 67c08a96c480b1f3e4b1ae903d406e84e02d4a7086dd6584d23d32c3fbe63bf06be3e94181287ed100491eff1dd083753df8888e50b20cc8666adc58a45fbd56
+  data.tar.gz: '0699c84e711f47fa6b44ea2e3290e12927e2e1d6429c5f9855970050b214e62d5ae37ffb0922993f8007b6d87e1bd0d4f9237e8ca8a618272dc08274f2153689'

data/README.md

@@ -4,12 +4,14 @@
 
 A Rails-inspired terminal user interface framework for **Ruby 4+**.
 
-Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, background tasks, cross-platform audio playback, inline image display (Kitty graphics protocol), system clipboard / desktop notifications / window title, braille charts and sparklines, and testable terminal backends.
+Charming gives terminal apps familiar application structure: routes, controllers, state objects, templates, layouts, reusable components, themes, keyboard bindings, command palettes, timers, physics-based animation (springs and projectiles, ported from charmbracelet/harmonica), background tasks, cross-platform audio playback, inline image display (Kitty graphics protocol), system clipboard / desktop notifications / window title, braille charts and sparklines, and testable terminal backends.
 
 ## Project Status
 
 Charming is still in its infancy and is under constant development. APIs, behavior, and generated app structure may change until the project reaches a stable `1.0` release.
 
+[API_POLICY.md](API_POLICY.md) defines what the 1.0 freeze covers: `Charming::Internal` is unversioned, and everything else follows semver from 1.0.
+
 ## Quick Start
 
 Install the Charming CLI gem on your machine:

data/lib/charming/application.rb

@@ -24,7 +24,7 @@ module Charming
       # Derives the module namespace from the class name — e.g., Admin::HomeController
       # yields "Admin". Mirrors Rails' engine-style namespacing.
       def namespace
-        ActiveSupport::Inflector.deconstantize(name.to_s)
+        Internal::Inflections.deconstantize(name.to_s)
       end
 
       # Returns or sets the app logger. Defaults to a null-device logger so app and framework code
@@ -93,9 +93,10 @@ module Charming
       end
 
       # Opts into session persistence: the session hash is serialized as JSON to *to*
-      # when the app quits and reloaded on boot. Only JSON-safe values survive the
-      # round-trip (hash keys come back as symbols); non-serializable entries (state
-      # objects, procs) are skipped with a warning in the log.
+      # when the app quits and reloaded on boot. JSON-safe values survive (hash keys
+      # come back as symbols; symbol values come back as strings). State objects
+      # persist only their `persist`-marked attributes; anything else dropped warns
+      # once per key (category :session_drop).
       def persist_session(to:)
         @session_path = to
       end
@@ -163,6 +164,13 @@ module Charming
     end
 
     attr_accessor :logger, :task_executor
+    attr_writer :timer_control
+
+    # The runtime-injected timer control used by `Controller#start_timer` and
+    # friends. Defaults to a null object so controllers work outside a Runtime.
+    def timer_control
+      @timer_control ||= Internal::TimerControl::Null.new
+    end
     attr_reader :session
 
     # Initializes the session hash for per-request state storage, restoring a
@@ -172,9 +180,10 @@ module Charming
       @session = load_session
     end
 
-    # Serializes the session to the configured `persist_session` path. Entries that
-    # don't survive a JSON round-trip (state objects, procs, focus scopes) are skipped.
-    # No-op when persistence isn't configured. Called by the Runtime on exit.
+    # Serializes the session to the configured `persist_session` path. State objects
+    # persist their `persist`-marked attributes only; other attributes reinitialize to
+    # defaults on next boot. Dropped entries warn once per key. No-op when persistence
+    # isn't configured. Called by the Runtime on exit.
     def save_session
       path = self.class.session_path
       return unless path
@@ -214,27 +223,102 @@ module Charming
     private
 
     # Loads the persisted session JSON (symbolizing keys), or {} when absent/invalid.
+    # Serialized state objects are re-instantiated from their declared class and
+    # persisted attributes; unknown classes and stale attribute sets degrade to a
+    # logged warning plus fresh state — a stale session file never crashes boot.
     def load_session
       path = self.class.session_path
       return {} unless path && File.exist?(path)
 
-      JSON.parse(File.read(path), symbolize_names: true)
+      data = JSON.parse(File.read(path), symbolize_names: true)
+      data[:states] = restore_states(data[:states]) if data[:states].is_a?(Hash)
+      data
     rescue JSON::ParserError => e
       logger.warn("session not restored: #{e.message}")
       {}
     end
 
+    # Re-instantiates serialized state objects; entries that fail (renamed class,
+    # changed attributes) are skipped with a warning.
+    def restore_states(serialized)
+      serialized.filter_map { |name, payload| restore_state(name, payload) }.to_h
+    end
+
+    # Restores one state object from its serialized payload, or nil on any mismatch.
+    def restore_state(name, payload)
+      klass = Object.const_get(payload[:class].to_s)
+      [name, klass.new(**payload[:attributes].to_h)]
+    rescue => e
+      logger.warn("session state #{name.inspect} not restored (#{e.class}: #{e.message}); starting fresh")
+      nil
+    end
+
     # Framework-internal session keys that must not be persisted: their values carry
     # symbols in *values* (which JSON round-trips into strings, corrupting focus rings
-    # and palette state) and they describe transient UI state anyway.
-    INTERNAL_SESSION_KEYS = %i[focus_state mouse_targets command_palette].freeze
+    # and palette state) and they describe transient UI state anyway. Both are app-global
+    # across screens by design: focus rings and the palette outlive any one controller.
+    INTERNAL_SESSION_KEYS = %i[focus_state command_palette].freeze
 
     # The subset of session entries that survive a JSON round-trip: nil, booleans,
-    # numbers, strings, symbols, and arrays/hashes of those. State objects, procs,
-    # framework-internal keys, and other rich values are skipped (hash keys come back
-    # as symbols via symbolize_names; symbol *values* come back as strings).
+    # numbers, strings, symbols, and arrays/hashes of those — plus state objects with
+    # `persist`-marked attributes, serialized under :states as
+    # {name => {class:, attributes:}}. Procs and other rich values are dropped with a
+    # one-time :session_drop warning per key (hash keys come back as symbols via
+    # symbolize_names; symbol *values* come back as strings).
     def serializable_session
-      session.except(*INTERNAL_SESSION_KEYS).select { |_key, value| json_safe?(value) }
+      plain = session.except(:states, *INTERNAL_SESSION_KEYS)
+      safe = plain.select { |_key, value| json_safe?(value) }
+      (plain.keys - safe.keys).each do |key|
+        warn_session_drop(key,
+          "session[:#{key}]: the value is not JSON-safe. Keep only strings, numbers, " \
+          "booleans, nil, symbols, and arrays/hashes of those in the session.")
+      end
+
+      states = serializable_states
+      states.empty? ? safe : safe.merge(states: states)
+    end
+
+    # Serializes session[:states] entries: classes with `persist` declarations keep
+    # their marked (JSON-safe) attributes; undeclared classes are dropped with a
+    # one-time :session_drop warning naming the `persist` declaration to add.
+    def serializable_states
+      states = session[:states]
+      return {} unless states
+
+      states.filter_map { |name, object| serialize_state(name, object) }.to_h
+    end
+
+    # Serializes one state object, or nil (with a warning) when its class declares no
+    # persisted attributes.
+    def serialize_state(name, object)
+      klass = object.class
+      unless klass.respond_to?(:persisted?) && klass.persisted?
+        warn_session_drop(name,
+          "#{klass.name || klass.inspect} (session[:states][:#{name}]) declares no persisted attributes. " \
+          "Declare what to keep: `persist :attr, ...` on #{klass.name || "the state class"}.")
+        return nil
+      end
+
+      [name, {class: klass.name, attributes: persisted_attributes_for(object)}]
+    end
+
+    # The JSON-safe subset of a state object's persisted attributes; non-safe values
+    # are dropped with a per-attribute warning.
+    def persisted_attributes_for(object)
+      object.class.persisted_attribute_names.filter_map do |attribute|
+        value = object.public_send(attribute)
+        next [attribute, value] if json_safe?(value)
+
+        warn_session_drop(attribute,
+          "#{object.class.name}##{attribute} is not JSON-safe. Keep only strings, numbers, " \
+          "booleans, nil, and arrays/hashes of those in persisted attributes.")
+        nil
+      end.to_h
+    end
+
+    # Warns once per key/class that a session entry was dropped, naming the fix.
+    def warn_session_drop(category_key, detail)
+      Charming.deprecate("save_session dropped #{detail}", category: :"session_drop_#{category_key}")
     end
 
     def json_safe?(value)

data/lib/charming/application_state.rb

@@ -6,8 +6,31 @@ module Charming
   # ApplicationState is the base for session-backed TUI state. It includes
   # `ActiveModel::Model` (validation, initialisation) and `ActiveModel::Attributes` (typed attributes
   # with defaults via `attribute :name, :type, default: ...`), making it suitable for screen/form state.
+  #
+  # Persistence across restarts is explicit: `persist :attr_name` marks the attributes that
+  # `save_session` serializes. Unmarked attributes reinitialize to their defaults on the
+  # next boot — by design, not by silent accident. State classes with no `persist`
+  # declarations are dropped from the session file with a deprecation warning this
+  # release; at 1.0 they are dropped without warning.
   class ApplicationState
     include ActiveModel::Model
     include ActiveModel::Attributes
+
+    # Marks attributes that persist across restarts via `persist_session`. Only
+    # JSON-safe values (strings, numbers, booleans, nil, arrays/hashes of those)
+    # survive the file; others are dropped with a warning.
+    def self.persist(*names)
+      persisted_attribute_names.concat(names.map(&:to_sym))
+    end
+
+    # The names marked with `persist`, inherited from the superclass.
+    def self.persisted_attribute_names
+      @persisted_attribute_names ||= superclass.respond_to?(:persisted_attribute_names) ? superclass.persisted_attribute_names.dup : []
+    end
+
+    # True when the class marks at least one attribute with `persist`.
+    def self.persisted?
+      persisted_attribute_names.any?
+    end
   end
 end

data/lib/charming/cli.rb

@@ -116,8 +116,8 @@ module Charming
 
     # Resolves `<AppModule>::Application` from the root file name, or nil.
     def console_application_class(root_file)
-      module_name = ActiveSupport::Inflector.camelize(File.basename(root_file, ".rb"))
-      ActiveSupport::Inflector.constantize("#{module_name}::Application")
+      module_name = Internal::Inflections.camelize(File.basename(root_file, ".rb"))
+      Internal::Inflections.constantize("#{module_name}::Application")
     rescue NameError
       nil
     end

data/lib/charming/controller/action_hooks.rb

@@ -57,9 +57,13 @@ module Charming
         private
 
         # Wraps an action call in the full before/around/after hook chain and rescue handlers.
-        # Replaces the plain `public_send(action)` in Controller#dispatch.
+        # Replaces the plain `public_send(action)` in Controller#dispatch. Tracks the running
+        # action so the DoubleRenderError message can name it.
         def run_action_with_hooks(action)
+          previous, @current_action = @current_action, action
           run_with_rescue(action) { run_around_hooks(action) { run_action(action) } }
+        ensure
+          @current_action = previous
         end
 
         def run_action(action)

data/lib/charming/controller/class_methods.rb

@@ -2,8 +2,10 @@
 
 module Charming
   class Controller
-    # DSL for declaring controller-level event bindings and configuration: keys, commands,
-    # timers, task handlers, the auto-rendered action, layout wrapper, and focus ring.
+    # DSL for declaring controller-level event bindings and configuration: keys,
+    # timers, task handlers, component-event handlers, the auto-rendered action,
+    # layout wrapper, and focus ring. (The `command` palette DSL lives in the
+    # opt-in app shell: Charming::Shell::Palette.)
     # Mixed into Controller as class methods; also exposed for tests and shared base controllers.
     module ClassMethods
       # Binds a key press to a controller action. *name* is the normalized key symbol (e.g., "up",
@@ -16,18 +18,23 @@ module Charming
         key_binding_scopes[key_name] = normalized_scope
       end
 
-      # Adds a CommandPalette entry with the given *label*. *action* is a method name to send on
-      # the controller, or a block to instance_exec when selected.
-      def command(label, action = nil, &block)
-        command_bindings << Components::CommandPalette::Command.new(label: label, value: block || action)
-      end
-
       # Declares a timer that fires every *every* seconds and dispatches *action* on the controller.
       # The runtime builds a TimerEvent and routes it to the active controller's dispatch_timer.
-      def timer(name, every:, action:)
+      # Timers run from boot by default; declare `autostart: false` to schedule one only when an
+      # action calls `start_timer`.
+      def timer(name, every:, action:, autostart: true)
         raise ArgumentError, "timer interval must be positive (got #{every.inspect})" unless every.is_a?(Numeric) && every.positive?
 
-        timer_bindings[name.to_sym] = TimerBinding.new(name: name.to_sym, interval: every, action: action)
+        timer_bindings[name.to_sym] = TimerBinding.new(name: name.to_sym, interval: every, action: action, autostart: autostart)
+      end
+
+      # Declares an animation: a stopped timer ticking *action* at *fps* frames per second.
+      # Begin motion with `start_timer(name)`; the action calls `stop_timer(name)` once the
+      # motion settles, returning the app to zero idle cost.
+      def animate(name, action:, fps: 30)
+        raise ArgumentError, "fps must be positive (got #{fps.inspect})" unless fps.is_a?(Numeric) && fps.positive?
+
+        timer(name, every: 1.0 / fps, action: action, autostart: false)
       end
 
       # Declares a task handler for async work submitted via `run_task(:name)`. When the task emits
@@ -43,6 +50,24 @@ module Charming
         task_progress_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
       end
 
+      # Declares the action dispatched when the component in *slot* submits a value
+      # (`Result.submitted(value)` from its `handle_key`; legacy forms normalize). The action receives the value.
+      def on_submit(slot, action)
+        component_event_bindings[[slot.to_sym, :submitted]] = action.to_sym
+      end
+
+      # Declares the action dispatched when the component in *slot* selects an item
+      # (`Result.selected(value)` from its `handle_key`; legacy forms normalize). The action receives the value.
+      def on_select(slot, action)
+        component_event_bindings[[slot.to_sym, :selected]] = action.to_sym
+      end
+
+      # Declares the action dispatched when the component in *slot* is cancelled
+      # (`Result.cancelled` from its `handle_key`; legacy forms normalize). The action receives no arguments.
+      def on_cancel(slot, action)
+        component_event_bindings[[slot.to_sym, :cancelled]] = action.to_sym
+      end
+
       # Sets the action that the controller should auto-render after a non-rendering action runs.
       # Defaults to :show when unset.
       def auto_render(action = :show)
@@ -66,6 +91,22 @@ module Charming
         @layout = layout_class
       end
 
+      # Declares the component for the named focus *slot*. The factory block is
+      # instance_exec'd against the controller (it can read params and state) and the
+      # result is memoized for the controller's lifetime — this replaces the
+      # hand-rolled `@query ||= ...` private-method convention. Also defines a private
+      # reader with the slot's name returning the memoized component.
+      def slot(name, &factory)
+        slot_definitions[name.to_sym] = factory
+        define_method(name) { component_for(name) }
+        private name
+      end
+
+      # Hash of declared slots (name => factory block), inherited from superclass.
+      def slot_definitions
+        @slot_definitions ||= superclass.respond_to?(:slot_definitions) ? superclass.slot_definitions.dup : {}
+      end
+
       # Hash of registered key bindings (symbol key name => action method name), inherited from
       # superclass controllers.
       def key_bindings
@@ -77,19 +118,26 @@ module Charming
         @key_binding_scopes ||= superclass.respond_to?(:key_binding_scopes) ? superclass.key_binding_scopes.dup : {}
       end
 
-      # Defines the named focus slots cycled by Tab/Shift+Tab traversal.
+      # Defines the named focus slots cycled by Tab/Shift+Tab traversal. Accepts any
+      # names, including layout panes without components (e.g. :sidebar). Called with
+      # no arguments — or never called — the ring defaults to the declared slots in
+      # declaration order.
       def focus_ring(*slots)
-        @focus_ring_slots = slots
+        @focus_ring_slots = slots unless slots.empty?
       end
 
-      # Returns the focus ring slots, inherited from superclass when undefined.
+      # Returns the focus ring slots: the explicit `focus_ring` declaration from the
+      # nearest declaring ancestor when one exists, otherwise the declared slots in
+      # declaration order.
       def focus_ring_slots
-        @focus_ring_slots ||= superclass.respond_to?(:focus_ring_slots) ? superclass.focus_ring_slots.dup : []
+        (explicit_focus_ring || slot_definitions.keys).dup
       end
 
-      # Array of registered command palette entries, inherited from superclass when undefined.
-      def command_bindings
-        @command_bindings ||= superclass.respond_to?(:command_bindings) ? superclass.command_bindings.dup : []
+      # True when the controller (or an ancestor) declared an explicit focus ring —
+      # explicit rings may name component-less layout panes, so they are not filtered
+      # to components the way the declared-slot default is.
+      def explicit_focus_ring?
+        !explicit_focus_ring.nil?
       end
 
       # Hash of timer name => TimerBinding, inherited from superclass when undefined.
@@ -107,8 +155,22 @@ module Charming
         @task_progress_bindings ||= superclass.respond_to?(:task_progress_bindings) ? superclass.task_progress_bindings.dup : {}
       end
 
+      # Hash of [slot, event] => action for component-event registrations made with
+      # `on_submit`/`on_select`/`on_cancel`, inherited from superclass when undefined.
+      def component_event_bindings
+        @component_event_bindings ||= superclass.respond_to?(:component_event_bindings) ? superclass.component_event_bindings.dup : {}
+      end
+
       private
 
+      # Returns the nearest explicit `focus_ring` declaration walking the superclass
+      # chain, or nil when none was made.
+      def explicit_focus_ring
+        return @focus_ring_slots if instance_variable_defined?(:@focus_ring_slots)
+
+        superclass.respond_to?(:explicit_focus_ring, true) ? superclass.send(:explicit_focus_ring) : nil
+      end
+
       # Validates that *scope* is :content or :global; otherwise raises ArgumentError.
       def validate_key_scope(scope)
         normalized_scope = scope.to_sym

data/lib/charming/controller/component_dispatch.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # ComponentDispatch forwards events to the currently focused component (the slot
+    # returned by `focus.current`) and translates component return values into controller
+    # action calls — `[:submitted, value]`, `[:selected, value]`, and `:cancelled` resolve
+    # through the class-level `on_submit`/`on_select`/`on_cancel` registry (falling back
+    # to the deprecated `<slot>_<event>` convention with a warning).
+    #
+    # Extracted as a collaborator (like KeyDispatch) so the dispatch rules live in one
+    # object instead of a mixin. Controllers access it via #component_dispatch.
+    class ComponentDispatch
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # Sends the current key event to the focused component (if it responds to `handle_key`).
+      # Returns `:handled` after dispatching, or nil when no component is focused.
+      def dispatch_to_focused_component
+        slot = controller.focus.current
+        component = slot && controller.component_for(slot)
+        return nil unless component&.respond_to?(:handle_key)
+
+        result = component.handle_key(event)
+        return nil if result.nil?
+
+        dispatch_component_result(slot, result)
+        :handled
+      end
+
+      # Translates a component `handle_key` *result* into a controller action call.
+      # Legacy return forms (`:handled`, `:cancelled`, `[:submitted, v]`,
+      # `[:selected, v]`) normalize to Components::Result here; components in the wild
+      # may return either form. Falls back to a default render when no handler exists
+      # (production only).
+      def dispatch_component_result(slot, result)
+        action, arguments = component_result_action(slot, Components::Result.normalize(result))
+        action ? controller.send(action, *arguments) : controller.send(:render_default_action)
+        controller.send(:render_default_action) unless controller.send(:response)
+      end
+
+      # Handles Tab/Shift+Tab by cycling through the focus ring. Returns :handled after rendering.
+      def dispatch_tab_traversal
+        return nil unless key_name == :tab
+        return nil if controller.focus.ring.empty?
+
+        controller.focus.cycle(event.shift ? -1 : +1)
+        controller.send(:render_default_action)
+        :handled
+      end
+
+      # Hit-tests the current mouse event against named layout panes from the latest render.
+      # Clicks move focus to matching slots; components in clicked panes receive local coordinates.
+      def dispatch_component_mouse
+        target = mouse_target_for_event
+        return nil unless target
+
+        slot = target.fetch(:name)
+        previous_focus = controller.focus.current
+        controller.focus.focus(slot) if focusable_click?(slot)
+
+        result = dispatch_mouse_to_target_component(slot, target)
+        return controller.send(:response) if result.nil? && previous_focus == controller.focus.current
+
+        result ? dispatch_component_result(slot, result) : controller.send(:render_default_action)
+        controller.send(:response)
+      end
+
+      private
+
+      attr_reader :controller
+
+      def event
+        controller.event
+      end
+
+      # Resolves which controller action (if any) corresponds to the normalized *result*.
+      def component_result_action(slot, result)
+        case result.kind
+        when :cancelled
+          component_action(slot, :cancelled)
+        when :submitted, :selected
+          component_action(slot, result.kind, result.value)
+        end
+      end
+
+      # Returns `[action, arguments]` for the component event in *slot* with *suffix*
+      # (:submitted, :selected, or :cancelled). Resolution order: an explicit
+      # `on_submit`/`on_select`/`on_cancel` registration, then the legacy
+      # `<slot>_<suffix>` hook (with a one-time deprecation warning). With neither,
+      # development/test raise UnhandledComponentEvent; production logs a warning and
+      # returns nil, which falls back to the default render.
+      def component_action(slot, suffix, *arguments)
+        action = controller.class.component_event_bindings[[slot.to_sym, suffix]]
+        return [action, arguments] if action
+
+        legacy_action = :"#{slot}_#{suffix}"
+        if controller.respond_to?(legacy_action, true)
+          Charming.deprecate(
+            "#{controller.class.name || "an anonymous controller"}##{legacy_action} uses the auto-discovered hook. " \
+            "Declare it explicitly: `#{component_event_dsl(suffix)} :#{slot}, :#{legacy_action}`.",
+            category: :"component_event_#{controller.class.name}_#{slot}_#{suffix}"
+          )
+          return [legacy_action, arguments]
+        end
+
+        unhandled_component_event(slot, suffix)
+        nil
+      end
+
+      # Raises UnhandledComponentEvent outside production; logs a warning in production.
+      def unhandled_component_event(slot, suffix)
+        message = "Unhandled component event: #{controller.class.name || "anonymous controller"} has no handler for " \
+          ":#{slot} :#{suffix}. Declare one: `#{component_event_dsl(suffix)} :#{slot}, :your_action`."
+        raise UnhandledComponentEvent, message unless Charming.env.production?
+
+        controller.logger.warn(message)
+      end
+
+      # The class-level DSL name that declares a handler for *suffix*.
+      def component_event_dsl(suffix)
+        {submitted: "on_submit", selected: "on_select", cancelled: "on_cancel"}.fetch(suffix)
+      end
+
+      # The normalized key symbol for the current event.
+      def key_name
+        Charming.key_of(event)
+      end
+
+      def mouse_target_for_event
+        controller.mouse_targets.rfind { |target| target.fetch(:rect).cover?(event.x, event.y) }
+      end
+
+      def focusable_click?(slot)
+        event.respond_to?(:click?) && event.click? && controller.focus.ring.include?(slot)
+      end
+
+      def dispatch_mouse_to_target_component(slot, target)
+        component = controller.component_for(slot)
+        return nil unless component&.respond_to?(:handle_mouse)
+
+        local_event = local_mouse_event(target.fetch(:inner_rect))
+        return nil unless local_event
+
+        component.handle_mouse(local_event)
+      end
+
+      def local_mouse_event(rect)
+        return nil unless rect.cover?(event.x, event.y)
+
+        Events::MouseEvent.new(
+          button: event.button,
+          x: event.x - rect.x,
+          y: event.y - rect.y,
+          ctrl: event.ctrl,
+          alt: event.alt,
+          shift: event.shift
+        )
+      end
+    end
+  end
+end

data/lib/charming/controller/dispatching.rb

@@ -76,9 +76,8 @@ module Charming
       # free-typed text (see Component#captures_text?).
       def focused_component_captures_text?
         slot = focus.current
-        return false unless slot && respond_to?(slot, true)
+        component = slot && component_for(slot)
 
-        component = send(slot)
         component.respond_to?(:captures_text?) && component.captures_text?
       end
     end

data/lib/charming/controller/focus_management.rb

@@ -9,8 +9,10 @@ module Charming
       # Returns the per-controller Focus object, defining the focus ring from class-level DSL
       # declarations on first access.
       def focus
+        assert_loop_thread!(:focus)
         @focus ||= Controller::Focus.for(session, self.class).tap do |f|
-          f.define(self.class.focus_ring_slots) unless self.class.focus_ring_slots.empty?
+          slots = resolved_focus_ring
+          f.define(slots) unless slots.empty?
         end
       end
 
@@ -18,6 +20,70 @@ module Charming
       def focused?(slot)
         focus.focused?(slot)
       end
+
+      # Internal: registers the focusable panes from the latest render — validates each
+      # name against the slot registry, then defines the layout focus scope. Called by
+      # views during render; the single commit point for layout focus.
+      def register_layout_focus(names)
+        validate_layout_slots(names)
+        focus.define_layout(names)
+      end
+
+      private
+
+      # Raises UnknownSlot for pane names nothing declares (dev/test); logs in production.
+      def validate_layout_slots(names)
+        unknown = names.reject { |name| known_slot?(name) }
+        return if unknown.empty?
+
+        message = unknown_slot_message(unknown, "rendered as focusable panes")
+        raise UnknownSlot, message unless Charming.env.production?
+
+        logger.warn(message)
+      end
+
+      # Validates on_submit/on_select/on_cancel registrations once per controller
+      # instance, at the first dispatch (class-definition-time checks would be
+      # order-sensitive: a slot's method may be defined below the registration).
+      def validate_slot_registrations_once
+        return if @slot_registrations_validated
+
+        @slot_registrations_validated = true
+        unknown = self.class.component_event_bindings.keys.map(&:first).uniq.reject { |name| known_slot?(name) }
+        return if unknown.empty?
+
+        message = unknown_slot_message(unknown, "registered `on_*` handlers for undeclared slots")
+        raise UnknownSlot, message unless Charming.env.production?
+
+        logger.warn(message)
+      end
+
+      # True when *name* resolves as a slot: declared with `slot`, named in the focus
+      # ring, or defined as a method (the legacy convention).
+      def known_slot?(name)
+        self.class.slot_definitions.key?(name.to_sym) ||
+          self.class.focus_ring_slots.include?(name.to_sym) ||
+          respond_to?(name, true)
+      end
+
+      # Builds the UnknownSlot message, naming the unknown slots, the fix, and the
+      # declared slots.
+      def unknown_slot_message(unknown, context)
+        declared = self.class.slot_definitions.keys
+        "#{self.class.name || "An anonymous controller"} #{context}: " \
+          "#{unknown.map { |name| name.inspect }.join(", ")} — nothing declares them. " \
+          "Declare each with `slot :name { ... }`, add it to `focus_ring`, or define a same-named method. " \
+          "Declared slots: #{declared.empty? ? "(none)" : declared.map(&:inspect).join(", ")}."
+      end
+
+      # The ring handed to Focus: the class ring, filtered to actual components when it
+      # comes from declared slots (an explicit `focus_ring` keeps component-less panes).
+      def resolved_focus_ring
+        ring = self.class.focus_ring_slots
+        return ring if self.class.explicit_focus_ring?
+
+        ring.select { |name| component_for(name).is_a?(Component) }
+      end
     end
   end
 end