charming 0.2.3 → 0.4.0

data/lib/charming/double_render_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when a controller sets the response twice in one dispatch — render, navigate,
+  # and quit each assign the response, and a second assignment would silently discard the
+  # first. The message names the action, the response already set, and the one attempted.
+  class DoubleRenderError < Error; end
+end

data/lib/charming/generators/layout_generator.rb

@@ -99,12 +99,15 @@ module Charming
 
       def controller_chrome
         class_body_block(<<~RUBY)
+          include Charming::Shell::Sidebar
+          include Charming::Shell::Palette
+
           focus_ring :sidebar, :content
 
           key "ctrl+p", :open_command_palette, scope: :global
 
           command "Home" do
-            navigate_to "/"
+            navigate :root
           end
 
           command "Theme", :open_theme_palette

data/lib/charming/generators/migration_generator.rb

@@ -60,7 +60,7 @@ module Charming
 
       # The CamelCase migration class name derived from the snake_case migration name.
       def migration_class_name
-        ActiveSupport::Inflector.camelize(name.snake_name)
+        Internal::Inflections.camelize(name.snake_name)
       end
 
       # Builds the `change` method body based on the migration name convention.

data/lib/charming/generators/model_generator.rb

@@ -103,12 +103,12 @@ module Charming
 
       # The pluralized table name (e.g., "user" → "users", "category" → "categories").
       def table_name
-        ActiveSupport::Inflector.pluralize(name.snake_name)
+        Internal::Inflections.pluralize(name.snake_name)
       end
 
       # The CamelCase migration class name (e.g., "users" → "Users").
       def table_class_name
-        ActiveSupport::Inflector.camelize(table_name)
+        Internal::Inflections.camelize(table_name)
       end
 
       # A migration timestamp in ActiveRecord's filename format, bumped past any

data/lib/charming/generators/name.rb

@@ -21,7 +21,7 @@ module Charming
 
       # The CamelCase class name (e.g., "user" → "User").
       def class_name
-        ActiveSupport::Inflector.camelize(snake_name)
+        Internal::Inflections.camelize(snake_name)
       end
 
       # The controller class name (e.g., "user" → "UserController").

data/lib/charming/generators/screen_generator.rb

@@ -141,14 +141,14 @@ module Charming
 
       # Inserts a `screen` route into `config/routes.rb`, idempotently.
       def insert_route
