client_like.c

Go to the documentation of this file.

 
#include "session/client_like.h"
#include "session/capture.h"
#include "session/display.h"
#include "session/render.h"
#include <ascii-chat/terminal/fd/reader.h>
#include "../../client/audio.h"
 
#include <ascii-chat/media/source.h>
#include <ascii-chat/audio/audio.h>
#include <ascii-chat/video/webcam/webcam.h>
#include <ascii-chat/ui/splash.h>
#include <ascii-chat/ui/update_banner.h>
#include <ascii-chat/ui/keyboard_help.h>
#include <ascii-chat/debug/sync.h>
 
#include <ascii-chat/log/log.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/platform/abstraction.h>
#include <ascii-chat/platform/terminal.h>
#include <ascii-chat/util/url.h>
#include <ascii-chat/app_callbacks.h>
 
#include <string.h>
#include <ascii-chat/atomic.h>
 
// Forward declarations (implemented below)
static bool capture_should_exit_adapter(void *user_data);
static bool display_should_exit_adapter(void *user_data);
static bool session_client_like_is_networked(session_client_like_kind_t kind);
 
static asciichat_error_t validate_mirror_webcam_selection(const session_client_like_config_t *config) {
  if (!config || config->kind != SESSION_CLIENT_LIKE_KIND_MIRROR || !terminal_is_stdout_tty() ||
      GET_OPTION(test_pattern)) {
    return ASCIICHAT_OK;
  }
 
  const char *media_file = GET_OPTION(media_file);
  const char *media_url = GET_OPTION(media_url);
  if ((media_file && media_file[0] != '\0') || (media_url && media_url[0] != '\0')) {
    return ASCIICHAT_OK;
  }
 
  webcam_device_info_t *devices = NULL;
  unsigned int device_count = 0;
  asciichat_error_t result = webcam_list_devices(&devices, &device_count);
  if (result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_WEBCAM, "Unable to enumerate webcams before starting mirror mode");
  }
 
  unsigned int selected_index = (unsigned int)GET_OPTION(webcam_index);
  if (selected_index >= device_count) {
    if (device_count == 0) {
      result =
          SET_ERRNO(ERROR_WEBCAM, "Webcam index %u is unavailable: no webcam devices were found (run --list-webcams)",
                    selected_index);
    } else {
      result = SET_ERRNO(ERROR_WEBCAM,
                         "Webcam index %u is unavailable: %u webcam device(s) found; valid indices are 0-%u "
                         "(run --list-webcams)",
                         selected_index, device_count, device_count - 1);
    }
  } else {
    result = ASCIICHAT_OK;
  }
 
  webcam_free_device_list(devices);
  return result;
}
 
// Module-level config for adapter callbacks
static const session_client_like_config_t *g_current_config = NULL;
 
// Module-level adapter functions for render loop access
static bool (*g_render_should_exit)(void *) = NULL;
 
// Module-level stdin reader for ASCII-to-video rendering (stdin render mode only)
static terminal_fd_reader_t *g_stdin_reader = NULL;
 
/* ============================================================================
 * Public Accessors
 * ============================================================================ */
 
bool (*session_client_like_get_render_should_exit(void))(void *) {
  return g_render_should_exit;
}
 
terminal_fd_reader_t *session_client_like_get_stdin_reader(void) {
  return g_stdin_reader;
}
 
/* ============================================================================
 * Exit Condition Adapters
 * ============================================================================ */
 
static bool capture_should_exit_adapter(void *user_data) {
  (void)user_data;
  if (APP_CALLBACK_BOOL(should_exit)) {
    return true;
  }
  if (g_current_config && g_current_config->custom_should_exit) {
    return g_current_config->custom_should_exit(g_current_config->exit_user_data);
  }
  return false;
}
 
static bool display_should_exit_adapter(void *user_data) {
  (void)user_data;
  if (APP_CALLBACK_BOOL(should_exit)) {
    return true;
  }
  if (g_current_config && g_current_config->custom_should_exit) {
    return g_current_config->custom_should_exit(g_current_config->exit_user_data);
  }
  return false;
}
 
static bool session_client_like_is_networked(session_client_like_kind_t kind) {
  return kind == SESSION_CLIENT_LIKE_KIND_CLIENT || kind == SESSION_CLIENT_LIKE_KIND_DISCOVERY;
}
 
