term.h

/* term.h - terminal emulator core: cell grid, UTF-8 decoding, escape parsing.
 * Backend-agnostic: no dependency on any rendering or OS layer. */
#ifndef HTERM_TERM_H
#define HTERM_TERM_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

enum {
    ATTR_BOLD = 1 << 0,
    ATTR_ITALIC = 1 << 1,
    ATTR_UNDERLINE = 1 << 2,
    ATTR_REVERSE = 1 << 3,
    ATTR_WIDE = 1 << 4,       /* first cell of a double-width glyph */
    ATTR_WIDE_DUMMY = 1 << 5, /* placeholder cell after a wide glyph */
};

typedef struct {
    uint32_t cp;     /* Unicode code point, 0 = empty cell */
    uint32_t fg, bg; /* 0xRRGGBB */
    uint16_t attrs;
} Cell;

typedef struct Term Term;

/* Called when the terminal needs to send bytes back to the child
 * (e.g. cursor position reports). */
typedef void (*TermWriteFn)(void *user, const char *buf, size_t len);

Term *term_new(int cols, int rows, TermWriteFn write, void *user);
void term_free(Term *t);

/* Feed raw bytes read from the pty. */
void term_feed(Term *t, const char *buf, size_t len);

void term_resize(Term *t, int cols, int rows);
int term_cols(const Term *t);
int term_rows(const Term *t);

/* Row `row` of the visible grid, cols cells wide. While scrolled back,
 * history rows are served from a shared scratch buffer, so the pointer
 * is only valid until the next call. */
const Cell *term_line(const Term *t, int row);
void term_cursor(const Term *t, int *col, int *row, bool *visible);

/* DECSCUSR (CSI Ps SP q) cursor style: 0 = default, 1/2 block,
 * 3/4 underline, 5/6 bar; odd styles blink, even are steady. */
int term_cursor_style(const Term *t);

/* Scrollback: move the view delta lines back into history (negative =
 * toward the live screen). The view is clamped to the stored history
 * and snaps to 0 on the alternate screen. term_line() serves history
 * lines while scrolled back. */
void term_scroll_view(Term *t, int delta);
int term_view(const Term *t);    /* current offset, 0 = live bottom */
bool term_on_alt(const Term *t); /* alternate screen active? */

/* Mouse reporting requested by the application: 0 = off, else the DEC
 * mode number (9, 1000, 1002, 1003). term_mouse_sgr is the 1006 SGR
 * report encoding. The frontend does the actual reporting. */
int term_mouse_mode(const Term *t);
bool term_mouse_sgr(const Term *t);

/* Bracketed paste (2004): the frontend wraps pastes in ESC[200~/201~. */
bool term_bracketed_paste(const Term *t);

/* True if the screen changed since the last call; clears the flag. */
bool term_take_dirty(Term *t);

/* OSC 52: clipboard text set by the application, base64-decoded.
 * Returns a malloc'd string the caller frees, or NULL if none arrived
 * since the last call. */
char *term_take_clipboard(Term *t);

/* Default colors (from config.h) used by SGR reset and erased cells. */
uint32_t term_default_fg(void);
uint32_t term_default_bg(void);

#endif