terminal_screen.h File Reference

Reusable "fixed header + scrolling logs" terminal screen abstraction. More...

Go to the source code of this file.

Data Structures
struct	terminal_screen_config_t
	Configuration for terminal screen rendering. More...

Typedefs
typedef struct session_log_buffer	session_log_buffer_t
typedef void(*	terminal_screen_header_fn) (frame_buffer_t *buf, terminal_size_t term_size, void *user_data)
	Callback to render the fixed header portion of the screen.

Functions
void	terminal_screen_render (const terminal_screen_config_t *config)
	Render a terminal screen with fixed header and scrolling logs.
void	terminal_screen_cleanup (void)
	Clean up terminal screen resources.
session_log_buffer_t *	terminal_screen_log_init (void)
	Initialize session log buffer for terminal screens.
void	terminal_screen_log_destroy (void)
	Standard log cleanup for terminal screens.
void	terminal_screen_log_clear (void)
	Clear buffered logs for terminal screens.
session_log_buffer_t *	terminal_screen_get_log_buffer (void)
	Get the current session log buffer.
void	terminal_screen_set_output_fd (int fd)
	Set output file descriptor for terminal screens (splash/status)

Detailed Description

Reusable "fixed header + scrolling logs" terminal screen abstraction.

Provides a common pattern for rendering terminal screens with:

• Fixed header area (caller-defined via callback)
• Scrolling log feed below header (automatically managed)
• Terminal size caching to avoid error log spam
• ANSI-aware line wrapping using display_width()
• Latest log at bottom (standard terminal behavior)

Definition in file terminal_screen.h.

Typedef Documentation

session_log_buffer_t

typedef struct session_log_buffer session_log_buffer_t

Definition at line 21 of file terminal_screen.h.

terminal_screen_header_fn

typedef void(* terminal_screen_header_fn) (frame_buffer_t *buf, terminal_size_t term_size, void *user_data)

Callback to render the fixed header portion of the screen.

Parameters

buf	Frame buffer to write header content into (via frame_buffer_printf, etc.)
term_size	Current terminal dimensions (cached, refreshed every 1 second)
user_data	Caller-provided context data

The callback should:

• Append exactly the number of lines specified in terminal_screen_config_t.fixed_header_lines
• Use display_width() to ensure lines don't exceed term_size.cols
• Write to buf parameter (frame_buffer_printf, frame_buffer_append)
• NOT clear the screen (terminal_screen_render does that)
• NOT print the final newline if it would be line N+1 (causes scroll)

Definition at line 37 of file terminal_screen.h.

Function Documentation

terminal_screen_cleanup()

void terminal_screen_cleanup

(

void

)

Clean up terminal screen resources.

Destroys the internal static frame buffer allocated by terminal_screen_render(). Call at program exit or when terminal screen rendering is no longer needed.

Definition at line 466 of file terminal_screen.c.

                                   {
  if (g_frame_buf) {
    frame_buffer_destroy(g_frame_buf);
    g_frame_buf = NULL;
  }
}

References frame_buffer_destroy().

Referenced by asciichat_shared_destroy().

terminal_screen_get_log_buffer()

session_log_buffer_t * terminal_screen_get_log_buffer

(

void

)

Get the current session log buffer.

Returns the log buffer owned by this module, or NULL if not initialized. Used by splash/status screens to register with the logger.

Returns

Pointer to log buffer, or NULL

Definition at line 495 of file terminal_screen.c.

                                                           {
  return g_session_log_buffer;
}

terminal_screen_log_clear()

void terminal_screen_log_clear

(

void

)

Clear buffered logs for terminal screens.

Clears all previously captured log entries from the buffer. Useful when transitioning between screens to start fresh.

Definition at line 489 of file terminal_screen.c.

                                     {
  if (g_session_log_buffer) {
    session_log_buffer_clear(g_session_log_buffer);
  }
}

References session_log_buffer_clear().

Referenced by splash_log_clear(), ui_mdns_log_clear(), and ui_status_log_clear().

terminal_screen_log_destroy()

void terminal_screen_log_destroy

(

void

)

Standard log cleanup for terminal screens.

Destroys the session log buffer after screens are done rendering.

Definition at line 482 of file terminal_screen.c.

                                       {
  if (g_session_log_buffer) {
    session_log_buffer_destroy(g_session_log_buffer);
    g_session_log_buffer = NULL;
  }
}

References session_log_buffer_destroy().

Referenced by splash_log_destroy(), ui_mdns_log_destroy(), and ui_status_log_destroy().

