emoemu 0.1.0

package/src/rendering/KittyRenderer/index.ts

@@ -0,0 +1,616 @@
+import { clamp } from 'remeda';
+import { appendFileSync, writeFileSync } from 'fs';
+import { deflateSync } from 'zlib';
+import { PostProcessingPipeline, type EffectOptions } from '../postProcessing';
+import { buildGammaLUT, rgb15ToRgb24, calculateLuminance8 } from '../../utils/color';
+import { getTerminalDimensions } from '../../utils/terminal';
+import { APC, ST, moveCursor, clearScreen, clearLine, hideCursor, showCursor } from '../shared/ansi';
+import { fitToTerminal } from '../shared/fitToTerminal';
+import { PNG_SIGNATURE, createPngChunk } from '../../utils/png';
+import { isRgb15Buffer, type FrameBuffer } from '../../core/core';
+import {
+  DEFAULT_NATIVE_WIDTH,
+  DEFAULT_NATIVE_HEIGHT,
+  STATUS_LINE_ROWS,
+  CELL_WIDTH_PX,
+  CELL_HEIGHT_PX,
+  INITIAL_FULL_RENDER_FRAMES,
+  KITTY_CHUNK_SIZE,
+  PNG_BIT_DEPTH,
+  PNG_COLOR_TYPE_INDEXED,
+  PNG_COLOR_TYPE_RGB,
+  DEFAULT_PNG_COMPRESSION,
+  DEFAULT_RENDER_SCALE,
+  MIN_RENDER_SCALE,
+  MAX_RENDER_SCALE,
+  MEMORY_LOG_INTERVAL,
+  DEFAULT_GAMMA,
+  RGB24_BYTES_PER_PIXEL,
+  PNG_IHDR_LENGTH,
+  PNG_IHDR_HEIGHT_OFFSET,
+  BYTES_PER_KB,
+  PACK_RED_SHIFT,
+  PACK_GREEN_SHIFT,
+  PALETTE_BUFFER_SIZE,
+} from '..';
+
+// Debug logging for Kitty graphics issues
+const DEBUG_KITTY = process.env.DEBUG_KITTY === '1';
+const DEBUG_LOG_PATH = '/tmp/kitty-debug.log';
+
+const debugLog = (msg: string): void => {
+  if (!DEBUG_KITTY) {return;}
+  const timestamp = new Date().toISOString();
+  appendFileSync(DEBUG_LOG_PATH, `[${timestamp}] ${msg}\n`);
+};
+
+// Kitty graphics protocol renderer
+// https://sw.kovidgoyal.net/kitty/graphics-protocol/
+
+export interface KittyRendererOptions extends EffectOptions {
+  scale?: number;  // Scale factor for the image (undefined = auto-fit to terminal)
+  sourceWidth?: number;   // Source framebuffer width (default: 256)
+  sourceHeight?: number;  // Source framebuffer height (default: 240)
+  colorSpace?: 'rgb15' | 'rgb24';  // Color format (default: rgb24)
+  pixelAspectRatio?: number;  // Pixel aspect ratio for correct display (default: 1.0)
+  enableDiffRendering?: boolean;  // Enable diff-based rendering optimization (default: true)
+  colorEnabled?: boolean;  // When false, render in grayscale (default: true)
+  pngCompressionLevel?: number;  // PNG compression level 1-9 (default: 1, higher = smaller but slower)
+}
+
+// Color space type for frame conversion
+type ColorSpace = 'rgb15' | 'rgb24';
+
+export class KittyRenderer {
+  private scale: number;  // Scale factor (0.25, 0.5, 1, 2, 3, etc.) - supports both up and downscaling
+  private imageId: number = 1;
+  private frameNumber: number = 0;
+  private displayCols: number;
+  private displayRows: number;
+  private offsetCol: number = 1;  // Horizontal offset for centering
+  private offsetRow: number = 1;  // Vertical offset for centering
+  // Source framebuffer dimensions
+  private sourceWidth: number;
+  private sourceHeight: number;
+  // Pixel aspect ratio for correct display (e.g., 8/7 for NES)
+  private pixelAspectRatio: number;
+  // Scaled image dimensions in pixels (integer multiple of source resolution)
+  private scaledWidth: number;
+  private scaledHeight: number;
+  // Pre-allocated RGB buffer for native resolution (before scaling, for post-processing)
+  private nativeRgbBuffer!: Uint8Array;
+  // Pre-allocated RGB buffer for scaled output
+  private scaledRgbBuffer!: Uint8Array;
+  // Pre-allocated row buffer for horizontal scaling
+  private scaledRowBuffer!: Uint8Array;
+  // Previous frame buffer for row-level memoization (skip unchanged rows)
+  // For rgb15: Uint16Array (2 bytes per pixel)
+  // For rgb24: Uint8Array (3 bytes per pixel)
+  private prevFrameBuffer: Uint8Array | Uint16Array;
+  // Cached PNG data from last encode
+  private pngBuffer: Buffer = Buffer.alloc(0);
+  // Color space for framebuffer interpretation
+  private colorSpace: ColorSpace;
+  // Diff-based rendering optimization
+  private enableDiffRendering: boolean;
+  // Color mode (true = full color, false = grayscale)
+  private colorEnabled: boolean;
+  // PNG compression level (1-9, higher = smaller but slower)
+  private pngCompressionLevel: number;
+  // Gamma lookup table for frame conversion
+  private gammaLUT: Uint8Array;
+  // Post-processing effects pipeline
+  private postProcessing: PostProcessingPipeline;
+
+  constructor(options: KittyRendererOptions = {}) {
+    this.sourceWidth = options.sourceWidth ?? DEFAULT_NATIVE_WIDTH;
+    this.sourceHeight = options.sourceHeight ?? DEFAULT_NATIVE_HEIGHT;
+    this.colorSpace = options.colorSpace ?? 'rgb24';
+    this.pixelAspectRatio = options.pixelAspectRatio ?? 1.0;
+    this.enableDiffRendering = options.enableDiffRendering ?? true;
+    this.colorEnabled = options.colorEnabled ?? true;
+    this.pngCompressionLevel = options.pngCompressionLevel ?? DEFAULT_PNG_COMPRESSION;
+
+    // Build gamma LUT for frame conversion (separate from post-processing)
+    const gamma = options.gamma ?? DEFAULT_GAMMA;
+    this.gammaLUT = buildGammaLUT(gamma);
+
+    // Create post-processing pipeline with effect options
+    this.postProcessing = new PostProcessingPipeline({
+      gamma,
+      scanlines: options.scanlines,
+      saturation: options.saturation,
+      brightness: options.brightness,
+      contrast: options.contrast,
+      vignette: options.vignette,
+      bloom: options.bloom,
+      bloomThreshold: options.bloomThreshold,
+      ntsc: options.ntsc,
+      curvature: options.curvature,
+      chromaticAberration: options.chromaticAberration,
+    });
+
+    // Allocate prevFrameBuffer based on color space
+    const pixelCount = this.sourceWidth * this.sourceHeight;
+    if (this.colorSpace === 'rgb15') {
+      this.prevFrameBuffer = new Uint16Array(pixelCount);
+    } else {
+      this.prevFrameBuffer = new Uint8Array(pixelCount * RGB24_BYTES_PER_PIXEL);
+    }
+
+    // Render scale controls internal buffer resolution (default: DEFAULT_RENDER_SCALE)
+    // Display size always fills terminal, Kitty handles the final scaling
+    // Supports fractional scales (0.25, 0.5) for downscaling and integer scales (1, 2, 3, 4) for upscaling
+    const rawScale = options.scale ?? DEFAULT_RENDER_SCALE;
+    this.scale = clamp(rawScale, { min: MIN_RENDER_SCALE, max: MAX_RENDER_SCALE });
+
+    // Calculate display size to fill terminal (Kitty will scale the image)
+    const { cols, rows, offsetCol, offsetRow } = this.calculateDisplaySize();
+    this.displayCols = cols;
+    this.displayRows = rows;
+    this.offsetCol = offsetCol;
+    this.offsetRow = offsetRow;
+
+    // Internal buffer uses render scale (round to ensure integer dimensions)
+    this.scaledWidth = Math.max(1, Math.round(this.sourceWidth * this.scale));
+    this.scaledHeight = Math.max(1, Math.round(this.sourceHeight * this.scale));
+
+    // Allocate buffers: native resolution for post-processing, scaled for output
+    this.nativeRgbBuffer = new Uint8Array(this.sourceWidth * this.sourceHeight * RGB24_BYTES_PER_PIXEL);
+    this.scaledRgbBuffer = new Uint8Array(this.scaledWidth * this.scaledHeight * RGB24_BYTES_PER_PIXEL);
+    this.scaledRowBuffer = new Uint8Array(this.scaledWidth * RGB24_BYTES_PER_PIXEL);
+
+    // Initialize debug log
+    if (DEBUG_KITTY) {
+      writeFileSync(DEBUG_LOG_PATH, `=== Kitty Debug Log Started ===\n`);
+      debugLog(`Init: sourceSize=${this.sourceWidth}x${this.sourceHeight}, scale=${this.scale}, scaledSize=${this.scaledWidth}x${this.scaledHeight}`);
+      debugLog(`Init: displayCols=${this.displayCols}, displayRows=${this.displayRows}, colorSpace=${this.colorSpace}`);
+      debugLog(`Init: pngCompression=${this.pngCompressionLevel}, diffRendering=${this.enableDiffRendering}`);
+    }
+  }
+
+  // Cleanup method (no-op, kept for API compatibility)
+  destroy(): void {
+    debugLog(`Destroy: frameNumber=${this.frameNumber}`);
+  }
+
+  // Calculate display size to fill terminal while maintaining aspect ratio
+  // Kitty handles scaling from internal buffer to display size
+  private calculateDisplaySize(): { cols: number; rows: number; offsetCol: number; offsetRow: number } {
+    const { width: termCols, height: termRows } = getTerminalDimensions();
+
+    const availableRows = termRows - STATUS_LINE_ROWS;
+    const availableCols = termCols;
+
+    // Formula: cols = rows * (sourceWidth * PAR) / sourceHeight * (cellHeight / cellWidth)
+    // For NES (256x240, 8:7 PAR): cols ≈ rows * 2.438
+    // For GBC (160x144, 1:1 PAR): cols ≈ rows * 2.222
+    const aspectRatio = (this.sourceWidth * this.pixelAspectRatio * CELL_HEIGHT_PX) / (this.sourceHeight * CELL_WIDTH_PX);
+
+    const { width: displayCols, height: displayRows } = fitToTerminal({
+      availableCols,
+      availableRows,
+      aspectRatio,
+    });
+
+    // Calculate centering offsets (1-based for ANSI escape sequences)
+    const offsetCol = Math.max(1, Math.floor((termCols - displayCols) / 2) + 1);
+    const offsetRow = Math.max(1, Math.floor((availableRows - displayRows) / 2) + 1);
+
+    return { cols: displayCols, rows: displayRows, offsetCol, offsetRow };
+  }
+
+  // Get current scale (useful for display info)
+  getScale(): number {
+    return this.scale;
+  }
+
+  // Get display dimensions
+  getDisplaySize(): { cols: number; rows: number } {
+    return { cols: this.displayCols, rows: this.displayRows };
+  }
+
+  // Update display dimensions (for terminal resize handling)
+  // Internal buffer scale stays fixed, only display size changes
+  setDimensions(): void {
+    const { cols, rows, offsetCol, offsetRow } = this.calculateDisplaySize();
+    this.displayCols = cols;
+    this.displayRows = rows;
+    this.offsetCol = offsetCol;
+    this.offsetRow = offsetRow;
+  }
+
+  // Generic frame comparison - check if entire frame is unchanged
+  private isFrameUnchanged(frameBuffer: Uint8Array | Uint16Array): boolean {
+    const prev = this.prevFrameBuffer;
+    const len = frameBuffer.length;
+    for (let i = 0; i < len; i++) {
+      if (frameBuffer[i] !== prev[i]) {return false;}
+    }
+    return true;
+  }
+
+  // Convert frame to RGB at native resolution (no scaling)
+  // Handles all color spaces: rgb15, rgb24
+  private frameToRgbNative(
+    frameBuffer: FrameBuffer,
+    colorSpace: ColorSpace
+  ): void {
+    const dst = this.nativeRgbBuffer;
+    const gammaLUT = this.gammaLUT;
+    const colorEnabled = this.colorEnabled;
+    const width = this.sourceWidth;
+    const height = this.sourceHeight;
+
+    for (let y = 0; y < height; y++) {
+      const srcRowStart = colorSpace === 'rgb24'
+        ? y * width * RGB24_BYTES_PER_PIXEL
+        : y * width;
+      const dstRowStart = y * width * RGB24_BYTES_PER_PIXEL;
+
+      for (let x = 0; x < width; x++) {
+        let r: number, g: number, b: number;
+
+        if (isRgb15Buffer(colorSpace, frameBuffer)) {
+          // RGB15: XBBBBBGGGGGRRRRR (5 bits per channel)
+          const color = frameBuffer[srcRowStart + x];
+          const [r8, g8, b8] = rgb15ToRgb24(color);
+          r = gammaLUT[r8];
+          g = gammaLUT[g8];
+          b = gammaLUT[b8];
+        } else {
+          // RGB24: direct 8-bit channels
+          const srcIdx = srcRowStart + x * RGB24_BYTES_PER_PIXEL;
+          r = gammaLUT[frameBuffer[srcIdx]];
+          g = gammaLUT[frameBuffer[srcIdx + 1]];
+          b = gammaLUT[frameBuffer[srcIdx + 2]];
+        }
+
+        // Convert to grayscale if color is disabled
+        const dstIdx = dstRowStart + x * RGB24_BYTES_PER_PIXEL;
+        if (!colorEnabled) {
+          const gray = calculateLuminance8(r, g, b);
+          dst[dstIdx] = gray;
+          dst[dstIdx + 1] = gray;
+          dst[dstIdx + 2] = gray;
+        } else {
+          dst[dstIdx] = r;
+          dst[dstIdx + 1] = g;
+          dst[dstIdx + 2] = b;
+        }
+      }
+    }
+  }
+
+  // Scale RGB buffer from native to display resolution
+  // Supports both upscaling (scale > 1) and downscaling (scale < 1)
+  private scaleRgbBuffer(): void {
+    const src = this.nativeRgbBuffer;
+    const dst = this.scaledRgbBuffer;
+    const scale = this.scale;
+    const srcWidth = this.sourceWidth;
+    const srcHeight = this.sourceHeight;
+    const dstWidth = this.scaledWidth;
+    const dstHeight = this.scaledHeight;
+
+    if (scale >= 1) {
+      // Upscaling: duplicate pixels (integer scale path)
+      const intScale = Math.round(scale);
+      const dstRowBytes = dstWidth * RGB24_BYTES_PER_PIXEL;
+      const rowBuffer = this.scaledRowBuffer;
+
+      for (let srcY = 0; srcY < srcHeight; srcY++) {
+        const srcRowStart = srcY * srcWidth * RGB24_BYTES_PER_PIXEL;
+
+        // Scale one source row horizontally into rowBuffer
+        let rowIdx = 0;
+        for (let srcX = 0; srcX < srcWidth; srcX++) {
+          const srcIdx = srcRowStart + srcX * RGB24_BYTES_PER_PIXEL;
+          const r = src[srcIdx];
+          const g = src[srcIdx + 1];
+          const b = src[srcIdx + 2];
+
+          // Write pixel 'scale' times horizontally
+          for (let sx = 0; sx < intScale; sx++) {
+            rowBuffer[rowIdx] = r;
+            rowBuffer[rowIdx + 1] = g;
+            rowBuffer[rowIdx + 2] = b;
+            rowIdx += RGB24_BYTES_PER_PIXEL;
+          }
+        }
+
+        // Copy the scaled row 'scale' times vertically
+        const dstRowStart = srcY * intScale * dstRowBytes;
+        for (let sy = 0; sy < intScale; sy++) {
+          dst.set(rowBuffer, dstRowStart + sy * dstRowBytes);
+        }
+      }
+    } else {
+      // Downscaling: sample pixels using nearest-neighbor
+      // For each destination pixel, find the corresponding source pixel
+      const invScale = 1 / scale;
+
+      for (let dstY = 0; dstY < dstHeight; dstY++) {
+        const srcY = Math.min(Math.floor(dstY * invScale), srcHeight - 1);
+        const srcRowStart = srcY * srcWidth * RGB24_BYTES_PER_PIXEL;
+        const dstRowStart = dstY * dstWidth * RGB24_BYTES_PER_PIXEL;
+
+        for (let dstX = 0; dstX < dstWidth; dstX++) {
+          const srcX = Math.min(Math.floor(dstX * invScale), srcWidth - 1);
+          const srcIdx = srcRowStart + srcX * RGB24_BYTES_PER_PIXEL;
+          const dstIdx = dstRowStart + dstX * RGB24_BYTES_PER_PIXEL;
+
+          dst[dstIdx] = src[srcIdx];
+          dst[dstIdx + 1] = src[srcIdx + 1];
+          dst[dstIdx + 2] = src[srcIdx + 2];
+        }
+      }
+    }
+  }
+
+  // Encode scaled RGB buffer to PNG format (indexed color with fallback to RGB)
+  private encodePng(): void {
+    const width = this.scaledWidth;
+    const height = this.scaledHeight;
+    const rgbData = this.scaledRgbBuffer;
+    const pixelCount = width * height;
+
+    // Build palette by scanning all pixels
+    // Use a Map with packed RGB as key for fast lookup
+    const colorToIndex = new Map<number, number>();
+    const palette: number[] = [];  // Flat RGB array
+    let fallbackToRgb = false;
+
+    // First pass: collect unique colors
+    for (let i = 0; i < pixelCount; i++) {
+      const idx = i * RGB24_BYTES_PER_PIXEL;
+      const r = rgbData[idx];
+      const g = rgbData[idx + 1];
+      const b = rgbData[idx + 2];
+      const packed = (r << PACK_RED_SHIFT) | (g << PACK_GREEN_SHIFT) | b;
+
+      if (!colorToIndex.has(packed)) {
+        if (palette.length >= PALETTE_BUFFER_SIZE) {
+          fallbackToRgb = true;
+          break;
+        }
+        colorToIndex.set(packed, palette.length / RGB24_BYTES_PER_PIXEL);
+        palette.push(r, g, b);
+      }
+    }
+
+    if (fallbackToRgb) {
+      // More than 256 colors - fall back to RGB encoding
+      this.encodePngRgb();
+      return;
+    }
+
+    // Second pass: build indexed pixel data
+    const rawDataSize = height * (1 + width);  // 1 filter byte + 1 byte per pixel per row
+    const rawData = Buffer.alloc(rawDataSize);
+
+    for (let y = 0; y < height; y++) {
+      const rawRowStart = y * (1 + width);
+      rawData[rawRowStart] = 0;  // Filter type: none
+
+      for (let x = 0; x < width; x++) {
+        const srcIdx = (y * width + x) * RGB24_BYTES_PER_PIXEL;
+        const r = rgbData[srcIdx];
+        const g = rgbData[srcIdx + 1];
+        const b = rgbData[srcIdx + 2];
+        const packed = (r << PACK_RED_SHIFT) | (g << PACK_GREEN_SHIFT) | b;
+        rawData[rawRowStart + 1 + x] = colorToIndex.get(packed)!;
+      }
+    }
+
+    const compressed = deflateSync(rawData, { level: this.pngCompressionLevel });
+
+    // Build IHDR
+    const ihdr = Buffer.alloc(PNG_IHDR_LENGTH);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, PNG_IHDR_HEIGHT_OFFSET);
+    ihdr[8] = PNG_BIT_DEPTH;  // bit depth
+    ihdr[9] = PNG_COLOR_TYPE_INDEXED;  // color type: indexed
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter
+    ihdr[12] = 0; // interlace
+
+    // Build PLTE chunk
+    const plteData = Buffer.from(palette);
+
+    const ihdrChunk = createPngChunk('IHDR', ihdr);
+    const plteChunk = createPngChunk('PLTE', plteData);
+    const idatChunk = createPngChunk('IDAT', compressed);
+    const iendChunk = createPngChunk('IEND', Buffer.alloc(0));
+
+    this.pngBuffer = Buffer.concat([PNG_SIGNATURE, ihdrChunk, plteChunk, idatChunk, iendChunk]);
+  }
+
+  // Fallback RGB encoding when palette exceeds 256 colors
+  private encodePngRgb(): void {
+    const width = this.scaledWidth;
+    const height = this.scaledHeight;
+    const rgbData = this.scaledRgbBuffer;
+
+    const rowBytes = width * RGB24_BYTES_PER_PIXEL;
+    const rawDataSize = height * (1 + rowBytes);
+    const rawData = Buffer.alloc(rawDataSize);
+
+    for (let y = 0; y < height; y++) {
+      const rawRowStart = y * (1 + rowBytes);
+      rawData[rawRowStart] = 0;  // Filter type: none
+      const srcStart = y * rowBytes;
+      for (let i = 0; i < rowBytes; i++) {
+        rawData[rawRowStart + 1 + i] = rgbData[srcStart + i];
+      }
+    }
+
+    const compressed = deflateSync(rawData, { level: this.pngCompressionLevel });
+
+    const ihdr = Buffer.alloc(PNG_IHDR_LENGTH);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, PNG_IHDR_HEIGHT_OFFSET);
+    ihdr[8] = PNG_BIT_DEPTH;  // bit depth
+    ihdr[9] = PNG_COLOR_TYPE_RGB;  // color type: RGB
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter
+    ihdr[12] = 0; // interlace
+
+    const ihdrChunk = createPngChunk('IHDR', ihdr);
+    const idatChunk = createPngChunk('IDAT', compressed);
+    const iendChunk = createPngChunk('IEND', Buffer.alloc(0));
+
+    this.pngBuffer = Buffer.concat([PNG_SIGNATURE, ihdrChunk, idatChunk, iendChunk]);
+  }
+
+  // Send image using Kitty graphics protocol with chunked transmission
+  private sendImage(): string {
+    // Encode to PNG (compressed)
+    this.encodePng();
+    const base64 = this.pngBuffer.toString('base64');
+    const chunks: string[] = [];
+
+    // Use large chunks to avoid crashes in some terminals (e.g., iTerm2)
+    // 4096 is Kitty's recommendation but causes issues with chunked transmission in some terminals
+    // Post-processing can create ~120KB+ base64, so use 256KB chunks
+    const chunkSize = KITTY_CHUNK_SIZE;
+
+    // Use alternating image IDs for double-buffering effect
+    const currentId = this.imageId + (this.frameNumber % 2);
+    const previousId = this.imageId + ((this.frameNumber + 1) % 2);
+
+    // Debug logging
+    const numChunks = Math.ceil(base64.length / chunkSize);
+    debugLog(`Frame ${this.frameNumber}: imageId=${currentId}, prevId=${previousId}, pngBytes=${this.pngBuffer.length}, base64Len=${base64.length}, chunks=${numChunks}`);
+
+    for (let i = 0; i < base64.length; i += chunkSize) {
+      const chunk = base64.slice(i, i + chunkSize);
+      const isFirst = i === 0;
+      const isLast = i + chunkSize >= base64.length;
+
+      let control: string;
+
+      if (isFirst) {
+        // First chunk: transmit image data
+        // a=T: transmit and display
+        // f=100: PNG format
+        // i=id: image ID
+        // p=1: placement ID (allows replacing in place)
+        // q=2: suppress response
+        // C=1: do not move cursor after displaying
+        // c=cols, r=rows: display size in terminal cells
+        // m=1: more chunks follow (0 if last)
+        const displayParams = `,c=${this.displayCols},r=${this.displayRows}`;
+        control = `a=T,f=100,i=${currentId},p=1,q=2,C=1${displayParams},m=${isLast ? 0 : 1}`;
+        debugLog(`Frame ${this.frameNumber}: SEND control="${control}"`);
+      } else {
+        // Subsequent chunks: just continuation
+        control = `m=${isLast ? 0 : 1}`;
+      }
+
+      chunks.push(`${APC}${control};${chunk}${ST}`);
+    }
+
+    // Delete previous frame's image after displaying new one
+    if (this.frameNumber > 0) {
+      debugLog(`Frame ${this.frameNumber}: DELETE imageId=${previousId}`);
+      chunks.push(`${APC}a=d,d=I,i=${previousId},q=2${ST}`);
+    }
+
+    this.frameNumber++;
+
+    return chunks.join('');
+  }
+
+  // Unified render method for all color spaces
+  private renderInternal(
+    frameBuffer: FrameBuffer,
+    colorSpace: ColorSpace
+  ): string {
+    // Check if frame buffer size changed (can happen with SNES resolution changes)
+    // If so, reallocate prevFrameBuffer to match
+    if (frameBuffer.length !== this.prevFrameBuffer.length) {
+      if (frameBuffer instanceof Uint16Array) {
+        this.prevFrameBuffer = new Uint16Array(frameBuffer.length);
+      } else {
+        this.prevFrameBuffer = new Uint8Array(frameBuffer.length);
+      }
+    }
+
+    // Force full rendering for initial frames to ensure display is populated
+    const isInitialFrame = this.frameNumber < INITIAL_FULL_RENDER_FRAMES;
+
+    // Periodic memory logging (every 60 frames ≈ 1 second)
+    if (DEBUG_KITTY && this.frameNumber % MEMORY_LOG_INTERVAL === 0) {
+      const mem = process.memoryUsage();
+      debugLog(`Memory @ frame ${this.frameNumber}: heapUsed=${Math.round(mem.heapUsed / BYTES_PER_KB / BYTES_PER_KB)}MB, heapTotal=${Math.round(mem.heapTotal / BYTES_PER_KB / BYTES_PER_KB)}MB, rss=${Math.round(mem.rss / BYTES_PER_KB / BYTES_PER_KB)}MB`);
+    }
+
+    // Skip entirely if frame unchanged (after initial frames)
+    if (this.enableDiffRendering && !isInitialFrame && this.isFrameUnchanged(frameBuffer)) {
+      debugLog(`Frame ${this.frameNumber}: SKIPPED (unchanged)`);
+      return '';
+    }
+
+    // Convert frame to RGB at native resolution
+    this.frameToRgbNative(frameBuffer, colorSpace);
+
+    // Save current frame for next frame's diff check
+    this.prevFrameBuffer.set(frameBuffer);
+
+    // Apply post-processing effects at native resolution (much faster than scaled)
+    this.postProcessing.apply(this.nativeRgbBuffer, this.sourceWidth, this.sourceHeight);
+
+    // Scale up to display resolution
+    this.scaleRgbBuffer();
+
+    // Build output
+    let output = '';
+
+    // Move cursor to centered position for image placement
+    output += moveCursor(this.offsetRow, this.offsetCol);
+
+    // Always use PNG - compression helps with terminal I/O even for dynamic frames
+    output += this.sendImage();
+
+    return output;
+  }
+
+  // Render RGB15 frame buffer to Kitty graphics
+  renderRgb15(frameBuffer: Uint16Array): string {
+    return this.renderInternal(frameBuffer, 'rgb15');
+  }
+
+  // Render RGB24 frame buffer to Kitty graphics
+  renderRgb24(frameBuffer: Uint8Array): string {
+    return this.renderInternal(frameBuffer, 'rgb24');
+  }
+
+  // Clear screen
+  clearScreen(): string {
+    // Delete all images and clear screen
+    return `${APC}a=d,d=A,q=2${ST}${clearScreen()}`;
+  }
+
+  // Hide cursor
+  hideCursor(): string {
+    return hideCursor();
+  }
+
+  // Show cursor
+  showCursor(): string {
+    return showCursor();
+  }
+
+  // Get status row (below the image)
+  getStatusRow(): number {
+    // We know exactly how many rows the image uses from displayRows
+    // Account for vertical centering offset
+    return this.offsetRow + this.displayRows;
+  }
+
+  // Move cursor to status row
+  moveCursorToRow(row: number): string {
+    return moveCursor(row, 1) + clearLine();
+  }
+}