charming 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3edeedc6b7d09bb964b5f3e6ba7306ced50355bfffb93c049c9cc7415cab4d2
-  data.tar.gz: 3944a4cef79f57035ac08d5dbeba1fef7e96504c5ea34c3237e2dad08dcdde31
+  metadata.gz: 71b370eac77c67126921d7347a0d23f834f23774626c111445e9abdef73555d9
+  data.tar.gz: c8dd983f46183c2fbdb22f9c30753b4f1443d8de2989a4e7f90016f397aa12e4
 SHA512:
-  metadata.gz: ea1881f3bf0d3517cc2a0f20b8ae15fcd452c091d71f6535bc632a7dd66be6abaf97fa3ca76aef567be068be41a374c11e263529cc43dad931ac7fe344847061
-  data.tar.gz: 6b396f225bdb25bf3cd1f5ff569d4907a9e2e0be8bbfc4ad500021251f1bc39ba65b270b80d28b7dd9fc087294fc9a91d4fb4da5dfbdfbdced19040074093c0a
+  metadata.gz: 2ee80f1c214001c8f91b36ba308f0e2f67aecbc258e7ff3ce63de2eb04093a405a0a23c3174cac6c3a1c6a98746b5353e66dd8179aebab4fe60ad35132603f19
+  data.tar.gz: 5242fbc9ad41ca1c0dbebbb070bb33cbdd1279955f81aa2f067954a1b11ffdd1b9cb7b90321285fa17e795c31d3fff32c7e052e95dee7e7c90318e19d252fba1

data/README.md

@@ -2,7 +2,7 @@
 
 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, 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, 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
 
