ratatui_ruby-tea 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c83e509aceb1826713abd9e4835055c1d28397627438d3041783564195b1821b
-  data.tar.gz: d452ab612362d0d3216101ab9d454c950a8af07afcd913c3fa8627e69eb09887
+  metadata.gz: fa0b4786fb2cf3f47481a630d0629da5870f2bcb5b2791a568760b3a20393724
+  data.tar.gz: 2e3064cfc39f24ea43ae1dc374d64b501723ca0c70d734446ba153388ee369d7
 SHA512:
-  metadata.gz: 6c211329907d95912192da187769d97ef56142cb4b1abe87ed2ed38c61b519d31f6823ab7f1154bc930e430b5fb19f1301c9497a9c68856c3c136c1ec0f6b962
-  data.tar.gz: 12b22830443dcc0783323bcccb8f2c1337a416cfe0cebaf89b0988d949f68e3ab73c4fbc37a6c140bc8b103465c8e467dad443654259961987dd91de7fa95767
+  metadata.gz: e3e093cdb72ceeb471c70e4ca2bfc8910a73229e514608a79873be5c3ab8acd414023ab0343dfc79546a8104c782a17d2dd770a6b8a054dc9e61a3646a9be5cf
+  data.tar.gz: af6f46ba59e0539b0d09025c63e9ca36df0035d000bced8fb4952065e5e4d275775ebdbca71afb53862063536f43b67e2574f00dd5aa53ba917af18c5e9bb560

data/AGENTS.md

@@ -34,8 +34,8 @@ Description: Part of the RatatuiRuby ecosystem.
 ### Tea-Specific Vocabulary
 
 - **BANNED WORD: "component"** — Reserved for Kit.
-- **Avoid "widget" for Tea units** — "Widget" refers to Engine/Ratatui render primitives. In Tea, call them **bags**.
-- **Bag:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Bags compose: parent bags delegate to child bags.
+- **Avoid "widget" for Tea units** — "Widget" refers to Engine/Ratatui render primitives. In Tea, call them **fragments**.
+- **Fragment:** A module containing `Model`, `INITIAL`, `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
@@ -66,3 +66,43 @@ Before considering a task complete and returning control to the user, you **MUST
 4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
   - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.
 
+## 4. Committing
+
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed..
+- When: Before reporting the task as complete to the user, suggest the commit message.
+- What: Consider not what you remember, but EVERYTHING in the `git diff` and `git diff --cached`.
+- **Format:**
+    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    - Body: Explanation if necessary (wrap at 72 chars).
+        - Explain why this is the implementation, as opposed to other possible implementations.
+        - Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
+        - **DON'T list the files changed or the edits made in the body.** Don't provide a bulleted list of changes. Use prose to explain the problem and the solution.
+        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links). The commit message must be plain text.
+- **Type conventions by directory:**
+    - `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+    - `bin/`, `tasks/`, `.builds/`, CI/CD: Use `chore` for tooling internal to developing this gem. Use `feat`/`fix` for user-facing executables or changes that affect downstream users.
+    - `examples/`: Always `docs` (documentation by example).
+    - `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
+    - `doc/`: Always `docs`.
+
+### 5. Changelog
+
+- Follow [Semantic Versioning](https://semver.org/)
+- Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specification.
+- **What belongs in CHANGELOG:** Only changes that affect **application developers** or **higher-level library developers** who use or depend on `ratatui_ruby`:
+    - New public APIs or widget parameters
+    - Backwards-incompatible type signature changes, or behavioral additions to type signature changes
+    - Observable behavior changes (rendering, styling, layout)
+    - Deprecations and removals
+    - Breaking changes
+- **What does NOT belong in CHANGELOG:** Internal or non-behavioral changes that don't affect downstream users:
+    - Test additions or improvements
+    - Documentation updates, RDoc fixes, markdown clarifications
+    - Refactors of internal code
+    - New or modified example code
+    - Internal tooling, CI/CD, or build configuration changes
+    - Code style or linting changes
+    - Performance improvements that affect applications
+- Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
+- The Unreleased section MUST be considered "since the last git tag". Therefore, if a change was done in one commit and undone in another (both since the last tag), the second commit should remove its changelog entry.
+- **Location:** New entries ALWAYS go in `## [Unreleased]`. Never edit past version sections (e.g., `## [0.4.0]`)—those are frozen history.

data/CHANGELOG.md

