zterm/RENDERER_REORG.md

Renderer.rs Reorganization Analysis

This document analyzes /src/renderer.rs (8189 lines) and identifies sections that could be extracted into separate modules for better code organization and maintainability.

Overview

The renderer.rs file is the largest file in the codebase and handles:

• GPU pipeline setup and rendering
• Font loading and glyph caching
• Color/emoji font rendering via FreeType/Cairo
• Box drawing character generation
• Statusline rendering
• Image/Kitty graphics protocol support
• Edge glow effects

---

Extraction Opportunities

1. Color Utilities / Linear Palette

Lines: 23-77
Suggested file: src/color.rs or src/palette.rs

Contents:

• LinearPalette struct
• srgb_to_linear() function
• make_linear_palette() function

Dependencies:

• crate::config::ColorScheme

Complexity: Low - self-contained utility code with minimal dependencies.

pub struct LinearPalette {
    pub foreground: [f32; 4],
    pub background: [f32; 4],
    pub cursor: [f32; 4],
    pub colors: [[f32; 4]; 256],
}

---

2. Statusline Types

Lines: 123-258
Suggested file: src/statusline.rs

Contents:

• StatuslineColor enum
• StatuslineComponent struct
• StatuslineSection struct
• StatuslineContent struct and its impl block

Dependencies:

• Standard library only

Complexity: Low - pure data structures with simple logic.

Note: The parse_ansi_statusline method (lines 4029-4144) should also move here.

---

3. Edge Glow Animation

Lines: 260-307
Suggested file: src/effects.rs or src/edge_glow.rs

Contents:

• EdgeGlowSide enum
• EdgeGlow struct
• Animation logic (update, is_active, intensity methods)

Dependencies:

• std::time::Instant

Complexity: Low - isolated animation state machine.

---

4. GPU Data Structures

Lines: 399-710
Suggested file: src/gpu_types.rs

Contents:

• GlyphVertex struct
• GlowInstance struct
• EdgeGlowUniforms struct
• ImageUniforms struct
• GPUCell struct
• SpriteInfo struct
• GridParams struct
• Quad struct
• QuadParams struct
• StatuslineParams struct
• Various constants (GLYPH_ATLAS_SIZE, CELL_INSTANCE_SIZE, etc.)

Dependencies:

• bytemuck::{Pod, Zeroable}

Complexity: Low - pure data structures with #[repr(C)] layouts for GPU compatibility.

---

5. Font Loading Helpers

Lines: 929-996, 1002-1081, 1382-1565
Suggested file: src/font_loader.rs

Contents:

• find_font_for_char() - finds a font file that can render a given character
• find_color_font_for_char() - finds color emoji fonts
• load_font_variant() - loads a specific font variant (bold, italic, etc.)
• find_font_family_variants() - discovers all variants of a font family
• load_font_family() - loads an entire font family

Dependencies:

• fontconfig crate
• fontdue crate
• std::fs
• std::collections::HashMap

Complexity: Medium - these are standalone functions but have some interdependencies. Would need to pass fontconfig patterns and settings as parameters.

---

6. Color Font Renderer (Emoji)

Lines: 1083-1380
Suggested file: src/color_font.rs or src/emoji_renderer.rs

Contents:

• ColorFontRenderer struct
• FreeType library/face management
• Cairo surface rendering
• Emoji glyph rasterization

Dependencies:

• freetype crate
• cairo crate
• std::collections::HashMap
• std::ptr

Complexity: Medium - self-contained but uses unsafe code and external C libraries. The struct is instantiated inside Renderer::new().

struct ColorFontRenderer {
    library: freetype::Library,
    faces: HashMap<String, FontFaceEntry>,
}

---

7. Box Drawing / Supersampled Canvas

Lines: 1567-1943, 4500-5706
Suggested file: src/box_drawing.rs

Contents:

• Corner enum
• SupersampledCanvas struct
• Canvas rendering methods (lines, arcs, shading, etc.)
• render_box_char() method (1200+ lines of box drawing logic)

Dependencies:

• Standard library only

Complexity: High - the render_box_char method is massive (1200+ lines) and handles all Unicode box drawing, block elements, and legacy graphics characters. However, it's functionally isolated.

Recommendation: This is the highest-value extraction target. The box drawing code is:

1. Completely self-contained
2. Very large (adds ~2400 lines)
3. Rarely needs modification
4. Easy to test in isolation

---

8. Pipeline Builder

Lines: 1947-2019
Suggested file: src/pipeline.rs

Contents:

• PipelineBuilder struct
• Builder pattern for wgpu render pipelines

Dependencies:

• wgpu crate

Complexity: Low - clean builder pattern, easily extractable.

struct PipelineBuilder<'a> {
    device: &'a wgpu::Device,
    label: &'a str,
    // ... other fields
}

---

9. Pane GPU Resources

Lines: 105-121, 3710-3785
Suggested file: src/pane_resources.rs

Contents:

• PaneGpuResources struct
• Buffer management for per-pane GPU state
• Methods: new(), ensure_grid_capacity(), ensure_glyph_capacity()

Dependencies:

• wgpu crate

Complexity: Medium - the struct is simple but tightly coupled to the Renderer for buffer creation. Would need to pass device as parameter.

---

10. Image Rendering / Kitty Graphics

Lines: 7940-8186 (+ GpuImage at 483-491)
Suggested file: src/image_renderer.rs

Contents:

• GpuImage struct
• upload_image() method
• remove_image() method
• sync_images() method
• prepare_image_renders() method

Dependencies:

• wgpu crate
• crate::terminal::ImageData

Complexity: Medium - these methods operate on Renderer state but could be extracted into a helper struct that holds image-specific GPU resources.

---

Recommended Extraction Order

Based on complexity and value, here's a suggested order:

Priority	Module	Lines Saved	Complexity	Value
1	box_drawing.rs	~2400	High	Very High
2	gpu_types.rs	~310	Low	High
3	color_font.rs	~300	Medium	High
4	font_loader.rs	~330	Medium	Medium
5	statusline.rs	~250	Low	Medium
6	pipeline.rs	~75	Low	Medium
7	color.rs	~55	Low	Low
8	edge_glow.rs	~50	Low	Low
9	pane_resources.rs	~80	Medium	Medium
10	image_renderer.rs	~250	Medium	Medium

---

Implementation Notes

The Renderer Struct (Lines 712-927)

The main Renderer struct ties everything together and would remain in renderer.rs. After extraction, it would:

1. Import types from the new modules
2. Potentially hold instances of extracted helper structs (e.g., ColorFontRenderer, ImageRenderer)
3. Still contain the core rendering logic (render(), prepare_pane_data(), etc.)

Module Structure

After refactoring, the structure might look like:

src/
├── renderer/
│   ├── mod.rs           # Main Renderer struct and render logic
│   ├── box_drawing.rs   # SupersampledCanvas + render_box_char
│   ├── color_font.rs    # ColorFontRenderer for emoji
│   ├── font_loader.rs   # Font discovery and loading
│   ├── gpu_types.rs     # GPU data structures
│   ├── image.rs         # Kitty graphics support
│   ├── pipeline.rs      # PipelineBuilder
│   ├── statusline.rs    # Statusline types and parsing
│   └── effects.rs       # EdgeGlow and other effects
├── color.rs             # LinearPalette (or keep in renderer/)
└── ...

Challenges

1. Circular dependencies: The Renderer struct is used throughout. Extracted modules should receive what they need via parameters, not by importing Renderer.

2. GPU resources: Many extracted components need &wgpu::Device and &wgpu::Queue. These should be passed as parameters rather than stored.

3. Method extraction: Some methods like render_box_char are currently impl Renderer methods. They'd need to become standalone functions or methods on the extracted structs.

4. Testing: Extracted modules will be easier to unit test, which is a significant benefit.

---

Quick Wins

These can be extracted with minimal refactoring:

1. gpu_types.rs - Just move the structs and constants, add pub use in renderer
2. color.rs - Move LinearPalette and helper functions
3. pipeline.rs - Move PipelineBuilder as-is
4. edge_glow.rs - Move EdgeGlow and related types

---

Conclusion

The renderer.rs file is doing too much. Extracting the identified modules would:

• Reduce renderer.rs from ~8200 lines to ~4000-4500 lines
• Improve code organization and discoverability
• Enable better unit testing of isolated components
• Make the codebase more approachable for new contributors

The highest-impact extraction is box_drawing.rs, which alone would remove ~2400 lines of self-contained code.