src/server/stream.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define SERVER_STREAM_HEX_BUFFER_SIZE 300
#define SERVER_STREAM_ASCII_BUFFER_SIZE 100
 
#include <libplatform/atomic.h>
#include <ascii-chat/debug/named.h>
#include <stdio.h>
#include <string.h>
#include <time.h>
#include <math.h>
#include <float.h>
 
#include "main.h"
#include "stream.h"
#include "client.h"
#include <ascii-chat/common.h>
#include <ascii-chat/util/endian.h>
#include <ascii-chat/buffer.h>
#include <ascii-chat/network/packet/queue.h>
#include <ascii-chat/ringbuffer.h>
#include <ascii-chat/video/rgba/video_frame.h>
#include <ascii-chat/video/rgba/image.h>
#include <ascii-chat/video/ascii/ascii.h>
#include <ascii-chat/util/utf8.h>
#include <ascii-chat/video/rgba/color_filter.h>
#include <ascii-chat/video/anim/digital_rain.h>
#include <ascii-chat/util/aspect_ratio.h>
#include <ascii-chat/util/endian.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/util/image.h>

static atomic_t g_previous_active_video_count = {0};

typedef struct {
  image_t *image;
  char client_id[MAX_CLIENT_ID_LEN];
  bool has_video;
} image_source_t;

