fix: hotfix palette surface backgrounds and macOS-only unfair lock

Author: phranck

Sources/TUIkit/App/RenderLoop.swift

@@ -30,6 +30,28 @@ private struct EnvironmentSnapshot: Equatable {
     }
 }
 
+/// ANSI background codes for each render surface in a frame.
+///
+/// Keeping these grouped avoids accidentally rendering every surface
+/// with `palette.background` and ignoring palette-specific tokens like
+/// `statusBarBackground`.
+internal struct RenderBackgroundCodes: Equatable {
+    /// Main content area background code.
+    let content: String
+
+    /// App header background code.
+    let appHeader: String
+
+    /// Status bar background code.
+    let statusBar: String
+
+    init(palette: any Palette) {
+        self.content = ANSIRenderer.backgroundCode(for: palette.background)
+        self.appHeader = ANSIRenderer.backgroundCode(for: palette.appHeaderBackground)
+        self.statusBar = ANSIRenderer.backgroundCode(for: palette.statusBarBackground)
+    }
+}
+
 // MARK: - Render Loop
 
 /// Manages the full rendering pipeline for each frame.
@@ -178,9 +200,13 @@ extension RenderLoop {
         var environment = buildEnvironment()
         environment.pulsePhase = pulsePhase
         environment.cursorTimer = cursorTimer
-        invalidateCacheIfEnvironmentChanged(environment: environment)
 
         let scene = evaluateAppBody(environment: environment)
+        if let paletteOverrideScene = scene as? any RootPaletteOverrideProvidingScene,
+           let paletteOverride = paletteOverrideScene.rootPaletteOverride() {
+            environment.palette = paletteOverride
+        }
+        invalidateCacheIfEnvironmentChanged(environment: environment)
 
         // Determine header height. On the first frame, we perform a measurement
         // pass to discover the actual header height before outputting anything.
@@ -329,15 +355,15 @@ private extension RenderLoop {
         statusBarHeight: Int,
         headerHeight: Int
     ) {
-        let bgCode = ANSIRenderer.backgroundCode(for: environment.palette.background)
+        let backgroundCodes = RenderBackgroundCodes(palette: environment.palette)
         let reset = ANSIRenderer.reset
         let contentHeight = terminalHeight - statusBarHeight - headerHeight
 
         let outputLines = diffWriter.buildOutputLines(
             buffer: buffer,
             terminalWidth: terminalWidth,
             terminalHeight: contentHeight,
-            bgCode: bgCode,
+            bgCode: backgroundCodes.content,
             reset: reset
         )
 
@@ -347,7 +373,8 @@ private extension RenderLoop {
             renderAppHeader(
                 atRow: 1,
                 terminalWidth: terminalWidth,
-                bgCode: bgCode,
+                environment: environment,
+                bgCode: backgroundCodes.appHeader,
                 reset: reset
             )
         }
@@ -362,7 +389,8 @@ private extension RenderLoop {
             renderStatusBar(
                 atRow: terminalHeight - statusBarHeight + 1,
                 terminalWidth: terminalWidth,
-                bgCode: bgCode,
+                environment: environment,
+                bgCode: backgroundCodes.statusBar,
                 reset: reset
             )
         }
@@ -406,10 +434,15 @@ private extension RenderLoop {
     }
 
     /// Renders the app header at the specified terminal row.
-    func renderAppHeader(atRow row: Int, terminalWidth: Int, bgCode: String, reset: String) {
+    func renderAppHeader(
+        atRow row: Int,
+        terminalWidth: Int,
+        environment: EnvironmentValues,
+        bgCode: String,
+        reset: String
+    ) {
         guard let contentBuffer = appHeader.contentBuffer else { return }
 
-        let environment = buildEnvironment()
         let headerView = AppHeader(contentBuffer: contentBuffer)
 
         let context = RenderContext(
@@ -431,8 +464,13 @@ private extension RenderLoop {
     }
 
     /// Renders the status bar at the specified terminal row.
-    func renderStatusBar(atRow row: Int, terminalWidth: Int, bgCode: String, reset: String) {
-        let environment = buildEnvironment()
+    func renderStatusBar(
+        atRow row: Int,
+        terminalWidth: Int,
+        environment: EnvironmentValues,
+        bgCode: String,
+        reset: String
+    ) {
         let palette = environment.palette
 
         let highlightColor =

Sources/TUIkit/App/Scene+PaletteOverride.swift

@@ -0,0 +1,51 @@
+//  🖥️ TUIKit — Terminal UI Kit for Swift
+//  Scene+PaletteOverride.swift
+//
+//  Created by LAYERED.work
+//  License: MIT
+
+// MARK: - Root Palette Discovery
+
+/// A scene that can provide a root-level palette override.
+///
+/// `RenderLoop` uses this to keep out-of-tree surfaces (status bar, app header)
+/// aligned with `.palette(...)` applied at the root view level.
+@MainActor
+internal protocol RootPaletteOverrideProvidingScene: Scene {
+    /// Returns the root palette override, if present.
+    func rootPaletteOverride() -> (any Palette)?
+}
+
+/// Type-erased access to `EnvironmentModifier` internals.
+///
+/// This is intentionally limited to root modifier chain discovery.
+@MainActor
+private protocol AnyEnvironmentModifierNode {
+    var anyEnvironmentKeyPath: AnyKeyPath { get }
+    var anyEnvironmentValue: Any { get }
+    var anyEnvironmentContent: Any { get }
+}
+
+@MainActor
+extension EnvironmentModifier: AnyEnvironmentModifierNode {
+    fileprivate var anyEnvironmentKeyPath: AnyKeyPath { keyPath }
+    fileprivate var anyEnvironmentValue: Any { value }
+    fileprivate var anyEnvironmentContent: Any { content }
+}
+
+@MainActor
+extension WindowGroup: RootPaletteOverrideProvidingScene {
+    func rootPaletteOverride() -> (any Palette)? {
+        var current: Any = content
+
+        while let modifier = current as? any AnyEnvironmentModifierNode {
+            if modifier.anyEnvironmentKeyPath == \EnvironmentValues.palette,
+               let palette = modifier.anyEnvironmentValue as? any Palette {
+                return palette
+            }
+            current = modifier.anyEnvironmentContent
+        }
+
+        return nil
+    }
+}

Sources/TUIkit/VERSION

@@ -1 +1 @@
-0.5.1
+0.5.2

Sources/TUIkitCore/Concurrency/Lock.swift

@@ -6,20 +6,20 @@
 
 import Foundation
 
-#if canImport(os)
+#if canImport(os) && os(macOS)
 import os
 #endif
 
 /// A cross-platform lock wrapper that uses the best available implementation.
 ///
-/// On Apple platforms, uses `OSAllocatedUnfairLock` for optimal performance
-/// (unfair lock with no syscall in the uncontended case). On Linux, falls back
-/// to `NSLock`.
+/// On macOS, uses `OSAllocatedUnfairLock` for optimal performance
+/// (unfair lock with no syscall in the uncontended case). On Linux and other
+/// non-macOS platforms, falls back to `NSLock`.
 ///
 /// This type is `@unchecked Sendable` because the underlying lock implementations
 /// are thread-safe by design.
 public final class Lock<State: Sendable>: @unchecked Sendable {
-    #if canImport(os)
+    #if canImport(os) && os(macOS)
     private let _lock: OSAllocatedUnfairLock<State>
 
     /// Creates a lock with the given initial state.

Tests/TUIkitTests/RenderLoopPaletteIntegrationTests.swift

@@ -0,0 +1,88 @@
+//  🖥️ TUIKit — Terminal UI Kit for Swift
+//  RenderLoopPaletteIntegrationTests.swift
+//
+//  Created by LAYERED.work
+//  License: MIT
+
+import Testing
+
+@testable import TUIkit
+
+private struct DistinctBackgroundPalette: Palette {
+    let id = "distinct-bg"
+    let name = "Distinct BG"
+    let background = Color.red
+    let foreground = Color.white
+    let accent = Color.cyan
+    let success = Color.green
+    let warning = Color.yellow
+    let error = Color.magenta
+    let info = Color.blue
+    let border = Color.brightBlack
+    let statusBarBackground = Color.green
+    let appHeaderBackground = Color.blue
+}
+
+@MainActor
+@Suite("Render Loop Palette Integration Tests")
+struct RenderLoopPaletteIntegrationTests {
+
+    @Test("RenderBackgroundCodes map each surface to the correct palette token")
+    func renderBackgroundCodesUseSurfaceTokens() {
+        let palette = DistinctBackgroundPalette()
+        let codes = RenderBackgroundCodes(palette: palette)
+
+        #expect(codes.content == ANSIRenderer.backgroundCode(for: palette.background))
+        #expect(codes.appHeader == ANSIRenderer.backgroundCode(for: palette.appHeaderBackground))
+        #expect(codes.statusBar == ANSIRenderer.backgroundCode(for: palette.statusBarBackground))
+        #expect(codes.content != codes.statusBar)
+        #expect(codes.content != codes.appHeader)
+    }
+
+    @Test("WindowGroup root palette override is discovered for built-in palettes")
+    func discoversSystemPaletteOverride() {
+        let scene = WindowGroup {
+            Text("Hello")
+                .palette(SystemPalette(.blue))
+        }
+
+        #expect(scene.rootPaletteOverride()?.id == "blue")
+    }
+
+    @Test("WindowGroup root palette override supports custom palettes")
+    func discoversCustomPaletteOverride() {
+        let palette = DistinctBackgroundPalette()
+        let scene = WindowGroup {
+            Text("Hello")
+                .palette(palette)
+        }
+
+        #expect(scene.rootPaletteOverride()?.id == palette.id)
+        #expect(scene.rootPaletteOverride()?.statusBarBackground == palette.statusBarBackground)
+    }
+
+    @Test("WindowGroup root palette override prefers the outermost palette")
+    func outermostPaletteWins() {
+        let scene = WindowGroup {
+            VStack {
+                Text("Nested")
+                    .palette(SystemPalette(.blue))
+            }
+            .palette(SystemPalette(.amber))
+        }
+
+        #expect(scene.rootPaletteOverride()?.id == "amber")
+    }
+
+    @Test("WindowGroup without root palette override returns nil")
+    func noRootOverrideReturnsNil() {
+        let scene = WindowGroup {
+            VStack {
+                Text("Nested")
+                    .palette(SystemPalette(.blue))
+            }
+        }
+
+        #expect(scene.rootPaletteOverride() == nil)
+    }
+}