src/common/session/display.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
 
#include <ascii-chat/otel.h>
#include <ascii-chat/debug/named.h>
#include <ascii-chat/video/ascii/zalgo.h>
#include <ascii-chat/stats/runtime.h>
 
#include <ascii-chat/tui/too_small.h>
#include <ascii-chat/tui/controller.h>
#include <ascii-chat/tui/keyboard_help.h>
#include <ascii-chat/app_callbacks.h>
#include "session/display.h"
#include "session/frame_validation.h"
#include <ascii-chat/util/utf8.h>
#include "session/render.h"
#include <ascii-chat/util/time.h>
#include <ascii-chat/common.h>
#include <ascii-chat/options/colorscheme.h>
#include <ascii-chat/log/log.h>
#include <ascii-chat/tui/splash.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/options/runtime.h>
#include <ascii-chat/util/time.h>
#include <libplatform/terminal.h>
#include <libplatform/compiler.h>
#include <libplatform/system.h>
#include <libplatform/terminal.h>
#include <ascii-chat/video/terminal/ansi.h>
#include <ascii-chat/video/ascii/palette.h>
#include <ascii-chat/video/ascii/ascii.h>
#include <ascii-chat/video/ascii/render.h>
#include <ascii-chat/video/ascii/common.h>
#include <ascii-chat/video/ascii/rle.h>
#include <ascii-chat/util/string.h>
#include <ascii-chat/video/rgba/color_filter.h>
#include <ascii-chat/video/anim/digital_rain.h>
#include <ascii-chat/video/rgba/image.h>
#include <ascii-chat/terminal/fd/reader.h>
#include <ascii-chat/media/render/renderer.h>
#include <ascii-chat/audio/audio.h>
#include <ascii-chat/audio/visualization.h>
#include <ascii-chat/video/anim/waveform.h>
#include <ascii-chat/video/anim/fft.h>
#include <ascii-chat/asciichat_errno.h>
#include <ascii-chat/video/ascii/neon.h>
#include <libplatform/cpu.h>
 
#include <string.h>
#include <stdio.h>
#include <libplatform/atomic.h>
#include <stdlib.h>
 
/* ============================================================================
 * Session Display Context Structure
 * ============================================================================ */

typedef struct session_display_ctx {
  tty_info_t tty_info;

  bool has_tty;

  terminal_capabilities_t caps;

  char palette_chars[ASCII_PALETTE_BUFFER_SIZE];

  size_t palette_len;

  char luminance_palette[ASCII_LUMINANCE_LEVELS];

  palette_type_t palette_type;

  bool snapshot_mode;

  atomic_t first_frame;

  atomic_t output_failed;

  bool initialized;

  bool audio_playback_enabled;

  void *audio_ctx;

  digital_rain_t *digital_rain;
  ascii_stabilizer_t stabilizer;
  ascii_stabilizer_t recording_stabilizer;
  color_filter_t previous_stabilizer_filter;
  bool stabilizer_filter_initialized;
  outbuf_t ascii_workspace;
  image_t *resize_workspace;
  image_t *flip_workspace;
  image_t *filter_workspace;
  char *tty_frame_buffer;
  size_t tty_frame_capacity;

  uint64_t last_frame_time_ns;

  uint32_t render_fps;

  render_file_ctx_t *render_file;

  terminal_fd_reader_t *stdin_reader;
} session_display_ctx_t;
 
// Display conversion and submission have a single owner, so scratch images can be reused.
static image_t *display_image_workspace(image_t **workspace, int width, int height) {
  if (*workspace && ((*workspace)->w != width || (*workspace)->h != height)) {
    image_destroy(*workspace);
    *workspace = NULL;
  }
  if (!*workspace)
    *workspace = image_new((size_t)width, (size_t)height);
  return *workspace;
}
 
/* ============================================================================
 * Internal Helper Functions
 * ============================================================================ */

/* ============================================================================
 * Session Display Lifecycle Functions
 * ============================================================================ */
 
asciichat_error_t session_display_init_render_file(session_display_ctx_t *ctx, uint32_t fps) {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL");
  }
 
  const char *render_file_opt = GET_OPTION(render_file);
  if ((!render_file_opt || !render_file_opt[0]) && GET_OPTION(render_kitty))
    render_file_opt = "--kitty";
  if (!render_file_opt || render_file_opt[0] == '\0') {
    return ASCIICHAT_OK;
  }
  if (ctx->render_file) {
    return ASCIICHAT_OK;
  }
 
  uint32_t encoder_fps = fps;
  if (encoder_fps == 0) {
    encoder_fps = (uint32_t)GET_OPTION(fps);
  }
  if (encoder_fps == 0) {
    encoder_fps = 60;
  }
 
  int width = (int)GET_OPTION(width);
  int height = (int)GET_OPTION(height);
  ctx->render_fps = encoder_fps;
 
  log_info("render-file: Initializing encoder after media timing selection: path='%s', grid=%dx%d, fps=%u",
           render_file_opt, width, height, encoder_fps);
  asciichat_error_t err =
      render_file_create(render_file_opt, width, height, (int)encoder_fps, GET_OPTION(render_theme), &ctx->render_file);
  if (err != ASCIICHAT_OK) {
    asciichat_error_context_t error;
    if (HAS_ERRNO(&error))
      log_error("render-file: %s", error.context_message);
    log_error("render-file: Failed to create encoder %s", asciichat_error_format(NULL, err));
    return err;
  }
 
  log_info("render-file: Encoder initialized successfully at %u FPS", encoder_fps);
  return ASCIICHAT_OK;
}
 
static void display_sync_entries(session_display_ctx_t *ctx, bool add) {
  if (add)
    NAMED_REGISTER_ATOMIC(&ctx->first_frame, "display.first_frame", NULL);
  else
    NAMED_UNREGISTER(&ctx->first_frame);
  if (add)
    NAMED_REGISTER_ATOMIC(&ctx->output_failed, "display.output_failed", NULL);
  else
    NAMED_UNREGISTER(&ctx->output_failed);
}
 
