rooibos 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7a4f2a869c06e70b95a34cac8915f8d8e6543283007fd7c595692cf34bf3329
-  data.tar.gz: c8c0be8e5059b55671baa49105aa7b470dfdfa17647353f4e81ebcf06ecf7f15
+  metadata.gz: 3c2eb32007ddd93c0a653829b44492878ca229fef1f90c84516d474d3f324132
+  data.tar.gz: f52b7a94243bd9582b7229cf48b3834d3f9ae6abaf9f9d6c622625f1d3951a8a
 SHA512:
-  metadata.gz: 97556fd7362f24d3d5572da7b11485456b3066bc56ef77994c2448a62085aa62d54c8503c5ffa2cea4472dd556bff1328ececb1dcb0c323cf663fdd1267ac8c9
-  data.tar.gz: c02267ab34497516ee6b6fee6daab08b72fcf26f6d4499aaf5d98162df1f063ee7eeec0464361189d3371a77434cf94d72b030289acea29cbc0d4b972691f1aa
+  metadata.gz: 2d5dc50320f2b8026cbb4f33d4c94b2a18beb6930bbdda45a0d38f14013c7015ecb5fce740d2003e6ba19cf48c901dc21e65034d2a66cc6ab6e6c7a3615688e0
+  data.tar.gz: 17a5f9bd24f5c9075fbe333a542a094ec40aa9063bd93d0265a5c4c264ead213d9c5030691c62cfd40c3c731570b5c30da0665dc67dbb1ff2a57545e729404f4

data/.builds/ruby-3.2.yml

@@ -15,8 +15,10 @@ packages:
   - libffi
   - clang
   - git
+artifacts:
+  - rooibos/pkg/rooibos-0.6.0.gem
 sources:
-  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+  - https://git.sr.ht/~kerrick/rooibos
 tasks:
   - setup: |
       curl https://mise.jdx.dev/install.sh | sh
@@ -27,7 +29,7 @@ tasks:
       echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
       export CI="true"
-      cd ratatui_ruby-tea
+      cd rooibos
       sed -i 's/ruby = .*/ruby = "3.2"/' mise.toml
       mise install
       mise x -- pip install reuse
@@ -37,15 +39,17 @@ tasks:
       mise x -- bundle install
   - test: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
+      echo "Installing rooibos gem globally for integration tests..."
+      mise x -- bundle exec rake install:force
       echo "Testing Ruby 3.2"
       mise x -- bundle exec rake test
   - lint: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       echo "Linting Ruby 3.2"
       mise x -- bundle exec rake lint
   - package: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       mise x -- bundle exec rake build

data/.builds/ruby-3.3.yml

@@ -15,8 +15,10 @@ packages:
   - libffi
   - clang
   - git
+artifacts:
+  - rooibos/pkg/rooibos-0.6.0.gem
 sources:
-  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+  - https://git.sr.ht/~kerrick/rooibos
 tasks:
   - setup: |
       curl https://mise.jdx.dev/install.sh | sh
@@ -27,7 +29,7 @@ tasks:
       echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
       export CI="true"
-      cd ratatui_ruby-tea
+      cd rooibos
       sed -i 's/ruby = .*/ruby = "3.3"/' mise.toml
       mise install
       mise x -- pip install reuse
@@ -37,15 +39,17 @@ tasks:
       mise x -- bundle install
   - test: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
+      echo "Installing rooibos gem globally for integration tests..."
+      mise x -- bundle exec rake install:force
       echo "Testing Ruby 3.3"
       mise x -- bundle exec rake test
   - lint: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       echo "Linting Ruby 3.3"
       mise x -- bundle exec rake lint
   - package: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       mise x -- bundle exec rake build

data/.builds/ruby-3.4.yml

@@ -15,8 +15,10 @@ packages:
   - libffi
   - clang
   - git
+artifacts:
+  - rooibos/pkg/rooibos-0.6.0.gem
 sources:
-  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+  - https://git.sr.ht/~kerrick/rooibos
 tasks:
   - setup: |
       curl https://mise.jdx.dev/install.sh | sh
@@ -27,7 +29,7 @@ tasks:
       echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
       export CI="true"
-      cd ratatui_ruby-tea
+      cd rooibos
       sed -i 's/ruby = .*/ruby = "3.4"/' mise.toml
       mise install
       mise x -- pip install reuse
@@ -37,15 +39,17 @@ tasks:
       mise x -- bundle install
   - test: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
