media/render/terminal.c

Go to the documentation of this file.

#include <ascii-chat/util/time.h>
 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define RENDER_DEBUG_SIGNATURE_ROWS 52
#define RENDER_DEBUG_SIGNATURE_COLUMNS 4
#define RENDER_DEBUG_SIGNATURE_BUFFER_SIZE (RENDER_DEBUG_SIGNATURE_COLUMNS + 1)
 
#include <ascii-chat/video/ascii/common.h>
#include <ascii-chat/video/anim/digital_rain.h>
#include <ascii-chat/media/render/renderer.h>
#include <ascii-chat/os/memory.h>
#include <libplatform/terminal.h>
#include <ascii-chat/log/log.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/uthash.h>
#include <ascii-chat/font.h>
#include <ascii-chat/video/ascii/zalgo.h>
#include <vterm.h>
#include <ft2build.h>
#include FT_FREETYPE_H
#include FT_GLYPH_H
#include FT_FONT_FORMATS_H
#include FT_TRUETYPE_TABLES_H
#include <string.h>
#include <stddef.h>
#include <stdint.h>
#include <limits.h>
 
// ============================================================================
// Glyph Cache
// ============================================================================

typedef struct {
  uint32_t codepoint;  // Hash key (character code)
  uint8_t *bitmap_buf; // Normalized 8-bit alpha bitmap
  int width;           // Bitmap dimensions (in pixels)
  int rows;            // Bitmap height (in rows)
  int pitch;           // Bytes per row
  int bitmap_left;     // Glyph positioning offsets
  int bitmap_top;
  UT_hash_handle hh; // uthash handle
} glyph_cache_entry_t;

static void glyph_cache_destroy(glyph_cache_entry_t **cache) {
  glyph_cache_entry_t *curr, *tmp;
  HASH_ITER(hh, *cache, curr, tmp) {
    HASH_DEL(*cache, curr);
    SAFE_FREE(curr->bitmap_buf);
    SAFE_FREE(curr);
  }
}
 
// Cache complete cells so repeated glyph/color combinations need only row copies.
#define CELL_CACHE_SIZE 512
typedef struct {
  uint32_t character, foreground, background;
  uint8_t *pixels;
  bool valid;
} rendered_cell_t;
 
struct terminal_renderer_s {
  rendered_cell_t cells[CELL_CACHE_SIZE];
  VTerm *vt;
  VTermScreen *vts;
  int cols, rows;
  FT_Library ft_lib;
  FT_Face ft_face;
  FT_Face zalgo_face;
  int zalgo_level;
  glyph_cache_entry_t *zalgo_cache;
  int cell_w, cell_h, baseline;
  uint8_t *framebuffer;
  int width_px, height_px, pitch;
  term_renderer_theme_t theme;
  bool is_matrix_font;
  glyph_cache_entry_t *glyph_cache; // Per-renderer glyph cache (per-font)
};

static FT_Bitmap *glyph_cache_get(terminal_renderer_t *r, FT_Face face, uint32_t codepoint) {
  glyph_cache_entry_t *entry = NULL;
 
  // Lookup in renderer's per-font cache
  HASH_FIND_INT(r->glyph_cache, &codepoint, entry);
  if (entry) {
    // Return cached bitmap
    static FT_Bitmap cached_result;
    cached_result.width = entry->width;
    cached_result.rows = entry->rows;
    cached_result.pitch = entry->pitch;
    cached_result.buffer = entry->bitmap_buf;
    return &cached_result;
  }
 
  // Not in cache — load and render glyph
  FT_UInt gi = FT_Get_Char_Index(face, codepoint);
  if (!gi || FT_Load_Glyph(face, gi, FT_LOAD_RENDER) != 0) {
    return NULL; // Glyph not found or load failed
  }
 
  FT_Bitmap *src_bitmap = &face->glyph->bitmap;
  if (!src_bitmap->buffer || src_bitmap->width == 0 || src_bitmap->rows == 0 || src_bitmap->width > INT_MAX ||
      src_bitmap->rows > INT_MAX) {
    return NULL;
  }
 
  // FreeType bitmaps may use packed mono/gray pixels and either pitch
  // direction. Normalize them once so blit_glyph can safely read one alpha
  // byte per pixel for every cached glyph.
  int64_t signed_pitch = src_bitmap->pitch;
  size_t source_pitch = (size_t)(signed_pitch < 0 ? -signed_pitch : signed_pitch);
  size_t minimum_source_pitch = 0;
  switch (src_bitmap->pixel_mode) {
  case FT_PIXEL_MODE_MONO:
    minimum_source_pitch = ((size_t)src_bitmap->width + 7) / 8;
    break;
  case FT_PIXEL_MODE_GRAY2:
    minimum_source_pitch = ((size_t)src_bitmap->width + 3) / 4;
    break;
  case FT_PIXEL_MODE_GRAY4:
    minimum_source_pitch = ((size_t)src_bitmap->width + 1) / 2;
    break;
  case FT_PIXEL_MODE_GRAY:
    minimum_source_pitch = src_bitmap->width;
    break;
  case FT_PIXEL_MODE_BGRA:
    minimum_source_pitch = (size_t)src_bitmap->width * 4;
    break;
  default:
    return NULL;
  }
  if (source_pitch == 0 || source_pitch < minimum_source_pitch || src_bitmap->rows > SIZE_MAX / source_pitch ||
      src_bitmap->rows > SIZE_MAX / (size_t)src_bitmap->width) {
    return NULL;
  }
 
  size_t bitmap_size = (size_t)src_bitmap->width * src_bitmap->rows;
 
  // Create and populate cache entry
  entry = SAFE_MALLOC(sizeof(glyph_cache_entry_t), glyph_cache_entry_t *);
  if (!entry) {
    return NULL;
  }
 
  entry->codepoint = codepoint;
  entry->bitmap_buf = SAFE_MALLOC(bitmap_size, uint8_t *);
  if (!entry->bitmap_buf) {
    SAFE_FREE(entry);
    return NULL;
  }
 
  for (unsigned row = 0; row < src_bitmap->rows; row++) {
    unsigned source_row = signed_pitch < 0 ? src_bitmap->rows - row - 1 : row;
    const uint8_t *source = src_bitmap->buffer + (size_t)source_row * source_pitch;
    uint8_t *destination = entry->bitmap_buf + (size_t)row * src_bitmap->width;
    for (unsigned col = 0; col < src_bitmap->width; col++) {
      switch (src_bitmap->pixel_mode) {
      case FT_PIXEL_MODE_MONO:
        destination[col] = (source[col / 8] & (0x80U >> (col % 8))) ? 255 : 0;
        break;
      case FT_PIXEL_MODE_GRAY2:
        destination[col] = (uint8_t)(((source[col / 4] >> (6 - (col % 4) * 2)) & 0x03U) * 85U);
        break;
      case FT_PIXEL_MODE_GRAY4:
        destination[col] = (uint8_t)(((source[col / 2] >> (col % 2 == 0 ? 4 : 0)) & 0x0fU) * 17U);
        break;
      case FT_PIXEL_MODE_GRAY:
        destination[col] = src_bitmap->num_grays > 1 && src_bitmap->num_grays != 256
                               ? (uint8_t)((source[col] * 255U) / (src_bitmap->num_grays - 1))
                               : source[col];
        break;
      case FT_PIXEL_MODE_BGRA:
        destination[col] = source[col * 4 + 3];
        break;
      default:
        break;
      }
    }
  }
  entry->width = src_bitmap->width;
  entry->rows = src_bitmap->rows;
  entry->pitch = (int)src_bitmap->width;
  entry->bitmap_left = face->glyph->bitmap_left;
  entry->bitmap_top = face->glyph->bitmap_top;
 
  // Add to renderer's per-font hash table
  HASH_ADD_INT(r->glyph_cache, codepoint, entry);
 
  // Return the cached bitmap
  static FT_Bitmap new_result;
  new_result.width = entry->width;
  new_result.rows = entry->rows;
  new_result.pitch = entry->pitch;
  new_result.buffer = entry->bitmap_buf;
  return &new_result;
}
 