static int collect_video_sources(image_source_t *sources, int max_sources) {
  int source_count = 0;
 
  // Check for shutdown before acquiring locks to prevent lock corruption
  if (atomic_load_bool(&g_should_exit)) {
    return 0;
  }
 
  // Keep client slots and their incoming frame buffers alive until every
  // active source has been copied out of its double buffer. remove_client()
  // frees those buffers under the manager write lock after stopping only that
  // client's own workers; the other clients' render workers also read them.
  bool manager_lock_held = g_client_manager_rwlock_initialized;
  if (manager_lock_held) {
    rwlock_rdlock(&g_client_manager_rwlock);
  }
 
  // Snapshot fields while holding the manager read lock so removal cannot
  // invalidate a frame-buffer pointer between this scan and its copy.
  typedef struct {
    char client_id[MAX_CLIENT_ID_LEN];
    bool is_active;
    bool is_sending_video;
    video_frame_buffer_t *video_buffer;
  } client_snapshot_t;
 
  client_snapshot_t client_snapshots[MAX_CLIENTS];
  int snapshot_count = 0;
 
  // The manager read lock protects slot identity and buffer lifetime; stream
  // flags are atomic because receive callbacks update them independently.
  for (int i = 0; i < MAX_CLIENTS; i++) {
    client_info_t *client = &g_client_manager.clients[i];
 
    if (client->client_id[0] == '\0') {
      continue; // Skip uninitialized clients
    }
 
    // Snapshot all needed client state (all atomic reads or stable pointers)
    SAFE_STRNCPY(client_snapshots[snapshot_count].client_id, client->client_id,
                 sizeof(client_snapshots[snapshot_count].client_id) - 1);
    client_snapshots[snapshot_count].is_active = atomic_load_bool(&client->active);
    client_snapshots[snapshot_count].is_sending_video = atomic_load_bool(&client->is_sending_video);
    client_snapshots[snapshot_count].video_buffer = client->incoming_video_buffer; // Stable pointer
    snapshot_count++;
  }
 
  // Process frames (expensive operations)
  log_dev_every(5 * NS_PER_MS_INT, "Processing %d snapshots", snapshot_count);
  for (int i = 0; i < snapshot_count && source_count < max_sources; i++) {
    client_snapshot_t *snap = &client_snapshots[i];
 
    if (!snap->is_active) {
      log_dev_every(5 * NS_PER_MS_INT, "Skipping inactive client %s", snap->client_id);
      continue;
    }
 
    log_dev_every(5 * NS_PER_MS_INT, "Client %s: is_sending_video=%d", snap->client_id, snap->is_sending_video);
 
    SAFE_STRNCPY(sources[source_count].client_id, snap->client_id, sizeof(sources[source_count].client_id) - 1);
    sources[source_count].image = NULL; // Will be set if video is available
    sources[source_count].has_video = false;
 
    // Declare these outside the if block so they're accessible later
    multi_source_frame_t current_frame = {0};
    bool got_new_frame = false;
 
    // Always try to get the last available video frame for consistent ASCII generation.
    // Keep the swap mutex held until the front-buffer bytes have been copied:
    // after the next commit, this frame becomes the writer's back buffer and
    // can be overwritten while the compositor is still reading it.
    if (snap->is_sending_video && snap->video_buffer) {
      video_frame_buffer_t *video_buffer = snap->video_buffer;
      mutex_lock(&video_buffer->swap_mutex);
      const video_frame_t *frame = video_buffer->front_buffer;
      if (!frame || !frame->data || frame->size < sizeof(uint32_t) * 2 ||
          frame->size > video_buffer->allocated_buffer_size) {
        mutex_unlock(&video_buffer->swap_mutex);
        continue;
      }
 
      size_t frame_size_val = frame->size;
 
      if (frame_size_val >= (sizeof(uint32_t) * 2 + 3)) {
        // PARSE AND VALIDATE DIMENSIONS BEFORE COPYING
        // Don't trust frame->size - calculate correct size from dimensions
        uint32_t peek_width = NET_TO_HOST_U32(read_u32_unaligned(frame->data));
        uint32_t peek_height = NET_TO_HOST_U32(read_u32_unaligned(frame->data + sizeof(uint32_t)));
 
        // Reject obviously corrupted dimensions
        if (peek_width == 0 || peek_height == 0 || peek_width > 4096 || peek_height > 2160) {
          log_debug("Per-client %s: rejected dimensions %ux%u as corrupted", snap->client_id, peek_width, peek_height);
          mutex_unlock(&video_buffer->swap_mutex);
          continue;
        }
 
        // Validate dimensions
        if (image_validate_dimensions((size_t)peek_width, (size_t)peek_height) != ASCIICHAT_OK) {
          mutex_unlock(&video_buffer->swap_mutex);
          continue;
        }
 
        // Calculate CORRECT frame size based on dimensions (don't trust frame->size)
        size_t correct_frame_size = sizeof(uint32_t) * 2;
        {
          size_t rgb_size = 0;
          if (image_calc_rgb_size((size_t)peek_width, (size_t)peek_height, &rgb_size) != ASCIICHAT_OK) {
            log_debug("Per-client: rgb_size calc failed for %ux%u", peek_width, peek_height);
            mutex_unlock(&video_buffer->swap_mutex);
            continue;
          }
          correct_frame_size += rgb_size;
        }
 
        log_debug_every(NS_PER_MS_INT, "Per-client: frame dimensions=%ux%u, frame_size=%zu, correct_size=%zu",
                        peek_width, peek_height, frame_size_val, correct_frame_size);
 
        // Verify frame is at least large enough for the correct size
        if (frame_size_val < correct_frame_size) {
          log_debug("Per-client: frame too small: got %zu, need %zu", frame_size_val, correct_frame_size);
          mutex_unlock(&video_buffer->swap_mutex);
          continue;
        }
 
        // We have frame data - copy ONLY the correct amount based on dimensions
        current_frame.data = buffer_alloc(NULL, correct_frame_size);
 
        if (current_frame.data) {
          memcpy(current_frame.data, frame->data, correct_frame_size);
          current_frame.size = correct_frame_size;
          SAFE_STRNCPY(current_frame.source_client_id, snap->client_id, sizeof(current_frame.source_client_id) - 1);
          current_frame.timestamp = (uint32_t)(frame->capture_timestamp_ns / NS_PER_SEC_INT);
          got_new_frame = true;
          // Keep the frame for reuse, but mark it consumed before the next swap.
          atomic_store_bool(&video_buffer->new_frame_available, false);
        }
        mutex_unlock(&video_buffer->swap_mutex);
      } else {
        mutex_unlock(&video_buffer->swap_mutex);
      }
    }
 
    multi_source_frame_t *frame_to_use = got_new_frame ? &current_frame : NULL;
 
    if (frame_to_use && frame_to_use->data && frame_to_use->size > sizeof(uint32_t) * 2) {
      // Parse the image data
      // Format: [width:4][height:4][rgb_data:w*h*3]
      // Use unaligned read helpers - frame data may not be aligned
      uint32_t img_width = NET_TO_HOST_U32(read_u32_unaligned(frame_to_use->data));
      uint32_t img_height = NET_TO_HOST_U32(read_u32_unaligned(frame_to_use->data + sizeof(uint32_t)));
 
      // Debug logging to understand the data
      if (img_width == 0xBEBEBEBE || img_height == 0xBEBEBEBE) {
        SET_ERRNO(ERROR_INVALID_STATE, "Uninitialized frame dimensions from client %s: 0x%08x x 0x%08x",
                  snap->client_id, img_width, img_height);
      }
 
      // Validate dimensions using image utility function
      if (image_validate_dimensions((size_t)img_width, (size_t)img_height) != ASCIICHAT_OK) {
        SET_ERRNO(ERROR_INVALID_STATE,
                  "Per-client: Invalid image dimensions from client %s: %ux%u (data may be corrupted)", snap->client_id,
                  img_width, img_height);
        if (got_new_frame) {
          buffer_release(current_frame.data);
        }
        source_count++;
        continue;
      }
 
      // Calculate expected frame size with overflow checking
      size_t expected_size = sizeof(uint32_t) * 2;
      {
        size_t rgb_size = 0;
        if (image_calc_rgb_size((size_t)img_width, (size_t)img_height, &rgb_size) != ASCIICHAT_OK) {
          SET_ERRNO(ERROR_INVALID_STATE, "Per-client: RGB size calculation failed for client %s: %ux%u",
                    snap->client_id, img_width, img_height);
          if (got_new_frame) {
            buffer_release(current_frame.data);
          }
          source_count++;
          continue;
        }
        expected_size += rgb_size;
      }
      if (frame_to_use->size != expected_size) {
        SET_ERRNO(ERROR_INVALID_STATE,
                  "Per-client: Frame size mismatch from client %s: got %zu, expected %zu for %ux%u image",
                  snap->client_id, frame_to_use->size, expected_size, img_width, img_height);
        if (got_new_frame) {
          buffer_release(current_frame.data);
        }
        source_count++;
        continue;
      }
 
      // Extract pixel data pointer
      rgb_pixel_t *pixels = (rgb_pixel_t *)(frame_to_use->data + (sizeof(uint32_t) * 2));
 
      // Create image from buffer domain for consistent video pipeline management
      image_t *img = image_new(img_width, img_height);
      if (!img) {
        log_error("Per-client: image_new failed for %ux%u", img_width, img_height);
        if (got_new_frame) {
          buffer_release(current_frame.data);
        }
        continue;
      }
      memcpy(img->pixels, pixels, (size_t)img_width * (size_t)img_height * sizeof(rgb_pixel_t));
      sources[source_count].image = img;
      sources[source_count].has_video = true;
 
      // Free temporary frame buffer - image has its own pixel data now
      if (got_new_frame) {
        buffer_release(current_frame.data);
      }
    } else {
      // frame_to_use check failed - clean up allocated frame data
      if (got_new_frame && current_frame.data) {
        buffer_release(current_frame.data);
      }
    }
 
    // Increment source count for this active client (with or without video)
    source_count++;
  }
 
  if (manager_lock_held) {
    rwlock_rdunlock(&g_client_manager_rwlock);
  }
  return source_count;
}

