@teammates/consolonia 0.2.0

package/dist/ansi/esc.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ANSI escape sequence constants and builder functions.
+ * All functions return raw escape strings — nothing is written to stdout.
+ */
+export declare const reset = "\u001B[0m";
+export declare const bold = "\u001B[1m";
+export declare const dim = "\u001B[2m";
+export declare const italic = "\u001B[3m";
+export declare const underline = "\u001B[4m";
+export declare const strikethrough = "\u001B[9m";
+export declare const boldOff = "\u001B[22m";
+export declare const dimOff = "\u001B[22m";
+export declare const italicOff = "\u001B[23m";
+export declare const underlineOff = "\u001B[24m";
+export declare const strikethroughOff = "\u001B[29m";
+/** Set foreground to an RGB truecolor value. */
+export declare function fg(r: number, g: number, b: number): string;
+/** Set background to an RGB truecolor value. */
+export declare function bg(r: number, g: number, b: number): string;
+/** Reset foreground color to default. */
+export declare const fgDefault = "\u001B[39m";
+/** Reset background color to default. */
+export declare const bgDefault = "\u001B[49m";
+/** Move cursor to absolute position (0-based). */
+export declare function moveTo(x: number, y: number): string;
+/** Move cursor up by n lines. */
+export declare function moveUp(n?: number): string;
+/** Move cursor down by n lines. */
+export declare function moveDown(n?: number): string;
+/** Move cursor right by n columns. */
+export declare function moveRight(n?: number): string;
+/** Move cursor left by n columns. */
+export declare function moveLeft(n?: number): string;
+/** Save cursor position. */
+export declare const saveCursor = "\u001B[s";
+/** Restore cursor position. */
+export declare const restoreCursor = "\u001B[u";
+/** Hide the cursor. */
+export declare const hideCursor = "\u001B[?25l";
+/** Show the cursor. */
+export declare const showCursor = "\u001B[?25h";
+/** Switch to the alternate screen buffer. */
+export declare const alternateScreenOn = "\u001B[?1049h";
+/** Switch back from the alternate screen buffer. */
+export declare const alternateScreenOff = "\u001B[?1049l";
+/** Clear the entire screen. */
+export declare const clearScreen = "\u001B[2J";
+/** Erase from cursor to end of display. */
+export declare const eraseDown = "\u001B[0J";
+/** Erase the entire current line. */
+export declare const eraseLine = "\u001B[2K";
+/** Enable bracketed paste mode. */
+export declare const bracketedPasteOn = "\u001B[?2004h";
+/** Disable bracketed paste mode. */
+export declare const bracketedPasteOff = "\u001B[?2004l";
+/** Enable SGR mouse tracking (any-event tracking + SGR extended coordinates). */
+export declare const mouseTrackingOn = "\u001B[?1003h\u001B[?1006h";
+/** Disable SGR mouse tracking. */
+export declare const mouseTrackingOff = "\u001B[?1006l\u001B[?1003l";
+/** Set the terminal window title. */
+export declare function setTitle(title: string): string;

package/dist/ansi/esc.js