static int screen_damage(VTermRect r, void *u) {
  (void)r;
  (void)u;
  return 1;
}
 
static VTermScreenCallbacks g_vterm_cbs = {.damage = screen_damage};

static uint32_t matrix_char_map(uint32_t ascii_char) {
  // Matrix font glyphs: U+E900 to U+E91A (27 glyphs total)
  const uint32_t matrix_start = 0xE900;
  const uint32_t matrix_count = 27;
 
  // If it's already in the PUA range, return as-is
  if (ascii_char >= 0xE900 && ascii_char <= 0xE91A) {
    return ascii_char;
  }
 
  // Map printable ASCII (32-126) to matrix glyphs
  if (ascii_char >= 32 && ascii_char <= 126) {
    // Cycle through available glyphs
    // Coverage order measured from the bundled Matrix-Resurrected font at 10px.
    // Adjacent alternatives preserve image shading when the rain mutates symbols.
    static const uint8_t glyphs[6][4] = {{15, 18, 19, 15}, {20, 1, 26, 25}, {23, 0, 3, 13},
                                         {12, 16, 24, 17}, {9, 4, 22, 21},  {2, 11, 14, 5}};
    int group = digital_rain_glyph_group(ascii_char);
    if (group >= 0)
      return matrix_start + glyphs[group][ascii_char % 4];
    return matrix_start + (ascii_char - 32) % matrix_count;
  }
 
  // Return unmapped characters as-is (will have no glyph)
  return ascii_char;
}

static void blit_glyph(terminal_renderer_t *r, FT_Bitmap *bm, int px, int py, uint8_t fr, uint8_t fg, uint8_t fb,
                       uint8_t br, uint8_t bg, uint8_t bb) {
  // Clip once, outside the pixel loop, so WASM can vectorize alpha blending.
  int first_col = px < 0 ? -px : 0;
  int last_col = (int)bm->width;
  if (px + last_col > r->width_px)
    last_col = r->width_px - px;
  int first_row = py < 0 ? -py : 0;
  int last_row = (int)bm->rows;
  if (py + last_row > r->height_px)
    last_row = r->height_px - py;
  if (first_col >= last_col || first_row >= last_row)
    return;
  for (int row = first_row; row < last_row; row++) {
    const uint8_t *alpha = bm->buffer + row * bm->pitch + first_col;
    uint8_t *line = r->framebuffer + (py + row) * r->pitch + (px + first_col) * 4;
    for (int col = 0; col < last_col - first_col; col++) {
      unsigned a = alpha[col];
      if (r->is_matrix_font && fr > 64 && fg > 64 && fb > 64 && (fr > 200 || fg > 200 || fb > 200)) {
        // A small local bloom softens pale rain heads without blurring the body.
        int x = first_col + col;
        unsigned glow = 0;
        if (x > 0)
          glow += bm->buffer[row * bm->pitch + x - 1];
        if (x + 1 < (int)bm->width)
          glow += bm->buffer[row * bm->pitch + x + 1];
        if (row > 0)
          glow += bm->buffer[(row - 1) * bm->pitch + x];
        if (row + 1 < (int)bm->rows)
          glow += bm->buffer[(row + 1) * bm->pitch + x];
        a += (255 - a) * glow / (255 * 24);
      }
      uint8_t *dst = line + col * 4;
      dst[0] = (uint8_t)((fr * a + br * (255 - a)) / 255);
      dst[1] = (uint8_t)((fg * a + bg * (255 - a)) / 255);
      dst[2] = (uint8_t)((fb * a + bb * (255 - a)) / 255);
      dst[3] = 255;
    }
  }
}
 
