rooibos 0.5.0 → 0.6.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rooibos
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -15,28 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.1
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.1
-- !ruby/object:Gem::Dependency
-  name: ostruct
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -93,11 +79,168 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.5'
-description: Rooibos - part of the RatatuiRuby TUI framework ecosystem
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+description: "== Confidently Build Terminal Apps\n\nRooibos[https://rooibos.run] helps
+  you build interactive terminal applications.\nKeep your code understandable and
+  testable as it scales. Rooibos handles\nkeyboard, mouse, and async work so you can
+  focus on behavior and user experience.\n\n  gem install rooibos\n\n<i>Currently
+  in beta. APIs may change before 1.0.</i>\n\n=== Get Started in Seconds\n\n  rooibos
+  new my_app\n  cd my_app\n  rooibos run\n\nThat's it. You have a working app with
+  keyboard navigation, mouse support,\nand clickable buttons. Open <tt>lib/my_app.rb</tt>
+  to make it your own.\n\n\n---\n\n=== The Pattern\n\n\\Rooibos uses Model-View-Update,
+  the architecture behind\nElm[https://guide.elm-lang.org/architecture/],\nRedux[https://redux.js.org/],
+  and {Bubble\nTea}[https://github.com/charmbracelet/bubbletea].\nState lives in one
+  place. Updates flow in one direction. The runtime handles\nrendering and runs background
+  work for you.\n\n---\n\n=== Hello, MVU\n\nThe simplest \\Rooibos app. Press any
+  key to increment the counter. Press\n<tt>Ctrl</tt>+<tt>C</tt> to quit.\n\n  require
+  \"rooibos\"\n\n  module Counter\n    # Init: How do you create the initial model?\n
+  \   Init = -> { 0 }\n \n    # View: What does the user see?\n    View = -> (model,
+  tui) { tui.paragraph(text: <<~END) }\n      Current count: #{model}.\n      Press
+  any key to increment.\n      Press Ctrl+C to quit.\n    END\n \n    # Update: What
+  happens when things change?\n    Update = -> (message, model) {\n      if message.ctrl_c?\n
+  \       Rooibos::Command.exit\n      elsif message.key?\n        model + 1\n      end\n
+  \   }\n  end\n\n  Rooibos.run(Counter)\n\nThat's the whole pattern: Model holds
+  state, Init creates it, View renders it,\nand Update changes it. The runtime handles
+  everything else.\n\n\n---\n\n=== Your First Real Application\n\nA file browser in
+  sixty lines. It opens files, navigates directories, handles\nerrors, styles directories
+  and hidden files differently, and supports vim-style\nkeyboard shortcuts. If you
+  can do this much with this little code, imagine how\neasy _your_ app will be to
+  build.\n\n  require \"rooibos\"\n  \n  module FileBrowser\n    # Model: What state
+  does your app need?\n    Model = Data.define(:path, :entries, :selected, :error)\n
+  \ \n    Init = -> {\n      path    = Dir.pwd\n      entries = Entries[path]\n      Ractor.make_shareable(
+  # Ensures thread safety\n        Model.new(path:, entries:, selected: entries.first,
+  error: nil))\n    }\n  \n    View = -> (model, tui) {\n      tui.block(\n        titles:
+  [model.error || model.path,\n                 { content: KEYS, position: :bottom,
+  alignment: :right}],\n        borders: [:all],\n        border_style: if model.error
+  then tui.style(fg: :red) else nil end,\n        children: [tui.list(items: model.entries.map(&ListItem[model,
+  tui]),\n                            selected_index: model.entries.index(model.selected),\n
+  \                           highlight_symbol: \"\",\n                            highlight_style:
+  tui.style(modifiers: [:reversed]))]\n      )\n    }\n  \n    Update = -> (message,
+  model) {\n      return model.with(error: ERROR) if message.error?\n      model =
+  model.with(error: nil) if model.error && message.key?\n  \n      if message.ctrl_c?
+  || message.q? then Rooibos::Command.exit\n      elsif message.home? || message.g?
+  then model.with(selected: model.entries.first)\n      elsif message.end? || message.G?
+  then model.with(selected: model.entries.last)\n      elsif message.up_arrow? ||
+  message.k? then Select[:-, model]\n      elsif message.down_arrow? || message.j?
+  then Select[:+, model]\n      elsif message.enter? then Open[model]\n      elsif
+  message.escape? then Navigate[File.dirname(model.path), model]\n      end\n    }\n
+  \ \n    private # Lines below this are implementation details\n  \n    KEYS  = \"↑/↓/Home/End:
+  Select | Enter: Open | Esc: Navigate Up | q: Quit\"\n    ERROR = \"Sorry, opening
+  the selected file failed.\"\n  \n    ListItem = -> (model, tui) { -> (name) {\n
+  \     modifiers = name.start_with?(\".\") ? [:dim] : []\n      fg        = :blue
+  if name.end_with?(\"/\")\n      tui.list_item(content: name, style: tui.style(fg:,
+  modifiers:))\n    } }\n  \n    Select = -> (operator, model) {\n      new_index
+  = model.entries.index(model.selected).public_send(operator, 1)\n      model.with(selected:
+  model.entries[new_index.clamp(0, model.entries.length - 1)])\n    }\n  \n    Open
+  = -> (model) {\n      full = File.join(model.path, model.selected.delete_suffix(\"/\"))\n
+  \     model.selected.end_with?(\"/\") ? Navigate[full, model] : Rooibos::Command.open(full)\n
+  \   }\n  \n    Navigate = -> (path, model) {\n      entries = Entries[path]\n      model.with(path:,
+  entries:, selected: entries.first, error: nil)\n    }\n  \n    Entries = -> (path)
+  {\n      Dir.children(path).map { |name|\n        File.directory?(File.join(path,
+  name)) ? \"#{name}/\" : name\n      }.sort_by { |name| [name.end_with?(\"/\") ?
+  0 : 1, name.downcase] }\n    }\n  end\n\n  Rooibos.run(FileBrowser)\n\n\n---\n\n===
+  Batteries Included\n\n==== Commands\n\nApplications fetch data, run shell commands,
+  and set timers. \\Rooibos Commands\nrun off the main thread and send results back
+  as messages.\n\n<b>HTTP requests:</b>\n\n  Update = -> (message, model) {\n    case
+  message\n    in :fetch_users\n      [model.with(loading: true), Rooibos::Command.http(:get,
+  \"/api/users\", :got_users)]\n    in { type: :http, envelope: :got_users, status:
+  200, body: }\n      model.with(loading: false, users: JSON.parse(body))\n    in
+  { type: :http, envelope: :got_users, status: }\n      model.with(error: \"HTTP #{status}\")\n
+  \   end\n  }\n\n<b>Shell commands:</b>\n\n  Update = -> (message, model) {\n    case
+  message\n    in :list_files\n      Rooibos::Command.system(\"ls -la\", :listed_files)\n
+  \   in { type: :system, envelope: :listed_files, stdout:, status: 0 }\n      model.with(files:
+  stdout.lines.map(&:chomp))\n    in { type: :system, envelope: :listed_files, stderr:,
+  status: }\n      model.with(error: stderr)\n    end\n  }\n\n<b>Timers:</b>\n\n  Update
+  = -> (message, model) {\n    case message\n    in { type: :timer, envelope: :tick,
+  elapsed: }\n      [model.with(frame: model.frame + 1), Rooibos::Command.wait(1.0
+  / 24, :tick)]\n    end\n  }\n\n<b>And more!</b> \\Rooibos includes <tt>all</tt>,
+  <tt>batch</tt>, <tt>cancel</tt>,\n<tt>custom</tt>, <tt>exit</tt>, <tt>http</tt>,
+  <tt>map</tt>, <tt>open</tt>,\n<tt>system</tt>, <tt>tick</tt>, and <tt>wait</tt>
+  commands.  You can also define\nyour own custom commands for complex orchestration.
+  \n\nEvery command produces a message, and Update handles it the same way.\n\n====
+  Testing\n\n\\Rooibos makes TUIs so easy to test, you'll save more time by writing
+  tests than\nby not testing.\n\n<b>Unit test Update, View, and Init.</b> No terminal
+  needed. Test helpers included.\n\n  def test_moves_selection_down_with_j\n    model
+  = Ractor.make_shareable(FileBrowser::Model.new(\n      path: \"/\", entries: %w[bin
+  exe lib], selected: \"bin\", error: nil))\n    message = RatatuiRuby::Event::Key.new(code:
+  \"j\")\n\n    result = FileBrowser::Update.call(message, model)\n\n    assert_equal
+  \"exe\", result.selected\n  end\n\n<b>Style assertions.</b> Draw to a headless terminal,
+  verify colors and modifiers.\n\n  def test_directories_are_blue\n    with_test_terminal(60,
+  10) do\n      model = Ractor.make_shareable(FileBrowser::Model.new(\n        path:
+  \"/\", entries: %w[file.txt subdir/], selected: \"file.txt\", error: nil))\n      widget
+  = FileBrowser::View.call(model, RatatuiRuby::TUI.new)\n\n      RatatuiRuby.draw
+  { |frame| frame.render_widget(widget, frame.area) }\n\n      assert_blue(1, 2) #
+  \"subdir/\" at column 1, row 2\n    end\n  end\n\n<b>System tests.</b> Inject events,
+  run the full app, snapshot the result.\n\n  def test_selection_moves_down\n    with_test_terminal(120,
+  30) do\n      Dir.mktmpdir do |dir|\n        FileUtils.touch(File.join(dir, \"a\"))\n
+  \       FileUtils.touch(File.join(dir, \"b\"))\n        FileUtils.touch(File.join(dir,
+  \"c\"))\n\n        inject_key(:down)\n        inject_key(:ctrl_c)\n\n        # Tests
+  use explicit params to inject deterministic initial state.\n        Rooibos.run(\n
+  \         model: Ractor.make_shareable(FileBrowser::Model.new(\n            path:
+  dir, entries: %w[a b c], selected: \"a\", error: nil)),\n          view: FileBrowser::View,\n
+  \         update: FileBrowser::Update\n        )\n\n        assert_snapshots(\"selection_moved_down\")
+  do |lines|\n          title = \"┌/tmp/test#{'─' * 107}┐\"\n          lines.map do
+  |l|\n            l.gsub(/┌#{Regexp.escape(dir)}[^┐]*┐/, title)\n          end\n
+  \       end\n      end\n    end\n  end\n\nSnapshots record both plain text and ANSI
+  colors. Normalization blocks mask\ndynamic content (timestamps, temp paths) for
+  cross-platform reproducibility.\nRun <tt>UPDATE_SNAPSHOTS=1 rake test</tt> to regenerate
+  baselines.\n\n==== Scale Up\n\nLarge applications decompose into fragments. Each
+  fragment has its own Model,\nView, Update, and Init. Parents compose children. The
+  pattern scales.\n\nThe Router DSL eliminates boilerplate:\n\n  module Dashboard\n
+  \   include Rooibos::Router\n\n    route :stats, to: StatsPanel\n    route :network,
+  to: NetworkPanel\n\n    keymap do\n      key :ctrl_c, -> { Rooibos::Command.exit
+  }\n      only when: -> (model) { !model.modal_open } do\n        key :q, -> { Rooibos::Command.exit
+  }\n        key :s, -> { StatsPanel.fetch_command }\n        key :p, -> { NetworkPanel.ping_command
+  }\n      end\n    end\n\n    Update = from_router\n\n    # ... Model, Init, View
+  below\n  end\n\nDeclare routes and keymaps. The router generates Update for you.
+  Use guards to\nignore keys when needed.\n\n==== CLI\n\nThe <tt>rooibos</tt> command
+  scaffolds projects and runs applications.\n\n  rooibos new my_app    # Generate
+  project structure\n  rooibos run           # Run the app in current directory\n\nGenerated
+  apps include tests, type signatures, and a working welcome\nscreen with keyboard
+  and mouse support.\n\n\n---\n\n=== The Ecosystem\n\n\\Rooibos builds on RatatuiRuby[https://www.ratatui-ruby.dev],
+  a Rubygem built on\nRatatui[https://ratatui.rs]. You get native performance with
+  the joy of Ruby.\n\\Rooibos is one way to manage state and composition. Kit is another.\n\n====
+  Rooibos[https://git.sr.ht/~kerrick/rooibos]\n\nModel-View-Update architecture. Inspired
+  by Elm, Bubble Tea, and React +\nRedux. Your UI is a pure function of state.\n\n-
+  Functional programming with MVU\n- Commands work off the main thread\n- Messages,
+  not callbacks, drive updates\n\n==== {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit]
+  (Coming Soon)\n\nComponent-based architecture. Encapsulate state, input handling,
+  and\nrendering in reusable pieces.\n\n- OOP with stateful components\n- Separate
+  UI state from domain logic\n- Built-in focus management & click handling\n\nBoth
+  use the same widget library and rendering engine. Pick the paradigm\nthat fits your
+  brain.\n\n\n---\n\n=== Links\n\n[Get Started]\n  {Getting Started}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/index.md],\n
+  \ {Tutorial}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/tutorial/index.md],\n
+  \ {Examples}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/examples]\n\n[Coming
+  From...]\n  {React/Redux}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_react_developers.md],\n
+  \ {BubbleTea}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_go_developers.md],\n
+  \ {Textual}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/getting_started/for_python_developers.md]\n\n[Learn
+  More]\n  {Essentials}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/essentials/index.md],\n
+  \ {Scaling Up}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/scaling_up/index.md],\n
+  \ {Best Practices}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/best_practices/index.md],\n
+  \ {Troubleshooting}[https://git.sr.ht/~kerrick/rooibos/tree/trunk/item/doc/troubleshooting/index.md]\n\n[Community]\n
+  \ {Discuss}[https://lists.sr.ht/~kerrick/ratatui_ruby-discuss],\n  {Announcements}[https://lists.sr.ht/~kerrick/ratatui_ruby-announce],\n
+  \ {Bug Tracker}[https://todo.sr.ht/~kerrick/ratatui_ruby],\n  {Contribution Guide}[https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md],\n
+  \ {Code of Conduct}[https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md]\n\n\n---\n\n[Website]
+  https://rooibos.run\n[Source] https://git.sr.ht/~kerrick/rooibos\n[RubyGems] https://rubygems.org/gems/rooibos\n\n©
+  2026 Kerrick Long · Library: LGPL-3.0-or-later · Website: CC-BY-NC-ND-4.0 · Snippets:
+  MIT-0\n"
 email:
 - me@kerricklong.com
 executables:
-- ".gitkeep"
+- rooibos
 extensions: []
 extra_rdoc_files: []
 files:
@@ -117,30 +260,105 @@ files:
 - LICENSES/MIT-0.txt
 - LICENSES/MIT.txt
 - README.md
+- README.rdoc
 - REUSE.toml
 - Rakefile
 - Steepfile
-- doc/concepts/application_architecture.md
-- doc/concepts/application_testing.md
-- doc/concepts/async_work.md
-- doc/concepts/commands.md
-- doc/concepts/message_processing.md
-- doc/contributors/WIP/decomposition_strategies_analysis.md
-- doc/contributors/WIP/implementation_plan.md
-- doc/contributors/WIP/init_callable_proposal.md
-- doc/contributors/WIP/mvu_tea_implementations_research.md
-- doc/contributors/WIP/runtime_refactoring_status.md
-- doc/contributors/WIP/task.md
-- doc/contributors/WIP/v0.4.0_todo.md
+- doc/best_practices/forms_and_validation.md
+- doc/best_practices/http_workflows.md
+- doc/best_practices/index.md
+- doc/best_practices/lists_and_tables.md
+- doc/best_practices/modal_dialogs.md
+- doc/best_practices/no_stateful_widgets.md
+- doc/best_practices/orchestration.md
+- doc/best_practices/streaming_data.md
 - doc/contributors/design/commands_and_outlets.md
-- doc/contributors/kit-no-outlet.md
-- doc/contributors/priorities.md
+- doc/contributors/design/mvu_tea_implementations_research.md
+- doc/contributors/documentation_plan.md
+- doc/contributors/documentation_stub_audit.md
+- doc/contributors/documentation_style.md
+- doc/contributors/e2e_pty.md
+- doc/contributors/specs/earliest_tutorial_steps_per_story.md
+- doc/contributors/specs/file_browser.md
+- doc/contributors/specs/file_browser_stories.md
+- doc/contributors/specs/tutorials_to_stories.rb
+- doc/contributors/todo/scrollbar.md
+- doc/contributors/tutorial_old/01_project_setup.md
+- doc/contributors/tutorial_old/02_hello_world.md
+- doc/contributors/tutorial_old/03_adding_state.md
+- doc/contributors/tutorial_old/06_organizing_your_code.md
+- doc/contributors/tutorial_old/07_your_first_command.md
+- doc/contributors/tutorial_old/08_the_preview_pane.md
+- doc/contributors/tutorial_old/09_loading_states.md
+- doc/contributors/tutorial_old/10_testing_your_app.md
+- doc/contributors/tutorial_old/11_polish_and_refine.md
+- doc/contributors/tutorial_old/12_going_further.md
+- doc/contributors/tutorial_old/index.md
 - doc/custom.css
+- doc/essentials/commands.md
+- doc/essentials/index.md
+- doc/essentials/messages.md
+- doc/essentials/models.md
+- doc/essentials/shortcuts.md
+- doc/essentials/the_elm_architecture.md
+- doc/essentials/the_runtime.md
+- doc/essentials/update_functions.md
+- doc/essentials/views.md
+- doc/getting_started/for_go_developers.md
+- doc/getting_started/for_python_developers.md
+- doc/getting_started/for_react_developers.md
+- doc/getting_started/index.md
+- doc/getting_started/install.md
 - doc/getting_started/quickstart.md
-- doc/images/.gitkeep
+- doc/getting_started/ruby_primer.md
+- doc/getting_started/why_rooibos.md
 - doc/images/verify_readme_usage.png
 - doc/images/widget_cmd_exec.png
 - doc/index.md
+- doc/scaling_up/async_patterns.md
+- doc/scaling_up/command_composition.md
+- doc/scaling_up/custom_commands.md
+- doc/scaling_up/fractal_architecture.md
+- doc/scaling_up/index.md
+- doc/scaling_up/message_routing.md
+- doc/scaling_up/ractor_safety.md
+- doc/scaling_up/testing.md
+- doc/troubleshooting/common_errors.md
+- doc/troubleshooting/debugging.md
+- doc/troubleshooting/index.md
+- doc/troubleshooting/performance.md
+- doc/tutorial/01_project_setup.md
+- doc/tutorial/02_hello_world.md
+- doc/tutorial/03_static_file_list.md
+- doc/tutorial/04_arrow_navigation.md
+- doc/tutorial/05_real_files.md
+- doc/tutorial/06_safe_refactoring.md
+- doc/tutorial/07_red_first_tdd.md
+- doc/tutorial/08_file_metadata.md
+- doc/tutorial/09_text_preview.md
+- doc/tutorial/10_directory_tree.md
+- doc/tutorial/11_pane_focus.md
+- doc/tutorial/12_sorting.md
+- doc/tutorial/13_filtering.md
+- doc/tutorial/14_toggle_hidden.md
+- doc/tutorial/15_text_input_widget.md
+- doc/tutorial/16_rename_files.md
+- doc/tutorial/17_confirmation_dialogs.md
+- doc/tutorial/18_progress_indicators.md
+- doc/tutorial/19_atomic_operations.md
+- doc/tutorial/20_external_editor.md
+- doc/tutorial/21_modal_overlays.md
+- doc/tutorial/22_error_handling.md
+- doc/tutorial/23_terminal_capabilities.md
+- doc/tutorial/24_mouse_events.md
+- doc/tutorial/25_resize_events.md
+- doc/tutorial/26_loading_states.md
+- doc/tutorial/27_performance.md
+- doc/tutorial/28_color_schemes.md
+- 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
@@ -158,22 +376,33 @@ files:
 - examples/app_fractal_dashboard/fragments/uptime.rb
 - examples/verify_readme_usage/README.md
 - examples/verify_readme_usage/app.rb
+- examples/verify_website_first_app/app.rb
+- examples/verify_website_hello_mvu/app.rb
 - examples/widget_command_system/README.md
 - examples/widget_command_system/app.rb
-- exe/.gitkeep
+- exe/rooibos
+- generate_tutorial_stubs.rb
 - lib/rooibos.rb
+- lib/rooibos/cli.rb
+- lib/rooibos/cli/commands/new.rb
+- lib/rooibos/cli/commands/run.rb
 - lib/rooibos/command.rb
 - lib/rooibos/command/all.rb
 - lib/rooibos/command/batch.rb
 - lib/rooibos/command/custom.rb
 - lib/rooibos/command/http.rb
 - lib/rooibos/command/lifecycle.rb
+- lib/rooibos/command/open.rb
 - lib/rooibos/command/outlet.rb
 - lib/rooibos/command/wait.rb
 - lib/rooibos/error.rb
 - lib/rooibos/message.rb
 - lib/rooibos/message/all.rb
+- lib/rooibos/message/batch.rb
+- lib/rooibos/message/canceled.rb
+- lib/rooibos/message/error.rb
 - lib/rooibos/message/http_response.rb
+- lib/rooibos/message/open.rb
 - lib/rooibos/message/system/batch.rb
 - lib/rooibos/message/system/stream.rb
 - lib/rooibos/message/timer.rb
@@ -182,14 +411,17 @@ files:
 - lib/rooibos/shortcuts.rb
 - lib/rooibos/test_helper.rb
 - lib/rooibos/version.rb
+- lib/rooibos/welcome.rb
 - mise.toml
 - rbs_collection.lock.yaml
 - rbs_collection.yaml
 - sig/concurrent.rbs
 - sig/examples/verify_readme_usage/app.rbs
 - sig/examples/widget_command_system/app.rbs
+- sig/gem.rbs
 - sig/open3.rbs
 - sig/rooibos.rbs
+- sig/rooibos/cli.rbs
 - sig/rooibos/command.rbs
 - sig/rooibos/error.rbs
 - sig/rooibos/message.rbs
@@ -198,18 +430,20 @@ files:
 - sig/rooibos/shortcuts.rbs
 - sig/rooibos/test_helper.rbs
 - sig/rooibos/version.rbs
+- sig/rooibos/welcome.rbs
 - tasks/example_viewer.html.erb
+- tasks/install.rake
 - tasks/resources/build.yml.erb
 - tasks/resources/index.html.erb
 - tasks/resources/rubies.yml
 - tasks/steep.rake
 - vendor/goodcop/base.yml
-homepage: https://sr.ht/~kerrick/ratatui_ruby/
+homepage: https://rooibos.run
 licenses:
 - LGPL-3.0-or-later
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://sr.ht/~kerrick/ratatui_ruby/
+  homepage_uri: https://rooibos.run
   bug_tracker_uri: https://todo.sr.ht/~kerrick/ratatui_ruby
   mailing_list_uri: https://lists.sr.ht/~kerrick/ratatui_ruby-discuss
   source_code_uri: https://git.sr.ht/~kerrick/rooibos
@@ -237,5 +471,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Part of the RatatuiRuby ecosystem
+summary: "☕ Confidently Build Terminal Apps"
 test_files: []

data/doc/concepts/application_architecture.md

@@ -1,197 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Application Architecture
-
-Build robust TUI applications with Rooibos patterns.
-
-## Core Concepts
-
-_This section is incomplete. Check the source files._
-
-## Thread and Ractor Safety
-
-### The Strategic Context
-
-Ruby 4.0 introduces [Ractors](https://docs.ruby-lang.org/en/4.0/Ractor.html)—
-true parallel actors that forbid shared mutable state. Code that passes
-mutable objects between threads crashes in a Ractor world.
-
-Rooibos prepares you today. The runtime enforces Ractor-shareability on every
-Model and Message *now*, using standard threads. Pass a mutable object,
-and it raises an error immediately. Write Ractor-safe code today; upgrade
-to Ruby 4.0 without changes tomorrow.
-
-Enforce immutability rules before you strictly need them, and the migration
-is invisible.
-
-### The Problem
-
-Ruby's Ractor model prevents data races by forbidding shared mutable state.
-Mutable objects cause runtime errors:
-
-```
-RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
-```
-
-### The Solution
-
-Use `Ractor.make_shareable`. It recursively freezes everything:
-
-```ruby
-Ractor.make_shareable(model.with(text: "#{model.text}#{char}"))
-```
-
-For constants, wrap INITIAL:
-
-```ruby
-INITIAL = Ractor.make_shareable(
-  Model.new(text: "", running: false, chunks: [])
-)
-```
-
-For collection updates:
-
-```ruby
-new_chunks = Ractor.make_shareable([*model.chunks, new_item])
-```
-
-### The Lightweight Alternative
-
-When you know exactly what's mutable, `.freeze` is shorter:
-
-```ruby
-[model.with(text: "#{model.text}#{char}".freeze), nil]
-```
-
-### Foot-Guns
-
-#### frozen_string_literal Only Affects Literals
-
-The magic comment freezes strings that appear directly in source code.
-Computed strings are mutable.
-
-```ruby
-# frozen_string_literal: true
-
-"literal"        # frozen ✓
-"#{var}"         # mutable ✗
-str.chop         # mutable ✗
-str + other      # mutable ✗
-```
-
-#### Data.define Needs Shareable Values
-
-`Data.define` creates frozen instances. The instance is Ractor-shareable
-only when all its values are shareable.
-
-### Quick Reference
-
-| Pattern | Code |
-|---------|------|
-| Make anything shareable | `Ractor.make_shareable(obj)` |
-| Freeze a string | `str.freeze` |
-| INITIAL constant | `Ractor.make_shareable(Model.new(...))` |
-| Array update | `Ractor.make_shareable([*old, new])` |
-
-### Debugging
-
-See this error?
-
-```
-RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
-```
-
-Wrap the returned model with `Ractor.make_shareable`.
-
-## Modals and Command Result Routing
-
-Modals capture keyboard input. They overlay the main UI and intercept keypresses until dismissed. But async commands keep running in the background. When their results arrive, they look like any other message.
-
-It's tempting to intercept *all* messages when the modal is active. This swallows those command results.
-
-### The Scenario
-
-1. User presses "u" to fetch uptime. The runtime dispatches an async command.
-2. User presses "c" to open a modal dialog.
-3. The uptime command completes. It sends `[:network, :uptime, { stdout:, ... }]`.
-4. The modal intercept sees the modal is active. It routes that message to the modal.
-5. The modal ignores it.
-6. The uptime panel never updates.
-
-### The Fix
-
-Route command results before modal interception. Modals intercept user input, not async results.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# Wrong: modal intercepts everything
-UPDATE = lambda do |message, model|
-  if Modal.active?(model.modal)
-    # Swallows command results
-    return Modal::UPDATE.call(message, model.modal)
-  end
-
-  case message
-  in [:network, *rest]
-    # Never reached while modal is open
-  end
-end
-
-# Correct: route command results first
-UPDATE = lambda do |message, model|
-  # 1. Route async command results (always)
-  case message
-  in [:network, *rest]
-    return [model.with(network: new_network), command]
-  in [:stats, *rest]
-    return [model.with(stats: new_stats), command]
-  else
-    nil
-  end
-
-  # 2. Modal intercepts user input
-  if Modal.active?(model.modal)
-    return Modal::UPDATE.call(message, model.modal)
-  end
-
-  # 3. Handle other input
-  case message
-  in _ if message.q? then Command.exit
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-### The Router DSL
-
-`Rooibos::Router` handles this correctly. Routes declared with `route :prefix, to: ChildModule` process before keymap handlers. Command results flow through even when guards block keyboard input.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-
-```ruby
-
-module Dashboard
-  include Rooibos::Router
-
-  route :stats, to: StatsPanel
-  route :network, to: NetworkPanel
-
-  keymap do
-    only when: MODAL_INACTIVE do
-      key "u", -> { Uptime.fetch_command }
-    end
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->

data/doc/concepts/application_testing.md

@@ -1,49 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Application Testing Guide
-
-This guide explains how to test your RatatuiRuby applications using the provided `RatatuiRuby::TestHelper`.
-
-## Overview
-
-You need to verify that your application looks and behaves correctly. Manually checking every character on a terminal screen is tedious. Dealing with race conditions and complex state management in tests creates friction.
-
-The `TestHelper` module solves this. It provides a headless "test terminal" to capture output and a suite of robust assertions to verify state.
-
-Use it to write fast, deterministic tests for your TUI applications.
-
-## Setup
-
-First, require the test helper in your test file or `test_helper.rb`:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-require "ratatui_ruby/test_helper"
-require "minitest/autorun" # or your preferred test framework
-```
-<!-- SPDX-SnippetEnd -->
-
-Then, include the module in your test class:
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-class MyApplicationTest < Minitest::Test
-  include RatatuiRuby::TestHelper
-  # ...
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-## Writing Tests
-
-_Because this gem is in pre-release, it lacks documentation. Please check the source files and automated tests._