static image_t *create_single_source_composite(image_source_t *sources, int source_count,
                                               const char *target_client_id __attribute__((unused)),
                                               unsigned short width __attribute__((unused)),
                                               unsigned short height __attribute__((unused))) {
  // Find the single source with video
  image_t *single_source = NULL;
  for (int i = 0; i < source_count; i++) {
    if (sources[i].has_video && sources[i].image) {
      single_source = sources[i].image;
      break;
    }
  }
 
  if (!single_source) {
    SET_ERRNO(ERROR_INVALID_STATE, "Logic error: sources_with_video=1 but no source found");
    return NULL;
  }
 
  // For single source, don't pre-fit the image. Let ascii_convert_with_capabilities handle
  // all aspect ratio fitting with proper CHAR_ASPECT correction. This avoids double-correction
  // that was happening when the image was pre-fitted in pixel space and then aspect_ratio()
  // was called again with CHAR_ASPECT=2.0.
  // Just return the source image as-is; ascii_convert_with_capabilities will fit it properly.
  return single_source;
}

static void calculate_optimal_grid_layout(image_source_t *sources, int source_count, int sources_with_video,
                                          int terminal_width, int terminal_height, int *out_cols, int *out_rows) {
  // Special cases
  if (sources_with_video == 0) {
    *out_cols = 0;
    *out_rows = 0;
    return;
  }
 
  if (sources_with_video == 1) {
    *out_cols = 1;
    *out_rows = 1;
    return;
  }
 
  // ASCII character aspect ratio: characters are ~2x taller than wide
  // So we need to adjust terminal dimensions to visual space
  const float CHAR_ASPECT = 2.0f; // Character height / width ratio
 
  // Calculate average aspect ratio of all video sources
  float avg_aspect = 0.0f;
  int aspect_count = 0;
  for (int i = 0; i < source_count; i++) {
    if (sources[i].has_video && sources[i].image) {
      float aspect = (float)sources[i].image->w / (float)sources[i].image->h;
      avg_aspect += aspect;
      aspect_count++;
    }
  }
  if (aspect_count > 0) {
    avg_aspect /= aspect_count;
  } else {
    avg_aspect = 1.6f; // Default aspect ratio
  }
 
  // Try all reasonable grid configurations
  int best_cols = 1;
  int best_rows = sources_with_video;
  float best_utilization = 0.0f;
 
  // Try grid configurations from 1x1 up to reasonable limits
  for (int cols = 1; cols <= sources_with_video; cols++) {
    int rows = (sources_with_video + cols - 1) / cols; // Ceiling division
 
    // Skip configurations with too many empty cells (more than one row worth)
    int total_cells = cols * rows;
    int empty_cells = total_cells - sources_with_video;
    if (empty_cells > cols) {
      continue;
    }
 
    // Calculate cell dimensions for this configuration
    int cell_width = terminal_width / cols;
    int cell_height = terminal_height / rows;
 
    // Skip if cells would be too small
    if (cell_width < 20 || cell_height < 10) {
      continue;
    }
 
    // Calculate total area utilized by all videos in this configuration
    // For each video, calculate how much space it would use in a cell
    // IMPORTANT: Account for character aspect ratio (chars are 2x taller than wide)
    float total_area_used = 0.0f;
    int cell_area = cell_width * cell_height;
 
    for (int i = 0; i < sources_with_video; i++) {
      // Use average aspect ratio for calculation
      float video_aspect = avg_aspect;
 
      // Calculate VISUAL cell aspect ratio (accounting for character shape)
      // A cell that is cell_width chars wide and cell_height chars tall
      // has visual aspect = cell_width / (cell_height * CHAR_ASPECT)
      float cell_visual_aspect = (float)cell_width / ((float)cell_height * CHAR_ASPECT);
 
      // Calculate fitted dimensions while preserving aspect ratio
      int fitted_width, fitted_height;
 
      if (video_aspect > cell_visual_aspect) {
        // Video is wider than cell - fit to width
        fitted_width = cell_width;
        // Visual height needed: cell_width / video_aspect
        // Character height: visual_height / CHAR_ASPECT
        fitted_height = (int)((cell_width / video_aspect) / CHAR_ASPECT);
      } else {
        // Video is taller than cell - fit to height
        fitted_height = cell_height;
        // Visual width needed: cell_height * CHAR_ASPECT * video_aspect
        fitted_width = (int)(cell_height * CHAR_ASPECT * video_aspect);
      }
 
      // Clamp to cell bounds
      if (fitted_width > cell_width) {
        fitted_width = cell_width;
      }
      if (fitted_height > cell_height) {
        fitted_height = cell_height;
      }
 
      // Add area used by this video
      total_area_used += fitted_width * fitted_height;
    }
 
    // Calculate utilization percentage
    float total_available_area = (float)(cell_area * sources_with_video);
    float utilization = total_area_used / total_available_area;
 
    float test_cell_visual_aspect = (float)cell_width / ((float)cell_height * CHAR_ASPECT);
    log_dev_every(LOG_RATE_NORMAL, "  Testing %dx%d: cell=%dx%d (visual aspect %.2f), utilization=%.1f%%", cols, rows,
                  cell_width, cell_height, test_cell_visual_aspect, utilization * 100.0f);
 
    // Prefer configurations with better utilization
    if (utilization > best_utilization) {
      best_utilization = utilization;
      best_cols = cols;
      best_rows = rows;
    }
  }
 
  *out_cols = best_cols;
  *out_rows = best_rows;
 
  float terminal_visual_aspect = (float)terminal_width / ((float)terminal_height * CHAR_ASPECT);
  log_dev_every(LOG_RATE_NORMAL,
                "Grid layout: %d clients -> %dx%d grid (%.1f%% utilization) | terminal=%dx%d (char aspect %.2f, VISUAL "
                "aspect %.2f), video aspect: %.2f",
                sources_with_video, best_cols, best_rows, best_utilization * 100.0f, terminal_width, terminal_height,
                (float)terminal_width / (float)terminal_height, terminal_visual_aspect, avg_aspect);
}

