Add a render loop for the Metal layer surface

Add an opt-in CAMetalLayer surface for the Metal terminal renderer. Set
SWIFTTERM_METAL_LAYER=1 with the Metal renderer enabled to use it. The
existing MTKView surface stays the default.

The new render loop prepares and draws coalesced frames on a dedicated
thread. The main thread captures all view state before it sends a frame to
the loop. It applies AppKit state, such as the scroller, caret, blink timer,
and accessibility updates, after the draw. This prevents the render thread
from read access to live view state and keeps frame preparation from blocking
the main thread.

Use a common render-target interface for MTKView and CAMetalLayer. Keep the
layer color space in sRGB and recreate a surface safely when its window moves
to a display with a different backing scale. The layer surface requires an
explicit draw call; this prevents a dirty-frame loop that does not render.

Move Metal cursor blinking to the main run loop and protect shared blink
state. Add render counts and render-loop coalescing counts so diagnostics can
detect ticks that do not produce a GPU submission.

Add surface-parity, render-loop, idle-cursor, resize-flood, and display-move
checks. The baseline harness also limits each command or baseline run to one
restored document window, so an extra hidden terminal does not change load
measurements.

Author: migueldeicaza

Sources/SwiftTerm/Apple/Metal/MetalSurfaceDiagnostics.swift

