controller.h File Reference

Go to the source code of this file.

Data Structures
struct	ui_presentation_state_t

Macros
#define	UI_CONTROLLER_MAX_FRAME_BYTES   (16 * 1024 * 1024)

Typedefs
typedef void(*	ui_render_fn) (terminal_size_t size, const void *snapshot)

Enumerations
enum	ui_screen_t {   UI_SCREEN_STATUS , UI_SCREEN_MEDIA , UI_SCREEN_SPLASH , UI_SCREEN_RENDER_PROGRESS ,   UI_SCREEN_LOGS , UI_SCREEN_ERRNO , UI_SCREEN_HELP , UI_SCREEN_STATS ,   UI_SCREEN_SYNC , UI_SCREEN_MDNS , UI_SCREEN_UPDATE , UI_SCREEN_NOTICE ,   UI_SCREEN_PROMPT , UI_SCREEN_ERROR , UI_SCREEN_COUNT }
enum	ui_title_render_t { UI_TITLE_IDLE , UI_TITLE_RENDERING , UI_TITLE_FINALIZING , UI_TITLE_FAILED }
enum	ui_title_activity_t {   UI_TITLE_ACTIVITY_IDLE , UI_TITLE_LOADING_URL , UI_TITLE_CONNECTING , UI_TITLE_RECONNECTING ,   UI_TITLE_CREATING_SESSION , UI_TITLE_JOINING_SESSION , UI_TITLE_WAITING_PEERS }

Functions
asciichat_error_t	ui_controller_submit (ui_screen_t screen, int fd, terminal_size_t minimum, ui_render_fn render, const void *snapshot, size_t bytes)
void	ui_controller_remove (ui_screen_t screen)
void	ui_controller_dismiss (ui_screen_t screen, int previous)
void	ui_controller_shutdown (void)
asciichat_error_t	ui_controller_title_start (const char *mode, int fd)
void	ui_controller_title_render (ui_title_render_t phase)
void	ui_controller_title_ready (void)
void	ui_controller_title_activity (ui_title_activity_t activity)
void	ui_controller_title_discovery (bool has_session, bool joining)
void	ui_controller_packet_begin (void)
void	ui_controller_packet_end (void)
void	ui_controller_restore_terminal (void)
void	ui_controller_redraw (void)
void	ui_controller_show_volume (void)
void	ui_controller_toggle_logs (void)
void	ui_controller_hide_logs (void)
bool	ui_controller_is_blocked (void)
bool	ui_controller_is_presenting (void)
bool	ui_controller_is_owner (void)
terminal_size_t	ui_controller_size (void)
ui_presentation_state_t	ui_controller_state (void)
int	ui_controller_current_screen (void)
int	ui_controller_active_fd (void)
int	ui_controller_interactive_screen (void)
void	ui_controller_select_interactive (int screen)
asciichat_error_t	ui_controller_write (int fd, const char *data, size_t len)
size_t	ui_controller_trim_utf8_chunk (const char *data, size_t length)
void	ui_controller_finish (int fd, const char *data, size_t len)
asciichat_error_t	ui_controller_present (ui_screen_t screen, int fd, terminal_size_t minimum, const char *data, size_t len)
asciichat_error_t	ui_controller_printf (int fd, const char *format,...)
const animation_sample_t *	ui_controller_animation_sample (void)
asciichat_error_t	ui_controller_present_retained (ui_screen_t screen, int fd, terminal_size_t minimum, const char *data, size_t len)
void	ui_controller_frame_acquired_at (uint64_t started_ns)
void	ui_controller_set_effective_fps (unsigned int fps)
asciichat_error_t	ui_controller_start_terminal (int fd)
bool	ui_controller_screen_live (ui_screen_t screen)
bool	ui_controller_first_use_key (int key)

Macro Definition Documentation

UI_CONTROLLER_MAX_FRAME_BYTES

#define UI_CONTROLLER_MAX_FRAME_BYTES   (16 * 1024 * 1024)

Maximum complete frame size accepted by the presenter, including cursor controls.

Definition at line 9 of file tui/controller.h.

Referenced by session_display_write_ascii_frame(), and ui_session_media().

Typedef Documentation

ui_render_fn

typedef void(* ui_render_fn) (terminal_size_t size, const void *snapshot)

Definition at line 30 of file tui/controller.h.

Enumeration Type Documentation

ui_screen_t

enum ui_screen_t

Rendering priority, from background to modal.

Enumerator
UI_SCREEN_STATUS
UI_SCREEN_MEDIA
UI_SCREEN_SPLASH
UI_SCREEN_RENDER_PROGRESS
UI_SCREEN_LOGS
UI_SCREEN_ERRNO
UI_SCREEN_HELP
UI_SCREEN_STATS
UI_SCREEN_SYNC
UI_SCREEN_MDNS
UI_SCREEN_UPDATE
UI_SCREEN_NOTICE
UI_SCREEN_PROMPT
UI_SCREEN_ERROR
UI_SCREEN_COUNT