static image_t *create_multi_source_composite(image_source_t *sources, int source_count, int sources_with_video,
                                              const char *target_client_id, unsigned short width,
                                              unsigned short height) {
  (void)target_client_id; // Unused - composite is same for all clients now
 
  // Calculate optimal grid layout using space-maximizing algorithm
  int grid_cols, grid_rows;
  calculate_optimal_grid_layout(sources, source_count, sources_with_video, width, height, &grid_cols, &grid_rows);
 
  // Calculate composite dimensions in PIXELS for half-block mode
  // Terminal dimensions are in CHARACTERS, need to convert to pixels:
  // - Width: 1 char = 1 horizontal pixel
  // - Height: 1 char = 2 vertical pixels (half-block = 2 pixels per char)
  const int PIXELS_PER_CHAR_HEIGHT = 2;
  int composite_width_px = width;                            // chars = pixels horizontally
  int composite_height_px = height * PIXELS_PER_CHAR_HEIGHT; // chars * 2 = pixels vertically
 
  // Create composite with final dimensions - no recreation needed
  image_t *composite = image_new(composite_width_px, composite_height_px);
  image_clear(composite);
 
  // Place each source in the grid
  int video_source_index = 0;                                        // Track only sources with video
  for (int i = 0; i < source_count && video_source_index < 9; i++) { // Max 9 sources in 3x3 grid
    if (!sources[i].image)
      continue;
 
    int row = video_source_index / grid_cols;
    int col = video_source_index % grid_cols;
    video_source_index++;
 
    // Use actual composite dimensions for cell calculations
    // Composite is now in PIXELS (already converted from terminal characters)
    int cell_width_px = composite->w / grid_cols;
    int cell_height_px = composite->h / grid_rows;
 
    // Calculate aspect ratios
    float src_aspect = (float)sources[i].image->w / (float)sources[i].image->h;
    float cell_visual_aspect = (float)cell_width_px / (float)cell_height_px;
 
    int target_width_px, target_height_px;
 
    // CONTAIN strategy: Fill one dimension completely, let other scale down (never overflow)
    // Compare aspects to decide which dimension to fill
    if (src_aspect > cell_visual_aspect) {
      // Video is WIDER than cell → fill WIDTH (height will be smaller)
      target_width_px = cell_width_px;
      target_height_px = (int)((cell_width_px / src_aspect) + 0.5f);
    } else {
      // Video is TALLER than cell → fill HEIGHT (width will be smaller)
      target_height_px = cell_height_px;
      target_width_px = (int)((cell_height_px * src_aspect) + 0.5f);
    }
 
    log_dev_every(LOG_RATE_NORMAL, "Cell %d: %dx%d px, video %.1f, cell %.2f → target %dx%d px (fill %s)",
                  video_source_index - 1, cell_width_px, cell_height_px, src_aspect, cell_visual_aspect,
                  target_width_px, target_height_px, (src_aspect > cell_visual_aspect) ? "WIDTH" : "HEIGHT");
 
    // Create resized image with standard allocation
    image_t *resized = image_new(target_width_px, target_height_px);
    image_resize(sources[i].image, resized);
 
    // Calculate cell position in pixels (after any composite recreation)
    int cell_x_offset_px = col * cell_width_px;
    int cell_y_offset_px = row * cell_height_px;
 
    // Grid centering strategy:
    // - Multi-client: Apply padding ONLY to edge cells to center the grid as a whole
    //   (left column gets left padding, right column gets right padding)
    //   (top row gets top padding, bottom row gets bottom padding)
    //   This keeps cells edge-to-edge while centering the entire grid
    // - Single client: Center the image within the cell
    int x_padding_px, y_padding_px;
 
    // Center images within their cells for all layouts
    // This prevents gaps/stripes between clients
    x_padding_px = (cell_width_px - target_width_px) / 2;
    y_padding_px = (cell_height_px - target_height_px) / 2;
 
    // Define cell boundaries for clipping (prevents bleeding into adjacent cells)
    int cell_x_min = cell_x_offset_px;
    int cell_x_max = cell_x_offset_px + cell_width_px - 1;
    int cell_y_min = cell_y_offset_px;
    int cell_y_max = cell_y_offset_px + cell_height_px - 1;
 
    // Copy resized image to composite with cell boundary clipping
    // This allows images to fill cells completely while preventing overlap
 
    for (int y = 0; y < resized->h; y++) {
      for (int x = 0; x < resized->w; x++) {
        // Calculate destination position
        int dst_x = cell_x_offset_px + x_padding_px + x;
        int dst_y = cell_y_offset_px + y_padding_px + y;
 
        // Clip to cell boundaries (prevents bleeding into adjacent cells)
        if (dst_x < cell_x_min || dst_x > cell_x_max || dst_y < cell_y_min || dst_y > cell_y_max) {
          continue; // Skip pixels outside cell boundaries
        }
 
        // Additional composite boundary check
        if (dst_x < 0 || dst_x >= composite->w || dst_y < 0 || dst_y >= composite->h) {
          continue; // Skip pixels outside composite
        }
 
        // Copy pixel
        int src_idx = (y * resized->w) + x;
        int dst_idx = (dst_y * composite->w) + dst_x;
        composite->pixels[dst_idx] = resized->pixels[src_idx];
      }
    }
 
    image_destroy(resized);
  }
 
  return composite;
}