session_display_ctx_t *session_display_create(const session_display_config_t *config) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_CREATE);
  if (GET_OPTION(zalgo) > 0 && (GET_OPTION(force_utf8) == UTF8_SETTING_FALSE ||
                                (GET_OPTION(force_utf8) == UTF8_SETTING_AUTO && terminal_is_stdout_tty() &&
                                 !detect_terminal_capabilities(options_terminal_settings()).utf8_support))) {
    SET_ERRNO(ERROR_USAGE, "--zalgo requires UTF-8 terminal output (on Windows, run chcp 65001 first)");
    return NULL;
  }
  // Auto-create config from command-line options if NULL
  session_display_config_t auto_config = {0};
  if (!config) {
    auto_config.snapshot_mode = GET_OPTION(snapshot_mode);
    auto_config.palette_type = GET_OPTION(palette_type);
    auto_config.custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL;
    auto_config.color_mode = TERM_COLOR_AUTO;
    config = &auto_config;
  }
 
  // Check if we should exit before starting initialization
  if (config->should_exit_callback && config->should_exit_callback(config->callback_data)) {
    return NULL;
  }
 
  // Allocate context
  session_display_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_display_ctx_t), session_display_ctx_t *);
 
  // Store configuration
  ctx->snapshot_mode = config->snapshot_mode;
  ctx->palette_type = config->palette_type;
  ctx->audio_playback_enabled = config->enable_audio_playback;
  ctx->audio_ctx = config->audio_ctx;
  ctx->render_fps = config->render_fps;
  atomic_store_bool(&ctx->first_frame, true);
  atomic_store_bool(&ctx->output_failed, false);
 
  // Get TTY info for direct terminal access
  ctx->tty_info = get_current_tty();
 
  // Presentation follows stdout. Opening a separate controlling terminal can
  // fail under ConPTY even though stdout is an interactive console.
  ctx->has_tty = terminal_is_stdout_tty();
  const char *stdout_output = GET_OPTION(render_file);
  bool owns_stdout = GET_OPTION(render_kitty) || strcmp(stdout_output, "--kitty") == 0 ||
                     strcmp(stdout_output, "-") == 0 || strcmp(stdout_output, "pipe:") == 0;
  if (owns_stdout)
    ctx->has_tty = false;
  if (ctx->has_tty) {
    // Retain the terminal before decoder/audio workers redirect process stdio
    // through LOG_IO. The first media submission must remain interactive too.
    int output = platform_dup(STDOUT_FILENO);
    if (output >= 0 && platform_isatty(output)) {
      if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0)
        platform_close(ctx->tty_info.fd);
      ctx->tty_info.fd = output;
      ctx->tty_info.owns_fd = true;
    } else if (output >= 0) {
      platform_close(output);
    }
  }
  if (ctx->has_tty && (ctx->tty_info.fd < 0 || !platform_isatty(ctx->tty_info.fd))) {
    if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0)
      platform_close(ctx->tty_info.fd);
    ctx->tty_info.fd = STDOUT_FILENO;
    ctx->tty_info.owns_fd = false;
  }
 
  // In piped mode, force all logs to stderr to prevent frame data corruption
  if (terminal_should_force_stderr()) {
    log_set_force_stderr(true);
    // Disable buffering for stdout to ensure frames appear immediately
    // Each frame ends with newline, so unbuffered output is critical for real-time display
    (void)setvbuf(stdout, NULL, _IONBF, 0);
  }
 
  // Also disable buffering for TTY mode to ensure smooth 40+ FPS animation
  setvbuf(stdout, NULL, _IONBF, 0);
 
  // Detect terminal capabilities
  ctx->caps = detect_terminal_capabilities(options_terminal_settings());
 
  // Set wants_padding based on terminal output mode
  // Enable padding for all rendering modes (including snapshot) to center output
  // The padding adds newlines at the top, which is useful for visual centering
  bool is_snapshot_mode = config->snapshot_mode;
  ctx->caps.wants_padding = true;
 
  // Calculate pad_height: when padding is enabled, add top padding for centering
  // Halfblock mode uses 2 source rows per output row, so padding is halved
  if (ctx->caps.wants_padding) {
    ctx->caps.pad_height = 5; // Halfblock needs half the padding (10 / 2 = 5)
  } else {
    ctx->caps.pad_height = 0;
  }
 
  log_debug("Padding mode: wants_padding=%d (snapshot=%d, has_tty=%d, stdin_tty=%d, stdout_tty=%d), pad_height=%zu",
            ctx->caps.wants_padding, is_snapshot_mode, ctx->has_tty, terminal_is_stdin_tty(), terminal_is_stdout_tty(),
            ctx->caps.pad_height);
 
  // Apply color mode override if specified
  if (config->color_mode != TERM_COLOR_AUTO) {
    ctx->caps.color_level = config->color_mode;
  }
 
  // Apply command-line overrides
  ctx->caps = apply_color_mode_override(ctx->caps, options_terminal_settings());
 
  // Initialize palette
  int palette_result = initialize_client_palette(config->palette_type, config->custom_palette, ctx->palette_chars,
                                                 &ctx->palette_len, ctx->luminance_palette);
  if (palette_result != ASCIICHAT_OK) {
    log_warn("Failed to initialize palette, using default");
    // Fall back to standard palette
    (void)initialize_client_palette(PALETTE_STANDARD, NULL, ctx->palette_chars, &ctx->palette_len,
                                    ctx->luminance_palette);
  }
 
  // Pre-warm UTF-8 palette cache during initialization (not during rendering)
  // This is expensive on first use (creates lookup tables), so warm it up now to avoid frame lag
  // This function is imported from lib/video/simd/common.h
  (void)get_utf8_palette_cache((const char *)ctx->palette_chars);
  log_debug("UTF-8 palette cache pre-warmed during display initialization");
 
  // Initialize ANSI fast lookup tables based on terminal capabilities
  if (ctx->caps.color_level == TERM_COLOR_TRUECOLOR) {
    ansi_fast_init();
  } else if (ctx->caps.color_level == TERM_COLOR_256) {
    ansi_fast_init_256color();
  } else if (ctx->caps.color_level == TERM_COLOR_16) {
    ansi_fast_init_16color();
  }
  // TERM_COLOR_MONO requires no init
 
  // Initialize ASCII output system if we have a TTY
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_init(ctx->tty_info.fd, false);
  }
 
  // Initialize digital rain effect if enabled
  if (GET_OPTION(matrix_rain)) {
    // Get terminal dimensions for grid size
    unsigned short int width_us = terminal_get_effective_width(GET_OPTION(width), 80);
    unsigned short int height_us = terminal_get_effective_height(GET_OPTION(height), 24);
 
    int width = (int)width_us;
    int height = (int)height_us;
 
    ctx->digital_rain = digital_rain_init(width, height);
    if (ctx->digital_rain) {
      // Set color from color filter if active
      color_filter_t filter = GET_OPTION(color_filter);
      digital_rain_set_color_from_filter(ctx->digital_rain, filter);
      log_info("Digital rain effect enabled: %dx%d grid", width, height);
    } else {
      log_warn("Failed to initialize digital rain effect");
    }
    ctx->last_frame_time_ns = time_get_ns();
  }
 
  if (GET_OPTION(fft) && audio_visualization_fft_init() != ASCIICHAT_OK) {
    session_display_destroy(ctx);
    return NULL;
  }
 
  display_sync_entries(ctx, true);
 
  // Initialize render-file unless media setup needs to determine its timing first.
  const char *render_file_opt = GET_OPTION(render_file);
  log_debug("render-file opt='%s' (len=%zu), deferred=%d", render_file_opt ? render_file_opt : "(null)",
            render_file_opt ? strlen(render_file_opt) : 0, config->defer_render_file);
  if (!config->defer_render_file) {
    asciichat_error_t render_err = session_display_init_render_file(ctx, config->render_fps);
    if (render_err != ASCIICHAT_OK) {
      log_error("render-file: Initialization failed %s", asciichat_error_format(NULL, render_err));
      asciichat_error_context_t error;
      bool has_error = HAS_ERRNO(&error);
      session_display_destroy(ctx);
      SET_ERRNO(render_err, "%s", has_error ? error.context_message : "Render-file initialization failed");
      return NULL;
    }
  }
 
  ctx->initialized = true;
  if (ctx->has_tty && !ctx->snapshot_mode) {
    const char initial[] = "\033[H";
    (void)ui_controller_present_retained(UI_SCREEN_MEDIA, ctx->tty_info.fd,
                                         (terminal_size_t){.cols = UI_MEDIA_MIN_COLS, .rows = UI_MEDIA_MIN_ROWS},
                                         initial, sizeof(initial) - 1);
  }
 
  return ctx;
}
 
void session_display_begin_drain(session_display_ctx_t *ctx, uint64_t total, bool total_known) {
  if (ctx && ctx->render_file) {
    ui_controller_remove(UI_SCREEN_HELP);
    render_file_begin_drain(ctx->render_file, total, total_known);
  }
}
 
asciichat_error_t session_display_finish_render_file(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->render_file)
    return ASCIICHAT_OK;
  asciichat_error_t err = render_file_destroy(ctx->render_file);
  ctx->render_file = NULL;
  return err;
}
 
