feat(cli): Add shiny inspect command with Reactlog visualization and interactive HTML export

[karangattu]

Summary

This PR adds shiny inspect, a CLI command that helps developers understand how a Shiny app reacts to user actions.

It shows dependencies, records browser sessions, replays reactive events, and creates reports for debugging or documentation.

Open the Reactlog report - Core Mode

Open another live Reactlog report - Express Mode

Quick start

Create an interactive HTML report:

shiny inspect app.py --html reactlog.html

Or run an app with live Reactlog enabled:

shiny run --reactlog app.py

More command examples

Inspect an app in the terminal

shiny inspect app.py

Run an app with live Reactlog support

shiny run --reactlog app.py

Record browser actions and video

shiny inspect app.py --record --video demo.webm --html session.html

Create a light-themed report

shiny inspect app.py --html report.html --theme light

Import a Shiny for R Reactlog file

shiny inspect legacy_reactlog.json --html imported-report.html

Export structured JSON

shiny inspect app.py --format json > graph.json

Export a Mermaid diagram

shiny inspect app.py --format mermaid > graph.md

Export a Graphviz DOT diagram

shiny inspect app.py --format dot > graph.dot

Show the event stream in the terminal

shiny inspect app.py --reactlog

Simulate input changes

shiny inspect app.py --input price=30 --input units=2

What the interactive report shows

• The full graph appears when the report opens.
• The timeline groups related events into action bursts.
• The Live Story explains each reactive step in plain language.
• Selecting an event or node updates the timeline, graph, and causal inspector.
• The causal inspector answers “Why did this run?” and “Why did this not run?”
• Input nodes focus on downstream effects. Calculation and output nodes focus on upstream causes.
• Filtering by lineage keeps focus on selected ancestors and descendants during timeline playback.
• Recorded video stays synchronized with the reactive timeline.
• Users can open another Reactlog JSON file from the report.

New Reactlog features

• Live app shortcuts:
  • Run with shiny run --reactlog app.py.
  • Press Cmd+F3 (macOS) or Ctrl+F3 (Windows/Linux) in the running app to open the report at /__reactlog__.
  • Press Cmd+Shift+F3 or Ctrl+Shift+F3 to save a bookmark label during an active session.
• User marks:
  • Call reactive.mark("label") in Python code to add timeline bookmarks.
  • Marks display as pins directly on the timeline bar.
• Isolated edge styling:
  • Values read inside with reactive.isolate(): display as dashed lines with isolated arrowheads in the graph.
• Keyboard navigation in reports:
  • Left / Right or h / l: Step backward and forward.
  • Up / Down or k / j: Jump between action bursts.
  • Space: Play and pause timeline playback.
  • Home / End: Jump to start or end.
  • ?: Open keyboard shortcut reference.
• Hotspot badges:
  • Nodes that run repeatedly display run count badges.
  • Nodes running 4 or more times show a flame icon badge with run counts to highlight reactive bottlenecks.

Compatibility and correctness

• Imports Shiny for R Reactlog JSON fields and normalizes epoch timestamps.
• Models @reactive.event() triggers as dependencies while keeping body reads isolated.
• Respects with reactive.isolate(): blocks during static analysis.
• Escapes imported labels and details before adding them to HTML.
• Supports dark, light, and automatic themes.
• Uses consistent Lucide SVG icons throughout the report.

CLI behavior

• --format controls the selected output, even when --record is present.
• Recording controls appear only when the report includes a recording.
• --html writes to reactlog.html when the user does not supply an output path.
• --record writes video to recording.webm when the user does not supply a path.
• --reactlog enables live Reactlog recording on shiny run.