ribir-debug

Ribir Debug Tool Guide

This guide explains how to use the Ribir Debug Tool HTTP API to debug, inspect, and interact with running Ribir applications.

0. Overview

Ribir provides a built-in HTTP debug server that enables:

• Visual Inspection: Capture screenshots, inspect widget trees
• Event Injection: Simulate user interactions (clicks, keyboard, etc.)
• Debug Overlays: Add visual highlights to widgets
• Logging: View and filter application logs
• Frame Recording: Capture frames for animation/transient issue debugging

Architecture

App (Native/WASM) --WebSocket--> CLI Debug Server --HTTP--> Debug Tools/UI

Both Native and WASM targets use the same unified architecture. The app acts as a WebSocket client connecting to the CLI debug server.

1. Getting Started

1.1 Start the Debug Server

Before running any app with debug feature, start the debug server:

cargo run -p ribir-cli -- debug-server

The debug server prints its URL on startup:

RIBIR_DEBUG_URL=http://127.0.0.1:2333

Important: The actual port may differ if the default port is in use. Always use the printed RIBIR_DEBUG_URL value.

1.2 Native Debugging

Run your Ribir application with the debug feature. The app will automatically connect to the debug server:

cargo run --features debug

# Or with specific package:
cargo run -p your_package --features debug

To use a custom debug server URL:

RIBIR_DEBUG_URL=http://127.0.0.1:8080 cargo run -p your_package --features debug

1.3 WASM Debugging

Use ribir-cli run-wasm with the --debug flag:

cargo run -p ribir-cli -- run-wasm --package your_package --debug

The debug server URL is automatically injected into the HTML as a query parameter:

http://127.0.0.1:8000/?ribir_debug_server=http://127.0.0.1:2333

Open the browser and the WASM app will automatically connect to the debug server.

1.4 Port Assignment Logic

Debug Server:

• Default port: 2333
• Tries up to 100 ports (2333-2432)
• Falls back to a dynamic port if all are busy
• Prints the actual URL on startup

Important: Always use the printed RIBIR_DEBUG_URL rather than assuming a specific port.

1.5 Configuration

The debug server can be configured via CLI arguments:

2. HTTP API Reference

Base URL: http://127.0.0.1:<port> (use the printed RIBIR_DEBUG_URL)

2.1 Status & Windows

Example: Get Status

curl http://127.0.0.1:2333/status

Response:

{
  "recording": false,
  "log_sink_connected": true,
  "filter_reload_installed": true,
  "filter": "info",
  "dropped_total": 0,
  "ring_len": 42,
  "capture_root": "captures",
  "active_capture": null,
  "active_macro_recording": null
}

Example: Get Windows

curl http://127.0.0.1:2333/windows

Response:

[
  {
    "id": 140375628188560,
    "title": "My App",
    "width": 800,
    "height": 600
  }
]

Note: Use the id from /windows as window_id in other endpoints (like /events/inject, /overlay, etc.) for multi-window apps.

2.2 Widget Inspection

Query Parameters:

• options: Comma-separated tokens: all, id, layout, global_pos, clamp, props, no_global_pos, no_clamp, no_props

Example: Inspect Widget Tree

curl "http://127.0.0.1:2333/inspect/tree?options=all"

2.3 Screenshots

Example:

curl -o screenshot.png http://127.0.0.1:2333/screenshot

2.4 Debug Overlays

Request Body for /overlay:

{
  "window_id": null,
  "id": "3:0",
  "color": "#FF000080"
}

Note: window_id is optional. If omitted, the first active window is used. For multi-window apps, query /windows first to get the correct window ID.

Example: Add Overlay

curl -X POST http://127.0.0.1:2333/overlay \
  -H "Content-Type: application/json" \
  -d '{"id": "3:0", "color": "#FF000080"}'

2.5 Event Injection

Request Body:

{
  "window_id": null,
  "events": [
    { "type": "click", "id": "3:0" }
  ]
}

Note: window_id is optional (uses first window if omitted). The accepted field indicates how many events were actually processed (may be less than sent if some fail).

Response:

{"accepted": 1}

2.6 Logging

Query Parameters for /logs:

• since_ts: Unix timestamp in milliseconds
• until_ts: Unix timestamp in milliseconds
• limit: Maximum number of log lines

Response Headers for /logs:

• X-Ribir-Log-Dropped: Number of logs dropped due to ring buffer overflow (indicates data loss)

Example: Get Logs

curl http://127.0.0.1:2333/logs?limit=50

Example: Set Filter

curl -X POST http://127.0.0.1:2333/logs/filter \
  -H "Content-Type: application/json" \
  -d '{"filter": "debug,ribir_core=trace"}'

2.7 Recording & Capture

2.8 Event Macro Recording

Start Recording (Async Mode):

