rooibos 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b78b8c6fabd42cda3c443da5f6487f043f33190ac7bb8d2190add134d154be
-  data.tar.gz: 790da4bb69ca1f711fe3ae5dc41c09f18d88db4986258716db7b6db6060e21a3
+  metadata.gz: f0bd248d3b6933a881c6a2dc2e01eff42ecf20ae9b8547237f216de1ba3fcc54
+  data.tar.gz: ef8473cff78d86f01022ae554b9a60bf7fdadbfd8528d499cd59ccc592ce5a2a
 SHA512:
-  metadata.gz: d306617ae1c2532c8bd105941beea50d4715840c0a087ec0199863e5ea089f7db1cdb9e9dea2a1921dec4b783c9f953963fe89f2a41d981101cc751b0ac518bf
-  data.tar.gz: 483be60cb25f8025bf222d8e63ba5d784695678aac93d883a0fa9ac83ba53832103e4f3c6be5b3908509d3b6b1f0d3572afa83de77e30398a12e7a56a9b25497
+  metadata.gz: e3dbe609e9423b3e7e9335c72da14e3eca798d4083baf6f7c17761eeb7f42267bd68d391e6e0102d225f9c3f7e4fc1799221547440baa2d5f9c28beed96ac5b8
+  data.tar.gz: 49d737453d32dc06193baf1b529270938ae8861afcf9f2e5c1faef0a6a04b594d2cd8d63dfb4892c51b2b64b5e06c52c3dbbb260daaa7184a961d0969ca26b39

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - rooibos/pkg/rooibos-0.6.1.gem
+  - rooibos/pkg/rooibos-0.6.2.gem
 sources:
   - https://git.sr.ht/~kerrick/rooibos
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - rooibos/pkg/rooibos-0.6.1.gem
+  - rooibos/pkg/rooibos-0.6.2.gem
 sources:
   - https://git.sr.ht/~kerrick/rooibos
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - rooibos/pkg/rooibos-0.6.1.gem
+  - rooibos/pkg/rooibos-0.6.2.gem
 sources:
   - https://git.sr.ht/~kerrick/rooibos
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - rooibos/pkg/rooibos-0.6.1.gem
+  - rooibos/pkg/rooibos-0.6.2.gem
 sources:
   - https://git.sr.ht/~kerrick/rooibos
 tasks:

data/CHANGELOG.md

@@ -21,6 +21,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.6.2] - 2026-01-27
+
+### Added
+
+- **Router `action` DSL Enhancements**: Multiple syntax forms for declaring actions with inline keybindings:
+  - Positional: `action :quit, -> { Command.exit }` (original)
+  - Keyword: `action quit: -> { Command.exit }` (cleaner)
+  - Inline keymap: `action quit: -> { Command.exit }, keymap: %i[ctrl_c q]`
+  - `key:` singular alias: `action go_home: FileList, key: :~`
+  - `keys:` plural alias: `action move_down: FileList, keys: %i[down j]`
+  - Anonymous: `action -> { Command.exit }, keymap: %i[ctrl_c q]` (no name, just binding)
+  - `mousemap:` for scroll bindings: `action scroll_up: ..., mousemap: %i[scroll_up]`
+
+- **Routed Actions**: Actions can now target child fragments. When the value is a `Module`, the Router synthesizes a `Message::Routed` and dispatches to the child's Update:
+  - `action move_down: FileList` — declares `FileList` as target
+  - Key presses trigger `Message::Routed.new(envelope: :move_down, event: key_event)`
+
+- **Message::Routed**: New message type for routed actions between parent and child fragments:
+  - `deconstruct_keys` returns `{ type: :routed, envelope:, event: }`
+  - Predicate methods via `method_missing`: `msg.move_down?`, `msg.go_back?`
+  - Carries original event for full context in child Update
+
+- **Keymap `key` DSL Enhancements**: Multiple syntax forms for declaring key handlers:
+  - Variadic keys: `key :down, :j, action: :move_down` (multiple keys, one action)
+  - `action:` keyword: `key :q, action: :quit` (explicit action reference)
+  - Keyword syntax: `key q: -> { Command.exit }` (hash-style)
+  - Multi-keyword: `keys ctrl_c: -> { ... }, q: -> { ... }` (multiple bindings)
+  - Hash metaprogramming: `key(exit_bindings)` where `exit_bindings = { q: ..., esc: ... }`
+  - `keys` alias: `alias_method :keys, :key` for readability
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [0.6.1] - 2026-01-26
 
 ### Added
