charming 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 651009e81e5bb2eb02b2df432b5e399773150691413f2519a6888160b60bd1ca
-  data.tar.gz: 8aa3bf4aebc1abab7890eec9b68791d4ed0fd354cffb982cc40f2cf4f261f70c
+  metadata.gz: fb4da799ae87f28a2495a56dd47dcb049c5b532397993976a5d56fcb2a51a518
+  data.tar.gz: 070767c2b15058ff97db6d4aec1da299f0f8a7df9e249ac323ef9ff1329764ac
 SHA512:
-  metadata.gz: d4276dd6ef588077877b4d4d44758a9c176161fccddd22a5d74161f8615ee38f3c8078872a0ccbca6c8d73e83c994f7e0221f45f75348b9b81bef507a35ff491
-  data.tar.gz: 595008aad5caa6c524e872593b8554b588c8018592aca1ead16820200c31dec67cb1189e338658e902abafa9033612780441ed71bb57bcdb8f296b8f03bbfecc
+  metadata.gz: c4a76d6edd2439e200ea88d1ec13f8be7d4a74974770fd091de041f3f0c03c953edc0ae72b53ca0aed3dd9648f924d3c693d9a696ea5a727d2d351dc6f04e660
+  data.tar.gz: da98baee0f32faa72560af2b6f1f05f80b61996a272739145774103d42d672d536c5b00634082042ee0a3d4d919eb9f53080f2c143ffb1b7d7563d9b7da86b89

data/README.md

@@ -4,7 +4,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, 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
 

data/lib/charming/application.rb

@@ -163,6 +163,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

data/lib/charming/controller/class_methods.rb

@@ -24,10 +24,21 @@ 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:)
+      # 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

data/lib/charming/controller/timers.rb

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

data/lib/charming/controller.rb

@@ -5,7 +5,11 @@ module Charming
   # It provides the action dispatch pipeline, key/command/timer/task bindings, sidebar navigation,
   # command palette management, and view rendering with layout composition.
   class Controller
-    TimerBinding = Data.define(:name, :interval, :action)
+    TimerBinding = Data.define(:name, :interval, :action, :autostart) do
+      def initialize(name:, interval:, action:, autostart: true)
+        super
+      end
+    end
     TaskBinding = Data.define(:name, :action)
 
     extend ClassMethods
@@ -18,6 +22,7 @@ module Charming
     include ComponentDispatching
     include Dispatching
     include Terminal
+    include Timers
 
     attr_reader :application, :event, :params, :screen, :route
 

data/lib/charming/internal/event_loop.rb

@@ -51,6 +51,24 @@ module Charming
         @timers = build_timers(timer_bindings)
       end
 
+      # Schedules *binding* one interval from now. Idempotent: starting a timer
+      # that is already running keeps its current deadline (no phase reset).
+      def start_timer(binding)
+        return if timer_running?(binding.name)
+
+        @timers << {binding: binding, next_at: clock_now + binding.interval}
+      end
+
+      # Removes the named timer from the schedule. Idempotent for unknown names.
+      def stop_timer(name)
+        @timers.reject! { |timer| timer.fetch(:binding).name == name }
+      end
+
+      # True while the named timer is scheduled.
+      def timer_running?(name)
+        @timers.any? { |timer| timer.fetch(:binding).name == name }
+      end
+
       private
 
       # The next due event in priority order: task results, then timers, then input.
@@ -74,13 +92,18 @@ module Charming
       end
 
       # Returns a TimerEvent for the first due timer and advances its next fire
-      # time. Returns nil if no timers are ready or registered.
+      # time. Returns nil if no timers are ready or registered. Rescheduling is
+      # accumulator-based so fire times stay on the interval grid (no drift);
+      # after a stall the deadline snaps forward, skipping missed ticks instead
+      # of firing a catch-up burst.
       def next_timer_event
         timer = due_timer
         return unless timer
 
         now = clock_now