terminal_screen_log_init()

session_log_buffer_t * terminal_screen_log_init

(

void

)

Initialize session log buffer for terminal screens.

Creates a new session log buffer owned by this module. Splash and status screens use this buffer to display logs.

Returns

Pointer to created buffer, or NULL on failure

Definition at line 473 of file terminal_screen.c.

                                                     {
  if (g_session_log_buffer) {
    return g_session_log_buffer; // Already initialized
  }
 
  g_session_log_buffer = session_log_buffer_create();
  return g_session_log_buffer;
}

References session_log_buffer_create().

Referenced by splash_log_init(), ui_mdns_log_init(), and ui_status_log_init().

terminal_screen_render()

void terminal_screen_render

(

const terminal_screen_config_t *

config

)

Render a terminal screen with fixed header and scrolling logs.

Renders a screen following the pattern:

1. Clear screen and move cursor to home (both stdout and stderr)
2. Call render_header() callback to draw fixed header
3. Calculate log area: rows - fixed_header_lines - 1 (prevent scroll)
4. Fetch recent logs from session_log_buffer
5. Calculate which logs fit (working backwards, accounting for wrapping)
6. Display logs chronologically (oldest to newest, latest at bottom)
7. Fill remaining lines to prevent terminal scroll
8. Flush stdout

Parameters

config

Screen configuration (header callback, line count, etc.)

Terminal size is cached internally with 1-second refresh interval to avoid flooding error logs if terminal size checks fail repeatedly.

