ratatui_ruby 1.0.0 → 1.1.0

data/doc/contributors/todo/align/term.md

@@ -0,0 +1,351 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# TERM Environment Variable Respect
+
+Expose terminal capability detection so applications can degrade gracefully.
+
+---
+
+## Crossterm Audit (2026-01-17)
+
+What crossterm actually exposes that we can wrap:
+
+### Available Public APIs
+
+| Function | Location | Notes |
+|----------|----------|-------|
+| `available_color_count()` | `src/style.rs:163` | Returns `u16`: 8, 256, or `u16::MAX` (truecolor). Checks `COLORTERM`, `TERM` env vars. |
+| `force_color_output(bool)` | `src/style.rs:191` | Override `NO_COLOR` check globally. |
+| `supports_keyboard_enhancement()` | `src/terminal/sys/unix.rs:188` | Requires `events` feature. Queries terminal via escape sequence. |
+| `window_size()` | `src/terminal.rs:148` | Returns `WindowSize { columns, rows, width, height }` including **pixel dimensions**. |
+| `supports_ansi()` | `src/ansi_support.rs:33` | **Windows only**. Checks VT processing + `TERM != "dumb"`. |
+
+### Internal Logic (Not Exposed, But Informs Design)
+
+From `src/style.rs:174-180`:
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```rust
+env::var("COLORTERM")
+    .or_else(|_| env::var("TERM"))
+    .map_or(DEFAULT, |x| match x {
+        _ if x.contains("24bit") || x.contains("truecolor") => u16::MAX,
+        _ if x.contains("256") => 256,
+        _ => DEFAULT,  // 8 colors
+    })
+```
+<!-- SPDX-SnippetEnd -->
+
+From `src/ansi_support.rs:39-40` (Windows):
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```rust
+let supported = enable_vt_processing().is_ok()
+    || std::env::var("TERM").map_or(false, |term| term != "dumb");
+```
+<!-- SPDX-SnippetEnd -->
+
+### What Ratatui Exposes
+
+The `Backend` trait in `ratatui-core/src/backend.rs` exposes:
+- `size()` → `Result<Size>` (columns/rows)
+- `window_size()` → `Result<WindowSize>` (columns/rows + pixels)
+
+**No capability detection is exposed through ratatui itself.** We must call crossterm directly.
+
+### Audit Summary
+
+| Proposed API | Implementation | Source |
+|--------------|----------------|--------|
+| `tty?` | Pure Ruby | `$stdout.tty?` |
+| `dumb?` | Pure Ruby | `ENV["TERM"]` |
+| `no_color?` | Pure Ruby | `ENV.key?("NO_COLOR")` |
+| `force_color?` | Pure Ruby | `ENV.key?("FORCE_COLOR")` |
+| `color_support` | **Wrap crossterm** | `crossterm::style::available_color_count()` |
+| `supports_keyboard_enhancement?` | **Wrap crossterm** | `crossterm::terminal::supports_keyboard_enhancement()` |
+| `size_pixels` | **Wrap crossterm** | `crossterm::terminal::window_size().{width,height}` |
+| `interactive?` | Pure Ruby | Combines `tty?` + `dumb?` |
+| `suggested_style` | Pure Ruby | Derives from `color_support` |
+
+---
+
+## Problem Statement
+
+Rust-based CLI libraries often ignore the `TERM` environment variable and assume modern terminal features. This causes issues in:
+
+- **CI environments** — `TERM=dumb` or missing entirely
+- **Piped output** — stdout isn't a TTY
+- **Legacy terminals** — SSH to old systems, embedded devices
+- **Accessibility** — Screen readers need simpler output
+- **`NO_COLOR` movement** — Users explicitly disable color
+
+RatatuiRuby currently provides no capability detection APIs. Applications cannot query terminal support before rendering.
+
+---
+
+## Proposed API
+
+> [!NOTE]
+> These capability detection methods integrate with the `Terminal` class design from [terminal.md](terminal.md).
+> They are **class methods** on `RatatuiRuby::Terminal`, not a separate module.
+
+### Phase 1: Environment Detection (Ruby-side)
+
+Pure Ruby class methods using environment variables and standard library.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# lib/ratatui_ruby/terminal.rb (additions to existing Terminal class)
+module RatatuiRuby
+  class Terminal
+    class << self
+      # Is stdout connected to a terminal?
+      def tty? = $stdout.tty?
+
+      # Is this a dumb terminal with no capabilities?
+      def dumb? = ENV["TERM"] == "dumb" || ENV["TERM"].to_s.empty?
+
+      # Should color be disabled? (NO_COLOR standard)
+      def no_color? = ENV.key?("NO_COLOR")
+
+      # Should color be forced? (overrides tty? check)
+      def force_color? = ENV.key?("FORCE_COLOR")
+
+      # Detected color support level
+      # :none    - No color (dumb terminal, NO_COLOR set, not a tty)
+      # :basic   - 16 colors (standard ANSI)
+      # :ansi256 - 256 colors
+      # :truecolor - 24-bit RGB
+      def color_support
+        return :none if no_color? || dumb?
+        return detect_color_level if tty? || force_color?
+        :none
+      end
+
+      private
+
+      def detect_color_level
+        colorterm = ENV["COLORTERM"]
+        return :truecolor if colorterm == "truecolor" || colorterm == "24bit"
+
+        term = ENV["TERM"].to_s
+        return :truecolor if term.include?("truecolor") || term.include?("24bit")
+        return :ansi256 if term.include?("256color")
+        return :basic if term.start_with?("xterm", "screen", "vt100", "linux")
+
+        :basic # Conservative default for unknown terminals
+      end
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### Phase 2: Crossterm Capability Queries (Rust-side)
+
+Expose crossterm's runtime detection through Magnus bindings.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```rust
+// ext/ratatui_ruby/src/terminal_capabilities.rs
+
+use crossterm::terminal;
+use magnus::{function, Error, Module, Object};
+
+/// Query if the terminal supports the Kitty keyboard protocol
+pub fn supports_keyboard_enhancement() -> Result<bool, Error> {
+    Ok(terminal::supports_keyboard_enhancement()
+        .map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?)
+}
+
+/// Query terminal size in pixels (if supported)
+pub fn terminal_size_pixels() -> Result<Option<(u16, u16)>, Error> {
+    match crossterm::terminal::window_size() {
+        Ok(size) => Ok(Some((size.width, size.height))),
+        Err(_) => Ok(None),
+    }
+}
+
+pub fn register(ruby: &magnus::Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    module.define_module_function("_supports_keyboard_enhancement", 
+        function!(supports_keyboard_enhancement, 0))?;
+    module.define_module_function("_terminal_size_pixels",
+        function!(terminal_size_pixels, 0))?;
+    Ok(())
+}
+```
+<!-- SPDX-SnippetEnd -->
+
+Ruby wrapper (class methods on Terminal):
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# lib/ratatui_ruby/terminal.rb (continued)
+module RatatuiRuby
+  class Terminal
+    class << self
+      # Does the terminal support the Kitty keyboard protocol?
+      def supports_keyboard_enhancement?
+        RatatuiRuby._supports_keyboard_enhancement
+      rescue
+        false
+      end
+
+      # Terminal size in pixels (for graphics protocols)
+      # Returns { width:, height: } or nil if unsupported
+      def size_pixels
+        result = RatatuiRuby._terminal_size_pixels
+        result ? { width: result[0], height: result[1] } : nil
+      rescue
+        nil
+      end
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### Phase 3: Graceful Degradation Helpers
+
+Convenience class methods for common patterns.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# lib/ratatui_ruby/terminal.rb (continued)
+module RatatuiRuby
+  class Terminal
+    class << self
+      # Should the application use TUI mode?
+      # Returns false for dumb terminals, piped output, etc.
+      def interactive?
+        tty? && !dumb?
+      end
+
+      # Suggested style based on terminal capabilities
+      def suggested_style
+        case color_support
+        when :none then :plain
+        when :basic then :ansi16
+        when :ansi256 then :ansi256
+        when :truecolor then :truecolor
+        end
+      end
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+---
+
+## Implementation Plan
+
+### Phase 1: Environment Detection
+
+| File | Change |
+|------|--------|
+| [NEW] `lib/ratatui_ruby/terminal.rb` | `Terminal` module with `tty?`, `dumb?`, `no_color?`, `force_color?`, `color_support` |
+| [NEW] `sig/ratatui_ruby/terminal.rbs` | RBS type declarations |
+| [NEW] `test/test_terminal_capabilities.rb` | Unit tests with mocked ENV |
+| [MODIFY] `lib/ratatui_ruby.rb` | Require the new module |
+
+### Phase 2: Crossterm Queries
+
+| File | Change |
+|------|--------|
+| [NEW] `ext/ratatui_ruby/src/terminal_capabilities.rs` | `supports_keyboard_enhancement`, `terminal_size_pixels` |
+| [MODIFY] `ext/ratatui_ruby/src/lib.rs` | Register new module |
+| [MODIFY] `lib/ratatui_ruby/terminal.rb` | Add `supports_keyboard_enhancement?`, `size_pixels` |
+| [MODIFY] `sig/ratatui_ruby/terminal.rbs` | Add new method types |
+| [MODIFY] `test/test_terminal_capabilities.rb` | Add integration tests |
+
+### Phase 3: Convenience Methods
+
+| File | Change |
+|------|--------|
+| [MODIFY] `lib/ratatui_ruby/terminal.rb` | Add `interactive?`, `suggested_style` |
+| [MODIFY] `sig/ratatui_ruby/terminal.rbs` | Add new method types |
+| [MODIFY] `test/test_terminal_capabilities.rb` | Add convenience method tests |
+
+---
+
+## Documentation Updates
+
+| File | Change |
+|------|--------|
+| [NEW] `doc/concepts/terminal_capabilities.md` | Guide for capability detection |
+| [MODIFY] `doc/troubleshooting/terminal_limitations.md` | Reference new detection APIs |
+| [MODIFY] `CHANGELOG.md` | Document new feature |
+
+---
+
+## Verification Plan
+
+### Automated Tests
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+bundle exec rake test TEST=test/test_terminal_capabilities.rb
+bundle exec steep check
+```
+<!-- SPDX-SnippetEnd -->
+
+### Manual Verification
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+# Test NO_COLOR respect
+NO_COLOR=1 bundle exec ruby -e "require 'ratatui_ruby'; p RatatuiRuby::Terminal.color_support"
+# Expected: :none
+
+# Test dumb terminal
+TERM=dumb bundle exec ruby -e "require 'ratatui_ruby'; p RatatuiRuby::Terminal.dumb?"
+# Expected: true
+
+# Test truecolor detection
+COLORTERM=truecolor bundle exec ruby -e "require 'ratatui_ruby'; p RatatuiRuby::Terminal.color_support"
+# Expected: :truecolor
+```
+<!-- SPDX-SnippetEnd -->
+
+---
+
+## References
+
+- [NO_COLOR Standard](https://no-color.org/)
+- [Crossterm Terminal Queries](https://docs.rs/crossterm/latest/crossterm/terminal/index.html)
+- [Kitty Keyboard Protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)
+- [terminfo(5)](https://man7.org/linux/man-pages/man5/terminfo.5.html)

data/doc/contributors/upstream_requests/paragraph_span_rects.md

@@ -0,0 +1,259 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Feature Request: Expose Paragraph Span Rects
+
+## Summary
+
+`Paragraph` computes the bounding rect for each span during word-wrapping and rendering, but does not expose this information. Interactive applications need these rects for:
+
+- Mouse click hit-testing on clickable text (links, buttons)
+- Accessibility tooling that needs semantic element positions
+- Tooltip positioning relative to specific text spans
+
+## The Problem
+
+Building clickable text within paragraphs requires knowing where each span renders after word wrapping. When a user clicks within a paragraph, the application cannot determine which specific span was clicked without duplicating the internal word-wrapping algorithm.
+
+Currently, the only options are:
+
+1. **Recompute the layout manually.** Duplicate the logic from `WordWrapper` and `LineTruncator`, accounting for word boundaries, trimming, and alignment. This is extremely fragile—the wrapping algorithm is complex and any upstream change breaks the user's code.
+
+2. **Use character counting.** Calculate `chars_before / width` for y-offset and `chars_before % width` for x-offset. This breaks with:
+   - Non-monospace Unicode (CJK, emoji)
+   - Word-level wrapping (spans don't split at character boundaries)
+   - Alignment (center/right shifts all positions)
+   - Trimmed leading whitespace
+
+Neither approach is satisfactory.
+
+## Use Case
+
+Consider a TUI welcome screen with a clickable link:
+
+```
+┌Hello, Rooibos!───────────────────────────────────────┐
+│                                                       │
+│ Welcome to Rooibos! You will find the Ruby code for  │
+│ this application in lib/saturday.rb. The tests that  │
+│ verify it are at test/test_saturday.rb. You can run  │
+│ the tests with bundle exec rake test. Visit          │
+│  www.rooibos.run  to learn about Rooibos and to find │
+│ other Rooibos developers. You can press Control + C  │
+│ to exit at any time.                                  │
+│                                                       │
+└───────────────────────────────────────────────────────┘
+```
+
+The link ` www.rooibos.run ` appears on row 5 after word-wrapping. The application wants to:
+
+1. Detect clicks on the link span
+2. Highlight the link on hover
+3. Open the URL when clicked
+
+Without span rects, the application must manually compute where the link renders after wrapping:
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2026 Kerrick Long
+SPDX-License-Identifier: MIT-0
+-->
+```rust
+// Manual calculation - fragile and duplicates internal logic
+let text_before_link = "Welcome to Rooibos! You will find the Ruby code for \
+    this application in lib/saturday.rb. The tests that verify it are at \
+    test/test_saturday.rb. You can run the tests with bundle exec rake test. Visit ";
+let chars_before = text_before_link.width(); // ~204 characters
+let inner_width = block.inner(area).width; // ~74 characters
+
+let y_offset = chars_before / inner_width; // Wrong: doesn't account for word wrapping
+let x_offset = chars_before % inner_width; // Wrong: words don't wrap mid-word
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+This fails because `WordWrapper`:
+
+- Wraps at word boundaries, not character positions
+- May trim leading whitespace on wrapped lines
+- Produces lines of varying length
+
+The computed position is always wrong by several cells.
+
+## Current State (v0.30.0)
+
+`Paragraph::render_paragraph` uses `WordWrapper` or `LineTruncator` to compose lines:
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2016-2022 Florian Dehau
+SPDX-FileCopyrightText: 2023-2025 The Ratatui Developers
+SPDX-License-Identifier: MIT
+-->
+```rust
+// From src/widgets/paragraph.rs - private rendering logic
+fn render_paragraph(&self, text_area: Rect, buf: &mut Buffer) {
+    let styled = self.text.iter().map(|line| {
+        let graphemes = line.styled_graphemes(self.text.style);
+        let alignment = line.alignment.unwrap_or(self.alignment);
+        (graphemes, alignment)
+    });
+
+    if let Some(Wrap { trim }) = self.wrap {
+        let mut line_composer = WordWrapper::new(styled, text_area.width, trim);
+        render_lines(line_composer, text_area, buf);
+    } else {
+        // ...LineTruncator path...
+    }
+}
+
+fn render_line(wrapped: &WrappedLine<'_, '_>, area: Rect, buf: &mut Buffer, y: u16) {
+    let mut x = get_line_offset(wrapped.width, area.width, wrapped.alignment);
+    for StyledGrapheme { symbol, style } in wrapped.graphemes {
+        // Position is computed here but not exposed
+        let position = Position::new(area.left() + x, area.top() + y);
+        buf[position].set_symbol(symbol).set_style(*style);
+        x += u16::try_from(width).unwrap_or(u16::MAX);
+    }
+}
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+The grapheme positions are computed during rendering but never associated back to the source spans.
+
+## Proposed API
+
+Following the pattern established by `Block::inner(area)` and `Layout::split()`, add a pure computation method that takes an area and returns computed span rects without rendering:
+
+### Option 1: Return all span rects
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2026 Kerrick Long
+SPDX-License-Identifier: MIT-0
+-->
+```rust
+impl Paragraph {
+    /// Returns the bounding rect for each span given an area.
+    ///
+    /// For wrapped paragraphs, a span that wraps across multiple lines
+    /// returns a rect covering all lines it occupies.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let link_span = Span::styled(" www.rooibos.run ", Style::new().underlined());
+    /// let text = Text::from(Line::from(vec![
+    ///     Span::raw("Visit "),
+    ///     link_span.clone(),
+    ///     Span::raw(" for more info."),
+    /// ]));
+    /// let paragraph = Paragraph::new(text).wrap(Wrap { trim: true });
+    ///
+    /// let span_rects = paragraph.span_rects(area);
+    /// if span_rects[1].contains(mouse_position) {
+    ///     // User clicked the link!
+    /// }
+    /// ```
+    pub fn span_rects(&self, area: Rect) -> Vec<Rect> { ... }
+}
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+### Option 2: Lookup by span index
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2026 Kerrick Long
+SPDX-License-Identifier: MIT-0
+-->
+```rust
+/// Returns the rect for the span at the given index.
+pub fn span_rect(&self, area: Rect, line_index: usize, span_index: usize) -> Option<Rect> { ... }
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+### Option 3: Iterator-based (memory efficient)
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2026 Kerrick Long
+SPDX-License-Identifier: MIT-0
+-->
+```rust
+/// Returns an iterator over (line_index, span_index, Rect) tuples.
+pub fn span_rects_iter(&self, area: Rect) -> impl Iterator<Item = (usize, usize, Rect)> { ... }
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+## Implementation Notes
+
+The implementation would reuse `WordWrapper`/`LineTruncator` in a non-rendering mode:
+
+1. Process the text through the line composer (same as `render_paragraph`)
+2. Track grapheme positions as they're composed (same loop as `render_line`)
+3. Group grapheme positions by source span
+4. Return span bounding rects
+
+Key considerations:
+
+- **Wrapped spans**: A span that wraps to the next line should return a rect covering both lines (bounding box) or multiple rects (one per line fragment)
+- **Empty spans**: Zero-width spans should return the position where they would appear
+- **Scroll offset**: Rects should be adjusted by the paragraph's scroll offset
+- **Block**: The area should be the inner area after block borders/padding
+
+## Workaround
+
+Without this API, users must reimplement word wrapping. This is impractical for production use—the workaround in RatatuiRuby uses simple character math that produces incorrect positions:
+
+<!--
+SPDX-SnippetBegin
+SPDX-FileCopyrightText: 2026 Kerrick Long
+SPDX-License-Identifier: MIT-0
+-->
+```rust
+// This is WRONG but the only option without span_rects
+let chars_before = preceding_spans.iter().map(|s| s.width()).sum();
+let x = area.x + (chars_before % area.width);
+let y = area.y + (chars_before / area.width);
+```
+<!--
+SPDX-SnippetEnd
+-->
+
+The correct implementation requires processing the entire text through `WordWrapper`, which is private.
+
+## Impact
+
+This feature benefits any application with clickable or interactive text:
+
+- **Hyperlinks**: Click to open URLs in wrapped text
+- **Command help**: Click command names to execute them
+- **Error messages**: Click file paths to open editors
+- **Documentation viewers**: Interactive code examples
+- **Accessibility**: Screen readers need element positions
+
+Rich text interaction is a natural expectation for modern TUI applications. Word-wrapped paragraphs with clickable elements are common in web UIs—TUIs should offer the same capability.
+
+## Related
+
+- `Block::inner(area)` - Same pattern: pure computation of content area
+- `Layout::split(area, constraints)` - Same pattern: pure computation of child areas
+- `Tabs::title_rects(area)` (proposed in separate issue) - Same pattern for tab hit-testing
+
+---
+
+This issue includes creative contributions from Claude (Anthropic) via Antigravity (Google). [https://declare-ai.org/1.0.0/creative.html](https://declare-ai.org/1.0.0/creative.html)
+
+*Discovered while implementing link click handling for RatatuiRuby's Saturday demo app.*

data/doc/getting_started/quickstart.md

@@ -8,7 +8,7 @@ Welcome to **ratatui_ruby**! This guide will help you get up and running with yo
 
 ## Installation
 
-See [Installation in the README](../README.md#installation) for setup instructions.
+See [Installation in the README](../../README.md#installation) for setup instructions.
 
 
 ## Tutorials

data/doc/getting_started/why.md

@@ -24,7 +24,7 @@ RatatuiRuby gives you Rust's layout engine, rendering speed, and battle-tested w
 
 ## RatatuiRuby vs. CharmRuby
 
-[CharmRuby](https://github.com/marcoroth/charm_ruby) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
+[CharmRuby](https://charm-ruby.dev) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
 
 So which one should you choose?
 
@@ -65,8 +65,8 @@ With RatatuiRuby, there's only Ruby. Rust compiles to plain machine code with no
 
 - **[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html)** — Query your database with elegant, chainable methods
 - **[RSpec](https://rspec.info/)** — Write expressive, readable tests with `describe`, `it`, and `expect`
-- **[Blocks](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/blocks.html)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
-- **[Metaprogramming](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/objinitialization.html)** — Define methods dynamically, build DSLs, and write code that writes code
+- **[Blocks](https://docs.ruby-lang.org/en/4.0/syntax/calling_methods_rdoc.html#label-Block+Argument)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
+- **[Metaprogramming](https://docs.ruby-lang.org/en/4.0/Module.html#method-i-class_eval)** — Define methods dynamically, build DSLs, and write code that writes code
 - **[Bundler](https://bundler.io/)** — Access 180,000+ gems with a single `bundle add`
 
 Build a dashboard for your Rails app. Monitor your Sidekiq jobs. Create developer tools in the same language as the code they inspect.

data/doc/index.md

@@ -25,14 +25,9 @@
 
 ### Troubleshooting
 
-- [Debugging](./troubleshooting/debugging.md): Debugging techniques and tools
+- [Debugging](./concepts/debugging.md): Debugging techniques and tools
 - [Terminal Limitations](./troubleshooting/terminal_limitations.md): Platform quirks and workarounds
 
-### Migration
-
-- [Migrating to v0.7.0](./migration/v0_7_0.md): Namespace changes and upgrade guide
-
-
 ## Documentation for Contributors
 
 - [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features