Skip to content

fix: prevent black Metal terminal frames#1129

Merged
batonogov merged 1 commit into
mainfrom
fix/1128-metal-terminal-black-frame
Jul 15, 2026
Merged

fix: prevent black Metal terminal frames#1129
batonogov merged 1 commit into
mainfrom
fix/1128-metal-terminal-black-frame

Conversation

@batonogov

Copy link
Copy Markdown
Owner

Summary

  • route terminal recovery redraws through the renderer that owns the pixels
  • invalidate SwiftTerm Metal row caches and its nested on-demand MTKView
  • retry the first frame at four bounded intervals after every view attachment
  • cancel pending retries on detach and preserve the CoreGraphics fallback
  • log Metal initialization failures instead of silently swallowing them
  • cover initial attachment, detach, same-window reattachment, and backend routing

Root cause

With Metal enabled, SwiftTerm returns early from the outer LocalProcessTerminalView draw path because a nested MTKView owns presentation. Pine still called setNeedsDisplay and displayIfNeeded on the outer view, so recovery redraws could be no-ops. A freshly attached CAMetalLayer may also temporarily have no currentDrawable; SwiftTerm records the missed frame, but that state is only consumed after a successful command buffer completes.

The compatibility bridge uses public SwiftTerm 1.14 APIs: selectionChanged(source:) marks the visible Metal range dirty, while a same-size setFrameSize(_:) immediately reaches SwiftTerm internal Metal display request without changing the PTY geometry.

Testing

  • SwiftLint 0.65.0 on all changed Swift files: 0 violations
  • Swift 6.4 syntax parsing and targeted type checking
  • reentrancy guard for Pine sources
  • standalone runtime check on the host Metal device confirmed that the backend-aware request invalidates the nested MTKView
  • full xcodebuild test suite was not run locally because /Applications/Xcode.app is unavailable; CI should run the complete suite

Fixes #1128

@batonogov batonogov added bug Something isn't working terminal Terminal emulator related priority: high Critical priority UX User experience labels Jul 15, 2026
@batonogov batonogov merged commit c924d8f into main Jul 15, 2026
16 of 22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working priority: high Critical priority terminal Terminal emulator related UX User experience

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(terminal): newly created Metal terminal tab intermittently remains black until a later redraw trigger

1 participant