Definition at line 12 of file tui/controller.h.

             {
  UI_SCREEN_STATUS,
  UI_SCREEN_MEDIA,
  UI_SCREEN_SPLASH,
  UI_SCREEN_RENDER_PROGRESS,
  UI_SCREEN_LOGS,
  UI_SCREEN_ERRNO,
  UI_SCREEN_HELP,
  UI_SCREEN_STATS,
  UI_SCREEN_SYNC,
  UI_SCREEN_MDNS,
  UI_SCREEN_UPDATE,
  UI_SCREEN_NOTICE,
  UI_SCREEN_PROMPT,
  UI_SCREEN_ERROR, // Virtual notification layer; rendered above screens and below help.
  UI_SCREEN_COUNT
} ui_screen_t;

ui_title_activity_t

enum ui_title_activity_t

Enumerator
UI_TITLE_ACTIVITY_IDLE
UI_TITLE_LOADING_URL
UI_TITLE_CONNECTING
UI_TITLE_RECONNECTING
UI_TITLE_CREATING_SESSION
UI_TITLE_JOINING_SESSION
UI_TITLE_WAITING_PEERS

Definition at line 50 of file tui/controller.h.

             {
  UI_TITLE_ACTIVITY_IDLE,
  UI_TITLE_LOADING_URL,
  UI_TITLE_CONNECTING,
  UI_TITLE_RECONNECTING,
  UI_TITLE_CREATING_SESSION,
  UI_TITLE_JOINING_SESSION,
  UI_TITLE_WAITING_PEERS
} ui_title_activity_t;

ui_title_render_t

enum ui_title_render_t

Enumerator
UI_TITLE_IDLE
UI_TITLE_RENDERING
UI_TITLE_FINALIZING
UI_TITLE_FAILED

Definition at line 47 of file tui/controller.h.

{ UI_TITLE_IDLE, UI_TITLE_RENDERING, UI_TITLE_FINALIZING, UI_TITLE_FAILED } ui_title_render_t;

Function Documentation

ui_controller_active_fd()

int ui_controller_active_fd

(

void

)

Output descriptor owned by the active screen, or stdout when none is active.

Definition at line 280 of file tui/controller.c.

                                  {
  int fd = atomic_load(&g_default_fd);
  if (!lifecycle_is_initialized(&g_lifecycle))
    return fd;
  mutex_lock(&g_mutex);
  if (g_active >= 0 && g_active < UI_SCREEN_COUNT && g_screens[g_active].render)
    fd = g_screens[g_active].fd;
  mutex_unlock(&g_mutex);
  return fd;
}

References screen::fd, screen::render, and UI_SCREEN_COUNT.

Referenced by tui_stats_render(), ui_controller_first_use_key(), ui_errno_stacks_toggle(), and ui_input_read_key().

ui_controller_animation_sample()

const animation_sample_t * ui_controller_animation_sample

(

void

)

Animation sample owned by the common runtime during a presentation callback.

Definition at line 671 of file tui/controller.c.

                                                               {
  return g_animation;
}

Referenced by ui_media_panel_render().

ui_controller_current_screen()

int ui_controller_current_screen

(

void

)

Last published screen priority; does not acquire application locks.

Definition at line 264 of file tui/controller.c.

                                       {
  int background = atomic_load(&g_background_screen);
  int interactive = atomic_load(&g_interactive_screen);
  if (interactive == UI_SCREEN_HELP && (atomic_load(&g_screen_mask) & (1u << UI_SCREEN_HELP)) &&
      (background != UI_SCREEN_UPDATE || keyboard_help_parent_screen() == UI_SCREEN_UPDATE ||
       keyboard_help_parent_screen() == UI_SCREEN_ERROR))
    return UI_SCREEN_HELP;
  if ((background >= 0 || interactive >= 0) && ui_error_popup_visible())
    return UI_SCREEN_ERROR;
  if (interactive < 0 && background < UI_SCREEN_MDNS && (atomic_load(&g_screen_mask) & (1u << UI_SCREEN_MDNS)))
    return UI_SCREEN_MDNS;
  return background > interactive ? background : interactive;
}

References keyboard_help_parent_screen(), ui_error_popup_visible(), UI_SCREEN_ERROR, UI_SCREEN_HELP, UI_SCREEN_MDNS, and UI_SCREEN_UPDATE.

Referenced by keyboard_help_toggle_terminal(), session_pipeline_run_main(), ui_controller_is_presenting(), ui_controller_state(), ui_controller_toggle_logs(), ui_controller_write(), ui_errno_stacks_handle_key(), and ui_input_poll_sync().

