feat: terminal rendering improvements

[Poorgramer-Zack]

[PR] Terminal Rendering Improvements: Text Descenders, Line Gaps, and Layout Stability

Description:

This PR addresses several terminal rendering quality issues affecting text clarity and visual consistency, particularly on Windows with high-DPI displays.

1. 📝 Text Descender Clipping Fix

Issue: Characters with descenders (y, p, g, q, j) were being clipped by the following line, making text difficult to read.
Root Cause: The TerminalStyle was using height: 1.0, which doesn't provide sufficient vertical space for descenders in monospaced fonts.
Solution:

• Removed the hardcoded height: 1.0 from TerminalStyle in terminal_component.dart
• Allows Flutter's default line height (1.2) to provide proper spacing for descenders
• Text now renders with full glyph shapes visible
  Result: ✅ Text descenders now render correctly without clipping.

2. 🎨 Horizontal Line Gap Reduction

Issue: Visible horizontal gaps appeared between terminal rows, especially noticeable during initial load of TUI applications like OpenCode on dark backgrounds.
Root Cause: Sub-pixel positioning and anti-aliasing artifacts caused 1-2 pixel gaps between consecutive lines when Y-coordinates didn't align perfectly to pixel boundaries.
Solution:

• Full viewport background painting: Added initial background fill in render.dart to cover the entire terminal area before painting cells
• Pixel-aligned positioning: Implemented floorToDouble() for all Y-coordinate calculations to ensure pixel-perfect alignment
• Anti-aliasing disabled: Set isAntiAlias = false on all background paint objects to prevent edge blurring
• Precise cell size calculation:
  • Width: floorToDouble() to prevent horizontal stretching in ASCII art
  • Height: ceilToDouble() to prevent vertical gaps
    Result: ⚠️ Horizontal line gaps significantly reduced. Minimal gaps may still appear in specific TUI apps (e.g., OpenCode) during initial load, but are resolved once content fills the buffer.

3. 🔄 Terminal Resize Refactor

Issue: The previous resize implementation used a Future.delayed polling mechanism that was fragile and could miss resize events.
Solution:

• Moved resize logic from terminal_component.dart to terminal_bloc.dart
• Implemented terminal.onResize callback in TerminalBloc._createTerminalNode()
• xterm's RenderTerminal now directly triggers PTY resize via the callback when autoResize: true
• Removed _lastCols and _lastRows state tracking
  Result: ✅ Automatic terminal resizing now works reliably without polling.

4. 🖼️ Layout and Padding Improvements

Changes:

• Padding moved to TerminalView: Removed wrapper Container padding in terminal_component.dart and passed padding directly to TerminalView
• Theme pre-loading: Added didChangeDependencies override to load theme before first frame, preventing flash of default theme on startup
• Proper change detection: Added markNeedsPaint() to _onTerminalChange() in render.dart to ensure repaints on terminal updates

Technical Details

Modified Files:

• packages/xterm/lib/src/ui/painter.dart
  • _measureCharSize(): Explicit floorToDouble() for width, ceilToDouble() for height
  • paintLine(): Added full-line background strip with 1px overlap
  • paintCellBackground(): Removed early return for normal cells, added isAntiAlias = false
• packages/xterm/lib/src/ui/render.dart
  • _paint(): Full viewport background painting before line iteration
  • Line Y-positioning refactored to use floorToDouble() for pixel alignment
  • Added markNeedsPaint() to _onTerminalChange()
• lib/features/terminal/views/terminal_component.dart
  • Removed height: 1.0 from TerminalStyle
  • Removed polling-based resize logic
  • Moved padding from Container to TerminalView.padding
  • Added didChangeDependencies() for theme pre-loading
• lib/features/terminal/bloc/terminal_bloc.dart
  • Added terminal.onResize callback for automatic PTY resize

Verification

• ✅ Verified text descenders render correctly (y, p, g, q, j)
• ✅ Verified horizontal line gaps are significantly reduced
• ✅ Verified terminal resizing works automatically without polling
• ✅ Verified padding is consistent across all four edges
• ✅ Verified ASCII art alignment is preserved (floor width prevents stretching)
• ✅ Ran dart analyze on xterm package - No errors found
• ✅ Hot reload works correctly with all changes

Known Limitations

• OpenCode Initial Load: Minor horizontal line gaps may still appear briefly during OpenCode's initial TUI rendering phase. These gaps disappear once the buffer is fully populated with content. This is a timing issue specific to how OpenCode renders its interface and is considered acceptable given the complexity of sub-pixel rendering on different platforms.

[Copilot]

Pull request overview

This PR addresses terminal rendering quality issues on high-DPI displays by fixing text descender clipping, reducing horizontal line gaps, and refactoring the resize mechanism. The changes also add comprehensive AGENTS.md documentation files across the codebase.

Key Changes:

• Removed hardcoded line height to allow proper descender rendering (y, p, g, q, j)
• Implemented pixel-aligned positioning with triple-layer background painting to eliminate gaps
• Replaced polling-based terminal resize with event-driven callback mechanism

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/xterm/lib/src/ui/render.dart	Added full viewport background painting and pixel-aligned line positioning using floorToDouble()
packages/xterm/lib/src/ui/painter.dart	Modified cell size calculation (floor width, ceil height), added per-line background strips with 1px overlap, disabled anti-aliasing
lib/features/terminal/views/terminal_component.dart	Removed height: 1.0 from TerminalStyle, removed polling-based resize logic, moved padding to TerminalView
lib/features/terminal/bloc/terminal_bloc.dart	Added terminal.onResize callback for automatic PTY resizing
packages/xterm/AGENTS.md	New documentation file describing xterm package structure and conventions
packages/flutter_pty/AGENTS.md	New documentation file for PTY bindings package
lib/features/terminal/AGENTS.md	New documentation for terminal feature module
lib/features/workspace/AGENTS.md	New documentation for workspace feature module
lib/features/settings/AGENTS.md	New documentation for settings feature module
lib/core/AGENTS.md	New documentation for core services and utilities
AGENTS.md	Root-level project documentation
.opencode/opencode.jsonc	Configuration file for OpenCode integration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.