-        timer[:next_at] = now + timer.fetch(:binding).interval
+        interval = timer.fetch(:binding).interval
+        timer[:next_at] += interval
+        timer[:next_at] = now + interval if timer[:next_at] <= now
         Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
       end
 

data/lib/charming/internal/timer_control.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # TimerControl is the runtime-injected surface that lets ephemeral controllers
+    # start and stop the EventLoop's scheduled timers by name (the same pattern as
+    # Application#task_executor). *bindings* is a callable returning the current
+    # route's timer bindings, so navigation needs no re-wiring.
+    class TimerControl
+      def initialize(event_loop:, bindings:)
+        @event_loop = event_loop
+        @bindings = bindings
+      end
+
+      # Schedules the named declared timer on the event loop.
+      def start(name)
+        binding = @bindings.call[name.to_sym]
+        raise ArgumentError, "unknown timer #{name.to_sym.inspect}" unless binding
+
+        @event_loop.start_timer(binding)
+      end
+
+      # Unschedules the named timer.
+      def stop(name)
+        @event_loop.stop_timer(name.to_sym)
+      end
+
+      # True while the named timer is scheduled.
+      def running?(name)
+        @event_loop.timer_running?(name.to_sym)
+      end
+
+      # Null is the default control for applications running outside a Runtime
+      # (unit specs, console): starts and stops are no-ops.
+      class Null
+        def start(name)
+        end
+
+        def stop(name)
+        end
+
+        def running?(name)
+          false
+        end
+      end
+    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/runtime.rb

@@ -20,6 +20,10 @@ module Charming
       @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 }
+      )
     end
 
     # Runs the event loop: enters alt-screen, dispatches incoming events
@@ -52,12 +56,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
@@ -282,7 +292,7 @@ module Charming
       return response unless response.navigate?
 
       @route = resolve_route(response.path)
-      @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
+      @event_loop.reset_timers(autostart_timer_bindings)
       dispatch(@route.action)
     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/version.rb

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

data/lib/charming.rb

@@ -43,6 +43,12 @@ module Charming
     Runtime.new(application, backend: backend).run
   end
 
+  # Returns the seconds-per-frame time delta for a frame rate, for initializing
+  # physics primitives: `Charming::Spring.new(delta_time: Charming.fps(60))`.
+  def self.fps(frames_per_second)
+    1.0 / frames_per_second
+  end
+
   # Returns the normalized key symbol for an event-like object — `event.key` when the object responds
   # to it, otherwise `event.to_sym`. Lets components treat raw strings and KeyEvent objects uniformly.
   def self.key_of(event)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - pando
@@ -206,6 +206,7 @@ files:
 - lib/charming/controller/session_state.rb
 - lib/charming/controller/sidebar_navigation.rb
 - lib/charming/controller/terminal.rb
+- lib/charming/controller/timers.rb
 - lib/charming/database/commands.rb
 - lib/charming/escape.rb
 - lib/charming/events/focus_event.rb
@@ -276,6 +277,7 @@ files:
 - lib/charming/internal/terminal/modified_key_parser.rb
 - lib/charming/internal/terminal/mouse_parser.rb
 - lib/charming/internal/terminal/tty_backend.rb
+- lib/charming/internal/timer_control.rb
 - lib/charming/presentation/component.rb
 - lib/charming/presentation/components/activity_indicator.rb
 - lib/charming/presentation/components/audio.rb
@@ -366,10 +368,12 @@ files:
 - lib/charming/presentation/ui/truncate.rb
 - lib/charming/presentation/ui/width.rb
 - lib/charming/presentation/view.rb
+- lib/charming/projectile.rb
 - lib/charming/response.rb
 - lib/charming/router.rb
 - lib/charming/runtime.rb
 - lib/charming/screen.rb
+- lib/charming/spring.rb
 - lib/charming/tasks/cancelled.rb
 - lib/charming/tasks/inline_executor.rb
 - lib/charming/tasks/progress.rb