@@ -47,7 +47,7 @@ lib/my_app.rb                            # namespace loader (Zeitwerk)
 exe/my_app                               # executable entry point
 ```
 
-Generated apps include a sidebar/content layout, command palette, focus management, theme switching, and default key bindings for commands (`p`) and quit (`q`).
+Generated apps include a sidebar/content layout, command palette, focus management, theme switching, and default key bindings for commands (`ctrl+p`) and quit (`q`).
 
 ## Development
 

data/lib/charming/application.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "json"
+
 module Charming
   # Application is a lightweight, Rails-inspired application base for building
   # terminal-based apps. It provides routing (via a DSL), session storage, and
@@ -7,6 +10,7 @@ module Charming
   class Application
     LOGGER_READER = Object.new.freeze
     THEME_READER = Object.new.freeze
+    COALESCE_READER = Object.new.freeze
 
     class << self
       # Registers or returns the app's Router. Accepts an optional block to define
@@ -39,13 +43,27 @@ module Charming
         @root = File.expand_path(path)
       end
 
-      # Registers a named theme. Provide either *from:* (path to a JSON file relative to the app root)
-      # or *built_in:* (name of a bundled theme such as "phosphor"). Raises when neither or both are given.
-      def theme(name, from: nil, built_in: nil)
-        raise ArgumentError, "theme expects from: or built_in:" unless from || built_in
-        raise ArgumentError, "theme expects either from: or built_in:, not both" if from && built_in
-
-        themes[name.to_sym] = if built_in
+      # Registers a named theme. Provide one of:
+      # - *from:* — path to a JSON theme file relative to the app root
+      # - *built_in:* — name of a bundled theme ("phosphor", "catppuccin-mocha",
+      #   "catppuccin-latte", "gruvbox-dark", "nord", "tokyonight")
+      # - *extends:* — name of an already-registered theme to derive from, with
+      #   *overrides:* (token name → style spec) merged on top:
+      #
+      #     theme :dark, built_in: "tokyonight"
+      #     theme :high_contrast, extends: :dark, overrides: {text: {foreground: "#ffffff"}}
+      def theme(name, from: nil, built_in: nil, extends: nil, overrides: nil)
+        sources = [from, built_in, extends].compact
+        raise ArgumentError, "theme expects from:, built_in:, or extends:" if sources.empty?
+        raise ArgumentError, "theme expects only one of from:, built_in:, or extends:" if sources.length > 1
+        raise ArgumentError, "overrides: requires extends:" if overrides && !extends
+
+        themes[name.to_sym] = if extends
+          parent = themes.fetch(extends.to_sym) do
+            raise ArgumentError, "unknown parent theme: #{extends.inspect} (register it before extending)"
+          end
+          parent.merge(overrides || {})
+        elsif built_in
           UI::Theme.load_builtin(built_in)
         else
           UI::Theme.load_file(resolve_theme_path(from))
@@ -74,6 +92,44 @@ module Charming
         themes.fetch(theme_name.to_sym)
       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.
+      def persist_session(to:)
+        @session_path = to
+      end
+
+      # The configured session file path, walking the superclass chain. Nil when
+      # persistence is not enabled.
+      def session_path
+        return @session_path if instance_variable_defined?(:@session_path)
+        return superclass.session_path if superclass.respond_to?(:session_path)
+
+        nil
+      end
+
+      # When true, the runtime collapses bursts of identical key events — the flood a terminal
+      # emits while a key is held (OS auto-repeat) — into a single dispatch, so holding a key
+      # can't queue a backlog that keeps acting after release. Off by default: it also merges
+      # intentional fast repeats of the same key (e.g. tab tab), so enable it only for
+      # movement-style apps. Pass a boolean to set; call without args to read (inherited).
+      def coalesce_input(value = COALESCE_READER)
+        return configured_coalesce_input if value == COALESCE_READER
+
+        @coalesce_input = value
+      end
+
+      # The mouse motion reporting mode: :drag (default) reports movement only while
+      # a button is held; :all also reports buttonless hover movement. Pass a symbol
+      # to set; call without args to read (inherited).
+      def mouse_motion(value = COALESCE_READER)
+        return configured_mouse_motion if value == COALESCE_READER
+        raise ArgumentError, "mouse_motion must be :drag or :all" unless %i[drag all].include?(value)
+
+        @mouse_motion = value
+      end
+
       private
 
       def configured_logger
@@ -83,6 +139,20 @@ module Charming
         @logger = Logger.new(File::NULL)
       end
 
+      def configured_coalesce_input
+        return @coalesce_input if instance_variable_defined?(:@coalesce_input)
+        return superclass.coalesce_input if superclass.respond_to?(:coalesce_input)
+
+        false
+      end
+
+      def configured_mouse_motion
+        return @mouse_motion if instance_variable_defined?(:@mouse_motion)
+        return superclass.mouse_motion if superclass.respond_to?(:mouse_motion)
+
+        :drag
+      end
+
       # Expands a relative theme path against the app root (or the current working directory
       # when no root is configured). Returns *path* unchanged when it is already absolute.
       def resolve_theme_path(path)
@@ -95,10 +165,24 @@ module Charming
     attr_accessor :logger, :task_executor
     attr_reader :session
 
-    # Initializes an empty session hash for per-request state storage.
+    # Initializes the session hash for per-request state storage, restoring a
+    # previously persisted session when `persist_session` is configured.
     def initialize
       @logger = self.class.logger
-      @session = {}
+      @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.
+    def save_session
+      path = self.class.session_path
+      return unless path
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.generate(serializable_session))
+    rescue => e
+      logger.warn("session not saved: #{e.class}: #{e.message}")
     end
 
     # Delegates to the class-level Router, providing instance access to route definitions.
@@ -114,5 +198,56 @@ module Charming
       self.class.theme_for(name)
       session[:theme] = name.to_sym
     end
+
+    # Whether the runtime should coalesce held-key auto-repeat for this app (see the class-level
+    # `coalesce_input` DSL). Read by the Runtime at startup.
+    def coalesce_input?
+      self.class.coalesce_input == true
+    end
+
+    # The mouse motion reporting mode for this app (see the class-level `mouse_motion`
+    # DSL). Read by the Runtime at startup.
+    def mouse_motion
+      self.class.mouse_motion
+    end
+
+    private
+
+    # Loads the persisted session JSON (symbolizing keys), or {} when absent/invalid.
+    def load_session
+      path = self.class.session_path
+      return {} unless path && File.exist?(path)
+
+      JSON.parse(File.read(path), symbolize_names: true)
+    rescue JSON::ParserError => e
+      logger.warn("session not restored: #{e.message}")
+      {}
+    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
+
+    # 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).
+    def serializable_session
+      session.except(*INTERNAL_SESSION_KEYS).select { |_key, value| json_safe?(value) }
+    end
+
+    def json_safe?(value)
+      case value
+      when nil, true, false, String, Symbol, Integer, Float
+        true
+      when Array
+        value.all? { |item| json_safe?(item) }
+      when Hash
+        value.all? { |key, item| (key.is_a?(String) || key.is_a?(Symbol)) && json_safe?(item) }
+      else
+        false
+      end
+    end
   end
 end

data/lib/charming/audio/player.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Charming
+  # Audio provides simple, cross-platform sound playback by shelling out to a system
+  # audio binary. The engine lives in {Player}; {System} is the swappable OS adapter.
+  module Audio
+    # Player plays a single sound file by spawning a system audio binary, and exposes
+    # `stop`/`playing?`/`wait` to manage the child process. It never blocks the event
+    # loop on its own — call {play} for fire-and-forget playback, or drive it from a
+    # controller `run_task` (spawn + {wait}, with an `ensure player.stop`) to get a
+    # completion event and reliable teardown when the app quits.
+    #
+    # A backend binary is resolved on first use, in priority order: `ffplay` (from
+    # ffmpeg) on every platform, then OS-native players (`afplay` on macOS; `paplay`,
+    # `mpg123`, `aplay` on Linux). {Unavailable} is raised when none are installed.
+    class Player
+      # Raised by {play} when no supported audio backend is found on `PATH`.
+      class Unavailable < Charming::Error; end
+
+      # Candidate backends in resolution order. `:os` is `:any`, `:macos`, or `:linux`;
+      # `:args` are inserted before the file path in the spawned command.
+      BACKENDS = [
+        {command: "ffplay", os: :any, args: ["-nodisp", "-autoexit", "-loglevel", "quiet"]},
+        {command: "afplay", os: :macos, args: []},
+        {command: "paplay", os: :linux, args: []},
+        {command: "mpg123", os: :linux, args: ["-q"]},
+        {command: "aplay", os: :linux, args: ["-q"]}
+      ].freeze
+
+      # *system* is the OS adapter used to probe `PATH` and spawn/track the player
+      # process. The default talks to the real OS; specs inject a fake.
+      def initialize(system: System.new)
+        @system = system
+        @pid = nil
+      end
+
+      # Plays the sound file at *path*, stopping any sound already in progress first.
+      # Spawns the resolved backend and returns the child PID. Raises {Unavailable}
+      # when no backend binary is installed for this platform.
+      def play(path)
+        backend = resolve_backend!
+        stop if playing?
+        @pid = @system.spawn([backend[:command], *backend[:args], path.to_s])
+      end
+
+      # Stops the current sound (if any), terminating and reaping the child process.
+      # Safe to call when nothing is playing.
+      def stop
+        return unless @pid
+
+        @system.terminate(@pid)
+        @system.wait(@pid)
+        @pid = nil
+      end
+
+      # True while a spawned sound is still playing.
+      def playing?
+        !@pid.nil? && @system.alive?(@pid)
+      end
+
+      # Blocks until the current sound finishes, then clears it. Intended for use inside
+      # a background `run_task`. If the task thread is killed mid-wait (e.g. on app
+      # shutdown), `@pid` is left intact so an `ensure player.stop` can reap the child.
+      def wait
+        return unless @pid
+
+        @system.wait(@pid)
+        @pid = nil
+      end
+
+      # True when a backend binary is installed for this platform. Lets callers degrade
+      # gracefully (e.g. skip a chime) instead of rescuing {Unavailable}.
+      def available?
+        !backend.nil?
+      end
+
+      private
+
+      # Returns the resolved backend or raises {Unavailable} listing what was searched.
+      def resolve_backend!
+        backend || raise(Unavailable, "no audio player found on PATH (looked for: #{searched.join(", ")})")
+      end
+
+      # The first supported, installed backend for this platform, or nil. Memoized once found.
+      def backend
+        @backend ||= BACKENDS.find { |candidate| supported?(candidate) && @system.which?(candidate[:command]) }
+      end
+
+      # The command names that apply to this platform, in order (for error messages).
+      def searched
+        BACKENDS.select { |candidate| supported?(candidate) }.map { |candidate| candidate[:command] }
+      end
+
+      # True when *candidate* targets this platform.
+      def supported?(candidate)
+        case candidate[:os]
+        when :any then true
+        when :macos then @system.macos?
+        when :linux then @system.linux?
+        end
+      end
+    end
+  end
+end

data/lib/charming/audio/system.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Charming
+  module Audio
+    # System is the OS adapter the {Player} uses to locate and control audio-player
+    # processes. It wraps Ruby's `Process`/`ENV`/`RbConfig` so specs can substitute a
+    # fake collaborator and never shell out, touch the real process table, or play sound.
+    class System
+      # *host_os* identifies the platform (defaults to the running Ruby's). *path* is the
+      # `PATH` string searched by {which?} (defaults to the process environment).
+      def initialize(host_os: RbConfig::CONFIG["host_os"], path: ENV["PATH"])
+        @host_os = host_os.to_s
+        @path = path.to_s
+      end
+
+      # True on macOS.
+      def macos?
+        @host_os.match?(/darwin/i)
+      end
+
+      # True on Linux.
+      def linux?
+        @host_os.match?(/linux/i)
+      end
+
+      # True when *command* resolves to an executable file on `PATH`.
+      def which?(command)
+        path_dirs.any? do |dir|
+          candidate = File.join(dir, command)
+          File.file?(candidate) && File.executable?(candidate)
+        end
+      end
+
+      # Spawns *argv* (an array) detached from the terminal, discarding the child's
+      # stdout/stderr, and returns the child PID.
+      def spawn(argv)
+        Process.spawn(*argv, out: File::NULL, err: File::NULL)
+      end
+
+      # Sends `SIGTERM` to *pid*, ignoring a process that has already exited.
+      def terminate(pid)
+        Process.kill("TERM", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      # True while *pid* is still running. Reaps the child (non-blocking) once it exits.
+      def alive?(pid)
+        Process.waitpid(pid, Process::WNOHANG).nil?
+      rescue Errno::ECHILD, Errno::ESRCH
+        false
+      end
+
+      # Blocks until *pid* exits, then reaps it. No-op when the child is already gone.
+      def wait(pid)
+        Process.waitpid(pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      private
+
+      # Returns the directories on `PATH`.
+      def path_dirs
+        @path.split(File::PATH_SEPARATOR)
+      end
+    end
+  end
+end

data/lib/charming/cli.rb

@@ -23,6 +23,7 @@ module Charming
       case command
       when "new" then new_app(args)
       when "generate", "g" then generate(args)
+      when "console", "c" then console(args)
       when /^db:/ then database(command, args)
       else usage(1)
       end
@@ -63,19 +64,76 @@ module Charming
       generator_class(type).new(name, args, out: out, destination: pwd, force: force)
     end
 
-    # Returns the generator class for a *type* string (controller, model, screen, view, component).
+    # Returns the generator class for a *type* string (controller, model, screen, view,
+    # component, migration).
     def generator_class(type)
       {
         "controller" => Generators::ControllerGenerator,
         "model" => Generators::ModelGenerator,
         "screen" => Generators::ScreenGenerator,
         "view" => Generators::ViewGenerator,
-        "component" => Generators::ComponentGenerator
+        "component" => Generators::ComponentGenerator,
+        "migration" => Generators::MigrationGenerator
       }.fetch(type) { raise Generators::Error, "Unknown generator: #{type}" }
     end
 
+    # Handles `charming console`: loads the app (root file, which sets up Zeitwerk and the
+    # database when configured), prints a banner, and opens IRB with `app` available.
+    def console(args)
+      raise Generators::Error, "Usage: charming console" if args.any?
+
+      root_file = app_root_file
+      raise Generators::Error, "Run this command from a Charming app root" unless root_file
+
+      require "irb"
+      require root_file
+      out.puts "Loading #{Charming.env} environment (Charming #{Charming::VERSION})"
+      app_class = console_application_class(root_file)
+      ConsoleContext.start(app_class)
+      0
+    end
+
+    # The app's root loader (`lib/<gemspec name>.rb`), or nil when not in an app root.
+    def app_root_file
+      gemspec = Dir.glob(File.join(pwd, "*.gemspec")).first
+      return nil unless gemspec
+
+      path = File.join(pwd, "lib", "#{File.basename(gemspec, ".gemspec")}.rb")
+      File.exist?(path) ? path : nil
+    end
+
+    # 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")
+    rescue NameError
+      nil
+    end
+
+    # ConsoleContext is the binding IRB starts in: `app` returns a memoized application
+    # instance when the app class was resolvable.
+    class ConsoleContext
+      def self.start(app_class)
+        new(app_class).start
+      end
+
+      def initialize(app_class)
+        @app_class = app_class
+      end
+
+      def app
+        @app ||= @app_class&.new
+      end
+
+      def start
+        IRB.setup(nil)
+        workspace = IRB::WorkSpace.new(binding)
+        IRB::Irb.new(workspace).run(IRB.conf)
+      end
+    end
+
     # Routes `db:*` commands to either the install path (db:install) or the generic
-    # Database::Commands dispatcher.
+    # Database::Commands dispatcher. Extra arguments (e.g., `STEP=2`) are passed through.
     def database(command, args)
       if command == "db:install"
         database = args.shift || raise(Generators::Error, "Usage: charming db:install sqlite3")
@@ -83,9 +141,7 @@ module Charming
 
         Generators::DatabaseInstaller.new(database, out: out, destination: pwd).install
       else
-        raise Generators::Error, "Usage: charming #{command}" if args.any?
-
-        Database::Commands.new(command, out: out, destination: pwd).run
+        Database::Commands.new(command, args: args, out: out, destination: pwd).run
       end
       0
     end
@@ -112,7 +168,7 @@ module Charming
 
     # Prints a usage banner to stderr and returns *status* (1 for unknown commands).
     def usage(status)
-      err.puts "Usage: charming new NAME | charming generate TYPE NAME [args] | charming db:COMMAND"
+      err.puts "Usage: charming new NAME | charming generate TYPE NAME [args] | charming console | charming db:COMMAND"
       status
     end
   end

data/lib/charming/controller/action_hooks.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # ActionHooks provides Rails-style before/after/around action hooks and rescue_from.
+    # Class-level DSL: before_action, after_action, around_action, rescue_from.
+    # Hook arrays are inherited by subclasses via dup.
+    module ActionHooks
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+      end
+
+      module ClassMethods
+        # Registers a before hook that runs before the given *actions* (or all actions when
+        # *only:* is omitted). *except:* excludes specific actions.
+        def before_action(method_name, only: nil, except: nil)
+          action_hooks << {type: :before, method: method_name, only: normalize_filter(only), except: normalize_filter(except)}
+        end
+
+        # Registers an after hook. Runs after the action even if the action rendered early.
+        def after_action(method_name, only: nil, except: nil)
+          action_hooks << {type: :after, method: method_name, only: normalize_filter(only), except: normalize_filter(except)}
+        end
+
+        # Registers an around hook. The hook method must yield to invoke the action.
+        def around_action(method_name, only: nil, except: nil)
+          action_hooks << {type: :around, method: method_name, only: normalize_filter(only), except: normalize_filter(except)}
+        end
+
+        # Registers an exception handler. When an action raises an exception matching *klass*
+        # (or any of *classes*), the controller calls *with:* instead of propagating.
+        def rescue_from(*classes, with:)
+          rescue_handlers << {classes: classes.flatten, with: with}
+        end
+
+        # All registered hooks, inherited from superclass.
+        def action_hooks
+          @action_hooks ||= superclass.respond_to?(:action_hooks) ? superclass.action_hooks.dup : []
+        end
+
+        # All registered rescue handlers, inherited from superclass.
+        def rescue_handlers
+          @rescue_handlers ||= superclass.respond_to?(:rescue_handlers) ? superclass.rescue_handlers.dup : []
+        end
+
+        private
+
+        def normalize_filter(value)
+          return nil if value.nil?
+
+          Array(value).map(&:to_sym)
+        end
+      end
+
+      module InstanceMethods
+        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.
+        def run_action_with_hooks(action)
+          run_with_rescue(action) { run_around_hooks(action) { run_action(action) } }
+        end
+
+        def run_action(action)
+          run_before_hooks(action)
+          public_send(action)
+          run_after_hooks(action)
+        end
+
+        def run_before_hooks(action)
+          hooks_for(action, :before).each { |hook| send(hook[:method]) }
+        end
+
+        def run_after_hooks(action)
+          hooks_for(action, :after).each { |hook| send(hook[:method]) }
+        end
+
+        def run_around_hooks(action, &block)
+          around = hooks_for(action, :around)
+          wrap_around(around, 0, &block)
+        end
+
+        def wrap_around(hooks, index, &block)
+          return yield if index >= hooks.length
+
+          send(hooks[index][:method]) { wrap_around(hooks, index + 1, &block) }
+        end
+
+        def run_with_rescue(action)
+          yield
+        rescue => e
+          handler = rescue_handler_for(e)
+          raise unless handler
+
+          send(handler[:with], e)
+          render_default_action unless response
+        end
+
+        # Finds the handler whose rescued class is most specific for *exception* (closest in its
+        # ancestor chain). Ties go to the last-registered handler. Note: this deliberately differs
+        # from Rails, where declaration order alone decides — specificity is less surprising.
+        def rescue_handler_for(exception)
+          ancestors = exception.class.ancestors
+          best = self.class.rescue_handlers.reverse.filter_map { |handler|
+            specificity = handler[:classes].filter_map { |klass| ancestors.index(klass) }.min
+            [specificity, handler] if specificity
+          }.min_by(&:first)
+          best&.last
+        end
+
+        def hooks_for(action, type)
+          self.class.action_hooks.select do |hook|
+            next false unless hook[:type] == type
+            next false if hook[:only] && !hook[:only].include?(action.to_sym)
+            next false if hook[:except]&.include?(action.to_sym)
+
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/charming/controller/class_methods.rb

@@ -11,7 +11,7 @@ module Charming
       # shortcuts that fire regardless of focus. Raises ArgumentError for any other scope.
       def key(name, action, scope: :content)
         normalized_scope = validate_key_scope(scope)
-        key_name = name.to_sym
+        key_name = Charming.key_binding_name(name)
         key_bindings[key_name] = action
         key_binding_scopes[key_name] = normalized_scope
       end
@@ -25,6 +25,8 @@ module Charming
       # 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:)
+        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)
       end
 
@@ -34,6 +36,13 @@ module Charming
         task_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
       end
 
+      # Declares a progress handler for a task: while `run_task(:name)` runs, each
+      # `progress.report(...)` dispatches *action* on the controller (the event is
+      # available as `event` — a TaskProgressEvent with current/total/message).
+      def on_task_progress(name, action:)
+        task_progress_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
+      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)
@@ -93,6 +102,11 @@ module Charming
         @task_bindings ||= superclass.respond_to?(:task_bindings) ? superclass.task_bindings.dup : {}
       end
 
+      # Hash of task name => TaskBinding for progress handlers, inherited from superclass.
+      def task_progress_bindings
+        @task_progress_bindings ||= superclass.respond_to?(:task_progress_bindings) ? superclass.task_progress_bindings.dup : {}
+      end
+
       private
 
       # Validates that *scope* is :content or :global; otherwise raises ArgumentError.