@@ -0,0 +1,142 @@
+//
+//  MetalSurfaceDiagnostics.swift
+//  SwiftTerm
+//
+//  Compares the two Metal surfaces by rendering the same content through both.
+//
+//  This exists because the equivalent unit test cannot run: the renderer loads
+//  its shaders from the SwiftTerm resource bundle, which is not present next to
+//  the SwiftPM test binary. Inside a host app the bundle is there, so the check
+//  runs for real.
+//
+//  It is the regression net for WO-F3 (replacing MTKView with a CAMetalLayer we
+//  drive ourselves). Same renderer, same shaders, same snapshot — only the
+//  surface differs, so the pixels must match exactly.
+//
+
+#if os(macOS) && canImport(MetalKit)
+import Foundation
+import AppKit
+import Metal
+import MetalKit
+import QuartzCore
+
+extension TerminalView {
+    /// Result of comparing the `MTKView` and `CAMetalLayer` render surfaces.
+    public struct MetalSurfaceComparison {
+        /// Pixels whose RGB differs between the two surfaces. Zero is the
+        /// expected result.
+        public let differingPixels: Int
+        public let totalPixels: Int
+        /// Pixels that differ from the top-left pixel. A comparison of two
+        /// blank surfaces would report a perfect match, so this guards against
+        /// the check silently passing on nothing.
+        public let nonUniformPixels: Int
+        /// Set when the comparison could not run; both counts are zero then.
+        public let unavailableReason: String?
+
+        /// True only when the surfaces agree *and* they actually drew
+        /// something.
+        public var matches: Bool {
+            unavailableReason == nil && differingPixels == 0 && nonUniformPixels > 0
+        }
+    }
+
+    /// Renders deterministic content through both Metal surfaces and compares
+    /// the results.
+    ///
+    /// Uses a terminal view it creates and sizes to match the surfaces, rather
+    /// than a live one: the renderer positions rows from
+    /// `SnapshotRenderContext.viewBounds`, so a view whose bounds differ from
+    /// the drawable puts every row outside it and both surfaces come back
+    /// blank — which compares equal and proves nothing.
+    ///
+    /// Diagnostic only — it builds throwaway renderers and blocks on the GPU,
+    /// so it must not be called on a frame path.
+    public static func compareMetalSurfaces(width: Int = 320, height: Int = 120) -> MetalSurfaceComparison {
+        func unavailable(_ reason: String) -> MetalSurfaceComparison {
+            MetalSurfaceComparison(differingPixels: 0, totalPixels: 0,
+                                   nonUniformPixels: 0, unavailableReason: reason)
+        }
+
+        guard let device = MTLCreateSystemDefaultDevice() else {
+            return unavailable("no Metal device")
+        }
+        let size = CGSize(width: CGFloat(width), height: CGFloat(height))
+        let frame = CGRect(origin: .zero, size: size)
+
+        let mtkView = MTKView(frame: frame, device: device)
+        mtkView.colorPixelFormat = .bgra8Unorm
+        mtkView.framebufferOnly = false        // needed to read the texture back
+        mtkView.isPaused = true
+        mtkView.enableSetNeedsDisplay = true
+
+        let layerView = TerminalMetalLayerView(frame: frame)
+        layerView.renderDevice = device
+        layerView.metalLayer.framebufferOnly = false
+
+        // Sized to the surfaces so rows land inside the drawable, and fed
+        // content with several colors so a blank render cannot pass.
+        let source = TerminalView(frame: frame)
+        source.feed(text: "SwiftTerm surface parity check\r\n"
+                    + "\u{1b}[31mred\u{1b}[32m green\u{1b}[34m blue\u{1b}[0m plain\r\n"
+                    + "\u{1b}[1mbold\u{1b}[0m \u{1b}[4munderline\u{1b}[0m 0123456789\r\n")
+
+        guard let fromMTK = renderPixels(source: source, target: mtkView, size: size),
+              let fromLayer = renderPixels(source: source, target: layerView, size: size) else {
+            return unavailable("no drawable or renderer available")
+        }
+        guard fromMTK.count == fromLayer.count else {
+            return unavailable("surfaces produced different buffer sizes")
+        }
+
+        var differing = 0
+        var nonUniform = 0
+        let firstR = fromMTK[0], firstG = fromMTK[1], firstB = fromMTK[2]
+        for index in stride(from: 0, to: fromMTK.count, by: 4) where
+            fromMTK[index] != firstR || fromMTK[index + 1] != firstG ||
+            fromMTK[index + 2] != firstB {
+            nonUniform += 1
+        }
+        for index in stride(from: 0, to: fromMTK.count, by: 4) where
+            fromMTK[index] != fromLayer[index] ||
+            fromMTK[index + 1] != fromLayer[index + 1] ||
+            fromMTK[index + 2] != fromLayer[index + 2] {
+            differing += 1
+        }
+        return MetalSurfaceComparison(differingPixels: differing,
+                                      totalPixels: fromMTK.count / 4,
+                                      nonUniformPixels: nonUniform,
+                                      unavailableReason: nil)
+    }
+
+    private static func renderPixels(source: TerminalView,
+                                     target: any MetalRenderTarget,
+                                     size: CGSize) -> [UInt8]? {
+        guard let renderer = try? MetalTerminalRenderer(view: target, terminalView: source) else {
+            return nil
+        }
+        renderer.waitForCompletionAfterCommit = true
+        renderer.capturesRenderedTexture = true
+        var mutable = target
+        mutable.renderContentsScale = 1
+        mutable.renderDrawableSize = size
+        renderer.render()
+
+        // The texture the renderer actually drew into. Asking the surface for
+        // another drawable would return a different, unrendered one.
+        guard let texture = renderer.lastRenderedTexture else { return nil }
+        guard texture.width > 0, texture.height > 0 else { return nil }
+        let bytesPerRow = texture.width * 4
+        var bytes = [UInt8](repeating: 0, count: bytesPerRow * texture.height)
+        bytes.withUnsafeMutableBytes { raw in
+            guard let base = raw.baseAddress else { return }
+            texture.getBytes(base,
+                             bytesPerRow: bytesPerRow,
+                             from: MTLRegionMake2D(0, 0, texture.width, texture.height),
+                             mipmapLevel: 0)
+        }
+        return bytes
+    }
+}
+#endif

Sources/SwiftTerm/Apple/RenderLoop.swift