@@ -21,6 +21,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.4.0] - 2026-01-16
+
+### Added
+
+- **Timer Commands**: `Command.wait(seconds, tag)` and `Command.tick(seconds, tag)` for timed events. After the duration, sends `tag` to the update function. Responds to cancellation cooperatively — sends `Command.cancel(self)` when cancelled so you can handle it. Uses `Concurrent::Cancellation.timeout` internally. `Command.tick` is an alias for `Command.wait`; the "recurring tick" pattern is achieved by re-dispatching in the update function.
+
+- **Command.uncancellable Factory**: Creates a fresh `Concurrent::Cancellation` that never fires. Use for commands wrapping non-cancellable blocking I/O (e.g., `Net::HTTP` requests).
+
+- **Command.batch**: Fire-and-forget parallel execution. `Command.batch(cmd1, cmd2)` or `Command.batch([cmds])` runs children in parallel; each child sends its own messages independently. On cancellation, emits `Command.cancel(self)` so you can detect the batch was stopped. Child errors surface as `Command::Error` so you can handle failures in your update function. One failing child does not stop the others. Requires all child commands to be Ractor-shareable.
+
+- **Command.all**: Aggregating parallel execution. `Command.all(:tag, cmd1, cmd2)` or `Command.all(:tag, [cmds])` runs children in parallel and waits for all to complete, then sends a single aggregated message. Array syntax produces `[:tag, [results]]`; variadic syntax splats results as `[:tag, result1, result2]`. On cancellation, emits `Command.cancel(self)`. Child errors surface as `Command::Error`. Requires all child commands to be Ractor-shareable.
+
+- **Outlet#source**: Command composition for multi-step workflows. `out.source(child_command, token, timeout: 30.0)` runs a child command synchronously within a custom command, returning its result (or `nil` if cancelled/timed out). Exceptions from failed children propagate to the caller. Use this to orchestrate sequential API calls, conditional fetches, or any workflow that needs one result before starting the next.
+
+- **Command.http**: Native HTTP client for API calls. Supports GET, POST, PUT, PATCH, DELETE with DWIM syntax: `Command.http(get: 'url')`, `Command.http(:get, 'url', :tag)`, etc. Returns hash-based `HttpResponse` with `deconstruct_keys` for pattern matching: `{ type: :http, envelope:, status:, body:, headers: }` or `{ type: :http, envelope:, error: }`. Optional `parser:` keyword invokes a callable on the response body for JSON, YAML, CSV, or custom parsing. SSL, default 10s timeout, and cancellation-before-request are supported. Parsers and parsed results must be Ractor-shareable.
+
+- **Streaming Command Data Loss Fix**: Fixed race condition in `Command.system(stream: true)` where fast commands could lose stdout/stderr data. Reader threads now `join` instead of `kill` to ensure all output is processed before completion.
+
+- **Message::Predicates Mixin**: Include in custom message types for safe predicate calls. Returns `false` for any unknown predicate method (ending in `?`). Enables pattern matching workflows where messages can respond to predicates like `msg.http?` or `msg.timer?` without raising `NoMethodError`. Includes `respond_to_missing?` for introspection parity.
+
+- **Message::Timer**: Predicate-rich response type for timer commands (`Command.wait`, `Command.tick`). Includes `timer?` predicate and `deconstruct_keys` for pattern matching with `type: :timer` discriminator. Contains `envelope` (routing symbol) and `elapsed` (actual wait time in seconds).
+
+- **Message::HttpResponse**: Moved from `Command::HttpResponse` to `Message::HttpResponse` with added predicates. Includes `http?`, `success?`, and `error?` predicates. Implements `deconstruct_keys` for pattern matching with `type: :http` discriminator.
+
+- **Message::System::Batch**: Response type for `Command.system` (batch mode). Includes `system?`, `success?` (exit 0), and `error?` (non-zero exit) predicates. Contains `envelope`, `stdout`, `stderr`, and `status`. Implements `deconstruct_keys` for pattern matching.
+
+- **Message::System::Stream**: Response type for `Command.system(..., stream: true)`. Includes `system?`, `stdout?`, `stderr?`, and `complete?` predicates. Contains `envelope`, `stream` type (`:stdout`, `:stderr`, `:complete`), `content` (for output lines), and `status` (for completion). Implements conditional `deconstruct_keys` based on stream type.
+
+- **Message::All**: Response type for `Command.all` aggregating parallel execution. Includes `all?` predicate. Contains `envelope`, `results` array, and `nested` boolean. Implements `deconstruct_keys` for pattern matching.
+
+- **Command Parameter Rename**: Renamed `tag` parameter to `envelope` across all commands for consistency: `Command.wait`, `Command.tick`, `Command.system`, and `Command.all`. These now use `envelope:` in their data definitions. Messages emit with `envelope:` for pattern matching.
+
+- **Dependencies**: Added `concurrent-ruby` (~> 1.3) and `concurrent-ruby-edge` (~> 0.7) for robust concurrency primitives.
+
+- **Tea.normalize_init Helper**: New `RatatuiRuby::Tea.normalize_init(result)` normalizes Init callable returns. Accepts the output of a `Fragment.Init` callable and always returns `[model, command]`. Use when composing child fragment initialization in parent fragments.
+
+### Changed
+
+- **Terminology: "Bag" → "Fragment"**: Renamed Fractal Architecture units from "bags" to "fragments" throughout the codebase. A fragment is a module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Parent fragments compose child fragments via routing. The `examples/app_fractal_dashboard/bags/` directory is now `examples/app_fractal_dashboard/fragments/`. All API documentation, code comments, and examples updated to reflect this terminology change.
+
+- **Runtime API Signature (Breaking)**: `Tea.run` signature changed:
+  - Fragment parameter is now **positional** instead of keyword: `Tea.run(MyApp)` instead of `Tea.run(fragment: MyApp)`
+  - Removed `argv:` and `env:` parameters - Runtime now automatically uses `ARGV` and `ENV` globals
+  - Added `fps:` parameter (default 60) for configurable frame rate
+  - Renamed `init:` parameter to `command:` in explicit parameters API for clarity
+
+- **Fragment Convention Rename (Breaking)**: Fragment constants have new naming conventions:
+  - `INITIAL` constant → `Init` callable. The runtime calls `Init.()` to get the initial model.
+  - `UPDATE` constant → `Update` callable (capitalized).
+  - `VIEW` constant → `View` callable (capitalized).
+  - Init is now a lambda/callable instead of a frozen constant. This enables parameterized initialization and returning `[model, command]` tuples for initial commands.
+
+- **Internal Method Rename (Breaking)**: `Runtime.normalize_update_result` renamed to `Runtime.normalize_update_return` for clarity. Only affects code calling private Runtime internals.
+
+- **Command.custom Ractor Validation (Breaking)**: `Command.custom(callable)` now validates in debug mode that the callable is Ractor-shareable. Callables that capture mutable state will raise `Invariant`. Define callables at module level or use `Ractor.make_shareable`.
+
+- **Model Validation Timing (Breaking)**: Runtime now validates model Ractor-shareability **immediately after Init returns**, not just during the Update cycle. This catches mutable models earlier, enforcing immutability at startup. Models must be frozen (`.freeze`) or use immutable data structures (`Data.define`). This is a good breaking change that prevents subtle concurrency bugs.
+
+- **CancellationToken Replaced (Breaking)**: Custom commands now receive `Concurrent::Cancellation` instead of `CancellationToken`. The method to check cancellation changes from `token.cancelled?` (British) to `token.canceled?` (American).
+
+- **Outlet Accepts Channel (Breaking)**: `Outlet.new` now accepts a `Concurrent::Promises::Channel` instead of `Thread::Queue`.
+
+- **Outlet#put (Breaking)**: `out.put(msg)`, the common case now sends `msg` directly instead of `[msg]`; `out.put(a, b, c)` sends `[a, b, c]`. Previously all calls wrapped arguments in an array. Update functions that matched `when Array` may need adjustment.
+
+- **Command.all Output (Breaking)**: `Command.all` now emits `Message::All` objects instead of raw arrays. Previously emitted `[:tag, [results]]` (nested) or `[:tag, result1, result2]` (variadic). Now emits `Message::All` with `envelope`, `results`, and `nested` fields. Use hash pattern matching: `in { type: :all, envelope:, results:, nested: }`.
+
+### Fixed
+
+- **Streaming Command Data Loss**: Fixed race condition where fast commands (e.g., `echo hello`) could lose stdout/stderr messages. The streaming reader threads were being killed immediately after the child process exited, before they could finish reading buffered output. Now the runtime joins the reader threads to ensure all data is processed before sending `:complete`.
+
+### Removed
+
+- **CancellationToken Class**: Removed in favor of `Concurrent::Cancellation` from concurrent-ruby-edge.
+- **CancellationToken::NONE**: Removed. Use `Command.uncancellable` factory instead.
+
 ## [0.3.1] - 2026-01-11
 
 ### Added