ui_controller_dismiss()

void ui_controller_dismiss	(	ui_screen_t	screen,
		int	previous )

Retire a modal and atomically restore its previous interactive owner if still live. Does not steal focus from a screen selected after the modal opened.

Definition at line 1683 of file tui/controller.c.

                                                             {
  remove_screen(screen, previous, NULL);
}

Referenced by keyboard_help_toggle_terminal(), and ui_prompt_dismiss().

ui_controller_finish()

void ui_controller_finish	(	int	fd,
		const char *	data,
		size_t	len )

Retire live screens and synchronously render final text before the caller exits.

Definition at line 610 of file tui/controller.c.

                                                                {
  atomic_store(&g_sync_finishing, true);
  if (!g_owner)
    while (atomic_load(&g_sync_rendering))
      platform_sleep_ms(1);
  errno_notifications_enable(false);
  screen_t retired[UI_SCREEN_COUNT] = {0};
  bool locked = lifecycle_is_initialized(&g_lifecycle);
  if (locked) {
    mutex_lock(&g_mutex);
    g_finished = true;
    memcpy(retired, g_screens, sizeof(retired));
    memset(g_screens, 0, sizeof(g_screens));
    atomic_store(&g_background_screen, -1);
    atomic_store(&g_screen_mask, 0);
    ui_controller_select_interactive(-1);
    cond_signal(&g_render_requested);
    uint64_t pending = g_render_started;
    while (!g_render_snapshot && g_render_completed < pending)
      cond_wait(&g_render_done, &g_mutex);
    mutex_unlock(&g_mutex);
  }
  for (int i = 0; i < UI_SCREEN_COUNT; ++i)
    release_screen(&retired[i], i == UI_SCREEN_NOTICE);
  terminal_screen_leave();
  platform_write_all(fd, data, len);
  atomic_store_bool(&g_live, false);
}

References errno_notifications_enable(), screen::fd, platform_sleep_ms(), platform_write_all(), ui_controller_select_interactive(), UI_SCREEN_COUNT, and UI_SCREEN_NOTICE.

Referenced by ui_notice_present(), and update_banner_print_instructions().

ui_controller_first_use_key()

bool ui_controller_first_use_key

(

int

key

)

Handle input for a first-use notice, retaining its snapshot while it is used.

Definition at line 1687 of file tui/controller.c.

                                          {
  if (!lifecycle_is_initialized(&g_lifecycle))
    return false;
  mutex_lock(&g_mutex);
  screen_snapshot_t *owned = g_screens[UI_SCREEN_NOTICE].owned;
  if (owned)
    atomic_fetch_add(&owned->references, 1);
  mutex_unlock(&g_mutex);
  if (!owned)
    return false;
  ui_notice_key_result_t result = ui_notice_first_use_key(owned->data, key);
  if (result == UI_NOTICE_KEY_HELP)
    keyboard_help_toggle_terminal(ui_controller_active_fd());
  if (result == UI_NOTICE_KEY_COMPLETE)
    ui_notice_first_use_complete(owned->data);
  if (result == UI_NOTICE_KEY_COMPLETE || result == UI_NOTICE_KEY_DISMISS)
    remove_screen(UI_SCREEN_NOTICE, -1, owned);
  else if (result == UI_NOTICE_KEY_HANDLED && (key == '\r' || key == '\n' || key == KEY_LEFT || key == KEY_RIGHT))
    ui_controller_redraw();
  release_snapshot(owned);
  return result != UI_NOTICE_KEY_ORDINARY;
}

References KEY_LEFT, KEY_RIGHT, keyboard_help_toggle_terminal(), screen_snapshot_t::references, ui_controller_active_fd(), ui_controller_redraw(), ui_notice_first_use_complete(), ui_notice_first_use_key(), UI_NOTICE_KEY_COMPLETE, UI_NOTICE_KEY_DISMISS, UI_NOTICE_KEY_HANDLED, UI_NOTICE_KEY_HELP, UI_NOTICE_KEY_ORDINARY, and UI_SCREEN_NOTICE.

Referenced by ui_input_read_key().

ui_controller_frame_acquired_at()

void ui_controller_frame_acquired_at

(

uint64_t

started_ns

)

Carry the acquisition start time with the next media snapshot on this producer thread.

Definition at line 357 of file tui/controller.c.

                                                          {
  g_acquisition_started_ns = started_ns;
}

Referenced by session_pipeline_run_main().

ui_controller_hide_logs()

void ui_controller_hide_logs

(

void

)

Definition at line 1952 of file tui/controller.c.

                                   {
  ui_controller_remove(UI_SCREEN_LOGS);
  terminal_screen_logs_reset();
}