@@ -0,0 +1,85 @@
+/**
+ * ANSI escape sequence constants and builder functions.
+ * All functions return raw escape strings — nothing is written to stdout.
+ */
+const ESC = "\x1b[";
+const OSC = "\x1b]";
+// ── Text style ──────────────────────────────────────────────────────
+export const reset = `${ESC}0m`;
+export const bold = `${ESC}1m`;
+export const dim = `${ESC}2m`;
+export const italic = `${ESC}3m`;
+export const underline = `${ESC}4m`;
+export const strikethrough = `${ESC}9m`;
+export const boldOff = `${ESC}22m`;
+export const dimOff = `${ESC}22m`;
+export const italicOff = `${ESC}23m`;
+export const underlineOff = `${ESC}24m`;
+export const strikethroughOff = `${ESC}29m`;
+// ── RGB truecolor ───────────────────────────────────────────────────
+/** Set foreground to an RGB truecolor value. */
+export function fg(r, g, b) {
+    return `${ESC}38;2;${r};${g};${b}m`;
+}
+/** Set background to an RGB truecolor value. */
+export function bg(r, g, b) {
+    return `${ESC}48;2;${r};${g};${b}m`;
+}
+/** Reset foreground color to default. */
+export const fgDefault = `${ESC}39m`;
+/** Reset background color to default. */
+export const bgDefault = `${ESC}49m`;
+// ── Cursor movement ─────────────────────────────────────────────────
+/** Move cursor to absolute position (0-based). */
+export function moveTo(x, y) {
+    return `${ESC}${y + 1};${x + 1}H`;
+}
+/** Move cursor up by n lines. */
+export function moveUp(n = 1) {
+    return `${ESC}${n}A`;
+}
+/** Move cursor down by n lines. */
+export function moveDown(n = 1) {
+    return `${ESC}${n}B`;
+}
+/** Move cursor right by n columns. */
+export function moveRight(n = 1) {
+    return `${ESC}${n}C`;
+}
+/** Move cursor left by n columns. */
+export function moveLeft(n = 1) {
+    return `${ESC}${n}D`;
+}
+/** Save cursor position. */
+export const saveCursor = `${ESC}s`;
+/** Restore cursor position. */
+export const restoreCursor = `${ESC}u`;
+/** Hide the cursor. */
+export const hideCursor = `${ESC}?25l`;
+/** Show the cursor. */
+export const showCursor = `${ESC}?25h`;
+// ── Screen ──────────────────────────────────────────────────────────
+/** Switch to the alternate screen buffer. */
+export const alternateScreenOn = `${ESC}?1049h`;
+/** Switch back from the alternate screen buffer. */
+export const alternateScreenOff = `${ESC}?1049l`;
+/** Clear the entire screen. */
+export const clearScreen = `${ESC}2J`;
+/** Erase from cursor to end of display. */
+export const eraseDown = `${ESC}0J`;
+/** Erase the entire current line. */
+export const eraseLine = `${ESC}2K`;
+// ── Input modes ─────────────────────────────────────────────────────
+/** Enable bracketed paste mode. */
+export const bracketedPasteOn = `${ESC}?2004h`;
+/** Disable bracketed paste mode. */
+export const bracketedPasteOff = `${ESC}?2004l`;
+/** Enable SGR mouse tracking (any-event tracking + SGR extended coordinates). */
+export const mouseTrackingOn = `${ESC}?1003h${ESC}?1006h`;
+/** Disable SGR mouse tracking. */
+export const mouseTrackingOff = `${ESC}?1006l${ESC}?1003l`;
+// ── Window ──────────────────────────────────────────────────────────
+/** Set the terminal window title. */
+export function setTitle(title) {
+    return `${OSC}0;${title}\x07`;
+}

package/dist/ansi/output.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Buffered ANSI output writer.
+ * Inspired by Consolonia's AnsiConsoleOutput.cs — tracks terminal state
+ * to emit minimal escape sequences when writing pixels.
+ */
+import type { Writable } from "node:stream";
+import type { Color } from "../pixel/color.js";
+import type { Pixel } from "../pixel/pixel.js";
+/**
+ * Buffered ANSI writer that accumulates escape sequences in a string buffer
+ * and flushes them in a single write to the underlying stream.
+ */
+export declare class AnsiOutput {
+    private readonly stream;
+    private buf;
+    private lastX;
+    private lastY;
+    private lastFgColor;
+    private lastBgColor;
+    private lastBold;
+    private lastItalic;
+    private lastUnderline;
+    private lastStrikethrough;
+    constructor(stream?: Writable);
+    /** Append raw text to the internal buffer. */
+    private write;
+    /** Move cursor to (x, y) if not already there. */
+    setCursor(x: number, y: number): void;
+    /** Emit hide-cursor sequence. */
+    hideCursor(): void;
+    /** Emit show-cursor sequence. */
+    showCursor(): void;
+    /**
+     * Write a single pixel at (x, y).
+     * Cursor is moved only if necessary. Colors and styles are set only when
+     * they differ from the previously written state.
+     */
+    writePixel(x: number, y: number, pixel: Pixel): void;
+    /**
+     * Write a string starting at (x, y) with optional style overrides.
+     * Convenience wrapper that writes character-by-character is wasteful,
+     * so instead we set styles once and write the full text.
+     */
+    writeText(x: number, y: number, text: string, style?: {
+        fgColor?: Color;
+        bgColor?: Color;
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean;
+        strikethrough?: boolean;
+    }): void;
+    /** Write the accumulated buffer to the output stream and clear it. */
+    flush(): void;
+    /**
+     * Prepare the terminal for full-screen TUI rendering:
+     * alternate screen, hide cursor, bracketed paste, mouse tracking.
+     */
+    prepareTerminal(): void;
+    /**
+     * Restore the terminal to its normal state:
+     * disable mouse, disable bracketed paste, show cursor, leave alternate screen.
+     */
+    restoreTerminal(): void;
+    /** Reset all tracked state so the next write re-emits everything. */
+    private resetState;
+}