void session_display_destroy(session_display_ctx_t *ctx) {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  session_display_finish_render_file(ctx);
 
  ui_controller_remove(UI_SCREEN_HELP);
  ui_controller_remove(UI_SCREEN_MEDIA);
 
  // Cleanup ASCII rendering if we had a TTY
  // Don't reset terminal in snapshot mode to preserve the rendered output
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_destroy(ctx->tty_info.fd, !ctx->snapshot_mode);
  }
 
  // Close the controlling terminal if we opened it
  if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0) {
    (void)platform_close(ctx->tty_info.fd);
    ctx->tty_info.fd = -1;
    ctx->tty_info.owns_fd = false;
  }
 
  // Cleanup digital rain effect
  if (ctx->digital_rain) {
    digital_rain_destroy(ctx->digital_rain);
    ctx->digital_rain = NULL;
  }
 
  image_destroy(ctx->resize_workspace);
  image_destroy(ctx->flip_workspace);
  image_destroy(ctx->filter_workspace);
  ctx->resize_workspace = ctx->flip_workspace = ctx->filter_workspace = NULL;
  SAFE_FREE(ctx->tty_frame_buffer);
  ascii_stabilizer_reset(&ctx->stabilizer);
  ascii_stabilizer_reset(&ctx->recording_stabilizer);
  SAFE_FREE(ctx->ascii_workspace.buf);
  ctx->initialized = false;
 
  // Clear the cached display context in splash state to prevent use-after-free
  // when worker threads try to access the display after it's been freed
  splash_clear_display_context();
 
  display_sync_entries(ctx, false);
  SAFE_FREE(ctx);
}
 
void session_display_set_stdin_reader(session_display_ctx_t *ctx, void *reader) {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL");
    return;
  }
 
  ctx->stdin_reader = (terminal_fd_reader_t *)reader;
  log_debug("stdin_reader set");
}
 
/* ============================================================================
 * Session Display Query Functions
 * ============================================================================ */
 
bool session_display_has_tty(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return false;
  }
  return ctx->has_tty;
}
 
const terminal_capabilities_t *session_display_get_caps(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return &ctx->caps;
}
 
const char *session_display_get_palette_chars(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->palette_chars;
}
 
size_t session_display_get_palette_len(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return 0;
  }
  return ctx->palette_len;
}
 
const char *session_display_get_luminance_palette(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->luminance_palette;
}
 
int session_display_get_tty_fd(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return -1;
  }
  return ctx->tty_info.fd;
}
 
void *session_display_get_stdin_reader(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
 
  return ctx->stdin_reader;
}
 
uint32_t session_display_get_render_fps(session_display_ctx_t *ctx) {
  if (!ctx)
    return 0;
  return ctx->render_fps;
}
 
void session_display_set_render_fps(session_display_ctx_t *ctx, uint32_t fps) {
  if (!ctx)
    return;
  ctx->render_fps = fps;
  if (fps > 0) {
    log_debug("Updated render FPS to %u (for correct video duration)", fps);
  }
}
 
bool session_display_has_first_frame(session_display_ctx_t *ctx) {
  if (!ctx) {
    return false;
  }
  // Return true if first_frame flag is false (meaning first frame has been rendered)
  return !atomic_load_bool(&ctx->first_frame);
}
 
void session_display_reset_first_frame(session_display_ctx_t *ctx) {
  if (!ctx) {
    return;
  }
  // Reset first_frame flag to true so splash screen can be shown again on next render
  atomic_store_bool(&ctx->first_frame, true);
}
 
bool session_display_has_render_file(session_display_ctx_t *ctx) {
  if (!ctx) {
    return false;
  }
  return ctx->render_file != NULL;
}
 
/* ============================================================================
 * Session Display ASCII Conversion Functions
 * ============================================================================ */
 