-        route = %(  screen "/#{name.snake_name}", to: "#{name.snake_name}#show", title: "#{name.class_name}")
+        route = %(  screen :#{name.snake_name}, "#{name.snake_name}#show", title: "#{name.class_name}")
         insert_before_end(route_path, route, "route", "end")
       end
 
       # Inserts a `command` block into `ApplicationController`, idempotently.
       def insert_command
         command = %(    command "#{name.class_name}" do
-      navigate_to "/#{name.snake_name}"
+      navigate :#{name.snake_name}
     end)
         insert_before_end(application_controller_path, command, "command", "  end")
       end

data/lib/charming/generators/view_generator.rb

@@ -40,7 +40,7 @@ module Charming
 
       # CamelCase rendering of the action name (e.g., "user_settings" → "UserSettings").
       def action_class_name
-        ActiveSupport::Inflector.camelize(action)
+        Internal::Inflections.camelize(action)
       end
     end
   end

data/lib/charming/internal/deep_freeze.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # DeepFreeze returns a deep-frozen copy of a value: strings, arrays, hashes, and
+    # sets are duplicated (recursively) and frozen; numbers, symbols, and nil pass
+    # through as-is (already immutable); anything else (IO, models, components) passes
+    # through unfrozen — it has no sane freeze semantics across a thread boundary.
+    # The caller's originals are never frozen.
+    module DeepFreeze
+      # Returns a deep-frozen copy of *value* per the rules above.
+      def self.call(value)
+        case value
+        when Hash then value.to_h { |key, element| [call(key), call(element)] }.freeze
+        when Array then value.map { |element| call(element) }.freeze
+        when Set then value.map { |element| call(element) }.to_set.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/env_inquirer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # A String that answers predicates about its own value:
+    # `EnvInquirer.new("development").development?` → true. Replaces
+    # ActiveSupport::StringInquirer for `Charming.env`.
+    class EnvInquirer < String
+      private
+
+      def method_missing(name, *)
+        return self == name.to_s.delete_suffix("?") if name.end_with?("?")
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        name.end_with?("?") || super
+      end
+    end
+  end
+end

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/inflections.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    # String inflection helpers covering exactly what Charming needs, with
+    # ActiveSupport-compatible semantics for the inputs Charming produces
+    # (snake_case identifiers and "A::B" constant paths). Replaces the former
+    # ActiveSupport::Inflector dependency. `pluralize` implements a deliberate
+    # subset of English rules — enough for conventional resource names — not
+    # ActiveSupport's full inflection table.
+    module Inflections
+      module_function
+
+      # "weather_report" → "WeatherReport"; "admin/users" → "Admin::Users".
+      def camelize(term)
+        string = term.to_s.sub(/\A[a-z\d]*/, &:capitalize)
+        string.gsub(%r{(?:_|(/))([a-z\d]*)}i) { "#{Regexp.last_match(1) && "::"}#{Regexp.last_match(2).capitalize}" }
+      end
+
+      # "HomeController" → "home_controller"; "MyApp::Home" → "my_app/home";
+      # acronym runs get a boundary before a capitalized word ("HTMLTidy" → "html_tidy").
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.gsub("::", "/")
+        word.gsub!(/([A-Z\d]+)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { "#{Regexp.last_match(1) || Regexp.last_match(2)}_" }
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+      # "MyApp::HomeController" → "HomeController".
+      def demodulize(path)
+        path.to_s.split("::").last
+      end
+
+      # "MyApp::Application" → "MyApp"; "Application" → "".
+      def deconstantize(path)
+        path.to_s[0, path.to_s.rindex("::") || 0]
+      end
+
+      # "Charming::Router" → Charming::Router. Raises NameError on a miss.
+      def constantize(name)
+        Object.const_get(name)
+      end
+
+      # "user_name" → "User name"; "author_id" → "Author". Assumes snake_case input.
+      def humanize(lower_case_and_underscored_word)
+        result = lower_case_and_underscored_word.to_s.sub(/_id\z/, "").tr("_", " ")
+        result.sub(/\A\w/, &:upcase)
+      end
+
+      # "category" → "categories"; "person" → "people". A subset of English
+      # rules covering conventional resource names; exotic words may need the
+      # generated migration renamed by hand.
+      def pluralize(word)
+        result = word.to_s.dup
+        return result if UNCOUNTABLE.include?(result)
+
+        irregular = IRREGULAR_FORMS[result.split("_").last]
+        return result.sub(/[^_]+\z/, irregular) if irregular
+
+        PLURAL_RULES.each do |pattern, replacement|
+          return result.sub(pattern, replacement) if result.match?(pattern)
+        end
+        result
+      end
+
+      IRREGULAR_FORMS = {
+        "child" => "children",
+        "man" => "men",
+        "mouse" => "mice",
+        "person" => "people",
+        "sex" => "sexes",
+        "woman" => "women"
+      }.freeze
+
+      UNCOUNTABLE = %w[equipment information money rice series sheep species].freeze
+
+      # Ordered: the first matching rule wins. Mirrors the head of
+      # ActiveSupport's plural rule list for the inputs generators produce.
+      PLURAL_RULES = [
+        [/(quiz)\z/, '\1zes'],
+        [/(matr|vert|ind)(ix|ex)\z/, '\1ices'],
+        [/(x|ch|ss|sh)\z/, '\1es'],
+        [/([^aeiouy]|qu)y\z/, '\1ies'],
+        [/sis\z/, "ses"],
+        [/([ti])um\z/, '\1a'],
+        [/(buffal|tomat|potat|her)o\z/, '\1oes'],
+        [/s\z/, "s"],
+        [/\z/, "s"]
+      ].freeze
+    end
+  end
+end

data/lib/charming/internal/session_guard.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Charming
+  module Internal
+    # SessionGuard wraps the application session hash and asserts every access happens
+    # on the controller's loop thread. Controller#session returns this wrapper in
+    # development and test; production gets the raw hash (a warning is logged instead
+    # of a raise).
+    class SessionGuard < SimpleDelegator
+      def initialize(session, controller)
+        super(session)
+        @controller = controller
+      end
+
+      def method_missing(name, *args, &block)
+        @controller.assert_loop_thread!(:session)
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        __getobj__.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/cursor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # Cursor emits the ANSI escape sequences for cursor visibility, screen clearing,
+      # and positioning. Replaces tty-cursor (a stateless escape-string generator) with
+      # the four sequences TTYBackend actually uses, asserted byte-for-byte in
+      # spec/internal/terminal/cursor_spec.rb.
+      module Cursor
+        module_function
+
+        # Shows the terminal cursor (DECTCEM set).
+        def show = "\e[?25h"
+
+        # Hides the terminal cursor (DECTCEM reset).
+        def hide = "\e[?25l"
+
+        # Clears the whole screen (ED 2).
+        def clear_screen = "\e[2J"
+
+        # Moves the cursor to zero-based *column*/*row* (CUP is one-based row;column).
+        def move_to(column, row)
+          "\e[#{row + 1};#{column + 1}H"
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/size.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # Size detects terminal dimensions without tty-screen: IO#winsize on the first
+      # reporting IO (a TTY), then ENV["COLUMNS"]/ENV["LINES"], then the 80x24 default.
+      module Size
+        DEFAULT_SIZE = [80, 24].freeze
+
+        module_function
+
+        # Returns [width, height] for the first of *ios* that reports a winsize,
+        # falling back to the environment and then the default.
+        def measure(*ios, env: ENV)
+          ios.each do |io|
+            size = winsize(io)
+            return size if size
+          end
+          env_size(env) || DEFAULT_SIZE
+        end
+
+        # IO#winsize reports [rows, columns]; size is [width, height]. Nil for IOs
+        # without a size (StringIO, pipes, closed streams).
+        def winsize(io)
+          return nil unless io.respond_to?(:winsize)
+
+          rows, columns = io.winsize
+          return nil if rows.to_i.zero? || columns.to_i.zero?
+
+          [columns, rows]
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        # The COLUMNS/LINES environment size, or nil when either is unset or zero.
+        def env_size(env)
+          columns = env["COLUMNS"].to_i
+          lines = env["LINES"].to_i
+          return nil if columns.zero? || lines.zero?
+
+          [columns, lines]
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/tty_backend.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-require "tty-cursor"
+require "io/console"
 require "tty-reader"
-require "tty-screen"
 
 module Charming
   module Internal
     module Terminal
       # TTYBackend is the production terminal backend. It reads key and mouse events from
       # a TTY::Reader, normalizes them via KeyNormalizer and MouseParser, and writes output
-      # frames using TTY::Cursor and TTY::Screen. It also installs SIGWINCH and SIGINFO
-      # handlers so the runtime can react to terminal resize and focus changes.
+      # frames using Terminal::Cursor sequences and IO#winsize for dimensions. It also
+      # installs SIGWINCH and SIGINFO handlers so the runtime can react to terminal resize
+      # and focus changes.
       class TTYBackend
         include Adapter
 
@@ -37,8 +37,9 @@ module Charming
 
         # *input* and *output* default to `$stdin`/`$stdout` for normal terminal use;
         # tests can inject IO objects. *reader* is a TTY::Reader instance (created from
-        # *input*/*output* when nil). *cursor* is the TTY::Cursor class used for cursor control.
-        def initialize(input: $stdin, output: $stdout, reader: nil, cursor: TTY::Cursor)
+        # *input*/*output* when nil). *cursor* is the Terminal::Cursor module used for
+        # cursor control sequences.
+        def initialize(input: $stdin, output: $stdout, reader: nil, cursor: Cursor)
           @input = input
           @output = output
           @reader = reader || TTY::Reader.new(input: input, output: output)
@@ -274,8 +275,9 @@ module Charming
           write_control(@cursor.move_to(column - 1, row - 1))
         end
 
-        # Returns the current terminal dimensions as [width, height] via TTY::Screen.
-        def size = [TTY::Screen.width, TTY::Screen.height]
+        # Returns the current terminal dimensions as [width, height]: IO#winsize on the
+        # output/input streams, then COLUMNS/LINES, then 80x24.
+        def size = Size.measure(@output, @input)
 
         private
 

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

@@ -9,8 +9,8 @@ module Charming
     #
     #   Autocomplete.new(suggestions: ["ruby", "rails", "rspec"], value: "r")
     #
-    # `handle_key` returns `[:submitted, value]` on Enter, `:cancelled` on Escape,
-    # `:handled` for consumed keys, nil otherwise.
+    # `handle_key` returns `Result.submitted(value)` on Enter, `Result.cancelled` on
+    # Escape, `Result.handled` for consumed keys, nil otherwise.
     class Autocomplete < Component
       DEFAULT_MAX_SUGGESTIONS = 6
 
@@ -29,6 +29,14 @@ module Charming
         clamp_selection
       end
 
+      # Replaces the suggestion list and reclamps the selection against the filtered
+      # list. Lets a memoized autocomplete stay fresh: keep the component in a slot
+      # and assign `combo.suggestions = names` before each render.
+      def suggestions=(new_suggestions)
+        @suggestions = Array(new_suggestions).map(&:to_s)
+        clamp_selection
+      end
+
       # The typed text.
       def value
         @input.value
@@ -56,8 +64,8 @@ module Charming
       # edits the text (resetting the highlight).
       def handle_key(event)
         case Charming.key_of(event)
-        when :escape then :cancelled
-        when :enter then [:submitted, submission_value]
+        when :escape then Result.cancelled
+        when :enter then Result.submitted(submission_value)
         when :up then move_selection(-1)
         when :down then move_selection(+1)
         else
@@ -100,10 +108,10 @@ module Charming
 
       def move_selection(delta)
         count = filtered_suggestions.length
-        return :handled if count.zero?
+        return Result.handled if count.zero?
 
         @selected_index = (selected_index + delta).clamp(0, count - 1)
-        :handled
+        Result.handled
       end
 
       def clamp_selection

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

@@ -5,7 +5,8 @@ module Charming
     # CommandPalette renders a fuzzy-searchable command picker UI. It wraps a TextInput for search
     # input and a List for result display, dispatching key events between them. Users type to filter
     # the registered commands by label match, navigate with up/down/home/end keys (delegated to List),
-    # confirm a selection with Enter (returns [:selected, command]), or cancel with Escape (returns :cancelled).
+    # confirm a selection with Enter (returns Result.selected(command)), or cancel with Escape (returns
+    # Result.cancelled).
     # State is serializable as a hash of value/cursor/selected_index for session persistence.
     class CommandPalette < Component
       Command = Data.define(:label, :value)
@@ -49,14 +50,14 @@ module Charming
       end
 
       # Handles key events by routing them to the appropriate sub-component: Escape kills the
-      # palette returning :cancelled; up/down/home/end keys go to the List selection handler
+      # palette returning Result.cancelled; up/down/home/end keys go to the List selection handler
       # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
       # which manages cursor position and input filtering. If a list key match fails, falls through
-      # to the TextInput handler. Returns nil/nil if no handler consumed the event, or :cancelled when
-      # Escape is pressed.
+      # to the TextInput handler. Returns nil if no handler consumed the event, or Result.cancelled
+      # when Escape is pressed.
       def handle_key(event)
         key = Charming.key_of(event)
-        return :cancelled if key == :escape
+        return Result.cancelled if key == :escape
 
         return handle_list_key(event) if list_key?(key)
 
@@ -75,17 +76,18 @@ module Charming
       attr_reader :height, :list
 
       # Delegates key handling entirely to the internal List widget, which manages up/down/home/end selection.
-      # Returns whatever the List's handle_key returns (typically nil or the symbol from the subclass).
+      # Returns whatever the List's handle_key returns (a Result or nil).
       def handle_list_key(event)
         list.handle_key(event)
       end
 
       # Passes the key event to the TextInput for cursor position and search text management.
-      # If the input returns :handled, rebuilds the List so that filtering is re-evaluated against
-      # the new input value. Returns nil/nil if no handler consumed the event.
+      # If the input returns Result.handled, rebuilds the List so that filtering is re-evaluated
+      # against the new input value. Returns the input's Result, or nil when it did not consume
+      # the event.
       def handle_input_key(event)
         result = input.handle_key(event)
-        @list = build_list if result == :handled
+        @list = build_list if result&.handled?
         result
       end
 

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

@@ -3,7 +3,7 @@
 module Charming
   module Components
     # Filepicker is a directory browser built on List. Enter descends into the
-    # highlighted directory or returns `[:selected, absolute_path]` for a file;
+    # highlighted directory or returns `Result.selected(absolute_path)` for a file;
     # Backspace (or the "../" entry) goes up, never above the configured root.
     # Dotfiles are hidden until `toggle_hidden`.
     class Filepicker < Component
@@ -63,14 +63,14 @@ module Charming
         return ascend if entry == PARENT_ENTRY
         return descend(entry.delete_suffix("/")) if entry.end_with?("/")
 
-        [:selected, File.join(current_dir, entry)]
+        Result.selected(File.join(current_dir, entry))
       end
 
       # Enters *name* under the current directory.
       def descend(name)
         @current_dir = File.join(current_dir, name)
         rebuild_list
-        :handled
+        Result.handled
       end
 
       # Moves to the parent directory, unless already at the root.
@@ -79,7 +79,7 @@ module Charming
 
         @current_dir = File.dirname(current_dir)
         rebuild_list
-        :handled
+        Result.handled
       end
 
       # Builds a fresh List over the current directory's entries.

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

@@ -16,6 +16,7 @@ module Charming
 
         # Handles the standard confirm keys: space toggles, y/right sets to true, n/left
         # sets to false, and a space character (when the event exposes `char`) also toggles.
+        # Returns Result.handled when consumed, nil otherwise.
         def handle_key(event)
           case Charming.key_of(event)
           when :space
@@ -29,7 +30,7 @@ module Charming
 
             toggle
           end
-          :handled
+          Result.handled
         end
 
         # Returns ["must be accepted"] when required and the value is not true, otherwise

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

@@ -116,7 +116,7 @@ module Charming
 
         # Converts a snake_case symbol/string to a humanized "Capitalized" string.
         def humanize(value)
-          ActiveSupport::Inflector.humanize(value)
+          Internal::Inflections.humanize(value)
         end
       end
     end

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

@@ -25,7 +25,7 @@ module Charming
         end
 
         # Forwards key events to the underlying TextInput, syncing the value and cursor
-        # back into the form state. Returns :handled when the event was consumed.
+        # back into the form state. Returns Result.handled when the event was consumed.
         def handle_key(event)
           forward_to_input(:handle_key, event)
         end
@@ -41,11 +41,11 @@ module Charming
         # the event, persists the resulting value and cursor into the form state.
         def forward_to_input(message, event)
           text_input = input
-          return nil unless text_input.public_send(message, event) == :handled
+          return nil unless text_input.public_send(message, event)&.handled?
 
           state[:values][name] = text_input.value
           field_state[:cursor] = text_input.cursor
-          :handled
+          Result.handled
         end
 
         # The default value for a freshly-bound field is the *value* passed at construction.