ghost-tab 2.6.0

package/lib/ai-select-tui.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# AI tool selection TUI wrapper using ghost-tab-tui
+
+# Interactive AI tool multi-selection
+# Returns 0 if selected, 1 if cancelled
+# Sets: _selected_ai_tool (first tool by priority)
+# Sets: _selected_ai_tools (space-separated list of all selected tools)
+select_ai_tool_interactive() {
+  if ! command -v ghost-tab-tui &>/dev/null; then
+    error "ghost-tab-tui binary not found. Please reinstall."
+    return 1
+  fi
+
+  local result
+  if ! result=$(ghost-tab-tui multi-select-ai-tool 2>/dev/null); then
+    return 1
+  fi
+
+  local confirmed
+  if ! confirmed=$(echo "$result" | jq -r '.confirmed' 2>/dev/null); then
+    error "Failed to parse AI tool selection response"
+    return 1
+  fi
+
+  # Validate against null/empty
+  if [[ -z "$confirmed" || "$confirmed" == "null" ]]; then
+    error "TUI returned invalid confirmation status"
+    return 1
+  fi
+
+  if [[ "$confirmed" != "true" ]]; then
+    return 1
+  fi
+
+  local tools_json
+  if ! tools_json=$(echo "$result" | jq -r '.tools[]' 2>/dev/null); then
+    error "Failed to parse selected tools"
+    return 1
+  fi
+
+  # Validate against empty selection
+  if [[ -z "$tools_json" ]]; then
+    error "TUI returned empty tool selection"
+    return 1
+  fi
+
+  # Set space-separated list of all selected tools
+  _selected_ai_tools="$tools_json"
+
+  # Pick first tool by priority: claude > codex > copilot > opencode
+  local priority_order=("claude" "codex" "copilot" "opencode")
+  _selected_ai_tool=""
+  for priority_tool in "${priority_order[@]}"; do
+    if echo "$tools_json" | grep -qx "$priority_tool"; then
+      _selected_ai_tool="$priority_tool"
+      break
+    fi
+  done
+
+  # Fallback to first tool if none matched priority
+  if [[ -z "$_selected_ai_tool" ]]; then
+    _selected_ai_tool=$(echo "$tools_json" | head -n1)
+  fi
+
+  return 0
+}

