module Lapis::Docs::J_MODERN_CLI_AND_TUI::B_TUI_HUB_AND_SPECIALIZED_VIEWS

Overview

Interactive TUI Hub & Domain Workspaces

Comprehensive guide to the next-generation Lapis terminal user interface suite, including the central navigation hub, interactive command palette, persistent editor supervisor, context-aware packaging configurator, and dynamic radare2 crash forensics debugger.

Executive Summary & Key Topics

Topic Method / Anchor Description
Interactive Navigation Hub & Command Palette .topic_00_interactive_cli_hub_and_palette Unified terminal navigation dashboard featuring live telemetry and floating command palette.
Project Scaffolding Wizard & Directory Selection .topic_01_project_scaffolding_and_folder_dialog Interactive project generator with directory browser dialog for custom workspace paths.
Persistent Editor Supervisor & Real-Time Log Tailing .topic_02_persistent_editor_supervisor Long-running Godot editor supervisor that monitors process status and streams engine stdout/stderr.
Context-Aware Packaging & Export Form .topic_03_context_aware_packaging_form Multi-target export configurator with platform-specific compile-time macro filtering.
Radare2 Native Crash Forensics & Decompilation .topic_04_radare2_crash_forensics_view Deep binary analysis workspace querying live r2 pipelines for real disassembly and decompilation.
Dynamic Benchmark Visualizer & Performance Analytics .topic_05_dynamic_benchmark_visualizer Multi-dimensional performance analysis tool powered by Opal charts and live XML metrics parsing.
Runtime Performance Monitor & Process Telemetry .topic_06_runtime_performance_monitor Real-time rolling FPS and RAM LineGraphs with graceful Ctrl+K process termination.
VCR Screenshots & Asciicast Session Recording .topic_07_tui_recording_and_vcr_screenshots Capturing instant ANSI/HTML terminal snapshots and recording .cast screencast sessions.

Related Guides & Source References

Defined in:

libgodot/docs/j_modern_cli_and_tui/b_tui_hub_and_specialized_views.cr

Class Method Summary

Class Method Detail

def self.topic_00_interactive_cli_hub_and_palette : Nil #

Interactive Navigation Hub & Command Palette: Unified terminal navigation dashboard featuring live telemetry and floating command palette.