package/dist/ansi/output.js

@@ -0,0 +1,192 @@
+/**
+ * Buffered ANSI output writer.
+ * Inspired by Consolonia's AnsiConsoleOutput.cs — tracks terminal state
+ * to emit minimal escape sequences when writing pixels.
+ */
+import * as esc from "./esc.js";
+/** Sentinel value meaning "no color has been set yet". */
+const NO_COLOR = { r: -1, g: -1, b: -1, a: -1 };
+function colorsEqual(a, b) {
+    return a.r === b.r && a.g === b.g && a.b === b.b;
+}
+/**
+ * Buffered ANSI writer that accumulates escape sequences in a string buffer
+ * and flushes them in a single write to the underlying stream.
+ */
+export class AnsiOutput {
+    stream;
+    buf = "";
+    // ── Tracked state to avoid redundant escapes ──────────────────────
+    lastX = -1;
+    lastY = -1;
+    lastFgColor = NO_COLOR;
+    lastBgColor = NO_COLOR;
+    lastBold = false;
+    lastItalic = false;
+    lastUnderline = false;
+    lastStrikethrough = false;
+    constructor(stream) {
+        this.stream = stream ?? process.stdout;
+    }
+    // ── Low-level append ──────────────────────────────────────────────
+    /** Append raw text to the internal buffer. */
+    write(s) {
+        this.buf += s;
+    }
+    // ── Cursor ────────────────────────────────────────────────────────
+    /** Move cursor to (x, y) if not already there. */
+    setCursor(x, y) {
+        if (x !== this.lastX || y !== this.lastY) {
+            this.write(esc.moveTo(x, y));
+            this.lastX = x;
+            this.lastY = y;
+        }
+    }
+    /** Emit hide-cursor sequence. */
+    hideCursor() {
+        this.write(esc.hideCursor);
+    }
+    /** Emit show-cursor sequence. */
+    showCursor() {
+        this.write(esc.showCursor);
+    }
+    // ── Pixel writing ─────────────────────────────────────────────────
+    /**
+     * Write a single pixel at (x, y).
+     * Cursor is moved only if necessary. Colors and styles are set only when
+     * they differ from the previously written state.
+     */
+    writePixel(x, y, pixel) {
+        this.setCursor(x, y);
+        const fgColor = pixel.foreground.color;
+        const bgColor = pixel.background.color;
+        const { bold: isBold, italic: isItalic, underline: isUnderline, strikethrough: isStrike, } = pixel.foreground;
+        // ── Style toggles (emit only on change) ─────────────────────
+        if (isBold !== this.lastBold) {
+            this.write(isBold ? esc.bold : esc.boldOff);
+            this.lastBold = isBold;
+        }
+        if (isItalic !== this.lastItalic) {
+            this.write(isItalic ? esc.italic : esc.italicOff);
+            this.lastItalic = isItalic;
+        }
+        if (isUnderline !== this.lastUnderline) {
+            this.write(isUnderline ? esc.underline : esc.underlineOff);
+            this.lastUnderline = isUnderline;
+        }
+        if (isStrike !== this.lastStrikethrough) {
+            this.write(isStrike ? esc.strikethrough : esc.strikethroughOff);
+            this.lastStrikethrough = isStrike;
+        }
+        // ── Foreground color ────────────────────────────────────────
+        if (fgColor.a > 0 && !colorsEqual(fgColor, this.lastFgColor)) {
+            this.write(esc.fg(fgColor.r, fgColor.g, fgColor.b));
+            this.lastFgColor = fgColor;
+        }
+        else if (fgColor.a === 0 &&
+            this.lastFgColor !== NO_COLOR &&
+            this.lastFgColor.a !== 0) {
+            this.write(esc.fgDefault);
+            this.lastFgColor = NO_COLOR;
+        }
+        // ── Background color ────────────────────────────────────────
+        if (bgColor.a > 0 && !colorsEqual(bgColor, this.lastBgColor)) {
+            this.write(esc.bg(bgColor.r, bgColor.g, bgColor.b));
+            this.lastBgColor = bgColor;
+        }
+        else if (bgColor.a === 0 &&
+            this.lastBgColor !== NO_COLOR &&
+            this.lastBgColor.a !== 0) {
+            this.write(esc.bgDefault);
+            this.lastBgColor = NO_COLOR;
+        }
+        // ── Character ───────────────────────────────────────────────
+        const ch = pixel.foreground.symbol.text;
+        this.write(ch);
+        this.lastX += pixel.foreground.symbol.width;
+    }
+    /**
+     * Write a string starting at (x, y) with optional style overrides.
+     * Convenience wrapper that writes character-by-character is wasteful,
+     * so instead we set styles once and write the full text.
+     */
+    writeText(x, y, text, style) {
+        this.setCursor(x, y);
+        if (style) {
+            if (style.bold !== undefined && style.bold !== this.lastBold) {
+                this.write(style.bold ? esc.bold : esc.boldOff);
+                this.lastBold = style.bold;
+            }
+            if (style.italic !== undefined && style.italic !== this.lastItalic) {
+                this.write(style.italic ? esc.italic : esc.italicOff);
+                this.lastItalic = style.italic;
+            }
+            if (style.underline !== undefined &&
+                style.underline !== this.lastUnderline) {
+                this.write(style.underline ? esc.underline : esc.underlineOff);
+                this.lastUnderline = style.underline;
+            }
+            if (style.strikethrough !== undefined &&
+                style.strikethrough !== this.lastStrikethrough) {
+                this.write(style.strikethrough ? esc.strikethrough : esc.strikethroughOff);
+                this.lastStrikethrough = style.strikethrough;
+            }
+            if (style.fgColor && !colorsEqual(style.fgColor, this.lastFgColor)) {
+                this.write(esc.fg(style.fgColor.r, style.fgColor.g, style.fgColor.b));
+                this.lastFgColor = style.fgColor;
+            }
+            if (style.bgColor && !colorsEqual(style.bgColor, this.lastBgColor)) {
+                this.write(esc.bg(style.bgColor.r, style.bgColor.g, style.bgColor.b));
+                this.lastBgColor = style.bgColor;
+            }
+        }
+        this.write(text);
+        this.lastX += text.length;
+    }
+    // ── Flush ─────────────────────────────────────────────────────────
+    /** Write the accumulated buffer to the output stream and clear it. */
+    flush() {
+        if (this.buf.length > 0) {
+            this.stream.write(this.buf);
+            this.buf = "";
+        }
+    }
+    // ── Terminal setup / teardown ─────────────────────────────────────
+    /**
+     * Prepare the terminal for full-screen TUI rendering:
+     * alternate screen, hide cursor, bracketed paste, mouse tracking.
+     */
+    prepareTerminal() {
+        this.write(esc.alternateScreenOn);
+        this.write(esc.hideCursor);
+        this.write(esc.bracketedPasteOn);
+        this.write(esc.mouseTrackingOn);
+        this.write(esc.clearScreen);
+        this.flush();
+        this.resetState();
+    }
+    /**
+     * Restore the terminal to its normal state:
+     * disable mouse, disable bracketed paste, show cursor, leave alternate screen.
+     */
+    restoreTerminal() {
+        this.write(esc.reset);
+        this.write(esc.mouseTrackingOff);
+        this.write(esc.bracketedPasteOff);
+        this.write(esc.showCursor);
+        this.write(esc.alternateScreenOff);
+        this.flush();
+        this.resetState();
+    }
+    /** Reset all tracked state so the next write re-emits everything. */
+    resetState() {
+        this.lastX = -1;
+        this.lastY = -1;
+        this.lastFgColor = NO_COLOR;
+        this.lastBgColor = NO_COLOR;
+        this.lastBold = false;
+        this.lastItalic = false;
+        this.lastUnderline = false;
+        this.lastStrikethrough = false;
+    }
+}

