Add backgroundOpacity for translucent terminal backgrounds

backgroundOpacity (0...1) on both platform views renders the default
background translucently, Terminal.app style: text, caret, selection
and cells with explicit backgrounds stay opaque. On macOS the opacity
rides in the alpha of nativeBackgroundColor (assigning an alpha-
bearing color is equivalent); on iOS it rides in the layer background
that already paints the terminal background there.

Fixing the pixel-verified double compositing this exposed:
- the CG path no longer fills runs that carry the default background
  (the layer background already paints it, including margins)
- the Metal path no longer emits quads for default-background runs
  (the pass clear color paints it), and the host layer background is
  cleared while Metal renders so the two never stack
- CAMetalLayer is made non-opaque when translucent

Verified by pixel sampling over a known backdrop: CG and Metal now
produce identical blends at 50% opacity, and opaque rendering is
byte-identical to before.

Author: migueldeicaza

Sources/SwiftTerm/Apple/AppleTerminalView.swift

@@ -1745,7 +1745,11 @@ extension TerminalView {
                     }
                     processedGlyphs += runGlyphsCount
 
-                    if let backgroundColor = preparedRun.backgroundColor {
+                    // Runs carrying the default background are not filled: the
+                    // view's layer background already paints that color, and
+                    // filling it again would double-composite when the
+                    // background is translucent (backgroundOpacity < 1)
+                    if let backgroundColor = preparedRun.backgroundColor, backgroundColor != nativeBackgroundColor {
                         let columnSpan = max(0, endColumn - startColumn)
                         if columnSpan > 0 {
                             var rect = CGRect(
@@ -1762,18 +1766,8 @@ extension TerminalView {
                             }
                             #endif
 
-                            if endColumn >= terminal.cols {
-                                if backgroundColor == nativeBackgroundColor {
-                                    rect.size.width = frame.width - rect.origin.x
-                                } else {
-                                    let marginX = rect.origin.x + rect.size.width
-                                    if marginX < frame.width {
-                                        let marginRect = CGRect(x: marginX, y: rect.origin.y, width: frame.width - marginX, height: rect.size.height)
-                                        context.setFillColor(cachedCGColor(nativeBackgroundColor))
-                                        context.fill(marginRect)
-                                    }
-                                }
-                            }
+                            // The right margin beyond the last column needs no
+                            // fill: the layer background paints it
 
                             context.setFillColor(cachedCGColor(backgroundColor))
                             context.fill(rect)

Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift

@@ -1144,27 +1144,16 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
                 } else if runAttributes.keys.contains(.backgroundColor) {
                     backgroundColor = runAttributes[.backgroundColor] as? TTColor
                 }
-                    if let backgroundColor = backgroundColor {
+                    // Runs carrying the default background emit no quad: the
+                    // pass's clear color already paints it (including the
+                    // margins), and a quad on top would double-composite when
+                    // the background is translucent (backgroundOpacity < 1)
+                    if let backgroundColor = backgroundColor, backgroundColor != terminalView.nativeBackgroundColor {
                         let columnSpan = max(0, endColumn - startColumn)
                         if columnSpan > 0 {
                             let x0 = lineOriginPx.x + (CGFloat(startColumn) * cellWidthPx)
                             let y0 = lineOriginPx.y
-                            var x1 = lineOriginPx.x + (CGFloat(startColumn + columnSpan) * cellWidthPx)
-                            if endColumn >= buffer.cols {
-                                if backgroundColor == terminalView.nativeBackgroundColor {
-                                    x1 = lineOriginPx.x + viewWidthPx
-                                } else {
-                                    let marginX0 = x1
-                                    let marginX1 = lineOriginPx.x + viewWidthPx
-                                    if marginX1 > marginX0 {
-                                        let (mx0, my0, mx1, my1) = transformRect(x0: marginX0, y0: y0, x1: marginX1, y1: lineOriginPx.y + cellHeightPx)
-                                        if let mClipped = self.clipRect(mx0, my0, mx1, my1, clipRect) {
-                                            let defaultBg = colorToSIMD(terminalView.nativeBackgroundColor)
-                                            backgroundCells.append(makeColorCell(x0: mClipped.0, y0: mClipped.1, x1: mClipped.2, y1: mClipped.3, color: defaultBg))
-                                        }
-                                    }
-                                }
-                            }
+                            let x1 = lineOriginPx.x + (CGFloat(startColumn + columnSpan) * cellWidthPx)
                             let y1 = lineOriginPx.y + cellHeightPx
                             let (tx0, ty0, tx1, ty1) = transformRect(x0: x0, y0: y0, x1: x1, y1: y1)
                             if let clipped = self.clipRect(tx0, ty0, tx1, ty1, clipRect) {

Sources/SwiftTerm/Mac/MacTerminalView.swift

@@ -428,6 +428,9 @@ open class TerminalView: NSView, NSTextInputClient, NSUserInterfaceValidations,
             metalView = mtkView
             metalRenderer = renderer
             metalBoundWindow = window
+            // Metal's clear color paints the background; if the host layer
+            // painted it too, a translucent background would composite twice
+            layer?.backgroundColor = NSColor.clear.cgColor
             needsDisplay = false
             mtkView.setNeedsDisplay(mtkView.bounds)
         } else {
@@ -436,6 +439,7 @@ open class TerminalView: NSView, NSTextInputClient, NSUserInterfaceValidations,
             metalView = nil
             metalRenderer = nil
             metalBoundWindow = nil
+            layer?.backgroundColor = nativeBackgroundColor.cgColor
             if let caretView = caretView {
                 caretView.isHidden = false
                 caretView.updateCursorStyle()
@@ -470,6 +474,8 @@ open class TerminalView: NSView, NSTextInputClient, NSUserInterfaceValidations,
         // so this is the colorspace they actually live in.
         if let metalLayer = mtkView.layer as? CAMetalLayer {
             metalLayer.colorspace = CGColorSpace(name: CGColorSpace.sRGB)
+            // Composite through the layer when the background is translucent
+            metalLayer.isOpaque = backgroundOpacity >= 1.0
         }
         return mtkView
     }
@@ -716,10 +722,41 @@ open class TerminalView: NSView, NSTextInputClient, NSUserInterfaceValidations,
             settingBg = true
             _nativeBg = newValue
             terminal.backgroundColor = nativeBackgroundColor.getTerminalColor ()
+            // Keep the layer background (which paints the margins) in sync,
+            // including any translucency carried in the alpha channel; when
+            // Metal renders, its clear color owns the background instead
+            layer?.backgroundColor = metalView == nil ? newValue.cgColor : NSColor.clear.cgColor
             settingBg = false
         }
     }
 
+    /**
+     * Opacity of the terminal's default background, in the 0...1 range (values are clamped).
+     *
+     * Values below 1 render the default background translucently, in the style of
+     * Terminal.app's background opacity: only the default background is affected;
+     * text, the caret, selections and cells with explicit background colors stay
+     * fully opaque. The opacity is carried in the alpha channel of
+     * `nativeBackgroundColor`, so assigning that property with an alpha-bearing
+     * color is equivalent.
+     *
+     * For the translucency to be visible, the hosting window must be configured
+     * to composite it: `window.isOpaque = false` and a clear
+     * `window.backgroundColor`.
+     */
+    public var backgroundOpacity: CGFloat {
+        get {
+            return _nativeBg.cgColor.alpha
+        }
+        set {
+            let clamped = max (0.0, min (1.0, newValue))
+            nativeBackgroundColor = _nativeBg.withAlphaComponent (clamped)
+            // CAMetalLayer defaults to opaque; it must composite when translucent
+            metalView?.layer?.isOpaque = clamped >= 1.0
+            colorsChanged ()
+        }
+    }
+
     /// Controls weather to use high ansi colors, if false terminal will use bold text instead of high ansi colors
     public var useBrightColors: Bool = true
 

Sources/SwiftTerm/iOS/iOSTerminalView.swift

@@ -423,6 +423,8 @@ open class TerminalView: UIScrollView, UITextInputTraits, UIKeyInput, UIScrollVi
             // displays.
             if let metalLayer = mtkView.layer as? CAMetalLayer {
                 metalLayer.colorspace = CGColorSpace(name: CGColorSpace.sRGB)
+                // Composite through the layer when the background is translucent
+                metalLayer.isOpaque = backgroundOpacity >= 1.0
             }
             let renderer = try MetalTerminalRenderer(view: mtkView, terminalView: self)
             mtkView.delegate = renderer
@@ -2937,6 +2939,26 @@ open class TerminalView: UIScrollView, UITextInputTraits, UIKeyInput, UIScrollVi
         caretView?.style = newStyle
         updateCaretView()
     }
+    /**
+     * Opacity of the terminal's default background, in the 0...1 range (values are clamped).
+     *
+     * On iOS the default background is painted by the view's layer, so the
+     * opacity is carried in the alpha of `layer.backgroundColor`; the view
+     * behind the terminal shows through when the value is below 1.
+     */
+    public var backgroundOpacity: CGFloat {
+        get {
+            return layer.backgroundColor?.alpha ?? 1.0
+        }
+        set {
+            let clamped = max (0.0, min (1.0, newValue))
+            if let background = layer.backgroundColor {
+                layer.backgroundColor = background.copy (alpha: clamped)
+            }
+            colorsChanged ()
+        }
+    }
+
     /// Controls how this view responds to the bell character; `.sound`
     /// preserves the historical behavior of invoking the delegate's `bell`
     public var bellStyle: BellStyle = .sound

Tests/SwiftTermTests/ProfileSupportTests.swift

@@ -187,6 +187,32 @@ final class ClearScrollbackTests {
     }
 }
 
+@MainActor
+final class BackgroundOpacityTests {
+    @Test func opacityIsClampedAndCarriedInAlpha () {
+        let view = TerminalView (frame: CGRect (x: 0, y: 0, width: 400, height: 300))
+        #expect (view.backgroundOpacity == 1.0)
+
+        view.nativeBackgroundColor = NSColor (srgbRed: 0.1, green: 0.2, blue: 0.3, alpha: 1)
+        view.backgroundOpacity = 0.5
+        #expect (abs (view.backgroundOpacity - 0.5) < 0.001)
+        #expect (abs (view.nativeBackgroundColor.alphaComponent - 0.5) < 0.001)
+        // The base color is preserved
+        #expect (abs (view.nativeBackgroundColor.redComponent - 0.1) < 0.01)
+
+        view.backgroundOpacity = 3.0
+        #expect (view.backgroundOpacity == 1.0)
+        view.backgroundOpacity = -1.0
+        #expect (view.backgroundOpacity == 0.0)
+    }
+
+    @Test func alphaBearingBackgroundReadsAsOpacity () {
+        let view = TerminalView (frame: CGRect (x: 0, y: 0, width: 400, height: 300))
+        view.nativeBackgroundColor = NSColor (srgbRed: 0, green: 0, blue: 0, alpha: 0.85)
+        #expect (abs (view.backgroundOpacity - 0.85) < 0.001)
+    }
+}
+
 @MainActor
 final class TerminalViewOptionsTests {
     @Test func startupOptionsReachTheTerminal () {