ratatui_ruby 0.9.1 → 0.10.0

data/doc/getting_started/quickstart.md

@@ -258,20 +258,25 @@ These larger examples combine widgets into complete applications, demonstrating
 |-------------|--------------|-------------------|
 | [All Events](../examples/app_all_events/app.rb) | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
 | [Color Picker](../examples/app_color_picker/app.rb) | Component-Based | Hit testing, modal dialogs, encapsulated state |
+| [Debugging Showcase](../examples/app_debugging_showcase/app.rb) | Simple Loop | Remote debugging, Rust backtraces, improved error messages |
 | [Login Form](../examples/app_login_form/app.rb) | Overlay + Center | Modal forms, cursor positioning, text input |
 | [Stateful Interaction](../examples/app_stateful_interaction/app.rb) | State Objects | ListState/TableState, offset read-back, mouse click-to-row |
 
 #### All Events
 
-[![all_events](./images/app_all_events.png)](../examples/app_all_events/README.md)
+[![all_events](../images/app_all_events.png)](../examples/app_all_events/README.md)
 
 #### Color Picker
 
-[![color_picker](./images/app_color_picker.png)](../examples/app_color_picker/README.md)
+[![color_picker](../images/app_color_picker.png)](../examples/app_color_picker/README.md)
+
+#### Debugging Showcase
+
+[![debugging_showcase](../images/app_debugging_showcase.gif)](../examples/app_debugging_showcase/README.md)
 
 #### Login Form
 
-[![login_form](./images/app_login_form.png)](../examples/app_login_form/README.md)
+[![login_form](../images/app_login_form.png)](../examples/app_login_form/README.md)
 
 
 ## Next Steps

data/doc/troubleshooting/async.md

@@ -0,0 +1,4 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->

data/examples/app_debugging_showcase/README.md