References terminal_screen_logs_reset(), ui_controller_remove(), and UI_SCREEN_LOGS.

Referenced by ui_controller_toggle_logs().

ui_controller_interactive_screen()

int ui_controller_interactive_screen

(

void

)

One interactive screen replaces the previous one; sync can switch without application locks.

Definition at line 297 of file tui/controller.c.

                                           {
  return atomic_load(&g_interactive_screen);
}

Referenced by keyboard_help_is_active(), keyboard_help_is_active_global(), keyboard_help_toggle_terminal(), session_handle_keyboard_input(), stats_runtime_active(), and ui_sync_is_visible().

ui_controller_is_blocked()

bool ui_controller_is_blocked

(

void

)

Atomic query, safe for interrupt handling.

Definition at line 639 of file tui/controller.c.

                                    {
  return atomic_load_bool(&g_blocked);
}

Referenced by keyboard_help_is_active_global(), and ui_input_poll_sync().

ui_controller_is_owner()

bool ui_controller_is_owner

(

void

)

Definition at line 647 of file tui/controller.c.

                                  {
  return g_owner;
}

Referenced by log_console_impl(), and ui_notice_present().

ui_controller_is_presenting()

bool ui_controller_is_presenting

(

void

)

Lock-free query for console logging, including logs from rendering callbacks.

Definition at line 643 of file tui/controller.c.

                                       {
  return ui_controller_current_screen() >= 0;
}

References ui_controller_current_screen().

Referenced by log_console_impl(), log_msg(), ui_controller_write(), ui_notice_present(), and ui_prompt_dismiss().

ui_controller_packet_begin()

void ui_controller_packet_begin

(

void

)

Keep a complete terminal protocol packet and its flush separate from title updates. Call outside presentation callbacks; application shutdown must follow packet completion.

Definition at line 1410 of file tui/controller.c.

                                      {
  if (lifecycle_is_initialized(&g_lifecycle))
    mutex_lock(&g_title_packet_mutex);
}

Referenced by kitty_image_write().

ui_controller_packet_end()

void ui_controller_packet_end

(

void

)

Definition at line 1415 of file tui/controller.c.

                                    {
  if (lifecycle_is_initialized(&g_lifecycle))
    mutex_unlock(&g_title_packet_mutex);
}

Referenced by kitty_image_write().

ui_controller_present()

asciichat_error_t ui_controller_present	(	ui_screen_t	screen,
		int	fd,
		terminal_size_t	minimum,
		const char *	data,
		size_t	len )

Publish an owned copy of an already rendered frame.

Definition at line 1973 of file tui/controller.c.

                                                    {
  return present_text(screen, fd, minimum, data, len, true);
}

Referenced by ascii_write(), and session_display_write_ascii_frame().

ui_controller_present_retained()

asciichat_error_t ui_controller_present_retained	(	ui_screen_t	screen,
		int	fd,
		terminal_size_t	minimum,
		const char *	data,
		size_t	len )

Redraw retained media without treating it as a newly acquired frame for FPS.

Definition at line 1977 of file tui/controller.c.

                                                             {
  return present_text(screen, fd, minimum, data, len, false);
}

Referenced by session_display_create(), and session_display_write_ascii_frame().

ui_controller_printf()

asciichat_error_t ui_controller_printf	(	int	fd,
		const char *	format,
			... )