# Async mode: starts recording, returns immediately with recording_id
curl -X POST http://127.0.0.1:2333/events/macro/start \
  -H "Content-Type: application/json" \
  -d '{}'

Response (Async Mode):

{
  "recording_id": "macro_1234567890_0",
  "started_at_ts_unix_ms": 1234567890123
}

Start with Auto-Stop (Sync Mode):

# Sync mode: waits for duration_ms, then returns recorded events
curl -X POST http://127.0.0.1:2333/events/macro/start \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 10000}'

Response (Sync Mode - waits for recording to complete):

{
  "recording_id": "macro_1234567890_0",
  "events": [
    {"type": "click", "id": "3:0"},
    {"type": "delay", "ms": 100},
    {"type": "chars", "chars": "hello"}
  ],
  "duration_ms": 10000
}

Key Difference:

• Async mode (no duration_ms): Returns immediately with recording_id and started_at_ts_unix_ms. You must call /events/macro/stop later.
• Sync mode (with duration_ms): Waits for the specified duration, then returns the complete recording with events and duration_ms. No need to call stop.

Stop Recording (Async Mode Only):

curl -X POST http://127.0.0.1:2333/events/macro/stop \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "recording_id": "macro_1234567890_0",
  "events": [
    {"type": "click", "id": "3:0"},
    {"type": "delay", "ms": 100},
    {"type": "chars", "chars": "hello"}
  ],
  "duration_ms": 200
}

The events array contains replay-ready events with automatic delay insertions to preserve the original timing between user interactions.

duration_ms reports the full wall-clock recording duration. For timed auto-stop, it should match the configured duration (plus small scheduling jitter), not the timestamp of the last recorded event.

Replay: The events array in the response is replay-ready and contains delay events to preserve the original timing. You can pass it directly to /events/inject:

# Step 1: Record and stop
RESPONSE=$(curl -s -X POST http://127.0.0.1:2333/events/macro/stop \
  -H "Content-Type: application/json" -d '{}')

# Step 2: Extract events and replay directly (includes timing delays)
EVENTS=$(echo "$RESPONSE" | jq '.events')
curl -X POST http://127.0.0.1:2333/events/inject \
  -H "Content-Type: application/json" \
  -d "{\"events\": $EVENTS}"

Or with the debug UI: click Start → interact with the app → click Stop → the events will be displayed with timing information. Click the Download Events button to save them as JSON. The downloaded JSON can be passed directly to /events/inject for replay with preserved timing.

Use Cases:

• Create reproducible test scenarios
• Automate repetitive debugging tasks
• Document bug reproduction steps

3. Widget ID Formats

Widget identifiers support multiple formats:

Using debug_name

Assign stable names to widgets for easier targeting:

button! {
  debug_name: "counter_button",
  @{ "+1" }
}

Then use in API calls:

curl -X POST http://127.0.0.1:2333/events/inject \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "click", "id": "name:counter_button"}]}'

4. Event Types Reference

4.1 Mouse Events

// Move cursor
{ "type": "cursor_moved", "x": 100, "y": 200 }

// Cursor leaves window
{ "type": "cursor_left" }

// Mouse button (button: primary|secondary|auxiliary|fourth|fifth)
{ "type": "mouse_input", "button": "primary", "state": "pressed" }
{ "type": "mouse_input", "button": "primary", "state": "released" }

// Scroll
{ "type": "mouse_wheel", "delta_x": 0, "delta_y": -10 }

// Click shortcut (auto-generates press + release)
{ "type": "click", "id": "3:0" }
{ "type": "click", "x": 100, "y": 200 }

// Double click
{ "type": "double_click", "id": "name:my_button" }

4.2 Keyboard Events

// Functional keyboard input (press + release + optional chars)
{ "type": "keyboard_input", "key": "a", "chars": "a" }
{ "type": "keyboard_input", "key": "Enter" }

// Raw keyboard input (low-level control)
{ "type": "raw_keyboard_input", "key": "a", "physical_key": "KeyA", "state": "pressed" }
{ "type": "raw_keyboard_input", "key": "a", "physical_key": "KeyA", "state": "released" }

// Quick text input
{ "type": "chars", "chars": "hello world" }

// Modifiers
{ "type": "modifiers_changed", "shift": true, "ctrl": false, "alt": false, "logo": false }

Raw Keyboard Input Fields:

• key: Virtual key name (e.g., "a", "Enter", "Space")
• physical_key: Optional W3C physical key code (e.g., "KeyA", "Digit1", "Enter")
• state: "pressed" or "released"
• is_repeat: Optional, whether this is a key repeat event (default: false)
• location: Optional key location: "standard", "left", "right", "numpad" (default: "standard")
• chars: Optional characters to receive on press

4.3 Utility Events

// Delay between events
{ "type": "delay", "ms": 100 }

// Request redraw
{ "type": "redraw_request", "force": true }

5. Common Debugging Workflows

5.1 Inspect Widget Hierarchy

