charming 0.2.3 → 0.4.0

data/lib/charming/presentation/components/viewport.rb

@@ -62,14 +62,14 @@ module Charming
       end
 
       # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
-      # visible row to the clicked position. Returns :handled on success.
+      # visible row to the clicked position. Returns Result.handled on success.
       def handle_mouse(event)
         return nil unless height
 
         if event.scroll?
           scroll_delta = (event.button_name == :scroll_up) ? -1 : 1
           position.move_to(offset + scroll_delta, bounds)
-          return :handled
+          return Result.handled
         end
 
         return nil unless event.click?
@@ -78,7 +78,7 @@ module Charming
         return nil if clicked_row < 0 || clicked_row >= viewport_height
 
         position.move_to(offset + clicked_row, bounds)
-        :handled
+        Result.handled
       end
 
       private

data/lib/charming/presentation/layout/pane.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module Charming
   module Layout
     # Pane is a leaf layout node: a single rectangle with optional border, padding, and
@@ -7,9 +9,11 @@ module Charming
     # view's context). Panes with a `name` and `behavior.focus: true` are registered as
     # focusable slots in the controller's focus ring.
     class Pane
+      extend Forwardable
+
       attr_reader :name
-      delegate :width, :height, :grow,
-        :min_width, :max_width, :min_height, :max_height, to: :geometry
+      def_delegators :geometry, :width, :height, :grow,
+        :min_width, :max_width, :min_height, :max_height
 
       # *name* is the focus slot identifier. *content* (or a *block*) is the body; *view*
       # is the view used for instance_exec when the block is given. *geometry*, *style*, and

data/lib/charming/presentation/layout/screen_layout.rb

@@ -49,6 +49,13 @@ module Charming
         end
       end
 
+      # Returns the rendered frame plus registration data (focusable pane names, mouse
+      # targets) as RenderArtifacts — the pure-render counterpart to #render that views
+      # use so dispatch, not rendering, commits registrations.
+      def render_with_artifacts
+        RenderArtifacts.new(frame: render, focus_slots: focusable_names, mouse_targets: mouse_targets)
+      end
+
       private
 
       # The screen, background style, the single child, and the list of overlays.

data/lib/charming/presentation/view.rb

@@ -5,11 +5,11 @@ module Charming
   # rendering hooks, layout composition helpers (`row`, `column`, `render_component`, `yield_content`),
   # and access to controller theme, style, and focus state from within views.
   class View
-    # Initializes the view with named assigns injected as instance-local accessor methods via
-    # `define_singleton_method`. Called when a controller instantiates a view for rendering.
+    # Initializes the view with named assigns. Assign keys become private reader
+    # methods via method_missing (see below) — existing methods always win, so a
+    # `title:` assign never shadows a `def title` helper.
     def initialize(**assigns)
       @assigns = assigns
-      define_assign_readers
     end
 
     # Returns all view assigns as a hash, used by layouts to compose the full template (content + screen + controller).
@@ -28,18 +28,28 @@ module Charming
       ctrl ? ctrl.focused?(slot) : false
     end
 
+    # The RenderArtifacts from every screen_layout call in this view's render, in render
+    # order. Internal — the controller's rendering pipeline and TestHelper#render_view
+    # read them; app code should not.
+    def render_artifacts
+      @render_artifacts ||= []
+    end
+
     private
 
     attr_reader :assigns
 
-    # Returns the shared UI style configuration used by components and views for visual rendering (colors, borders).
+    # Builds a fresh Style for inline visual styling (colors, borders, alignment).
+    # Styles are constructed, not read from a shared singleton.
     def style
-      UI.style
+      UI::Style.new
     end
 
-    # Returns the active theme: uses `theme` from assigns or controller, falling back to `UI::Theme.default`.
+    # Returns the active theme as injected: the `theme` assign (the controller's
+    # rendering pipeline always passes one) or the controller's theme. Views and
+    # components take what they're given — there is no ambient fallback.
     def theme