static char *convert_to_ascii(session_display_ctx_t *ctx, const image_t *image, bool reuse) {
  uint64_t stats_start = time_get_ns();
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ctx is NULL");
    return NULL;
  }
 
  if (!ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_STATE, "ctx not initialized");
    return NULL;
  }
 
  if (!image) {
    SET_ERRNO(ERROR_INVALID_PARAM, "image is NULL");
    return NULL;
  }
 
  // Read the renderer and palette from the same committed options revision.
  options_snapshot_t snapshot;
  if (options_read_snapshot(&snapshot) != ASCIICHAT_OK) {
    return NULL;
  }
  const options_t *values = &snapshot.values;
  unsigned short int width = values->width;
  unsigned short int height = values->height;
  bool stretch = values->stretch;
  terminal_capabilities_t caps_copy = ctx->caps;
  caps_copy.render_mode = (terminal_render_mode_t)values->render_mode;
  caps_copy.text_renderer = values->renderer;
  caps_copy.stabilize = values->stabilize;
  caps_copy.palette_explicit = values->palette_explicit;
  terminal_color_mode_t color_mode_opt = (terminal_color_mode_t)values->color_mode;
  const palette_def_t *builtin = get_builtin_palette(values->palette_type);
  const char *selected_palette = !values->palette_explicit                ? ctx->palette_chars
                                 : values->palette_type == PALETTE_CUSTOM ? values->palette_custom
                                 : builtin                                ? builtin->chars
                                                                          : ctx->palette_chars;
  char palette_chars[ASCII_PALETTE_BUFFER_SIZE];
  SAFE_STRNCPY(palette_chars, selected_palette, sizeof(palette_chars));
  bool preserve_aspect_ratio = !stretch;
 
  // Determine if we should apply flip_x and flip_y
  bool flip_x_enabled = GET_OPTION(flip_x);
  bool flip_y_enabled = GET_OPTION(flip_y);
 
  color_filter_t color_filter = GET_OPTION(color_filter);
  if (ctx->stabilizer_filter_initialized && ctx->previous_stabilizer_filter != color_filter) {
    ascii_stabilizer_reset(&ctx->stabilizer);
    ascii_stabilizer_reset(&ctx->recording_stabilizer);
  }
  ctx->previous_stabilizer_filter = color_filter;
  ctx->stabilizer_filter_initialized = true;
 
  // Handle dynamic matrix rain effect toggle
  bool matrix_rain_enabled = GET_OPTION(matrix_rain);
  if (matrix_rain_enabled && !ctx->digital_rain) {
    // Initialize digital rain if it's now enabled but wasn't before
    unsigned short int width_us = terminal_get_effective_width(GET_OPTION(width), 80);
    unsigned short int height_us = terminal_get_effective_height(GET_OPTION(height), 24);
    int width_for_rain = (int)width_us;
    int height_for_rain = (int)height_us;
    ctx->digital_rain = digital_rain_init(width_for_rain, height_for_rain);
    if (ctx->digital_rain) {
      digital_rain_set_color_from_filter(ctx->digital_rain, color_filter);
      log_info("Matrix rain effect: enabled");
    }
  } else if (!matrix_rain_enabled && ctx->digital_rain) {
    // Disable digital rain if it's now disabled but was enabled before
    digital_rain_destroy(ctx->digital_rain);
    ctx->digital_rain = NULL;
    log_info("Matrix rain effect: disabled");
  }
 
  // Make a mutable copy of terminal capabilities for ascii_convert_with_capabilities
  if (color_mode_opt != TERM_COLOR_AUTO) {
    caps_copy.color_level = color_mode_opt;
  }
 
  // MEASURE EVERY OPERATION - Debug systematic timing
  uint64_t t_flip_start = time_get_ns();
 
  // Apply horizontal and/or vertical flips if requested
  image_t *flipped_image = NULL;
  const image_t *display_image = image;
 
  if ((flip_x_enabled || flip_y_enabled) && image->w > 1 && image->h > 1 && image->pixels) {
    uint64_t t_flip_alloc_start = time_get_ns();
    flipped_image = ctx->render_file ? image_new(image->w, image->h)
                                     : display_image_workspace(&ctx->flip_workspace, image->w, image->h);
    uint64_t t_flip_alloc_end = time_get_ns();
 
    if (flipped_image) {
      uint64_t t_flip_memcpy_start = time_get_ns();
      // OPTIMIZATION: Copy entire image first (sequential memory access - cache-friendly)
      memcpy(flipped_image->pixels, image->pixels, (size_t)image->w * (size_t)image->h * sizeof(rgb_pixel_t));
      uint64_t t_flip_memcpy_end = time_get_ns();
 
      uint64_t t_flip_reverse_start = time_get_ns();
 
      // Apply horizontal flip (X-axis)
      if (flip_x_enabled) {
#if SIMD_SUPPORT_NEON
        if (platform_cpu_features() & CPU_FEATURE_NEON) {
          image_flip_horizontal_neon(flipped_image);
        } else
#endif
        {
          for (int y = 0; y < image->h; y++) {
            rgb_pixel_t *row = &flipped_image->pixels[y * image->w];
            for (int x = 0; x < image->w / 2; x++) {
              rgb_pixel_t temp = row[x];
              row[x] = row[image->w - 1 - x];
              row[image->w - 1 - x] = temp;
            }
          }
        }
      }
 
      // Apply vertical flip (Y-axis)
      if (flip_y_enabled) {
        for (int y = 0; y < image->h / 2; y++) {
          rgb_pixel_t *top_row = &flipped_image->pixels[y * image->w];
          rgb_pixel_t *bottom_row = &flipped_image->pixels[(image->h - 1 - y) * image->w];
          for (int x = 0; x < image->w; x++) {
            rgb_pixel_t temp = top_row[x];
            top_row[x] = bottom_row[x];
            bottom_row[x] = temp;
          }
        }
      }
 
      uint64_t t_flip_reverse_end = time_get_ns();
      display_image = flipped_image;
 
      log_dev("TIMING_FLIP: alloc=%llu us, memcpy=%llu us, flip=%llu us (x=%d, y=%d)",
              (t_flip_alloc_end - t_flip_alloc_start) / 1000, (t_flip_memcpy_end - t_flip_memcpy_start) / 1000,
              (t_flip_reverse_end - t_flip_reverse_start) / 1000, flip_x_enabled, flip_y_enabled);
    }
  }
  uint64_t t_flip_end = time_get_ns();
 
  uint64_t t_filter_start = time_get_ns();
 
  // Apply color filter to RGB pixels before ASCII conversion
  // Rainbow filter is handled separately via ANSI color replacement
  image_t *filtered_image = NULL;
  if (color_filter != COLOR_FILTER_NONE && color_filter != COLOR_FILTER_RAINBOW) {
    // Create a copy to avoid modifying the original
    filtered_image = ctx->render_file
                         ? image_new(display_image->w, display_image->h)
                         : display_image_workspace(&ctx->filter_workspace, display_image->w, display_image->h);
    if (filtered_image && filtered_image->pixels && display_image->pixels) {
      memcpy(filtered_image->pixels, display_image->pixels,
             (size_t)display_image->w * (size_t)display_image->h * sizeof(rgb_pixel_t));
 
      // Apply filter to the copy
      int stride = (int)display_image->w * 3;
      float time_seconds = (float)t_filter_start / (float)NS_PER_SEC_INT;
      apply_color_filter((uint8_t *)filtered_image->pixels, (uint32_t)display_image->w, (uint32_t)display_image->h,
                         (uint32_t)stride, color_filter, time_seconds);
    }
  }
 
  const image_t *ascii_input_image = filtered_image ? filtered_image : display_image;
  uint64_t t_filter_end = time_get_ns();
 
  uint64_t t_convert_start = time_get_ns();
  // Recording converts concurrently on its encoder thread and retains owned output.
  outbuf_t *output = reuse && !ctx->render_file && color_filter == COLOR_FILTER_NONE && !matrix_rain_enabled
                         ? &ctx->ascii_workspace
                         : NULL;
  // Recording and live display run on separate threads and own separate histories.
  bool recording = ctx->render_file && !reuse;
  ascii_stabilizer_t *history = recording ? &ctx->recording_stabilizer : &ctx->stabilizer;
  if (recording && ctx->render_fps)
    history->fixed_step_ns = NS_PER_SEC_INT / ctx->render_fps;
  char *result = ascii_convert_with_buffers_stabilized(
      ascii_input_image, width, height, &caps_copy, preserve_aspect_ratio, stretch, palette_chars, false,
      ctx->render_file ? NULL : &ctx->resize_workspace, output, caps_copy.stabilize ? history : NULL);
  if (!caps_copy.stabilize)
    ascii_stabilizer_reset(history);
  uint64_t t_convert_end = time_get_ns();
 
  // Apply rainbow color filter to ANSI output by replacing RGB values
  // This preserves character selection while applying the filter colors
  if (result && color_filter == COLOR_FILTER_RAINBOW) {
    uint64_t t_color_replace_start = time_get_ns();
    float time_seconds = (float)t_filter_start / (float)NS_PER_SEC_INT;
 
    char *rainbow_result = rainbow_replace_ansi_colors(result, time_seconds);
    if (rainbow_result) {
      SAFE_FREE(result);
      result = rainbow_result;
    }
 
    uint64_t t_color_replace_end = time_get_ns();
    char color_replace_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty(t_color_replace_end - t_color_replace_start, -1, color_replace_str, sizeof(color_replace_str));
    log_dev("COLOR_REPLACE: %s", color_replace_str);
  }
 
  // Apply digital rain effect if enabled
  if (result && ctx->digital_rain) {
    uint64_t t_rain_start = time_get_ns();
    uint64_t current_time_ns = t_rain_start;
    float delta_time = (float)(current_time_ns - ctx->last_frame_time_ns) / (float)NS_PER_SEC_INT;
    ctx->last_frame_time_ns = current_time_ns;
 
    // Update digital rain color from current filter (allows live filter changes)
    color_filter_t current_filter = GET_OPTION(color_filter);
    digital_rain_set_color_from_filter(ctx->digital_rain, current_filter);
 
    char *rain_result = digital_rain_apply(ctx->digital_rain, result, delta_time);
    if (rain_result) {
      SAFE_FREE(result);
      result = rain_result;
    }
 
    uint64_t t_rain_end = time_get_ns();
    char rain_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty(t_rain_end - t_rain_start, -1, rain_str, sizeof(rain_str));
    log_dev("DIGITAL_RAIN: Effect applied (%s)", rain_str);
  }
 
  uint64_t validation_started_ns = time_get_ns();
  // Validate the completed local frame using the same policy as received text.
  // Wide palettes use the existing cell composer before the rectangular check.
  bool explicit_palette = caps_copy.palette_explicit;
  bool glyph_match = caps_copy.text_renderer == ASCII_RENDERER_GLYPH &&
                     caps_copy.render_mode != RENDER_MODE_HALF_BLOCK && width > 0 && height > 0 &&
                     width <= IMAGE_MAX_WIDTH / 8 && height <= IMAGE_MAX_HEIGHT / 8 &&
                     (!explicit_palette || ascii_glyph_palette_supported(palette_chars));
  if (result && !glyph_match && (size_t)utf8_display_width(palette_chars) != utf8_char_count(palette_chars)) {
    ascii_frame_source_t source = {.frame_data = result, .frame_size = strlen(result)};
    size_t normalized_size;
    char *rectangular = ascii_create_grid(&source, 1, width, height, &normalized_size);
    session_display_release_ascii(ctx, result);
    result = rectangular;
  }
  if (result) {
    acip_render_settings_t rendering = {.caps = caps_copy};
    const char *contract_palette =
        glyph_match && !explicit_palette
            ? " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
            : palette_chars;
    SAFE_STRNCPY(rendering.palette, contract_palette, sizeof(rendering.palette));
    uint32_t effects = ctx->digital_rain ? FRAME_RENDER_CONTRACT_RAIN : 0;
    if (session_frame_validate_contract(result, strlen(result), width, height, &rendering, effects) != ASCIICHAT_OK) {
      session_display_release_ascii(ctx, result);
      result = NULL;
    }
  }
 
  uint64_t validation_finished_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "DISPLAY_STAGE: conversion_ms=%.2f validation_ms=%.2f",
                  (double)(t_convert_end - t_convert_start) / NS_PER_MS_INT,
                  (double)(validation_finished_ns - validation_started_ns) / NS_PER_MS_INT);
  uint64_t t_cleanup_start = time_get_ns();
  // Scratch images remain owned by the display until resize or teardown.
  if (ctx->render_file) {
    image_destroy(filtered_image);
    image_destroy(flipped_image);
  }
  uint64_t t_cleanup_end = time_get_ns();
 
  // Log total breakdown with actual measured times
  log_dev_every(US_PER_SEC_INT,
                "CONVERT_TIMING: flip=%llu us, filter=%llu us, convert=%llu us, cleanup=%llu us, TOTAL=%llu us",
                (t_flip_end - t_flip_start) / 1000, (t_filter_end - t_filter_start) / 1000,
                (t_convert_end - t_convert_start) / 1000, (t_cleanup_end - t_cleanup_start) / 1000,
                (t_cleanup_end - t_flip_start) / 1000);
 
  stats_duration_record(stats_runtime_scope(), STATS_DURATION_ASCII_CONVERT, time_get_ns() - stats_start);
  stats_counter_add(stats_runtime_scope(), result ? STATS_COUNTER_FRAMES_CONVERTED : STATS_COUNTER_FRAMES_DROPPED, 1);
  return result;
}
 
