Home /Modules/bash/pixel-terminal.sh

pixel-terminal.sh

bash/pixel-terminal.sh · 119 line(s) · bash

#!/usr/bin/env bash
# SleelaTerminal(TM) -- SLeeLa's terminal product, built on GNU Bash
# (GPL, (C) Free Software Foundation). This file is a SLeeLa-authored addition;
# the vendored GNU Bash sources keep their own GPL headers and copyright.
#
# Phraign(TM) -- SleelaTerminal(TM)'s frame-based, pixel-accurate terminal
# control system. This is the Phraign(TM) pixel-addressable terminal shell
# interface. The functions emit a text protocol consumed by the SLeeLa terminal
# bridge. See PHRAIGN.md for the system overview.

: "${SLEELA_PIXEL_TERMINAL:=sleeLa-pixel-terminal}"
: "${SLEELA_BASH_PROTOCOL:=1}"
: "${SLEELA_PHRAIGN_VERSION:=1}"
: "${SLEELA_PHRAIGN_VARIANT:=NATIVE}"

# Establish that this Bash session understands the versioned native Phraign™
# terminal protocol. SLeeLa may use READY/CAPS before sending frame commands.
pixel_terminal_handshake() {
    printf '%s HELLO SLEELA-BASH/%s PHRAIGN/%s VARIANT=%s\n' \
        "$SLEELA_PIXEL_TERMINAL" "$SLEELA_BASH_PROTOCOL" \
        "$SLEELA_PHRAIGN_VERSION" "$SLEELA_PHRAIGN_VARIANT"
    printf '%s READY SLEELA-BASH/%s PHRAIGN/%s VARIANT=%s\n' \
        "$SLEELA_PIXEL_TERMINAL" "$SLEELA_BASH_PROTOCOL" \
        "$SLEELA_PHRAIGN_VERSION" "$SLEELA_PHRAIGN_VARIANT"
    printf '%s CAPS PIXEL_GRANULARITY NATIVE_FRAME RESIZE_EVENTS\n' \
        "$SLEELA_PIXEL_TERMINAL"
}

pixel_terminal_begin() {
    local width="$1" height="$2"
    printf '%s BEGIN %s %s\n' "$SLEELA_PIXEL_TERMINAL" "$width" "$height"
}

pixel_terminal_set() {
    local x="$1" y="$2" value="$3"
    printf '%s SET %s %s %s\n' "$SLEELA_PIXEL_TERMINAL" "$x" "$y" "$value"
}

pixel_terminal_fill() {
    local value="$1"
    printf '%s FILL %s\n' "$SLEELA_PIXEL_TERMINAL" "$value"
}

pixel_terminal_clear() {
    printf '%s CLEAR\n' "$SLEELA_PIXEL_TERMINAL"
}

pixel_terminal_show() {
    printf '%s SHOW\n' "$SLEELA_PIXEL_TERMINAL"
}

pixel_terminal_end() {
    printf '%s END\n' "$SLEELA_PIXEL_TERMINAL"
}

# Report character-cell dimensions. This is always available on a terminal
# with a usable tty, and is used as the portability fallback for pixel size.
pixel_terminal_cell_size() {
    local rows cols
    if read -r rows cols < <(stty size 2>/dev/null); then
        printf '%s CELL_SIZE %s %s\n' "$SLEELA_PIXEL_TERMINAL" "$cols" "$rows"
        return 0
    fi
    return 1
}

# Request the terminal's physical pixel dimensions using the common xterm
# window-size report (CSI 14 t). The terminal response is expected as
# CSI 4 ; height ; width t. Not every terminal supports this query.
pixel_terminal_pixel_size() {
    local response height width old_stty
    old_stty="$(stty -g 2>/dev/null)" || return 1

    stty -echo -icanon min 0 time 5 2>/dev/null || return 1
    printf '\033[14t' > /dev/tty 2>/dev/null || {
        stty "$old_stty" 2>/dev/null
        return 1
    }
    IFS= read -r -d 't' response < /dev/tty 2>/dev/null || true
    stty "$old_stty" 2>/dev/null || true

    if [[ "$response" =~ $'\033\[4;([0-9]+);([0-9]+)' ]]; then
        height="${BASH_REMATCH[1]}"
        width="${BASH_REMATCH[2]}"
        printf '%s PIXEL_SIZE %s %s\n' "$SLEELA_PIXEL_TERMINAL" "$width" "$height"
        return 0
    fi
    return 1
}

# Emit the best available current dimensions and derive the frame center.
# Pixel size is authoritative when supported; cell size remains available as
# a fallback and is explicitly labeled so the bridge can distinguish them.
pixel_terminal_size() {
    local pixel_report center_x center_y width height
    if pixel_report="$(pixel_terminal_pixel_size 2>/dev/null)"; then
        printf '%s\n' "$pixel_report"
        read -r _ _ width height <<< "$pixel_report"
        center_x=$((width / 2))
        center_y=$((height / 2))
        printf '%s CENTER %s %s\n' "$SLEELA_PIXEL_TERMINAL" "$center_x" "$center_y"
        return 0
    fi

    pixel_terminal_cell_size || return 1
    return 0
}

# Capture terminal resize events. Bash receives SIGWINCH when the terminal
# window changes size. The handler refreshes the frame dimensions and center.
pixel_terminal_watch_resize() {
    trap 'pixel_terminal_size' WINCH
    pixel_terminal_size
}

pixel_terminal_unwatch_resize() {
    trap - WINCH
}