+      echo "Installing rooibos gem globally for integration tests..."
+      mise x -- bundle exec rake install:force
       echo "Testing Ruby 3.4"
       mise x -- bundle exec rake test
   - lint: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       echo "Linting Ruby 3.4"
       mise x -- bundle exec rake lint
   - package: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       mise x -- bundle exec rake build

data/.builds/ruby-4.0.0.yml

@@ -15,8 +15,10 @@ packages:
   - libffi
   - clang
   - git
+artifacts:
+  - rooibos/pkg/rooibos-0.6.0.gem
 sources:
-  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+  - https://git.sr.ht/~kerrick/rooibos
 tasks:
   - setup: |
       curl https://mise.jdx.dev/install.sh | sh
@@ -27,7 +29,7 @@ tasks:
       echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
       export CI="true"
-      cd ratatui_ruby-tea
+      cd rooibos
       sed -i 's/ruby = .*/ruby = "4.0.0"/' mise.toml
       mise install
       mise x -- pip install reuse
@@ -37,15 +39,17 @@ tasks:
       mise x -- bundle install
   - test: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
+      echo "Installing rooibos gem globally for integration tests..."
+      mise x -- bundle exec rake install:force
       echo "Testing Ruby 4.0.0"
       mise x -- bundle exec rake test
   - lint: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       echo "Linting Ruby 4.0.0"
       mise x -- bundle exec rake lint
   - package: |
       . ~/.buildenv
-      cd ratatui_ruby-tea
+      cd rooibos
       mise x -- bundle exec rake build

data/AGENTS.md

@@ -35,7 +35,7 @@ Description: Part of the RatatuiRuby ecosystem.
 
 - **BANNED WORD: "component"** — Reserved for Kit.
 - **Avoid "widget" for Rooibos units** — "Widget" refers to Engine/Ratatui render primitives. In Rooibos, call them **fragments**.
-- **Fragment:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Fragments compose: parent fragments delegate to child fragments.
+- **Fragment:** A module containing `Model`, `Init`, `Update`, and `View` constants. Fragments compose: parent fragments delegate to child fragments.
 - Use "model", "update", "view" for the MVU pattern. Use "message" (not "msg") and "command" (not "cmd").
 
 ### Ruby Standards

data/CHANGELOG.md