# Get the widget tree
curl http://127.0.0.1:2333/inspect/tree | jq .

# Find a specific widget
curl http://127.0.0.1:2333/inspect/3:0 | jq .

5.2 Visual Debugging with Overlays

# Highlight a widget
curl -X POST http://127.0.0.1:2333/overlay \
  -H "Content-Type: application/json" \
  -d '{"id": "3:0", "color": "#FF000080"}'

# Take a screenshot to see the overlay
curl -o debug.png http://127.0.0.1:2333/screenshot

# Clear overlays when done
curl -X DELETE http://127.0.0.1:2333/overlays

5.3 Simulate User Interaction

# Click a button by debug name
curl -X POST http://127.0.0.1:2333/events/inject \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "click", "id": "name:submit_button"}]}'

# Type text into an input field
curl -X POST http://127.0.0.1:2333/events/inject \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "chars", "chars": "Hello, World!"}]}'

# Complex interaction sequence
curl -X POST http://127.0.0.1:2333/events/inject \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "cursor_moved", "x": 100, "y": 100 },
      { "type": "delay", "ms": 100 },
      { "type": "mouse_input", "button": "primary", "state": "pressed" },
      { "type": "delay", "ms": 50 },
      { "type": "mouse_input", "button": "primary", "state": "released" }
    ]
  }'

5.4 Debug Logging

# Increase log verbosity
curl -X POST http://127.0.0.1:2333/logs/filter \
  -H "Content-Type: application/json" \
  -d '{"filter": "debug,ribir_core=trace"}'

# Stream logs in real-time
curl -N http://127.0.0.1:2333/logs/stream

5.5 Capture for Bug Reports

# One-shot capture (logs + frames)
curl -X POST http://127.0.0.1:2333/capture/one_shot \
  -H "Content-Type: application/json" \
  -d '{"include": ["logs", "images"], "pre_ms": 2000, "post_ms": 1000}'

# One-shot capture with settle time (wait for frame to stabilize)
curl -X POST http://127.0.0.1:2333/capture/one_shot \
  -H "Content-Type: application/json" \
  -d '{"include": ["logs", "images"], "pre_ms": 2000, "post_ms": 1000, "settle_ms": 150}'

# Response contains the capture directory
# {"capture_dir": "/path/to/captures/{capture_id}", "manifest_path": "..."}

Capture One-Shot Parameters:

• include: Array of "logs" and/or "images"
• pre_ms: Logs captured from (now - pre_ms) (default: 2000)
• post_ms: Logs captured until (now + post_ms) (default: 1000)
• settle_ms: Extra time to wait after frame update (default: 150)
• output_dir: Optional custom output directory

6. Tips & Best Practices

6.1 Use debug_name Proactively

When debugging, add debug_name to target widgets:

@Button {
  debug_name: "login_button",
  on_tap: move |_| { /* ... */ },
  @{ "Login" }
}

This makes event injection much more reliable:

{ "type": "click", "id": "name:login_button" }

6.2 Verify Widget IDs

Before injecting events, verify the widget exists:

# Check if widget exists
curl http://127.0.0.1:2333/inspect/name:my_button

6.3 Use Overlays for Visual Confirmation

Before clicking, add an overlay to confirm the target:

curl -X POST http://127.0.0.1:2333/overlay \
  -H "Content-Type: application/json" \
  -d '{"id": "name:my_button", "color": "#00FF0080"}'

# Then capture screenshot to verify
curl -o check.png http://127.0.0.1:2333/screenshot

6.4 Check Server Status

Always verify the debug server is responsive:

curl http://127.0.0.1:2333/status

7. Troubleshooting

7.1 No Logs Captured

If ring_len is 0 in status:

1. Check if log_sink_connected is true
2. Verify tracing subscriber was initialized (check console for warnings)
3. Try setting a more permissive filter

7.2 Event Injection Not Working

1. Verify the widget ID format is correct
2. Check if the widget exists using /inspect/{id}
3. Use overlays to visually confirm the target

7.3 Screenshot Timeout

If screenshots timeout:

1. The application may be unresponsive
2. Try requesting a redraw first: {"type": "redraw_request", "force": true}

7.4 Widget Not Found

Widget IDs can change between frames if the widget tree is rebuilt. Use debug_name for stable identifiers, or re-query the widget tree before each operation.

7.5 Debug Server Not Starting

If the debug server fails to start:

1. Check if port 2333 is already in use
2. Try a different port: cargo run -p ribir-cli -- debug-server --port 3000
3. Check the printed RIBIR_DEBUG_URL for the actual port

7.6 WASM Connection Issues

1. Ensure the debug server is running (cargo run -p ribir-cli -- debug-server)
2. Check that the ribir_debug_server query parameter is present in the URL
3. Check browser console for connection errors
4. Verify the WebSocket URL matches the debug server's printed RIBIR_DEBUG_URL