-      assigns[:theme] || assigns[:controller]&.theme || UI::Theme.default
+      assigns[:theme] || assigns[:controller]&.theme
     end
 
     # Outputs styled text through the view's rendering pipeline. Accepts a named `style:` for inline formatting.
@@ -80,11 +90,15 @@ module Charming
     end
 
     # Builds a declarative layout tree for the current terminal screen and renders it.
+    # The layout's registration data (focusable panes, mouse targets) is stashed on the
+    # view as RenderArtifacts — the dispatch pipeline commits them when the response
+    # paints, so rendering never mutates the controller. Several screen_layout calls in
+    # one render accumulate in order.
     def screen_layout(background: nil, &)
       layout = Layout::Builder.build(screen: layout_screen, view: self, background: background, &)
-      register_layout_focus(layout)
-      register_layout_mouse_targets(layout)
-      layout.render
+      artifacts = layout.render_with_artifacts
+      render_artifacts << artifacts
+      artifacts.frame
     end
 
     # Yields the layout's `content` slot — used by view templates to inject their body into a layout wrapper (e.g., sidebar).
@@ -113,30 +127,22 @@ module Charming
       style_object ? style_object.render(value) : value
     end
 
-    # Dynamically defines read-only accessor methods for each assign key as singleton methods on self.
-    # Skips keys where the view already responds (controller methods take precedence).
-    def define_assign_readers
-      assigns.each_key do |name|
-        next if respond_to?(name, true)
+    # Resolves assign keys as zero-argument private readers. Real methods take
+    # precedence (method_missing only fires when nothing defined the message).
+    def method_missing(name, *args, &block)
+      return assigns.fetch(name) if args.empty? && block.nil? && assigns.key?(name)
 
-        define_singleton_method(name) { assigns.fetch(name) }
-      end
-    end
-
-    def layout_screen
-      assigns[:screen] || assigns[:controller]&.screen || Charming::Screen.new(width: 80, height: 24)
+      super
     end
 
-    def register_layout_focus(layout)
-      return unless assigns[:controller]
-
-      assigns[:controller].focus.define_layout(layout.focusable_names)
+    # Lets `respond_to?` answer true for assign names, matching the readers
+    # method_missing provides.
+    def respond_to_missing?(name, include_private = false)
+      assigns.key?(name) || super
     end
 
-    def register_layout_mouse_targets(layout)
-      return unless assigns[:controller]
-
-      assigns[:controller].register_mouse_targets(layout.mouse_targets)
+    def layout_screen
+      assigns[:screen] || assigns[:controller]&.screen || Charming::Screen.new(width: 80, height: 24)
     end
   end
 end

data/lib/charming/projectile.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Charming
+  # Projectile is simple physics motion for games: a position advanced by a
+  # velocity, and a velocity advanced by an acceleration (typically gravity),
+  # one fixed time step per frame (semi-implicit Euler, matching
+  # charmbracelet/harmonica's projectile):
+  #
+  #   ball = Charming::Projectile.new(
+  #     delta_time: Charming.fps(60),
+  #     position: Charming::Projectile::Point.new(x: 0.0, y: 0.0),
+  #     velocity: Charming::Projectile::Vector.new(x: 20.0, y: 0.0),
+  #     acceleration: Charming::Projectile::TERMINAL_GRAVITY
+  #   )
+  #   position = ball.update  # each frame
+  class Projectile
+    Point = Data.define(:x, :y, :z) do
+      def initialize(x:, y:, z: 0.0)
+        super
+      end
+    end
+
+    Vector = Data.define(:x, :y, :z) do
+      def initialize(x:, y:, z: 0.0)
+        super
+      end
+    end
+
+    # Gravity for a coordinate plane whose origin is bottom-left (y grows upward).
+    GRAVITY = Vector.new(x: 0.0, y: -9.81)
+
+    # Gravity for terminal coordinates, whose origin is top-left (y grows downward).
+    TERMINAL_GRAVITY = Vector.new(x: 0.0, y: 9.81)
+
+    attr_reader :position, :velocity, :acceleration
+
+    def initialize(delta_time:, position:, velocity: Vector.new(x: 0.0, y: 0.0), acceleration: Vector.new(x: 0.0, y: 0.0))
+      @delta_time = delta_time
+      @position = position
+      @velocity = velocity
+      @acceleration = acceleration
+    end
+
+    # Advances one frame and returns the new position. Position moves by the
+    # current velocity before the velocity accelerates — keep this order.
+    def update
+      @position = shift(position, velocity)
+      @velocity = shift(velocity, acceleration)
+      position
+    end
+
+    private
+
+    attr_reader :delta_time
+
+    def shift(value, rate)
+      value.with(
+        x: value.x + rate.x * delta_time,
+        y: value.y + rate.y * delta_time,
+        z: value.z + rate.z * delta_time
+      )
+    end
+  end
+end

