zterm/MISC_REORG.md

Code Reorganization Analysis

This document identifies sections of code that could be moved into separate files to improve code organization.

Summary

File	Lines	Assessment	Recommended Extractions
pty.rs	260	Well-organized	None needed
keyboard.rs	558	Could benefit from split	1 extraction recommended
graphics.rs	1846	Needs refactoring	3-4 extractions recommended

---

pty.rs (260 lines)

Assessment: Well-Organized - No Changes Needed

The file is focused and cohesive:

• PtyError enum (lines 10-28) - Error types for PTY operations
• Pty struct and impl (lines 31-250) - Core PTY functionality
• All code directly relates to PTY management

Rationale for keeping as-is:

• Single responsibility: pseudo-terminal handling
• Manageable size (260 lines)
• All components are tightly coupled
• No reusable utilities that other modules would need

---

keyboard.rs (558 lines)

Assessment: Could Benefit from Minor Refactoring

The file contains the Kitty keyboard protocol implementation with several logical sections.

Recommended Extraction: None (Optional Minor Refactoring)

While the file has distinct sections, they are all tightly coupled around the keyboard protocol:

1. Flags/Types (lines 8-95): KeyboardFlags, KeyEventType, Modifiers
2. FunctionalKey enum (lines 96-195): Key code definitions
3. KeyboardState (lines 197-292): Protocol state management
4. KeyEncoder (lines 294-548): Key encoding logic

Rationale for keeping as-is:

• All components implement a single protocol specification
• KeyEncoder depends on KeyboardState, Modifiers, FunctionalKey
• The file is under 600 lines, which is manageable
• Splitting would require importing everything back together in practice

Optional Consideration: If the codebase grows to support multiple keyboard protocols, consider:

• keyboard/mod.rs - Public API
• keyboard/kitty.rs - Kitty protocol implementation
• keyboard/legacy.rs - Legacy encoding (currently in encode_legacy_* methods)

---

graphics.rs (1846 lines)

Assessment: Needs Refactoring - Multiple Extractions Recommended

This file is too large and contains several distinct logical modules that could be separated.

Extraction 1: Animation Module

Location: Lines 391-746 (animation-related code)

Components to extract:

• AnimationState enum (lines 707-717)
• AnimationData struct (lines 719-736)
• AnimationFrame struct (lines 738-745)
• decode_gif() function (lines 393-459)
• decode_webm() function (lines 461-646, when feature enabled)

Suggested file: src/graphics/animation.rs

Dependencies:

use std::io::{Cursor, Read};
use std::time::Instant;
use image::{codecs::gif::GifDecoder, AnimationDecoder};
use super::GraphicsError;

Challenges:

• decode_webm is feature-gated (#[cfg(feature = "webm")])
• Need to re-export types from graphics/mod.rs

---

Extraction 2: Graphics Protocol Types

Location: Lines 16-162, 648-789

Components to extract:

• Action enum (lines 17-34)
• Format enum (lines 36-48)
• Transmission enum (lines 50-62)
• Compression enum (lines 64-69)
• DeleteTarget enum (lines 71-92)
• GraphicsCommand struct (lines 94-162)
• GraphicsError enum (lines 648-673)
• ImageData struct (lines 675-705)
• PlacementResult struct (lines 747-758)
• ImagePlacement struct (lines 760-789)

Suggested file: src/graphics/types.rs

Dependencies:

use std::time::Instant;
use super::animation::{AnimationData, AnimationState};

Challenges:

• GraphicsCommand has methods that depend on decoding logic
• Consider keeping GraphicsCommand::parse() and decode_* methods in types.rs or a separate parsing.rs

---

Extraction 3: Image Storage

Location: Lines 791-1807

Components to extract:

• ImageStorage struct and impl (lines 791-1807)
• ChunkBuffer struct (lines 808-813)

Suggested file: src/graphics/storage.rs

Dependencies:

use std::collections::HashMap;
use std::time::Instant;
use super::types::*;
use super::animation::*;

Challenges:

• This is the largest section (~1000 lines)
• Contains many handler methods (handle_transmit, handle_put, etc.)
• Could be further split into:
  • storage.rs - Core storage and simple operations
  • handlers.rs - Command handlers
  • animation_handlers.rs - Animation-specific handlers (lines 1026-1399)

---

Extraction 4: Base64 Utility

Location: Lines 1809-1817

Components to extract:

• base64_decode() function

Suggested file: Could go in a general src/utils.rs or stay in graphics

Dependencies:

use base64::Engine;
use super::GraphicsError;

Challenges: Minimal - this is a simple utility function

---

Recommended Graphics Module Structure

src/
  graphics/
    mod.rs          # Re-exports, module declarations
    types.rs        # Enums, structs, GraphicsCommand parsing
    animation.rs    # AnimationData, AnimationFrame, GIF/WebM decoding
    storage.rs      # ImageStorage, placement logic
    handlers.rs     # Command handlers (optional further split)

mod.rs example:

mod animation;
mod handlers;
mod storage;
mod types;

pub use animation::{AnimationData, AnimationFrame, AnimationState, decode_gif};
pub use storage::ImageStorage;
pub use types::*;

#[cfg(feature = "webm")]
pub use animation::decode_webm;

---

Implementation Priority

1. High Priority: Split graphics.rs - it's nearly 1900 lines and hard to navigate
2. Low Priority: keyboard.rs is fine as-is but could be modularized if protocol support expands
3. No Action: pty.rs is well-organized

---

Migration Notes

When splitting graphics.rs:

1. Start by creating src/graphics/ directory
2. Move graphics.rs to src/graphics/mod.rs temporarily
3. Extract types first (fewest dependencies)
4. Extract animation module
5. Extract storage module
6. Update imports in renderer.rs, terminal.rs, and any other consumers
7. Run tests after each extraction to catch breakages

The tests at the bottom of graphics.rs (lines 1819-1845) should remain in mod.rs or be split into module-specific test files.