asciichat_error_t term_renderer_create(const term_renderer_config_t *cfg, terminal_renderer_t **out) {
  if (!cfg || !out || cfg->cols <= 0 || cfg->rows <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing font renderer configuration or output");
  *out = NULL;
  if (cfg->font_data_size > LONG_MAX || (cfg->font_data_size && !cfg->font_data))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font data or size");
  terminal_renderer_t *r = SAFE_CALLOC(1, sizeof(*r), terminal_renderer_t *);
  r->cols = cfg->cols;
  r->rows = cfg->rows;
  r->theme = cfg->theme;
 
  if (FT_Init_FreeType(&r->ft_lib)) {
    SAFE_FREE(r);
    return SET_ERRNO(ERROR_INIT, "FreeType init failed");
  }
 
  FT_Error face_error;
  if (cfg->font_data && cfg->font_data_size > 0) {
    face_error = FT_New_Memory_Face(r->ft_lib, cfg->font_data, (FT_Long)cfg->font_data_size, 0, &r->ft_face);
  } else {
    face_error = FT_New_Face(r->ft_lib, cfg->font_spec, 0, &r->ft_face);
  }
  if (face_error) {
    FT_Done_FreeType(r->ft_lib);
    SAFE_FREE(r);
    if (face_error == FT_Err_Cannot_Open_Resource)
      return SET_ERRNO(ERROR_NOT_FOUND, "Cannot open font '%s' (FreeType error %d)", cfg->font_spec, face_error);
    // Older FreeType versions recognize an HVF SFNT wrapper, then reject its
    // missing TrueType outline tables instead of reporting an unknown format.
    if (face_error == FT_Err_Unknown_File_Format || face_error == FT_Err_Unimplemented_Feature ||
        face_error == FT_Err_Locations_Missing)
      return SET_ERRNO(ERROR_NOT_SUPPORTED,
                       "Unsupported font format: '%s' (FreeType error %d). HVF fonts require HVF-enabled FreeType "
                       "2.15+ on macOS 15.4+ or iOS 18.4+",
                       cfg->font_spec, face_error);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid font '%s' (FreeType error %d)", cfg->font_spec, face_error);
  }
 
  // Some older FreeType drivers can open an SFNT container without supporting
  // its outlines. Check the parsed table directory before accepting that face.
  FT_ULong hvf_size = 0;
  bool is_hvf = FT_IS_SFNT(r->ft_face) &&
                FT_Load_Sfnt_Table(r->ft_face, FT_MAKE_TAG('h', 'v', 'g', 'l'), 0, NULL, &hvf_size) == 0;
  const char *font_format = FT_Get_Font_Format(r->ft_face);
  if (is_hvf) {
    bool supported = false;
#ifdef __APPLE__
    if (__builtin_available(macOS 15.4, iOS 18.4, *))
      supported = font_format && strcmp(font_format, "HVF") == 0;
#endif
    if (!supported) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED,
                       "Unsupported HVF font '%s': requires HVF-enabled FreeType 2.15+ on macOS 15.4+ or iOS 18.4+",
                       cfg->font_spec);
    }
  }
  log_debug("Loaded font '%s' using FreeType format %s", cfg->font_spec, font_format ? font_format : "unknown");
 
  // Detect if this is the matrix font (needs character mapping to Private Use Area)
  r->is_matrix_font = (strstr(cfg->font_spec, "matrix") != NULL || strstr(cfg->font_spec, "Matrix") != NULL) ||
                      (cfg->font_data != NULL && GET_OPTION(matrix_rain));
  if (r->is_matrix_font) {
    log_debug("Detected matrix font - will use Private Use Area character mapping");
  }
 
  // Handle scalable vs bitmap fonts differently
  // Bitmap fonts (like matrix) don't respond to FT_Set_Char_Size
  // Instead, use FT_Set_Pixel_Sizes to request a specific pixel size
  if (r->ft_face->num_fixed_sizes > 0) {
    // Bitmap font: use FT_Set_Pixel_Sizes to select appropriate size (12px is reasonable for ASCII)
    int err = FT_Set_Pixel_Sizes(r->ft_face, 12, 12);
    log_debug("[BITMAP] FT_Set_Pixel_Sizes(12, 12) returned %d", err);
 
    // If that fails, try FT_Select_Size as fallback
    if (err != 0) {
      err = FT_Select_Size(r->ft_face, 0); // Use first available strike
      log_debug("[BITMAP FALLBACK] FT_Select_Size(0) returned %d", err);
    }
    if (err != 0) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' has no usable bitmap size (FreeType error %d)", cfg->font_spec,
                       err);
    }
  } else {
    // Scalable font: use FT_Set_Char_Size
    // FT_Set_Char_Size takes 1/64pt units and DPI — supports fractional point sizes.
    // 96 DPI is the standard screen DPI used here; the 64 factor is the 26.6 fixed-point scale.
    int err = FT_Set_Char_Size(r->ft_face, 0, (FT_F26Dot6)(cfg->font_size_pt * 64.0), 96, 96);
    log_debug("[SCALABLE] FT_Set_Char_Size(size_pt=%.1f → %ld 1/64pt) returned %d", cfg->font_size_pt,
              (long)(cfg->font_size_pt * 64.0), err);
    if (err != 0) {
      FT_Done_Face(r->ft_face);
      FT_Done_FreeType(r->ft_lib);
      SAFE_FREE(r);
      return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot be sized (FreeType error %d)", cfg->font_spec, err);
    }
  }
 
  // For matrix fonts, try PUA glyph first (U+E900) since ASCII chars might not have bitmap data
  // For other fonts, start with 'M'
  int load_err;
  if (r->is_matrix_font) {
    log_debug("Matrix font detected: trying PUA glyph U+E900 first");
    load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
    log_debug("FT_Load_Char(U+E900) returned %d", load_err);
 
    // If PUA glyph fails, try ASCII fallback
    if (load_err != 0) {
      log_debug("U+E900 failed, trying fallback character 'M'");
      load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
      log_debug("FT_Load_Char('M') returned %d", load_err);
    }
  } else {
    // For non-matrix fonts, standard approach
    load_err = FT_Load_Char(r->ft_face, 'M', FT_LOAD_RENDER);
    log_debug("FT_Load_Char('M', FT_LOAD_RENDER) returned %d", load_err);
 
    // For bitmap fonts (like matrix), FT_Load_Char may fail if the character doesn't exist.
    // Try a fallback character if 'M' fails.
    if (load_err != 0 && r->ft_face->num_fixed_sizes > 0) {
      log_debug("FT_Load_Char('M') failed for bitmap font, trying fallback character 'A'");
      load_err = FT_Load_Char(r->ft_face, 'A', FT_LOAD_RENDER);
      log_debug("FT_Load_Char('A') returned %d", load_err);
 
      if (load_err != 0) {
        // Last resort: try a PUA glyph for unknown bitmap fonts
        log_debug("FT_Load_Char('A') also failed, trying PUA glyph U+E900");
        load_err = FT_Load_Char(r->ft_face, 0xE900, FT_LOAD_RENDER);
        log_debug("FT_Load_Char(U+E900) returned %d", load_err);
      }
    }
  }
 
  if (load_err != 0) {
    FT_Done_Face(r->ft_face);
    FT_Done_FreeType(r->ft_lib);
    SAFE_FREE(r);
    return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font '%s' cannot render glyphs (FreeType error %d)", cfg->font_spec,
                     load_err);
  }
 
  // For monospace ASCII grid: use advance.x (proper character spacing) and rendered height
  FT_Pos advance_x_26_6 = r->ft_face->glyph->advance.x;
  log_debug("advance.x (26.6pt)=%ld", advance_x_26_6);
 
  // Calculate cell width from font metrics
  r->cell_w = (int)(advance_x_26_6 >> 6);
 
  // Safeguard: for bitmap fonts, cell_w might be wrong if the font metrics are off
  // Ensure we have a reasonable minimum width
  if (r->cell_w <= 0) {
    log_warn("cell_w is %d (invalid), using default 10px", r->cell_w);
    r->cell_w = 10;
  }
 
  // Only add spacing to fill entire frame if --stretch is specified
  bool stretch_mode = GET_OPTION(stretch);
  if (stretch_mode) {
    r->cell_w++;
    log_debug("ADVANCE_X: value=%ld (26.6pt) → cell_w=%d (advance + 1 for stretch), cols=%d → width_px=%d",
              advance_x_26_6, r->cell_w, r->cols, r->cols * r->cell_w);
  } else {
    log_debug("ADVANCE_X: value=%ld (26.6pt) → cell_w=%d (preserve aspect ratio), cols=%d → width_px=%d",
              advance_x_26_6, r->cell_w, r->cols, r->cols * r->cell_w);
  }
 
  // For both bitmap and scalable fonts, use the actual glyph bitmap height
  // This ensures text doesn't overflow cells. Using size->metrics.height (line spacing)
  // instead of bitmap.rows causes cells to be too large and text to overflow.
  r->cell_h = r->ft_face->glyph->bitmap.rows;
  int raw_bitmap_top = r->ft_face->glyph->bitmap_top;
  log_debug("cell_h=%d (from bitmap.rows), raw_bitmap_top=%d", r->cell_h, raw_bitmap_top);
 
  // Fallback: if cell_h is 0 (bitmap failed to load), use aspect ratio calculation
  if (r->cell_h <= 0) {
    log_warn("cell_h is 0 (FT_Load_Char failed or no bitmap), using aspect ratio fallback");
    r->cell_h = r->cell_w * 2;
    log_debug("FALLBACK: cell_h set to %d (2x width=%d)", r->cell_h, r->cell_w);
  }
 
  // Apply aspect ratio correction unless --stretch is specified
  // Terminal characters are typically 2:1 (height:width) to appear normal
  // BUT: only correct if the loaded glyph height is reasonably close (±30%)
  // This prevents huge jumps from small glyphs (e.g., 8px → 32px)
  if (!stretch_mode && r->cell_h > 0) {
    int corrected_h = r->cell_w * 2;
    int min_acceptable = (corrected_h * 70) / 100;  // 70% of target
    int max_acceptable = (corrected_h * 130) / 100; // 130% of target
 
    if (r->cell_h < min_acceptable || r->cell_h > max_acceptable) {
      // Loaded height is far from expected, apply correction
      log_debug("ASPECT_RATIO: Correcting cell_h from %d to %d (out of range [%d,%d], 2x width=%d)", r->cell_h,
                corrected_h, min_acceptable, max_acceptable, r->cell_w);
      r->cell_h = corrected_h;
    } else if (corrected_h != r->cell_h) {
      // Loaded height is close to expected, fine-tune by small amount only
      int delta = corrected_h - r->cell_h;
      if (delta > 4 || delta < -4) {
        // Only apply if difference is more than 4px
        log_debug("ASPECT_RATIO: Fine-tuning cell_h from %d to %d (within acceptable range, 2x width=%d)", r->cell_h,
                  corrected_h, r->cell_w);
        r->cell_h = corrected_h;
      } else {
        log_debug("ASPECT_RATIO: Keeping cell_h=%d (close to target %d, delta=%d)", r->cell_h, corrected_h, delta);
      }
    }
  }
 
  // Position baseline vertically within the cell.
  // Baseline should be positioned at approximately 75% of cell height to allow proper
  // glyph rendering with space both above and below. This prevents glyphs from being
  // clipped at the cell boundaries.
  //
  // Baseline position: y_glyph = py + r->baseline - g->bitmap_top
  // We want: 0 <= baseline - bitmap_top < cell_h (glyph fits within cell)
  // Choose: baseline = (3 * cell_h) / 4 (positions at 75% height)
  r->baseline = (3 * r->cell_h) / 4;
  log_debug("baseline set to %d (75%% of cell_h=%d)", r->baseline, r->cell_h);
 
  r->width_px = r->cols * r->cell_w;
  r->height_px = r->rows * r->cell_h;
  log_debug("calculated dimensions: width_px=%d (cols=%d * cell_w=%d), height_px=%d (rows=%d * cell_h=%d)", r->width_px,
            r->cols, r->cell_w, r->height_px, r->rows, r->cell_h);
  // Pitch in bytes: each pixel is 4 bytes (RGBA), already aligned to 4-byte boundary
  int base_pitch = r->width_px * 4;
  r->pitch = base_pitch;
  log_debug("PITCH_CALC: width_px=%d, base_pitch=%d, final_pitch=%d (RGBA, no padding needed)", r->width_px, base_pitch,
            r->pitch);
  log_debug("Allocating framebuffer: %d bytes total (%d pitch * %d height)", (int)((size_t)r->pitch * r->height_px),
            r->pitch, r->height_px);
  r->framebuffer = SAFE_MALLOC((size_t)r->pitch * r->height_px, uint8_t *);
 
  r->vt = vterm_new(r->rows, r->cols);
  r->vts = vterm_obtain_screen(r->vt);
 
  // Enable UTF-8 encoding so vterm correctly parses multi-byte characters
  vterm_set_utf8(r->vt, 1);
 
  // Set size BEFORE reset to ensure screen is allocated with correct dimensions
  vterm_set_size(r->vt, r->rows, r->cols);
  log_debug("vterm_set_size called with rows=%d cols=%d", r->rows, r->cols);
 
  vterm_screen_set_callbacks(r->vts, &g_vterm_cbs, r);
  // Reset MUST come before any input writing to initialize state correctly
  vterm_screen_reset(r->vts, 1);
 
  // Verify the size was set correctly after reset
  int vt_rows, vt_cols;
  vterm_get_size(r->vt, &vt_rows, &vt_cols);
  log_debug("vterm_get_size returned rows=%d cols=%d (expected %d,%d)", vt_rows, vt_cols, r->rows, r->cols);
 
  // CRITICAL: Set size AGAIN after reset, as reset may have affected it
  vterm_set_size(r->vt, r->rows, r->cols);
  log_debug("vterm_set_size called AGAIN after reset");
 
  // Initialize per-renderer glyph cache (empty, will populate on demand)
  r->glyph_cache = NULL;
 
  *out = r;
  return ASCIICHAT_OK;
}
 
