BAML Onionskin

A live TUI (Text User Interface) for exploring BAML compiler phases in real-time, inspired by animation onion skinning techniques.

What is Onion Skinning?

In animation, onion skinning displays ghosted versions of previous and next frames overlaid on the current frame, allowing animators to see how their work changes over time. BAML Onionskin applies this concept to compiler development - create a snapshot of your compiler output, make changes, and see a live diff showing exactly what changed.

Features

• 🔍 Real-time file watching: Automatically updates when your BAML file changes
• 🔄 Multiple compiler phases: View Lexer, Parser, HIR, THIR, Diagnostics, and Codegen output
• 🧅 Onion skin snapshots: Create snapshots and view side-by-side diffs of compiler output
• ⌨️ Keyboard navigation: Easy navigation with arrow keys and shortcuts

Usage

Run the tool by specifying a BAML file or directory to watch:

# Watch a single file
cargo run --bin tools_onionskin -- --from path/to/your/file.baml

# Watch an entire directory
cargo run --bin tools_onionskin -- --from path/to/your/directory

Compiler Hot-Reload 🔥

When running from within the baml_language workspace, onionskin automatically enables hot-reload for compiler development. It detects the workspace by looking for the crates/baml_compiler_lexer directory.

# Hot-reload is automatic when running from the workspace
cd /path/to/baml_language
cargo run --bin tools_onionskin -- --from test.baml

# Explicitly specify workspace root (if auto-detection fails)
cargo run --bin tools_onionskin -- --from path/to/file.baml --workspace /path/to/baml_language

# Disable hot-reload if you don't want it
cargo run --bin tools_onionskin -- --from test.baml --no-hot-reload

With hot-reload enabled (shown as 🔥 Hot-Reload in the header):

• Onionskin watches all compiler crate source files (e.g., baml_compiler_lexer, baml_compiler_hir, etc.)
• When a .rs file in any compiler crate changes, a banner appears prompting you to rebuild
• Press Enter to trigger a rebuild, or Esc to dismiss
• Press Shift+R anytime to manually trigger a rebuild
• After a successful rebuild, onionskin automatically restarts with the new compiler

Keyboard Shortcuts

Compiler Phases

Navigate through these compiler phases using the arrow keys:

1. Lexer (Tokens) - Shows the tokenized output
2. Parser (CST/AST) - Shows the concrete/abstract syntax tree
3. HIR (High-level IR) - Shows the high-level intermediate representation
4. THIR (Typed IR) - Shows type inference results
5. Diagnostics - Shows compilation errors and warnings
6. Codegen (Bytecode) - Shows generated bytecode

Single File vs Directory Mode

• Single File Mode: Watch a specific .baml file. Shows lexer/parser output for that file, and project-wide HIR/THIR/Codegen.
• Directory Mode: Watch all .baml files in a directory. Shows aggregated output across all files.
  • Lexer/Parser show per-file breakdowns
  • HIR/THIR/Codegen show project-wide results
  • Automatically detects new/modified/deleted files

Onion Skin Mode

Press s to create an onion skin snapshot of the current compiler output. Once a snapshot exists:

• The view splits into two columns: Snapshot (left) and Current (right)
• Changes are highlighted in red (removed) and green (added)
• Both panes update when you change compiler phases
• Press s again to update the snapshot to the current state

This is useful for:

• Comparing how code changes affect compiler output across all phases
• Understanding incremental compilation behavior
• Debugging compiler transformations
• Visualizing the evolution of your code through the compilation pipeline

Example Workflow

1. Start watching a file:

   bashCopy

   cargo run --bin tools_onionskin -- --from test.baml
   

2. The TUI shows the lexer output by default

3. Press → to navigate to the Parser view

4. Press s to create an onion skin snapshot

5. Edit test.baml in your editor - the view updates automatically

6. See the diff between your snapshot and the new compiler output

7. Navigate phases with ← → - both panes update to show that phase

8. Press s again to update the snapshot

Building

cargo build --bin tools_onionskin

Implementation Details

The tool uses:

• ratatui for the terminal UI
• notify for file system watching
• similar for diffing
• clap for CLI argument parsing
• The full BAML compiler pipeline