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
- CLI Hub:
tools/lapis/src/tui/hub.cr - Editor Launcher:
tools/lapis/src/tui/editor_launcher.cr - Package Form:
tools/lapis/src/tui/package_form.cr - Crash Forensics:
tools/lapis/src/tui/debugger_view.cr - Benchmark Visualizer:
tools/lapis/src/tui/bench_viewer.cr - Performance Monitor:
tools/lapis/src/tui/run_monitor.cr
Defined in:
libgodot/docs/j_modern_cli_and_tui/b_tui_hub_and_specialized_views.crClass Method Summary
-
.topic_00_interactive_cli_hub_and_palette : Nil
Interactive Navigation Hub & Command Palette: Unified terminal navigation dashboard featuring live telemetry and floating command palette.
-
.topic_01_project_scaffolding_and_folder_dialog : Nil
Project Scaffolding Wizard & Directory Selection: Interactive project generator with directory browser dialog for custom workspace paths.
-
.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.
-
.topic_03_context_aware_packaging_form : Nil
Context-Aware Packaging & Export Form: Multi-target export configurator with platform-specific compile-time macro filtering.
-
.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.
-
.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.
-
.topic_06_runtime_performance_monitor : Nil
Runtime Performance Monitor & Process Telemetry: Real-time rolling FPS and RAM LineGraphs with graceful Ctrl+K process termination.
-
.topic_07_tui_recording_and_vcr_screenshots : Nil
VCR Screenshots & Asciicast Session Recording: Capturing instant ANSI/HTML terminal snapshots and recording .cast screencast sessions.
Class Method Detail
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 cliserves 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 (
~,`, orCtrl+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.
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::FileDialogin:open_dirmode 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.godotfiles.
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 editoror 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
stdoutandstderrinto a high-performance circular log buffer with scroll locking and keyword highlighting. - Supports on-the-fly hot reloading (
Rkey) and graceful process termination (Kkey).
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 |
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
cradare2for:- Disassembly View: Real machine instructions fetched via
pdf. - Decompiler View: Pseudo-C decompilation extracted via
pdc. - CPU Registers: Live CPU register states parsed via
drj. - Memory Inspection: Raw binary byte visualization powered by
Opal::UI::HexViewer. - Demangled Call Stack: Crystal method backtraces retrieved via
client.crystal.demangled_backtrace.
- Disassembly View: Real machine instructions fetched via
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/*.xmlviaCommands::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.
Runtime Performance Monitor & Process Telemetry: Real-time rolling FPS and RAM LineGraphs with graceful Ctrl+K process termination.
Telemetry Monitoring
- Launched via
lapis run --monitororlapis 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+KorK, eliminating orphaned processes.
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. |