data/lib/charming/render_artifacts.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Charming
+  # RenderArtifacts is what a pure view render produces: the painted *frame* string plus
+  # the registration data the frame implies — *focus_slots* (focusable layout pane
+  # names) and *mouse_targets* (named pane hit areas). Views stash them instead of
+  # mutating the controller mid-render; the dispatch pipeline commits them when the
+  # response actually paints.
+  RenderArtifacts = Data.define(:frame, :focus_slots, :mouse_targets) do
+    def initialize(frame: "", focus_slots: [], mouse_targets: [])
+      super
+    end
+
+    # Merges several layouts' artifacts from one render: the last-rendered layout wins
+    # for focus, and mouse targets concatenate in render order (overlays hit-test
+    # last-wins via rfind).
+    def self.merge(artifacts)
+      new(
+        focus_slots: artifacts.last&.focus_slots || [],
+        mouse_targets: artifacts.flat_map(&:mouse_targets)
+      )
+    end
+  end
+end

data/lib/charming/response.rb

@@ -1,31 +1,42 @@
 # frozen_string_literal: true
 
 module Charming
-  # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another route, or quit.
+  # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another screen, or quit.
   # Rails-style factories (`render`, `navigate`, `quit`) serve as the public API and map to :kind values
   # that the Runtime interprets at the end of each event loop iteration.
   #
   # *escapes* carries any out-of-band terminal sequences (image transmissions, clipboard writes,
   # notifications, window-title changes) gathered during the dispatch. The Runtime flushes them straight
   # to the backend, bypassing the line-based frame pipeline. It is empty for ordinary responses.
-  Response = Data.define(:kind, :body, :path, :escapes) do
+  #
+  # *artifacts* carries the merged RenderArtifacts (focus slots, mouse targets) from the views
+  # rendered during the dispatch, attached when the response is assigned. The dispatch pipeline
+  # commits them at dispatch exit; nil for navigate/quit responses and renders with no layout.
+  Response = Data.define(:kind, :body, :name, :params, :escapes, :artifacts) do
     # Factory constructing a Render response for displaying *body* text on the current screen. *escapes*
     # is the list of out-of-band sequences gathered during the dispatch (defaults to none).
     def self.render(body, escapes: [])
-      new(kind: :render, body: body, path: nil, escapes: escapes)
+      new(kind: :render, body: body, name: nil, params: {}, escapes: escapes, artifacts: nil)
     end
 
-    # Factory constructing a NavigateResponse routing to the named *path* (string).
-    def self.navigate(path)
-      new(kind: :navigate, body: "", path: path, escapes: [])
+    # Factory constructing a NavigateResponse routing to the screen registered under *name*
+    # (a Symbol from config/routes.rb), passing *params* through to the controller.
+    def self.navigate(name, **params)
+      if name.is_a?(String) && name.start_with?("/")
+        suggestion = name.split("/")[1].to_s.delete_prefix(":")
+        raise ArgumentError,
+          "String URL paths were removed. Use `navigate :#{suggestion}` with a screen name from config/routes.rb. See UPGRADING.md."
+      end
+
+      new(kind: :navigate, body: "", name: name.to_sym, params: params, escapes: [], artifacts: nil)
     end
 
     # Factory constructing a QuitResponse signalling termination of the top-level event loop.
     def self.quit