Definition at line 107 of file terminal_screen.c.

                                                                    {
  // Validate config
  if (!config || !config->render_header) {
    return;
  }
 
  // Track startup timing (first 500ms)
  static bool first_render = true;
  if (first_render) {
    g_render_start_time_ns = platform_get_monotonic_time_us() * 1000;
    first_render = false;
  }
 
  uint64_t now_ns = platform_get_monotonic_time_us() * 1000;
  uint64_t elapsed_ms = (now_ns - g_render_start_time_ns) / 1000000;
 
  // Ensure cursor is visible for log-only UI (splash, status screens)
  (void)terminal_cursor_show();
 
  // Update terminal size (cached with 1-second refresh interval)
  // Always check on first call (when still at default 24x80) to get correct dimensions immediately
  uint64_t now_us = platform_get_monotonic_time_us();
  bool should_check = (g_cached_term_size.rows == 24 && g_cached_term_size.cols == 80) ||
                      (now_us - g_last_term_size_check_us >= TERM_SIZE_CHECK_INTERVAL_US);
 
  if (should_check) {
    terminal_size_t new_size = {0};
 
    // PRIORITY 1: COLUMNS and ROWS environment variables (most reliable, user-controlled)
    const char *cols_env = SAFE_GETENV("COLUMNS");
    const char *rows_env = SAFE_GETENV("ROWS");
    if (cols_env && rows_env) {
      char *endptr;
      errno = 0;
      long cols_val = strtol(cols_env, &endptr, 10);
      if (*endptr == '\0' && errno == 0 && cols_val > 0 && cols_val <= INT_MAX) {
        int cols = (int)cols_val;
        errno = 0;
        long rows_val = strtol(rows_env, &endptr, 10);
        if (*endptr == '\0' && errno == 0 && rows_val > 0 && rows_val <= INT_MAX) {
          int rows = (int)rows_val;
          new_size.cols = cols;
          new_size.rows = rows;
        } else {
          log_error("terminal_screen_render: Invalid ROWS value: %s", rows_env);
        }
      } else {
        log_error("terminal_screen_render: Invalid COLUMNS value: %s", cols_env);
      }
    }
 
    // PRIORITY 2: Options-provided width/height (explicit user settings)
    if (new_size.cols == 0 || new_size.rows == 0) {
      const options_t *opts = options_get();
      if (opts && opts->width > 0 && opts->height > 0) {
        new_size.cols = opts->width;
        new_size.rows = opts->height;
      }
    }
 
    // PRIORITY 3: Terminal auto-detection
    if (new_size.cols == 0 || new_size.rows == 0) {
      if (terminal_get_size(&new_size) != ASCIICHAT_OK) {
        // If terminal detection fails, use defaults
        new_size.cols = 80;
        new_size.rows = 24;
      }
    }
 
    if (new_size.cols > 0 && new_size.rows > 0) {
      g_cached_term_size = new_size;
    }
    g_last_term_size_check_us = now_us;
  }
 
  bool grep_entering = log_search_is_entering();
 
  // When transitioning out of grep mode, clear the log cache so all logs are redrawn
  // (grep mode may have shown filtered logs, need to refresh for normal view)
  static bool last_grep_state = false;
  if (last_grep_state && !grep_entering) {
    terminal_screen_clear_cache();
  }
 
  // Also clear cache when pattern changes while still in grep mode (e.g., user backspaces to empty)
  if (grep_entering && log_search_needs_rerender()) {
    terminal_screen_clear_cache();
  }
 
  last_grep_state = grep_entering;
 
  // Allocate or reuse frame buffer (module-level static to avoid malloc per frame)
  if (!g_frame_buf) {
    g_frame_buf = frame_buffer_create(g_cached_term_size.rows, g_cached_term_size.cols);
    if (!g_frame_buf) {
      return; // Allocation failed
    }
  }
 
  frame_buffer_reset(g_frame_buf);
 
  if (!grep_entering) {
    // Redraw in place; frame_buffer_flush erases each rendered line without
    // exposing a full-screen clear between frames.
    frame_buffer_cursor_home(g_frame_buf);
  } else {
    // Grep mode: overwrite in place, never clear whole screen
    frame_buffer_cursor_home(g_frame_buf);
  }
 
  // Render fixed header via callback (writes into frame buffer)
  config->render_header(g_frame_buf, g_cached_term_size, config->user_data);
 
  // If logs are disabled, flush and return
  if (!config->show_logs) {
    frame_buffer_flush(g_frame_buf);
    return;
  }
 
  // Measure actual header height by pre-rendering and counting display lines
  int actual_header_height = config->fixed_header_lines;
 
  if (config->render_header) {
    // Pre-render header to a temporary buffer to measure its display height
    frame_buffer_t *temp_buf = frame_buffer_create(config->fixed_header_lines + 10, g_cached_term_size.cols);
    if (temp_buf) {
      config->render_header(temp_buf, g_cached_term_size, config->user_data);
 
      // Measure display height of the rendered header
      // The buffer contains ANSI codes + text. We count newlines and account for wrapped lines.
      int measured_height = 0;
      const char *content = frame_buffer_get_content(temp_buf);
      size_t buf_len = frame_buffer_get_length(temp_buf);
      const char *buf_end = content + buf_len;
      const char *line_start = content;
 
      while (content < buf_end) {
        if (*content == '\n') {
          // Found end of line - measure this line's display height
          size_t line_len = content - line_start;
          char line_buf[1024];
          if (line_len < sizeof(line_buf)) {
            memcpy(line_buf, line_start, line_len);
            line_buf[line_len] = '\0';
 
            int line_height = display_height(line_buf, g_cached_term_size.cols);
            if (line_height <= 0)
              line_height = 1;
            measured_height += line_height;
          }
          line_start = content + 1;
        }
        content++;
      }
 
      if (measured_height > 0) {
        actual_header_height = measured_height;
      }
      frame_buffer_destroy(temp_buf);
    }
  }
 
  // Calculate log area: total rows - actual header height - 1 (prevent scroll)
  // When grep search is open, subtract additional row to prevent header bump
  int log_area_rows = g_cached_term_size.rows - actual_header_height - (grep_entering ? 2 : 1);
 
  if (log_area_rows <= 0) {
    // Terminal too small for logs, flush header and return
    frame_buffer_flush(g_frame_buf);
    if (grep_entering) {
      log_search_render_input_line(g_cached_term_size.cols);
    }
    return;
  }
 
  // When grep input is active, reserve 1 row for the grep input line at bottom.
  // Subtract 1 from log_area_rows to prevent logs from overlapping the grep input.
  int renderable_log_rows = grep_entering ? (log_area_rows - 1) : log_area_rows;
 
  // Fetch and filter logs
  session_log_entry_t *log_entries = NULL;
  size_t log_count = 0;
 
  if (log_search_is_active()) {
    asciichat_error_t result = log_search_gather_and_filter_logs(&log_entries, &log_count);
    if (result != ASCIICHAT_OK || !log_entries) {
      log_entries = SAFE_MALLOC(SESSION_LOG_BUFFER_SIZE * sizeof(session_log_entry_t), session_log_entry_t *);
      if (log_entries) {
        log_count = session_log_buffer_get_recent(g_session_log_buffer, log_entries, SESSION_LOG_BUFFER_SIZE);
      }
    }
  } else {
    // Get logs from in-memory buffer
    session_log_entry_t *buffer_entries =
        SAFE_MALLOC(SESSION_LOG_BUFFER_SIZE * sizeof(session_log_entry_t), session_log_entry_t *);
    if (buffer_entries) {
      size_t buffer_count =
          session_log_buffer_get_recent(g_session_log_buffer, buffer_entries, SESSION_LOG_BUFFER_SIZE);
      log_entries = buffer_entries;
      log_count = buffer_count;
    }
  }
 
  // Display logs - most recent at bottom, oldest scrolled off top.
  // Calculate a stable window: show logs that fit in available space, newest last.
  // This ensures smooth scrolling as new logs arrive (no jumping viewport).
  // Use renderable_log_rows when in grep mode to account for grep input line.
  // CRITICAL: account for multi-line logs via display_height() in pre-selection.
  // Without this, logs overflow and push the header off screen.
  int first_log_to_display = log_count; // Start past the end (no logs selected)
  int total_lines_used = 0;
  int available_rows = grep_entering ? renderable_log_rows : log_area_rows;
 
  // Work backwards from newest to oldest log, selecting which fit
  for (int i = (int)log_count - 1; i >= 0; i--) {
    int lines_for_msg = display_height(log_entries[i].message, g_cached_term_size.cols);
    if (lines_for_msg <= 0) {
      lines_for_msg = 1;
    }
    // Check if adding this log would exceed available space
    if (total_lines_used + lines_for_msg <= available_rows) {
      total_lines_used += lines_for_msg;
      first_log_to_display = i; // This is the first (oldest) log we'll display
    }
    // Continue checking older logs - they might be shorter and still fit
  }
 
  // If no logs fit, show nothing (just padding)
  if (first_log_to_display == (int)log_count) {
    first_log_to_display = log_count; // Will result in 0 logs to display
  }
 
  int logs_to_display = log_count - first_log_to_display;
 
  // Log detailed info about what logs are being displayed
  int logs_displayed_count = logs_to_display;
  if (elapsed_ms < 500) {
    log_dev_every(1 * NS_PER_SEC_INT, "[STARTUP_FRAME] t=%llu log_count=%zu first=%d display=%d area=%d",
                  (unsigned long long)elapsed_ms, log_count, first_log_to_display, logs_displayed_count, log_area_rows);
  } else {
    log_debug_every(1 * NS_PER_SEC_INT,
                    "[HEIGHT_CALC] log_count=%zu first_log_to_display=%d logs_displayed=%d "
                    "renderable_log_rows=%d",
                    log_count, first_log_to_display, logs_displayed_count, renderable_log_rows);
  }
 
  if (!grep_entering) {
    // Normal mode: accumulate everything (header + logs + blank lines) into frame buffer,
    // then flush atomically. This prevents real-time logs from appearing after the frame,
    // which would cause the display to scroll and push the header up.
 
    // Output logs to frame buffer, counting actual display lines (accounting for wrapping)
    int terminal_lines_used = 0;
    for (int i = first_log_to_display; i < (int)log_count && terminal_lines_used < log_area_rows; i++) {
      const char *msg = log_entries[i].message;
 
      // Calculate how many display lines this message will consume when wrapped
      // Uses display_height() which handles ANSI codes and UTF-8 properly
      int lines_for_this_msg = display_height(msg, g_cached_term_size.cols);
      if (lines_for_this_msg <= 0) {
        lines_for_this_msg = 1;
      }
 
      // Only output if it fits in remaining space
      if (terminal_lines_used + lines_for_this_msg <= log_area_rows) {
        frame_buffer_printf(g_frame_buf, "%s\n", msg);
        terminal_lines_used += lines_for_this_msg;
      }
    }
 
    // Pad remaining log area with blank lines to maintain fixed frame height.
    // This ensures every frame has exactly the same height on screen,
    // preventing flicker caused by dynamic frame height changes.
    while (terminal_lines_used < log_area_rows) {
      frame_buffer_printf(g_frame_buf, "\n");
      terminal_lines_used++;
    }
 
    // Flush entire frame (header + logs + blank lines) in one atomic write
    frame_buffer_flush(g_frame_buf);
  } else {
    // Grep mode: render logs with frame buffer (same as normal mode)
    // Just apply grep highlighting to visible logs
 
    int terminal_lines_used = 0;
    for (int i = first_log_to_display; i < (int)log_count && terminal_lines_used < log_area_rows; i++) {
      const char *original_msg = log_entries[i].message;
      const char *msg = original_msg;
 
      // Strip ANSI codes first to match against plain text
      char plain_text[SESSION_LOG_LINE_MAX] = {0};
      strip_ansi_codes(original_msg, plain_text, sizeof(plain_text));
 
      // Apply highlighting if match found in plain text
      size_t match_start = 0, match_len = 0;
      if (log_search_get_match_info(plain_text, &match_start, &match_len) && match_len > 0) {
        // Validate match is within bounds
        size_t plain_len = strlen(plain_text);
        if (match_start < plain_len && (match_start + match_len) <= plain_len) {
          const char *highlighted = grep_highlight_colored(original_msg, plain_text, match_start, match_len);
          if (highlighted && highlighted[0] != '\0') {
            msg = highlighted;
          }
        }
      }
 
      int msg_display_width = display_width(msg);
      if (msg_display_width < 0) {
        msg_display_width = (int)strlen(msg);
      }
      int lines_for_this_msg = 1;
      if (g_cached_term_size.cols > 0 && msg_display_width > g_cached_term_size.cols) {
        lines_for_this_msg = (msg_display_width + g_cached_term_size.cols - 1) / g_cached_term_size.cols;
      }
 
      if (terminal_lines_used + lines_for_this_msg <= log_area_rows) {
        frame_buffer_printf(g_frame_buf, "%s\n", msg);
        terminal_lines_used += lines_for_this_msg;
      }
    }
 
    // Pad remaining log area with blank lines
    while (terminal_lines_used < log_area_rows) {
      frame_buffer_printf(g_frame_buf, "\n");
      terminal_lines_used++;
    }
 
    // Flush frame buffer before rendering grep UI
    frame_buffer_flush(g_frame_buf);
 
    // Grep input line UI (position cursor at bottom and display "/" prompt with pattern)
    // Get the search pattern under mutex protection
    mutex_t *grep_mutex = log_search_get_mutex();
    if (grep_mutex && g_cached_term_size.rows > 0) {
      mutex_lock(grep_mutex);
      int pattern_len = log_search_get_input_len();
      const char *pattern = log_search_get_input_buffer();
      int cursor_pos = log_search_get_cursor_position();
 
      // Render grep input line at bottom of screen
      printf("\x1b[%d;1H/", g_cached_term_size.rows);
      if (pattern_len > 0 && pattern) {
        printf("%.*s", pattern_len, pattern);
      }
 
      // Position cursor at current edit position
      int cursor_offset = pattern_len - cursor_pos;
      if (cursor_offset > 0) {
        printf("\x1b[%dD", cursor_offset);
      }
      fflush(stdout);
 
      mutex_unlock(grep_mutex);
    }
  }
 
  SAFE_FREE(log_entries);
}