Definition at line 1929 of file tui/controller.c.

                                                                        {
  char buffer[TUI_CONTROLLER_BUFFER_BUFFER_SIZE];
  va_list args;
  va_start(args, format);
  int len = vsnprintf(buffer, sizeof(buffer), format, args);
  va_end(args);
  if (len < 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Cannot format terminal output");
  size_t bytes = (size_t)len < sizeof(buffer) ? (size_t)len : sizeof(buffer) - 1;
  return ui_controller_write(fd, buffer, bytes);
}

References args, ERROR_INVALID_PARAM, SET_ERRNO, TUI_CONTROLLER_BUFFER_BUFFER_SIZE, and ui_controller_write().

Referenced by log_search_render_input_line(), and session_render_loop().

ui_controller_redraw()

void ui_controller_redraw

(

void

)

Definition at line 1857 of file tui/controller.c.

                                {
  if (!lifecycle_is_initialized(&g_lifecycle))
    return;
  mutex_lock(&g_mutex);
  g_redraw = true;
  cond_signal(&g_render_requested);
  mutex_unlock(&g_mutex);
}

References ui_session_redraw().

Referenced by ascii_write_init(), keyboard_help_render(), session_display_clear(), session_display_cursor_home(), session_display_reset(), terminal_screen_logs_handle_key_sized(), ui_controller_first_use_key(), ui_error_popup_key(), and update_banner_install_update().

ui_controller_remove()

void ui_controller_remove

(

ui_screen_t

screen

)

Definition at line 1679 of file tui/controller.c.

                                              {
  remove_screen(screen, -1, NULL);
}

Referenced by display_cleanup(), render_progress_destroy(), session_capture_cancel_open(), session_capture_complete_open(), session_capture_destroy(), session_display_begin_drain(), session_display_destroy(), session_display_write_ascii_frame(), session_render_loop(), terminal_screen_log_destroy(), ui_controller_hide_logs(), ui_errno_stacks_handle_key(), ui_errno_stacks_hide(), ui_errno_stacks_toggle(), ui_input_read_key(), ui_notice_dismiss(), update_banner_show_prompt(), and update_banner_toggle_overlay().

ui_controller_restore_terminal()

void ui_controller_restore_terminal

(

void

)

Stop presentation and restore cursor visibility on an interactive terminal.

Definition at line 1941 of file tui/controller.c.

                                          {
  ui_controller_shutdown();
  if (platform_isatty(STDOUT_FILENO))
    ui_controller_write(STDOUT_FILENO, "\033[0m\033[?25h", 10);
}

References ui_controller_shutdown(), and ui_controller_write().

ui_controller_screen_live()

bool ui_controller_screen_live

(

ui_screen_t

screen

)

Definition at line 1454 of file tui/controller.c.

                                                   {
  return screen >= 0 && screen < UI_SCREEN_COUNT && (atomic_load(&g_screen_mask) & (1u << screen));
}

References UI_SCREEN_COUNT.

Referenced by stats_runtime_start(), and ui_input_read_key().

ui_controller_select_interactive()

void ui_controller_select_interactive

(

int

screen

)

Definition at line 301 of file tui/controller.c.

                                                  {
  atomic_store(&g_interactive_screen, screen);
}

Referenced by stats_runtime_toggle(), ui_controller_finish(), ui_controller_shutdown(), ui_sync_handle_key(), and ui_sync_stop().

ui_controller_set_effective_fps()

void ui_controller_set_effective_fps

(

unsigned int

fps

)

Set the target FPS displayed by the media overlay.

Definition at line 361 of file tui/controller.c.

                                                       {
  atomic_store_int(&g_effective_fps, (int)(fps > 0 ? fps : 60));
  if (g_fps)
    fps_counter_set_effective_fps(g_fps, fps);
}

References fps_counter_set_effective_fps().

ui_controller_show_volume()

void ui_controller_show_volume

(

void

)

Show volume feedback for 1.5 seconds after a volume or mute control is used.

Definition at line 221 of file tui/controller.c.

                                     {
  if (!GET_OPTION(snapshot_mode))
    atomic_store_u64(&g_volume_until, time_get_ns() + 1500 * NS_PER_MS_INT);
}

References GET_OPTION, and NS_PER_MS_INT.

ui_controller_shutdown()

void ui_controller_shutdown

(

void

)

Definition at line 1888 of file tui/controller.c.

                                  {
  if (!lifecycle_destroy_once(&g_lifecycle))
    return;
  mutex_lock(&g_mutex);
  atomic_store_bool(&g_presentation_stop_requested, true);
  cond_signal(&g_render_requested);
  mutex_unlock(&g_mutex);
  thread_join(&g_thread, NULL);
  // Shutdown may precede the next presentation tick. Keep pending errors readable
  // after exit without delaying transport teardown or waiting for terminal input.
  ui_error_popup_preserve(atomic_load(&g_default_fd), unpack_size(atomic_load(&g_size)));
  ui_session_destroy(g_session);
  g_session = NULL;
  errno_notifications_enable(false);
  ui_error_popup_reset();
  atomic_store_u64(&g_volume_until, 0);
  ui_sync_stop();
  for (int i = 0; i < UI_SCREEN_COUNT; ++i) {
    release_screen(&g_screens[i], i == UI_SCREEN_NOTICE);
  }
  destroy_media_snapshots();
  cond_destroy(&g_render_requested);
  cond_destroy(&g_render_done);
  mutex_destroy(&g_title_packet_mutex);
  mutex_destroy(&g_mutex);
  atomic_store_bool(&g_live, false);
  atomic_store(&g_background_screen, -1);
  atomic_store(&g_screen_mask, 0);
  ui_controller_select_interactive(-1);
  terminal_screen_leave();
  NAMED_UNREGISTER(&g_title_active);
  NAMED_UNREGISTER(&g_title_render);
  NAMED_UNREGISTER(&g_title_ready);
  NAMED_UNREGISTER(&g_title_activity);
  NAMED_UNREGISTER(&g_live);
  NAMED_UNREGISTER(&g_presentation_stop_requested);
  NAMED_UNREGISTER(&g_blocked);
  NAMED_UNREGISTER(&g_lifecycle.state);
  lifecycle_destroy_commit(&g_lifecycle);
}

References errno_notifications_enable(), NAMED_UNREGISTER, ui_controller_select_interactive(), ui_error_popup_preserve(), ui_error_popup_reset(), UI_SCREEN_COUNT, UI_SCREEN_NOTICE, ui_session_destroy(), and ui_sync_stop().

Referenced by asciichat_shared_destroy(), stats_runtime_stop(), and ui_controller_restore_terminal().

ui_controller_size()

terminal_size_t ui_controller_size

(

void

)

Definition at line 651 of file tui/controller.c.

                                         {
  if (g_owner)
    return g_render_size;
  terminal_size_t size = {.cols = 80, .rows = 24};
  if (lifecycle_is_initialized(&g_lifecycle)) {
    size = unpack_size(atomic_load(&g_size));
  }
  // A title-only controller has no screen to poll geometry yet.
  if (!lifecycle_is_initialized(&g_lifecycle) || atomic_load(&g_screen_mask) == 0) {
    terminal_size_t detected = {0};
    asciichat_errno_scope_t scope = errno_scope_begin();
    int fd = atomic_load(&g_default_fd);
    if (platform_isatty(fd) && terminal_get_size_fd(fd, &detected) == ASCIICHAT_OK && detected.cols > 0 &&
        detected.rows > 0)
      size = detected;
    errno_scope_end(scope, ASCIICHAT_ERRNO_DISMISSED);
  }
  return size;
}

References ASCIICHAT_ERRNO_DISMISSED, ASCIICHAT_OK, errno_scope_begin(), errno_scope_end(), screen::fd, and ui_session_size().

Referenced by key_identity_format_terminal(), keyboard_help_toggle_terminal(), prompt_unknown_host(), terminal_screen_logs_handle_key(), ui_controller_state(), ui_notice_present(), and ui_session_logs_key().

ui_controller_start_terminal()

asciichat_error_t ui_controller_start_terminal

(

int

fd

)

Start terminal interaction without publishing a background screen.

Definition at line 1420 of file tui/controller.c.

                                                       {
  if (fd < 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid UI terminal descriptor");
  atomic_store(&g_default_fd, fd);
  asciichat_error_t result = controller_start();
  return result == ASCIICHAT_OK ? ui_sync_start(fd) : result;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, SET_ERRNO, and ui_sync_start().

Referenced by stats_runtime_start().

ui_controller_state()

ui_presentation_state_t ui_controller_state

(

void

)

Definition at line 1710 of file tui/controller.c.

                                                  {
  ui_presentation_state_t state = {.screen = -1};
  if (!lifecycle_is_initialized(&g_lifecycle))
    return state;
  state.screen = ui_controller_current_screen();
  if (state.screen == UI_SCREEN_ERROR) {
    state.covered = ui_too_small(ui_controller_size(), ui_error_popup_minimum());
    return state;
  }
  if (state.screen >= 0 && state.screen < UI_SCREEN_COUNT) {
    uint64_t published = atomic_load(&g_input_state);
    // Sync has an independent mailbox instead of a controller slot. Treat an
    // unpublished slot as absent so the session can dispatch queued switches.
    if (!(published & (UINT64_C(1) << state.screen)))
      state.screen = -1;
    else
      state.covered = (published & (UINT64_C(1) << (state.screen + 32))) != 0;
  }
  return state;
}

References ui_presentation_state_t::screen, ui_controller_current_screen(), ui_controller_size(), ui_error_popup_minimum(), UI_SCREEN_COUNT, UI_SCREEN_ERROR, and ui_too_small().

Referenced by stats_runtime_start(), and ui_input_read_key().

ui_controller_submit()

asciichat_error_t ui_controller_submit	(	ui_screen_t	screen,
		int	fd,
		terminal_size_t	minimum,
		ui_render_fn	render,
		const void *	snapshot,
		size_t	bytes )

Copies snapshot before returning. Interactive callbacks run on the presentation thread; batch output renders synchronously. Pointer members must remain valid until ui_controller_remove() returns. Callbacks may remove themselves. Callbacks run without the controller mutex. External removal waits for an in-flight callback to finish, so producers must not hold locks needed by that callback while removing its screen.

Definition at line 1623 of file tui/controller.c.

                                                                           {
  return submit_screen(screen, fd, minimum, render, snapshot, bytes, NULL, true);
}

Referenced by keyboard_help_toggle_terminal(), terminal_screen_render(), ui_controller_toggle_logs(), ui_media_loading_present(), ui_notice_present(), ui_notice_present_first_use(), ui_password_prompt_present(), ui_prompt_present_kind(), and update_banner_show_prompt().

ui_controller_title_activity()

void ui_controller_title_activity

(

ui_title_activity_t

activity

)

Definition at line 766 of file tui/controller.c.

                                                                {
  atomic_store_int(&g_title_activity, activity);
}

Referenced by session_display_write_ascii_frame(), splash_clear_discovery_session(), and ui_controller_title_discovery().

ui_controller_title_discovery()

void ui_controller_title_discovery	(	bool	has_session,
		bool	joining )

Definition at line 769 of file tui/controller.c.

                                                                   {
  ui_controller_title_activity(joining       ? UI_TITLE_JOINING_SESSION
                               : has_session ? UI_TITLE_WAITING_PEERS
                                             : UI_TITLE_CREATING_SESSION);
}

References ui_controller_title_activity(), UI_TITLE_CREATING_SESSION, UI_TITLE_JOINING_SESSION, and UI_TITLE_WAITING_PEERS.

Referenced by splash_set_discovery_session().

ui_controller_title_ready()

void ui_controller_title_ready

(

void

)

Definition at line 757 of file tui/controller.c.

                                     {
  atomic_store_bool(&g_title_ready, true);
}

Referenced by session_display_write_ascii_frame(), session_server_like_run(), and ui_controller_title_render().

ui_controller_title_render()

void ui_controller_title_render

(

ui_title_render_t

phase

)

Definition at line 760 of file tui/controller.c.

                                                         {
  atomic_store_int(&g_title_render, phase);
  if (phase != UI_TITLE_IDLE)
    ui_controller_title_ready();
}

References ui_controller_title_ready(), and UI_TITLE_IDLE.

Referenced by render_file_create(), render_file_destroy(), and render_file_write_frame().

ui_controller_title_start()

asciichat_error_t ui_controller_title_start	(	const char *	mode,
		int	fd )

Start interactive title presentation. Producer events never write to the terminal.

Definition at line 1428 of file tui/controller.c.

                                                                      {
  if (!mode || !platform_isatty(fd) ||
      (GET_OPTION(snapshot_mode) && !GET_OPTION(render_file)[0] && !GET_OPTION(render_kitty)))
    return ASCIICHAT_OK;
  if (atomic_load_bool(&g_title_active))
    return SET_ERRNO(ERROR_INVALID_STATE, "Terminal title is already initialized");
  atomic_store(&g_default_fd, fd);
  asciichat_error_t result = controller_start();
  if (result != ASCIICHAT_OK)
    return result;
  g_title_fd = platform_dup(fd);
  if (g_title_fd < 0)
    return SET_ERRNO_SYS(ERROR_TERMINAL, "Cannot retain title terminal");
  g_title_mode = mode;
  g_title_started = time_get_ns();
  g_last_title[0] = '\0';
  g_title_written = false;
  g_title_startup_finished = false;
  atomic_store_int(&g_title_render, UI_TITLE_IDLE);
  atomic_store_int(&g_title_activity, UI_TITLE_ACTIVITY_IDLE);
  atomic_store_bool(&g_title_ready, false);
  // Publish only after the retained descriptor and immutable configuration are ready.
  atomic_store_bool(&g_title_active, true);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_STATE, ERROR_TERMINAL, GET_OPTION, platform_dup(), SET_ERRNO, SET_ERRNO_SYS, UI_TITLE_ACTIVITY_IDLE, and UI_TITLE_IDLE.

Referenced by main().

ui_controller_toggle_logs()

void ui_controller_toggle_logs

(

void

)

Definition at line 1957 of file tui/controller.c.

                                     {
  ui_errno_stacks_hide();
  if (ui_controller_current_screen() == UI_SCREEN_LOGS) {
    ui_controller_hide_logs();
    return;
  }
  if (!platform_isatty(STDOUT_FILENO) || GET_OPTION(snapshot_mode))
    return;
  const bool snapshot = true;
  asciichat_error_t result =
      ui_controller_submit(UI_SCREEN_LOGS, STDOUT_FILENO, (terminal_size_t){.cols = 40, .rows = 6}, render_logs,
                           &snapshot, sizeof(snapshot));
  if (result != ASCIICHAT_OK)
    log_warn("Cannot show application logs: %d", result);
}

References ASCIICHAT_OK, GET_OPTION, log_warn, ui_controller_current_screen(), ui_controller_hide_logs(), ui_controller_submit(), ui_errno_stacks_hide(), and UI_SCREEN_LOGS.

ui_controller_trim_utf8_chunk()

size_t ui_controller_trim_utf8_chunk	(	const char *	data,
		size_t	length )

Return the largest prefix of a chunk that does not end in a UTF-8 continuation byte.

Definition at line 440 of file tui/controller.c.

                                                                      {
  while (data && length && ((unsigned char)data[length - 1] & 0xc0) == 0x80)
    --length;
  return length;
}

Referenced by ui_controller_write().

ui_controller_write()

asciichat_error_t ui_controller_write	(	int	fd,
		const char *	data,
		size_t	len )

Final output sink. Live screen writes must originate in a presentation callback. Other terminal text is suppressed while a screen owns the terminal; non-TTY output remains synchronous.

Definition at line 446 of file tui/controller.c.

                                                                            {
  if (!data || !len)
    return ASCIICHAT_OK;
  if (g_capture) {
    frame_buffer_append(g_capture, data, len);
    return ASCIICHAT_OK;
  }
  // Logging may call this while holding subsystem locks; never wait for a
  // renderer callback here. Live screens already capture logs in their model.
  if (!g_owner && ui_controller_is_presenting())
    return ASCIICHAT_OK;
  if (g_owner && g_render_fd >= 0)
    fd = g_render_fd;
  fps_counter_write_begin(g_fps);
  uint64_t stats_start = g_stats_media ? time_get_ns() : 0;
  // Terminals supporting synchronized output present the art and its overlays
  // together, even when a large UTF-8 frame requires several writes.
  bool help_media_overlay =
      ui_controller_current_screen() == UI_SCREEN_HELP && keyboard_help_parent_screen() == UI_SCREEN_MEDIA;
  bool synchronized = g_render_snapshot != NULL || help_media_overlay;
  g_help_sync_open = help_media_overlay;
  bool started = !synchronized || write_output_chunk(fd, "\033[?2026h", 8) == 8;
  uint64_t sync_started_ns = g_stats_media && synchronized ? time_get_ns() : 0;
  size_t written = 0;
  bool superseded = false;
  while (started && written < len) {
    // A pending editor or overlay supersedes the remainder of a media frame.
    // Bound each console write so a large frame cannot delay that transition.
    if (g_stats_media && ui_controller_current_screen() != UI_SCREEN_MEDIA) {
      superseded = true;
      break;
    }
    size_t count = len - written;
    bool row_boundary = false;
    if (g_stats_media && count > 32768) {
      count = 32768;
      size_t boundary = media_chunk_boundary(data + written, count);
      if (boundary) {
        count = boundary;
        row_boundary = true;
      }
      // Never inspect beyond the candidate chunk: the next byte may belong
      // to unrelated memory or to the next output chunk.
      count = ui_controller_trim_utf8_chunk(data + written, count);
    }
    size_t sent = write_output_chunk(fd, data + written, count);
    written += sent;
    if (sent != count)
      break;
    if (synchronized && g_stats_media && row_boundary && written < len &&
        time_get_ns() - sync_started_ns >= 40 * NS_PER_MS_INT) {
      // Give the terminal a complete set of rows before its synchronized
      // output watchdog can expose a partly written row.
      if (write_output_chunk(fd, "\033[?2026l\033[?2026h", 16) != 16) {
        started = false;
        break;
      }
      sync_started_ns = time_get_ns();
    }
  }
  // End the update even when input superseded the frame halfway through.
  static const char end_with_query[] = "\033[?2026l\033]11;?\033\\";
  bool probe = synchronized && g_probe_frame && written == len && started;
  if (probe)
    g_probe_requested_ns = time_get_ns();
  size_t end_length = probe ? sizeof(end_with_query) - 1 : 8;
  bool ended = g_help_sync_open || !synchronized || write_output_chunk(fd, end_with_query, end_length) == end_length;
  if (!ended)
    g_probe_requested_ns = 0;
  // Switching screens intentionally cancels the remainder of an old media frame.
  bool complete = (written == len || superseded) && started && ended;
  if (g_stats_media) {
    g_stats_write_ns += time_get_ns() - stats_start;
    g_stats_writes++;
    g_stats_failed |= !complete;
  }
  fps_counter_write_end(g_fps, complete);
  return complete ? ASCIICHAT_OK
                  : SET_ERRNO(ERROR_FILE_OPERATION, "Incomplete terminal frame write (%zu/%zu bytes)", written, len);
}

References ASCIICHAT_OK, ERROR_FILE_OPERATION, screen::fd, fps_counter_write_begin(), fps_counter_write_end(), frame_buffer_append(), keyboard_help_parent_screen(), NS_PER_MS_INT, SET_ERRNO, ui_controller_current_screen(), ui_controller_is_presenting(), ui_controller_trim_utf8_chunk(), UI_SCREEN_HELP, and UI_SCREEN_MEDIA.

Referenced by ascii_write(), ascii_write_destroy(), ascii_write_init(), log_console_impl(), log_search_render_input_line(), main(), session_display_write_ascii_frame(), session_display_write_raw(), tui_stats_render(), ui_controller_printf(), ui_controller_restore_terminal(), ui_notice_present(), ui_prompt_dismiss(), and ui_sync_render().