charming 0.2.3 → 0.4.0

data/lib/charming/runtime.rb

@@ -16,10 +16,15 @@ module Charming
       @task_queue = Thread::Queue.new
       @task_executor = build_task_executor(task_executor)
       @application.task_executor = @task_executor
-      @route = resolve_route("/")
+      @route = resolve_route(:root)
       @screen = backend_screen
       @coalesce_input = @application.respond_to?(:coalesce_input?) && @application.coalesce_input?
       @event_loop = build_event_loop
+      @application.timer_control = Internal::TimerControl.new(
+        event_loop: @event_loop,
+        bindings: -> { @route.controller_class.timer_bindings }
+      )
+      enter_controller
     end
 
     # Runs the event loop: enters alt-screen, dispatches incoming events
@@ -30,10 +35,12 @@ module Charming
       setup_terminal
       install_signal_handlers
       install_exit_hook
+      @controller.capture_loop_thread!
       with_raw_input do
         render(initial_response)
         @event_loop.run { |event, more_ready| process(event, flush: !more_ready) }
       ensure
+        exit_controller
         restore_signal_handlers
         @task_executor&.shutdown(timeout: 2.0)
         @application.save_session if @application.respond_to?(:save_session)
@@ -52,12 +59,18 @@ module Charming
         backend: @backend,
         clock: @clock,
         task_queue: @task_queue,
-        timer_bindings: @route.controller_class.timer_bindings.values,
+        timer_bindings: autostart_timer_bindings,
         coalesce_input: @coalesce_input,
         interrupted: -> { @interrupted }
       )
     end
 
+    # The current route's timers that run from boot. Timers declared with
+    # `autostart: false` (including `animate` ticks) wait for `start_timer`.
+    def autostart_timer_bindings
+      @route.controller_class.timer_bindings.values.select(&:autostart)
+    end
+
     # 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
@@ -203,38 +216,48 @@ module Charming
     # Dispatches an action on the current route's controller with an optional event.
     # Entry point from the event loop into controllers.
     def dispatch(action, event: nil)
-      controller(event: event).dispatch(action)
+      @controller.dispatch(action, event: event)
     end
 
     # Dispatches a key press to the current route's controller.
     def dispatch_key(event)
-      controller(event: event).dispatch_key
+      @controller.dispatch_key(event)
     end
 
     # Dispatches a timer tick to the current route's controller.
     def dispatch_timer(event)
-      controller(event: event).dispatch_timer
+      @controller.dispatch_timer(event)
     end
 
     # Dispatches an async task result to the current route's controller.
     def dispatch_task(event)
-      controller(event: event).dispatch_task
+      @controller.dispatch_task(event)
     end
 
     # Dispatches a task progress report to the current route's controller.
     def dispatch_task_progress(event)
-      controller(event: event).dispatch_task_progress
+      @controller.dispatch_task_progress(event)
     end
 
     # Dispatches a mouse action (click, drag, scroll) to the current route's controller.
     def dispatch_mouse(event)
-      controller(event: event).dispatch_mouse
+      @controller.dispatch_mouse(event)
+    end
+
+    # Constructs the controller for the current route and runs its screen_entered hook.
+    # The instance lives until the next navigation (or quit), so controller ivars hold
+    # screen-lifetime state.
+    def enter_controller
+      @controller = @route.controller_class.new(
+        application: @application, params: @route.params, screen: screen, route: @route
+      )
+      @controller.screen_entered
     end
 
-    # Instantiates a fresh controller for the active route, passing the application, current *event*,
-    # route params, screen dimensions, and route object. Called by every dispatch path.
-    def controller(event: nil)
-      @route.controller_class.new(application: @application, event: event, params: @route.params, screen: screen, route: @route)
+    # Runs the current controller's screen_exited hook and releases it.
+    def exit_controller
+      @controller&.screen_exited
+      @controller = nil
     end
 
     # Type-based dispatcher: routes resize, task, progress, timer, mouse, paste, and key
@@ -254,47 +277,50 @@ module Charming
     # 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)