@@ -260,6 +296,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **First Release**: Empty release of `rooibos`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
 
 [Unreleased]: https://git.sr.ht/~kerrick/rooibos/refs/HEAD
+[0.6.2]: https://git.sr.ht/~kerrick/rooibos/refs/v0.6.2
 [0.6.1]: https://git.sr.ht/~kerrick/rooibos/refs/v0.6.1
 [0.6.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.6.0
 [0.5.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.5.0

data/doc/contributors/maybe_stateful_router.md

@@ -0,0 +1,56 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Maybe: Stateful Router
+
+**Status:** Not implemented — noted for future consideration.
+
+## Problem
+
+Current routed actions require the parent fragment's model to hold child fragments' models (e.g., `model.file_list`). The Router then needs to know which field name to use when dispatching to children and updating the parent model.
+
+This couples the Router to the parent's model structure.
+
+## Proposed Alternative
+
+Make the Router stateful, holding child fragment models internally:
+
+```ruby
+module ClassMethods
+  def route(prefix, to:)
+    # Router would also initialize and store child model
+    child_model, init_command = to.const_get(:Init).()
+    routed_models[prefix] = child_model
+    routes[prefix] = to
+  end
+end
+```
+
+## Pattern Symmetry
+
+This mirrors the architecture at every level:
+
+| Component | Holds Model | Calls Update |
+|-----------|-------------|--------------|
+| Runtime   | Root model  | Root Update  |
+| Router    | Child models| Child Updates|
+
+## Pros
+
+- Parent fragment doesn't need nested model composition
+- Router becomes a true "mini-runtime" for children
+- Enables features like broadcasting resize events to all children
+- Parent's Update is simpler — just handles its own concerns
+
+## Cons
+
+- Breaks from strict Elm pattern where parent Model contains child Models
+- Router becomes stateful (but Runtime already is)
+- Initialization order requires careful thought
+- View needs a different way to access child models for rendering
+
+## Decision
+
+Deferred. Current implementation requires parent to hold child models, which follows canonical Elm patterns. The stateful router approach is coherent but would be a significant architectural change.

data/doc/contributors/specs/file_browser_stories.md

@@ -133,6 +133,8 @@ _Note: If you started with negative-numbered stories, this happened in Story 0._
 - Selected item is visually highlighted
 - Selection wraps at top/bottom of list
 - `j`/`k` vim keys also work
+- `Home`/`g` jumps to first item
+- `End`/`G` jumps to last item
 
 ### Notes
 - Introduces state management (current selection index)
@@ -152,7 +154,11 @@ _Note: If you started with negative-numbered stories, this happened in Story 0._
 - File list updates to show new directory contents
 - Current path display updates
 - Enter on regular file does nothing (for now)
-- Backspace goes to parent directory
+- Backspace or `←`/`h` goes to parent directory
+- `→`/`l` enters directory (same as Enter)
+- `~` jumps to home directory
+- `/` jumps to root directory
+- `R` refreshes current view
 
 ### Notes
 - Introduces directory traversal
@@ -215,6 +221,8 @@ _Note: If you started with negative-numbered stories, this happened in Story 0._
 - Binary files show "Binary file" message
 - Preview pane scrolls if content is long
 - File type is detected (text vs binary)
+- `Space` toggles preview pane visibility
+- `PgUp`/`PgDn` pages through preview content (when focused)
 
 ### Notes
 - Introduces file reading
@@ -256,10 +264,12 @@ _Note: If you started with negative-numbered stories, this happened in Story 0._
 - Active pane has visual indicator (highlighted border)
 - Keyboard shortcuts work in context of focused pane
 - Arrow keys navigate within focused pane
+- `PgUp`/`PgDn` pages by visible height
 
 ### Notes
 - Introduces focus management
 - Introduces context-sensitive key handling
+- Introduces cached layout pattern (store pane dimensions for dynamic paging)
 - Preview pane becomes interactive (scrollable)
 
 ---

data/examples/{app_file_browser → tutorial/01}/app.rb

@@ -10,12 +10,15 @@ require "rooibos"
 
 module Tutorial01
   module FileBrowser
-    Model = Data.define(:current_directory, :file_names)
+    Entry = Data.define(:name, :directory?)
+
+    Model = Data.define(:current_directory, :entries)
 
     View = -> (model, tui) {
+      items = model.entries.map { |e| e.directory? ? "#{e.name}/" : e.name }
       tui.layout(children: [
         tui.paragraph(text: model.current_directory),
-        tui.list(items: model.file_names),
+        tui.list(items:),
       ])
     }
 
@@ -27,10 +30,17 @@ module Tutorial01
       end
     }
 
+    ReadEntries = -> (path) {
+      Dir.children(path).map { |name|
+        full_path = File.join(path, name)
+        Entry.new(name:, directory?: File.directory?(full_path))
+      }.sort_by { |e| [e.directory? ? 0 : 1, e.name.downcase] }
+    }
+
     Init = -> {
       current_directory = Dir.pwd
-      file_names = Dir.children(current_directory)
-      Ractor.make_shareable Model.new(current_directory, file_names)
+      entries = ReadEntries.call(current_directory)
+      Ractor.make_shareable Model.new(current_directory, entries)
     }
   end
 end

data/examples/tutorial/02/app.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rooibos"
+
+module Tutorial02
+  module FileBrowser
+    Entry = Data.define(:name, :directory?)
+
+    Model = Data.define(:current_directory, :entries, :selected_index)
+
+    View = -> (model, tui) {
+      items = model.entries.map { |e| e.directory? ? "#{e.name}/" : e.name }
+      tui.layout(children: [
+        tui.paragraph(text: model.current_directory),
+        tui.list(
+          items:,
+          selected_index: model.selected_index,
+          highlight_style: tui.style(modifiers: [:reversed])
+        ),
+      ])
+    }
+
+    Update = -> (message, model) {
+      if message.ctrl_c? or message.q?
+        Rooibos::Command.exit
+      elsif message.down_arrow? or message.j?
+        new_index = (model.selected_index + 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.up_arrow? or message.k?
+        new_index = (model.selected_index - 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.home? or message.g?
+        model.with(selected_index: 0)
+      elsif message.end? or message.G?
+        model.with(selected_index: model.entries.length - 1)
+      else
+        model
+      end
+    }
+
+    ReadEntries = -> (path) {
+      Dir.children(path).map { |name|
+        full_path = File.join(path, name)
+        Entry.new(name:, directory?: File.directory?(full_path))
+      }.sort_by { |e| [e.directory? ? 0 : 1, e.name.downcase] }
+    }
+
+    Init = -> {
+      current_directory = Dir.pwd
+      entries = ReadEntries.call(current_directory)
+      Ractor.make_shareable Model.new(current_directory, entries, 0)
+    }
+  end
+end
+
+if __FILE__ == $0
+  Rooibos.run(Tutorial02::FileBrowser)
+end

data/examples/tutorial/03/app.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rooibos"
+
+module Tutorial03
+  module FileBrowser
+    Entry = Data.define(:name, :directory?)
+
+    Model = Data.define(:current_directory, :entries, :selected_index)
+
+    View = -> (model, tui) {
+      items = model.entries.map { |e| e.directory? ? "#{e.name}/" : e.name }
+      tui.layout(children: [
+        tui.paragraph(text: model.current_directory),
+        tui.list(
+          items:,
+          selected_index: model.selected_index,
+          highlight_style: tui.style(modifiers: [:reversed])
+        ),
+      ])
+    }
+
+    Update = -> (message, model) {
+      if message.ctrl_c? or message.q?
+        Rooibos::Command.exit
+      elsif message.down_arrow? or message.j?
+        new_index = (model.selected_index + 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.up_arrow? or message.k?
+        new_index = (model.selected_index - 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.home? or message.g?
+        model.with(selected_index: 0)
+      elsif message.end? or message.G?
+        model.with(selected_index: model.entries.length - 1)
+      elsif message.enter? or message.right_arrow? or message.l?
+        selected_entry = model.entries[model.selected_index]
+        if selected_entry.directory?
+          new_dir = File.join(model.current_directory, selected_entry.name)
+          new_entries = read_entries(new_dir)
+          model.with(current_directory: new_dir, entries: new_entries, selected_index: 0)
+        else
+          model
+        end
+      elsif message.backspace? or message.left_arrow? or message.h?
+        parent_dir = File.dirname(model.current_directory)
+        new_entries = read_entries(parent_dir)
+        model.with(current_directory: parent_dir, entries: new_entries, selected_index: 0)
+      elsif message.tilde?
+        home_dir = Dir.home
+        new_entries = read_entries(home_dir)
+        model.with(current_directory: home_dir, entries: new_entries, selected_index: 0)
+      elsif message.slash?
+        new_entries = read_entries("/")
+        model.with(current_directory: "/", entries: new_entries, selected_index: 0)
+      elsif message.R?
+        new_entries = read_entries(model.current_directory)
+        model.with(entries: new_entries)
+      else
+        model
+      end
+    }
+
+    ReadEntries = -> (path) {
+      Dir.children(path).map { |name|
+        full_path = File.join(path, name)
+        Entry.new(name:, directory?: File.directory?(full_path))
+      }.sort_by { |e| [e.directory? ? 0 : 1, e.name.downcase] }
+    }
+
+    Init = -> {
+      current_directory = Dir.pwd
+      entries = ReadEntries.call(current_directory)
+      Ractor.make_shareable Model.new(current_directory, entries, 0)
+    }
+
+    private_class_method def self.read_entries(path)
+      ReadEntries.call(path)
+    end
+  end
+end
+
+if __FILE__ == $0
+  Rooibos.run(Tutorial03::FileBrowser)
+end

data/examples/tutorial/06_safe_refactoring/app.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rooibos"
+
+module Tutorial06
+  # A Fragment is a module with Model, Init, Update, View.
+  # This FileList fragment handles the list of files and navigation.
+  module FileList
+    Entry = Data.define(:name, :directory?)
+
+    Model = Data.define(:current_directory, :entries, :selected_index)
+
+    View = -> (model, tui) {
+      items = model.entries.map { |e| e.directory? ? "#{e.name}/" : e.name }
+      tui.layout(children: [
+        tui.paragraph(text: model.current_directory),
+        tui.list(
+          items:,
+          selected_index: model.selected_index,
+          highlight_style: tui.style(modifiers: [:reversed])
+        ),
+      ])
+    }
+
+    Update = -> (message, model) {
+      if message.move_down?
+        new_index = (model.selected_index + 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.move_up?
+        new_index = (model.selected_index - 1) % model.entries.length
+        model.with(selected_index: new_index)
+      elsif message.jump_to_first?
+        model.with(selected_index: 0)
+      elsif message.jump_to_last?
+        model.with(selected_index: model.entries.length - 1)
+      elsif message.enter?
+        selected_entry = model.entries[model.selected_index]
+        if selected_entry.directory?
+          new_dir = File.join(model.current_directory, selected_entry.name)
+          new_entries = read_entries(new_dir)
+          model.with(current_directory: new_dir, entries: new_entries, selected_index: 0)
+        else
+          nil
+        end
+      elsif message.go_back?
+        parent_dir = File.dirname(model.current_directory)
+        new_entries = read_entries(parent_dir)
+        model.with(current_directory: parent_dir, entries: new_entries, selected_index: 0)
+      elsif message.go_home?
+        home_dir = Dir.home
+        new_entries = read_entries(home_dir)
+        model.with(current_directory: home_dir, entries: new_entries, selected_index: 0)
+      elsif message.go_root?
+        root = File.expand_path("/")
+        new_entries = read_entries(root)
+        model.with(current_directory: root, entries: new_entries, selected_index: 0)
+      elsif message.refresh?
+        new_entries = read_entries(model.current_directory)
+        model.with(entries: new_entries)
+      end
+    }
+
+    ReadEntries = -> (path) {
+      Dir.children(path).map { |name|
+        full_path = File.join(path, name)
+        Entry.new(name:, directory?: File.directory?(full_path))
+      }.sort_by { |e| [e.directory? ? 0 : 1, e.name.downcase] }
+    }
+
+    Init = -> {
+      current_directory = Dir.pwd
+      entries = ReadEntries.call(current_directory)
+      Ractor.make_shareable Model.new(current_directory, entries, 0)
+    }
+
+    private_class_method def self.read_entries(path)
+      ReadEntries.call(path)
+    end
+  end
+
+  # The main FileBrowser delegates to the FileList fragment via Router.
+  module FileBrowser
+    include Rooibos::Router
+
+    Command = Rooibos::Command
+
+    # Parent model wraps child fragment
+    Model = Data.define(:file_list)
+
+    route :file_list, to: FileList
+
+    action go_back: FileList, keys: %i[backspace left h]
+    action go_home: FileList, key: :~
+    action go_root: FileList, key: :/
+    action refresh: FileList, key: :R
+    action enter: FileList, keys: %i[enter right l]
+    action move_down: FileList, keys: %i[down j]
+    action move_up: FileList, keys: %i[up k]
+    action jump_to_first: FileList, keys: %i[home g]
+    action jump_to_last: FileList, keys: %i[end G]
+    action -> { Command.exit }, keys: %i[ctrl_c q]
+
+    View = -> (model, tui) {
+      FileList::View.call(model.file_list, tui)
+    }
+
+    Update = from_router
+
+    Init = -> {
+      file_list = FileList::Init.()
+      Ractor.make_shareable Model.new(file_list:)
+    }
+  end
+end
+
+if __FILE__ == $0
+  Rooibos.run(Tutorial06::FileBrowser)
+end

data/lib/rooibos/message/routed.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Message synthesized by Router when keymap uses symbol + route.
+    #
+    # When a keymap entry uses a symbol instead of a handler, and specifies
+    # a route, the Router creates this message and dispatches it to the
+    # child fragment's UPDATE.
+    #
+    # === Example
+    #
+    #   # In parent keymap:
+    #   key :down, :move_down, route: :file_list
+    #
+    #   # Router synthesizes:
+    #   Routed.new(envelope: :move_down, event: key_event)
+    #
+    #   # Child UPDATE matches:
+    #   in { type: :routed, envelope: :move_down }
+    #     handle_move_down(model)
+    Routed = Data.define(:envelope, :event) do
+      include Predicates
+
+      def deconstruct_keys(_keys)
+        { type: :routed, envelope:, event: }
+      end
+
+      def routed?
+        true
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        method_name.end_with?("?") || super
+      end
+
+      def method_missing(method_name, *args, &block)
+        if method_name.end_with?("?")
+          method_name.to_s.chomp("?") == envelope.to_s
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rooibos/message.rb

@@ -116,3 +116,4 @@ require_relative "message/all"
 require_relative "message/batch"
 require_relative "message/error"
 require_relative "message/canceled"
+require_relative "message/routed"

data/lib/rooibos/router.rb

@@ -65,12 +65,13 @@ module Rooibos
 
     # Class methods added when Router is included.
     module ClassMethods
-      # Declares a route to a child.
+      # Declares a route to a child fragment.
       #
-      # [prefix] Symbol or String identifying the route (normalized via +.to_s.to_sym+).
-      # [to] The child module (must have UPDATE and INITIAL constants).
-      def route(prefix, to:)
-        routes[prefix.to_s.to_sym] = to
+      # [fragment_model_instance_attr] Symbol naming the attr on the parent's model
+      #   that holds this fragment's model instance (normalized via +.to_s.to_sym+).
+      # [to] The child fragment module (must have Update and Init constants).
+      def route(fragment_model_instance_attr, to:)
+        routes[fragment_model_instance_attr.to_s.to_sym] = to
       end
 
       # Returns the registered routes hash.
@@ -84,17 +85,79 @@ module Rooibos
       # This avoids duplicating logic for keys and mouse events that do
       # the same thing.
       #
+      # Supports both positional and keyword syntax:
+      #   action :scroll_up, -> { Command.scroll(-1) }  # Positional
+      #   action scroll_up: -> { Command.scroll(-1) }   # Keyword
+      #
       # [name] Symbol or String identifying the action (normalized via +.to_s.to_sym+).
-      # [handler] Callable that returns a command or message.
-      def action(name, handler)
-        actions[name.to_s.to_sym] = handler
+      # [value] Callable that returns a command or message.
+      def action(name = nil, value = nil, keymap: nil, key: nil, keys: nil, mousemap: nil, **kwargs)
+        # key: and keys: are aliases for keymap:
+        effective_keymap = keymap || key || keys
+        action_name, action_value = if name && value
+          # Positional: action :name, handler
+          [name, value]
+        elsif name.respond_to?(:call) && value.nil?
+          # Anonymous: action -> { ... }, keymap: %i[...]
+          # No name, just handler with bindings
+          [nil, name]
+        elsif kwargs.size == 1
+          # Keyword: action name: handler
+          kwargs.first
+        else
+          raise ArgumentError, "action requires (name, value) or (name: value)"
+        end
+
+        # @type var action_name: Symbol?
+        # @type var action_value: (^() -> Command::execution? | Module)?
+        register_action(action_name, action_value) if action_name && action_value
+
+        # For anonymous actions, store handler directly in keymap
+        handler_for_keymap = action_name.nil? ? action_value : nil
+
+        # Register keymap bindings if provided
+        if effective_keymap
+          Array(effective_keymap).each do |key_name|
+            key_handlers[key_name.to_s.to_sym] = Router::KeyHandlerConfig.new(
+              handler: handler_for_keymap,
+              action: action_name&.to_s&.to_sym,
+              guard: nil,
+              route: nil
+            )
+          end
+        end
+
+        # Register mousemap bindings if provided
+        if mousemap
+          Array(mousemap).each do |mouse_event|
+            scroll_handlers[mouse_event.to_s.to_sym] = Router::ScrollHandlerConfig.new(
+              handler: handler_for_keymap,
+              action: action_name&.to_s&.to_sym
+            )
+          end
+        end
       end
 
-      # Returns the registered actions hash.
+      private def register_action(name, value)
+        key = name.to_s.to_sym
+        case value
+        when Module
+          routed_actions[key] = value
+        else
+          actions[key] = value
+        end
+      end
+
+      # Returns the registered handler actions hash.
       def actions
         @actions ||= {}
       end
 
+      # Returns the registered routed actions hash.
+      def routed_actions
+        @routed_actions ||= {}
+      end
+
       # Declares key handlers in a block.
       #
       # === Example
@@ -150,6 +213,7 @@ module Rooibos
         RouterUpdate.new(
           routes:,
           actions:,
+          routed_actions:,
           key_handlers:,
           scroll_handlers:,
           click_handler:
@@ -159,9 +223,10 @@ module Rooibos
 
     # Internal UPDATE callable with proper typing.
     class RouterUpdate # :nodoc:
-      def initialize(routes:, actions:, key_handlers:, scroll_handlers:, click_handler:)
+      def initialize(routes:, actions:, routed_actions:, key_handlers:, scroll_handlers:, click_handler:)
         @routes = routes
         @actions = actions
+        @routed_actions = routed_actions
         @key_handlers = key_handlers
         @scroll_handlers = scroll_handlers
         @click_handler = click_handler
@@ -195,6 +260,24 @@ module Rooibos
             if handler.nil? && config.action
               handler = @actions[config.action]
             end
+
+            # Check for routed action if no handler found
+            if handler.nil? && config.action
+              routed_fragment = @routed_actions[config.action]
+              if routed_fragment
+                # Find the model attr for this fragment
+                fragment_model_instance_attr = @routes.key(routed_fragment)
+                next unless fragment_model_instance_attr
+
+                # Synthesize Message::Routed and dispatch to child
+                routed_message = Rooibos::Message::Routed.new(envelope: config.action, event: message)
+                child_update = routed_fragment.const_get(:Update)
+                previous_child_fragment_model_instance = model.public_send(fragment_model_instance_attr)
+                updated_child_fragment_model_instance, command = child_update.call(routed_message, previous_child_fragment_model_instance)
+                return [model.with(fragment_model_instance_attr => updated_child_fragment_model_instance), command]
+              end
+            end
+
             next unless handler
 
             command = handler.call
@@ -260,18 +343,53 @@ module Rooibos
 
       # Registers a key handler.
       #
-      # [key_name] String or Symbol for the key (normalized via +.to_s+).
-      # [handler_or_action] Callable or Symbol (action name).
+      # Supports multiple forms:
+      #   key :q, -> { Command.exit }           # Single key with handler
+      #   key :q, :quit                         # Single key with action name
+      #   key :down, :j, action: :move_down     # Multiple keys with action
+      #   key :enter, -> { ... }, route: :foo   # With options
+      #
+      # [*key_names] One or more key names (String or Symbol).
+      # [handler_or_action] Callable or Symbol (action name) - optional if action: given.
+      # [action] Action name as keyword arg (alternative to positional).
       # [route] Optional route prefix for the command result.
       # [when/if/only/guard] Guard that runs if truthy (aliases).
       # [unless/except/skip] Guard that runs if falsy (negative aliases).
-      def key(key_name, handler_or_action, route: nil, when: nil, if: nil, only: nil, guard: nil, unless: nil, except: nil, skip: nil)
+      def key(*args, action: nil, route: nil, when: nil, if: nil, only: nil, guard: nil, unless: nil, except: nil, skip: nil, **bindings)
+        # Parse args: all symbols/strings are keys, last callable is handler
+        key_names = [] #: Array[Symbol | String]
         handler = nil
-        action = nil
-        if handler_or_action.is_a?(Symbol)
-          action = handler_or_action
-        else
-          handler = handler_or_action
+        action_name = action
+
+        args.each do |arg|
+          if arg.is_a?(Hash)
+            # Hash passed positionally: key({q: -> { ... }})
+            bindings.merge!(arg)
+          elsif arg.respond_to?(:call)
+            handler = arg
+          elsif arg.is_a?(Symbol) || arg.is_a?(String)
+            # Could be a key name or action name (positional action from old API)
+            key_names << arg
+          end
+        end
+
+        # Keyword syntax: key ctrl_c: -> { ... }
+        # Each kwarg is key_name => handler
+        bindings.each do |key_name, handler_or_action|
+          if handler_or_action.respond_to?(:call)
+            register_key_handler(key_name, handler_or_action, nil, route, nil)
+          else
+            register_key_handler(key_name, nil, handler_or_action, route, nil)
+          end
+        end
+
+        # If we had keyword bindings, skip positional processing
+        return if bindings.any?
+
+        # Old API: key :q, :quit - last symbol is the action
+        if handler.nil? && action_name.nil? && key_names.size >= 2
+          # Check if last "key" is actually an action by seeing if it looks like a handler
+          action_name = key_names.pop
         end
 
         guards = @guard_stack.dup
@@ -293,14 +411,24 @@ module Rooibos
           -> (model) { guards.all? { |g| g.call(model) } }
         end
 
+        # Register each key
+        key_names.each do |key_name|
+          register_key_handler(key_name, handler, action_name, route, combined_guard)
+        end
+      end
+
+      private def register_key_handler(key_name, handler, action_name, route, guard)
         @handlers[key_name.to_s] = KeyHandlerConfig.new(
           handler:,
-          action:,
+          action: action_name,
           route:,
-          guard: combined_guard
+          guard:
         )
       end
 
+      # Alias for key (reads better with multiple keys)
+      alias_method :keys, :key
+
       # Applies a guard to all keys in the block.
       #
       # [when/if/only/guard] Guard that runs if truthy.

data/lib/rooibos/version.rb

@@ -8,5 +8,5 @@
 module Rooibos
   # The version of this gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
 end

data/sig/rooibos/message.rbs

@@ -181,5 +181,22 @@ module Rooibos
     def open?: () -> bool
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
+
+  # Routed message from parent Router to child fragment.
+  class Routed < Data
+    include Predicates
+
+    attr_reader envelope: Symbol
+    attr_reader event: RatatuiRuby::Event?
+
+    def self.new: (envelope: Symbol, event: RatatuiRuby::Event?) -> instance
+
+    def routed?: () -> bool
+    def deconstruct_keys: (Array[Symbol]? keys) -> { type: Symbol, envelope: Symbol, event: RatatuiRuby::Event? }
+
+    # Predicate methods via method_missing (e.g., move_down?, go_back?)
+    def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+    def method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+  end
 end
 end

data/sig/rooibos/router.rbs

@@ -48,18 +48,31 @@ module Rooibos
   module ClassMethods : Module
     @routes: Hash[Symbol, Module]
     @actions: Hash[Symbol, ^() -> Command::execution?]
-    @key_handlers: Hash[String, KeyHandlerConfig]
+    @routed_actions: Hash[Symbol, Module]
+    @key_handlers: Hash[Symbol, KeyHandlerConfig]
     @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
     @click_handler: ClickHandlerConfig?
 
-    def route: (Symbol | String prefix, to: Module) -> void
+    def route: (Symbol | String fragment_model_instance_attr, to: Module) -> void
     def routes: () -> Hash[Symbol, Module]
 
-    def action: (Symbol | String name, ^() -> Command::execution? handler) -> void
+    # Action: multiple syntax forms supported
+    def action: (
+      ?(Symbol | String | ^() -> Command::execution?) name,
+      ?(^() -> Command::execution? | Module) value,
+      ?keymap: (Symbol | Array[Symbol])?,
+      ?key: (Symbol | Array[Symbol])?,
+      ?keys: (Symbol | Array[Symbol])?,
+      ?mousemap: (Symbol | Array[Symbol])?,
+      **(^() -> Command::execution? | Module) kwargs
+    ) -> void
     def actions: () -> Hash[Symbol, ^() -> Command::execution?]
+    def routed_actions: () -> Hash[Symbol, Module]
+
+    private def register_action: (Symbol name, (^() -> Command::execution? | Module) value) -> void
 
     def keymap: () { (KeymapBuilder) [self: KeymapBuilder] -> void } -> void
-    def key_handlers: () -> Hash[String, KeyHandlerConfig]
+    def key_handlers: () -> Hash[Symbol, KeyHandlerConfig]
 
     def mousemap: () { (MousemapBuilder) [self: MousemapBuilder] -> void } -> void
     def scroll_handlers: () -> Hash[Symbol, ScrollHandlerConfig]
@@ -76,14 +89,16 @@ module Rooibos
   class RouterUpdate
     @routes: Hash[Symbol, Module]
     @actions: Hash[Symbol, ^() -> Command::execution?]
-    @key_handlers: Hash[String, KeyHandlerConfig]
+    @routed_actions: Hash[Symbol, Module]
+    @key_handlers: Hash[Symbol, KeyHandlerConfig]
     @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
     @click_handler: ClickHandlerConfig?
 
     def initialize: (
       routes: Hash[Symbol, Module],
       actions: Hash[Symbol, ^() -> Command::execution?],
-      key_handlers: Hash[String, KeyHandlerConfig],
+      routed_actions: Hash[Symbol, Module],
+      key_handlers: Hash[Symbol, KeyHandlerConfig],
       scroll_handlers: Hash[Symbol, ScrollHandlerConfig],
       click_handler: ClickHandlerConfig?
     ) -> void
@@ -104,9 +119,10 @@ module Rooibos
 
     def initialize: () -> void
 
+    # Variadic key binding: accepts multiple keys, optional action kwarg, hash bindings
     def key: (
-      String | Symbol key_name,
-      (^() -> Command::execution?) | Symbol handler_or_action,
+      *(String | Symbol | ^() -> Command::execution? | Hash[Symbol, (^() -> Command::execution?) | Symbol]) args,
+      ?action: Symbol?,
       ?route: Symbol?,
       ?when: (^(_DataModel) -> bool)?,
       ?if: (^(_DataModel) -> bool)?,
@@ -114,9 +130,13 @@ module Rooibos
       ?guard: (^(_DataModel) -> bool)?,
       ?unless: (^(_DataModel) -> bool)?,
       ?except: (^(_DataModel) -> bool)?,
-      ?skip: (^(_DataModel) -> bool)?
+      ?skip: (^(_DataModel) -> bool)?,
+      **(^() -> Command::execution? | Symbol) bindings
     ) -> void
 
+    # Alias for key (reads better with multiple keys)
+    alias keys key
+
     def only: (
       ?when: (^(_DataModel) -> bool)?,
       ?if: (^(_DataModel) -> bool)?,
@@ -134,6 +154,7 @@ module Rooibos
     private
 
     def with_guard: ((^(_DataModel) -> bool)?) { () -> void } -> void
+    def register_key_handler: ((Symbol | String) key_name, (^() -> Command::execution? | Symbol)? handler, (Symbol | String | ^() -> Command::execution?)? action_name, Symbol? route, (^(_DataModel) -> bool)? guard) -> void
   end
 
   # Builder for mousemap DSL.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rooibos
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Kerrick Long
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -278,6 +278,7 @@ files:
 - doc/contributors/documentation_stub_audit.md
 - doc/contributors/documentation_style.md
 - doc/contributors/e2e_pty.md
+- doc/contributors/maybe_stateful_router.md
 - doc/contributors/specs/earliest_tutorial_steps_per_story.md
 - doc/contributors/specs/file_browser.md
 - doc/contributors/specs/file_browser_stories.md
@@ -360,7 +361,6 @@ files:
 - doc/tutorial/29_configuration.md
 - doc/tutorial/30_going_further.md
 - doc/tutorial/index.md
-- examples/app_file_browser/app.rb
 - examples/app_fractal_dashboard/README.md
 - examples/app_fractal_dashboard/app.rb
 - examples/app_fractal_dashboard/dashboard/base.rb
@@ -376,6 +376,10 @@ files:
 - examples/app_fractal_dashboard/fragments/stats_panel.rb
 - examples/app_fractal_dashboard/fragments/system_info.rb
 - examples/app_fractal_dashboard/fragments/uptime.rb
+- examples/tutorial/01/app.rb
+- examples/tutorial/02/app.rb
+- examples/tutorial/03/app.rb
+- examples/tutorial/06_safe_refactoring/app.rb
 - examples/verify_readme_usage/README.md
 - examples/verify_readme_usage/app.rb
 - examples/verify_website_first_app/app.rb
@@ -405,6 +409,7 @@ files:
 - lib/rooibos/message/error.rb
 - lib/rooibos/message/http_response.rb
 - lib/rooibos/message/open.rb
+- lib/rooibos/message/routed.rb
 - lib/rooibos/message/system/batch.rb
 - lib/rooibos/message/system/stream.rb
 - lib/rooibos/message/timer.rb