/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  Licensed under the StarForth License, Version 1.0.
*/

/**
 * vt100.h — Full-color ANSI / VT100 terminal state machine
 *
 * Sits on top of the framebuffer driver.  Call vt100_init() once the
 * framebuffer is ready, then route all character output through vt100_putc().
 *
 * Supported escape sequences
 * ──────────────────────────
 *   Cursor movement   ESC[H  ESC[n;mH  ESC[nA  ESC[nB  ESC[nC  ESC[nD
 *   Cursor save/restore  ESC[s  ESC[u  (also ESC7 / ESC8)
 *   Erase             ESC[2J  ESC[K  ESC[0K  ESC[1K  ESC[2K
 *   SGR attributes    ESC[…m  (see below)
 *
 * SGR codes
 * ─────────
 *   0          reset all attributes
 *   1          bold (doubles fg brightness)
 *   4          underline
 *   7          reverse video
 *   22         normal intensity
 *   24         underline off
 *   27         reverse off
 *   30–37      set fg to standard ANSI color 0–7
 *   38;2;r;g;b set fg to 24-bit RGB truecolor
 *   38;5;n     set fg to 256-color index
 *   39         reset fg to default
 *   40–47      set bg to standard ANSI color 0–7
 *   48;2;r;g;b set bg to 24-bit RGB truecolor
 *   48;5;n     set bg to 256-color index
 *   49         reset bg to default
 *   90–97      set fg to bright ANSI color 8–15
 *   100–107    set bg to bright ANSI color 8–15
 */

#ifndef STARKERNEL_VT100_H
#define STARKERNEL_VT100_H

#include <stdint.h>

/* Default terminal colors */
#define VT100_DEFAULT_FG  FB_RGB(0xAA, 0xAA, 0xAA)  /* light gray */
#define VT100_DEFAULT_BG  FB_RGB(0x00, 0x00, 0x00)  /* black       */

/* -----------------------------------------------------------------------
 * Lifecycle
 * --------------------------------------------------------------------- */

/**
 * Initialize the VT100 terminal.
 * Must be called after fb_init().  Clears the screen and homes the cursor.
 */
void vt100_init(void);

/**
 * FABRIC.md item 4.4j: switch the glyph-draw backend from font_8x16.c to
 * TTF-TEXT's rasterizer for everything drawn from this call onward --
 * boot/POST output before this call stays font_8x16.c, unaffected.
 * Lazily loads the font capsule and its raster cache on first call
 * (no-op on later calls). Recomputes cols/rows for the new cell size and
 * clears the screen, since the two glyph backends use different cell
 * dimensions. TTF point size/cell dimensions decided final by FABRIC.md
 * item 4.4m (20px text, 96px REPL strip). No-op if the font capsule
 * fails to load (stays on font_8x16.c; logged, not fatal).
 */
void vt100_enable_ttf(void);

/**
 * FABRIC.md item 4.4q: move the REPL scrollback view back/forward by
 * @p n lines and redraw. Offset 0 (the default, and where every call
 * eventually returns to) is the live view -- the same content already on
 * screen. Clamped at both ends: back cannot pass the oldest stored line,
 * forward cannot pass the live view. No-op (including no redraw) if the
 * scrollback buffers failed to allocate at vt100_enable_ttf() time, or
 * before TTF mode is active at all.
 *
 * Known limitation: redraw uses the terminal's current default fg/bg,
 * not each line's original SGR color state at the time it was printed
 * (colors aren't stored per-cell) -- text content is recovered exactly,
 * color is not.
 */
void vt100_scroll_back(uint32_t n);
void vt100_scroll_fwd(uint32_t n);

/* -----------------------------------------------------------------------
 * Character output
 * --------------------------------------------------------------------- */

/** Feed one byte into the terminal (handles escape sequences transparently). */
void vt100_putc(char c);

/** Feed a null-terminated string. */
void vt100_puts(const char *s);

/**
 * FABRIC.md items 4.4u/4.4w/4.4x: draw the REPL prompt/input strip -- a
 * single-line region pinned to the bottom of the screen, independent of
 * the scrollback box and its grid/cursor. @p text is the full line to
 * show (prompt plus whatever has been typed so far), plain text with no
 * ANSI/SGR codes -- the strip renders everything in one fixed color
 * (bright white on black, 4.4u). Horizontally scrolls (tail-anchored)
 * once @p text exceeds the strip's width. No-op before TTF mode is
 * active (vt100_enable_ttf() must have run first).
 */
void vt100_strip_draw(const char *text);

/* -----------------------------------------------------------------------
 * Queries
 * --------------------------------------------------------------------- */

/** Terminal width in character columns. */
uint32_t vt100_cols(void);

/** Terminal height in character rows. */
uint32_t vt100_rows(void);

#endif /* STARKERNEL_VT100_H */