/* ============================================================================
 * Session Display Rendering Functions
 * ============================================================================ */
 
static char *session_display_create_visualization_frame(session_display_ctx_t *ctx) {
  unsigned int width = terminal_get_effective_width(GET_OPTION(width), 80);
  unsigned int height = terminal_get_effective_height(GET_OPTION(height), 24);
  bool use_color = ctx->caps.color_level == TERM_COLOR_TRUECOLOR && GET_OPTION(color) != COLOR_SETTING_FALSE;
  int color_mode = colorscheme_current_background() == TERM_BACKGROUND_DARK ? AUDIO_VISUALIZATION_COLOR_BRIGHTER
                                                                            : AUDIO_VISUALIZATION_COLOR_DARKER;
  audio_source_t selected_audio = GET_OPTION(audio_source);
  audio_visualization_source_t visual_source = AUDIO_VISUALIZATION_SOURCE_MIX;
  if (selected_audio == AUDIO_SOURCE_MEDIA)
    visual_source = AUDIO_VISUALIZATION_SOURCE_MEDIA;
  else if (selected_audio == AUDIO_SOURCE_MIC)
    visual_source = AUDIO_VISUALIZATION_SOURCE_MIC;
  else if (selected_audio == AUDIO_SOURCE_CALL)
    visual_source = AUDIO_VISUALIZATION_SOURCE_REMOTE;
  char *text = GET_OPTION(fft)
                   ? audio_visualization_render_fft(width, height, visual_source, use_color, color_mode,
                                                    GET_OPTION(flip_x), GET_OPTION(flip_y))
                   : audio_visualization_render_waveform(width, height, visual_source, use_color, color_mode,
                                                         GET_OPTION(flip_x), GET_OPTION(flip_y));
  if (text && session_frame_validate(text, strlen(text), width, height) != ASCIICHAT_OK) {
    SAFE_FREE(text);
    return NULL;
  }
  return text;
}
 
void session_display_render_frame(session_display_ctx_t *ctx, const char *frame_data) {
  // Legacy function: shim that calls both new split functions for backward compatibility
  // This maintains API compatibility with existing code while delegating to specialized functions
 
  if (!ctx || !frame_data) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context or frame data is NULL");
    return;
  }
 
  // Write the selected visualization to the render file as well as the terminal.
  char *visualization_frame = NULL;
  const char *render_frame = frame_data;
  if (GET_OPTION(waveform) || GET_OPTION(fft)) {
    visualization_frame = session_display_create_visualization_frame(ctx);
    if (visualization_frame)
      render_frame = visualization_frame;
  }
 
  // Write ASCII to terminal (main thread output path)
  if (ctx && ctx->render_file) {
    render_file_set_live_timing(ctx->render_file);
    asciichat_error_t err = render_file_write_frame(ctx->render_file, render_frame, time_get_ns());
    if (err != ASCIICHAT_OK)
      log_warn_every(5 * US_PER_SEC_INT, "Recording received frame failed: %s", asciichat_error_format(NULL, err));
  }
  SAFE_FREE(visualization_frame);
  session_display_write_ascii(ctx, frame_data);
}
 
char *session_display_convert_to_ascii(session_display_ctx_t *ctx, const image_t *image) {
  return convert_to_ascii(ctx, image, false);
}
 
char *session_display_convert_to_ascii_reuse(session_display_ctx_t *ctx, const image_t *image) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_CONVERT_TO_ASCII_REUSE);
  return convert_to_ascii(ctx, image, true);
}
 
void session_display_reset_stabilizer(session_display_ctx_t *ctx, bool recording) {
  if (ctx)
    ascii_stabilizer_reset(recording ? &ctx->recording_stabilizer : &ctx->stabilizer);
}
 
void session_display_release_ascii(session_display_ctx_t *ctx, char *ascii) {
  if (!ctx || ascii != ctx->ascii_workspace.buf)
    SAFE_FREE(ascii);
}
 