static void invalidate_changed_composite_owners(ascii_stabilizer_t *history, image_source_t *sources, int source_count,
                                                int sources_with_video, int width, int height) {
  if (!history->cells || history->width != (size_t)width || sources_with_video <= 0 ||
      (history->height != (size_t)height && history->height != (size_t)height * 2))
    return;
  size_t history_scale = history->height / (size_t)height;
  int cols = 1, rows = 1;
  if (sources_with_video > 1)
    calculate_optimal_grid_layout(sources, source_count, sources_with_video, width, height, &cols, &rows);
  uint64_t owners[9] = {0};
  int count = 0;
  for (int i = 0; i < source_count && count < 9; ++i) {
    if (!sources[i].has_video || !sources[i].image)
      continue;
    uint64_t hash = 1469598103934665603ULL;
    for (const unsigned char *p = (const unsigned char *)sources[i].client_id; *p; ++p) {
      hash ^= *p;
      hash *= 1099511628211ULL;
    }
    owners[count++] = hash ? hash : 1;
  }
  int cell_width = width / cols, cell_height = (height * 2) / rows;
  if (!cell_width || !cell_height)
    return;
  for (size_t y = 0; y < history->height; ++y) {
    for (int x = 0; x < width; ++x) {
      int col = x / cell_width, row = (int)((y * 2 / history_scale) / (size_t)cell_height);
      int index = row * cols + col;
      uint64_t owner = col < cols && row < rows && index < count ? owners[index] : 0;
      ascii_temporal_cell_t *cell = &history->cells[y * (size_t)width + (size_t)x];
      if (cell->source_owner != owner)
        cell->valid = false;
      cell->source_owner = owner;
    }
  }
}
 
