rooibos 0.5.0 → 0.6.1

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._

data/doc/concepts/async_work.md

@@ -1,164 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Async Work
-
-## Context
-
-Your application does concurrent work. It fetches from multiple APIs. It reads from sockets. It processes streams. These operations overlap in time.
-
-## Problem
-
-Threads are hard. Exceptions in spawned threads vanish silently. The main thread never learns what happened. Your application hangs, waiting for messages that will never arrive. Debugging this is miserable.
-
-## Solution
-
-Rooibos handles concurrency for you. Two patterns cover nearly every case. Use them instead of raw threads.
-
-## Pattern 1: Command Orchestration
-
-Compose child commands instead of spawning threads. Use <tt>out.source</tt> for sequential steps. Use <tt>Command.all</tt> for parallel steps.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-class LoadDashboard < Data.define(:user_id, :tag)
-  include Rooibos::Command::Custom
-
-  def call(out, token)
-    # Step 1: Authenticate (sequential - we need the token first)
-    auth = out.source(Authenticate.new(user_id:, tag: :_), token)
-    return if auth.nil? || token.canceled?
-
-    # Step 2: Fetch dashboard data in parallel, waiting for all to complete
-    dashboard = out.source(
-      Command.all(:_, [
-        FetchProfile.new(token: auth[:token], tag: :profile),
-        FetchNotifications.new(token: auth[:token], tag: :notifications),
-        FetchWeather.new(tag: :weather)
-      ]),
-      token
-    )
-    return if dashboard.nil? || token.canceled?
-
-    # Step 3: Send a message to the update with the dashboard data
-    out.put(tag, dashboard.results)
-    return if token.canceled?
-
-    # Step 4: Log the access (sequential - after we have data)
-    out.source(LogAccess.new(user_id:, tag: :_), token)
-    return if token.canceled?
-
-    # COMING SOON: out.source_nonblock
-    # Step 5: Watch for new data via HTTP Server-Sent Events, handling parallel streaming data
-    # 5a: Pass messages from the StreamNotifications custom command directly to LoadDashboard's out.put
-    notifications = out.source_nonblocki(
-      StreamNotifications.new(:user_id, auth[:token]),
-      token,
-    )
-    # 5b: Do work to the messages before sending them to the update function
-    deltas = out.source_nonblock(
-      StreamDashboardDeltas.new(dashboard.results[:profile][:id], auth[:token]),
-      token,
-      DeltaPostProcessor.new(:user_id)
-    )
-    # 5c: block this command on both async outsourced commands finishing
-    out.last(notifications, deltas)
-    return if token.canceled?
-
-    # Step 6: Log completion
-    out.source(LogAccess.new(user_id:, tag: :_, finished: true), token)
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-<tt>out.source</tt> blocks until the child command finishes. Pass <tt>Command.all</tt> to run children in parallel. Exceptions propagate correctly. Cancellation stops the workflow at any point.
-
-Use this for any multi-step workflow with dependencies between stages.
-
-## Pattern 2: Multiplexed I/O
-
-Read from multiple sources without threads. Ruby's <tt>IO.select</tt> waits for any of several IOs to become ready.
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-class MultiSocketReader < Data.define(:sockets, :tag)
-  include Rooibos::Command::Custom
-
-  def call(out, token)
-    remaining = sockets.dup
-
-    until remaining.empty? || token.canceled?
-      # Wait up to 0.1s for any socket to have data
-      ready = IO.select(remaining, nil, nil, 0.1)
-      next unless ready
-
-      ready[0].each do |socket|
-        data = socket.read_nonblock(4096, exception: false)
-        case data
-        when :wait_readable
-          next
-        when nil
-          remaining.delete(socket)
-        else
-          out.put(:data, { socket: socket, chunk: data })
-        end
-      end
-    end
-
-    out.put(tag, :complete)
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-<tt>IO.select</tt> multiplexes reads across sockets, pipes, or files. One thread handles many connections. No spawned threads means no silent failures.
-
-Use this for chat clients, log tailers, or any multi-stream scenario.
-
-## Why Not Threads?
-
-You might wonder: "Why can't I just spawn a thread?"
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```ruby
-# ❌ Don't do this
-def call(out, token)
-  Thread.new do
-    data = fetch_something
-    out.put(:result, data)
-  end
-end
-```
-<!-- SPDX-SnippetEnd -->
-
-This looks harmless. It hides a trap.
-
-If <tt>fetch_something</tt> raises, the exception happens in the spawned thread. Ruby logs it. The main thread never sees it. Your <tt>call</tt> method returns. The runtime considers the command complete. But <tt>out.put</tt> never ran. Your update function waits for <tt>:result</tt> forever.
-
-The runtime cannot protect you from this. Threads spawned inside your command escape its error handling. The framework wraps <tt>call</tt> in a rescue. It does not wrap threads you create.
-
-Use the patterns above instead. They keep errors visible.
-
-## Choosing the Right Pattern
-
-| Situation | Pattern |
-|-----------|---------|
-| Multi-step workflows | <tt>out.source</tt> + <tt>Command.all</tt> |
-| Read from multiple sockets/pipes | <tt>IO.select</tt> |
-| One blocking operation | Just do it in <tt>call</tt> |
-
-Commands already run off the main thread. You rarely need additional concurrency. When you do, these patterns handle the hard parts.