@@ -0,0 +1,166 @@
+//
+//  RenderLoop.swift
+//  SwiftTerm
+//
+//  A dedicated thread that prepares and draws terminal frames.
+//
+//  The main thread pays about 6 ms per frame on the Metal path, essentially
+//  all of it building row data (io-gaps.md G1). That cost is CPU work rather
+//  than a blocked wait, so moving it off main genuinely frees the main thread
+//  instead of relocating a stall — and once it is off main, blocking for a
+//  drawable costs the main thread nothing either.
+//
+//  This type is deliberately small. It owns a thread, a semaphore and a
+//  coalescing flag, and it knows nothing about terminals or Metal.
+//
+
+#if os(macOS) || os(iOS) || os(visionOS) || os(macCatalyst)
+import Foundation
+
+/// Counters describing how the render loop behaved over a measurement window.
+struct RenderLoopCounters {
+    /// Calls to `signal`.
+    var signals = 0
+    /// Frames the loop actually ran.
+    var frames = 0
+    /// Signals that arrived while one was already pending and were folded into
+    /// it. A large value means the producer is outrunning the renderer, which
+    /// is the intended behaviour under a flood, not a fault.
+    var coalesced = 0
+}
+
+/// Runs a callback on a dedicated high-priority thread, one frame at a time.
+///
+/// Signals coalesce: several `signal()` calls before the loop wakes produce one
+/// frame, so a flood cannot queue work faster than it can be drawn.
+final class RenderLoop {
+    /// Renders one frame. Called on the render thread, never re-entrantly, and
+    /// always with `frameLock` held.
+    var onRender: (() -> Void)?
+
+    /// Serialises a frame against structural changes made on the main thread:
+    /// enabling or disabling Metal, rebinding the surface after a display
+    /// change, a synchronous draw for a screenshot.
+    ///
+    /// **Never take this while holding the terminal lock.** The render thread
+    /// takes them in the order frameLock -> terminalLock, so the reverse order
+    /// on main deadlocks. Structural operations hold neither when they start.
+    let frameLock = NSLock()
+
+    private let semaphore = DispatchSemaphore(value: 0)
+    private let stateLock = NSLock()
+    private var pending = false
+    private var stopped = false
+    private var thread: Thread?
+    private var counters = RenderLoopCounters()
+
+    /// Starts the render thread. Idempotent.
+    func start () {
+        stateLock.lock()
+        let alreadyRunning = thread != nil || stopped
+        stateLock.unlock()
+        guard !alreadyRunning else { return }
+
+        let thread = Thread { [weak self] in
+            self?.run()
+        }
+        thread.name = "org.tirania.SwiftTerm.render"
+        // The frame deadline is the display's, the same class of deadline the
+        // main thread runs at. Anything lower and a busy machine drops frames
+        // that the main-thread path would have produced.
+        thread.qualityOfService = .userInteractive
+        stateLock.lock()
+        self.thread = thread
+        stateLock.unlock()
+        thread.start()
+    }
+
+    /// Asks for one frame. Safe from any thread, including the render thread.
+    func signal () {
+        stateLock.lock()
+        counters.signals += 1
+        guard !stopped else {
+            stateLock.unlock()
+            return
+        }
+        let wasPending = pending
+        pending = true
+        if wasPending {
+            counters.coalesced += 1
+        }
+        stateLock.unlock()
+
+        // Only the transition from clean to pending posts, so the semaphore
+        // never accumulates a backlog of frames to catch up on.
+        if !wasPending {
+            semaphore.signal()
+        }
+    }
+
+    /// Stops the loop permanently and waits for any frame in flight to finish.
+    ///
+    /// Waiting matters: the caller is usually tearing down the surface the
+    /// in-flight frame is drawing into.
+    func invalidate () {
+        stateLock.lock()
+        let wasStopped = stopped
+        stopped = true
+        pending = false
+        stateLock.unlock()
+        guard !wasStopped else { return }
+
+        semaphore.signal()
+        // The loop drops frameLock between frames and takes it again only
+        // after re-checking `stopped`, so acquiring it here means no frame is
+        // running and none will start.
+        frameLock.lock()
+        frameLock.unlock()
+
+        stateLock.lock()
+        thread = nil
+        onRender = nil
+        stateLock.unlock()
+    }
+
+    var isRunning: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return thread != nil && !stopped
+    }
+
+    var currentCounters: RenderLoopCounters {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return counters
+    }
+
+    func resetCounters () {
+        stateLock.lock()
+        counters = RenderLoopCounters()
+        stateLock.unlock()
+    }
+
+    private func run () {
+        while true {
+            semaphore.wait()
+
+            stateLock.lock()
+            if stopped {
+                stateLock.unlock()
+                return
+            }
+            // Cleared before the frame, not after: a change arriving while
+            // this frame is being drawn must schedule the next one.
+            pending = false
+            counters.frames += 1
+            let render = onRender
+            stateLock.unlock()
+
+            guard let render else { continue }
+            frameLock.lock()
+            render()
+            frameLock.unlock()
+        }
+    }
+}
+#endif