Architectural Invariants

  • The central terminal interface launched via lapis cli serves as a master dashboard for all developer workflows.
  • Includes a persistent top header card showing host OS, architecture, Crystal compiler version, and Godot engine paths.
  • A global command palette shortcut (~, `, or Ctrl+P) is registered across all subviews to allow instantaneous switching between tools without restarting the CLI.
  • Built using double-buffered Opal virtual screen rendering with differential ANSI updates for silky smooth interaction.

def self.topic_01_project_scaffolding_and_folder_dialog : Nil #

Project Scaffolding Wizard & Directory Selection: Interactive project generator with directory browser dialog for custom workspace paths.

Mechanics & Directory Browsing

  • Accessible via lapis new (when in an interactive TTY) or through the hub menu.
  • Integrates Opal::UI::FileDialog in :open_dir mode to let developers visually browse the filesystem and select destination directories.
  • Configures project name, author name, target template (2D Starter, 3D Starter, or GDExtension Addon), and initializes Git repositories.
  • Prevents scaffolding collisions by verifying directory vacancy and checking for existing project.godot files.

def self.topic_02_persistent_editor_supervisor : Nil #

Persistent Editor Supervisor & Real-Time Log Tailing: Long-running Godot editor supervisor that monitors process status and streams engine stdout/stderr.

Process Lifecycle & Log Streaming

  • Launched via lapis editor or through the TUI hub.
  • When executed in a directory without project.godot, prompts the user with an interactive directory picker instead of failing.
  • Spawns the Godot editor asynchronously and keeps the TUI alive in the terminal.
  • Uses non-blocking background fibers to continuously pump both stdout and stderr into a high-performance circular log buffer with scroll locking and keyword highlighting.
  • Supports on-the-fly hot reloading (R key) and graceful process termination (K key).

def self.topic_03_context_aware_packaging_form : Nil #

Context-Aware Packaging & Export Form: Multi-target export configurator with platform-specific compile-time macro filtering.

Target Invariants & Platform Awareness

  • Configures export targets including Playable Games, Portable Executables with embedded PCK footers, GDExtension Addon archives, and redistributable installers.
  • Strictly macro-flags platform targets to ensure context-aware choices:
Platform Macro Guard Available Specialized Target
Windows flag?(:windows) Windows Installer (.exe via NSIS / InnoSetup)
Linux flag?(:linux) Debian Binary Package (.deb with desktop launcher)
macOS flag?(:darwin) macOS Application Bundle Archive (.app / .zip)
All Platforms Standard Playable Game, Portable Binary, Addon, Toolchain, Benchmarks

def self.topic_04_radare2_crash_forensics_view : Nil #

Radare2 Native Crash Forensics & Decompilation: Deep binary analysis workspace querying live r2 pipelines for real disassembly and decompilation.

Zero-Cheating Policy & Dynamic Queries

  • Automatically activates when a game or editor process crashes with access violation (0xC0000005) or abnormal signals.
  • Strictly prohibits mock data, fake disassembly lines, or hardcoded registers.
  • Dynamically queries cradare2 for:
    1. Disassembly View: Real machine instructions fetched via pdf.
    2. Decompiler View: Pseudo-C decompilation extracted via pdc.
    3. CPU Registers: Live CPU register states parsed via drj.
    4. Memory Inspection: Raw binary byte visualization powered by Opal::UI::HexViewer.
    5. Demangled Call Stack: Crystal method backtraces retrieved via client.crystal.demangled_backtrace.

def self.topic_05_dynamic_benchmark_visualizer : Nil #

Dynamic Benchmark Visualizer & Performance Analytics: Multi-dimensional performance analysis tool powered by Opal charts and live XML metrics parsing.

Analytics & Charting

  • Parses real XML benchmark reports generated in benchmarks/reports/*.xml via Commands::Benchmarks::XmlHandler.
  • Features an interactive file dialog to select past benchmark runs or triggers live benchmark execution directly from the TUI.
  • Visualizes comparative metrics using rich Opal charts:
    • Opal::UI::BarChart: Crystal vs GDScript execution latency comparisons with speedup ratios.
    • Opal::UI::PieChart: Memory and processing category distribution.
    • Opal::UI::LineGraph: Historical trend across multiple successive benchmark runs.

def self.topic_06_runtime_performance_monitor : Nil #

Runtime Performance Monitor & Process Telemetry: Real-time rolling FPS and RAM LineGraphs with graceful Ctrl+K process termination.

Telemetry Monitoring

  • Launched via lapis run --monitor or lapis bench --monitor.
  • Renders dual rolling line graphs showing frame rate (FPS) and memory allocation (MB) over the last 30 samples.
  • Displays PID, uptime counter, peak RAM consumption, and current operational status.
  • Provides instantaneous, graceful process termination via Ctrl+K or K, eliminating orphaned processes.

def self.topic_07_tui_recording_and_vcr_screenshots : Nil #

VCR Screenshots & Asciicast Session Recording: Capturing instant ANSI/HTML terminal snapshots and recording .cast screencast sessions.

Universal Session Capture Keys

All specialized TUI workspaces (Navigation Hub, Editor Supervisor, Packaging Center, Performance Monitor, Log Viewer, Benchmark Visualizer) implement unified capture shortcuts:

Shortcut Feature Output Formats & Destination
Ctrl+S VCR Instant Screenshot Saves timestamped recordings/screenshot_*.ansi and standalone styled recordings/screenshot_*.html. Also copies clean ANSI buffer directly to the OS clipboard for instant sharing.
Ctrl+R Asciicast Screencast Toggle Starts/stops high-fidelity asciicast v2 session recordings saved to recordings/*_session_*.cast, fully playable via asciinema play or embeddable in web documentation.