/*
  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 item 4.4y-revised: toggle the full-screen vt100 terminal
 * between visible (normal operation) and hidden (graphics mode -- the
 * terminal stops drawing, letting direct framebuffer/TTF-TEXT calls show
 * through undisturbed). Toggling back to visible does a full redraw of
 * the terminal's current on-screen content, restoring it exactly as it
 * was. No-op before TTF mode is active.
 */
void vt100_toggle_graphics(void);

/**
 * Draw a solid block cursor at the terminal's current position. Static,
 * not blinking. Idempotent -- safe to call after every keystroke, since
 * whatever gets typed next naturally overwrites it. No-op before TTF mode
 * is active or while in graphics mode (vt100_toggle_graphics()).
 */
void vt100_draw_cursor(void);

/**
 * Erases whatever vt100_draw_cursor() last drew, restoring the cell to
 * plain background. Call before moving away from a cursor-drawn cell
 * without also drawing a character there (e.g. Enter/newline). No-op
 * before TTF mode is active or while in graphics mode.
 */
void vt100_erase_cursor(void);

/* -----------------------------------------------------------------------
 * 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 */