@@ -21,6 +21,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.6.0] - 2026-01-25
+
+### Added
+
+- **rooibos CLI**: New command-line interface installed as executable when you install the gem. Provides `rooibos new APP_NAME` to scaffold a complete Rooibos application using `bundle gem` conventions, and `rooibos run` to launch the application. The scaffolded app includes a working TUI that displays "Hello, Rooibos!" and exits on q or Ctrl+C, plus a passing test demonstrating `Rooibos::TestHelper` patterns.
+
+- **Rooibos::Welcome**: Built-in welcome screen fragment available via `require "rooibos/welcome"`. Provides `Model`, `View`, `Update`, and `Init` constants that scaffolded apps delegate to. Features keyboard Tab/Shift+Tab focus cycling, mouse hover states, and clickable buttons for visiting the website or exiting. Use as a starting point or reference for building your own fragments.
+
+- **Command::Custom#deconstruct_keys**: Default pattern matching support for custom commands. Introspects public query methods and returns a hash with `:type` as a snake_case discriminator. Data.define members are included automatically. Respects the `keys` argument for performance optimization. Override for hot paths or metaprogrammed methods.
+
+- **Rooibos::TestHelper#assert_no_errors**: Test assertion to fail fast when `Message::Error` is unexpectedly present in collected messages. Works with Minitest (via `flunk`) and RSpec (via `raise`). Include via `include Rooibos::TestHelper`.
+
+- **Message::Error**: New message type for command errors. Includes `error?` predicate and `deconstruct_keys` for pattern matching with `{ type: :error, command:, exception: }`.
+
+- **Message::Canceled**: New message type for canceled commands. Includes `canceled?` predicate (with `cancelled?` alias for British spelling) and `deconstruct_keys` for pattern matching with `{ type: :canceled, command: }`. Custom command authors should emit this when `token.canceled?` is true.
+
+- **Message Symbol Comparison**: All `Message::*` types now support symbol comparison via `to_sym` and `==`, similar to RatatuiRuby events. Symbols use the `message_` prefix to avoid collision with event types: `msg == :message_timer`, `msg == :message_http`, `msg == :message_error`. `Message::Predicates` also provides a smart-default `deconstruct_keys` that derives `:type` from the class name.
+
+- **Rooibos::Message.=== for case/when dispatch**: The `Rooibos::Message` module now implements `===` for use in case/when statements. Matches only built-in framework message types (classes under `Rooibos::Message::`), rejecting key events and user-defined message classes. Enables Update functions to distinguish framework responses from user input.
+
+- **Command.open**: Opens a file or URL with the system's default application. Cross-platform: uses `open` on macOS, `xdg-open` on Linux, `start` on Windows. Sends `Message::Open` on success (exit 0) or `Message::Error` on failure.
+
+### Changed
+
+- **BREAKING: Rooibos::TestHelper Include Pattern**: `Rooibos::TestHelper` now includes `RatatuiRuby::TestHelper` instead of the other way around. Previously, requiring `rooibos/test_helper` would inject Rooibos assertions into `RatatuiRuby::TestHelper`. Now, use `include Rooibos::TestHelper` to get both Rooibos assertions and RatatuiRuby test terminal helpers. Update your test classes from `include RatatuiRuby::TestHelper` to `include Rooibos::TestHelper`.
+
+- **BREAKING: Rooibos.delegate Message Format**: `Rooibos.delegate` now passes `message[1]` (single value) to child UPDATEs instead of `message[1..]` (array slice). This aligns child fragments with the universal `{ type:, envelope: }` pattern. Update pattern matches from `in [{ type: :system, ... }]` to `in { type: :system, ... }`.
+
+- **BREAKING: Command::Error → Message::Error**: Moved `Command::Error` to `Message::Error`. Commands flow *out* from Update; Messages flow *in* to Update. Error was always sent *to* Update so it belongs in the Message module. Includes `error?` predicate and `deconstruct_keys` for pattern matching with `{ type: :error, command:, exception: }`. Update pattern matches from `Command::Error` to `Message::Error`.
+
+- **BREAKING: Timer/Batch Cancellation → Message::Canceled**: When `Command.wait`, `Command.tick`, `Command.all`, or `Command.batch` are canceled, they now send `Message::Canceled` instead of `Command.cancel(self)`. Custom command authors should do the same: when `token.canceled?`, emit `Message::Canceled.new(command: self)`. Update pattern matches from `in Command::Cancel` to `in Message::Canceled` or `in { type: :canceled, command: }`.
+
+- **Dependency Update**: Now requires `ratatui_ruby ~> 1.2.0` (was `~> 1.0.0.beta.3`). This stable release adds inline sync mode for deterministic event ordering in tests.
+
+### Fixed
+
+- **Init runs after terminal initialization**: `Init` callables now run after the terminal is initialized, enabling them to call `RatatuiRuby.terminal_size`, compute layout areas, or perform other terminal-dependent initialization. Previously Init ran before the terminal was ready, causing "Terminal is not initialized" errors.
+
+- **FPS timeout uses float division**: The runtime now uses `1.0 / fps` instead of `1 / fps` for poll timeout calculation. Integer division caused `1 / 60` to yield 0, resulting in busy-wait CPU spinning at 100%.
+
+### Removed
+
+- **BREAKING: Command::Error class**: Removed. Use `Message::Error` instead.
+- **BREAKING: Command.error factory**: Removed. Use `Message::Error.new(command:, exception:)` instead.
+
 ## [0.5.0] - 2026-01-16
 
 ### Added
@@ -205,6 +250,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.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.6.0
 [0.5.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.5.0
 [0.4.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.4.0
 [0.3.1]: https://git.sr.ht/~kerrick/rooibos/refs/v0.3.1

data/README.md

@@ -20,7 +20,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]
-> **rooibos** is currently in **ALPHA**. The API may change with minor versions.
+> **rooibos** is currently in **BETA**. The API may change with minor versions.
 
 **[Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) to CharmRuby, raw Rust, and Go.
 
@@ -146,7 +146,7 @@ For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md).
 
 ## Features
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+_Because this gem is in alpha, it lacks documentation. Please check the source files._
 
 
 ## Documentation

data/README.rdoc