void session_display_write_ascii_frame(session_display_ctx_t *ctx, const char *ascii, bool fresh) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_WRITE_ASCII_FRAME);
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL or uninitialized");
    return;
  }
 
  // Shutdown is asynchronous; queued frames must not retry a failed output.
  if (atomic_load_bool(&ctx->output_failed)) {
    return;
  }
 
  if (!ascii) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ASCII data is NULL");
    return;
  }
 
  // Re-evaluate color_level on every frame to pick up live color_mode changes
  terminal_color_mode_t color_mode = (terminal_color_mode_t)GET_OPTION(color_mode);
  if (color_mode != TERM_COLOR_AUTO) {
    ctx->caps.color_level = color_mode;
  }
 
  // Suppress frame rendering when help screen is active
 
  bool visualization_enabled = GET_OPTION(waveform) || GET_OPTION(fft);
  char *visualization_frame = visualization_enabled ? session_display_create_visualization_frame(ctx) : NULL;
  if (visualization_frame)
    ascii = visualization_frame;
 
  // Leave room for cursor controls when passing the frame to the presenter.
  const size_t max_frame_len = UI_CONTROLLER_MAX_FRAME_BYTES - 7;
  size_t frame_len = strnlen(ascii, max_frame_len);
  if (frame_len == max_frame_len) {
    SET_ERRNO(ERROR_BUFFER_FULL, "ASCII frame exceeds the presenter limit");
    SAFE_FREE(visualization_frame);
    return;
  }
  if (frame_len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ASCII data is empty");
    SAFE_FREE(visualization_frame);
    return;
  }
 
  /* Inspect the payload before any terminal presentation.  This is bounded
   * diagnostics: it records shape/control-byte anomalies and a short tail,
   * never the full webcam frame. */
  {
    size_t lines = 0, current = 0, min_line = SIZE_MAX, max_line = 0, last_line = 0;
    unsigned control_bytes = 0, escape_bytes = 0;
    for (size_t i = 0; i < frame_len; ++i) {
      unsigned char byte = (unsigned char)ascii[i];
      if (byte == '\n') {
        min_line = MIN(min_line, current);
        max_line = MAX(max_line, current);
        last_line = current;
        ++lines;
        current = 0;
      } else {
        current++;
        if (byte < 32 && byte != '\r' && byte != '\t')
          ++control_bytes;
        if (byte == 0x1b)
          ++escape_bytes;
      }
    }
    if (current) {
      min_line = MIN(min_line, current);
      max_line = MAX(max_line, current);
      last_line = current;
    }
    char tail[64] = {0};
    size_t tail_start = frame_len > 24 ? frame_len - 24 : 0;
    size_t tail_used = 0;
    for (size_t i = tail_start; i < frame_len && tail_used + 4 < sizeof(tail); ++i)
      tail_used += (size_t)safe_snprintf(tail + tail_used, sizeof(tail) - tail_used, "%02X ", (unsigned char)ascii[i]);
 
    // Also capture the actual glyphs in the final row.  Byte/line counts alone
    // cannot distinguish a bad terminal write from a bad rendered frame.
    size_t row_start = 0;
    for (size_t i = 0; i < frame_len; ++i)
      if (ascii[i] == '\n')
        row_start = i + 1;
    char last_row[192] = {0};
    size_t row_used = 0;
    for (size_t i = row_start; i < frame_len && row_used + 5 < sizeof(last_row); ++i) {
      unsigned char byte = (unsigned char)ascii[i];
      if (byte == 0x1b) {
        ++i;
        while (i < frame_len && !((ascii[i] >= '@' && ascii[i] <= 'Z') || (ascii[i] >= 'a' && ascii[i] <= 'z')))
          ++i;
        continue;
      }
      if (byte >= 32 && byte < 127)
        last_row[row_used++] = (char)byte;
      else if (byte == '\r' || byte == '\t')
        last_row[row_used++] = ' ';
      else
        row_used += (size_t)safe_snprintf(last_row + row_used, sizeof(last_row) - row_used, "\\x%02X", byte);
    }
    log_debug_every(US_PER_SEC_INT,
                    "FRAME_DATA: bytes=%zu lines=%zu line_bytes=%zu..%zu last=%zu controls=%u escapes=%u last_row=\"%s\" tail=%s",
                    frame_len, lines, min_line == SIZE_MAX ? 0 : min_line, max_line, last_line, control_bytes,
                    escape_bytes, last_row, tail);
  }
 
  // Apply digital rain effect if enabled
  char *display_frame = (char *)ascii;
  char *rain_result = NULL;
  if (ctx->digital_rain && !visualization_enabled) {
    uint64_t t_rain_start = time_get_ns();
    uint64_t current_time_ns = t_rain_start;
    float delta_time = (float)(current_time_ns - ctx->last_frame_time_ns) / (float)NS_PER_SEC_INT;
    ctx->last_frame_time_ns = current_time_ns;
 
    // Update digital rain color from current filter
    color_filter_t current_filter = GET_OPTION(color_filter);
    digital_rain_set_color_from_filter(ctx->digital_rain, current_filter);
 
    rain_result = digital_rain_apply(ctx->digital_rain, (char *)ascii, delta_time);
    if (rain_result) {
      display_frame = rain_result;
      frame_len = strnlen(rain_result, max_frame_len);
      if (frame_len == max_frame_len) {
        SET_ERRNO(ERROR_BUFFER_FULL, "Digital rain frame exceeds the presenter limit");
        SAFE_FREE(rain_result);
        SAFE_FREE(visualization_frame);
        return;
      }
 
      uint64_t t_rain_end = time_get_ns();
      char rain_str[TIME_DURATION_BUFFER_SIZE];
      time_pretty(t_rain_end - t_rain_start, -1, rain_str, sizeof(rain_str));
      log_debug("DIGITAL_RAIN (write_ascii): Effect applied (%s)", rain_str);
    }
  }
 
  // Binary video owns stdout in every terminal mode.
  const char *output = GET_OPTION(render_file);
  bool binary_stdout = ctx->render_file && (strcmp(output, "-") == 0 || strcmp(output, "pipe:") == 0 ||
                                            strcmp(output, "--kitty") == 0 || GET_OPTION(render_kitty));
  char *zalgo_frame = NULL;
  int zalgo_level = GET_OPTION(zalgo);
  if (zalgo_level > 0 && !binary_stdout) {
    asciichat_error_t err =
        zalgo_apply(display_frame, frame_len, zalgo_level, UI_CONTROLLER_MAX_FRAME_BYTES - 7, &zalgo_frame);
    if (err == ASCIICHAT_OK) {
      display_frame = zalgo_frame;
      frame_len = strlen(zalgo_frame);
    } else {
      log_warn_every(5 * US_PER_SEC_INT, "Cannot apply Zalgo: %s", asciichat_error_format(NULL, err));
    }
  }
 
  char *plain_frame = NULL;
  if (GET_OPTION(strip_ansi)) {
    // Expand REP before stripping escapes so repeated cells are preserved.
    char *expanded = ansi_expand_rle(display_frame, frame_len);
    if (expanded) {
      size_t capacity = strlen(expanded) + 1;
      plain_frame = SAFE_MALLOC(capacity, char *);
      strip_ansi_codes(expanded, plain_frame, capacity);
      SAFE_FREE(expanded);
      display_frame = plain_frame;
      frame_len = strlen(plain_frame);
    }
  }
 
  // Handle first frame - perform initial terminal reset and splash cleanup
  bool was_first_frame = atomic_exchange_bool(&ctx->first_frame, false);
  if (was_first_frame) {
    ui_controller_title_ready();
    ui_controller_title_activity(UI_TITLE_ACTIVITY_IDLE);
    // Stop splash screen when first frame is ready
    splash_intro_done();
    splash_wait_for_animation();
  }
 
  if (binary_stdout) {
    if (GET_OPTION(snapshot_mode) && !g_snapshot_first_frame_rendered) {
      g_snapshot_first_frame_rendered = true;
      g_snapshot_first_frame_rendered_ns = time_get_ns();
    }
    SAFE_FREE(plain_frame);
    SAFE_FREE(zalgo_frame);
    SAFE_FREE(rain_result);
    SAFE_FREE(visualization_frame);
    return;
  }
 
  // Output routing logic
  // A snapshot still needs terminal cursor framing when stdout is a real TTY.
  // `terminal_is_interactive()` also depends on stdin, which is commonly false
  // for scripted snapshot invocations even though the PTY can display output.
  bool use_tty_control = ctx->has_tty ||
                         (ctx->snapshot_mode && ctx->tty_info.fd >= 0 && platform_isatty(ctx->tty_info.fd));
 
  uint64_t frame_write_started_ns = time_get_ns();
 
  // Increment shared frame counter for both client and host rendering
  // This metric is used by debug scripts to measure FPS across all modes
  static atomic_t g_display_frames_rendered = {0};
  int frame_number = atomic_fetch_add_u64(&g_display_frames_rendered, 1) + 1;
  log_dev("[FRAMES_RENDERED_TOTAL] %d", frame_number);
 
  if (use_tty_control) {
    // TTY mode: Buffer cursor control + frame data together for atomic frame display
    const char *cursor_home_sequence = "\033[H";
    const char *erase_below_sequence = "\033[J";
    size_t cursor_seq_len = 3;
    size_t erase_below_len = 3;
    // The frame is shorter than the terminal in some configurations.  Erase
    // from the final frame cursor to the bottom of the screen in the same
    // submission so stale rows cannot survive a resize or a shorter frame.
    size_t total_size = cursor_seq_len + frame_len + erase_below_len;
 
    if (ctx->tty_frame_capacity < total_size) {
      size_t capacity = ctx->tty_frame_capacity ? ctx->tty_frame_capacity : 4096;
      while (capacity < total_size && capacity <= SIZE_MAX / 2)
        capacity *= 2;
      if (capacity < total_size)
        capacity = total_size;
      ctx->tty_frame_buffer = SAFE_REALLOC(ctx->tty_frame_buffer, capacity, char *);
      ctx->tty_frame_capacity = capacity;
    }
    char *frame_buffer = ctx->tty_frame_buffer;
    if (frame_buffer) {
      memcpy(frame_buffer, cursor_home_sequence, cursor_seq_len);
      memcpy(frame_buffer + cursor_seq_len, display_frame, frame_len);
      memcpy(frame_buffer + cursor_seq_len + frame_len, erase_below_sequence, erase_below_len);
 
      log_debug_every(US_PER_SEC_INT, "FRAME_WRITE_TTY: Writing %zu bytes (cursor=%zu + frame=%zu) to stdout",
                      total_size, cursor_seq_len, frame_len);
      int output_fd = ctx->tty_info.fd >= 0 ? ctx->tty_info.fd : STDOUT_FILENO;
      asciichat_error_t presented = ASCIICHAT_OK;
      if (ctx->snapshot_mode) {
        // Snapshot processes may exit immediately after the first frame. Write
        // directly so teardown cannot discard a queued UI-controller update.
        if (platform_write_all(output_fd, frame_buffer, total_size) != total_size)
          presented = SET_ERRNO(ERROR_FILE_OPERATION, "Cannot write snapshot frame to terminal");
      } else {
        presented = (fresh ? ui_controller_present : ui_controller_present_retained)(
            UI_SCREEN_MEDIA, output_fd, (terminal_size_t){.cols = UI_MEDIA_MIN_COLS, .rows = UI_MEDIA_MIN_ROWS},
            frame_buffer, total_size);
      }
      if (was_first_frame && presented == ASCIICHAT_OK)
        ui_controller_remove(UI_SCREEN_SPLASH);
      ssize_t written = presented == ASCIICHAT_OK ? (ssize_t)total_size : -1;
      log_debug_every(US_PER_SEC_INT, "FRAME_WRITE_TTY: Wrote %zd bytes (requested %zu)", written, total_size);
 
      // Start snapshot timer on first ASCII frame rendered
      if (GET_OPTION(snapshot_mode) && !g_snapshot_first_frame_rendered) {
        g_snapshot_first_frame_rendered = true;
        g_snapshot_first_frame_rendered_ns = time_get_ns();
        log_debug("SNAPSHOT: FIRST ASCII FRAME RENDERED (write_ascii) - Timer started");
      }
 
      // The UI controller copies the submission before this workspace is reused.
    }
 
    // Live presentation owns terminal writes on its worker. Draining here
    // blocks packet reception, including audio, behind a slow terminal reader.
    if (ctx->snapshot_mode) {
      (void)fflush(stdout);
      int flush_fd = (ctx->tty_info.fd >= 0) ? ctx->tty_info.fd : STDOUT_FILENO;
      (void)terminal_flush(flush_fd);
    }
 
  } else if (terminal_is_interactive()) {
    // Piped to interactive terminal: output ASCII frames with newline
    char *write_buf = SAFE_MALLOC(frame_len + 1, char *);
    if (write_buf) {
      memcpy(write_buf, display_frame, frame_len);
      write_buf[frame_len] = '\n';
      if (ui_controller_write(STDOUT_FILENO, write_buf, frame_len + 1) != ASCIICHAT_OK) {
        atomic_store_bool(&ctx->output_failed, true);
        APP_CALLBACK_VOID(signal_exit);
        SAFE_FREE(write_buf);
        goto cleanup_frame;
      }
      SAFE_FREE(write_buf);
    }
 
    if (ctx->snapshot_mode) {
      (void)fflush(stdout);
      int flush_fd = (ctx->tty_info.fd >= 0) ? ctx->tty_info.fd : STDOUT_FILENO;
      (void)terminal_flush(flush_fd);
    }
  } else {
    // Named render files leave stdout available for ASCII output
    char *write_buf = SAFE_MALLOC(frame_len + 1, char *);
    if (write_buf) {
      memcpy(write_buf, display_frame, frame_len);
      write_buf[frame_len] = '\n';
      if (ui_controller_write(STDOUT_FILENO, write_buf, frame_len + 1) != ASCIICHAT_OK) {
        atomic_store_bool(&ctx->output_failed, true);
        APP_CALLBACK_VOID(signal_exit);
        SAFE_FREE(write_buf);
        goto cleanup_frame;
      }
 
      // Start snapshot timer on first ASCII frame rendered
      if (GET_OPTION(snapshot_mode) && !g_snapshot_first_frame_rendered) {
        g_snapshot_first_frame_rendered = true;
        g_snapshot_first_frame_rendered_ns = time_get_ns();
        log_debug("SNAPSHOT: FIRST ASCII FRAME RENDERED (write_ascii piped) - Timer started");
      }
 
      SAFE_FREE(write_buf);
    }
 
    // Writes already reach the OS synchronously; streaming frames do not need
    // a durability barrier or a terminal drain on the receiving thread.
    (void)fflush(stdout);
    if (ctx->snapshot_mode && ctx->has_tty) {
      int flush_fd = (ctx->tty_info.fd >= 0) ? ctx->tty_info.fd : STDOUT_FILENO;
      (void)terminal_flush(flush_fd);
    }
  }
 