package/lib/ai-tools.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# AI tool helper functions — pure, no side effects on source.
+
+# Validates SELECTED_AI_TOOL against AI_TOOLS_AVAILABLE.
+# Falls back to first available if current selection is invalid.
+# Optional arg $1: path to preference file (writes corrected value if provided).
+validate_ai_tool() {
+  local _valid=0 _t
+  for _t in "${AI_TOOLS_AVAILABLE[@]}"; do
+    [ "$_t" == "$SELECTED_AI_TOOL" ] && _valid=1
+  done
+  if [ "$_valid" -eq 0 ] && [ ${#AI_TOOLS_AVAILABLE[@]} -gt 0 ]; then
+    SELECTED_AI_TOOL="${AI_TOOLS_AVAILABLE[0]}"
+    if [ -n "${1:-}" ]; then
+      mkdir -p "$(dirname "$1")"
+      echo "$SELECTED_AI_TOOL" > "$1"
+    fi
+  fi
+}

package/lib/config-tui.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# Config menu TUI dispatcher
+# Uses ghost-tab-tui config-menu subcommand in a loop
+
+# Source dependencies if not already loaded
+_config_tui_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/tui.sh
+[ "$(type -t header 2>/dev/null)" = "function" ] || source "$_config_tui_dir/tui.sh"
+# shellcheck source=lib/terminal-select-tui.sh
+[ "$(type -t select_terminal_interactive 2>/dev/null)" = "function" ] || source "$_config_tui_dir/terminal-select-tui.sh"
+# shellcheck source=lib/terminals/registry.sh
+[ "$(type -t get_terminal_display_name 2>/dev/null)" = "function" ] || source "$_config_tui_dir/terminals/registry.sh"
+# shellcheck source=lib/project-actions-tui.sh
+[ "$(type -t add_project_interactive 2>/dev/null)" = "function" ] || source "$_config_tui_dir/project-actions-tui.sh"
+# shellcheck source=lib/project-actions.sh
+[ "$(type -t add_project_to_file 2>/dev/null)" = "function" ] || source "$_config_tui_dir/project-actions.sh"
+# shellcheck source=lib/ai-select-tui.sh
+[ "$(type -t select_ai_tool_interactive 2>/dev/null)" = "function" ] || source "$_config_tui_dir/ai-select-tui.sh"
+# shellcheck source=lib/settings-menu-tui.sh
+[ "$(type -t settings_menu_interactive 2>/dev/null)" = "function" ] || source "$_config_tui_dir/settings-menu-tui.sh"
+
+# Interactive config menu loop.
+# Calls ghost-tab-tui config-menu, dispatches on action, loops until quit.
+config_menu_interactive() {
+  if ! command -v ghost-tab-tui &>/dev/null; then
+    error "ghost-tab-tui binary not found. Please reinstall."
+    return 1
+  fi
+
+  local config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/ghost-tab"
+
+  while true; do
+    local result
+    if ! result=$(ghost-tab-tui config-menu 2>/dev/null); then
+      return 1
+    fi
+
+    local action
+    if ! action=$(echo "$result" | jq -r '.action' 2>/dev/null); then
+      error "Failed to parse config menu response"
+      return 1
+    fi
+
+    case "$action" in
+      manage-terminals)
+        export GHOST_TAB_TERMINAL_PREF="$config_dir/terminal"
+        if select_terminal_interactive; then
+          # shellcheck disable=SC2154
+          echo "$_selected_terminal" > "$config_dir/terminal"
+          success "Terminal set to $(get_terminal_display_name "$_selected_terminal")"
+          echo ""
+          read -rsn1 -p "Press any key to continue..." </dev/tty
+        fi
+        ;;
+      manage-projects)
+        if add_project_interactive; then
+          # shellcheck disable=SC2154
+          add_project_to_file "$_add_project_name" "$_add_project_path" "$config_dir/projects"
+          success "Added project: $_add_project_name"
+          echo ""
+          read -rsn1 -p "Press any key to continue..." </dev/tty
+        fi
+        ;;
+      select-ai-tools)
+        if select_ai_tool_interactive; then
+          # shellcheck disable=SC2154
+          echo "$_selected_ai_tool" > "$config_dir/ai-tool"
+          success "Default AI tool set to $_selected_ai_tool"
+          echo ""
+          read -rsn1 -p "Press any key to continue..." </dev/tty
+        fi
+        ;;
+      display-settings)
+        settings_menu_interactive
+        ;;
+      reinstall)
+        local script_dir
+        script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+        if [ -f "$script_dir/bin/ghost-tab" ]; then
+          exec bash "$script_dir/bin/ghost-tab"
+        else
+          error "Installer not found. Re-clone the repository."
+          echo ""
+          read -rsn1 -p "Press any key to continue..." </dev/tty
+        fi
+        ;;
+      quit|"")
+        return 0
+        ;;
+      *)
+        error "Unknown action: $action"
+        ;;
+    esac
+  done
+}

package/lib/ghostty-config.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Ghostty config file helpers.
+
+# Merge a command line into an existing Ghostty config.
+# If a "command = ..." line exists, replace it; otherwise append.
+merge_ghostty_config() {
+  local config_path="$1" wrapper_line="$2"
+  if grep -q '^command[[:space:]]*=' "$config_path"; then
+    sed -i '' 's|^command[[:space:]]*=.*|'"$wrapper_line"'|' "$config_path"
+    success "Replaced existing command line in config"
+  else
+    echo "$wrapper_line" >> "$config_path"
+    success "Appended wrapper command to config"
+  fi
+}
+
+# Backup an existing config and replace it with the source config.
+backup_replace_ghostty_config() {
+  local config_path="$1" source_config="$2"
+  local backup
+  backup="${config_path}.backup.$(date +%s)"
+  cp "$config_path" "$backup"
+  success "Backed up existing config to $backup"
+  cp "$source_config" "$config_path"
+  success "Replaced config with ghost-tab defaults"
+}