+      return nil unless @controller.respond_to?(:focus_changed)
 
-      ctrl.dispatch(:focus_changed)
+      @controller.dispatch(:focus_changed, event: event)
     end
 
     # Dispatches pasted text to the current route's controller.
     def dispatch_paste(event)
-      controller(event: event).dispatch_paste
+      @controller.dispatch_paste(event)
     end
 
-    # Dispatches a resize event: updates screen dimensions and re-renders the current action.
+    # Dispatches a resize event: updates screen dimensions on the live controller 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.
     def dispatch_resize(event)
       @screen = Screen.new(width: event.width, height: event.height)
       @renderer.invalidate if @renderer.respond_to?(:invalidate)
       @backend.clear if @backend.respond_to?(:clear)
+      @controller.update_screen(@screen)
       dispatch(@route.action, event: event)
     end
 
-    # Follows navigation responses: resolves the new route from the router,
-    # reschedules the event loop's timers for the new controller, and
+    # Follows navigation responses: discards the current controller, resolves and enters
+    # the new route, 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 = resolve_route(response.path)
-      @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
+      exit_controller
+      @route = resolve_route(response.name, response.params)
+      @event_loop.reset_timers(autostart_timer_bindings)
+      enter_controller
       dispatch(@route.action)
     end
 
-    # Resolves *path* from the app's router. An unrouted "/" falls back to the app's
-    # first route, or to the built-in welcome screen when no routes are defined yet
-    # (like Rails' welcome page); other unrouted paths still raise.
-    def resolve_route(path)
-      @application.routes.resolve(path)
+    # Resolves *name* from the app's router, attaching *params*. An unrouted :root falls
+    # back to the app's first route, or to the built-in welcome screen when no screens
+    # are defined yet (like Rails' welcome page); other unrouted names still raise.
+    def resolve_route(name, params = {})
+      @application.routes.resolve(name, params)
     rescue KeyError
-      raise unless path == "/"
+      raise unless name.to_sym == :root
 
-      @application.routes.all.first || Welcome.route
+      (@application.routes.all.first || Welcome.route).with_params(params)
     end
 
     # Derives Screen dimensions (width, height) from the terminal backend.

data/lib/charming/{controller/command_palette.rb → shell/palette.rb}

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
 module Charming
-  class Controller
-    # Command palette helpers mixed into Controller. Opens/closes the palette, builds the
-    # palette from registered command bindings or theme list, and routes key/mouse events
-    # through it. Supports both the standard command palette (:commands) and the theme picker
-    # (:themes) via a discriminated `session[:command_palette]` state hash.
-    module CommandPalette
+  # Shell::Palette is the opt-in app-shell command palette: the `command` class DSL,
+  # open/close helpers, the theme picker, and key/mouse routing while the palette is
+  # open. Generated apps include it in ApplicationController when generated with the
+  # sidebar layout (`include Charming::Shell::Palette`).
+  #
+  # Palette state lives in the session, not on the controller: the palette is app-global —
+  # a command can navigate to another screen, and the open/closed state must survive the
+  # controller swap that navigation causes.
+  module Shell
+    module Palette
+      # Wires the class-level `command` DSL into the including controller.
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level palette DSL: `command` entries and their inherited registry.
+      module ClassMethods
+        # 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
+
+        # 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 : []
+        end
+      end
+
       # Opens the command palette populated with the controller's `command_bindings`. Pushes
       # a focus scope so subsequent keys are routed to the palette.
       def open_command_palette
@@ -32,6 +55,13 @@ module Charming
         build_command_palette_from_state(session[:command_palette]) if command_palette_open?
       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
+
       private
 
       # Routes the current key event to the open palette. Cancels on Escape, performs the
@@ -40,10 +70,10 @@ module Charming
         palette = command_palette
         result = palette.handle_key(event)
 
-        if result == :cancelled
+        if result&.cancelled?
           close_command_palette
         elsif selected_command?(result)
-          perform_command(result.last)
+          perform_command(result.value)
         else
           save_command_palette_state(palette)
           render_default_action unless response