cleanup_frame:
  log_dev_every(3 * US_PER_SEC_INT, "FRAME_WRITE: Published in %.2f ms",
                (double)(time_get_ns() - frame_write_started_ns) / NS_PER_MS_INT);
 
  // Clean up digital rain result if allocated
  SAFE_FREE(plain_frame);
  SAFE_FREE(zalgo_frame);
  if (rain_result) {
    SAFE_FREE(rain_result);
  }
  SAFE_FREE(visualization_frame);
}
 
void session_display_set_render_live_timing(session_display_ctx_t *ctx) {
  if (ctx && ctx->render_file)
    render_file_set_live_timing(ctx->render_file);
}
 
asciichat_error_t session_display_encode_frame(session_display_ctx_t *ctx, const image_t *image, uint64_t captured_ns) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_ENCODE_FRAME);
  static int call_count = 0;
  if (call_count++ < 5) {
    log_debug("ctx=%p, image=%p, captured_ns=%llu, ctx->render_file=%p", (void *)ctx, (void *)image,
              (unsigned long long)captured_ns, ctx ? (void *)ctx->render_file : NULL);
  }
 
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL or uninitialized");
  }
 
  if (!image) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Image is NULL");
  }
 
  // Only encode if render_file is active
  if (!ctx->render_file) {
    log_warn_every(10 * US_PER_SEC_INT, "render_file is NULL, skipping encode");
    return ASCIICHAT_OK;
  }
 
  // Convert image to ASCII
  uint64_t conversion_started_ns = time_get_ns();
  char *ascii = session_display_convert_to_ascii(ctx, image);
  uint64_t converted_ns = time_get_ns();
  if (!ascii) {
    log_warn("Failed to convert image to ASCII");
    return SET_ERRNO(ERROR_MEDIA_INIT, "Cannot convert recording frame to ASCII");
  }
 
  // Write the same selected visualization used by the terminal to the render-file encoder.
  char *visualization_frame = NULL;
  const char *render_frame = ascii;
  if (GET_OPTION(waveform) || GET_OPTION(fft)) {
    visualization_frame = session_display_create_visualization_frame(ctx);
    if (visualization_frame)
      render_frame = visualization_frame;
  }
 
  uint64_t stats_record_start = time_get_ns();
  asciichat_error_t fe = render_file_write_frame(ctx->render_file, render_frame, captured_ns);
  uint64_t recorded_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "RECORD_FRAME: convert_ms=%.2f output_ms=%.2f total_ms=%.2f",
                  (double)(converted_ns - conversion_started_ns) / NS_PER_MS_INT,
                  (double)(recorded_ns - converted_ns) / NS_PER_MS_INT,
                  (double)(recorded_ns - conversion_started_ns) / NS_PER_MS_INT);
  stats_duration_record(stats_runtime_scope(), STATS_DURATION_RECORDING, time_get_ns() - stats_record_start);
  if (fe == ASCIICHAT_OK)
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_RECORDING_FRAMES, 1);
  SAFE_FREE(visualization_frame);
  if (fe != ASCIICHAT_OK) {
    log_warn_every(5 * US_PER_SEC_INT, "render-file: encode failed (%s)", asciichat_error_format(NULL, fe));
  }
 
  SAFE_FREE(ascii);
  return fe;
}
 
