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.

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.