@@ -92,13 +122,15 @@ module Charming
         session[:command_palette] = session.fetch(:command_palette).merge(palette.state)
       end
 
-      # True when a component result is the `[:selected, command]` array shape.
+      # True when a component result carries a selected command (Result.selected).
       def selected_command?(result)
-        result.is_a?(Array) && result.first == :selected
+        result.respond_to?(:selected?) && result.selected?
       end
 
       # Invokes the value (proc, lambda, or method symbol) of the selected *command*, then
       # closes the palette unless the command was :quit or the user has re-opened it.
+      # A command that set a response keeps it; only a command that produced no response
+      # falls back to the default render.
       def perform_command(command)
         current_palette_state = session[:command_palette]
         pop_command_palette_scope
@@ -106,7 +138,7 @@ module Charming
         if command.value != :quit && session[:command_palette].equal?(current_palette_state)
           session.delete(:command_palette)
         end
-        render_default_action unless response&.navigate? || response&.quit?
+        render_default_action unless response
       end
 
       # Returns the theme-switching commands used by the theme picker palette.

data/lib/charming/{controller/sidebar_navigation.rb → shell/sidebar.rb}

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 module Charming
-  class Controller
-    # Sidebar-navigation helpers mixed into Controller. Tracks the sidebar's current route index,
-    # routes j/k/enter/tab keys when the sidebar is focused, and exposes `sidebar_focused?` for views.
-    #
-    # Sidebar/content focus is driven entirely by the controller's Focus object. Controllers
-    # that want Tab-driven sidebar navigation declare `focus_ring :sidebar, :content` (generated
-    # apps do); without those slots in the ring, `focus_sidebar`/`focus_content` are no-ops.
-    module SidebarNavigation
+  # Shell::Sidebar is the opt-in app-shell sidebar: route listing, sidebar/content focus
+  # split, j/k/enter navigation, and mouse clicks on route rows. Generated apps include it
+  # in ApplicationController when generated with the sidebar layout
+  # (`include Charming::Shell::Sidebar`). Controllers that want Tab-driven sidebar
+  # navigation declare `focus_ring :sidebar, :content`.
+  module Shell
+    module Sidebar
       # Moves focus to the sidebar slot and remembers the highlighted route.
       def focus_sidebar
         focus.focus(:sidebar)
@@ -37,7 +36,8 @@ module Charming
       end
 
       # Returns the index of the currently selected route in `sidebar_routes`, defaulting to the
-      # active route when the session index is unset.
+      # active route when the session index is unset. Stored in the session: the sidebar cursor
+      # is app-global — it should keep its position as the user moves between screens.
       def sidebar_index
         session[:sidebar_index] || current_route_index
       end
@@ -52,7 +52,7 @@ module Charming
       def current_route?(candidate)
         return candidate.controller_class == self.class && candidate.action == :show unless route
 
-        candidate.path == route.path &&
+        candidate.name == route.name &&
           candidate.controller_class == route.controller_class &&
           candidate.action == route.action
       end
@@ -139,7 +139,7 @@ module Charming
         route = sidebar_routes[sidebar_index]
         slot = content_slot
         focus.focus(slot) if slot
-        route ? navigate_to(route.path) : render_default_action
+        route ? navigate(route.name) : render_default_action
       end
     end
   end