package/lib/input.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Input parsing helpers — no side effects on source.
+
+# Interactive confirmation using ghost-tab-tui
+# Usage: confirm_tui "Delete project 'foo'?"
+# Returns: 0 if confirmed, 1 if cancelled
+confirm_tui() {
+  local msg="$1"
+
+  if ! command -v ghost-tab-tui &>/dev/null; then
+    # Fallback to simple bash prompt
+    read -rp "$msg (y/N) " response </dev/tty
+    [[ "$response" =~ ^[Yy]$ ]]
+    return $?
+  fi
+
+  local result
+  if ! result=$(ghost-tab-tui confirm "$msg" 2>/dev/null); then
+    return 1
+  fi
+
+  local confirmed
+  if ! confirmed=$(echo "$result" | jq -r '.confirmed' 2>/dev/null); then
+    # Source tui.sh for error function if not already loaded
+    if ! declare -F error &>/dev/null; then
+      echo "ERROR: Failed to parse confirmation response" >&2
+    else
+      error "Failed to parse confirmation response"
+    fi
+    return 1
+  fi
+
+  # Validate against "null" string (learned from Task 3)
+  if [[ "$confirmed" == "null" || -z "$confirmed" ]]; then
+    return 1
+  fi
+
+  [[ "$confirmed" == "true" ]]
+}

package/lib/install.sh