-      new(kind: :quit, body: "", path: nil, escapes: [])
+      new(kind: :quit, body: "", name: nil, params: {}, escapes: [], artifacts: nil)
     end
 
-    # Returns `true` when this response is navigating to another screen or route.
+    # Returns `true` when this response is navigating to another screen.
     def navigate?
       kind == :navigate
     end

data/lib/charming/router.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require "uri"
-
 module Charming
-  # Router manages an application's route table and provides a Rails-inspired DSL for defining routes.
-  # Each route maps a URL path to a controller, action (implicitly :show), and title (for sidebar display).
+  # Router manages an application's screen table and provides a Rails-inspired DSL for
+  # defining screens. Each screen maps a symbolic name to a controller, an action
+  # (implicitly :show), and a title (for sidebar display). Navigation passes params
+  # directly — there are no URL path templates.
   class Router
-    # Route is a Data object holding a route's path template, target controller/action, title, and resolved params.
-    Route = Data.define(:path, :controller_class, :action, :title, :params) do
+    # Route is a Data object holding a screen's name, target controller/action, title,
+    # and resolved params.
+    Route = Data.define(:name, :controller_class, :action, :title, :params) do
       def with_params(params)
         self.class.new(
-          path: path,
+          name: name,
           controller_class: controller_class,
           action: action,
           title: title,
@@ -19,48 +20,48 @@ module Charming
       end
     end
 
-    DynamicRoute = Data.define(:route, :pattern, :param_names)
-
     # Initializes a new router with an optional namespace prefix for controller constant lookups.
     def initialize(namespace: nil)
       @namespace = namespace
       @routes = {}
-      @dynamic_routes = []
     end
 
-    # Evaluates a block in the context of this Router instance using instance_eval, allowing DSL calls like screen and root to register routes.
-    # This is how `routes.draw { screen "/", to: "HomeController", title: "Home" }` works.
+    # Evaluates a block in the context of this Router instance using instance_eval, allowing DSL
+    # calls like screen and root to register routes.
+    # This is how `routes.draw { root "home#show" }` works.
     def draw(&)
       instance_eval(&)
     end
 
-    # Registers the home screen at "/" with a given title. Shorthand for `screen path, to: target`.
-    # Example: `root "HomeController"` maps `/` → HomeController#show with title "Home".
+    # Registers the home screen under the reserved name :root.
+    # Example: `root "home#show"` maps :root → HomeController#show with title "Home".
     def root(target, title: "Home")
-      screen("/", to: target, title: title)
+      screen(:root, target, title: title)
     end
 
-    # Maps a URL path to a controller and action (e.g. "HomeController" for HomeController#show).
-    # Builds a Route object from the path, resolved controller constant, parsed action, and an optional or derived title.
-    def screen(path, to:, title: nil)
-      controller_name, action = to.split("#", 2)
-      route = Route.new(
-        path: path,
+    # Maps a symbolic *name* to a controller and action (e.g. "home#show" for
+    # HomeController#show; the action defaults to :show). *title* defaults to a
+    # humanized form of the name.
+    def screen(name, target = nil, title: nil, to: nil)
+      name = screen_name(name)
+      target ||= to or raise ArgumentError, "screen :#{name} needs a target like \"home#show\""
+      controller_name, action = target.split("#", 2)
+      @routes[name] = Route.new(
+        name: name,
         controller_class: constantize(controller_constant_name(controller_name)),
         action: (action || "show").to_sym,
-        title: title || derive_title(path),
+        title: title || derive_title(name),
         params: {}
       )
-      @routes[path] = route
-      @dynamic_routes.reject! { |dynamic_route| dynamic_route.route.path == path }
-      @dynamic_routes << compile_dynamic_route(route) if dynamic_path?(path)
     end
 
-    # Resolves a route by path from the router's table. Exact routes win over dynamic routes.
-    # Raises KeyError if no route matches.
-    # Used at runtime to look up the controller class and action for incoming requests.
-    def resolve(path = "/")
-      @routes[path] || resolve_dynamic(path) || raise(KeyError, "key not found: #{path.inspect}")
+    # Resolves a screen by name, returning the route with *params* attached. Raises
+    # KeyError listing the registered names when no screen matches. Used at runtime to
+    # look up the controller class and action for navigation.
+    def resolve(name = :root, params = {})
+      @routes.fetch(name.to_sym) do
+        raise KeyError, "unknown screen #{name.inspect} (registered screens: #{@routes.keys.map(&:inspect).join(", ")})"
+      end.with_params(params)
     end
 
     # Returns all registered routes as Route objects, ordered by insertion.
@@ -75,58 +76,39 @@ module Charming
     # For example, namespace "Admin" means HomeController resolves as Admin::HomeController.
     attr_reader :namespace
 
-    def dynamic_path?(path)
-      path.split("/").any? { |segment| segment.start_with?(":") && segment.length > 1 }
-    end
+    # Normalizes a screen name to a Symbol, rejecting legacy string URL paths with a
+    # migration hint.
+    def screen_name(name)
+      return name if name.is_a?(Symbol)
+      raise ArgumentError, string_path_hint(name, "screen") if name.is_a?(String) && name.start_with?("/")
 
-    def compile_dynamic_route(route)
-      param_names = []
-      segments = route.path.split("/", -1).map do |segment|
-        if segment.start_with?(":") && segment.length > 1
-          param_names << segment.delete_prefix(":").to_sym
-          "([^/]+)"
-        else
-          Regexp.escape(segment)
-        end
-      end
-
-      DynamicRoute.new(route: route, pattern: /\A#{segments.join("/")}\z/, param_names: param_names)
-    end
-
-    def resolve_dynamic(path)
-      @dynamic_routes.each do |dynamic_route|
-        match = dynamic_route.pattern.match(path)
-        return dynamic_route.route.with_params(extract_params(dynamic_route.param_names, match.captures)) if match
-      end
-
-      nil
-    end
-
-    def extract_params(names, values)
-      names.zip(values).to_h do |name, value|
-        [name, URI.decode_www_form_component(value)]
-      end
+      name.to_sym
     end
 
     # Looks up a constant by name in Object. Used to resolve controller strings from route definitions.
     def constantize(name)
-      ActiveSupport::Inflector.constantize(name)
+      Internal::Inflections.constantize(name)
     end
 
     # Builds the full controller constant name, prepending the namespace if present.
     # For example: "home" with namespace "Admin" → "Admin::HomeController".
     def controller_constant_name(controller_name)
-      name = "#{ActiveSupport::Inflector.camelize(controller_name)}Controller"
+      name = "#{Internal::Inflections.camelize(controller_name)}Controller"
       @namespace.to_s.empty? ? name : "#{@namespace}::#{name}"
     end
 
-    # Derives a human-readable title from a URL path by stripping the leading slash,
-    # splitting on underscores/hyphens/slashes, capitalizing each segment, and joining with spaces.
-    # Examples: "/projects" → "Projects", "/projects/list" → "Projects List".
-    def derive_title(path)
-      return "Home" if path == "/"
+    # Derives a human-readable title from a screen name by splitting on underscores and
+    # hyphens, capitalizing each segment, and joining with spaces.
+    # Example: :project_list → "Project List".
+    def derive_title(name)
+      name.to_s.split(/[_-]/).map(&:capitalize).join(" ")
+    end
 
-      path.delete_prefix("/").split(%r{[_\-/]}).map(&:capitalize).join(" ")
+    # The error message for callers still passing string URL paths.
+    def string_path_hint(path, dsl)
+      suggestion = path.split("/")[1].to_s.delete_prefix(":")
+      "String URL paths were removed. Register screens by name — `#{dsl} :#{suggestion}, ...` — " \
+        "and navigate with `navigate :#{suggestion}`. See UPGRADING.md."
     end
   end
 end