package/dist/ansi/strip.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Functions for stripping and measuring ANSI-escaped strings.
+ */
+/**
+ * Strip all ANSI escape codes from a string, returning only visible characters.
+ */
+export declare function stripAnsi(str: string): string;
+/**
+ * Get the visible (non-ANSI) length of a string.
+ */
+export declare function visibleLength(str: string): number;
+/**
+ * Truncate a string containing ANSI codes to a maximum number of visible characters.
+ * ANSI sequences are preserved up to the cut-off point.
+ */
+export declare function truncateAnsi(str: string, maxWidth: number): string;

package/dist/ansi/strip.js

@@ -0,0 +1,74 @@
+/**
+ * Functions for stripping and measuring ANSI-escaped strings.
+ */
+/**
+ * Regex matching all common ANSI escape sequences:
+ * - CSI sequences: ESC [ ... <letter>
+ * - OSC sequences: ESC ] ... BEL/ST
+ * - Simple two-byte escapes: ESC <char>
+ */
+const ANSI_RE = 
+// eslint-disable-next-line no-control-regex
+/\x1b(?:\[[0-9;?]*[A-Za-z]|\][^\x07]*\x07|[()#][A-Za-z0-9]|[A-Za-z])/g;
+/**
+ * Strip all ANSI escape codes from a string, returning only visible characters.
+ */
+export function stripAnsi(str) {
+    return str.replace(ANSI_RE, "");
+}
+/**
+ * Get the visible (non-ANSI) length of a string.
+ */
+export function visibleLength(str) {
+    return stripAnsi(str).length;
+}
+/**
+ * Truncate a string containing ANSI codes to a maximum number of visible characters.
+ * ANSI sequences are preserved up to the cut-off point.
+ */
+export function truncateAnsi(str, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    let visible = 0;
+    let i = 0;
+    while (i < str.length && visible < maxWidth) {
+        // Check for ESC
+        if (str.charCodeAt(i) === 0x1b) {
+            // Try to match a CSI sequence: ESC [ ... letter
+            if (i + 1 < str.length && str.charCodeAt(i + 1) === 0x5b) {
+                // 0x5b = '['
+                let j = i + 2;
+                while (j < str.length &&
+                    str.charCodeAt(j) >= 0x20 &&
+                    str.charCodeAt(j) <= 0x3f) {
+                    j++;
+                }
+                if (j < str.length) {
+                    j++; // consume the final letter
+                }
+                i = j;
+                continue;
+            }
+            // Try to match an OSC sequence: ESC ] ... BEL
+            if (i + 1 < str.length && str.charCodeAt(i + 1) === 0x5d) {
+                // 0x5d = ']'
+                let j = i + 2;
+                while (j < str.length && str.charCodeAt(j) !== 0x07) {
+                    j++;
+                }
+                if (j < str.length) {
+                    j++; // consume BEL
+                }
+                i = j;
+                continue;
+            }
+            // Simple two-byte escape
+            i += 2;
+            continue;
+        }
+        // Visible character
+        visible++;
+        i++;
+    }
+    return str.slice(0, i);
+}

package/dist/app.d.ts

@@ -0,0 +1,68 @@
+/**
+ * App — the top-level shell that owns the entire terminal lifecycle.
+ *
+ * Creates and wires together all subsystems (PixelBuffer, AnsiOutput,
+ * RenderTarget, DrawingContext, InputProcessor) and drives the
+ * measure → arrange → render loop in response to input and resize events.
+ */
+import type { Control } from "./layout/control.js";
+export interface AppOptions {
+    /** Root control to render. */
+    root: Control;
+    /** Use alternate screen buffer (default: true). */
+    alternateScreen?: boolean;
+    /** Enable mouse tracking (default: false). */
+    mouse?: boolean;
+    /** Terminal title (optional). */
+    title?: string;
+}
+export declare class App {
+    readonly root: Control;
+    private readonly _alternateScreen;
+    private readonly _mouse;
+    private readonly _title;
+    private _output;
+    private _buffer;
+    private _dirtyRegions;
+    private _renderTarget;
+    private _drawingContext;
+    private _processor;
+    private _events;
+    private _running;
+    private _resolve;
+    private _stdinListener;
+    private _resizeListener;
+    private _sigintListener;
+    private _renderScheduled;
+    constructor(options: AppOptions);
+    /**
+     * Start the app — enters raw mode, sets up terminal, runs the event
+     * loop. Returns a promise that resolves when the app stops.
+     */
+    run(): Promise<void>;
+    /** Stop the app — restores terminal and exits the event loop. */
+    stop(): void;
+    /** Force a full re-render. */
+    refresh(): void;
+    private _setup;
+    private _prepareTerminal;
+    private _restoreTerminal;
+    private _createRenderPipeline;
+    private _setupInput;
+    private _handleInput;
+    private _handleResize;
+    /**
+     * Schedule a render pass using setImmediate so multiple rapid events
+     * within the same tick coalesce into a single render.
+     */
+    private _scheduleRender;
+    /** Perform a full measure → arrange → render cycle (used on init and resize). */
+    private _fullRender;
+    /** Perform an incremental render for dirty regions. */
+    private _renderFrame;
+    /** Recursively clear dirty flags on the entire control tree. */
+    private _clearDirty;
+    /** Run the initial render after setup. */
+    private _initialRender;
+    private _teardown;
+}