data/lib/charming/spring.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# ******************************************************************************
+#
+#  Copyright (c) 2008-2012 Ryan Juckett
+#  http://www.ryanjuckett.com/
+#
+#  This software is provided 'as-is', without any express or implied
+#  warranty. In no event will the authors be held liable for any damages
+#  arising from the use of this software.
+#
+#  Permission is granted to anyone to use this software for any purpose,
+#  including commercial applications, and to alter it and redistribute it
+#  freely, subject to the following restrictions:
+#
+#  1. The origin of this software must not be misrepresented; you must not
+#     claim that you wrote the original software. If you use this software
+#     in a product, an acknowledgment in the product documentation would be
+#     appreciated but is not required.
+#
+#  2. Altered source versions must be plainly marked as such, and must not be
+#     misrepresented as being the original software.
+#
+#  3. This notice may not be removed or altered from any source
+#     distribution.
+#
+# ******************************************************************************
+#
+#  Ported to Go by Charmbracelet, Inc. in 2021 (charmbracelet/harmonica, MIT).
+#  Ported to Ruby for Charming in 2026 from charmbracelet/harmonica.
+#
+#  For background on the algorithm see:
+#  https://www.ryanjuckett.com/damped-springs/
+
+module Charming
+  # Spring is a damped harmonic oscillator for physics-based animation. It
+  # precomputes motion coefficients for a fixed time step so each frame update
+  # is four multiply-adds. Instances are immutable; the caller owns position
+  # and velocity (typically as Float attributes on an ApplicationState) and
+  # feeds them back in every frame:
+  #
+  #   SPRING = Charming::Spring.new(delta_time: Charming.fps(60))
+  #   position, velocity = SPRING.update(position, velocity, target)
+  #
+  # The damping ratio shapes the motion: below 1 overshoots and oscillates,
+  # exactly 1 reaches the target as fast as possible without overshooting,
+  # above 1 approaches slower still. Angular frequency scales the speed.
+  class Spring
+    def initialize(delta_time:, angular_frequency: 6.0, damping_ratio: 0.5)
+      angular_frequency = [0.0, angular_frequency].max
+      damping_ratio = [0.0, damping_ratio].max
+      @pos_pos, @pos_vel, @vel_pos, @vel_vel =
+        coefficients(delta_time, angular_frequency, damping_ratio)
+      freeze
+    end
+
+    # Advances one frame toward *target*, returning `[new_position, new_velocity]`.
+    def update(position, velocity, target)
+      relative = position - target
+      [relative * @pos_pos + velocity * @pos_vel + target,
+        relative * @vel_pos + velocity * @vel_vel]
+    end
+
+    # True once the motion has effectively come to rest at *target* — the guard
+    # for stopping an animation timer.
+    def settled?(position, velocity, target, epsilon: 0.01)
+      (position - target).abs < epsilon && velocity.abs < epsilon
+    end
+
+    private
+
+    def coefficients(delta_time, frequency, ratio)
+      return [1.0, 0.0, 0.0, 1.0] if frequency < Float::EPSILON
+
+      if ratio > 1.0 + Float::EPSILON
+        over_damped(delta_time, frequency, ratio)
+      elsif ratio < 1.0 - Float::EPSILON
+        under_damped(delta_time, frequency, ratio)
+      else
+        critically_damped(delta_time, frequency)
+      end
+    end
+
+    def over_damped(delta_time, frequency, ratio)
+      za = -frequency * ratio
+      zb = frequency * Math.sqrt(ratio * ratio - 1.0)
+      z1 = za - zb
+      z2 = za + zb
+      e2 = Math.exp(z2 * delta_time)
+      e1_over_two_zb = Math.exp(z1 * delta_time) / (2.0 * zb)
+      e2_over_two_zb = e2 / (2.0 * zb)
+      z1e1_over_two_zb = z1 * e1_over_two_zb
+      z2e2_over_two_zb = z2 * e2_over_two_zb
+
+      [e1_over_two_zb * z2 - z2e2_over_two_zb + e2,
+        -e1_over_two_zb + e2_over_two_zb,
+        (z1e1_over_two_zb - z2e2_over_two_zb + e2) * z2,
+        -z1e1_over_two_zb + z2e2_over_two_zb]
+    end
+
+    def under_damped(delta_time, frequency, ratio)
+      omega_zeta = frequency * ratio
+      alpha = frequency * Math.sqrt(1.0 - ratio * ratio)
+      exp_term = Math.exp(-omega_zeta * delta_time)
+      exp_sin = exp_term * Math.sin(alpha * delta_time)
+      exp_cos = exp_term * Math.cos(alpha * delta_time)
+      exp_omega_zeta_sin_over_alpha = omega_zeta * exp_sin / alpha
+
+      [exp_cos + exp_omega_zeta_sin_over_alpha,
+        exp_sin / alpha,
+        -exp_sin * alpha - omega_zeta * exp_omega_zeta_sin_over_alpha,
+        exp_cos - exp_omega_zeta_sin_over_alpha]
+    end
+
+    def critically_damped(delta_time, frequency)
+      exp_term = Math.exp(-frequency * delta_time)
+      time_exp = delta_time * exp_term
+      time_exp_freq = time_exp * frequency
+
+      [time_exp_freq + exp_term,
+        time_exp,
+        -frequency * time_exp_freq,
+        -time_exp_freq + exp_term]
+    end
+  end
+end

