charming 0.2.2 → 0.3.0

data/lib/charming/generators/templates/app/routes.template

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 __APP_CLASS__::Application.routes do
-  root "home#show"
+  # Generate your first screen with `charming generate screen NAME`, then make it home:
+  #
+  #   root "home#show"
 end

data/lib/charming/generators/templates/layout/sidebar/application_layout.rb.template

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  module Layouts
+    class ApplicationLayout < Charming::View
+      def render
+        screen_layout(background: theme.background) do
+          split(narrow? ? :vertical : :horizontal, gap: 1) do
+            pane(:sidebar, **sidebar_options, border: :rounded, padding: [1, 2], style: sidebar_style) do
+              column(app_title, navigation, shortcuts, gap: 1)
+            end
+
+            pane(:content, grow: 1, border: :rounded, padding: [1, 2], style: content_style) do
+              yield_content
+            end
+          end
+
+          overlay command_palette_modal if command_palette_modal
+        end
+      end
+
+      private
+
+      def palette_component
+        assigns.fetch(:palette, nil)
+      end
+
+      def narrow?
+        screen.narrow?(below: 72, min_height: 20)
+      end
+
+      def sidebar_options
+        narrow? ? {height: [screen.height / 3, 5].max} : {width: 22}
+      end
+
+      def sidebar_inner_width
+        narrow? ? [screen.width - 6, 20].max : 16
+      end
+
+      def app_title
+        text "__APP_NAME__", style: theme.header_accent.align(:center).width(sidebar_inner_width)
+      end
+
+      def navigation
+        column(*nav_items)
+      end
+
+      def nav_items
+        controller.sidebar_routes.each_with_index.map do |route, index|
+          text nav_item_label(route, index), style: nav_item_style(route, index)
+        end
+      end
+
+      def nav_item_label(route, index)
+        cursor = (sidebar_focused? && index == sidebar_index) ? ">" : " "
+        active = current_route?(route) ? "\u{25cf}" : " "
+        "#{cursor} #{active} #{route.title}"
+      end
+
+      def nav_item_style(route, index)
+        if sidebar_focused? && index == sidebar_index
+          theme.selected
+        elsif current_route?(route)
+          theme.title
+        else
+          theme.muted
+        end
+      end
+
+      def shortcuts
+        text "tab focus\nctrl+p commands\nq quit", style: theme.muted
+      end
+
+      def sidebar_style
+        focused_style = sidebar_focused? ? theme.title : theme.border
+        palette_component ? focused_style.faint : focused_style
+      end
+
+      def content_style
+        focused_style = content_focused? ? theme.title : theme.border
+        palette_component ? focused_style.faint : focused_style
+      end
+
+      def command_palette_modal
+        return unless palette_component
+
+        render_component Charming::Components::CommandPaletteModal.new(
+          content: palette_component,
+          theme: theme
+        )
+      end
+
+      def sidebar_focused?
+        controller.sidebar_focused?
+      end
+
+      def content_focused?
+        controller.content_focused?
+      end
+
+      def sidebar_index
+        controller.sidebar_index
+      end
+
+      def current_route?(route)
+        controller.current_route?(route)
+      end
+    end
+  end
+end

data/lib/charming/image/protocol/kitty.rb

@@ -82,6 +82,13 @@ module Charming
           end.join("\n")
         end
 
+        # Builds the `a=d,d=I` escape that deletes *image_id*'s placements AND frees its data from
+        # terminal memory (lowercase `d=i` would keep the data resident). Long-lived apps that cycle
+        # many images must emit this when evicting, or the terminal's image storage grows unbounded.
+        def delete(image_id:)
+          "\e_Ga=d,d=I,i=#{image_id},q=2\e\\"
+        end
+
         # The chunked `a=t` (transmit) escapes carrying the base64 PNG data directly (`f=100,t=d`).
         # Control keys ride only the first chunk; `m=1` flags more-to-come, `m=0` the last.
         def transmit_image(image_id, png_bytes)

data/lib/charming/image/source.rb

@@ -53,6 +53,16 @@ module Charming
         protocol.placeholder_block(image_id: image_id, rows: rows, cols: cols)
       end
 
+      # Builds the out-of-band {Transmit} that frees the image from terminal memory, or nil when
+      # graphics are unsupported. Re-arms {transmitted?} so a later render retransmits. Callers
+      # evicting an image register this the same way as {transmit}.
+      def release
+        return unless protocol
+
+        @transmitted = false
+        Transmit.new(image_id: image_id, payload: protocol.delete(image_id: image_id))
+      end
+
       # True once {mark_transmitted} has recorded that the image was sent to the terminal.
       def transmitted?
         @transmitted

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/presentation/components/autocomplete.rb