@@ -0,0 +1,119 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Debugging Showcase
+
+[![Debugging Showcase](../../doc/images/app_debugging_showcase.gif)](app.rb)
+
+Interactive demonstration of RatatuiRuby's debugging features.
+
+For comprehensive documentation, see the [Debugging Guide](../../doc/concepts/debugging.md).
+
+## What This Example Does
+
+This app lets you trigger each debugging feature with a hotkey. Test your setup before encountering a real bug.
+
+| Key | Action |
+|-----|--------|
+| `d` | Enable `debug_mode!` programmatically |
+| `p` | Trigger a Rust panic |
+| `t` | Trigger a Rust `TypeError` |
+| `b` | Refresh debug status |
+| `q` | Quit |
+
+## Library Features Showcased
+
+Reading this code will teach you how to:
+
+*   **Enable Remote Debugging**: Call `RatatuiRuby.debug_mode!` and receive the socket path
+*   **Detect Debug State**: Query `Debug.enabled?`, `Debug.rust_backtrace_enabled?`, and `Debug.remote_debugging_mode`
+*   **Trigger Test Panics**: Use `Debug.test_panic!` to verify Rust backtrace visibility
+*   **See Improved Error Messages**: Bypass DWIM coercion to see `TypeError` messages with value context
+
+**Note:** Rust backtraces only appear for panics (`[p]`). Exceptions (`[t]`) show Ruby backtraces with improved error messages from Rust.
+
+## Environment Variables
+
+The example behaves differently depending on which environment variables you set.
+
+### No Environment Variables
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+ruby examples/app_debugging_showcase/app.rb
+```
+<!-- SPDX-SnippetEnd -->
+
+The TUI starts normally. Rust backtraces are disabled. Press `[d]` to enable remote debugging mid-session.
+
+### `RUST_BACKTRACE=1`
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+RUST_BACKTRACE=1 ruby examples/app_debugging_showcase/app.rb
+```
+<!-- SPDX-SnippetEnd -->
+
+Enables Rust backtraces. Press `[p]` to see the full Rust stack trace with file names and line numbers.
+
+### `RR_DEBUG=1`
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+RR_DEBUG=1 ruby examples/app_debugging_showcase/app.rb
+```
+<!-- SPDX-SnippetEnd -->
+
+Full debug mode at startup. The debugger opens a socket and **waits for a connection** before the TUI starts. You'll see the socket path printed before the app runs.
+
+In another terminal:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+rdbg --attach
+```
+<!-- SPDX-SnippetEnd -->
+
+When you attach, you'll see "Stop by SIGURG" — that's normal! SIGURG is how the debug gem signals the app to pause. Type `continue` to resume.
+
+This uses the [ruby/debug](https://github.com/ruby/debug?tab=readme-ov-file#readme) gem for remote debugging.
+
+### When to Use Which
+
+`RR_DEBUG=1` includes Rust backtraces automatically (it calls `enable_rust_backtrace!` internally).
+
+Use `RUST_BACKTRACE=1` alone when you want backtraces but **don't** want the debugger to stop and wait for a connection at startup.
+
+## What Problems Does This Solve?
+
+### "Is my Rust backtrace setup working?"
+
+Press `[p]`. If you see a stack trace with file names and line numbers, you're good. If not, you need `RUST_BACKTRACE=1`.
+
+### "How do I attach a debugger to a TUI?"
+
+TUIs run in raw mode — you can't type into a REPL. Press `[d]` to enable remote debugging. The socket path appears in the UI. Run `rdbg --attach` from another terminal.
+
+### "What does a Rust TypeError look like?"
+
+Press `[t]`. The error message shows the expected type and the actual value you passed (e.g., `expected array for rows, got 42`). Note: This shows Ruby's backtrace — only panics (`[p]`) show Rust backtraces.
+
+[Read the source code →](app.rb)

data/examples/app_debugging_showcase/app.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+
+##
+# Interactive demonstration of RatatuiRuby debugging features.
+#
+# This example lets you trigger each debugging feature with a hotkey to verify
+# your setup works before encountering a real bug.
+#
+# == Hotkeys
+#
+# [d] Enable debug_mode! — Shows the debug socket path for remote attachment
+# [p] Trigger test_panic! — Deliberately crashes to verify Rust backtrace visibility
+# [t] Cause TypeError — Passes wrong type to widget factory to show Rust stack frames
+# [b] Show backtrace status — Displays current debug configuration
+# [q] Quit
+#
+# == Usage
+#
+#   # Normal mode (no backtraces):
+#   ruby examples/verify_debugging_usage/app.rb
+#
+#   # With Rust backtraces only:
+#   RUST_BACKTRACE=1 ruby examples/verify_debugging_usage/app.rb
+#
+#   # Full debug mode (stops at startup for debugger attachment):
+#   RR_DEBUG=1 ruby examples/verify_debugging_usage/app.rb
+#
+# == Remote Debugging
+#
+# When you press [d] to enable debug_mode!, the app continues running but
+# prints a socket path. From another terminal:
+#
+#   rdbg --attach
+#
+# This gives you a full debugger REPL while the TUI keeps running.
+class VerifyDebuggingUsage
+  def initialize
+    @status_message = "Press a key to test debugging features"
+    @show_debug_info = false
+    @quit = false
+
+    # If debug mode was enabled via RR_DEBUG=1 at startup, capture the socket path
+    if RatatuiRuby::Debug.enabled?
+      @socket_path = begin
+        ::DEBUGGER__.create_unix_domain_socket_name
+      rescue NameError
+        nil
+      end
+      @show_debug_info = true
+      @status_message = "RR_DEBUG=1 detected — debug mode active"
+    end
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @loop_count = 0
+
+      loop do
+        @loop_count += 1
+
+        # 🎯 Breakpoint every 250 loops. Try: p @status_message
+        if RatatuiRuby::Debug.enabled? && (@loop_count % 250).zero?
+          you_found_me = "🎉 You found me! Loop ##{@loop_count}"
+          # rubocop:disable Lint/Debugger
+          debugger
+          # rubocop:enable Lint/Debugger
+          _ = you_found_me # Suppress unused variable warning
+        end
+
+        render
+        break if @quit || handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      constraints = [
+        @tui.constraint_length(3),  # Status
+        @tui.constraint_length(5),  # Config
+        @tui.constraint_length(6),  # Actions
+      ]
+
+      if @show_debug_info
+        constraints << @tui.constraint_length(6) # Debug info
+      end
+
+      constraints << @tui.constraint_fill(1)    # Spacer
+      constraints << @tui.constraint_length(3)  # Help
+
+      chunks = @tui.layout_split(frame.area, direction: :vertical, constraints:)
+
+      idx = 0
+      render_status(frame, chunks[idx])
+      idx += 1
+      render_config(frame, chunks[idx])
+      idx += 1
+      render_actions(frame, chunks[idx])
+      idx += 1
+
+      if @show_debug_info
+        render_debug_info(frame, chunks[idx])
+        idx += 1
+      end
+
+      # Skip spacer
+      idx += 1
+      render_help(frame, chunks[idx])
+    end
+  end
+
+  private def render_status(frame, area)
+    frame.render_widget(
+      @tui.paragraph(
+        text: @status_message,
+        alignment: :center,
+        block: @tui.block(
+          title: " Status ",
+          title_alignment: :center,
+          borders: [:all],
+          border_style: { fg: :yellow }
+        )
+      ),
+      area
+    )
+  end
+
+  private def render_config(frame, area)
+    config_lines = [
+      "Rust Backtraces:  #{flag(RatatuiRuby::Debug.rust_backtrace_enabled?)}",
+      "Full Debug Mode:  #{flag(RatatuiRuby::Debug.enabled?)}",
+      "Remote Debugging: #{remote_mode_description}",
+    ].join("\n")
+
+    frame.render_widget(
+      @tui.paragraph(
+        text: config_lines,
+        block: @tui.block(
+          title: " Current Debug Configuration ",
+          borders: [:all],
+          border_style: { fg: :cyan }
+        )
+      ),
+      area
+    )
+  end
+
+  private def render_actions(frame, area)
+    actions_lines = [
+      "[d] Enable debug_mode! and show socket info",
+      "[p] Trigger test_panic! to verify backtrace visibility",
+      "[t] Cause TypeError (pass wrong type to widget)",
+      "[b] Refresh debug status",
+    ].join("\n")
+
+    frame.render_widget(
+      @tui.paragraph(
+        text: actions_lines,
+        block: @tui.block(
+          title: " Available Actions ",
+          borders: [:all],
+          border_style: { fg: :green }
+        )
+      ),
+      area
+    )
+  end
+
+  private def render_debug_info(frame, area)
+    socket_display = @socket_path || "(socket not available)"
+    info_lines = [
+      "Socket: #{socket_display}",
+      "Attach: rdbg --attach",
+      "Hint: type 'continue' if you see SIGURG",
+    ]
+
+    frame.render_widget(
+      @tui.paragraph(
+        text: info_lines.join("\n"),
+        block: @tui.block(
+          title: " Remote Debugging ",
+          borders: [:all],
+          border_style: { fg: :magenta }
+        )
+      ),
+      area
+    )
+  end
+
+  private def render_help(frame, area)
+    frame.render_widget(
+      @tui.paragraph(
+        text: "[d] debug_mode!  [p] test_panic!  [t] TypeError  [b] status  [q] quit",
+        alignment: :center,
+        block: @tui.block(
+          borders: [:all],
+          border_style: { fg: :dark_gray }
+        )
+      ),
+      area
+    )
+  end
+
+  private def flag(value)
+    value ? "✓ enabled" : "✗ disabled"
+  end
+
+  private def remote_mode_description
+    case RatatuiRuby::Debug.remote_debugging_mode
+    when :open
+      attached = debugger_attached? ? " — ATTACHED" : " — waiting"
+      "✓ open#{attached}"
+    when :open_nonstop
+      attached = debugger_attached? ? " — ATTACHED" : ""
+      "✓ open_nonstop#{attached}"
+    else
+      "✗ not configured"
+    end
+  end
+
+  # ☣️  FRAGILE: This pokes at debug gem internals.
+  #
+  # Private instance variables can change between gem versions. This code
+  # may silently break. We accept that risk here because this showcase
+  # exists specifically to demonstrate debugger attachment status.
+  #
+  # For production apps, checking Debug.enabled? is sufficient — knowing
+  # whether a client has attached rarely matters.
+  private def debugger_attached?
+    return false unless defined?(::DEBUGGER__::SESSION)
+
+    ui = ::DEBUGGER__::SESSION.instance_variable_get(:@ui)
+    return false unless ui
+
+    # The @sock instance variable is set when a client connects
+    sock = ui.instance_variable_get(:@sock)
+    !sock.nil?
+  rescue
+    false
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+
+    in { type: :key, code: "d" }
+      enable_debug_mode!
+
+    in { type: :key, code: "p" }
+      trigger_test_panic!
+
+    in { type: :key, code: "t" }
+      trigger_type_error!
+
+    in { type: :key, code: "b" }
+      @status_message = "Debug status refreshed at #{Time.now.strftime('%H:%M:%S')}"
+
+    else
+      nil
+    end
+  end
+
+  private def enable_debug_mode!
+    if RatatuiRuby::Debug.enabled?
+      @status_message = "Debug mode already enabled!"
+    else
+      # debug_mode! returns the socket path and suppresses the debug gem's output
+      @socket_path = RatatuiRuby.debug_mode!
+      @status_message = "debug_mode! enabled"
+      @show_debug_info = true
+    end
+  end
+
+  private def trigger_test_panic!
+    if RatatuiRuby::Debug.rust_backtrace_enabled?
+      @status_message = "Triggering test_panic! — check stderr for backtrace..."
+    else
+      @status_message = "Triggering test_panic! — backtrace hidden (set RUST_BACKTRACE=1)"
+    end
+    render # Show the message before crashing
+
+    # Give a moment for the render to complete
+    sleep 0.1
+
+    # This will crash the app with a Rust panic. If RUST_BACKTRACE=1 or
+    # debug mode is enabled, you'll see the full Rust stack trace after
+    # the terminal is restored.
+    RatatuiRuby::Debug.test_panic!
+  end
+
+  private def trigger_type_error!
+    if RatatuiRuby::Debug.rust_backtrace_enabled?
+      @status_message = "Triggering TypeError — check stderr for error message..."
+    else
+      @status_message = "Triggering TypeError — set RUST_BACKTRACE=1 for stack trace"
+    end
+    render # Show the message before crashing
+    sleep 0.1
+
+    # Bypass the factory's DWIM coercion to trigger a real Rust TypeError.
+    # Uses Widgets::Table.new directly with invalid rows type.
+    bad_table = RatatuiRuby::Widgets::Table.new(rows: 42, widths: [])
+    @tui.draw { |f| f.render_widget(bad_table, f.area) }
+  end
+end
+
+VerifyDebuggingUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_canvas/app.rb

@@ -37,24 +37,26 @@ class WidgetCanvas
 
   private def render
     @tui.draw do |frame|
-      # Define shapes
+      # Define shapes using terse aliases (circle, rectangle, point, map, label)
+      # These are shorter forms of shape_circle, shape_rectangle, etc.
       shapes = []
 
-      # 1. Static Grid (Lines)
+      # 1. Static Grid (Lines) - using shape_line (no terse alias for line)
       (-100..100).step(20) do |i|
         shapes << @tui.shape_line(x1: i.to_f, y1: -100.0, x2: i.to_f, y2: 100.0, color: :gray)
         shapes << @tui.shape_line(x1: -100.0, y1: i.to_f, x2: 100.0, y2: i.to_f, color: :gray)
       end
 
-      # 2. Moving Circle (The "Player")
-      shapes << @tui.shape_circle(
+      # 2. Moving Circle (The "Player") - using terse 'circle' alias
+      shapes << @tui.circle(
         x: @x_offset,
         y: @y_offset,
         radius: 10.0,
         color: :green
       )
 
-      # 3. Static Rectangle (Target)
+      # 3. Static Rectangle (Target) - using shape_rectangle (no 'rectangle' alias
+      #    to avoid confusion with Layout::Rect)
       shapes << @tui.shape_rectangle(
         x: 30.0,
         y: 30.0,
@@ -63,16 +65,16 @@ class WidgetCanvas
         color: :red
       )
 
-      # 4. Points (Starfield)
+      # 4. Points (Starfield) - using terse 'point' alias
       # Deterministic "random" points
       10.times do |i|
-        shapes << @tui.shape_point(
+        shapes << @tui.point(
           x: ((i * 37) % 200) - 100.0,
           y: ((i * 19) % 200) - 100.0
         )
       end
 
-      # 5. Label
+      # 5. Connecting line from origin to player position
       shapes << @tui.shape_line(x1: 0.0, y1: 0.0, x2: @x_offset, y2: @y_offset, color: :yellow)
 
       canvas = @tui.canvas(
@@ -89,21 +91,24 @@ class WidgetCanvas
         direction: :vertical,
         constraints: [
           @tui.constraint_fill(1),
-          @tui.constraint_length(3),
+          @tui.constraint_length(2),
         ]
       )
 
       frame.render_widget(canvas, layout[0])
 
-      # Controls
+      # Query: Canvas#get_point maps canvas coordinates to normalized [0.0, 1.0] grid
+      normalized = canvas.get_point(@x_offset, @y_offset)
+      norm_str = normalized ? format("[%.2f, %.2f]", normalized[0], normalized[1]) : "nil"
+
+      # Controls showing query method demonstration (single concise line)
       controls = @tui.paragraph(
         text: [
-          @tui.text_line(spans: [
-            @tui.text_span(content: "Canvas auto-animates.", style: @tui.style(fg: :yellow)),
-          ]),
           @tui.text_line(spans: [
             @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
-            @tui.text_span(content: ": Quit"),
+            @tui.text_span(content: ": Quit  "),
+            @tui.text_span(content: "get_point → ", style: @tui.style(fg: :dark_gray)),
+            @tui.text_span(content: norm_str, style: @tui.style(fg: :cyan)),
           ]),
         ],
         block: @tui.block(borders: [:top])