@xincli/opentui-core 0.4.6

package/src/zig/renderer.zig

@@ -0,0 +1,2106 @@
+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 split_scrollback = @import("split-scrollback.zig");
+const Terminal = @import("terminal.zig");
+const logger = @import("logger.zig");
+const NativeSpanFeed = @import("native-span-feed.zig");
+const output = @import("renderer-output.zig");
+
+pub const RGBA = ansi.RGBA;
+pub const OptimizedBuffer = buf.OptimizedBuffer;
+pub const TextAttributes = ansi.TextAttributes;
+pub const CursorStyle = Terminal.CursorStyle;
+pub const OutputBackend = output.OutputBackend;
+pub const BufferedBackend = output.BufferedBackend;
+pub const BufferedOutput = output.BufferedOutput;
+pub const StdoutOutput = output.StdoutOutput;
+pub const FeedBackend = output.FeedBackend;
+pub const OUTPUT_BUFFER_SIZE = output.OUTPUT_BUFFER_SIZE;
+
+pub const RenderStatus = enum(u8) {
+    rendered = 0,
+    skipped = 1,
+    failed = 2,
+};
+
+pub const RenderResult = struct {
+    renderOffset: u32,
+    status: RenderStatus,
+};
+
+const CLEAR_CHAR = '\u{0a00}';
+const MAX_STAT_SAMPLES = 30;
+const STAT_SAMPLE_CAPACITY = 30;
+
+pub const RendererError = error{
+    OutOfMemory,
+    InvalidDimensions,
+    ThreadingFailed,
+    WriteFailed,
+};
+
+pub const DebugOverlayCorner = enum {
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+};
+
+fn moveToSplitOutputCursor(writer: anytype, render_offset: u32, output_column: u32, width: u32) void {
+    const safe_width = @max(width, @as(u32, 1));
+    const row: u32 = if (render_offset > 0) render_offset else 1;
+    const column: u32 = if (render_offset == 0 or output_column == 0)
+        1
+    else
+        @min(output_column + 1, safe_width);
+
+    ansi.ANSI.moveToOutput(writer, column, row) catch {};
+}
+
+fn snapshotRowEnd(snapshot: *const OptimizedBuffer, row: u32, limit: u32) u32 {
+    var x = limit;
+    while (x > 0) {
+        const cell = snapshot.get(x - 1, row) orelse {
+            x -= 1;
+            continue;
+        };
+
+        if (cell.char == 0 or gp.isContinuationChar(cell.char)) {
+            x -= 1;
+            continue;
+        }
+
+        return x;
+    }
+
+    return 0;
+}
+
+pub const SplitFooterTransitionMode = enum(u8) {
+    none = 0,
+    viewport_scroll = 1,
+    clear_stale_rows = 2,
+};
+
+pub const RenderStatsSnapshot = struct {
+    lastFrameTime: f64,
+    averageFrameTime: f64,
+    frameCount: u64,
+    cellsUpdated: u32,
+    averageCellsUpdated: u32,
+    renderTime: ?f64,
+    outputWriteTime: ?f64,
+};
+
+const SplitFooterTransition = struct {
+    mode: SplitFooterTransitionMode = .none,
+    source_top_line: u32 = 0,
+    source_height: u32 = 0,
+    target_top_line: u32 = 0,
+    target_height: u32 = 0,
+    scroll_lines: u32 = 0,
+
+    fn clear(self: *SplitFooterTransition) void {
+        self.* = .{};
+    }
+};
+
+pub const CliRenderer = struct {
+    width: u32,
+    height: u32,
+    currentRenderBuffer: *OptimizedBuffer,
+    nextRenderBuffer: *OptimizedBuffer,
+    pool: *gp.GraphemePool,
+    backgroundColor: RGBA,
+    renderOffset: u32,
+    terminal: Terminal,
+    useAlternateScreen: bool = true,
+    terminalSetup: bool = false,
+    clearOnShutdown: bool = true,
+
+    splitScrollback: split_scrollback.SplitScrollback = .{},
+    // Batch state for split-footer commit flushing. A single JS render tick can
+    // enqueue multiple stdout snapshots; batching keeps all of them inside one
+    // sync frame so terminals do not repeatedly enter/exit synchronized update.
+    splitBatchActive: bool = false,
+    splitBatchRedrawFooter: bool = false,
+    splitBatchDeltaTime: f64 = 0,
+    pendingSplitFooterTransition: SplitFooterTransition = .{},
+
+    /// Output transport. Owned by the renderer; destroyed in `destroy()`.
+    backend: OutputBackend,
+
+    renderStats: struct {
+        lastFrameTime: f64,
+        averageFrameTime: f64,
+        frameCount: u64,
+        fps: u32,
+        cellsUpdated: u32,
+        renderTime: ?f64,
+        overallFrameTime: ?f64,
+        bufferResetTime: ?f64,
+        outputWriteTime: ?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),
+        outputWriteTime: std.ArrayListUnmanaged(f64),
+        cellsUpdated: std.ArrayListUnmanaged(u32),
+        frameCallbackTime: std.ArrayListUnmanaged(f64),
+    },
+    lastRenderTime: i64,
+    allocator: Allocator,
+    writeOutBuf: [1024]u8 = undefined,
+    debugOverlay: struct {
+        enabled: bool,
+        corner: DebugOverlayCorner,
+    } = .{
+        .enabled = false,
+        .corner = .bottomRight,
+    },
+
+    // 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,
+    hitGridResizeInvalidated: bool = false,
+
+    lastCursorStyleTag: ?u8 = null,
+    lastCursorBlinking: ?bool = null,
+    lastCursorColorRGB: ?[3]u8 = null,
+    // Cursor diff cache. If nothing changed we avoid emitting cursor restore/show
+    // sequences for no-op frames, which removes a major source of visible flicker.
+    lastCursorX: ?u32 = null,
+    lastCursorY: ?u32 = null,
+    lastCursorVisible: ?bool = null,
+    lastMousePointerStyle: Terminal.MousePointerStyle = .default,
+    palette_rgba: [256]RGBA,
+    default_fg_rgba: RGBA,
+    default_bg_rgba: RGBA,
+    palette_epoch: u32,
+    last_rendered_palette_epoch: ?u32 = null,
+    force_full_repaint: bool = false,
+    palette_index_cache: std.AutoHashMapUnmanaged(u64, u8) = .{},
+
+    pub const OutputTarget = union(enum) {
+        stdout,
+        memory,
+        buffered: BufferedOutput,
+        feed: *NativeSpanFeed.Stream,
+    };
+
+    /// Full set of options for `createWithOptions`. `output` determines the
+    /// backend variant: buffered stdout, injected buffered output, or feed.
+    pub const CreateOptions = struct {
+        remote_mode: Terminal.RemoteMode = .local,
+        output: OutputTarget = .stdout,
+        clearOnShutdown: bool = true,
+        // Optional override for terminal environment lookups. Borrowed: the
+        // caller owns the map and must keep it alive for the renderer's lifetime.
+        env_map: ?*const std.process.EnvMap = null,
+    };
+
+    pub fn create(allocator: Allocator, width: u32, height: u32, pool: *gp.GraphemePool) !*CliRenderer {
+        return createWithOptions(allocator, width, height, pool, .{});
+    }
+
+    pub fn createWithOptions(
+        allocator: Allocator,
+        width: u32,
+        height: u32,
+        pool: *gp.GraphemePool,
+        opts: CreateOptions,
+    ) !*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 outputWriteTime: std.ArrayListUnmanaged(f64) = .{};
+        errdefer outputWriteTime.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 outputWriteTime.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) = .{};
+
+        // Backend variant selected once by opts.output.
+        var backend: OutputBackend = switch (opts.output) {
+            .stdout => .{ .buffered = try BufferedBackend.createStdout(allocator) },
+            .memory => .{ .buffered = try BufferedBackend.createMemory(allocator) },
+            .buffered => |buffered_output| .{ .buffered = try BufferedBackend.create(allocator, buffered_output) },
+            .feed => |feed_ptr| .{ .feed = FeedBackend.create(feed_ptr) },
+        };
+        errdefer backend.deinit();
+
+        self.* = .{
+            .width = width,
+            .height = height,
+            .currentRenderBuffer = currentBuffer,
+            .nextRenderBuffer = nextBuffer,
+            .pool = pool,
+            .backgroundColor = ansi.rgbColor(0, 0, 0, 0),
+            .renderOffset = 0,
+            .terminal = Terminal.init(.{ .remote_mode = opts.remote_mode, .env_map = opts.env_map }),
+            .clearOnShutdown = opts.clearOnShutdown,
+            .backend = backend,
+            .lastCursorStyleTag = null,
+            .lastCursorBlinking = null,
+            .lastCursorColorRGB = null,
+
+            .renderStats = .{
+                .lastFrameTime = 0,
+                .averageFrameTime = 0,
+                .frameCount = 0,
+                .fps = 0,
+                .cellsUpdated = 0,
+                .renderTime = null,
+                .overallFrameTime = null,
+                .bufferResetTime = null,
+                .outputWriteTime = null,
+                .heapUsed = 0,
+                .heapTotal = 0,
+                .arrayBuffers = 0,
+                .frameCallbackTime = null,
+            },
+            .statSamples = .{
+                .lastFrameTime = lastFrameTime,
+                .renderTime = renderTime,
+                .overallFrameTime = overallFrameTime,
+                .bufferResetTime = bufferResetTime,
+                .outputWriteTime = outputWriteTime,
+                .cellsUpdated = cellsUpdated,
+                .frameCallbackTime = frameCallbackTimes,
+            },
+            .lastRenderTime = std.time.microTimestamp(),
+            .allocator = allocator,
+            .currentHitGrid = currentHitGrid,
+            .nextHitGrid = nextHitGrid,
+            .hitGridWidth = width,
+            .hitGridHeight = height,
+            .hitScissorStack = hitScissorStack,
+            .palette_rgba = undefined,
+            .default_fg_rgba = ansi.defaultColor(255, 255, 255, 255),
+            .default_bg_rgba = ansi.defaultColor(0, 0, 0, 255),
+            .palette_epoch = 0,
+        };
+
+        self.resetFallbackPaletteState();
+        nextBuffer.setBlendBackdropColor(ansi.rgbColor(ansi.red(self.backgroundColor), ansi.green(self.backgroundColor), ansi.blue(self.backgroundColor), 255));
+
+        currentBuffer.clear(self.backgroundColor, CLEAR_CHAR);
+        nextBuffer.clear(self.backgroundColor, null);
+
+        return self;
+    }
+
+    pub fn destroy(self: *CliRenderer) void {
+        // Order matters: performShutdownSequence writes cleanup ANSI through
+        // the backend. backend.deinit then joins the render thread using a
+        // terminate-only signal (no renderRequested) so the thread exits
+        // without replaying the stale last-frame buffer on top of the
+        // freshly-restored terminal.
+        self.performShutdownSequence();
+        self.backend.deinit();
+        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.outputWriteTime.deinit(self.allocator);
+        self.statSamples.cellsUpdated.deinit(self.allocator);
+        self.statSamples.frameCallbackTime.deinit(self.allocator);
+        self.palette_index_cache.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;
+
+        // Build capability query into a stack buffer, then emit via backend.
+        // Buffer sized to accommodate all capability-query sequences with margin.
+        var queryBuf: [4096]u8 = undefined;
+        var stream = std.io.fixedBufferStream(&queryBuf);
+        self.terminal.queryTerminalSend(stream.writer()) catch {
+            logger.warn("Failed to query terminal capabilities", .{});
+        };
+        self.backend.writeOut(stream.getWritten());
+
+        self.setupTerminalWithoutDetection(useAlternateScreen, true);
+    }
+
+    fn setupTerminalWithoutDetection(self: *CliRenderer, useAlternateScreen: bool, reserve_non_alt_surface: bool) void {
+        var setupBuf: [4096]u8 = undefined;
+        var stream = std.io.fixedBufferStream(&setupBuf);
+        const writer = stream.writer();
+
+        writer.writeAll(ansi.ANSI.saveCursorState) catch {};
+
+        if (useAlternateScreen) {
+            self.terminal.enterAltScreen(writer) catch {};
+        } else if (reserve_non_alt_surface) {
+            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 {};
+
+        self.backend.writeOut(stream.getWritten());
+    }
+
+    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, self.renderOffset == 0);
+    }
+
+    fn clearSplitFooterSurface(self: *CliRenderer, writer: anytype) void {
+        if (self.renderOffset == 0) return;
+
+        const footer_top_line = @max(self.renderOffset + 1, @as(u32, 1));
+        writer.writeAll("\x1b[r") catch {};
+        ansi.ANSI.moveToOutput(writer, 1, footer_top_line) catch {};
+        writer.writeAll(ansi.ANSI.eraseBelowCursor) catch {};
+        ansi.ANSI.moveToOutput(writer, 1, footer_top_line) catch {};
+    }
+
+    pub fn performShutdownSequence(self: *CliRenderer) void {
+        if (!self.terminalSetup) return;
+
+        // Build the shutdown ANSI sequence into a stack buffer, then emit.
+        var shutdownBuf: [4096]u8 = undefined;
+        var stream = std.io.fixedBufferStream(&shutdownBuf);
+        const writer = stream.writer();
+
+        self.terminal.resetState(writer) catch {
+            logger.warn("Failed to reset terminal state", .{});
+        };
+
+        if (self.useAlternateScreen) {
+            // Alt screen: resetState already exited alt screen; just flush.
+        } else if (self.clearOnShutdown and self.renderOffset == 0) {
+            writer.writeAll("\x1b[H\x1b[J") catch {};
+        } else if (self.clearOnShutdown and self.renderOffset > 0) {
+            self.clearSplitFooterSurface(writer);
+        }
+
+        // NOTE: This messes up state after shutdown, but might be necessary for windows?
+        // writer.writeAll(ansi.ANSI.restoreCursorState) catch {};
+
+        writer.writeAll(ansi.ANSI.resetCursorColorFallback) catch {};
+        writer.writeAll(ansi.ANSI.resetCursorColor) catch {};
+        writer.writeAll(ansi.ANSI.defaultCursorStyle) catch {};
+        writer.writeAll(ansi.ANSI.showCursor) catch {};
+
+        self.backend.writeOut(stream.getWritten());
+
+        // Workaround for Ghostty not showing the cursor after shutdown for some reason.
+        // Keep this backend-agnostic: the active output transport owns delivery.
+        std.Thread.sleep(10 * std.time.ns_per_ms);
+        self.backend.writeOut(ansi.ANSI.showCursor);
+        std.Thread.sleep(10 * std.time.ns_per_ms);
+    }
+
+    pub fn setClearOnShutdown(self: *CliRenderer, clear: bool) void {
+        self.clearOnShutdown = clear;
+    }
+
+    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));
+        }
+    }
+
+    fn collectFrameStats(self: *CliRenderer, deltaTime: f64) void {
+        if (self.backend.getLastWriteTimeUs()) |wt| {
+            self.renderStats.outputWriteTime = wt;
+        }
+
+        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.outputWriteTime) |swt| {
+            self.addStatSample(f64, &self.statSamples.outputWriteTime, swt);
+        }
+        self.addStatSample(u32, &self.statSamples.cellsUpdated, self.renderStats.cellsUpdated);
+    }
+
+    pub fn setUseThread(self: *CliRenderer, useThread: bool) void {
+        if (!self.backend.supportsThreading() and useThread) return;
+        self.backend.setUseThread(useThread);
+    }
+
+    /// Whether the backend is currently running a write thread (for debug overlay).
+    pub fn isUseThread(self: *CliRenderer) bool {
+        return self.backend.isUseThread();
+    }
+
+    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 getRenderStats(self: *const CliRenderer) RenderStatsSnapshot {
+        return .{
+            .lastFrameTime = self.renderStats.lastFrameTime,
+            .averageFrameTime = getStatAverage(f64, &self.statSamples.lastFrameTime),
+            .frameCount = self.renderStats.frameCount,
+            .cellsUpdated = self.renderStats.cellsUpdated,
+            .averageCellsUpdated = getStatAverage(u32, &self.statSamples.cellsUpdated),
+            .renderTime = self.renderStats.renderTime,
+            .outputWriteTime = self.renderStats.outputWriteTime,
+        };
+    }
+
+    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(ansi.rgbColor(ansi.red(self.backgroundColor), ansi.green(self.backgroundColor), ansi.blue(self.backgroundColor), 255));
+
+        self.currentRenderBuffer.clear(ansi.rgbColor(0, 0, 0, 255), CLEAR_CHAR);
+        self.nextRenderBuffer.clear(self.backgroundColor, 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);
+
+            self.allocator.free(self.currentHitGrid);
+            self.allocator.free(self.nextHitGrid);
+            self.currentHitGrid = newCurrentHitGrid;
+            self.nextHitGrid = newNextHitGrid;
+        }
+
+        @memset(self.currentHitGrid, 0);
+        @memset(self.nextHitGrid, 0);
+        self.hitGridResizeInvalidated = true;
+
+        // 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(ansi.rgbColor(ansi.red(rgba), ansi.green(rgba), ansi.blue(rgba), 255));
+
+        // Do not mirror renderer background to terminal default background via
+        // OSC 11 for now. In Ghostty, once OSC 11 has been used, later system
+        // light/dark theme changes can leave OSC 11 queries stuck on stale bg
+        // values even after OSC 111 resets. Theme detection relies on fresh
+        // OSC 10/11 replies, so mutating terminal default bg here breaks that.
+    }
+
+    fn resetFallbackPaletteState(self: *CliRenderer) void {
+        for (0..self.palette_rgba.len) |index| {
+            self.palette_rgba[index] = ansi.fallbackAnsi256Color(index);
+        }
+        self.default_fg_rgba = ansi.defaultColor(255, 255, 255, 255);
+        self.default_bg_rgba = ansi.defaultColor(0, 0, 0, 255);
+    }
+
+    pub fn setPaletteState(self: *CliRenderer, palette: []const RGBA, default_fg: RGBA, default_bg: RGBA, palette_epoch: u32) void {
+        self.resetFallbackPaletteState();
+
+        const copy_len = @min(palette.len, self.palette_rgba.len);
+        for (palette[0..copy_len], 0..) |color, index| {
+            self.palette_rgba[index] = color;
+        }
+
+        self.default_fg_rgba = default_fg;
+        self.default_bg_rgba = default_bg;
+
+        if (self.palette_epoch != palette_epoch) {
+            self.palette_epoch = palette_epoch;
+            self.force_full_repaint = true;
+            self.palette_index_cache.clearRetainingCapacity();
+        }
+    }
+
+    fn cachedNearestPaletteIndex(self: *CliRenderer, rgba: RGBA) u8 {
+        const rgb24 = ansi.rgbaToRgb24(rgba);
+        const key = (@as(u64, self.palette_epoch) << 24) | @as(u64, rgb24);
+
+        if (self.palette_index_cache.get(key)) |cached| {
+            return cached;
+        }
+
+        var best_index: u8 = 0;
+        var best_distance = std.math.inf(f32);
+
+        for (self.palette_rgba, 0..) |candidate, index| {
+            const distance = ansi.colorDistanceSquared(rgba, candidate);
+            if (distance < best_distance) {
+                best_distance = distance;
+                best_index = @intCast(index);
+            }
+        }
+
+        self.palette_index_cache.put(self.allocator, key, best_index) catch {};
+        return best_index;
+    }
+
+    fn emitColor(self: *CliRenderer, writer: anytype, rgba: RGBA, is_background: bool) void {
+        const caps = self.terminal.getCapabilities();
+
+        if (ansi.intent(rgba) == .default) {
+            if (is_background) {
+                ansi.ANSI.bgDefaultOutput(writer) catch {};
+            } else {
+                ansi.ANSI.fgDefaultOutput(writer) catch {};
+            }
+            return;
+        }
+
+        if (is_background and ansi.alpha(rgba) == 0) {
+            ansi.ANSI.bgDefaultOutput(writer) catch {};
+            return;
+        }
+
+        if (ansi.intent(rgba) == .indexed and caps.ansi256) {
+            const index = ansi.slot(rgba);
+            if (is_background) {
+                ansi.ANSI.bgIndexedColorOutput(writer, index) catch {};
+            } else {
+                ansi.ANSI.fgIndexedColorOutput(writer, index) catch {};
+            }
+            return;
+        }
+
+        if (!caps.rgb and caps.ansi256) {
+            const index: u8 = self.cachedNearestPaletteIndex(rgba);
+
+            if (is_background) {
+                ansi.ANSI.bgIndexedColorOutput(writer, index) catch {};
+            } else {
+                ansi.ANSI.fgIndexedColorOutput(writer, index) catch {};
+            }
+            return;
+        }
+
+        if (is_background) {
+            ansi.ANSI.bgColorOutput(writer, ansi.red(rgba), ansi.green(rgba), ansi.blue(rgba)) catch {};
+        } else {
+            ansi.ANSI.fgColorOutput(writer, ansi.red(rgba), ansi.green(rgba), ansi.blue(rgba)) catch {};
+        }
+    }
+
+    pub fn setRenderOffset(self: *CliRenderer, offset: u32) void {
+        if (self.terminalSetup and !self.useAlternateScreen and self.renderOffset > 0 and offset == 0) {
+            var clearBuf: [256]u8 = undefined;
+            var stream = std.io.fixedBufferStream(&clearBuf);
+            const writer = stream.writer();
+            self.clearSplitFooterSurface(writer);
+            self.backend.writeOut(stream.getWritten());
+        }
+
+        self.renderOffset = offset;
+    }
+
+    fn renderStatusFromWrite(status: output.WriteStatus) RenderStatus {
+        return switch (status) {
+            .ok => .rendered,
+            .skipped => .skipped,
+            .failed => .failed,
+        };
+    }
+
+    fn clearSkippedFrameState(self: *CliRenderer) void {
+        self.nextRenderBuffer.clear(self.backgroundColor, null);
+        @memset(self.nextHitGrid, 0);
+    }
+
+    fn finishSkippedFrame(self: *CliRenderer) RenderStatus {
+        self.clearSkippedFrameState();
+        return .skipped;
+    }
+
+    fn finishFailedFrame(self: *CliRenderer) RenderStatus {
+        self.force_full_repaint = true;
+        return .failed;
+    }
+
+    fn renderResult(self: *CliRenderer, status: RenderStatus) RenderResult {
+        return .{ .renderOffset = self.renderOffset, .status = status };
+    }
+
+    // One code path; backend selects writer type at compile time.
+    pub fn render(self: *CliRenderer, force: bool) RenderStatus {
+        // Backpressure: skipping must NOT update lastRenderTime so the next
+        // successful render sees the full accumulated delta (catch-up).
+        if (self.backend.prepareFrame() != .ok) {
+            return self.finishSkippedFrame();
+        }
+
+        const now = std.time.microTimestamp();
+        const deltaTimeMs = @as(f64, @floatFromInt(now - self.lastRenderTime));
+        const deltaTime = deltaTimeMs / 1000.0;
+
+        self.lastRenderTime = now;
+        self.renderDebugOverlay();
+
+        // `inline else` monomorphizes the writer type per variant — one
+        // dispatch site, zero vtable cost.
+        var write_status: output.WriteStatus = .ok;
+        switch (self.backend) {
+            inline else => |*b| {
+                b.beginFrame();
+                var w = b.writer();
+                self.prepareRenderFrameWithWriter(&w, force, false);
+                write_status = b.endFrame();
+            },
+        }
+
+        const status = renderStatusFromWrite(write_status);
+        if (status == .failed) {
+            return self.finishFailedFrame();
+        }
+
+        self.collectFrameStats(deltaTime);
+        return status;
+    }
+
+    fn splitOutputOffset(self: *const CliRenderer, surface_offset: u32) u32 {
+        return self.splitScrollback.renderOffset(surface_offset);
+    }
+
+    fn clampSplitSurfaceOffset(self: *const CliRenderer, surface_offset: u32, pinned_render_offset: u32) u32 {
+        const output_offset = self.splitOutputOffset(pinned_render_offset);
+        return std.math.clamp(surface_offset, output_offset, pinned_render_offset);
+    }
+
+    pub fn resetSplitScrollback(self: *CliRenderer, seed_rows: u32, pinned_render_offset: u32) u32 {
+        self.splitScrollback.reset(seed_rows);
+        self.renderOffset = self.splitScrollback.renderOffset(pinned_render_offset);
+        return self.renderOffset;
+    }
+
+    pub fn syncSplitScrollback(self: *CliRenderer, pinned_render_offset: u32) u32 {
+        self.renderOffset = self.clampSplitSurfaceOffset(self.renderOffset, pinned_render_offset);
+        return self.renderOffset;
+    }
+
+    pub fn getSplitOutputOffset(self: *CliRenderer, surface_offset: u32) u32 {
+        return self.splitOutputOffset(surface_offset);
+    }
+
+    pub fn setPendingSplitFooterTransition(
+        self: *CliRenderer,
+        mode: SplitFooterTransitionMode,
+        source_top_line: u32,
+        source_height: u32,
+        target_top_line: u32,
+        target_height: u32,
+        scroll_lines: u32,
+    ) void {
+        self.pendingSplitFooterTransition = .{
+            .mode = mode,
+            .source_top_line = source_top_line,
+            .source_height = source_height,
+            .target_top_line = target_top_line,
+            .target_height = target_height,
+            .scroll_lines = scroll_lines,
+        };
+    }
+
+    pub fn clearPendingSplitFooterTransition(self: *CliRenderer) void {
+        self.pendingSplitFooterTransition.clear();
+    }
+
+    fn applyPendingSplitFooterTransition(self: *CliRenderer, writer: anytype, frame_started: *bool) void {
+        const transition = self.pendingSplitFooterTransition;
+        defer self.pendingSplitFooterTransition.clear();
+
+        if (transition.mode == .none or transition.source_height == 0 or transition.target_height == 0) {
+            return;
+        }
+
+        if (!frame_started.*) {
+            beginRenderFrame(writer);
+            frame_started.* = true;
+        }
+
+        switch (transition.mode) {
+            .viewport_scroll => {
+                if (transition.scroll_lines == 0) {
+                    return;
+                }
+
+                self.splitScrollback.noteViewportScroll(transition.scroll_lines);
+
+                if (transition.source_top_line < transition.target_top_line) {
+                    writer.print("\x1b[{d}T", .{transition.scroll_lines}) catch {};
+                } else if (transition.source_top_line > transition.target_top_line) {
+                    writer.print("\x1b[{d}S", .{transition.scroll_lines}) catch {};
+                }
+            },
+            .clear_stale_rows => {
+                const source_end = transition.source_top_line + transition.source_height - 1;
+                const target_end = transition.target_top_line + transition.target_height - 1;
+                var line = transition.source_top_line;
+                while (line <= source_end) : (line += 1) {
+                    if (line >= transition.target_top_line and line <= target_end) {
+                        continue;
+                    }
+
+                    ansi.ANSI.moveToOutput(writer, 1, line) catch {};
+                    writer.writeAll("\x1b[2K") catch {};
+                }
+            },
+            .none => {},
+        }
+    }
+
+    pub fn repaintSplitFooter(
+        self: *CliRenderer,
+        pinned_render_offset: u32,
+        force: bool,
+    ) RenderResult {
+        if (self.backend.prepareFrame() != .ok) {
+            const status = self.finishSkippedFrame();
+            return self.renderResult(status);
+        }
+
+        const now = std.time.microTimestamp();
+        const deltaTimeMs = @as(f64, @floatFromInt(now - self.lastRenderTime));
+        const deltaTime = deltaTimeMs / 1000.0;
+
+        self.lastRenderTime = now;
+        self.renderDebugOverlay();
+
+        const status = self.prepareSplitFooterRepaintFrame(pinned_render_offset, force);
+        var result_status = status;
+        if (status == .failed) {
+            result_status = self.finishFailedFrame();
+        } else {
+            self.collectFrameStats(deltaTime);
+        }
+
+        return self.renderResult(result_status);
+    }
+
+    pub fn commitSplitFooterSnapshotBatched(
+        self: *CliRenderer,
+        snapshot: *const OptimizedBuffer,
+        row_columns: u32,
+        start_on_new_line: bool,
+        trailing_newline: bool,
+        pinned_render_offset: u32,
+        force: bool,
+        begin_frame: bool,
+        finalize_frame: bool,
+    ) RenderResult {
+        // Batched commit protocol:
+        // - first call starts frame and appends payload
+        // - middle calls append payload only
+        // - final call renders footer diff/cursor and closes frame
+        // This avoids repeated syncSet/syncReset and cursor toggles per chunk.
+        if (begin_frame) {
+            if (self.backend.prepareFrame() != .ok) {
+                const status = self.finishSkippedFrame();
+                return self.renderResult(status);
+            }
+
+            const now = std.time.microTimestamp();
+            const deltaTimeMs = @as(f64, @floatFromInt(now - self.lastRenderTime));
+            const deltaTime = deltaTimeMs / 1000.0;
+
+            self.lastRenderTime = now;
+            self.renderDebugOverlay();
+
+            var write_status: output.WriteStatus = .ok;
+            var result_status: RenderStatus = .rendered;
+            switch (self.backend) {
+                inline else => |*b| {
+                    b.beginFrame();
+                    var w = b.writer();
+                    beginRenderFrame(&w);
+                    var frame_started = true;
+                    self.applyPendingSplitFooterTransition(&w, &frame_started);
+
+                    // Track batch lifetime so subsequent calls can append into the same
+                    // output buffer without restarting frame state.
+                    self.splitBatchActive = !finalize_frame;
+                    self.splitBatchRedrawFooter = false;
+                    self.splitBatchDeltaTime = deltaTime;
+
+                    const redraw_footer = self.appendSplitFooterSnapshotCommit(
+                        &w,
+                        snapshot,
+                        row_columns,
+                        start_on_new_line,
+                        trailing_newline,
+                        pinned_render_offset,
+                        force,
+                    );
+
+                    if (finalize_frame) {
+                        self.prepareRenderFrameWithWriter(&w, redraw_footer, true);
+                        write_status = b.endFrame();
+                        const status = renderStatusFromWrite(write_status);
+                        if (status == .failed) {
+                            result_status = self.finishFailedFrame();
+                        } else {
+                            result_status = status;
+                            self.collectFrameStats(deltaTime);
+                        }
+
+                        self.splitBatchActive = false;
+                        self.splitBatchRedrawFooter = false;
+                        self.splitBatchDeltaTime = 0;
+                    } else {
+                        result_status = .rendered;
+                        self.splitBatchRedrawFooter = redraw_footer;
+                    }
+                },
+            }
+
+            return self.renderResult(result_status);
+        }
+
+        // Defensive fallback: if caller forgot begin_frame, execute through a
+        // single-call frame instead of appending into undefined batch state.
+        if (!self.splitBatchActive) {
+            return self.commitSplitFooterSnapshotBatched(
+                snapshot,
+                row_columns,
+                start_on_new_line,
+                trailing_newline,
+                pinned_render_offset,
+                force,
+                true,
+                true,
+            );
+        }
+
+        var write_status: output.WriteStatus = .ok;
+        var result_status: RenderStatus = .rendered;
+        switch (self.backend) {
+            inline else => |*b| {
+                var w = b.writer();
+                const redraw_footer = self.appendSplitFooterSnapshotCommit(
+                    &w,
+                    snapshot,
+                    row_columns,
+                    start_on_new_line,
+                    trailing_newline,
+                    pinned_render_offset,
+                    force,
+                );
+                self.splitBatchRedrawFooter = self.splitBatchRedrawFooter or redraw_footer;
+
+                if (finalize_frame) {
+                    self.prepareRenderFrameWithWriter(&w, self.splitBatchRedrawFooter, true);
+                    write_status = b.endFrame();
+
+                    const status = renderStatusFromWrite(write_status);
+                    if (status == .failed) {
+                        result_status = self.finishFailedFrame();
+                    } else {
+                        result_status = status;
+                        self.collectFrameStats(self.splitBatchDeltaTime);
+                    }
+
+                    self.splitBatchActive = false;
+                    self.splitBatchRedrawFooter = false;
+                    self.splitBatchDeltaTime = 0;
+                } else {
+                    result_status = .rendered;
+                }
+            },
+        }
+
+        return self.renderResult(result_status);
+    }
+
+    /// Serialization for one split append payload.
+    ///
+    /// This function intentionally does not emit syncSet/syncReset or footer
+    /// repaint sequences. It only writes snapshot text rows at the current output
+    /// cursor. Frame boundaries are controlled by commitSplitFooterSnapshot*
+    /// callers so multiple payloads can share one frame.
+    ///
+    /// row_columns limits the per-row emitted width. Caller may provide a
+    /// wider buffer but a smaller logical row width for wrapped stdout chunks.
+    ///
+    /// trailing_newline mirrors stdout semantics: only payloads that logically
+    /// ended with '\n' advance and clear the next row after the final row.
+    fn writeSnapshotCommit(
+        self: *CliRenderer,
+        writer: anytype,
+        snapshot: *const OptimizedBuffer,
+        row_columns: u32,
+        trailing_newline: bool,
+    ) void {
+        var currentFg: ?RGBA = null;
+        var currentBg: ?RGBA = null;
+        var currentAttributes: ?u32 = null;
+        var currentLinkId: u32 = 0;
+        var utf8Buf: [4]u8 = undefined;
+
+        const hyperlinksEnabled = self.terminal.getCapabilities().hyperlinks;
+        const render_columns = @min(row_columns, snapshot.width);
+
+        for (0..snapshot.height) |uy| {
+            const y = @as(u32, @intCast(uy));
+            const row_end = snapshotRowEnd(snapshot, y, render_columns);
+
+            for (0..row_end) |ux| {
+                const x = @as(u32, @intCast(ux));
+                const cell = snapshot.get(x, y) orelse continue;
+
+                const fgMatch = currentFg != null and buf.rgbaEqual(currentFg.?, cell.fg);
+                const bgMatch = currentBg != null and buf.rgbaEqual(currentBg.?, cell.bg);
+                const sameAttributes = fgMatch and bgMatch and currentAttributes != null and 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 |_| {
+                            currentLinkId = 0;
+                        }
+                    }
+                }
+
+                if (!sameAttributes) {
+                    writer.writeAll(ansi.ANSI.reset) catch {};
+
+                    currentFg = cell.fg;
+                    currentBg = cell.bg;
+                    currentAttributes = cell.attributes;
+
+                    self.emitColor(writer, cell.fg, false);
+                    self.emitColor(writer, cell.bg, true);
+
+                    ansi.TextAttributes.applyAttributesOutputWriter(writer, cell.attributes) catch {};
+                }
+
+                if (cell.char == 0) {
+                    writer.writeByte(' ') catch {};
+                } else if (gp.isGraphemeChar(cell.char)) {
+                    const gid: u32 = gp.graphemeIdFromChar(cell.char);
+                    const bytes = self.pool.get(gid) catch {
+                        writer.writeByte(' ') catch {};
+                        continue;
+                    };
+
+                    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 {};
+                        }
+                    }
+                } else if (gp.isContinuationChar(cell.char)) {
+                    // Keep split scrollback payload behavior aligned with the live
+                    // frame renderer: continuation cells must not serialize as
+                    // spaces, or wide graphemes become one extra column wider in
+                    // terminal output and table rows can autowrap unexpectedly.
+                } else {
+                    const len = std.unicode.utf8Encode(@intCast(cell.char), &utf8Buf) catch 1;
+                    writer.writeAll(utf8Buf[0..len]) catch {};
+                }
+            }
+
+            if (hyperlinksEnabled and currentLinkId != 0) {
+                writer.writeAll("\x1b]8;;\x1b\\") catch {};
+                currentLinkId = 0;
+            }
+
+            writer.writeAll(ansi.ANSI.reset) catch {};
+            // Guarantee short rows do not leave stale content from prior frame data.
+            writer.writeAll(ansi.ANSI.eraseToEndOfLine) catch {};
+            currentFg = null;
+            currentBg = null;
+            currentAttributes = null;
+
+            const is_last_row = @as(u32, @intCast(uy + 1)) >= snapshot.height;
+            if (!is_last_row or trailing_newline) {
+                writer.writeAll("\r\n") catch {};
+            }
+
+            if (is_last_row and trailing_newline) {
+                // After a trailing newline, clear the destination row that becomes
+                // current so old footer text cannot flash through.
+                writer.writeAll(ansi.ANSI.reset) catch {};
+                writer.writeAll(ansi.ANSI.eraseToEndOfLine) catch {};
+            }
+        }
+    }
+
+    /// Shared append path for all split payload sources.
+    ///
+    /// Contract: append payload first, then position for footer repaint in the
+    /// same frame. Returning redraw_footer lets caller skip full diff work when
+    /// footer position did not actually change.
+    fn appendSplitFooterSnapshotCommit(
+        self: *CliRenderer,
+        writer: anytype,
+        snapshot: *const OptimizedBuffer,
+        row_columns: u32,
+        start_on_new_line: bool,
+        trailing_newline: bool,
+        pinned_render_offset: u32,
+        force: bool,
+    ) bool {
+        const previousSurfaceOffset = self.renderOffset;
+        const previousOutputOffset = self.splitOutputOffset(previousSurfaceOffset);
+        const previousOutputColumn = self.splitScrollback.tail_column;
+        const snapshot_has_content = snapshot.width > 0 and snapshot.height > 0;
+        const normalized_row_columns = @min(row_columns, snapshot.width);
+        const starts_mid_line = previousOutputColumn > 0 and start_on_new_line;
+        const starts_wrapped_line = previousOutputColumn >= self.width;
+        const previousFooterTopLine: u32 = @max(previousSurfaceOffset + 1, @as(u32, 1));
+
+        if (snapshot_has_content) {
+            // First update logical split scrollback state, then emit terminal I/O.
+            // Keeping model state authoritative makes repaint decisions deterministic.
+            if (starts_mid_line) {
+                self.splitScrollback.noteNewline();
+            }
+
+            var row: u32 = 0;
+            while (row < snapshot.height) : (row += 1) {
+                self.splitScrollback.publishRow(
+                    snapshotRowEnd(snapshot, row, normalized_row_columns),
+                    self.width,
+                    row + 1 < snapshot.height or trailing_newline,
+                );
+            }
+
+            self.splitScrollback.published_rows = @min(self.splitScrollback.published_rows, pinned_render_offset);
+        }
+
+        const next_output_offset = self.splitScrollback.renderOffset(pinned_render_offset);
+        const next_render_offset = self.clampSplitSurfaceOffset(previousSurfaceOffset, pinned_render_offset);
+        const targetFooterTopLine: u32 = @max(next_render_offset + 1, @as(u32, 1));
+        // Footer redraw is only needed when offset changes (settling/pinning) or
+        // when an explicit force was requested by the caller.
+        const redraw_footer = force or previousSurfaceOffset != next_render_offset;
+        // When split scrollback is settled at the pinned boundary, newlines/wraps from
+        // appended output must scroll only the upper pane. Without a temporary DECSTBM
+        // region, terminals advance into the footer rows and overwrite them in place.
+        const use_bounded_scroll_region = snapshot_has_content and
+            pinned_render_offset > 0 and
+            next_render_offset == pinned_render_offset and
+            next_output_offset == next_render_offset;
+
+        if (snapshot_has_content or force) {
+            if (snapshot_has_content) {
+                // Clear rows that are transitioning from "footer surface" to scrollback before
+                // writing appended rows. If this happens after append, the clear itself is what
+                // gets scrolled and manifests as extra blank lines in history.
+                if (targetFooterTopLine > previousFooterTopLine) {
+                    var clear_line = previousFooterTopLine;
+                    while (clear_line < targetFooterTopLine) : (clear_line += 1) {
+                        ansi.ANSI.moveToOutput(writer, 1, clear_line) catch {};
+                        writer.writeAll("\x1b[2K") catch {};
+                    }
+                }
+
+                if (use_bounded_scroll_region) {
+                    // Temporarily bound scrolling to the upper pane so newline/wrap
+                    // from appended payload pushes history upward instead of stepping
+                    // through footer rows.
+                    writer.print("\x1b[1;{d}r", .{pinned_render_offset}) catch {};
+                }
+
+                moveToSplitOutputCursor(writer, previousOutputOffset, previousOutputColumn, self.width);
+                if (starts_mid_line or starts_wrapped_line) {
+                    // The prior commit left output cursor mid-row and caller asked
+                    // for newline anchoring. When the prior commit exactly filled the
+                    // row, we also need a CRLF here because moving the cursor back to
+                    // the last column loses the terminal's pending autowrap state.
+                    // Emit CRLF before payload to preserve logical row boundaries
+                    // across commit chunks.
+                    writer.writeAll("\r\n") catch {};
+                }
+
+                // Serialize payload rows at current output cursor.
+                self.writeSnapshotCommit(writer, snapshot, normalized_row_columns, trailing_newline);
+
+                if (use_bounded_scroll_region) {
+                    // Restore default full-height scroll region for regular repaint
+                    // and cursor operations after append is complete.
+                    writer.writeAll("\x1b[r") catch {};
+                }
+            }
+
+            self.renderOffset = next_render_offset;
+            if (redraw_footer) {
+                ansi.ANSI.moveToOutput(writer, 1, targetFooterTopLine) catch {};
+            }
+        } else {
+            self.renderOffset = next_render_offset;
+        }
+
+        return redraw_footer;
+    }
+
+    fn beginRenderFrame(writer: anytype) void {
+        writer.writeAll(ansi.ANSI.syncSet) catch {};
+        writer.writeAll(ansi.ANSI.hideCursor) catch {};
+    }
+
+    fn prepareSplitFooterRepaintFrame(
+        self: *CliRenderer,
+        pinned_render_offset: u32,
+        force: bool,
+    ) RenderStatus {
+        const transition = self.pendingSplitFooterTransition;
+        const hasPendingViewportTarget = transition.mode == .viewport_scroll and
+            transition.target_top_line > 0 and
+            transition.scroll_lines > 0;
+        const previousRenderOffset = self.renderOffset;
+        const next_render_offset = if (hasPendingViewportTarget)
+            transition.target_top_line - 1
+        else
+            self.clampSplitSurfaceOffset(previousRenderOffset, pinned_render_offset);
+        const redraw_footer = force or previousRenderOffset != next_render_offset;
+
+        self.renderOffset = next_render_offset;
+        // Do not pre-start sync frame here. prepareRenderFrameWithWriter now lazily starts
+        // frame output only when something actually changes; this prevents no-op
+        // repaint ticks from emitting hide/show cursor and sync envelopes.
+        var write_status: output.WriteStatus = .ok;
+        switch (self.backend) {
+            inline else => |*b| {
+                b.beginFrame();
+                var w = b.writer();
+                self.prepareRenderFrameWithWriter(&w, redraw_footer, false);
+                write_status = b.endFrame();
+            },
+        }
+        return renderStatusFromWrite(write_status);
+    }
+
+    pub fn getNextBuffer(self: *CliRenderer) *OptimizedBuffer {
+        return self.nextRenderBuffer;
+    }
+
+    pub fn getCurrentBuffer(self: *CliRenderer) *OptimizedBuffer {
+        return self.currentRenderBuffer;
+    }
+
+    /// Generic over the writer type so each backend can provide its own writer
+    /// (buffered frame append or feed streaming) without dispatch in the render path.
+    /// `sync_started` is true only when the caller already opened the
+    /// synchronized-update envelope for a batched split-footer commit.
+    pub fn prepareRenderFrameWithWriter(self: *CliRenderer, writer: anytype, force: bool, sync_started: bool) void {
+        const renderStartTime = std.time.microTimestamp();
+        var cellsUpdated: u32 = 0;
+        const palette_force = self.last_rendered_palette_epoch == null or self.last_rendered_palette_epoch.? != self.palette_epoch;
+        const should_force = force or self.force_full_repaint or palette_force;
+
+        // Lazy frame start is the core no-op suppression mechanism. If diffing,
+        // cursor state, and pointer state are unchanged, frame_started stays false
+        // and we emit nothing at all for this tick.
+        var frame_started = sync_started;
+        self.applyPendingSplitFooterTransition(writer, &frame_started);
+
+        var currentFg: ?RGBA = null;
+        var currentBg: ?RGBA = null;
+        var currentAttributes: ?u32 = null;
+        var currentLinkId: u32 = 0;
+        var utf8Buf: [4]u8 = undefined;
+
+        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 (!should_force) {
+                    const charEqual = currentCell.?.char == nextCell.?.char;
+                    const attrEqual = currentCell.?.attributes == nextCell.?.attributes;
+
+                    if (charEqual and attrEqual and
+                        buf.rgbaEqual(currentCell.?.fg, nextCell.?.fg) and
+                        buf.rgbaEqual(currentCell.?.bg, nextCell.?.bg))
+                    {
+                        if (runLength > 0) {
+                            writer.writeAll(ansi.ANSI.reset) catch {};
+                            runStart = -1;
+                            runLength = 0;
+                        }
+                        continue;
+                    }
+                }
+
+                const cell = nextCell.?;
+
+                if (!frame_started) {
+                    beginRenderFrame(writer);
+                    frame_started = true;
+                }
+
+                const fgMatch = currentFg != null and buf.rgbaEqual(currentFg.?, cell.fg);
+                const bgMatch = currentBg != null and buf.rgbaEqual(currentBg.?, cell.bg);
+                const sameAttributes = fgMatch and bgMatch and currentAttributes != null and 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 = cell.attributes;
+
+                    ansi.ANSI.moveToOutput(writer, x + 1, y + 1 + self.renderOffset) catch {};
+
+                    self.emitColor(writer, cell.fg, false);
+                    self.emitColor(writer, cell.bg, true);
+
+                    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) {
+            if (!frame_started) {
+                beginRenderFrame(writer);
+                frame_started = true;
+            }
+            writer.writeAll("\x1b]8;;\x1b\\") catch {};
+        }
+
+        if (frame_started) {
+            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 = ansi.red(cursorColor);
+            const cursorG = ansi.green(cursorColor);
+            const cursorB = ansi.blue(cursorColor);
+
+            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);
+            const cursorX = cursorPos.x;
+            const cursorY = cursorPos.y + self.renderOffset;
+            const positionChanged = self.lastCursorX == null or self.lastCursorY == null or self.lastCursorX.? != cursorX or self.lastCursorY.? != cursorY;
+            const visibilityChanged = self.lastCursorVisible == null or !self.lastCursorVisible.?;
+            // If any visual output was produced this frame, we must restore cursor
+            // state (position + visibility). If frame is otherwise empty, only emit
+            // cursor sequences when some cursor property actually changed.
+            const needsCursorRestore = frame_started or styleChanged or colorChanged or positionChanged or visibilityChanged;
+
+            if (needsCursorRestore) {
+                if (!frame_started) {
+                    beginRenderFrame(writer);
+                    frame_started = true;
+                }
+
+                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, cursorX, cursorY) catch {};
+                writer.writeAll(ansi.ANSI.showCursor) catch {};
+            }
+
+            self.lastCursorX = cursorX;
+            self.lastCursorY = cursorY;
+            self.lastCursorVisible = true;
+        } else {
+            if (!frame_started and (self.lastCursorVisible == null or self.lastCursorVisible.?)) {
+                beginRenderFrame(writer);
+                frame_started = true;
+                writer.writeAll(ansi.ANSI.hideCursor) catch {};
+            }
+
+            self.lastCursorStyleTag = null;
+            self.lastCursorBlinking = null;
+            self.lastCursorColorRGB = null;
+            self.lastCursorX = null;
+            self.lastCursorY = null;
+            self.lastCursorVisible = false;
+        }
+
+        const mousePointer = self.terminal.getMousePointer();
+        if (mousePointer != self.lastMousePointerStyle) {
+            if (!frame_started) {
+                beginRenderFrame(writer);
+                frame_started = true;
+            }
+            ansi.ANSI.setMousePointerOutput(writer, mousePointer.toName()) catch {};
+            self.lastMousePointerStyle = mousePointer;
+        }
+
+        // Only close sync if we opened it. This keeps true no-op frames empty.
+        if (frame_started) {
+            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.last_rendered_palette_epoch = self.palette_epoch;
+        self.force_full_repaint = false;
+
+        self.nextRenderBuffer.clear(self.backgroundColor, null);
+
+        // 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 = self.hitGridResizeInvalidated or !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 {
+        self.backend.writeOut(data);
+    }
+
+    pub fn writeOutMultiple(self: *CliRenderer, data_slices: []const []const u8) void {
+        self.backend.writeOutMultiple(data_slices);
+    }
+
+    /// 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 {
+        const dirty = self.hitGridDirty;
+        self.hitGridResizeInvalidated = false;
+        return dirty;
+    }
+
+    /// 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 .{
+            .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 {};
+    }
+
+    /// Dump the last rendered output to a file. Backend-specific formatting
+    /// is delegated to `backend.dumpTo(writer)` — no tag inspection here.
+    pub fn dumpOutputBuffer(self: *CliRenderer, 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/output_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("Output Buffer Dump (timestamp: {d}):\n", .{timestamp}) catch return;
+        writer.writeAll("Last Rendered ANSI Output:\n") catch return;
+        writer.writeAll("================\n") catch return;
+
+        self.backend.dumpTo(writer);
+
+        writer.flush() catch {};
+    }
+
+    pub fn dumpBuffers(self: *CliRenderer, timestamp: i64) void {
+        self.dumpSingleBuffer(self.currentRenderBuffer, "current", timestamp);
+        self.dumpSingleBuffer(self.nextRenderBuffer, "next", timestamp);
+        self.dumpOutputBuffer(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 queryThemeColors(self: *CliRenderer) void {
+        var stream = std.io.fixedBufferStream(&self.writeOutBuf);
+        self.terminal.queryThemeColors(stream.writer()) catch {};
+        self.writeOut(stream.getWritten());
+    }
+
+    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, text_utf8: []const u8) bool {
+        const output_len = self.terminal.clipboardSequenceSize(text_utf8.len) catch return false;
+        const output_bytes = self.allocator.alloc(u8, output_len) catch return false;
+        defer self.allocator.free(output_bytes);
+
+        var stream = std.io.fixedBufferStream(output_bytes);
+        self.terminal.writeClipboard(stream.writer(), target, text_utf8) catch return false;
+        const written = stream.getWritten();
+        std.debug.assert(written.len == output_len);
+        self.writeOut(written);
+        return true;
+    }
+
+    pub fn clearClipboardOSC52(self: *CliRenderer, target: Terminal.ClipboardTarget) bool {
+        var stream: std.ArrayListUnmanaged(u8) = .{};
+        defer stream.deinit(self.allocator);
+        self.terminal.writeClipboard(stream.writer(self.allocator), target, "") catch return false;
+        self.writeOut(stream.items);
+        return true;
+    }
+
+    pub fn triggerNotification(self: *CliRenderer, message: []const u8, title: ?[]const u8) bool {
+        var stream: std.ArrayListUnmanaged(u8) = .{};
+        defer stream.deinit(self.allocator);
+
+        const ok = self.terminal.writeNotification(self.allocator, stream.writer(self.allocator), message, title) catch return false;
+        if (!ok) return false;
+        self.writeOut(stream.items);
+        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, ansi.rgbColor(20, 20, 40, 255));
+        self.nextRenderBuffer.drawText("Debug Information", x + 1, y + 1, ansi.rgbColor(255, 255, 100, 255), ansi.rgbColor(0, 0, 0, 0), ansi.TextAttributes.BOLD) catch {};
+
+        var row: u32 = 2;
+        const bg: RGBA = ansi.rgbColor(0, 0, 0, 0);
+        const fg: RGBA = ansi.rgbColor(200, 200, 200, 255);
+
+        // 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 outputWriteTimeAvg = getStatAverage(f64, &self.statSamples.outputWriteTime);
+        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;
+        }
+
+        // Output Write Time
+        if (self.renderStats.outputWriteTime) |writeTime| {
+            var writeTimeText: [64]u8 = undefined;
+            const writeTimeLen = std.fmt.bufPrint(&writeTimeText, "Output: {d:.3}ms (avg: {d:.3}ms)", .{ writeTime / 1000.0, outputWriteTimeAvg / 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.backend.isUseThread()) "Yes" else "No"}) catch return;
+        self.nextRenderBuffer.drawText(isThreadedLen, x + 1, y + row, fg, bg, 0) catch {};
+        row += 1;
+    }
+};