@@ -67,6 +67,13 @@ module Charming
         end
       end
 
+      # Forwards pasted text to the inner input and re-filters the suggestions.
+      def handle_paste(event)
+        result = @input.handle_paste(event)
+        clamp_selection if result
+        result
+      end
+
       # Renders the input row followed by the suggestion dropdown.
       def render
         [input_line, *suggestion_lines].join("\n")

data/lib/charming/presentation/components/form/field.rb

@@ -41,6 +41,11 @@ module Charming
           nil
         end
 
+        # Default paste handler returns nil (paste ignored). Text fields override.
+        def handle_paste(_event)
+          nil
+        end
+
         # Renders the field as a control line prefixed with ">" (active) or " " (inactive),
         # optionally followed by the help line and any error lines.
         def render(active: false)

data/lib/charming/presentation/components/form/input.rb

@@ -27,17 +27,27 @@ module Charming
         # Forwards key events to the underlying TextInput, syncing the value and cursor
         # back into the form state. Returns :handled when the event was consumed.
         def handle_key(event)
+          forward_to_input(:handle_key, event)
+        end
+
+        # Forwards pasted text to the underlying TextInput the same way.
+        def handle_paste(event)
+          forward_to_input(:handle_paste, event)
+        end
+
+        private
+
+        # Sends *message* to a freshly-built TextInput and, when the widget consumed
+        # the event, persists the resulting value and cursor into the form state.
+        def forward_to_input(message, event)
           text_input = input
-          result = text_input.handle_key(event)
-          return nil unless result == :handled
+          return nil unless text_input.public_send(message, event) == :handled
 
           state[:values][name] = text_input.value
           field_state[:cursor] = text_input.cursor
           :handled
         end
 
-        private
-
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

data/lib/charming/presentation/components/form/textarea.rb

@@ -29,15 +29,12 @@ module Charming
         # Forwards key events to the underlying TextArea, syncing the value, cursor, offset,
         # and preferred column back into the form state. Returns :handled when consumed.
         def handle_key(event)
-          area = text_area
-          result = area.handle_key(event)
-          return nil unless result == :handled
+          forward_to_text_area(:handle_key, event)
+        end
 
-          state[:values][name] = area.value
-          field_state[:cursor] = area.cursor
-          field_state[:offset] = area.offset
-          field_state[:preferred_column] = area.preferred_column
-          :handled
+        # Forwards pasted text (newlines preserved) to the underlying TextArea the same way.
+        def handle_paste(event)
+          forward_to_text_area(:handle_paste, event)
         end
 
         # Renders the field with its label on the first line, body lines indented, and
@@ -50,6 +47,19 @@ module Charming
 
         private
 
+        # Sends *message* to a freshly-built TextArea and, when the widget consumed the
+        # event, persists the value, cursor, offset, and preferred column into form state.
+        def forward_to_text_area(message, event)
+          area = text_area
+          return nil unless area.public_send(message, event) == :handled
+
+          state[:values][name] = area.value
+          field_state[:cursor] = area.cursor
+          field_state[:offset] = area.offset
+          field_state[:preferred_column] = area.preferred_column
+          :handled
+        end
+
         # The default value for a freshly-bound field is the *value* passed at construction.
         def default_value
           @initial_value

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

@@ -38,6 +38,12 @@ module Charming
         advance_or_submit if key == :enter
       end
 
+      # Forwards pasted text to the currently focused field. Text fields insert it
+      # at their cursor; other fields ignore it.
+      def handle_paste(event)
+        current_field&.handle_paste(event)
+      end
+
       # Forms accept free-typed text (their input/textarea fields do), so printable
       # characters route here before global/content key bindings.
       def captures_text?

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

@@ -39,8 +39,8 @@ module Charming
         result
       end
 
-      # Renders the modal as a bordered, padded string with the title and help lines stacked
-      # above the content.
+      # Renders the modal as a bordered, padded string with the title above the content
+      # and the help footer below it.
       def render
         box(column(*lines, gap: 1), style: modal_style)
       end
@@ -49,9 +49,9 @@ module Charming
 
       attr_reader :content, :title, :help, :width
 
-      # Returns the array of non-nil lines: title, help, content.
+      # Returns the array of non-nil lines: title, content, help footer.
       def lines
-        [title_line, help_line, body_content].compact
+        [title_line, body_content, help_line].compact
       end
 
       # The body: windowed through a Viewport when scrollable, otherwise rendered directly.

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

@@ -34,7 +34,7 @@ module Charming
 
       # Adds *seconds* (default 1) when running; a no-op otherwise. Returns self.
       def tick(seconds = 1)