data/lib/charming/tasks/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Charming
+  module Tasks
+    # Context is the object a task block receives as its argument. It carries the
+    # task's inputs (the `with:` hash given to `run_task`, deep-frozen at submit time)
+    # and the progress reporter:
+    #
+    #   run_task(:search, with: {query: query.value}) do |ctx|
+    #     results = Api.search(ctx[:query])
+    #     ctx.report(1, of: 1)
+    #     results
+    #   end
+    #
+    # 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.
+    class Context
+      def initialize(data, progress)
+        @data = data
+        @progress = progress
+      end
+
+      # Returns the input value for *key* from the `with:` hash.
+      def [](key)
+        @data[key]
+      end
+
+      # Reports progress to the matching `on_task_progress` handler on the loop thread.
+      def report(current, of: nil, message: nil)
+        @progress.report(current, of: of, message: message)
+      end
+    end
+  end
+end

data/lib/charming/test_helper.rb

@@ -18,27 +18,28 @@ module Charming
   #     end
   #
   #     it "quits on q" do
-  #       expect(press(ctrl_class: HomeController, key: "q")).to be_quit
+  #       expect(press(ctrl, "q")).to be_quit
   #     end
   #   end
   #
   # Helpers:
-  # - `build_controller(klass, app:, screen:, route:)` — controller instance wired to an app
+  # - `build_controller(klass, app:, screen:, route:, params:)` — controller instance wired to an app
   # - `key_event("ctrl+p")` — build a KeyEvent from a human-readable string
-  # - `press(controller_or_class, "down")` — dispatch a key press, returns the Response
-  # - `press_sequence(klass, ["down", "down", "enter"], app:)` — dispatch several presses
+  # - `press(controller, "down")` — dispatch a key press at the instance, returns the Response
+  # - `press_sequence(controller, ["down", "down", "enter"])` — dispatch several presses at one instance
   #
   # RSpec matchers (when RSpec is loaded):
   # - `expect(response).to render_text("...")` / `render_match(/.../)`
   # - `expect(response).to be_quit` / `be_navigate` (predicate matchers on Response)
-  # - `expect(response).to navigate_to("/path")`
+  # - `expect(response).to navigate_to(:projects)`
   module TestHelper
-    # Builds a controller instance with sensible test defaults: a fresh Application,
-    # an 80x24 screen, and no event.
-    def build_controller(controller_class, app: nil, screen: nil, route: nil, event: nil)
+    # Builds a controller instance with sensible test defaults: a fresh Application and
+    # an 80x24 screen. Runs the screen_entered lifecycle hook, mirroring the Runtime's
+    # persistent-controller lifecycle.
+    def build_controller(controller_class, app: nil, screen: nil, route: nil, params: {})
       app ||= Charming::Application.new
       screen ||= Charming::Screen.new(width: 80, height: 24)
-      controller_class.new(application: app, event: event, screen: screen, route: route)
+      controller_class.new(application: app, params: params, screen: screen, route: route).tap(&:screen_entered)
     end
 
     # Builds a KeyEvent from a human-readable string like "q", "down", "ctrl+p",
@@ -57,18 +58,16 @@ module Charming
       )
     end
 