static char *convert_composite_to_ascii(image_t *composite, const char *target_client_id, unsigned short width,
                                        unsigned short height, acip_render_settings_t *out_rendering,
                                        image_source_t *sources, int source_count, int sources_with_video) {
  // LOCK OPTIMIZATION: Don't call find_client_by_id() - it would acquire rwlock unnecessarily
  // Instead, the render thread already has snapshot of client state, so we just need palette data
  // which is stable after initialization
 
  // We need to find the client to access palette data, but we can do this without locking
  // since palette is initialized once and never changes
  client_info_t *render_client = NULL;
 
  // Find client without locking - client_id is stable once set
  for (int i = 0; i < MAX_CLIENTS; i++) {
    client_info_t *client = &g_client_manager.clients[i];
    if (strcmp(client->client_id, target_client_id) == 0) {
      render_client = client;
      break;
    }
  }
 
  if (!render_client) {
    SET_ERRNO(ERROR_INVALID_STATE, "Per-client %s: Target client not found", target_client_id);
    return NULL;
  }
 
  mutex_lock(&render_client->client_state_mutex);
  bool ready = render_client->has_terminal_caps && render_client->client_palette_initialized;
  acip_render_settings_t rendering = render_client->render_settings;
  mutex_unlock(&render_client->client_state_mutex);
  if (!ready) {
    SET_ERRNO(ERROR_TERMINAL, "Client rendering is not configured");
    return NULL;
  }
  if (out_rendering)
    *out_rendering = rendering;
  terminal_capabilities_t caps_snapshot = rendering.caps;
  width = rendering.width;
  height = rendering.height;
  if (caps_snapshot.stabilize)
    invalidate_changed_composite_owners(&render_client->render_stabilizer, sources, source_count, sources_with_video,
                                        width, height);
  uint64_t convert_start_ns = time_get_ns();
  char *ascii_frame = ascii_convert_with_buffers_stabilized(
      composite, width, height, &caps_snapshot, true, false, rendering.palette, false, NULL, NULL,
      caps_snapshot.stabilize ? &render_client->render_stabilizer : NULL);
  if (!caps_snapshot.stabilize)
    ascii_stabilizer_reset(&render_client->render_stabilizer);
  uint64_t convert_end_ns = time_get_ns();
  uint64_t convert_duration_ns = convert_end_ns - convert_start_ns;
 
  if (convert_duration_ns > 5 * NS_PER_MS_INT) { // Log if > 5ms
    char duration_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty((uint64_t)((double)convert_duration_ns), -1, duration_str, sizeof(duration_str));
    log_warn_every(US_PER_SEC_INT, "SLOW_ASCII_CONVERT: Client %s took %s to convert %dx%d image to ASCII",
                   target_client_id, duration_str, composite->w, composite->h);
  }
 
  const bool matrix_rain = (caps_snapshot.capabilities & TERM_CAP_MATRIX_RAIN) != 0;
  if (matrix_rain && ascii_frame) {
    if (!render_client->digital_rain || render_client->digital_rain->num_columns != width ||
        render_client->digital_rain->num_rows != height) {
      if (render_client->digital_rain) {
        digital_rain_destroy(render_client->digital_rain);
      }
      render_client->digital_rain = digital_rain_init(width, height);
      render_client->digital_rain_last_update_time = (double)time_get_ns() / (double)NS_PER_SEC_INT;
    }
 
    if (render_client->digital_rain) {
      const double now = (double)time_get_ns() / (double)NS_PER_SEC_INT;
      const float elapsed = (float)(now - render_client->digital_rain_last_update_time);
      render_client->digital_rain_last_update_time = now;
      digital_rain_set_color_from_filter(render_client->digital_rain, caps_snapshot.color_filter);
      char *rain_frame = digital_rain_apply(render_client->digital_rain, ascii_frame, elapsed);
      if (rain_frame) {
        SAFE_FREE(ascii_frame);
        ascii_frame = rain_frame;
      }
    }
  } else if (render_client->digital_rain) {
    digital_rain_destroy(render_client->digital_rain);
    render_client->digital_rain = NULL;
  }
 
  if (ascii_frame && (size_t)utf8_display_width(rendering.palette) != utf8_char_count(rendering.palette)) {
    // Normalize display-cell geometry (wide palettes and REP included) with the
    // same row composer as discovery/browser hosts.
    ascii_frame_source_t source = {.frame_data = ascii_frame, .frame_size = strlen(ascii_frame)};
    size_t size;
    char *rectangular = ascii_create_grid(&source, 1, width, height, &size);
    SAFE_FREE(ascii_frame);
    ascii_frame = rectangular;
  }
  return ascii_frame;
}
 