References ASCIICHAT_OK, terminal_size_t::cols, display_height(), display_width(), errno, terminal_screen_config_t::fixed_header_lines, frame_buffer_create(), frame_buffer_cursor_home(), frame_buffer_destroy(), frame_buffer_flush(), frame_buffer_get_content(), frame_buffer_get_length(), frame_buffer_printf(), frame_buffer_reset(), grep_highlight_colored(), options_state::height, log_debug_every, log_dev_every, log_error, log_search_gather_and_filter_logs(), log_search_get_cursor_position(), log_search_get_input_buffer(), log_search_get_input_len(), log_search_get_match_info(), log_search_get_mutex(), log_search_is_active(), log_search_is_entering(), log_search_needs_rerender(), log_search_render_input_line(), session_log_entry_t::message, mutex_lock, mutex_unlock, NS_PER_SEC_INT, options_get(), platform_get_monotonic_time_us(), terminal_screen_config_t::render_header, terminal_size_t::rows, SAFE_FREE, SAFE_GETENV, SAFE_MALLOC, session_log_buffer_get_recent(), SESSION_LOG_BUFFER_SIZE, SESSION_LOG_LINE_MAX, terminal_screen_config_t::show_logs, TERM_SIZE_CHECK_INTERVAL_US, terminal_cursor_show(), terminal_get_size(), terminal_screen_config_t::user_data, and options_state::width.

Referenced by ui_status_display(), and ui_status_display_interactive().

terminal_screen_set_output_fd()

void terminal_screen_set_output_fd

(

int

fd

)

Set output file descriptor for terminal screens (splash/status)

Parameters

fd	File descriptor (STDOUT_FILENO for TTY, STDERR_FILENO for piped)

Configures where splash and status screens write their output. Should be called before terminal_screen_render() to control output destination.

Definition at line 499 of file terminal_screen.c.

                                           {
  frame_buffer_set_screen_output_fd(fd);
}

References frame_buffer_set_screen_output_fd().

Referenced by splash_intro_start(), and ui_status_display().