-    # Dispatches a single key press against *controller_class* and returns the Response.
-    # Pass `app:` to share session state across presses.
-    def press(controller_class, key, app:, screen: nil, route: nil)
-      controller = build_controller(controller_class, app: app, screen: screen, route: route, event: key_event(key))
-      controller.dispatch_key
+    # Dispatches a single key press at *controller* (an instance from build_controller)
+    # and returns the Response. Accepts a human-readable string or a ready KeyEvent.
+    def press(controller, key)
+      controller.dispatch_key(key.is_a?(String) ? key_event(key) : key)
     end
 
-    # Dispatches each key in *keys* in order against fresh controller instances sharing
-    # *app*'s session (mirroring the runtime's controller-per-event model). Returns the
-    # last Response.
-    def press_sequence(controller_class, keys, app:, screen: nil, route: nil)
-      keys.map { |key| press(controller_class, key, app: app, screen: screen, route: route) }.last
+    # Dispatches each key in *keys* in order at the same controller instance (mirroring
+    # the runtime's persistent-controller model). Returns the last Response.
+    def press_sequence(controller, keys)
+      keys.map { |key| press(controller, key) }.last
     end
 
     # Builds a MemoryBackend pre-seeded with KeyEvents parsed from *keys*, ready to be
@@ -77,6 +76,24 @@ module Charming
       events = keys.map { |key| key.is_a?(String) ? key_event(key) : key }
       Charming::Internal::Terminal::MemoryBackend.new(events: events, width: width, height: height)
     end
+
+    # Renders a view class standalone — no controller needed — and returns a hash with
+    # the painted :frame plus the layout's registration data (:focus_slots,
+    # :mouse_targets). Rendering is pure: registrations only commit when a response
+    # paints, so unit-testing a view means asserting on these artifacts.
+    #
+    #   result = render_view(Home::ShowView, screen: Charming::Screen.new(width: 40, height: 10))
+    #   expect(result[:focus_slots]).to eq([:entries])
+    def render_view(view_class, **assigns)
+      view = view_class.new(**assigns)
+      frame = view.render
+      artifacts = view.render_artifacts
+      {
+        frame: frame,
+        focus_slots: artifacts.last&.focus_slots || [],
+        mouse_targets: artifacts.flat_map(&:mouse_targets)
+      }
+    end
   end
 end
 
@@ -108,13 +125,16 @@ if defined?(RSpec)
     end
   end
 
-  RSpec::Matchers.define :navigate_to do |expected_path|
+  RSpec::Matchers.define :navigate_to do |expected_name, **expected_params|
     match do |response|
-      response.respond_to?(:navigate?) && response.navigate? && response.path == expected_path
+      next false unless response.respond_to?(:navigate?) && response.navigate?
+      next false unless response.name == expected_name.to_sym
+
+      expected_params.empty? || response.params == expected_params
     end
 
     failure_message do |response|
-      "expected a navigation response to #{expected_path.inspect}, got: #{response.inspect}"
+      "expected a navigation response to #{expected_name.inspect}, got: #{response.inspect}"
     end
   end
 end

data/lib/charming/unhandled_component_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when a component emits a result (`[:submitted, value]`, `[:selected, value]`,
+  # or `:cancelled`) and the controller has neither an `on_submit`/`on_select`/`on_cancel`
+  # registration nor a legacy `<slot>_<event>` hook for it. Raised in development and test;
+  # production logs a warning and falls back to the default render instead.
+  class UnhandledComponentEvent < Error; end
+end

data/lib/charming/unknown_slot.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when a rendered layout names a focusable pane, or an `on_*` registration
+  # references a slot, that nothing declares — not a `slot` declaration, not a
+  # `focus_ring` entry, not a same-named method. Raised in development and test;
+  # production logs a warning. The message names the fix and lists declared slots.
+  class UnknownSlot < Error; end
+end

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.3"
+  VERSION = "0.4.0"
 end

data/lib/charming/welcome.rb

@@ -7,7 +7,7 @@ module Charming
   module Welcome
     # The fallback route the Runtime uses when the application has no routes.
     def self.route
-      Router::Route.new(path: "/", controller_class: Controller, action: :show, title: "Welcome", params: {})
+      Router::Route.new(name: :root, controller_class: Controller, action: :show, title: "Welcome", params: {})
     end
   end
 end