/* ============================================================================
 * Per-Client Video Mixing and Frame Generation
 * ============================================================================
 */

// Compute hash of all active video sources for cache invalidation
// Uses hardware-accelerated CRC32 for ultra-fast hashing
char *create_mixed_ascii_frame_for_client(const char *target_client_id, unsigned short width, unsigned short height,
                                          bool wants_stretch, size_t *out_size, bool *out_grid_changed,
                                          int *out_sources_count, acip_render_settings_t *out_rendering) {
  (void)wants_stretch; // Unused - we always handle aspect ratio ourselves
 
  // Register the stream counter once even when per-client render workers enter
  // this function concurrently.
  static _Atomic bool stream_atomics_registered = false;
  if (!atomic_exchange_explicit(&stream_atomics_registered, true, memory_order_acq_rel)) {
    NAMED_REGISTER_ATOMIC(&g_previous_active_video_count, "server_video_source_count_for_layout_detection", NULL);
  }
 
  uint64_t frame_gen_start_ns = time_get_ns();
 
  // Initialize output parameters
  if (out_grid_changed) {
    *out_grid_changed = false;
  }
  if (out_sources_count) {
    *out_sources_count = 0;
  }
 
  if (!out_size || width == 0 || height == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: width=%u, height=%u, out_size=%p", width, height, out_size);
    return NULL;
  }
 
  // Collect all active clients and their image sources
  image_source_t sources[MAX_CLIENTS];
  uint64_t collect_start_ns = time_get_ns();
  int source_count = collect_video_sources(sources, MAX_CLIENTS);
  uint64_t collect_end_ns = time_get_ns();
 
  // Count sources that actually have video data
  int sources_with_video = 0;
  for (int i = 0; i < source_count; i++) {
    if (sources[i].has_video && sources[i].image) {
      sources_with_video++;
    }
  }
 
  log_dev_every(333 * NS_PER_MS_INT, "FRAME_GEN_START: target_client=%s sources=%d collect=%.1fms", target_client_id,
                sources_with_video, (collect_end_ns - collect_start_ns) / NS_PER_MS);
 
  // Return the source count for debugging/tracking
  if (out_sources_count) {
    *out_sources_count = sources_with_video;
  }
 
  // GRID LAYOUT CHANGE DETECTION:
  // Check if the number of active video sources has changed
  // NOTE: We only UPDATE the count and SIGNAL the change via out parameter
  // Broadcasting CLEAR_CONSOLE must happen AFTER the new frames are written to buffers
  // to prevent race condition where CLEAR arrives before new frame is ready
  uint64_t previous_count = atomic_load_u64(&g_previous_active_video_count);
  if (sources_with_video != (int)previous_count) {
    // Use compare-and-swap to ensure only ONE thread detects the change
    if (atomic_cas_u64(&g_previous_active_video_count, &previous_count, (uint64_t)sources_with_video)) {
      log_dev_every(
          LOG_RATE_DEFAULT,
          "Grid layout changing: %d -> %d active video sources - caller will broadcast clear AFTER buffering frame",
          previous_count, sources_with_video);
      if (out_grid_changed) {
        *out_grid_changed = true; // Signal to caller
      }
    }
  }
 
  // No active video sources - don't generate placeholder frames
  image_t *composite = NULL;
 
  if (sources_with_video == 0) {
    *out_size = 0;
    // No active video sources for client - this isn't an error.
    // Return NULL to indicate no frame should be sent
    return NULL;
  }
 
  if (sources_with_video == 1) {
    // Single source handling - create composite and convert to ASCII
    // Note: create_single_source_composite returns a reference to sources[i].image
    // which could be modified by other threads. Make a copy to prevent concurrent
    // modification during ascii_convert_with_capabilities.
    image_t *single_source = create_single_source_composite(sources, source_count, target_client_id, width, height);
    if (single_source) {
      composite = image_new_copy(single_source);
      if (!composite) {
        SET_ERRNO(ERROR_MEMORY, "Failed to copy single source composite");
        *out_size = 0;
        return NULL;
      }
    }
  } else {
    // Multiple sources - create grid layout
    composite =
        create_multi_source_composite(sources, source_count, sources_with_video, target_client_id, width, height);
  }
 
  char *out = NULL;
 
  if (!composite) {
    SET_ERRNO(ERROR_INVALID_STATE, "Per-client %s: Failed to create composite image", target_client_id);
    *out_size = 0;
    return NULL;
  }
 
  // Convert composite to ASCII using client capabilities
  // Pass terminal dimensions so the frame can be padded to full width
  char *ascii_frame = convert_composite_to_ascii(composite, target_client_id, width, height, out_rendering, sources,
                                                 source_count, sources_with_video);
 
  if (ascii_frame) {
    // The frame should have been null-terminated by the padding functions.
    // Use strlen() which is optimized and reliable
    size_t ascii_len = strlen(ascii_frame);
 
    // Safety check: don't accept unreasonably large frames (10MB limit)
    if (ascii_len > 10 * 1024 * 1024) {
      log_error("Frame size exceeds 10MB safety limit (possible buffer overflow)");
      SET_ERRNO(ERROR_INVALID_PARAM, "Frame size exceeds 10MB");
      SAFE_FREE(ascii_frame);
      image_destroy(composite);
      *out_size = 0;
      return NULL;
    }
 
    *out_size = ascii_len; // Renderer owns complete rows; never truncate to a color reset.
 
    log_dev_every(LOG_RATE_SLOW, "Final frame size=%zu bytes for client %s", *out_size, target_client_id);
 
    // Debug: Log the last 50 bytes of the frame to see what's really there
    if (*out_size >= 50) {
      char hex_buf[SERVER_STREAM_HEX_BUFFER_SIZE] = {0};
      size_t hex_len = 0;
      const uint8_t *last_bytes = (const uint8_t *)ascii_frame + (*out_size - 50);
      for (int i = 0; i < 50 && hex_len < sizeof(hex_buf) - 5; i++) {
        hex_len += snprintf(hex_buf + hex_len, sizeof(hex_buf) - hex_len, "%02X ", last_bytes[i]);
      }
      log_dev_every(4500 * US_PER_MS_INT, "FRAME_LAST_50_BYTES (hex): %s", hex_buf);
 
      // Also log as ASCII for readability
      char ascii_buf[SERVER_STREAM_ASCII_BUFFER_SIZE] = {0};
      for (int i = 0; i < 50 && i < (int)sizeof(ascii_buf) - 1; i++) {
        if (last_bytes[i] >= 32 && last_bytes[i] < 127) {
          ascii_buf[i] = (char)last_bytes[i];
        } else if (last_bytes[i] == '\n') {
          ascii_buf[i] = 'N';
        } else if (last_bytes[i] == '\0') {
          ascii_buf[i] = '0';
        } else {
          ascii_buf[i] = '.';
        }
      }
      log_dev_every(4500 * US_PER_MS_INT, "FRAME_LAST_50_ASCII: %s", ascii_buf);
    }
 
    out = ascii_frame;
  } else {
    SET_ERRNO(ERROR_TERMINAL, "Per-client %s: Failed to convert image to ASCII", target_client_id);
    *out_size = 0;
  }
 
  if (composite) {
    image_destroy(composite);
  }
  for (int i = 0; i < source_count; i++) {
    if (sources[i].image) {
      image_destroy(sources[i].image);
    }
  }
 
  uint64_t frame_gen_end_ns = time_get_ns();
  uint64_t frame_gen_duration_ns = frame_gen_end_ns - frame_gen_start_ns;
  if (frame_gen_duration_ns > 10 * NS_PER_MS_INT) { // Log if > 10ms
    char duration_str[TIME_DURATION_BUFFER_SIZE];
    time_pretty((uint64_t)((double)frame_gen_duration_ns), -1, duration_str, sizeof(duration_str));
    log_warn_every(LOG_RATE_DEFAULT, "SLOW_FRAME_GENERATION: Client %s full frame gen took %s", target_client_id,
                   duration_str);
  }
 
  return out;
}
 
/* ============================================================================
 * Frame Queuing and Delivery Functions
 * ============================================================================
 */


bool any_clients_sending_video(void) {
  // LOCK OPTIMIZATION: Don't acquire rwlock - all fields we access are atomic
  // client_id, active, is_sending_video are all atomic variables
 
  // Iterate through all client slots
  for (int i = 0; i < MAX_CLIENTS; i++) {
    client_info_t *client = &g_client_manager.clients[i];
 
    // Skip uninitialized clients (atomic read)
    if (client->client_id[0] == '\0') {
      continue;
    }
 
    // Check if client is active and sending video (both atomic reads)
    bool is_active = atomic_load_bool(&client->active);
    bool is_sending = atomic_load_bool(&client->is_sending_video);
 
    if (is_active && is_sending) {
      return true;
    }
  }
 
  return false;
}