-        @elapsed += seconds.to_i if running?
+        @elapsed += seconds if running?
         self
       end
 

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

@@ -8,7 +8,7 @@ module Charming
     # for long buffers. Vertical movement preserves a "preferred column" so left/right
     # navigation feels stable.
     class TextArea < Component
-      # The current text value, cursor byte offset, top-visible row offset, and remembered
+      # The current text value, cursor character offset, top-visible row offset, and remembered
       # column for vertical navigation, respectively.
       attr_reader :value, :cursor, :offset, :preferred_column
 
@@ -212,7 +212,7 @@ module Charming
         [row, column]
       end
 
-      # Returns the byte offset where line *row* begins in the value.
+      # Returns the character offset where line *row* begins in the value.
       def line_start(row)
         lines.first(row).sum(&:length) + row
       end

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

@@ -25,7 +25,7 @@ module Charming
         delete: :delete_at_cursor
       }.freeze
 
-      # The current input string and the byte offset of the cursor within it.
+      # The current input string and the character offset of the cursor within it.
       attr_reader :value, :cursor
 
       # *value* is the initial text. *placeholder* is shown when the value is empty.
@@ -94,7 +94,7 @@ module Charming
         !char.match?(/[[:cntrl:]]/)
       end
 
-      # Inserts *char* at the cursor and advances the cursor by its byte length.
+      # Inserts *char* at the cursor and advances the cursor by its character length.
       def insert(char)
         @value = value[0...cursor] + char + value[cursor..]
         @cursor += char.length

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

@@ -18,7 +18,7 @@ module Charming
 
       # Counts down by *seconds* (default 1), clamping at zero. Returns self.
       def tick(seconds = 1)
-        @remaining = [@remaining - seconds.to_i, 0].max
+        @remaining = [@remaining - seconds, 0].max
         self
       end
 

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

@@ -3,9 +3,10 @@
 module Charming
   module Components
     # Toast is a small auto-dismissing notification panel, usually composited as an
-    # overlay anchored to a screen corner. Controllers manage its lifetime with the
-    # `show_toast` / `dismiss_toast` helpers (which pair it with a timer); the component
-    # itself just renders the styled box.
+    # overlay anchored to a screen corner. The component just renders the styled box;
+    # apps manage its lifetime themselves — typically a session-backed hash with an
+    # expiry deadline plus a controller timer that clears it (see the journal example's
+    # ApplicationController#show_toast / #expire_toast).
     #
     #   Toast.new(message: "Saved!", kind: :success)
     #

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

@@ -25,7 +25,10 @@ module Charming
       # *content* may be a string, an array of lines, or any object responding to `render`.
       # *width* and *height* constrain the visible window; *offset* is the top-visible row
       # and *column* is the left-visible column. *wrap* enables soft-wrapping of long lines.
-      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
+      # *follow* pins the viewport to the bottom of the content regardless of *offset*, so
+      # callers that rebuild each event stick to new content; pair with `at_bottom?` to
+      # decide whether to keep following after the user scrolls.
+      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim, follow: false)
         super()
         @content = content
         @width = width
@@ -34,6 +37,7 @@ module Charming
         @wrap = wrap
         @keymap = keymap
         position.clamp(bounds)
+        position.move_to(max_offset, bounds) if follow
       end
 
       # Renders the visible window of content as a multi-line string.
@@ -51,6 +55,12 @@ module Charming
         @position.column
       end
 
+      # True when the last content row is visible. Callers persisting follow mode
+      # store this after key dispatch to decide whether the next build follows.
+      def at_bottom?
+        offset >= max_offset
+      end
+
       # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
       # visible row to the clicked position. Returns :handled on success.
       def handle_mouse(event)

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

@@ -16,10 +16,14 @@ module Charming
       @task_queue = Thread::Queue.new
       @task_executor = build_task_executor(task_executor)
       @application.task_executor = @task_executor
-      @route = @application.routes.resolve("/")
+      @route = resolve_route("/")
       @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
@@ -281,11 +291,22 @@ module Charming
     def resolve_response(response)
       return response unless response.navigate?
 
-      @route = @application.routes.resolve(response.path)
-      @event_loop.reset_timers(@route.controller_class.timer_bindings.values)
+      @route = resolve_route(response.path)
+      @event_loop.reset_timers(autostart_timer_bindings)
       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)
+    rescue KeyError
+      raise unless path == "/"
+
+      @application.routes.all.first || Welcome.route
+    end
+
     # Derives Screen dimensions (width, height) from the terminal backend.
     def backend_screen
       width, height = @backend.size