asciichat_error_t session_client_like_run(const session_client_like_config_t *config) {
  log_info("session_client_like_run: ENTRY");
  if (!config || !config->run_fn) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "config or run_fn is NULL");
  }
  log_info("session_client_like_run: config validated");
 
  // Store config globally for adapter callbacks
  g_current_config = config;
 
  // Store the render should_exit adapter globally so mode-specific run_fn can access it
  g_render_should_exit = display_should_exit_adapter;
 
  asciichat_error_t result = ASCIICHAT_OK;
 
  // Keep track of what's been initialized for cleanup
  session_capture_ctx_t *capture = NULL;
  session_display_ctx_t *display = NULL;
  audio_context_t *audio_ctx = NULL;
  media_source_t *probe_source = NULL;
  bool audio_available = false;
 
  // ============================================================================
  // SETUP: Terminal and Logging
  // ============================================================================
 
  log_debug("session_client_like_run(): Setting up terminal and logging");
 
  // Force stderr when stdout is piped (prevents ASCII corruption in output stream)
  bool should_force_stderr = terminal_should_force_stderr();
  log_debug("terminal_should_force_stderr()=%d", should_force_stderr);
 
  if (should_force_stderr) {
    // Redirect logs to stderr to prevent corruption of stdout (for pipes)
    // But keep terminal output enabled so we can see initialization errors
    log_set_force_stderr(true);
  }
 
  // Note: Force all logging to stderr if encoding to pipe to prevent corrupting binary video output
  // (implemented via should_force_stderr check above)
  const char *render_file_early = GET_OPTION(render_file);
  log_info("[CLIENT_LIKE_RUN] render_file_early=%s (ptr=%p)", render_file_early ? render_file_early : "(null)",
           (void *)render_file_early);
  if (render_file_early && render_file_early[0] != '\0' &&
      (strcmp(render_file_early, "-") == 0 || strcmp(render_file_early, "pipe:") == 0)) {
    log_info("--render-file=- will output binary video to stdout, logging sent to stderr");
  }
 
  // ============================================================================
  // SETUP: Keepawake System
  // ============================================================================
 
  log_debug("session_client_like_run(): Validating keepawake options");
 
  // Validate mutual exclusivity
  bool enable_ka = GET_OPTION(enable_keepawake);
  bool disable_ka = GET_OPTION(disable_keepawake);
  log_debug("enable_keepawake=%d, disable_keepawake=%d", enable_ka, disable_ka);
 
  if (enable_ka && disable_ka) {
    result = SET_ERRNO(ERROR_INVALID_PARAM, "--keepawake and --no-keepawake are mutually exclusive");
    goto cleanup;
  }
 
  log_debug("session_client_like_run(): Enabling keepawake if needed");
 
  // Enable keepawake unless explicitly disabled
  if (!disable_ka) {
    (void)platform_enable_keepawake();
  }
 
  log_debug("session_client_like_run(): Keepawake setup complete");
 
  result = validate_mirror_webcam_selection(config);
  if (result != ASCIICHAT_OK) {
    goto cleanup;
  }
 
  // ============================================================================
  // SETUP: Display Context (before splash for unified TTY initialization)
  // ============================================================================
 
  // Create display context early to share TTY initialization between splash and rendering
  // This prevents double TTY init which was corrupting the terminal state
  session_display_config_t display_config = {0};
  display_config.snapshot_mode = GET_OPTION(snapshot_mode);
  display_config.palette_type = GET_OPTION(palette_type);
  display_config.custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL;
  display_config.color_mode = TERM_COLOR_AUTO;
  display_config.should_exit_callback = display_should_exit_adapter;
  display_config.callback_data = NULL;
  display_config.defer_render_file = true;
 
  log_debug("[SETUP_DISPLAY_EARLY] Creating display context (before splash)");
  display = session_display_create(&display_config);
  if (!display) {
    log_debug("[SETUP_DISPLAY_EARLY] session_display_create() returned NULL");
    log_fatal("Failed to initialize display context");
    result = ERROR_DISPLAY;
    goto cleanup;
  }
  log_debug("[SETUP_DISPLAY_EARLY] Display context created, will use for splash");
 
  // Register global display context for signal handlers (Ctrl+C help screen closure)
  // This makes the context available to signal handlers for the entire app lifetime
  session_display_set_global_context(display);
 
  // ============================================================================
  // SETUP: Splash Screen (using unified display context)
  // ============================================================================
 
  log_debug("session_client_like_run(): Starting splash with display context");
 
  // Use the display context we just created for splash animation
  splash_intro_start(display);
  log_debug("session_client_like_run(): splash_intro_start() returned");
  if (splash_is_running()) {
    log_set_terminal_output(false);
  }
 
  // Detect if we're using media vs webcam (needed for splash timing)
  const char *media_url = GET_OPTION(media_url);
  const char *media_file = GET_OPTION(media_file);
  bool has_media = (media_url && strlen(media_url) > 0) || (media_file && strlen(media_file) > 0);
 
  // Show splash briefly for webcam, but skip sleep for media (which takes time anyway)
  if (!has_media && !GET_OPTION(snapshot_mode)) {
    APP_CALLBACK_VOID(platform_pump_events);
    APP_CALLBACK_VOID_UINT(platform_sleep_ms, 250);
  }
  log_debug("session_client_like_run(): After splash sleep");
 
  // Restore stderr now that splash animation and post-splash logging are done
  // This allows logs to appear on screen again after this point
  splash_restore_stderr();
 
  // Wait for background update check to finish and show prompt if update available
  update_banner_wait_for_check();
  if (update_banner_has_update() && !GET_OPTION(snapshot_mode)) {
    bool wants_update = update_banner_show_prompt(display);
    if (wants_update) {
      update_banner_print_instructions();
      return ASCIICHAT_OK;
    }
    terminal_clear_screen();
  }
 
  // ============================================================================
  // SETUP: Terminal Logging in Snapshot Mode
  // ============================================================================
 
  log_debug("session_client_like_run(): About to disable terminal logging (snapshot=%d, discovery=%d)",
            GET_OPTION(snapshot_mode), config->discovery != NULL);
  // For discovery mode, skip disabling logging initially - we'll handle it after role is determined
  // Discovery participants should show logs, only hosts should have logs disabled for rendering
  bool should_disable_logging = !GET_OPTION(snapshot_mode) && (config->discovery == NULL);
  if (should_disable_logging) {
    log_debug("session_client_like_run(): Calling log_set_terminal_output(false)...");
    log_set_terminal_output(false);
    log_debug("session_client_like_run(): RETURNED from log_set_terminal_output(false)");
  } else {
    log_debug("session_client_like_run(): Skipping log disable (snapshot=%d or discovery=%d)",
              GET_OPTION(snapshot_mode), config->discovery != NULL);
  }
  log_debug("session_client_like_run(): Terminal logging setup complete, starting media source setup");
 
  // ============================================================================
  // SETUP: Media Source Selection and FPS Probing
  // ============================================================================
 
  log_debug("session_client_like_run(): Initializing capture config");
  session_capture_config_t capture_config = {0};
  capture_config.resize_for_network = config->kind == SESSION_CLIENT_LIKE_KIND_DISCOVERY;
  capture_config.should_exit_callback = capture_should_exit_adapter;
  capture_config.callback_data = NULL;
 
  // Determine FPS explicitly set by user
  log_debug("session_client_like_run(): Getting FPS option");
  int user_fps = GET_OPTION(fps);
  bool fps_explicitly_set = GET_OPTION(fps_explicitly_set);
  log_debug("session_client_like_run(): FPS=%d (explicitly_set=%d)", user_fps, fps_explicitly_set);
 
  // Select media source based on options (priority order)
  log_debug("session_client_like_run(): Getting media_url option");
  const char *media_url_val = GET_OPTION(media_url);
  log_debug("session_client_like_run(): Getting media_file option");
  const char *media_file_val = GET_OPTION(media_file);
  log_debug("session_client_like_run(): media_url=%s, media_file=%s", media_url_val ? media_url_val : "(null)",
            media_file_val ? media_file_val : "(null)");
 
  if (media_url_val && strlen(media_url_val) > 0) {
    // Network URL takes priority
    log_info("Using network URL: %s (webcam disabled)", media_url_val);
    capture_config.type = MEDIA_SOURCE_FILE;
    capture_config.path = media_url_val;
    capture_config.loop = false; // Network URLs cannot be looped
 
    if (fps_explicitly_set) {
      capture_config.target_fps = (uint32_t)user_fps;
      log_info("Using user-specified FPS: %u", capture_config.target_fps);
    } else {
      // Always probe FPS for HTTP URLs, even in snapshot mode
      // (snapshot mode needs correct FPS to capture right number of frames during snapshot_delay window)
      log_debug("Probing FPS for HTTP URL");
      probe_source = media_source_create(MEDIA_SOURCE_FILE, media_url_val);
      if (probe_source) {
        double url_fps = media_source_get_video_fps(probe_source);
        log_info("Detected HTTP stream video FPS: %.1f", url_fps);
        if (url_fps > 0.0) {
          capture_config.target_fps = (uint32_t)(url_fps + 0.5);
        } else {
          log_warn("FPS detection failed for HTTP stream, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      } else {
        log_warn("Failed to create probe source for HTTP stream, using default 60 FPS");
        capture_config.target_fps = 60;
      }
    }
  } else if (media_file_val && strlen(media_file_val) > 0) {
    // Local file or stdin
    log_info("DEBUG: media_file_val='%s', strcmp result=%d", media_file_val, strcmp(media_file_val, "-"));
    if (strcmp(media_file_val, "-") == 0) {
      log_info("Using stdin for media streaming (webcam disabled)");
      capture_config.type = MEDIA_SOURCE_STDIN;
      capture_config.path = NULL;
      capture_config.loop = false;
      if (fps_explicitly_set) {
        capture_config.target_fps = (uint32_t)user_fps;
      } else {
        log_debug("Probing FPS from buffered stdin media");
        probe_source = media_source_create(MEDIA_SOURCE_STDIN, NULL);
        if (probe_source) {
          double stdin_fps = media_source_get_video_fps(probe_source);
          log_info("Detected stdin video FPS: %.1f", stdin_fps);
          capture_config.target_fps = stdin_fps > 0.0 ? (uint32_t)(stdin_fps + 0.5) : 60;
        } else {
          log_warn("Failed to probe stdin FPS, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      }
    } else {
      log_info("Using media file: %s (webcam disabled)", media_file_val);
      capture_config.type = MEDIA_SOURCE_FILE;
      capture_config.path = media_file_val;
      capture_config.loop = GET_OPTION(media_loop);
 
      if (fps_explicitly_set) {
        capture_config.target_fps = (uint32_t)user_fps;
        log_info("Using user-specified FPS: %u", capture_config.target_fps);
      } else {
        // Always probe FPS for local files, even in snapshot mode
        // (snapshot mode needs correct FPS to capture right number of frames during snapshot_delay window)
        log_debug("Probing FPS for local file");
        probe_source = media_source_create(MEDIA_SOURCE_FILE, media_file_val);
        if (probe_source) {
          double file_fps = media_source_get_video_fps(probe_source);
          log_info("Detected file video FPS: %.1f", file_fps);
          if (file_fps > 0.0) {
            capture_config.target_fps = (uint32_t)(file_fps + 0.5);
          } else {
            log_warn("FPS detection failed, using default 60 FPS");
            capture_config.target_fps = 60;
          }
        } else {
          log_warn("Failed to create probe source for FPS detection, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      }
    }
  } else if (GET_OPTION(test_pattern)) {
    // Test pattern
    log_debug("session_client_like_run(): Using test pattern");
    log_info("Using test pattern");
    capture_config.type = MEDIA_SOURCE_TEST;
    capture_config.path = NULL;
    capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
    capture_config.loop = false;
  } else {
    // Default: Try webcam if stdout is a TTY, otherwise use test pattern
    // (webcam + piped output often fails, test pattern is reliable fallback)
    bool stdout_is_tty = terminal_is_stdout_tty();
    if (stdout_is_tty) {
      // Normal terminal mode: use webcam
      log_debug("session_client_like_run(): Stdout is TTY, using local webcam");
      log_info("Using local webcam");
      capture_config.type = MEDIA_SOURCE_WEBCAM;
      static char webcam_index_str[32];
      safe_snprintf(webcam_index_str, sizeof(webcam_index_str), "%u", GET_OPTION(webcam_index));
      capture_config.path = webcam_index_str;
      log_info("Using webcam device index %u", GET_OPTION(webcam_index));
      capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
      capture_config.loop = false;
    } else {
      // Piped output mode: use test pattern (webcam + pipes often fails)
      log_debug("session_client_like_run(): Stdout is piped, defaulting to test pattern for reliability");
      log_info("Stdout is piped - using test pattern instead of webcam");
      capture_config.type = MEDIA_SOURCE_TEST;
      capture_config.path = NULL;
      capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
      capture_config.loop = false;
    }
  }
 
  // Apply initial seek if specified
  log_debug("session_client_like_run(): Getting media_seek_timestamp option");
  capture_config.initial_seek_timestamp = GET_OPTION(media_seek_timestamp);
  log_debug("session_client_like_run(): Media seek timestamp set");
 
  // Clean up probe source (don't reuse for actual capture)
  if (probe_source) {
    log_debug("session_client_like_run(): Destroying probe source");
    media_source_destroy(probe_source);
    probe_source = NULL;
    log_debug("session_client_like_run(): Probe source destroyed");
  } else {
    log_debug("session_client_like_run(): No probe source to destroy");
  }
 
  // Pass probed FPS to display context for correct render-file duration
  if (capture_config.target_fps > 0) {
    session_display_set_render_fps(display, capture_config.target_fps);
    log_debug("session_client_like_run(): Set display render FPS to %u for correct video encoding duration",
              capture_config.target_fps);
  }
 
  asciichat_error_t render_init_result = session_display_init_render_file(display, capture_config.target_fps);
  if (render_init_result != ASCIICHAT_OK) {
    result = render_init_result;
    goto cleanup;
  }
 
  // ============================================================================
  // SETUP: Network Transports (TCP/WebSocket)
  // ============================================================================
 
  log_debug("session_client_like_run(): Setting up network transports");
 
  bool networked_mode = session_client_like_is_networked(config->kind);
 
  switch (config->kind) {
  case SESSION_CLIENT_LIKE_KIND_MIRROR:
    log_debug("Mirror mode detected - will use local capture with media source");
    break;
  case SESSION_CLIENT_LIKE_KIND_CLIENT:
    log_debug("Client/Network mode detected - will use network capture without local media source");
    break;
  case SESSION_CLIENT_LIKE_KIND_DISCOVERY:
    log_debug("Discovery mode detected - discovery session will manage networking");
    break;
  }
 
  // ============================================================================
  // SETUP: Capture Context
  // ============================================================================
 
  // Check for stdin render mode: read ASCII frames from stdin, render to video
  // Only enable stdin render mode if:
  // 1. render-file is "-" (output to stdout)
  // 2. stdin is not a TTY
  // 3. --height is explicitly specified (user must opt-in to stdin render mode)
  // 4. NO media source is being used (not reading from file/URL/test-pattern)
  // This prevents accidental activation when piping to other processes or using mirror mode
  const char *render_file_opt = GET_OPTION(render_file);
  int frame_height = GET_OPTION(height);
  bool height_explicitly_set = (frame_height != OPT_HEIGHT_DEFAULT);
  bool has_media_source = (media_url_val && strlen(media_url_val) > 0) ||
                          (media_file_val && strlen(media_file_val) > 0) || GET_OPTION(test_pattern);
 
  // Enable audio capture if render-file is active and media source exists
  if (render_file_opt && strlen(render_file_opt) > 0 && has_media_source) {
    capture_config.enable_audio = true;
    log_debug("Audio capture enabled for render-file encoding");
  }
 
  bool stdin_render_mode =
      (render_file_opt && strcmp(render_file_opt, "-") == 0 && !terminal_is_stdin_tty() && height_explicitly_set &&
       !has_media_source && config->kind != SESSION_CLIENT_LIKE_KIND_MIRROR);
 
  if (stdin_render_mode) {
    // Stdin render mode: read ASCII frames from stdin, output video to stdout
    log_info("Stdin render mode enabled: reading ASCII frames from stdin, output to stdout");
 
    // Get frame dimensions (--height must be explicitly set to reach here)
    int frame_width = GET_OPTION(width);
 
    // Validate stdin render mode constraints (--height is already validated above since height_explicitly_set is true)
    bool width_was_explicitly_set = (frame_width != OPT_WIDTH_DEFAULT);
 
    if (width_was_explicitly_set) {
      result = SET_ERRNO(ERROR_USAGE, "Stdin render mode does not accept --width (auto-detected from frames).\n"
                                      "Only specify: --height <rows>");
      goto cleanup;
    }
 
    asciichat_error_t stdin_err = terminal_fd_reader_create(STDIN_FILENO, frame_height, &g_stdin_reader);
    if (stdin_err != ASCIICHAT_OK) {
      log_fatal("Failed to initialize stdin frame reader: %s", asciichat_error_string(stdin_err));
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
 
    // For stdin render mode, create a minimal capture context for compatibility
    int fps = GET_OPTION(fps);
    capture = session_network_capture_create((uint32_t)(fps > 0 ? fps : 60));
    if (!capture) {
      log_fatal("Failed to initialize capture context for stdin rendering");
      terminal_fd_reader_destroy(g_stdin_reader);
      g_stdin_reader = NULL;
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
 
    log_info("stdin render mode: reading %d-line frames from stdin, auto-detecting width", frame_height);
  }
 
  // Choose capture type based on mode determined earlier:
  // - Mirror mode: needs to capture local media (webcam, file, test pattern)
  // - Network modes (client/discovery): receive frames from network, no local capture
  // Discovery peers may use a local media source (for example the synthetic
  // test pattern used by headless WebRTC tests) as their outgoing stream.
  // Keep the network-only capture for ordinary client mode, but do not discard
  // an explicitly requested source before the discovery transport is active.
  bool discovery_has_local_source = config->kind == SESSION_CLIENT_LIKE_KIND_DISCOVERY;
  if (!stdin_render_mode && networked_mode && !discovery_has_local_source) {
    // Network mode: create minimal capture context without media source
    log_debug("Network mode detected - using network capture (no local media source)");
    int fps = GET_OPTION(fps);
    uint64_t net_cap_start = time_get_ns();
    capture = session_network_capture_create((uint32_t)(fps > 0 ? fps : 60));
    double net_cap_ms = time_ns_to_ms(time_elapsed_ns(net_cap_start, time_get_ns()));
    log_info("★ INIT_CHECKPOINT: Network capture created in %.1f ms", net_cap_ms);
    if (!capture) {
      log_fatal("Failed to initialize network capture context");
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
    if (fps > 0) {
      log_debug("Network capture FPS set to %d from options", fps);
    }
  }
 
  // ============================================================================
  // SETUP: Audio Context
  // ============================================================================
 
  // Skip audio for immediate snapshots
  bool should_init_audio = GET_OPTION(audio_enabled);
  if (GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0) {
    should_init_audio = false;
    log_debug("Skipping audio initialization for immediate snapshot");
  }
 
  // Pass stdin_reader to display if in stdin render mode
  if (stdin_render_mode && g_stdin_reader) {
    session_display_set_stdin_reader(display, g_stdin_reader);
    log_debug("stdin_reader passed to display context");
  }
 
  // ============================================================================
  // SETUP: End Splash Screen
  // ============================================================================
  log_debug("[SETUP_SPLASH] About to end splash screen");
 
  // The splash screen will display during initialization and exit when done.
  // The initialization process (media probing, display setup, etc.) naturally
  // takes time, keeping the splash visible. The splash is kept alive during
  // connection attempts (TCP and WebSocket) to prevent a blank screen during
  // network operations. splash_intro_done() is called only after a successful
  // connection is established.
 
  log_debug("[SETUP_SPLASH] Splash will remain visible during connection attempts");
 
  // Exit early if shutdown was requested (e.g., user pressed Ctrl-C)
  if (APP_CALLBACK_BOOL(should_exit)) {
    log_debug("[SETUP] Shutdown requested, exiting early");
    log_debug("[SETUP_SPLASH] Ending splash due to early shutdown request");
    splash_intro_done();
    splash_wait_for_animation();
    result = ASCIICHAT_OK;
    goto cleanup;
  }
 
  // Wait for splash animation to finish before proceeding to render loop
  // (splash_anim thread uses the display, must not be disrupted before cleanup)
  // But skip for immediate snapshots (snapshot-delay=0) which need to output first frame immediately
  // For discovery mode, keep the splash running - it stays visible while waiting for peers
  if (config->discovery == NULL) {
    splash_intro_done();
    if (!(GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0)) {
      splash_wait_for_animation();
    }
  } else {
    log_debug("[SETUP_SPLASH] Discovery mode: keeping splash visible while waiting for peers");
  }
 
  // ============================================================================
  // SETUP: Create Mirror Capture (after splash screen finishes)
  // ============================================================================
 
  log_info("[MIRROR_CHECK] stdin_render_mode=%d, capture=%p", stdin_render_mode, (void *)capture);
  if (!stdin_render_mode && !capture) {
    // Mirror mode: create capture context with local media source (NOW, after splash finishes)
    log_info("Mirror mode detected - creating mirror capture after splash screen");
    uint64_t mirror_cap_start = time_get_ns();
    capture = session_mirror_capture_create(&capture_config);
    double mirror_cap_ms = time_ns_to_ms(time_elapsed_ns(mirror_cap_start, time_get_ns()));
    log_info("★ INIT_CHECKPOINT: Mirror capture created in %.1f ms (after splash)", mirror_cap_ms);
    if (!capture) {
      log_fatal("Failed to initialize mirror capture source");
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
  }
 
  if (should_init_audio && config->kind == SESSION_CLIENT_LIKE_KIND_MIRROR) {
    media_source_t *source = session_capture_get_media_source(capture);
    bool file_audio = media_source_has_audio(source);
    bool record_mic = render_file_opt && render_file_opt[0] && !file_audio;
    if (file_audio || record_mic) {
      audio_ctx = SAFE_CALLOC(1, sizeof(*audio_ctx), audio_context_t *);
      if (audio_init(audio_ctx) == ASCIICHAT_OK) {
        audio_available = true;
        if (file_audio && GET_OPTION(audio_capture_source) != AUDIO_CAPTURE_SOURCE_MIC)
          audio_ctx->capture_media_source = source;
        audio_ctx->monitor_local_media = true;
        audio_ctx->playback_only = !audio_should_enable_microphone(GET_OPTION(audio_capture_source), file_audio);
        session_capture_set_audio_context(capture, audio_ctx);
        media_source_set_audio_context(source, audio_ctx);
      } else {
        SAFE_FREE(audio_ctx);
      }
    }
  }
 
  // ============================================================================
  // SETUP: Start Audio Playback
  // ============================================================================
 
  log_debug("[SETUP_AUDIO] About to check audio context for duplex");
  if (audio_ctx && audio_available) {
    log_debug("[SETUP_AUDIO] Starting audio duplex");
    if (audio_start_duplex(audio_ctx) == ASCIICHAT_OK) {
      log_info("Audio playback started");
    } else {
      log_warn("Failed to start audio duplex");
      session_capture_set_audio_context(capture, NULL);
      media_source_set_audio_context(session_capture_get_media_source(capture), NULL);
      audio_destroy(audio_ctx);
      SAFE_FREE(audio_ctx);
      audio_ctx = NULL;
      audio_available = false;
    }
  }
 
  log_info("[MARKER] Audio setup complete at line 614");
  log_info("[SETUP_COMPLETE] All setup complete, about to start connection loop");
 
  // ============================================================================
  // RUN: Mode-Specific Main Loop with Reconnection
  // ============================================================================
 
  // Connection/attempt loop - wraps run_fn with reconnection logic
  int attempt = 0;
  int max_attempts = config->max_reconnect_attempts;
 
  log_info("[CLIENT_LIKE_LOOP] Starting connection loop, max_attempts=%d", max_attempts);
 
  while (true) {
    attempt++;
 
    result = config->run_fn(capture, display, config->run_user_data);
 
    // Exit immediately if run_fn succeeded
    if (result == ASCIICHAT_OK) {
      // Connection succeeded - splash screen cleanup now happens when first frame renders
      // This ensures the splash stays visible during TCP/WebSocket/datachannel connection attempts
 
      break;
    }
 
    // Check if we should attempt reconnection
    bool should_retry = false;
 
    if (max_attempts != 0) { // max_attempts == 0 means no retries
      // Check custom reconnect logic if provided
      if (config->should_reconnect_callback) {
        should_retry = config->should_reconnect_callback(result, attempt, config->reconnect_user_data);
      } else {
        should_retry = true; // Default: always retry
      }
 
      // Check retry limits if still planning to retry
      if (should_retry && max_attempts > 0 && attempt >= max_attempts) {
        log_debug("Reached maximum reconnection attempts (%d), giving up", max_attempts);
        should_retry = false;
      }
    }
 
    // If not retrying or shutdown requested, exit loop
    if (!should_retry || APP_CALLBACK_BOOL(should_exit)) {
      break;
    }
 
    // Reconnection will happen - show splash screen during reconnection attempt
    // Reset first_frame flag so splash cleanup runs on next successful connection
    session_display_reset_first_frame(display);
 
    // splash_intro_start() handles all the logic:
    // - If splash should display: shows splash and disables console logging
    // - If splash shouldn't display: restores stderr and returns without changing logging state
    splash_intro_start(display);
 
    // Log reconnection message
    if (max_attempts == -1) {
      log_info("Connection failed, retrying...");
    } else if (max_attempts > 0) {
      log_info("Connection failed, retrying (attempt %d/%d)...", attempt + 1, max_attempts);
    }
 
    // Apply reconnection delay if configured
    // Check APP_CALLBACK_BOOL(should_exit) frequently during sleep so SIGTERM can interrupt reconnection attempts
    if (config->reconnect_delay_ms > 0) {
      unsigned int remaining_ms = config->reconnect_delay_ms;
      const unsigned int check_interval_ms = 100; // Check exit flag every 100ms
 
      while (remaining_ms > 0 && !APP_CALLBACK_BOOL(should_exit)) {
        unsigned int sleep_ms = (remaining_ms < check_interval_ms) ? remaining_ms : check_interval_ms;
        APP_CALLBACK_VOID(platform_pump_events);
        APP_CALLBACK_VOID_UINT(platform_sleep_ms, sleep_ms);
        remaining_ms -= sleep_ms;
      }
    }
 
    // Continue loop to retry
  }
 
  // ============================================================================
  // CLEANUP (always runs, even on error)
  // ============================================================================
 
cleanup:
  // Re-enable terminal output for shutdown logs
  log_set_terminal_output(true);
 
  g_current_config = NULL;
  g_render_should_exit = NULL;
 
#ifndef NDEBUG
  // Join the registry inspector before freeing the session's synchronization objects.
  debug_sync_cleanup_thread();
#endif
 
  // Stop audio thread before destroying audio context to prevent use-after-free
  // The audio worker thread may still be logging when we destroy the buffer
  APP_CALLBACK_VOID(audio_stop_thread);
 
  // Stop streams before releasing the local media source.
  if (audio_ctx) {
    audio_stop_duplex(audio_ctx);
    audio_destroy(audio_ctx);
    SAFE_FREE(audio_ctx);
    audio_ctx = NULL;
  }
 
  // Destroy display (check global context to see if discovery mode already destroyed it)
  // Discovery participant mode may destroy the display early and clear the global context
  session_display_ctx_t *current_global = session_display_get_global_context();
  if (display && display == current_global) {
    // Display is still valid (not destroyed by discovery mode)
    session_display_destroy(display);
    display = NULL;
  } else if (display && display != current_global) {
    // Display was already destroyed (by discovery participant mode)
    // Just NULL it out, don't call destroy again
    log_debug("[CLEANUP] Display was already destroyed by discovery mode, skipping destroy");
    display = NULL;
  }
 
  // Destroy capture
  if (capture) {
    session_capture_destroy(capture);
    capture = NULL;
  }
 
  // Destroy stdin reader if active (stdin render mode)
  if (g_stdin_reader) {
    terminal_fd_reader_destroy(g_stdin_reader);
    g_stdin_reader = NULL;
  }
 
  // Clean up probe source if still allocated (shouldn't happen, but be safe)
  if (probe_source) {
    media_source_destroy(probe_source);
    probe_source = NULL;
  }
 
  // Stop splash animation and enforce minimum display time (even on error path)
  // But skip completely if shutting down - don't interact with splash at all during shutdown
  // The animation thread will exit on its own when it detects shutdown_is_requested()
  // For discovery mode, keep the splash running - it stays visible while waiting for peers
  if (config->discovery != NULL) {
    log_debug("[CLEANUP] Discovery mode: keeping splash alive for peer waiting UI");
  } else if (!APP_CALLBACK_BOOL(should_exit)) {
    log_debug("[CLEANUP] About to call splash_intro_done()");
    splash_intro_done();
    log_debug("[CLEANUP] splash_intro_done() returned");
 
    // Wait for animation thread to exit before cleanup
    log_debug("[CLEANUP] About to call splash_wait_for_animation()");
    splash_wait_for_animation();
    log_debug("[CLEANUP] splash_wait_for_animation() returned");
  } else {
    log_debug("[CLEANUP] Skipping all splash operations (shutdown in progress)");
    // During shutdown, don't interact with splash - let animation thread exit naturally
    // and don't wait for it (prevents blocking on signals)
  }
 
  // Disable keepawake (re-allow OS to sleep)
  log_debug("[CLEANUP] Disabling keepawake");
  platform_disable_keepawake();
  log_debug("[CLEANUP] keepawake disabled");
 
  // Write newline to separate final frame from prompt (if configured)
  log_debug("About to check print_newline_on_tty_exit");
  if (config->print_newline_on_tty_exit && terminal_is_stdout_tty()) {
    log_debug("Writing newline");
    const char newline = '\n';
    (void)platform_write_all(STDOUT_FILENO, &newline, 1);
  }
 
  log_set_terminal_output(false);
 
  return result;
}