@@ -0,0 +1,374 @@
+== Confidently Build Terminal Apps
+
+Rooibos[https://rooibos.run] helps you build interactive terminal applications.
+Keep your code understandable and testable as it scales. Rooibos handles
+keyboard, mouse, and async work so you can focus on behavior and user experience.
+
+  gem install rooibos
+
+<i>Currently in beta. APIs may change before 1.0.</i>
+
+=== Get Started in Seconds
+
+  rooibos new my_app
+  cd my_app
+  rooibos run
+
+That's it. You have a working app with keyboard navigation, mouse support,
+and clickable buttons. Open <tt>lib/my_app.rb</tt> to make it your own.
+
+
+---
+
+=== The Pattern
+
+\Rooibos uses Model-View-Update, the architecture behind
+Elm[https://guide.elm-lang.org/architecture/],
+Redux[https://redux.js.org/], and {Bubble
+Tea}[https://github.com/charmbracelet/bubbletea].
+State lives in one place. Updates flow in one direction. The runtime handles
+rendering and runs background work for you.
+
+---
+
+=== Hello, MVU
+
+The simplest \Rooibos app. Press any key to increment the counter. Press
+<tt>Ctrl</tt>+<tt>C</tt> to quit.
+
+  require "rooibos"
+
+  module Counter
+    # Init: How do you create the initial model?
+    Init = -> { 0 }
+ 
+    # View: What does the user see?
+    View = -> (model, tui) { tui.paragraph(text: <<~END) }
+      Current count: #{model}.
+      Press any key to increment.
+      Press Ctrl+C to quit.
+    END
+ 
+    # Update: What happens when things change?
+    Update = -> (message, model) {
+      if message.ctrl_c?
+        Rooibos::Command.exit
+      elsif message.key?
+        model + 1
+      end
+    }
+  end
+
+  Rooibos.run(Counter)
+
+That's the whole pattern: Model holds state, Init creates it, View renders it,
+and Update changes it. The runtime handles everything else.
+
+
+---
+
+=== Your First Real Application
+
+A file browser in sixty lines. It opens files, navigates directories, handles
+errors, styles directories and hidden files differently, and supports vim-style
+keyboard shortcuts. If you can do this much with this little code, imagine how
+easy _your_ app will be to build.
+
+  require "rooibos"
+  
+  module FileBrowser
+    # Model: What state does your app need?
+    Model = Data.define(:path, :entries, :selected, :error)
+  
+    Init = -> {
+      path    = Dir.pwd
+      entries = Entries[path]
+      Ractor.make_shareable( # Ensures thread safety
+        Model.new(path:, entries:, selected: entries.first, error: nil))
+    }
+  
+    View = -> (model, tui) {
+      tui.block(
+        titles: [model.error || model.path,
+                 { content: KEYS, position: :bottom, alignment: :right}],
+        borders: [:all],
+        border_style: if model.error then tui.style(fg: :red) else nil end,
+        children: [tui.list(items: model.entries.map(&ListItem[model, tui]),
+                            selected_index: model.entries.index(model.selected),
+                            highlight_symbol: "",
+                            highlight_style: tui.style(modifiers: [:reversed]))]
+      )
+    }
+  
+    Update = -> (message, model) {
+      return model.with(error: ERROR) if message.error?
+      model = model.with(error: nil) if model.error && message.key?
+  
+      if message.ctrl_c? || message.q? then Rooibos::Command.exit
+      elsif message.home? || message.g? then model.with(selected: model.entries.first)
+      elsif message.end? || message.G? then model.with(selected: model.entries.last)
+      elsif message.up_arrow? || message.k? then Select[:-, model]
+      elsif message.down_arrow? || message.j? then Select[:+, model]
+      elsif message.enter? then Open[model]
+      elsif message.escape? then Navigate[File.dirname(model.path), model]
+      end
+    }
+  
+    private # Lines below this are implementation details
+  
+    KEYS  = "↑/↓/Home/End: Select | Enter: Open | Esc: Navigate Up | q: Quit"
+    ERROR = "Sorry, opening the selected file failed."
+  
+    ListItem = -> (model, tui) { -> (name) {
+      modifiers = name.start_with?(".") ? [:dim] : []
+      fg        = :blue if name.end_with?("/")
+      tui.list_item(content: name, style: tui.style(fg:, modifiers:))
+    } }
+  
+    Select = -> (operator, model) {
+      new_index = model.entries.index(model.selected).public_send(operator, 1)
+      model.with(selected: model.entries[new_index.clamp(0, model.entries.length - 1)])
+    }
+  
+    Open = -> (model) {
+      full = File.join(model.path, model.selected.delete_suffix("/"))
+      model.selected.end_with?("/") ? Navigate[full, model] : Rooibos::Command.open(full)
+    }
+  
+    Navigate = -> (path, model) {
+      entries = Entries[path]
+      model.with(path:, entries:, selected: entries.first, error: nil)
+    }
+  
+    Entries = -> (path) {
+      Dir.children(path).map { |name|
+        File.directory?(File.join(path, name)) ? "#{name}/" : name
+      }.sort_by { |name| [name.end_with?("/") ? 0 : 1, name.downcase] }
+    }
+  end
+
+  Rooibos.run(FileBrowser)
+
+
+---
+
+=== Batteries Included
+
+==== Commands
+
+Applications fetch data, run shell commands, and set timers. \Rooibos Commands
+run off the main thread and send results back as messages.
+
+<b>HTTP requests:</b>
+
+  Update = -> (message, model) {
+    case message
+    in :fetch_users
+      [model.with(loading: true), Rooibos::Command.http(:get, "/api/users", :got_users)]
+    in { type: :http, envelope: :got_users, status: 200, body: }
+      model.with(loading: false, users: JSON.parse(body))
+    in { type: :http, envelope: :got_users, status: }
+      model.with(error: "HTTP #{status}")
+    end
+  }
+
+<b>Shell commands:</b>
+
+  Update = -> (message, model) {
+    case message
+    in :list_files
+      Rooibos::Command.system("ls -la", :listed_files)
+    in { type: :system, envelope: :listed_files, stdout:, status: 0 }
+      model.with(files: stdout.lines.map(&:chomp))
+    in { type: :system, envelope: :listed_files, stderr:, status: }
+      model.with(error: stderr)
+    end
+  }
+
+<b>Timers:</b>
+
+  Update = -> (message, model) {
+    case message
+    in { type: :timer, envelope: :tick, elapsed: }
+      [model.with(frame: model.frame + 1), Rooibos::Command.wait(1.0 / 24, :tick)]
+    end
+  }
+
+<b>And more!</b> \Rooibos includes <tt>all</tt>, <tt>batch</tt>, <tt>cancel</tt>,
+<tt>custom</tt>, <tt>exit</tt>, <tt>http</tt>, <tt>map</tt>, <tt>open</tt>,
+<tt>system</tt>, <tt>tick</tt>, and <tt>wait</tt> commands.  You can also define
+your own custom commands for complex orchestration. 
+
+Every command produces a message, and Update handles it the same way.
+
+==== Testing
+
+\Rooibos makes TUIs so easy to test, you'll save more time by writing tests than
+by not testing.
+
+<b>Unit test Update, View, and Init.</b> No terminal needed. Test helpers included.
+
+  def test_moves_selection_down_with_j
+    model = Ractor.make_shareable(FileBrowser::Model.new(
+      path: "/", entries: %w[bin exe lib], selected: "bin", error: nil))
+    message = RatatuiRuby::Event::Key.new(code: "j")
+
+    result = FileBrowser::Update.call(message, model)
+
+    assert_equal "exe", result.selected
+  end
+
+<b>Style assertions.</b> Draw to a headless terminal, verify colors and modifiers.
+
+  def test_directories_are_blue
+    with_test_terminal(60, 10) do
+      model = Ractor.make_shareable(FileBrowser::Model.new(
+        path: "/", entries: %w[file.txt subdir/], selected: "file.txt", error: nil))
+      widget = FileBrowser::View.call(model, RatatuiRuby::TUI.new)
+
+      RatatuiRuby.draw { |frame| frame.render_widget(widget, frame.area) }
+
+      assert_blue(1, 2) # "subdir/" at column 1, row 2
+    end
+  end
+
+<b>System tests.</b> Inject events, run the full app, snapshot the result.
+
+  def test_selection_moves_down
+    with_test_terminal(120, 30) do
+      Dir.mktmpdir do |dir|
+        FileUtils.touch(File.join(dir, "a"))
+        FileUtils.touch(File.join(dir, "b"))
+        FileUtils.touch(File.join(dir, "c"))
+
+        inject_key(:down)
+        inject_key(:ctrl_c)
+
+        # Tests use explicit params to inject deterministic initial state.
+        Rooibos.run(
+          model: Ractor.make_shareable(FileBrowser::Model.new(
+            path: dir, entries: %w[a b c], selected: "a", error: nil)),
+          view: FileBrowser::View,
+          update: FileBrowser::Update
+        )
+
+        assert_snapshots("selection_moved_down") do |lines|
+          title = "┌/tmp/test#{'─' * 107}┐"
+          lines.map do |l|
+            l.gsub(/┌#{Regexp.escape(dir)}[^┐]*┐/, title)
+          end
+        end
+      end
+    end
+  end
+
+Snapshots record both plain text and ANSI colors. Normalization blocks mask
+dynamic content (timestamps, temp paths) for cross-platform reproducibility.
+Run <tt>UPDATE_SNAPSHOTS=1 rake test</tt> to regenerate baselines.
+
+==== Scale Up
+
+Large applications decompose into fragments. Each fragment has its own Model,
+View, Update, and Init. Parents compose children. The pattern scales.
+
+The Router DSL eliminates boilerplate:
+
+  module Dashboard
+    include Rooibos::Router
+
+    route :stats, to: StatsPanel
+    route :network, to: NetworkPanel
+
+    keymap do
+      key :ctrl_c, -> { Rooibos::Command.exit }
+      only when: -> (model) { !model.modal_open } do
+        key :q, -> { Rooibos::Command.exit }
+        key :s, -> { StatsPanel.fetch_command }
+        key :p, -> { NetworkPanel.ping_command }
+      end
+    end
+
+    Update = from_router
+
+    # ... Model, Init, View below
+  end
+
+Declare routes and keymaps. The router generates Update for you. Use guards to
+ignore keys when needed.
+
+==== CLI
+
+The <tt>rooibos</tt> command scaffolds projects and runs applications.
+
+  rooibos new my_app    # Generate project structure
+  rooibos run           # Run the app in current directory
+
+Generated apps include tests, type signatures, and a working welcome
+screen with keyboard and mouse support.
+
+
+---
+
+=== The Ecosystem
+
+\Rooibos builds on RatatuiRuby[https://www.ratatui-ruby.dev], a Rubygem built on
+Ratatui[https://ratatui.rs]. You get native performance with the joy of Ruby.
+\Rooibos is one way to manage state and composition. Kit is another.
+
+==== Rooibos[https://git.sr.ht/~kerrick/rooibos]
+
+Model-View-Update architecture. Inspired by Elm, Bubble Tea, and React +
+Redux. Your UI is a pure function of state.
+
+- Functional programming with MVU
+- Commands work off the main thread
+- Messages, not callbacks, drive updates
+
+==== {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit] (Coming Soon)
+
+Component-based architecture. Encapsulate state, input handling, and
+rendering in reusable pieces.
+
+- OOP with stateful components
+- Separate UI state from domain logic
+- Built-in focus management & click handling
+
+Both use the same widget library and rendering engine. Pick the paradigm
+that fits your brain.
+
+
+---
+
+=== Links
+
+[Get Started]
+  {Getting Started}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/index.md],
+  {Tutorial}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/tutorial/index.md],
+  {Examples}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/examples]
+
+[Coming From...]
+  {React/Redux}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_react_developers.md],
+  {BubbleTea}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_go_developers.md],
+  {Textual}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_python_developers.md]
+
+[Learn More]
+  {Essentials}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/essentials/index.md],
+  {Scaling Up}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/scaling_up/index.md],
+  {Best Practices}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/best_practices/index.md],
+  {Troubleshooting}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/troubleshooting/index.md]
+
+[Community]
+  {Discuss}[https://lists.sr.ht/~kerrick/ratatui_ruby-discuss],
+  {Announcements}[https://lists.sr.ht/~kerrick/ratatui_ruby-announce],
+  {Bug Tracker}[https://todo.sr.ht/~kerrick/ratatui_ruby],
+  {Contribution Guide}[https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md],
+  {Code of Conduct}[https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md]
+
+
+---
+
+[Website] https://rooibos.run
+[Source] https://git.sr.ht/~kerrick/rooibos
+[RubyGems] https://rubygems.org/gems/rooibos
+
+© 2026 Kerrick Long · Library: LGPL-3.0-or-later · Website: CC-BY-NC-ND-4.0 · Snippets: MIT-0

data/REUSE.toml

@@ -8,6 +8,11 @@ path = 'Gemfile.lock'
 SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC0-1.0"
 
+[[annotations]]
+path = 'README.rdoc'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
 [[annotations]]
 path = '**/snapshots/*.txt'
 SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"

data/Rakefile

@@ -13,4 +13,4 @@ RatatuiRuby::Devtools.install!
 # Import project-specific tasks
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[lint:fix test lint reuse steep]
+task default: %w[lint:fix install:force test lint reuse steep]