void session_display_write_raw(session_display_ctx_t *ctx, const char *data, size_t len) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_WRITE_RAW);
  if (!ctx || !ctx->initialized || !data || len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, data=%p, len=%zu", ctx, data, len);
    return;
  }
 
  int fd = -1;
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    fd = ctx->tty_info.fd;
  } else {
    fd = STDOUT_FILENO;
  }
 
  // Write all data with automatic retry on transient errors
  (void)ui_controller_write(fd, data, len);
 
  // Flush immediately after write to TTY to ensure data is sent
  (void)terminal_flush(fd);
}
 
void session_display_reset(session_display_ctx_t *ctx) {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}
 
void session_display_clear(session_display_ctx_t *ctx) {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}
 
void session_display_cursor_home(session_display_ctx_t *ctx) {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}
 
bool session_display_has_audio_playback(session_display_ctx_t *ctx) {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return false;
  }
  return ctx->audio_playback_enabled;
}
 
asciichat_error_t session_display_write_audio(session_display_ctx_t *ctx, const float *buffer, size_t num_samples) {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_WRITE_AUDIO);
  if (!ctx || !ctx->initialized || !buffer || num_samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%zu", ctx, buffer,
                     num_samples);
  }
 
  if (!ctx->audio_playback_enabled || !ctx->audio_ctx) {
    // Audio not enabled, but not an error - just skip silently
    return ASCIICHAT_OK;
  }
 
  // For mirror mode with local files: write samples directly without jitter buffering
  // The jitter buffer is designed for network scenarios with irregular packet arrivals
  // For local playback, we just want raw samples flowing to the speakers
  audio_context_t *audio_ctx = (audio_context_t *)ctx->audio_ctx;
  if (audio_ctx && audio_ctx->playback_buffer) {
    audio_ring_buffer_t *rb = audio_ctx->playback_buffer;
 
    // Simple direct write: append samples to ring buffer without network-oriented complexity
    uint32_t write_idx = (uint32_t)atomic_load_u64(&rb->write_index);
    uint32_t read_idx = (uint32_t)atomic_load_u64(&rb->read_index);
 
    // Calculate available space in ring buffer
    uint32_t available = (read_idx - write_idx - 1) & (AUDIO_RING_BUFFER_SIZE - 1);
 
    if ((uint32_t)num_samples > available) {
      // Buffer full - just skip this write to avoid distortion from overwriting old audio
      return ASCIICHAT_OK;
    }
 
    // Direct memcpy to ring buffer, handling wrap-around
    uint32_t space_before_wrap = AUDIO_RING_BUFFER_SIZE - write_idx;
    if ((uint32_t)num_samples <= space_before_wrap) {
      memcpy(&rb->data[write_idx], buffer, num_samples * sizeof(float));
    } else {
      // Split write: first part to end of buffer, second part wraps to beginning
      uint32_t first_part = space_before_wrap;
      uint32_t second_part = num_samples - first_part;
      memcpy(&rb->data[write_idx], buffer, first_part * sizeof(float));
      memcpy(&rb->data[0], &buffer[first_part], second_part * sizeof(float));
    }
 
    // Update write index atomically
    atomic_store_u64(&rb->write_index, (write_idx + num_samples) % AUDIO_RING_BUFFER_SIZE);
 
    return ASCIICHAT_OK;
  }
 
  return ASCIICHAT_OK;
}
 
/* ============================================================================
 * Keyboard Help Functions (from keyboard_help module)
 * ============================================================================ */

// Global reference to current display context (used by signal handlers)
// Set during render loop, cleared on exit
static atomic_ptr_t g_current_display_ctx = {0};
 
// Signal-safe flag to request help screen closure from Ctrl+C handler
static atomic_t g_help_signal_cancel = {0};
 
// Signal handler safe way to access current display context
static session_display_ctx_t *get_current_display_ctx(void) {
  return (session_display_ctx_t *)atomic_ptr_load(&g_current_display_ctx);
}
 
// Called by render loop to register/unregister the display context
void session_display_set_global_context(session_display_ctx_t *ctx) {
  atomic_ptr_store(&g_current_display_ctx, (void *)ctx);
}
 
// Public getter for global display context
session_display_ctx_t *session_display_get_global_context(void) {
  return get_current_display_ctx();
}
 
// Public setter for global display context (used by discovery participant cleanup)
void session_display_set_global_context_public(session_display_ctx_t *ctx) {
  session_display_set_global_context(ctx);
}
 
// Called from Ctrl+C signal handler to request help screen closure
void keyboard_help_signal_cancel(void) {
  atomic_store_bool(&g_help_signal_cancel, true);
}
 
// Called from render loop to check if help should be closed
bool keyboard_help_check_signal_cancel(void) {
  bool expected = true;
  return atomic_cas_bool(&g_help_signal_cancel, &expected, false);
}
 
bool keyboard_help_is_active(session_display_ctx_t *ctx) {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return false;
  }
 
  // Disable help in snapshot mode only - allow help state check even if stdin/stdout aren't TTYs
  if (GET_OPTION(snapshot_mode)) {
    return false;
  }
 
  return ui_controller_interactive_screen() == UI_SCREEN_HELP;
}
 
// Global accessor for signal handlers (called from Ctrl+C handler)
// Checks raw help state without snapshot mode check (signal handler needs to know
// if help is active even in snapshot mode)
bool keyboard_help_is_active_global(void) {
  session_display_ctx_t *ctx = get_current_display_ctx();
  return ctx && !ui_controller_is_blocked() && (ui_controller_interactive_screen() == UI_SCREEN_HELP);
}
 
void keyboard_help_toggle_global(void) {
  keyboard_help_signal_cancel();
}
 
void session_display_set_snapshot_actual_duration(session_display_ctx_t *ctx, double actual_duration_sec) {
  log_debug("duration=%.3f, ctx=%p, render_file=%p", actual_duration_sec, (void *)ctx,
            ctx ? (void *)ctx->render_file : NULL);
 
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  if (!ctx->render_file) {
    // Terminal snapshots have no render-file encoder; their duration is
    // governed by the capture loop and requires no additional action.
    return;
  }
 
  log_debug("  -> Passing duration %.3f to render_file encoder", actual_duration_sec);
  render_file_set_snapshot_actual_duration(ctx->render_file, actual_duration_sec);
}
 
void session_display_write_ascii(session_display_ctx_t *ctx, const char *ascii) {
  session_display_write_ascii_frame(ctx, ascii, true);
}