@@ -115,6 +190,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **First Release**: Empty release of `ratatui_ruby-tea`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/HEAD
+[0.4.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.4.0
 [0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.1
 [0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0

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]
-> **ratatui_ruby-tea** is currently in **PRE-RELEASE**. The API will change rapidly, even between minor and patch versions.
+> **ratatui_ruby-tea** is currently in **ALPHA**. 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.
 
@@ -107,9 +107,12 @@ gem install ratatui_ruby-tea
 <!-- SYNC:START:examples/verify_readme_usage/app.rb:mvu -->
 ```ruby
 Model = Data.define(:text)
-MODEL = Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
 
-VIEW = -> (model, tui) do
+Init = -> do
+  Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
+end
+
+View = -> (model, tui) do
   tui.paragraph(
     text: model.text,
     alignment: :center,
@@ -121,7 +124,7 @@ VIEW = -> (model, tui) do
   )
 end
 
-UPDATE = -> (msg, model) do
+Update = -> (msg, model) do
   if msg.q? || msg.ctrl_c?
     RatatuiRuby::Tea::Command.exit
   else
@@ -130,7 +133,7 @@ UPDATE = -> (msg, model) do
 end
 
 def run
-  RatatuiRuby::Tea.run(model: MODEL, view: VIEW, update: UPDATE)
+  RatatuiRuby::Tea.run(VerifyReadmeUsage)
 end
 ```
 <!-- SYNC:END -->

data/doc/concepts/async_work.md

@@ -0,0 +1,164 @@
+<!--
+  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
+
+Tea 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 RatatuiRuby::Tea::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 RatatuiRuby::Tea::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.