asciichat_error_t term_renderer_set_zalgo(terminal_renderer_t *r, int level) {
  if (!r || level < 0 || level > 10)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Zalgo raster level must be 0-10");
  if (level && !r->zalgo_face) {
    if (FT_New_Memory_Face(r->ft_lib, g_font_default, (FT_Long)g_font_default_size, 0, &r->zalgo_face))
      return SET_ERRNO(ERROR_INIT, "Cannot load Zalgo combining font");
    if (FT_Set_Pixel_Sizes(r->zalgo_face, 0, (FT_UInt)(r->cell_w * 2))) {
      FT_Done_Face(r->zalgo_face);
      r->zalgo_face = NULL;
      return SET_ERRNO(ERROR_INIT, "Cannot size Zalgo combining font");
    }
  }
  r->zalgo_level = level;
  return ASCIICHAT_OK;
}

static void render_zalgo(terminal_renderer_t *r, int offset_x, int offset_y) {
  if (!r->zalgo_level)
    return;
  // Reuse the glyph cache machinery with a separate cache for the combining font.
  glyph_cache_entry_t *base_cache = r->glyph_cache;
  r->glyph_cache = r->zalgo_cache;
  for (int row = 0; row < r->rows; row++) {
    for (int col = 0; col < r->cols; col++) {
      VTermScreenCell cell;
      vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
      if (cell.chars[0] <= ' ' || cell.chars[0] >= 0x7f)
        continue;
      uint16_t marks[ZALGO_MAX_MARKS];
      unsigned count = zalgo_cell_marks((uint32_t)row, (uint32_t)col, r->zalgo_level, marks);
      VTermColor color = cell.fg;
      vterm_screen_convert_color_to_rgb(r->vts, &color);
      int above = 0, below = 0;
      for (unsigned i = 0; i < count; i++) {
        uint32_t cp = marks[i];
        FT_Bitmap *bitmap = glyph_cache_get(r, r->zalgo_face, cp);
        glyph_cache_entry_t *entry = NULL;
        HASH_FIND_INT(r->glyph_cache, &cp, entry);
        if (!bitmap || !entry)
          continue;
        int x = offset_x + col * r->cell_w + (r->cell_w - (int)bitmap->width) / 2;
        int y = offset_y + row * r->cell_h + r->baseline - entry->bitmap_top;
        if (i && cp < 0x0320) {
          y -= above;
          above += (int)bitmap->rows + 1;
        } else if (i) {
          y += below;
          below += (int)bitmap->rows + 1;
        }
        for (unsigned by = 0; by < bitmap->rows; by++) {
          int dy = y + (int)by;
          if (dy < 0 || dy >= r->height_px)
            continue;
          for (unsigned bx = 0; bx < bitmap->width; bx++) {
            int dx = x + (int)bx;
            if (dx < 0 || dx >= r->width_px)
              continue;
            unsigned alpha = bitmap->buffer[by * bitmap->pitch + bx];
            uint8_t *dst = r->framebuffer + dy * r->pitch + dx * 4;
            dst[0] = (uint8_t)((color.rgb.red * alpha + dst[0] * (255 - alpha)) / 255);
            dst[1] = (uint8_t)((color.rgb.green * alpha + dst[1] * (255 - alpha)) / 255);
            dst[2] = (uint8_t)((color.rgb.blue * alpha + dst[2] * (255 - alpha)) / 255);
          }
        }
      }
    }
  }
  r->zalgo_cache = r->glyph_cache;
  r->glyph_cache = base_cache;
}
 