@@ -0,0 +1,224 @@
+#!/bin/bash
+# Package installation helpers for the installer.
+
+# Detect CPU architecture: outputs "arm64" or "x86_64"
+detect_arch() {
+  local arch
+  arch="$(uname -m)"
+  case "$arch" in
+    arm64)   echo "arm64" ;;
+    x86_64)  echo "x86_64" ;;
+    *)
+      error "Unsupported architecture: $arch"
+      return 1 ;;
+  esac
+}
+
+# Get the latest release tag from a GitHub repo (e.g. "v1.2.3")
+# Uses the /releases/latest redirect — no API key required.
+get_latest_release_tag() {
+  local repo="$1" tag
+  tag="$(curl -fsSI "https://github.com/$repo/releases/latest" 2>/dev/null \
+    | grep -i '^location:' \
+    | sed 's|.*/tag/||' \
+    | tr -d '[:space:]\r')"
+  if [[ -z "$tag" ]]; then
+    error "Failed to fetch release tag for $repo"
+    return 1
+  fi
+  echo "$tag"
+}
+
+# Download a binary from $url to $dest and make it executable.
+install_binary() {
+  local url="$1" dest="$2" display_name="$3"
+  info "Downloading $display_name..."
+  mkdir -p "$(dirname "$dest")"
+  if curl -fsSL -o "$dest" "$url"; then
+    chmod +x "$dest"
+    success "$display_name installed"
+  else
+    warn "Failed to download $display_name from $url"
+    return 1
+  fi
+}
+
+# Install jq from jqlang/jq GitHub releases.
+ensure_jq() {
+  if command -v jq &>/dev/null; then
+    success "jq already installed"
+    return 0
+  fi
+  local arch jq_arch
+  arch="$(detect_arch)" || return 1
+  case "$arch" in
+    arm64)   jq_arch="macos-arm64" ;;
+    x86_64)  jq_arch="macos-amd64" ;;
+  esac
+  install_binary \
+    "https://github.com/jqlang/jq/releases/latest/download/jq-${jq_arch}" \
+    "$HOME/.local/bin/jq" \
+    "jq"
+}
+
+# Install tmux from tmux/tmux-builds GitHub releases.
+ensure_tmux() {
+  if command -v tmux &>/dev/null; then
+    success "tmux already installed"
+    return 0
+  fi
+  local arch tag version tmp_dir url
+  arch="$(detect_arch)" || return 1
+  tag="$(get_latest_release_tag "tmux/tmux-builds")" || return 1
+  version="${tag#v}"
+  tmp_dir="$(mktemp -d)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp_dir'" RETURN
+  url="https://github.com/tmux/tmux-builds/releases/download/${tag}/tmux-${version}-macos-${arch}.tar.gz"
+  info "Downloading tmux..."
+  if curl -fsSL -o "$tmp_dir/tmux.tar.gz" "$url"; then
+    tar -xzf "$tmp_dir/tmux.tar.gz" -C "$tmp_dir" tmux
+    mkdir -p "$HOME/.local/bin"
+    mv "$tmp_dir/tmux" "$HOME/.local/bin/tmux"
+    chmod +x "$HOME/.local/bin/tmux"
+    success "tmux installed"
+  else
+    warn "Failed to install tmux"
+    return 1
+  fi
+}
+
+# Install lazygit from jesseduffield/lazygit GitHub releases.
+ensure_lazygit() {
+  if command -v lazygit &>/dev/null; then
+    success "lazygit already installed"
+    return 0
+  fi
+  local arch tag version tmp_dir url
+  arch="$(detect_arch)" || return 1
+  tag="$(get_latest_release_tag "jesseduffield/lazygit")" || return 1
+  version="${tag#v}"
+  tmp_dir="$(mktemp -d)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp_dir'" RETURN
+  url="https://github.com/jesseduffield/lazygit/releases/download/${tag}/lazygit_${version}_darwin_${arch}.tar.gz"
+  info "Downloading lazygit..."
+  if curl -fsSL -o "$tmp_dir/lazygit.tar.gz" "$url"; then
+    tar -xzf "$tmp_dir/lazygit.tar.gz" -C "$tmp_dir" lazygit
+    mkdir -p "$HOME/.local/bin"
+    mv "$tmp_dir/lazygit" "$HOME/.local/bin/lazygit"
+    chmod +x "$HOME/.local/bin/lazygit"
+    success "lazygit installed"
+  else
+    warn "Failed to install lazygit"
+    return 1
+  fi
+}
+
+# Install broot from Canop/broot GitHub releases.
+ensure_broot() {
+  if command -v broot &>/dev/null; then
+    success "broot already installed"
+    return 0
+  fi
+  local arch broot_arch tag version tmp_dir url
+  arch="$(detect_arch)" || return 1
+  case "$arch" in
+    arm64)   broot_arch="aarch64-apple-darwin" ;;
+    x86_64)  broot_arch="x86_64-apple-darwin" ;;
+  esac
+  tag="$(get_latest_release_tag "Canop/broot")" || return 1
+  version="${tag#v}"
+  tmp_dir="$(mktemp -d)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp_dir'" RETURN
+  url="https://github.com/Canop/broot/releases/download/${tag}/broot_${version}.zip"
+  info "Downloading broot..."
+  if curl -fsSL -o "$tmp_dir/broot.zip" "$url"; then
+    unzip -q -d "$tmp_dir" "$tmp_dir/broot.zip"
+    mkdir -p "$HOME/.local/bin"
+    mv "$tmp_dir/${broot_arch}/broot" "$HOME/.local/bin/broot"
+    chmod +x "$HOME/.local/bin/broot"
+    success "broot installed"
+  else
+    warn "Failed to install broot"
+    return 1
+  fi
+}
+
+# Install or update ghost-tab-tui by downloading the pre-built binary from the ghost-tab release.
+# Args: share_dir (to read VERSION from)
+# Checks installed binary version against VERSION file and re-downloads if mismatched.
+ensure_ghost_tab_tui() {
+  local share_dir="$1"
+
+  local version
+  version="$(tr -d '[:space:]' < "$share_dir/VERSION" 2>/dev/null)"
+  if [[ -z "$version" ]]; then
+    error "Cannot determine ghost-tab-tui version: VERSION file missing in $share_dir"
+    return 1
+  fi
+
+  if command -v ghost-tab-tui &>/dev/null; then
+    # Check if installed version matches expected version
+    local installed_version
+    installed_version="$(ghost-tab-tui --version 2>/dev/null | sed 's/.*version //' || echo "")"
+    if [[ "$installed_version" == "$version" ]]; then
+      success "ghost-tab-tui is up to date ($version)"
+      return 0
+    fi
+    info "Updating ghost-tab-tui ($installed_version -> $version)..."
+  fi
+
+  local arch url
+  arch="$(detect_arch)" || return 1
+  url="https://github.com/JackUait/ghost-tab/releases/download/v${version}/ghost-tab-tui-darwin-${arch}"
+
+  mkdir -p "$HOME/.local/bin"
+  install_binary "$url" "$HOME/.local/bin/ghost-tab-tui" "ghost-tab-tui" || return 1
+}
+
+# Install base CLI requirements.
+ensure_base_requirements() {
+  ensure_jq
+  ensure_tmux
+  ensure_lazygit
+  ensure_broot
+}
+
+# Install a Homebrew cask if the .app isn't in /Applications.
+# Usage: ensure_cask "cask_name" "AppDisplayName"
+# Respects APPLICATIONS_DIR env var for testing (defaults to /Applications).
+ensure_cask() {
+  local cask="$1" app_name="$2"
+  local app_dir="${APPLICATIONS_DIR:-/Applications}"
+  if [ -d "${app_dir}/${app_name}.app" ]; then
+    success "$app_name found"
+  else
+    info "Installing $app_name..."
+    if brew install --cask "$cask"; then
+      success "$app_name installed"
+    else
+      error "$app_name installation failed."
+      info "Install manually or run: brew install --cask $cask"
+      return 1
+    fi
+  fi
+}
+
+# Install a command-line tool if not already on PATH.
+# Usage: ensure_command "cmd" "install_cmd" "post_msg" "display_name"
+ensure_command() {
+  local cmd="$1" install_cmd="$2" post_msg="$3" display_name="$4"
+  if command -v "$cmd" &>/dev/null; then
+    success "$display_name already installed"
+  else
+    info "Installing $display_name..."
+    if eval "$install_cmd"; then
+      success "$display_name installed"
+      [ -n "$post_msg" ] && info "$post_msg"
+    else
+      warn "$display_name installation failed — install manually: $install_cmd"
+    fi
+  fi
+}

