@fairyhunter13/opentui-core 0.1.112 → 0.1.114

package/src/zig/renderer.zig

@@ -0,0 +1,1393 @@
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const ansi = @import("ansi.zig");
+const buf = @import("buffer.zig");
+const gp = @import("grapheme.zig");
+const link = @import("link.zig");
+const Terminal = @import("terminal.zig");
+const logger = @import("logger.zig");
+
+pub const RGBA = ansi.RGBA;
+pub const OptimizedBuffer = buf.OptimizedBuffer;
+pub const TextAttributes = ansi.TextAttributes;
+pub const CursorStyle = Terminal.CursorStyle;
+
+const CLEAR_CHAR = '\u{0a00}';
+const MAX_STAT_SAMPLES = 30;
+const STAT_SAMPLE_CAPACITY = 30;
+
+const COLOR_EPSILON_DEFAULT: f32 = 0.00001;
+const OUTPUT_BUFFER_SIZE = 1024 * 1024 * 2; // 2MB
+
+pub const RendererError = error{
+    OutOfMemory,
+    InvalidDimensions,
+    ThreadingFailed,
+    WriteFailed,
+};
+
+fn rgbaComponentToU8(component: f32) u8 {
+    if (!std.math.isFinite(component)) return 0;
+
+    const clamped = std.math.clamp(component, 0.0, 1.0);
+    return @intFromFloat(@round(clamped * 255.0));
+}
+
+pub const DebugOverlayCorner = enum {
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+};
+
+pub const CliRenderer = struct {
+    width: u32,
+    height: u32,
+    currentRenderBuffer: *OptimizedBuffer,
+    nextRenderBuffer: *OptimizedBuffer,
+    pool: *gp.GraphemePool,
+    backgroundColor: RGBA,
+    renderOffset: u32,
+    terminal: Terminal,
+    testing: bool = false,
+    useAlternateScreen: bool = true,
+    terminalSetup: bool = false,
+
+    renderStats: struct {
+        lastFrameTime: f64,
+        averageFrameTime: f64,
+        frameCount: u64,
+        fps: u32,
+        cellsUpdated: u32,
+        renderTime: ?f64,
+        overallFrameTime: ?f64,
+        bufferResetTime: ?f64,
+        stdoutWriteTime: ?f64,
+        heapUsed: u32,
+        heapTotal: u32,
+        arrayBuffers: u32,
+        frameCallbackTime: ?f64,
+    },
+    statSamples: struct {
+        lastFrameTime: std.ArrayListUnmanaged(f64),
+        renderTime: std.ArrayListUnmanaged(f64),
+        overallFrameTime: std.ArrayListUnmanaged(f64),
+        bufferResetTime: std.ArrayListUnmanaged(f64),
+        stdoutWriteTime: std.ArrayListUnmanaged(f64),
+        cellsUpdated: std.ArrayListUnmanaged(u32),
+        frameCallbackTime: std.ArrayListUnmanaged(f64),
+    },
+    lastRenderTime: i64,
+    allocator: Allocator,
+    renderThread: ?std.Thread = null,
+    stdoutBuffer: [4096]u8,
+    writeOutBuf: [1024]u8 = undefined,
+    debugOverlay: struct {
+        enabled: bool,
+        corner: DebugOverlayCorner,
+    } = .{
+        .enabled = false,
+        .corner = .bottomRight,
+    },
+    // Threading
+    useThread: bool = false,
+    renderMutex: std.Thread.Mutex = .{},
+    renderCondition: std.Thread.Condition = .{},
+    renderRequested: bool = false,
+    shouldTerminate: bool = false,
+    renderInProgress: bool = false,
+    currentOutputBuffer: []u8 = &[_]u8{},
+    currentOutputLen: usize = 0,
+
+    // Hit grid for mouse event dispatch.
+    //
+    // The hit grid is a screen-sized array where each cell stores the renderable ID
+    // at that position. Mouse events query checkHit(x, y) to find which element to
+    // dispatch to.
+    //
+    // Double buffering: During render, addToHitGrid writes to nextHitGrid. After
+    // render completes, the buffers swap. This keeps hit testing consistent during
+    // a frame. Queries see the previous frame's state, not a half-built grid.
+    //
+    // On-demand sync: When scroll/translate changes between renders, the TypeScript
+    // layer can rebuild currentHitGrid directly via addToCurrentHitGridClipped. This
+    // updates hover states immediately rather than waiting for the next render.
+    //
+    // Scissor clipping: The hitScissorStack mirrors overflow:hidden regions. Elements
+    // outside their parent's visible area are excluded from hit testing. The stack
+    // uses screen coordinates. Buffered renderables need getHitGridScissorRect() to
+    // convert from buffer-local (0,0) to their actual screen position.
+    currentHitGrid: []u32,
+    nextHitGrid: []u32,
+    hitGridWidth: u32,
+    hitGridHeight: u32,
+    hitScissorStack: std.ArrayListUnmanaged(buf.ClipRect),
+    hitGridDirty: bool = false,
+
+    lastCursorStyleTag: ?u8 = null,
+    lastCursorBlinking: ?bool = null,
+    lastCursorColorRGB: ?[3]u8 = null,
+    lastMousePointerStyle: Terminal.MousePointerStyle = .default,
+
+    // Preallocated output buffer
+    var outputBuffer: [OUTPUT_BUFFER_SIZE]u8 = undefined;
+    var outputBufferLen: usize = 0;
+    var outputBufferB: [OUTPUT_BUFFER_SIZE]u8 = undefined;
+    var outputBufferBLen: usize = 0;
+    var activeBuffer: enum { A, B } = .A;
+
+    const OutputBufferWriter = struct {
+        pub fn write(_: void, data: []const u8) !usize {
+            const bufferLen = if (activeBuffer == .A) &outputBufferLen else &outputBufferBLen;
+            const buffer = if (activeBuffer == .A) &outputBuffer else &outputBufferB;
+
+            if (bufferLen.* + data.len > buffer.len) {
+                // TODO: Resize buffer when necessary
+                return error.BufferFull;
+            }
+
+            @memcpy(buffer.*[bufferLen.*..][0..data.len], data);
+            bufferLen.* += data.len;
+
+            return data.len;
+        }
+
+        // TODO: std.io.GenericWriter is deprecated, however the "correct" option seems to be much more involved
+        // So I have simply used GenericWriter here, and then the proper migration can be done later
+        pub fn writer() std.io.GenericWriter(void, error{BufferFull}, write) {
+            return .{ .context = {} };
+        }
+    };
+
+    pub fn create(allocator: Allocator, width: u32, height: u32, pool: *gp.GraphemePool, testing: bool) !*CliRenderer {
+        return createWithOptions(allocator, width, height, pool, testing, false);
+    }
+
+    pub fn createWithOptions(
+        allocator: Allocator,
+        width: u32,
+        height: u32,
+        pool: *gp.GraphemePool,
+        testing: bool,
+        remote: bool,
+    ) !*CliRenderer {
+        const self = try allocator.create(CliRenderer);
+        errdefer allocator.destroy(self);
+
+        const currentBuffer = try OptimizedBuffer.init(allocator, width, height, .{ .pool = pool, .width_method = .unicode, .id = "current buffer" });
+        errdefer currentBuffer.deinit();
+        const nextBuffer = try OptimizedBuffer.init(allocator, width, height, .{ .pool = pool, .width_method = .unicode, .id = "next buffer" });
+        errdefer nextBuffer.deinit();
+
+        // stat sample arrays
+        var lastFrameTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer lastFrameTime.deinit(allocator);
+        var renderTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer renderTime.deinit(allocator);
+        var overallFrameTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer overallFrameTime.deinit(allocator);
+        var bufferResetTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer bufferResetTime.deinit(allocator);
+        var stdoutWriteTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer stdoutWriteTime.deinit(allocator);
+        var cellsUpdated: std.ArrayListUnmanaged(u32) = .{};
+        errdefer cellsUpdated.deinit(allocator);
+        var frameCallbackTimes: std.ArrayListUnmanaged(f64) = .{};
+        errdefer frameCallbackTimes.deinit(allocator);
+
+        try lastFrameTime.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try renderTime.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try overallFrameTime.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try bufferResetTime.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try stdoutWriteTime.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try cellsUpdated.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+        try frameCallbackTimes.ensureTotalCapacity(allocator, STAT_SAMPLE_CAPACITY);
+
+        const hitGridSize = width * height;
+        const currentHitGrid = try allocator.alloc(u32, hitGridSize);
+        errdefer allocator.free(currentHitGrid);
+        const nextHitGrid = try allocator.alloc(u32, hitGridSize);
+        errdefer allocator.free(nextHitGrid);
+        @memset(currentHitGrid, 0); // Initialize with 0 (no renderable)
+        @memset(nextHitGrid, 0);
+        const hitScissorStack: std.ArrayListUnmanaged(buf.ClipRect) = .{};
+
+        self.* = .{
+            .width = width,
+            .height = height,
+            .currentRenderBuffer = currentBuffer,
+            .nextRenderBuffer = nextBuffer,
+            .pool = pool,
+            .backgroundColor = .{ 0.0, 0.0, 0.0, 0.0 },
+            .renderOffset = 0,
+            .terminal = Terminal.init(.{ .remote = remote }),
+            .testing = testing,
+            .lastCursorStyleTag = null,
+            .lastCursorBlinking = null,
+            .lastCursorColorRGB = null,
+
+            .renderStats = .{
+                .lastFrameTime = 0,
+                .averageFrameTime = 0,
+                .frameCount = 0,
+                .fps = 0,
+                .cellsUpdated = 0,
+                .renderTime = null,
+                .overallFrameTime = null,
+                .bufferResetTime = null,
+                .stdoutWriteTime = null,
+                .heapUsed = 0,
+                .heapTotal = 0,
+                .arrayBuffers = 0,
+                .frameCallbackTime = null,
+            },
+            .statSamples = .{
+                .lastFrameTime = lastFrameTime,
+                .renderTime = renderTime,
+                .overallFrameTime = overallFrameTime,
+                .bufferResetTime = bufferResetTime,
+                .stdoutWriteTime = stdoutWriteTime,
+                .cellsUpdated = cellsUpdated,
+                .frameCallbackTime = frameCallbackTimes,
+            },
+            .lastRenderTime = std.time.microTimestamp(),
+            .allocator = allocator,
+            .stdoutBuffer = undefined,
+            .currentHitGrid = currentHitGrid,
+            .nextHitGrid = nextHitGrid,
+            .hitGridWidth = width,
+            .hitGridHeight = height,
+            .hitScissorStack = hitScissorStack,
+        };
+
+        nextBuffer.setBlendBackdropColor(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], 1.0 });
+
+        try currentBuffer.clear(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], self.backgroundColor[3] }, CLEAR_CHAR);
+        try nextBuffer.clear(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], self.backgroundColor[3] }, null);
+
+        return self;
+    }
+
+    pub fn destroy(self: *CliRenderer) void {
+        self.renderMutex.lock();
+        while (self.renderInProgress) {
+            self.renderCondition.wait(&self.renderMutex);
+        }
+
+        self.shouldTerminate = true;
+        self.renderRequested = true;
+        self.renderCondition.signal();
+        self.renderMutex.unlock();
+
+        if (self.renderThread) |thread| {
+            thread.join();
+        }
+
+        self.performShutdownSequence();
+        self.terminal.deinit();
+
+        self.currentRenderBuffer.deinit();
+        self.nextRenderBuffer.deinit();
+
+        // Free stat sample arrays
+        self.statSamples.lastFrameTime.deinit(self.allocator);
+        self.statSamples.renderTime.deinit(self.allocator);
+        self.statSamples.overallFrameTime.deinit(self.allocator);
+        self.statSamples.bufferResetTime.deinit(self.allocator);
+        self.statSamples.stdoutWriteTime.deinit(self.allocator);
+        self.statSamples.cellsUpdated.deinit(self.allocator);
+        self.statSamples.frameCallbackTime.deinit(self.allocator);
+
+        self.allocator.free(self.currentHitGrid);
+        self.allocator.free(self.nextHitGrid);
+        self.hitScissorStack.deinit(self.allocator);
+
+        self.allocator.destroy(self);
+    }
+
+    pub fn setupTerminal(self: *CliRenderer, useAlternateScreen: bool) void {
+        self.useAlternateScreen = useAlternateScreen;
+        self.terminalSetup = true;
+
+        var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+        const writer = &stdoutWriter.interface;
+
+        self.terminal.queryTerminalSend(writer) catch {
+            logger.warn("Failed to query terminal capabilities", .{});
+        };
+        writer.flush() catch {};
+
+        self.setupTerminalWithoutDetection(useAlternateScreen);
+    }
+
+    fn setupTerminalWithoutDetection(self: *CliRenderer, useAlternateScreen: bool) void {
+        var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+        const writer = &stdoutWriter.interface;
+
+        writer.writeAll(ansi.ANSI.saveCursorState) catch {};
+
+        if (useAlternateScreen) {
+            self.terminal.enterAltScreen(writer) catch {};
+        } else {
+            ansi.ANSI.makeRoomForRendererOutput(writer, @max(self.height, 1)) catch {};
+        }
+
+        self.terminal.setCursorPosition(1, 1, false);
+        const useKitty = self.terminal.opts.kitty_keyboard_flags > 0;
+        self.terminal.enableDetectedFeatures(writer, useKitty) catch {};
+
+        writer.flush() catch {};
+    }
+
+    pub fn suspendRenderer(self: *CliRenderer) void {
+        if (!self.terminalSetup) return;
+        self.performShutdownSequence();
+    }
+
+    pub fn resumeRenderer(self: *CliRenderer) void {
+        if (!self.terminalSetup) return;
+        self.setupTerminalWithoutDetection(self.useAlternateScreen);
+    }
+
+    pub fn performShutdownSequence(self: *CliRenderer) void {
+        if (!self.terminalSetup) return;
+
+        var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+        const direct = &stdoutWriter.interface;
+        self.terminal.resetState(direct) catch {
+            logger.warn("Failed to reset terminal state", .{});
+        };
+
+        if (self.useAlternateScreen) {
+            direct.flush() catch {};
+        } else if (self.renderOffset == 0) {
+            direct.writeAll("\x1b[H\x1b[J") catch {};
+            direct.flush() catch {};
+        } else if (self.renderOffset > 0) {
+            // Currently still handled in typescript
+            // const consoleEndLine = self.height - self.renderOffset;
+            // ansi.ANSI.moveToOutput(direct, 1, consoleEndLine) catch {};
+        }
+
+        // NOTE: This messes up state after shutdown, but might be necessary for windows?
+        // direct.writeAll(ansi.ANSI.restoreCursorState) catch {};
+
+        direct.writeAll(ansi.ANSI.resetCursorColorFallback) catch {};
+        direct.writeAll(ansi.ANSI.resetCursorColor) catch {};
+        direct.writeAll(ansi.ANSI.defaultCursorStyle) catch {};
+        // Workaround for Ghostty not showing the cursor after shutdown for some reason
+        direct.writeAll(ansi.ANSI.showCursor) catch {};
+        direct.flush() catch {};
+        std.Thread.sleep(10 * std.time.ns_per_ms);
+        direct.writeAll(ansi.ANSI.showCursor) catch {};
+        direct.flush() catch {};
+        std.Thread.sleep(10 * std.time.ns_per_ms);
+    }
+
+    fn addStatSample(self: *CliRenderer, comptime T: type, samples: *std.ArrayListUnmanaged(T), value: T) void {
+        samples.append(self.allocator, value) catch return;
+
+        if (samples.items.len > MAX_STAT_SAMPLES) {
+            _ = samples.orderedRemove(0);
+        }
+    }
+
+    fn getStatAverage(comptime T: type, samples: *const std.ArrayListUnmanaged(T)) T {
+        if (samples.items.len == 0) {
+            return 0;
+        }
+
+        var sum: T = 0;
+        for (samples.items) |value| {
+            sum += value;
+        }
+
+        if (@typeInfo(T) == .float) {
+            return sum / @as(T, @floatFromInt(samples.items.len));
+        } else {
+            return sum / @as(T, @intCast(samples.items.len));
+        }
+    }
+
+    pub fn setUseThread(self: *CliRenderer, useThread: bool) void {
+        if (self.useThread == useThread) return;
+
+        if (useThread) {
+            if (self.renderThread == null) {
+                self.renderThread = std.Thread.spawn(.{}, renderThreadFn, .{self}) catch |err| {
+                    std.log.warn("Failed to spawn render thread: {}, falling back to non-threaded mode", .{err});
+                    self.useThread = false;
+                    return;
+                };
+            }
+        } else {
+            if (self.renderThread) |thread| {
+                // Signal the render thread to terminate (same pattern as destroy)
+                self.renderMutex.lock();
+                while (self.renderInProgress) {
+                    self.renderCondition.wait(&self.renderMutex);
+                }
+                self.shouldTerminate = true;
+                self.renderRequested = true;
+                self.renderCondition.signal();
+                self.renderMutex.unlock();
+
+                thread.join();
+                self.renderThread = null;
+
+                // Reset termination flag so thread can be re-enabled later
+                self.shouldTerminate = false;
+            }
+        }
+
+        self.useThread = useThread;
+    }
+
+    pub fn updateStats(self: *CliRenderer, time: f64, fps: u32, frameCallbackTime: f64) void {
+        self.renderStats.overallFrameTime = time;
+        self.renderStats.fps = fps;
+        self.renderStats.frameCallbackTime = frameCallbackTime;
+
+        self.addStatSample(f64, &self.statSamples.overallFrameTime, time);
+        self.addStatSample(f64, &self.statSamples.frameCallbackTime, frameCallbackTime);
+    }
+
+    pub fn updateMemoryStats(self: *CliRenderer, heapUsed: u32, heapTotal: u32, arrayBuffers: u32) void {
+        self.renderStats.heapUsed = heapUsed;
+        self.renderStats.heapTotal = heapTotal;
+        self.renderStats.arrayBuffers = arrayBuffers;
+    }
+
+    pub fn resize(self: *CliRenderer, width: u32, height: u32) !void {
+        if (self.width == width and self.height == height) return;
+
+        self.width = width;
+        self.height = height;
+
+        try self.currentRenderBuffer.resize(width, height);
+        try self.nextRenderBuffer.resize(width, height);
+        self.nextRenderBuffer.setBlendBackdropColor(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], 1.0 });
+
+        try self.currentRenderBuffer.clear(.{ 0.0, 0.0, 0.0, 1.0 }, CLEAR_CHAR);
+        try self.nextRenderBuffer.clear(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], self.backgroundColor[3] }, null);
+
+        const newHitGridSize = width * height;
+        const currentHitGridSize = self.hitGridWidth * self.hitGridHeight;
+        if (newHitGridSize > currentHitGridSize) {
+            const newCurrentHitGrid = try self.allocator.alloc(u32, newHitGridSize);
+            errdefer self.allocator.free(newCurrentHitGrid);
+            const newNextHitGrid = try self.allocator.alloc(u32, newHitGridSize);
+            @memset(newCurrentHitGrid, 0);
+            @memset(newNextHitGrid, 0);
+
+            self.allocator.free(self.currentHitGrid);
+            self.allocator.free(self.nextHitGrid);
+            self.currentHitGrid = newCurrentHitGrid;
+            self.nextHitGrid = newNextHitGrid;
+        }
+
+        // Always update dimensions. The backing buffer is at least as large as
+        // width*height, so this is safe even when the terminal shrinks. Without
+        // this, checkHit keeps using stale dimensions after a shrink and returns
+        // 0 for any coordinate beyond the old bounds.
+        self.hitGridWidth = width;
+        self.hitGridHeight = height;
+
+        const cursor = self.terminal.getCursorPosition();
+        self.terminal.setCursorPosition(@min(cursor.x, width), @min(cursor.y, height), cursor.visible);
+    }
+
+    pub fn setBackgroundColor(self: *CliRenderer, rgba: RGBA) void {
+        self.backgroundColor = rgba;
+        self.nextRenderBuffer.setBlendBackdropColor(.{ rgba[0], rgba[1], rgba[2], 1.0 });
+    }
+
+    pub fn setRenderOffset(self: *CliRenderer, offset: u32) void {
+        self.renderOffset = offset;
+    }
+
+    fn renderThreadFn(self: *CliRenderer) void {
+        while (true) {
+            self.renderMutex.lock();
+            while (!self.renderRequested and !self.shouldTerminate) {
+                self.renderCondition.wait(&self.renderMutex);
+            }
+
+            if (self.shouldTerminate and !self.renderRequested) {
+                self.renderMutex.unlock();
+                break;
+            }
+
+            self.renderRequested = false;
+
+            const outputData = self.currentOutputBuffer;
+            const outputLen = self.currentOutputLen;
+
+            const writeStart = std.time.microTimestamp();
+
+            if (outputLen > 0 and !self.testing) {
+                var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+                const w = &stdoutWriter.interface;
+                w.writeAll(outputData[0..outputLen]) catch {};
+                w.flush() catch {};
+            }
+
+            // Signal that rendering is complete
+            self.renderStats.stdoutWriteTime = @as(f64, @floatFromInt(std.time.microTimestamp() - writeStart));
+            self.renderInProgress = false;
+            self.renderCondition.signal();
+            self.renderMutex.unlock();
+        }
+    }
+
+    // Render once with current state
+    pub fn render(self: *CliRenderer, force: bool) void {
+        const now = std.time.microTimestamp();
+        const deltaTimeMs = @as(f64, @floatFromInt(now - self.lastRenderTime));
+        const deltaTime = deltaTimeMs / 1000.0; // Convert to seconds
+
+        self.lastRenderTime = now;
+        self.renderDebugOverlay();
+
+        self.prepareRenderFrame(force);
+
+        if (self.useThread) {
+            self.renderMutex.lock();
+            while (self.renderInProgress) {
+                self.renderCondition.wait(&self.renderMutex);
+            }
+
+            if (activeBuffer == .A) {
+                activeBuffer = .B;
+                self.currentOutputBuffer = &outputBuffer;
+                self.currentOutputLen = outputBufferLen;
+            } else {
+                activeBuffer = .A;
+                self.currentOutputBuffer = &outputBufferB;
+                self.currentOutputLen = outputBufferBLen;
+            }
+
+            self.renderRequested = true;
+            self.renderInProgress = true;
+            self.renderCondition.signal();
+            self.renderMutex.unlock();
+        } else {
+            const writeStart = std.time.microTimestamp();
+            if (!self.testing) {
+                var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+                const w = &stdoutWriter.interface;
+                w.writeAll(outputBuffer[0..outputBufferLen]) catch {};
+                w.flush() catch {};
+            }
+            self.renderStats.stdoutWriteTime = @as(f64, @floatFromInt(std.time.microTimestamp() - writeStart));
+        }
+
+        self.renderStats.lastFrameTime = deltaTime * 1000.0;
+        self.renderStats.frameCount += 1;
+
+        self.addStatSample(f64, &self.statSamples.lastFrameTime, deltaTime * 1000.0);
+        if (self.renderStats.renderTime) |rt| {
+            self.addStatSample(f64, &self.statSamples.renderTime, rt);
+        }
+        if (self.renderStats.bufferResetTime) |brt| {
+            self.addStatSample(f64, &self.statSamples.bufferResetTime, brt);
+        }
+        if (self.renderStats.stdoutWriteTime) |swt| {
+            self.addStatSample(f64, &self.statSamples.stdoutWriteTime, swt);
+        }
+        self.addStatSample(u32, &self.statSamples.cellsUpdated, self.renderStats.cellsUpdated);
+    }
+
+    pub fn getNextBuffer(self: *CliRenderer) *OptimizedBuffer {
+        return self.nextRenderBuffer;
+    }
+
+    pub fn getCurrentBuffer(self: *CliRenderer) *OptimizedBuffer {
+        return self.currentRenderBuffer;
+    }
+
+    fn prepareRenderFrame(self: *CliRenderer, force: bool) void {
+        const renderStartTime = std.time.microTimestamp();
+        var cellsUpdated: u32 = 0;
+
+        if (activeBuffer == .A) {
+            outputBufferLen = 0;
+        } else {
+            outputBufferBLen = 0;
+        }
+
+        var writer = OutputBufferWriter.writer();
+
+        writer.writeAll(ansi.ANSI.syncSet) catch {};
+        writer.writeAll(ansi.ANSI.hideCursor) catch {};
+
+        var currentFg: ?RGBA = null;
+        var currentBg: ?RGBA = null;
+        var currentAttributes: i32 = -1;
+        var currentLinkId: u32 = 0;
+        var utf8Buf: [4]u8 = undefined;
+
+        const colorEpsilon: f32 = COLOR_EPSILON_DEFAULT;
+        const hyperlinksEnabled = self.terminal.getCapabilities().hyperlinks;
+
+        for (0..self.height) |uy| {
+            const y = @as(u32, @intCast(uy));
+
+            var runStart: i64 = -1;
+            var runLength: u32 = 0;
+
+            for (0..self.width) |ux| {
+                const x = @as(u32, @intCast(ux));
+                const currentCell = self.currentRenderBuffer.get(x, y);
+                const nextCell = self.nextRenderBuffer.get(x, y);
+
+                if (currentCell == null or nextCell == null) continue;
+
+                if (!force) {
+                    const charEqual = currentCell.?.char == nextCell.?.char;
+                    const attrEqual = currentCell.?.attributes == nextCell.?.attributes;
+
+                    if (charEqual and attrEqual and
+                        buf.rgbaEqual(currentCell.?.fg, nextCell.?.fg, colorEpsilon) and
+                        buf.rgbaEqual(currentCell.?.bg, nextCell.?.bg, colorEpsilon))
+                    {
+                        if (runLength > 0) {
+                            writer.writeAll(ansi.ANSI.reset) catch {};
+                            runStart = -1;
+                            runLength = 0;
+                        }
+                        continue;
+                    }
+                }
+
+                const cell = nextCell.?;
+
+                const fgMatch = currentFg != null and buf.rgbaEqual(currentFg.?, cell.fg, colorEpsilon);
+                const bgMatch = currentBg != null and buf.rgbaEqual(currentBg.?, cell.bg, colorEpsilon);
+                const sameAttributes = fgMatch and bgMatch and @as(i32, @intCast(cell.attributes)) == currentAttributes;
+
+                const linkId = if (hyperlinksEnabled) ansi.TextAttributes.getLinkId(cell.attributes) else 0;
+
+                if (hyperlinksEnabled and linkId != currentLinkId) {
+                    if (currentLinkId != 0) {
+                        writer.writeAll("\x1b]8;;\x1b\\") catch {};
+                    }
+                    currentLinkId = linkId;
+                    if (currentLinkId != 0) {
+                        const lp = link.initGlobalLinkPool(self.allocator);
+                        if (lp.get(currentLinkId)) |url_bytes| {
+                            writer.print("\x1b]8;id={d};{s}\x1b\\", .{ currentLinkId, url_bytes }) catch {};
+                        } else |_| {
+                            // Link not found, treat as no link
+                            currentLinkId = 0;
+                        }
+                    }
+                }
+
+                if (!sameAttributes or runStart == -1) {
+                    if (runLength > 0) {
+                        writer.writeAll(ansi.ANSI.reset) catch {};
+                    }
+
+                    runStart = @intCast(x);
+                    runLength = 0;
+
+                    currentFg = cell.fg;
+                    currentBg = cell.bg;
+                    currentAttributes = @as(i32, @intCast(cell.attributes));
+
+                    ansi.ANSI.moveToOutput(writer, x + 1, y + 1 + self.renderOffset) catch {};
+
+                    const fgR = rgbaComponentToU8(cell.fg[0]);
+                    const fgG = rgbaComponentToU8(cell.fg[1]);
+                    const fgB = rgbaComponentToU8(cell.fg[2]);
+
+                    const bgR = rgbaComponentToU8(cell.bg[0]);
+                    const bgG = rgbaComponentToU8(cell.bg[1]);
+                    const bgB = rgbaComponentToU8(cell.bg[2]);
+                    const bgA = cell.bg[3];
+
+                    ansi.ANSI.fgColorOutput(writer, fgR, fgG, fgB) catch {};
+
+                    // If alpha is 0 (transparent), use terminal default background instead of black
+                    if (bgA < 0.001) {
+                        writer.writeAll("\x1b[49m") catch {};
+                    } else {
+                        ansi.ANSI.bgColorOutput(writer, bgR, bgG, bgB) catch {};
+                    }
+
+                    ansi.TextAttributes.applyAttributesOutputWriter(writer, cell.attributes) catch {};
+                }
+
+                // Handle grapheme characters
+                if (gp.isGraphemeChar(cell.char)) {
+                    const gid: u32 = gp.graphemeIdFromChar(cell.char);
+                    const bytes = self.pool.get(gid) catch |err| {
+                        self.performShutdownSequence();
+                        std.debug.panic("Fatal: no grapheme bytes in pool for gid {d}: {}", .{ gid, err });
+                    };
+                    if (bytes.len > 0) {
+                        const capabilities = self.terminal.getCapabilities();
+                        const graphemeWidth = gp.charRightExtent(cell.char) + 1;
+                        if (capabilities.explicit_width) {
+                            ansi.ANSI.explicitWidthOutput(writer, graphemeWidth, bytes) catch {};
+                        } else {
+                            writer.writeAll(bytes) catch {};
+                            if (capabilities.explicit_cursor_positioning) {
+                                const nextX = x + graphemeWidth;
+                                if (nextX < self.width) {
+                                    ansi.ANSI.moveToOutput(writer, nextX + 1, y + 1 + self.renderOffset) catch {};
+                                }
+                            }
+                        }
+                    }
+                } else if (gp.isContinuationChar(cell.char)) {
+                    // Intentionally do not write a space for continuation cells.
+                    // NOTE: disabled to fix 2-cell emoji rendering when the two
+                    // cells have distinct colors (space overwrite can break glyph output)
+
+                    // writer.writeByte(' ') catch {};
+                } else {
+                    const len = std.unicode.utf8Encode(@intCast(cell.char), &utf8Buf) catch 1;
+                    writer.writeAll(utf8Buf[0..len]) catch {};
+                }
+                runLength += 1;
+
+                // Sync this cell to the current buffer so the next frame's diff
+                // is correct. Use syncCell (set without span cleanup) because
+                // span cleanup would destroy continuation cells written by an
+                // earlier iteration of this same left-to-right pass (#723).
+                self.currentRenderBuffer.syncCell(x, y, nextCell.?);
+
+                cellsUpdated += 1;
+            }
+        }
+
+        if (hyperlinksEnabled and currentLinkId != 0) {
+            writer.writeAll("\x1b]8;;\x1b\\") catch {};
+        }
+
+        writer.writeAll(ansi.ANSI.reset) catch {};
+
+        const cursorPos = self.terminal.getCursorPosition();
+        const cursorStyle = self.terminal.getCursorStyle();
+        const cursorColor = self.terminal.getCursorColor();
+
+        if (cursorPos.visible) {
+            var cursorStyleCode: []const u8 = undefined;
+
+            switch (cursorStyle.style) {
+                .block => {
+                    cursorStyleCode = if (cursorStyle.blinking)
+                        ansi.ANSI.cursorBlockBlink
+                    else
+                        ansi.ANSI.cursorBlock;
+                },
+                .line => {
+                    cursorStyleCode = if (cursorStyle.blinking)
+                        ansi.ANSI.cursorLineBlink
+                    else
+                        ansi.ANSI.cursorLine;
+                },
+                .underline => {
+                    cursorStyleCode = if (cursorStyle.blinking)
+                        ansi.ANSI.cursorUnderlineBlink
+                    else
+                        ansi.ANSI.cursorUnderline;
+                },
+                .default => {
+                    cursorStyleCode = ansi.ANSI.defaultCursorStyle;
+                },
+            }
+
+            const cursorR = rgbaComponentToU8(cursorColor[0]);
+            const cursorG = rgbaComponentToU8(cursorColor[1]);
+            const cursorB = rgbaComponentToU8(cursorColor[2]);
+
+            const styleTag: u8 = @intFromEnum(cursorStyle.style);
+            const styleChanged = (self.lastCursorStyleTag == null or self.lastCursorStyleTag.? != styleTag) or
+                (self.lastCursorBlinking == null or self.lastCursorBlinking.? != cursorStyle.blinking);
+            const colorChanged = (self.lastCursorColorRGB == null or self.lastCursorColorRGB.?[0] != cursorR or self.lastCursorColorRGB.?[1] != cursorG or self.lastCursorColorRGB.?[2] != cursorB);
+
+            if (colorChanged) {
+                ansi.ANSI.cursorColorOutputWriter(writer, cursorR, cursorG, cursorB) catch {};
+                self.lastCursorColorRGB = .{ cursorR, cursorG, cursorB };
+            }
+            if (styleChanged) {
+                writer.writeAll(cursorStyleCode) catch {};
+                self.lastCursorStyleTag = styleTag;
+                self.lastCursorBlinking = cursorStyle.blinking;
+            }
+            ansi.ANSI.moveToOutput(writer, cursorPos.x, cursorPos.y + self.renderOffset) catch {};
+            writer.writeAll(ansi.ANSI.showCursor) catch {};
+        } else {
+            writer.writeAll(ansi.ANSI.hideCursor) catch {};
+            self.lastCursorStyleTag = null;
+            self.lastCursorBlinking = null;
+            self.lastCursorColorRGB = null;
+        }
+
+        const mousePointer = self.terminal.getMousePointer();
+        if (mousePointer != self.lastMousePointerStyle) {
+            ansi.ANSI.setMousePointerOutput(writer, mousePointer.toName()) catch {};
+            self.lastMousePointerStyle = mousePointer;
+        }
+
+        writer.writeAll(ansi.ANSI.syncReset) catch {};
+
+        const renderEndTime = std.time.microTimestamp();
+        const renderTime = @as(f64, @floatFromInt(renderEndTime - renderStartTime));
+
+        self.renderStats.cellsUpdated = cellsUpdated;
+        self.renderStats.renderTime = renderTime;
+
+        self.nextRenderBuffer.clear(.{ self.backgroundColor[0], self.backgroundColor[1], self.backgroundColor[2], self.backgroundColor[3] }, null) catch {};
+
+        // Compare hit grids before swap to detect changes. This allows TypeScript to
+        // know if hover state needs rechecking without manually tracking dirty state.
+        self.hitGridDirty = !std.mem.eql(u32, self.currentHitGrid, self.nextHitGrid);
+
+        // Swap hit grids: nextHitGrid (built this frame) becomes the active grid for
+        // hit testing. The old currentHitGrid becomes nextHitGrid and is cleared for
+        // the next frame.
+        const temp = self.currentHitGrid;
+        self.currentHitGrid = self.nextHitGrid;
+        self.nextHitGrid = temp;
+        @memset(self.nextHitGrid, 0);
+    }
+
+    pub fn setDebugOverlay(self: *CliRenderer, enabled: bool, corner: DebugOverlayCorner) void {
+        self.debugOverlay.enabled = enabled;
+        self.debugOverlay.corner = corner;
+    }
+
+    pub fn clearTerminal(self: *CliRenderer) void {
+        self.writeOut(ansi.ANSI.clearAndHome);
+    }
+
+    pub fn writeOut(self: *CliRenderer, data: []const u8) void {
+        if (data.len == 0) return;
+        if (self.testing) return;
+
+        if (self.useThread) {
+            self.renderMutex.lock();
+            while (self.renderInProgress) {
+                self.renderCondition.wait(&self.renderMutex);
+            }
+            self.renderMutex.unlock();
+        }
+
+        var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+        const w = &stdoutWriter.interface;
+        w.writeAll(data) catch {};
+        w.flush() catch {};
+    }
+
+    pub fn writeOutMultiple(self: *CliRenderer, data_slices: []const []const u8) void {
+        if (self.testing) return;
+
+        if (self.useThread) {
+            self.renderMutex.lock();
+            while (self.renderInProgress) {
+                self.renderCondition.wait(&self.renderMutex);
+            }
+            self.renderMutex.unlock();
+        }
+
+        var totalLen: usize = 0;
+        for (data_slices) |slice| {
+            totalLen += slice.len;
+        }
+
+        if (totalLen == 0) return;
+
+        var stdoutWriter = std.fs.File.stdout().writer(&self.stdoutBuffer);
+        const w = &stdoutWriter.interface;
+        for (data_slices) |slice| {
+            w.writeAll(slice) catch {};
+        }
+        w.flush() catch {};
+    }
+
+    /// Write a renderable's bounds to nextHitGrid for the upcoming frame.
+    ///
+    /// Called during render for each visible renderable. The rect is clipped to
+    /// the current hit scissor stack, so elements inside overflow:hidden parents
+    /// only register hits within the visible region. Later renderables overwrite
+    /// earlier ones. Z-order is determined by render order.
+    pub fn addToHitGrid(self: *CliRenderer, x: i32, y: i32, width: u32, height: u32, id: u32) void {
+        const clipped = self.clipRectToHitScissor(x, y, width, height) orelse return;
+        const startX = @max(0, clipped.x);
+        const startY = @max(0, clipped.y);
+        const endX = @min(
+            @as(i32, @intCast(self.hitGridWidth)),
+            clipped.x + @as(i32, @intCast(clipped.width)),
+        );
+        const endY = @min(
+            @as(i32, @intCast(self.hitGridHeight)),
+            clipped.y + @as(i32, @intCast(clipped.height)),
+        );
+
+        if (startX >= endX or startY >= endY) return;
+
+        const uStartX: u32 = @intCast(startX);
+        const uStartY: u32 = @intCast(startY);
+        const uEndX: u32 = @intCast(endX);
+        const uEndY: u32 = @intCast(endY);
+
+        for (uStartY..uEndY) |row| {
+            const rowStart = row * self.hitGridWidth;
+            const startIdx = rowStart + uStartX;
+            const endIdx = rowStart + uEndX;
+
+            @memset(self.nextHitGrid[startIdx..endIdx], id);
+        }
+    }
+
+    /// Clear currentHitGrid before an immediate rebuild.
+    ///
+    /// Used by syncHitGridIfNeeded in TypeScript when scroll/translate changes
+    /// require updating hit targets without waiting for the next render.
+    pub fn clearCurrentHitGrid(self: *CliRenderer) void {
+        @memset(self.currentHitGrid, 0);
+    }
+
+    /// Return whether the hit grid changed during the last render.
+    /// This is set by comparing the previous and current hit grids after render.
+    /// TypeScript can use this to decide if hover state needs rechecking.
+    pub fn getHitGridDirty(self: *CliRenderer) bool {
+        return self.hitGridDirty;
+    }
+
+    /// Return the renderable ID at screen position (x, y), or 0 if none.
+    pub fn checkHit(self: *CliRenderer, x: u32, y: u32) u32 {
+        if (x >= self.hitGridWidth or y >= self.hitGridHeight) {
+            return 0;
+        }
+
+        const index = y * self.hitGridWidth + x;
+        return self.currentHitGrid[index];
+    }
+
+    /// Return the current (topmost) hit scissor rect, or null if the stack is empty.
+    fn getCurrentHitScissorRect(self: *const CliRenderer) ?buf.ClipRect {
+        if (self.hitScissorStack.items.len == 0) return null;
+        return self.hitScissorStack.items[self.hitScissorStack.items.len - 1];
+    }
+
+    /// Intersect a rect with the current hit scissor. Returns null if fully clipped.
+    fn clipRectToHitScissor(self: *const CliRenderer, x: i32, y: i32, width: u32, height: u32) ?buf.ClipRect {
+        const scissor = self.getCurrentHitScissorRect() orelse return buf.ClipRect{
+            .x = x,
+            .y = y,
+            .width = width,
+            .height = height,
+        };
+
+        const rect_end_x = x + @as(i32, @intCast(width));
+        const rect_end_y = y + @as(i32, @intCast(height));
+        const scissor_end_x = scissor.x + @as(i32, @intCast(scissor.width));
+        const scissor_end_y = scissor.y + @as(i32, @intCast(scissor.height));
+
+        const intersect_x = @max(x, scissor.x);
+        const intersect_y = @max(y, scissor.y);
+        const intersect_end_x = @min(rect_end_x, scissor_end_x);
+        const intersect_end_y = @min(rect_end_y, scissor_end_y);
+
+        if (intersect_x >= intersect_end_x or intersect_y >= intersect_end_y) {
+            return null;
+        }
+
+        return buf.ClipRect{
+            .x = intersect_x,
+            .y = intersect_y,
+            .width = @intCast(intersect_end_x - intersect_x),
+            .height = @intCast(intersect_end_y - intersect_y),
+        };
+    }
+
+    /// Push a scissor rect for hit grid clipping.
+    ///
+    /// The rect is intersected with any existing scissor, so nested overflow:hidden
+    /// containers compound correctly. All coordinates are in screen space.
+    pub fn hitGridPushScissorRect(self: *CliRenderer, x: i32, y: i32, width: u32, height: u32) void {
+        var rect = buf.ClipRect{
+            .x = x,
+            .y = y,
+            .width = width,
+            .height = height,
+        };
+
+        if (self.getCurrentHitScissorRect() != null) {
+            const intersect = self.clipRectToHitScissor(rect.x, rect.y, rect.width, rect.height);
+            if (intersect) |clipped| {
+                rect = clipped;
+            } else {
+                rect = buf.ClipRect{ .x = 0, .y = 0, .width = 0, .height = 0 };
+            }
+        }
+
+        self.hitScissorStack.append(self.allocator, rect) catch |err| {
+            logger.warn("Failed to push hit-grid scissor rect: {}", .{err});
+        };
+    }
+
+    pub fn hitGridPopScissorRect(self: *CliRenderer) void {
+        if (self.hitScissorStack.items.len > 0) {
+            _ = self.hitScissorStack.pop();
+        }
+    }
+
+    /// Clear all hit grid scissors. Called at start of render to reset state.
+    pub fn hitGridClearScissorRects(self: *CliRenderer) void {
+        self.hitScissorStack.clearRetainingCapacity();
+    }
+
+    /// Write directly to currentHitGrid with scissor clipping.
+    ///
+    /// Used for immediate hit grid sync when scroll/translate changes. Unlike
+    /// addToHitGrid (which writes to nextHitGrid for the upcoming frame), this
+    /// updates the grid that checkHit reads right now. Lets hover states update
+    /// without waiting for the next render.
+    pub fn addToCurrentHitGridClipped(self: *CliRenderer, x: i32, y: i32, width: u32, height: u32, id: u32) void {
+        const clipped = self.clipRectToHitScissor(x, y, width, height) orelse return;
+
+        const startX = @max(0, clipped.x);
+        const startY = @max(0, clipped.y);
+        const endX = @min(@as(i32, @intCast(self.hitGridWidth)), clipped.x + @as(i32, @intCast(clipped.width)));
+        const endY = @min(@as(i32, @intCast(self.hitGridHeight)), clipped.y + @as(i32, @intCast(clipped.height)));
+
+        if (startX >= endX or startY >= endY) return;
+
+        const uStartX: u32 = @intCast(startX);
+        const uStartY: u32 = @intCast(startY);
+        const uEndX: u32 = @intCast(endX);
+        const uEndY: u32 = @intCast(endY);
+
+        for (uStartY..uEndY) |row| {
+            const rowStart = row * self.hitGridWidth;
+            const startIdx = rowStart + uStartX;
+            const endIdx = rowStart + uEndX;
+
+            @memset(self.currentHitGrid[startIdx..endIdx], id);
+        }
+    }
+
+    pub fn dumpHitGrid(self: *CliRenderer) void {
+        const timestamp = std.time.timestamp();
+        var filename_buf: [64]u8 = undefined;
+        const filename = std.fmt.bufPrint(&filename_buf, "hitgrid_{d}.txt", .{timestamp}) catch return;
+
+        const file = std.fs.cwd().createFile(filename, .{}) catch return;
+        defer file.close();
+
+        var fileBuffer: [4096]u8 = undefined;
+        var fileWriter = file.writer(&fileBuffer);
+        const writer = &fileWriter.interface;
+
+        for (0..self.hitGridHeight) |y| {
+            for (0..self.hitGridWidth) |x| {
+                const index = y * self.hitGridWidth + x;
+                const id = self.currentHitGrid[index];
+
+                const char = if (id == 0) '.' else ('0' + @as(u8, @intCast(id % 10)));
+                writer.writeByte(char) catch return;
+            }
+            writer.writeByte('\n') catch return;
+        }
+        writer.flush() catch {};
+    }
+
+    fn dumpSingleBuffer(self: *CliRenderer, buffer: *OptimizedBuffer, buffer_name: []const u8, timestamp: i64) void {
+        std.fs.cwd().makeDir("buffer_dump") catch |err| switch (err) {
+            error.PathAlreadyExists => {},
+            else => return,
+        };
+
+        var filename_buf: [128]u8 = undefined;
+        const filename = std.fmt.bufPrint(&filename_buf, "buffer_dump/{s}_buffer_{d}.txt", .{ buffer_name, timestamp }) catch return;
+
+        const file = std.fs.cwd().createFile(filename, .{}) catch return;
+        defer file.close();
+
+        var fileBuffer: [4096]u8 = undefined;
+        var fileWriter = file.writer(&fileBuffer);
+        const writer = &fileWriter.interface;
+
+        writer.print("{s} Buffer ({d}x{d}):\n", .{ buffer_name, self.width, self.height }) catch return;
+        writer.writeAll("Characters:\n") catch return;
+
+        for (0..self.height) |y| {
+            for (0..self.width) |x| {
+                const cell = buffer.get(@intCast(x), @intCast(y));
+                if (cell) |c| {
+                    if (gp.isContinuationChar(c.char)) {
+                        // skip
+                    } else if (gp.isGraphemeChar(c.char)) {
+                        const gid: u32 = gp.graphemeIdFromChar(c.char);
+                        const bytes = self.pool.get(gid) catch &[_]u8{};
+                        if (bytes.len > 0) writer.writeAll(bytes) catch return;
+                    } else {
+                        var utf8Buf: [4]u8 = undefined;
+                        const len = std.unicode.utf8Encode(@intCast(c.char), &utf8Buf) catch 1;
+                        writer.writeAll(utf8Buf[0..len]) catch return;
+                    }
+                } else {
+                    writer.writeByte(' ') catch return;
+                }
+            }
+            writer.writeByte('\n') catch return;
+        }
+        writer.flush() catch {};
+    }
+
+    pub fn getLastOutputForTest(_: *CliRenderer) []const u8 {
+        // In non-threaded mode, we want the current active buffer
+        // In threaded mode, we want the previously rendered buffer
+        const currentBuffer = if (activeBuffer == .A) &outputBuffer else &outputBufferB;
+        const currentLen = if (activeBuffer == .A) outputBufferLen else outputBufferBLen;
+        return currentBuffer.*[0..currentLen];
+    }
+
+    pub fn dumpStdoutBuffer(self: *CliRenderer, timestamp: i64) void {
+        _ = self;
+        std.fs.cwd().makeDir("buffer_dump") catch |err| switch (err) {
+            error.PathAlreadyExists => {},
+            else => return,
+        };
+
+        var filename_buf: [128]u8 = undefined;
+        const filename = std.fmt.bufPrint(&filename_buf, "buffer_dump/stdout_buffer_{d}.txt", .{timestamp}) catch return;
+
+        const file = std.fs.cwd().createFile(filename, .{}) catch return;
+        defer file.close();
+
+        var fileBuffer: [4096]u8 = undefined;
+        var fileWriter = file.writer(&fileBuffer);
+        const writer = &fileWriter.interface;
+
+        writer.print("Stdout Buffer Output (timestamp: {d}):\n", .{timestamp}) catch return;
+        writer.writeAll("Last Rendered ANSI Output:\n") catch return;
+        writer.writeAll("================\n") catch return;
+
+        const lastBuffer = if (activeBuffer == .A) &outputBufferB else &outputBuffer;
+        const lastLen = if (activeBuffer == .A) outputBufferBLen else outputBufferLen;
+
+        if (lastLen > 0) {
+            writer.writeAll(lastBuffer.*[0..lastLen]) catch return;
+        } else {
+            writer.writeAll("(no output rendered yet)\n") catch return;
+        }
+
+        writer.writeAll("\n================\n") catch return;
+        writer.print("Buffer size: {d} bytes\n", .{lastLen}) catch return;
+        writer.print("Active buffer: {s}\n", .{if (activeBuffer == .A) "A" else "B"}) catch return;
+        writer.flush() catch {};
+    }
+
+    pub fn dumpBuffers(self: *CliRenderer, timestamp: i64) void {
+        self.dumpSingleBuffer(self.currentRenderBuffer, "current", timestamp);
+        self.dumpSingleBuffer(self.nextRenderBuffer, "next", timestamp);
+        self.dumpStdoutBuffer(timestamp);
+    }
+
+    pub fn restoreTerminalModes(self: *CliRenderer) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.restoreTerminalModes(stream.writer()) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn enableMouse(self: *CliRenderer, enableMovement: bool) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.setMouseMode(stream.writer(), true, enableMovement) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn queryPixelResolution(self: *CliRenderer) void {
+        self.writeOut(ansi.ANSI.queryPixelSize);
+    }
+
+    pub fn disableMouse(self: *CliRenderer) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.setMouseMode(stream.writer(), false, self.terminal.state.mouse_movement) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn enableKittyKeyboard(self: *CliRenderer, flags: u8) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.setKittyKeyboard(stream.writer(), true, flags) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn disableKittyKeyboard(self: *CliRenderer) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.setKittyKeyboard(stream.writer(), false, 0) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn getTerminalCapabilities(self: *CliRenderer) Terminal.Capabilities {
+        return self.terminal.getCapabilities();
+    }
+
+    pub fn setTerminalEnvVar(self: *CliRenderer, key: []const u8, value: []const u8) bool {
+        self.terminal.setHostEnvVar(self.allocator, key, value) catch return false;
+        return true;
+    }
+
+    pub fn processCapabilityResponse(self: *CliRenderer, response: []const u8) void {
+        self.terminal.processCapabilityResponse(response);
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        _ = self.terminal.sendPendingQueries(stream.writer()) catch |err| blk: {
+            logger.warn("Failed to send pending queries: {}", .{err});
+            break :blk false;
+        };
+        const useKitty = self.terminal.opts.kitty_keyboard_flags > 0;
+        self.terminal.enableDetectedFeatures(stream.writer(), useKitty) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn setKittyKeyboardFlags(self: *CliRenderer, flags: u8) void {
+        self.terminal.setKittyKeyboardFlags(flags);
+    }
+
+    pub fn getKittyKeyboardFlags(self: *CliRenderer) u8 {
+        return self.terminal.opts.kitty_keyboard_flags;
+    }
+
+    pub fn setTerminalTitle(self: *CliRenderer, title: []const u8) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.setTerminalTitle(stream.writer(), title);
+        self.writeOut(stream.getWritten());
+    }
+
+    pub fn copyToClipboardOSC52(self: *CliRenderer, target: Terminal.ClipboardTarget, payload: []const u8) bool {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.writeClipboard(stream.writer(), target, payload) catch return false;
+        self.writeOut(stream.getWritten());
+        return true;
+    }
+
+    pub fn clearClipboardOSC52(self: *CliRenderer, target: Terminal.ClipboardTarget) bool {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.writeClipboard(stream.writer(), target, "") catch return false;
+        self.writeOut(stream.getWritten());
+        return true;
+    }
+
+    fn renderDebugOverlay(self: *CliRenderer) void {
+        if (!self.debugOverlay.enabled) return;
+
+        const width: u32 = 40;
+        const height: u32 = 11;
+        var x: u32 = 0;
+        var y: u32 = 0;
+
+        if (self.width < width + 2 or self.height < height + 2) return;
+
+        switch (self.debugOverlay.corner) {
+            .topLeft => {
+                x = 1;
+                y = 1;
+            },
+            .topRight => {
+                x = self.width - width - 1;
+                y = 1;
+            },
+            .bottomLeft => {
+                x = 1;
+                y = self.height - height - 1;
+            },
+            .bottomRight => {
+                x = self.width - width - 1;
+                y = self.height - height - 1;
+            },
+        }
+
+        self.nextRenderBuffer.fillRect(x, y, width, height, .{ 20.0 / 255.0, 20.0 / 255.0, 40.0 / 255.0, 1.0 }) catch {};
+        self.nextRenderBuffer.drawText("Debug Information", x + 1, y + 1, .{ 1.0, 1.0, 100.0 / 255.0, 1.0 }, .{ 0.0, 0.0, 0.0, 0.0 }, ansi.TextAttributes.BOLD) catch {};
+
+        var row: u32 = 2;
+        const bg: RGBA = .{ 0.0, 0.0, 0.0, 0.0 };
+        const fg: RGBA = .{ 200.0 / 255.0, 200.0 / 255.0, 200.0 / 255.0, 1.0 };
+
+        // Calculate averages
+        const lastFrameTimeAvg = getStatAverage(f64, &self.statSamples.lastFrameTime);
+        const renderTimeAvg = getStatAverage(f64, &self.statSamples.renderTime);
+        const overallFrameTimeAvg = getStatAverage(f64, &self.statSamples.overallFrameTime);
+        const bufferResetTimeAvg = getStatAverage(f64, &self.statSamples.bufferResetTime);
+        const stdoutWriteTimeAvg = getStatAverage(f64, &self.statSamples.stdoutWriteTime);
+        const cellsUpdatedAvg = getStatAverage(u32, &self.statSamples.cellsUpdated);
+        const frameCallbackTimeAvg = getStatAverage(f64, &self.statSamples.frameCallbackTime);
+
+        // FPS
+        var fpsText: [32]u8 = undefined;
+        const fpsLen = std.fmt.bufPrint(&fpsText, "FPS: {d}", .{self.renderStats.fps}) catch return;
+        self.nextRenderBuffer.drawText(fpsLen, x + 1, y + row, fg, bg, 0) catch {};
+        row += 1;
+
+        // Frame Time
+        var frameTimeText: [64]u8 = undefined;
+        const frameTimeLen = std.fmt.bufPrint(&frameTimeText, "Frame: {d:.3}ms (avg: {d:.3}ms)", .{ self.renderStats.lastFrameTime / 1000.0, lastFrameTimeAvg / 1000.0 }) catch return;
+        self.nextRenderBuffer.drawText(frameTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+        row += 1;
+
+        // Frame Callback Time
+        if (self.renderStats.frameCallbackTime) |frameCallbackTime| {
+            var frameCallbackTimeText: [64]u8 = undefined;
+            const frameCallbackTimeLen = std.fmt.bufPrint(&frameCallbackTimeText, "Frame Callback: {d:.3}ms (avg: {d:.3}ms)", .{ frameCallbackTime, frameCallbackTimeAvg }) catch return;
+            self.nextRenderBuffer.drawText(frameCallbackTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Overall Time
+        if (self.renderStats.overallFrameTime) |overallTime| {
+            var overallTimeText: [64]u8 = undefined;
+            const overallTimeLen = std.fmt.bufPrint(&overallTimeText, "Overall: {d:.3}ms (avg: {d:.3}ms)", .{ overallTime, overallFrameTimeAvg }) catch return;
+            self.nextRenderBuffer.drawText(overallTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Render Time
+        if (self.renderStats.renderTime) |renderTime| {
+            var renderTimeText: [64]u8 = undefined;
+            const renderTimeLen = std.fmt.bufPrint(&renderTimeText, "Render: {d:.3}ms (avg: {d:.3}ms)", .{ renderTime / 1000.0, renderTimeAvg / 1000.0 }) catch return;
+            self.nextRenderBuffer.drawText(renderTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Buffer Reset Time
+        if (self.renderStats.bufferResetTime) |resetTime| {
+            var resetTimeText: [64]u8 = undefined;
+            const resetTimeLen = std.fmt.bufPrint(&resetTimeText, "Reset: {d:.3}ms (avg: {d:.3}ms)", .{ resetTime / 1000.0, bufferResetTimeAvg / 1000.0 }) catch return;
+            self.nextRenderBuffer.drawText(resetTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Stdout Write Time
+        if (self.renderStats.stdoutWriteTime) |writeTime| {
+            var writeTimeText: [64]u8 = undefined;
+            const writeTimeLen = std.fmt.bufPrint(&writeTimeText, "Stdout: {d:.3}ms (avg: {d:.3}ms)", .{ writeTime / 1000.0, stdoutWriteTimeAvg / 1000.0 }) catch return;
+            self.nextRenderBuffer.drawText(writeTimeLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Cells Updated
+        var cellsText: [64]u8 = undefined;
+        const cellsLen = std.fmt.bufPrint(&cellsText, "Cells: {d} (avg: {d})", .{ self.renderStats.cellsUpdated, cellsUpdatedAvg }) catch return;
+        self.nextRenderBuffer.drawText(cellsLen, x + 1, y + row, fg, bg, 0) catch {};
+        row += 1;
+
+        if (self.renderStats.heapUsed > 0 or self.renderStats.heapTotal > 0) {
+            var memoryText: [64]u8 = undefined;
+            const memoryLen = std.fmt.bufPrint(&memoryText, "Memory: {d:.2}MB / {d:.2}MB / {d:.2}MB", .{ @as(f64, @floatFromInt(self.renderStats.heapUsed)) / 1024.0 / 1024.0, @as(f64, @floatFromInt(self.renderStats.heapTotal)) / 1024.0 / 1024.0, @as(f64, @floatFromInt(self.renderStats.arrayBuffers)) / 1024.0 / 1024.0 }) catch return;
+            self.nextRenderBuffer.drawText(memoryLen, x + 1, y + row, fg, bg, 0) catch {};
+            row += 1;
+        }
+
+        // Is threaded?
+        var isThreadedText: [64]u8 = undefined;
+        const isThreadedLen = std.fmt.bufPrint(&isThreadedText, "Threaded: {s}", .{if (self.useThread) "Yes" else "No"}) catch return;
+        self.nextRenderBuffer.drawText(isThreadedLen, x + 1, y + row, fg, bg, 0) catch {};
+        row += 1;
+    }
+};