asciichat_error_t term_renderer_feed(terminal_renderer_t *r, const char *ansi_frame, size_t len) {
  if (!r || (!ansi_frame && len > 0)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "renderer or frame is invalid");
  }
 
  uint64_t stage_start_ns = time_get_ns();
  // libvterm natively implements CSI REP.  Expanding those runs here turns a
  // compact network frame into synchronous browser-main-thread work before
  // every paint.
  const char *frame = ansi_frame;
  const size_t frame_len = len;
 
  // Clear framebuffer to ensure no leftover pixels from previous frames
  uint8_t def_fg_r, def_fg_g, def_fg_b;
  uint8_t def_bg_r, def_bg_g, def_bg_b;
  terminal_get_default_foreground_color(r->theme, &def_fg_r, &def_fg_g, &def_fg_b);
  terminal_get_default_background_color(r->theme, &def_bg_r, &def_bg_g, &def_bg_b);
  uint8_t def_bg = def_bg_r;
  memset(r->framebuffer, def_bg, (size_t)r->pitch * r->height_px);
 
  // Reset scrolling region and cursor position to prevent vertical shifts
  static const char reset_sequence[] = "\033[2J\033[H\033[r\033[?7l";
  vterm_input_write(r->vt, reset_sequence, sizeof(reset_sequence) - 1);
 
  // Count newlines to determine CRLF conversion size
  int newline_count = 0;
  for (size_t i = 0; i < frame_len; i++) {
    if (frame[i] == '\n')
      newline_count++;
  }
 
  // Convert LF-only line endings to CRLF (vterm expects CRLF)
  // This fixes cursor positioning on alternate rows
  char *fixed_frame = SAFE_MALLOC(frame_len + (size_t)newline_count, char *);
  if (!fixed_frame) {
    log_error("failed to allocate memory for CRLF conversion");
    return SET_ERRNO(ERROR_MEMORY, "CRLF conversion allocation failed");
  }
 
  size_t fixed_pos = 0;
  int frame_row = 0;
  for (size_t i = 0; i < frame_len; i++) {
    // A video frame is a fixed grid, not a scrolling terminal transcript.
    // A trailing newline on the bottom row must not scroll the whole image.
    if (frame[i] == '\n' && frame_row >= r->rows - 1) {
      continue;
    }
    fixed_frame[fixed_pos++] = frame[i];
    if (frame[i] == '\n' && (i == 0 || frame[i - 1] != '\r')) {
      // Insert carriage return before LF if not already preceded by CR
      fixed_frame[fixed_pos - 1] = '\r';
      fixed_frame[fixed_pos++] = '\n';
    }
    if (frame[i] == '\n')
      frame_row++;
  }
 
  vterm_input_write(r->vt, fixed_frame, fixed_pos);
  uint64_t parsed_ns = time_get_ns();
  SAFE_FREE(fixed_frame);
 
  // Calculate centering offsets to position grid in center of canvas
  int grid_width_px = r->cols * r->cell_w;
  int grid_height_px = r->rows * r->cell_h;
  int offset_x = (r->width_px - grid_width_px) / 2;
  int offset_y = (r->height_px - grid_height_px) / 2;
 
  static int frame_count = 0;
  static char prev_row_sigs[RENDER_DEBUG_SIGNATURE_ROWS][RENDER_DEBUG_SIGNATURE_BUFFER_SIZE] = {
      0}; // Store signatures of previous frame's rows
  frame_count++;
 
  // Log if any row signature changed to detect vertical shifts
  if (frame_count % 10 == 0) {
    char curr_row_sigs[RENDER_DEBUG_SIGNATURE_ROWS][RENDER_DEBUG_SIGNATURE_BUFFER_SIZE];
    for (int row = 0; row < r->rows && row < RENDER_DEBUG_SIGNATURE_ROWS; row++) {
      // Get first 4 chars as signature
      for (int col = 0; col < RENDER_DEBUG_SIGNATURE_COLUMNS && col < r->cols; col++) {
        VTermScreenCell cell;
        vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
        curr_row_sigs[row][col] = (cell.chars[0] >= 32 && cell.chars[0] <= 126) ? cell.chars[0] : '.';
      }
      curr_row_sigs[row][RENDER_DEBUG_SIGNATURE_COLUMNS] = 0;
    }
    memcpy(prev_row_sigs, curr_row_sigs, sizeof(curr_row_sigs));
  }
 
  int glyph_rendered_count = 0;
  int occupied_cell_count = 0;
  // ANSI 16/256 colors are indexed.  Converting them through libvterm for
  // every cell is especially expensive in the single-threaded WASM renderer.
  // A terminal palette has at most 256 entries and is stable for a frame.
  uint32_t indexed_rgb[ASCII_LUMINANCE_LEVELS] = {0};
  bool indexed_rgb_valid[ASCII_LUMINANCE_LEVELS] = {false};
  for (int row = 0; row < r->rows; row++) {
    for (int col = 0; col < r->cols; col++) {
      VTermScreenCell cell;
      vterm_screen_get_cell(r->vts, (VTermPos){row, col}, &cell);
 
      uint8_t fr, fg, fb, br, bg, bb;
      if (VTERM_COLOR_IS_RGB(&cell.fg)) {
        fr = cell.fg.rgb.red;
        fg = cell.fg.rgb.green;
        fb = cell.fg.rgb.blue;
      } else if (VTERM_COLOR_IS_INDEXED(&cell.fg)) {
        const uint8_t index = cell.fg.indexed.idx;
        if (!indexed_rgb_valid[index]) {
          VTermColor foreground = cell.fg;
          vterm_screen_convert_color_to_rgb(r->vts, &foreground);
          indexed_rgb[index] =
              ((uint32_t)foreground.rgb.red << 16) | ((uint32_t)foreground.rgb.green << 8) | foreground.rgb.blue;
          indexed_rgb_valid[index] = true;
        }
        fr = (uint8_t)(indexed_rgb[index] >> 16);
        fg = (uint8_t)(indexed_rgb[index] >> 8);
        fb = (uint8_t)indexed_rgb[index];
      } else {
        fr = def_fg_r;
        fg = def_fg_g;
        fb = def_fg_b;
      }
 
      if (VTERM_COLOR_IS_RGB(&cell.bg)) {
        br = cell.bg.rgb.red;
        bg = cell.bg.rgb.green;
        bb = cell.bg.rgb.blue;
      } else if (VTERM_COLOR_IS_INDEXED(&cell.bg)) {
        const uint8_t index = cell.bg.indexed.idx;
        if (!indexed_rgb_valid[index]) {
          VTermColor background = cell.bg;
          vterm_screen_convert_color_to_rgb(r->vts, &background);
          indexed_rgb[index] =
              ((uint32_t)background.rgb.red << 16) | ((uint32_t)background.rgb.green << 8) | background.rgb.blue;
          indexed_rgb_valid[index] = true;
        }
        br = (uint8_t)(indexed_rgb[index] >> 16);
        bg = (uint8_t)(indexed_rgb[index] >> 8);
        bb = (uint8_t)indexed_rgb[index];
      } else {
        br = def_bg_r;
        bg = def_bg_g;
        bb = def_bg_b;
      }
 
      int px = offset_x + col * r->cell_w, py = offset_y + row * r->cell_h;
      uint32_t foreground = ((uint32_t)fr << 16) | ((uint32_t)fg << 8) | fb;
      uint32_t background = ((uint32_t)br << 16) | ((uint32_t)bg << 8) | bb;
      // Retain the low 32 bits without overflowing the intermediate products.
      uint32_t cell_hash = (uint32_t)((uint64_t)cell.chars[0] * UINT64_C(2654435761) ^
                                      (uint64_t)foreground * UINT64_C(2246822519) ^ background);
      cell_hash ^= cell_hash >> 16;
      rendered_cell_t *cached_cell = &r->cells[cell_hash % CELL_CACHE_SIZE];
      bool contained = px >= 0 && py >= 0 && px + r->cell_w <= r->width_px && py + r->cell_h <= r->height_px;
      if (contained && cached_cell->valid && cached_cell->character == cell.chars[0] &&
          cached_cell->foreground == foreground && cached_cell->background == background) {
        for (int dy = 0; dy < r->cell_h; dy++) {
          memcpy(r->framebuffer + (py + dy) * r->pitch + px * 4, cached_cell->pixels + dy * r->cell_w * 4,
                 (size_t)r->cell_w * 4);
        }
        if (cell.chars[0] && cell.chars[0] != ' ') {
          occupied_cell_count++;
          glyph_rendered_count++;
        }
        continue;
      }
      // Block elements represent cell geometry, independent of font bearings and line spacing.
      bool block = cell.chars[0] == 0x2580 || cell.chars[0] == 0x2584 || cell.chars[0] == 0x2588;
      for (int dy = 0; dy < r->cell_h; dy++) {
        bool block_foreground =
            block && (cell.chars[0] == 0x2588 || (cell.chars[0] == 0x2580 ? dy < r->cell_h / 2 : dy >= r->cell_h / 2));
        int y = py + dy;
        if (y < 0 || y >= r->height_px)
          continue;
        uint8_t *line = r->framebuffer + y * r->pitch + px * 4;
        for (int dx = 0; dx < r->cell_w; dx++) {
          int x = px + dx;
          if (x < 0 || x >= r->width_px)
            continue;
          line[dx * 4] = block_foreground ? fr : br;
          line[dx * 4 + 1] = block_foreground ? fg : bg;
          line[dx * 4 + 2] = block_foreground ? fb : bb;
          line[dx * 4 + 3] = 255;
        }
      }
 
      if (block) {
        occupied_cell_count++;
        glyph_rendered_count++;
      } else if (cell.chars[0] && cell.chars[0] != ' ') {
        occupied_cell_count++;
        // For matrix font, map ASCII characters to Private Use Area glyphs (U+E900-U+E91A)
        uint32_t char_to_render = r->is_matrix_font ? matrix_char_map(cell.chars[0]) : cell.chars[0];
 
        // Use per-renderer glyph cache to avoid rasterizing every glyph every frame
        FT_Bitmap *cached_bitmap = glyph_cache_get(r, r->ft_face, char_to_render);
        if (cached_bitmap && cached_bitmap->width > 0 && cached_bitmap->rows > 0) {
          // Find cache entry to get positioning offsets
          glyph_cache_entry_t *cache_entry = NULL;
          HASH_FIND_INT(r->glyph_cache, &char_to_render, cache_entry);
          if (cache_entry) {
            // Overhanging glyphs must retain the normal cross-cell drawing order.
            contained = contained && cache_entry->bitmap_left >= 0 &&
                        cache_entry->bitmap_left + cache_entry->width <= r->cell_w &&
                        r->baseline - cache_entry->bitmap_top >= 0 &&
                        r->baseline - cache_entry->bitmap_top + cache_entry->rows <= r->cell_h;
            blit_glyph(r, cached_bitmap, px + cache_entry->bitmap_left, py + r->baseline - cache_entry->bitmap_top, fr,
                       fg, fb, br, bg, bb);
            glyph_rendered_count++;
          }
        } else if (cell.chars[0] >= 0x2800 && cell.chars[0] <= 0x28ff) {
          // The bundled font lacks Braille. Draw its eight-dot pattern in the
          // cell when the selected font cannot supply the requested glyph.
          static const unsigned dot_bits[4][2] = {{0, 3}, {1, 4}, {2, 5}, {6, 7}};
          unsigned pattern = cell.chars[0] - 0x2800;
          int dot_w = r->cell_w / 4 > 0 ? r->cell_w / 4 : 1;
          int dot_h = r->cell_h / 8 > 0 ? r->cell_h / 8 : 1;
          for (int row = 0; row < 4; row++) {
            for (int col = 0; col < 2; col++) {
              if (!(pattern & (1U << dot_bits[row][col])))
                continue;
              int left = px + (2 * col + 1) * r->cell_w / 4 - dot_w / 2;
              int top = py + (2 * row + 1) * r->cell_h / 8 - dot_h / 2;
              for (int dy = 0; dy < dot_h; dy++) {
                for (int dx = 0; dx < dot_w; dx++) {
                  int x = left + dx, y = top + dy;
                  if (x < px || x >= px + r->cell_w || y < py || y >= py + r->cell_h || x < 0 || x >= r->width_px ||
                      y < 0 || y >= r->height_px)
                    continue;
                  uint8_t *pixel = r->framebuffer + y * r->pitch + x * 4;
                  pixel[0] = fr;
                  pixel[1] = fg;
                  pixel[2] = fb;
                  pixel[3] = 255;
                }
              }
            }
          }
          glyph_rendered_count++;
        } else {
          return SET_ERRNO(ERROR_NOT_SUPPORTED, "Font cannot render Unicode character U+%04X", cell.chars[0]);
        }
      }
      if (contained) {
        if (!cached_cell->pixels)
          cached_cell->pixels = SAFE_MALLOC((size_t)r->cell_w * r->cell_h * 4, uint8_t *);
        if (cached_cell->pixels) {
          for (int dy = 0; dy < r->cell_h; dy++) {
            memcpy(cached_cell->pixels + dy * r->cell_w * 4, r->framebuffer + (py + dy) * r->pitch + px * 4,
                   (size_t)r->cell_w * 4);
          }
          cached_cell->character = cell.chars[0];
          cached_cell->foreground = foreground;
          cached_cell->background = background;
          cached_cell->valid = true;
        }
      }
    }
  }
  render_zalgo(r, offset_x, offset_y);
  uint64_t rendered_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "RECORD_RASTER: input_bytes=%zu parse_ms=%.2f paint_ms=%.2f cells=%dx%d", len,
                  (double)(parsed_ns - stage_start_ns) / NS_PER_MS_INT,
                  (double)(rendered_ns - parsed_ns) / NS_PER_MS_INT, r->cols, r->rows);
  log_debug_every(5 * US_PER_SEC_INT, "Rendered %d glyphs from %d occupied cells out of %d cells", glyph_rendered_count,
                  occupied_cell_count, r->rows * r->cols);
 
  return ASCIICHAT_OK;
}
 
const uint8_t *term_renderer_pixels(terminal_renderer_t *r) {
  return r->framebuffer;
}
int term_renderer_width_px(terminal_renderer_t *r) {
  return r->width_px;
}
int term_renderer_height_px(terminal_renderer_t *r) {
  return r->height_px;
}
int term_renderer_pitch(terminal_renderer_t *r) {
  return r->pitch;
}
 
int term_renderer_get_cols(terminal_renderer_t *r) {
  if (!r)
    return 0;
  return r->cols;
}
 
int term_renderer_get_rows(terminal_renderer_t *r) {
  if (!r)
    return 0;
  return r->rows;
}
 
void term_renderer_destroy(terminal_renderer_t *r) {
  if (!r)
    return;
  vterm_free(r->vt);
  if (r->zalgo_face)
    FT_Done_Face(r->zalgo_face);
  glyph_cache_destroy(&r->zalgo_cache);
  FT_Done_Face(r->ft_face);
  FT_Done_FreeType(r->ft_lib);
  SAFE_FREE(r->framebuffer);
  glyph_cache_destroy(&r->glyph_cache);
  for (size_t i = 0; i < CELL_CACHE_SIZE; i++)
    SAFE_FREE(r->cells[i].pixels);
  SAFE_FREE(r);
}