package/lib/loading.sh

@@ -0,0 +1,190 @@
+#!/bin/bash
+# Loading screen with ASCII art, tool-specific color palettes, and animation.
+
+# Print the loading screen ASCII art to stdout.
+get_loading_art() {
+  cat << 'ART'
++--------------------------------------------------------------------------------------+
+|                                                                                      |
+|        .d8888b. 888                     888         88888888888     888              |
+|       d88P  Y88b888                     888             888         888              |
+|       888    888888                     888             888         888              |
+|       888       88888b.  .d88b. .d8888b 888888          888  8888b. 88888b.          |
+|       888  88888888 "88bd88""88b88K     888             888     "88b888 "88b         |
+|       888    888888  888888  888"Y8888b.888             888 .d888888888  888         |
+|       Y88b  d88P888  888Y88..88P     X88Y88b.           888 888  888888 d88P         |
+|        "Y8888P88888  888 "Y88P"  88888P' "Y888          888 "Y88888888888P"          |
+|                                                                                      |
++--------------------------------------------------------------------------------------+
+ART
+}
+
+# Get color palette for a given AI tool. Prints space-separated 256-color codes.
+# Falls back to Claude palette for unknown or empty tool names.
+get_tool_palette() {
+  case "${1:-}" in
+    codex)    echo "22 28 29 34 35 41 42 47" ;;          # green
+    copilot)  echo "54 56 93 99 135 141 177 183" ;;       # purple (GitHub Copilot brand)
+    opencode) echo "240 242 244 246 248 250 252 254" ;;   # gray/silver (OpenCode mascot)
+    *)        echo "130 166 172 208 209 214 215 220" ;;   # orange/amber (claude default)
+  esac
+}
+
+# Render a single frame of the loading screen.
+# Args: tool_name frame_number term_cols term_rows
+render_loading_frame() {
+  local tool="$1" frame="$2"
+  local cols="${3:-80}" rows="${4:-24}"
+
+  # Get art lines into array
+  local art
+  art="$(get_loading_art)"
+  local -a lines=()
+  while IFS= read -r line; do
+    lines+=("$line")
+  done <<< "$art"
+
+  # Get palette
+  local -a palette
+  read -ra palette <<< "$(get_tool_palette "$tool")"
+  local pal_len=${#palette[@]}
+
+  # Calculate art dimensions
+  local art_height=${#lines[@]}
+  local art_width=0
+  for line in "${lines[@]}"; do
+    local len=${#line}
+    if (( len > art_width )); then
+      art_width=$len
+    fi
+  done
+
+  # Center position
+  local start_row=$(( (rows - art_height) / 2 ))
+  local start_col=$(( (cols - art_width) / 2 ))
+  if (( start_row < 1 )); then start_row=1; fi
+  if (( start_col < 1 )); then start_col=1; fi
+
+  # Draw each line with gradient color shifted by frame
+  local i
+  for i in "${!lines[@]}"; do
+    local color_idx=$(( (i + frame) % pal_len ))
+    local color="${palette[$color_idx]}"
+    printf '\033[%d;%dH\033[38;5;%dm%s' \
+      "$((start_row + i))" "$start_col" "$color" "${lines[$i]}"
+  done
+
+  printf '\033[0m'
+}
+
+# PID of the background animation process.
+_LOADING_SCREEN_PID=""
+
+# Detect terminal dimensions reliably. Prints "rows cols" to stdout.
+_detect_term_size() {
+  local _r _c
+
+  # Method 1: stty size via /dev/tty (most reliable in pty context)
+  local _size
+  if _size=$( (stty size </dev/tty) 2>/dev/null ) && read -r _r _c <<< "$_size"; then
+    if (( _r > 0 && _c > 0 )); then
+      echo "$_r $_c"
+      return
+    fi
+  fi
+
+  # Method 2: stty size from stdin
+  if read -r _r _c < <(stty size 2>/dev/null); then
+    if (( _r > 0 && _c > 0 )); then
+      echo "$_r $_c"
+      return
+    fi
+  fi
+
+  # Method 3: tput (uses terminfo + ioctl)
+  _c=$(tput cols 2>/dev/null || echo 0)
+  _r=$(tput lines 2>/dev/null || echo 0)
+  if (( _r > 0 && _c > 0 )); then
+    echo "$_r $_c"
+    return
+  fi
+
+  # Fallback
+  echo "24 80"
+}
+
+# Show animated loading screen with tool-specific colors.
+# Args: [tool_name] — defaults to claude if omitted.
+# Sets _LOADING_SCREEN_PID for the caller to stop later.
+show_loading_screen() {
+  local tool="${1:-claude}"
+
+  # Clear screen, hide cursor (instant dark feedback)
+  printf '\033[2J\033[H\033[?25l'
+
+  # Symbols for floating particles
+  local symbols=('·' '•' '°' '∘' '⋅' '∙')
+
+  # Start animation in background
+  (
+    trap 'printf "\033[?25h\033[0m"; exit 0' TERM INT HUP
+
+    # Brief delay so terminal reports its final size after window opens
+    sleep 0.1
+
+    local frame=0
+    local rows cols
+    local -a prev_sym_positions=()
+    local prev_rows=0 prev_cols=0
+
+    while true; do
+      # Detect terminal size each frame (handles late window resizes)
+      read -r rows cols <<< "$(_detect_term_size)"
+      if (( rows != prev_rows || cols != prev_cols )); then
+        printf '\033[2J'  # Clear screen on resize to avoid ghost artifacts
+        prev_rows="$rows" prev_cols="$cols"
+        prev_sym_positions=()
+      fi
+
+      # Redraw art with shifted colors
+      render_loading_frame "$tool" "$frame" "$cols" "$rows"
+
+      # Clear previous floating symbols
+      for pos in "${prev_sym_positions[@]}"; do
+        local sr sc
+        IFS=';' read -r sr sc <<< "$pos"
+        printf '\033[%d;%dH ' "$sr" "$sc"
+      done
+      prev_sym_positions=()
+
+      # Draw new floating symbols
+      local -a palette
+      read -ra palette <<< "$(get_tool_palette "$tool")"
+      local pal_len=${#palette[@]}
+      local _s
+      for _s in 0 1 2; do
+        local sym_row=$(( RANDOM % rows + 1 ))
+        local sym_col=$(( RANDOM % cols + 1 ))
+        local sym_color="${palette[$(( RANDOM % pal_len ))]}"
+        local sym="${symbols[$(( RANDOM % ${#symbols[@]} ))]}"
+        printf '\033[%d;%dH\033[2m\033[38;5;%dm%s\033[0m' \
+          "$sym_row" "$sym_col" "$sym_color" "$sym"
+        prev_sym_positions+=("${sym_row};${sym_col}")
+      done
+
+      frame=$(( (frame + 1) % pal_len ))
+      sleep 0.15
+    done
+  ) &
+  _LOADING_SCREEN_PID=$!
+}
+
+# Stop loading screen animation and restore terminal.
+stop_loading_screen() {
+  if [ -n "${_LOADING_SCREEN_PID:-}" ]; then
+    kill "$_LOADING_SCREEN_PID" 2>/dev/null
+    wait "$_LOADING_SCREEN_PID" 2>/dev/null
+    _LOADING_SCREEN_PID=""
+  fi
+  printf '\033[?25h\033[0m'
+}