@teammates/consolonia 0.2.0

package/dist/app.js

@@ -0,0 +1,297 @@
+/**
+ * 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 * as esc from "./ansi/esc.js";
+import { AnsiOutput } from "./ansi/output.js";
+import { DrawingContext } from "./drawing/context.js";
+import { createInputProcessor } from "./input/processor.js";
+import { disableRawMode, enableRawMode } from "./input/raw-mode.js";
+import { PixelBuffer } from "./pixel/buffer.js";
+import { DirtyRegions } from "./render/regions.js";
+import { RenderTarget } from "./render/render-target.js";
+// ── App ──────────────────────────────────────────────────────────────
+export class App {
+    root;
+    _alternateScreen;
+    _mouse;
+    _title;
+    // Subsystems — created during run()
+    _output;
+    _buffer;
+    _dirtyRegions;
+    _renderTarget;
+    _drawingContext;
+    _processor;
+    _events;
+    // Lifecycle bookkeeping
+    _running = false;
+    _resolve = null;
+    _stdinListener = null;
+    _resizeListener = null;
+    _sigintListener = null;
+    _renderScheduled = false;
+    constructor(options) {
+        this.root = options.root;
+        this._alternateScreen = options.alternateScreen ?? true;
+        this._mouse = options.mouse ?? false;
+        this._title = options.title;
+    }
+    // ── Public API ───────────────────────────────────────────────────
+    /**
+     * Start the app — enters raw mode, sets up terminal, runs the event
+     * loop. Returns a promise that resolves when the app stops.
+     */
+    run() {
+        if (this._running) {
+            return Promise.reject(new Error("App is already running"));
+        }
+        this._running = true;
+        return new Promise((resolve) => {
+            this._resolve = resolve;
+            try {
+                this._setup();
+                this._initialRender();
+            }
+            catch (err) {
+                this._teardown();
+                throw err;
+            }
+        });
+    }
+    /** Stop the app — restores terminal and exits the event loop. */
+    stop() {
+        if (!this._running)
+            return;
+        this._teardown();
+    }
+    /** Force a full re-render. */
+    refresh() {
+        if (!this._running)
+            return;
+        this._fullRender();
+    }
+    // ── Setup ────────────────────────────────────────────────────────
+    _setup() {
+        const stdout = process.stdout;
+        // 1. Enable raw mode
+        enableRawMode();
+        // 2. Create ANSI output
+        this._output = new AnsiOutput(stdout);
+        // 3. Prepare terminal (custom sequence instead of prepareTerminal()
+        //    so we can conditionally enable mouse tracking)
+        this._prepareTerminal();
+        // 4. Set terminal title
+        if (this._title) {
+            stdout.write(esc.setTitle(this._title));
+        }
+        // 5. Create pixel buffer at terminal dimensions
+        const cols = stdout.columns || 80;
+        const rows = stdout.rows || 24;
+        this._createRenderPipeline(cols, rows);
+        // 6. Wire up input
+        this._setupInput();
+        // 7. Wire up resize
+        this._resizeListener = () => this._handleResize();
+        stdout.on("resize", this._resizeListener);
+        // 8. SIGINT fallback
+        this._sigintListener = () => this.stop();
+        process.on("SIGINT", this._sigintListener);
+    }
+    _prepareTerminal() {
+        const stream = process.stdout;
+        let seq = "";
+        if (this._alternateScreen) {
+            seq += esc.alternateScreenOn;
+        }
+        seq += esc.hideCursor;
+        seq += esc.bracketedPasteOn;
+        if (this._mouse) {
+            seq += esc.mouseTrackingOn;
+        }
+        seq += esc.clearScreen;
+        stream.write(seq);
+    }
+    _restoreTerminal() {
+        const stream = process.stdout;
+        let seq = esc.reset;
+        if (this._mouse) {
+            seq += esc.mouseTrackingOff;
+        }
+        seq += esc.bracketedPasteOff;
+        seq += esc.showCursor;
+        if (this._alternateScreen) {
+            seq += esc.alternateScreenOff;
+        }
+        stream.write(seq);
+    }
+    _createRenderPipeline(cols, rows) {
+        this._buffer = new PixelBuffer(cols, rows);
+        this._dirtyRegions = new DirtyRegions();
+        this._renderTarget = new RenderTarget(this._buffer, this._output);
+        this._drawingContext = new DrawingContext(this._buffer);
+    }
+    _setupInput() {
+        const { processor, events } = createInputProcessor();
+        this._processor = processor;
+        this._events = events;
+        // Listen for parsed input events
+        this._events.on("input", (event) => {
+            this._handleInput(event);
+        });
+        // Feed raw stdin data to the processor
+        this._stdinListener = (data) => {
+            this._processor.feed(data);
+        };
+        process.stdin.on("data", this._stdinListener);
+    }
+    // ── Input handling ───────────────────────────────────────────────
+    _handleInput(event) {
+        // Dispatch to root control (including Ctrl+C — let the app handle it)
+        this.root.handleInput(event);
+        // Schedule a render if the tree is dirty
+        this._scheduleRender();
+    }
+    // ── Resize handling ──────────────────────────────────────────────
+    _handleResize() {
+        const stdout = process.stdout;
+        const cols = stdout.columns || 80;
+        const rows = stdout.rows || 24;
+        // Recreate render pipeline at new size
+        this._buffer = new PixelBuffer(cols, rows);
+        this._dirtyRegions = new DirtyRegions();
+        this._renderTarget = new RenderTarget(this._buffer, this._output);
+        this._drawingContext = new DrawingContext(this._buffer);
+        // Mark root as dirty and do a full render
+        this.root.invalidate();
+        this._fullRender();
+    }
+    // ── Render loop ──────────────────────────────────────────────────
+    /**
+     * Schedule a render pass using setImmediate so multiple rapid events
+     * within the same tick coalesce into a single render.
+     */
+    _scheduleRender() {
+        if (this._renderScheduled || !this._running)
+            return;
+        this._renderScheduled = true;
+        setImmediate(() => {
+            this._renderScheduled = false;
+            if (!this._running)
+                return;
+            if (this.root.dirty) {
+                this._renderFrame();
+            }
+        });
+    }
+    /** Perform a full measure → arrange → render cycle (used on init and resize). */
+    _fullRender() {
+        if (!this._running)
+            return;
+        const cols = this._buffer.width;
+        const rows = this._buffer.height;
+        // Clear buffer
+        this._buffer.clear();
+        // Measure
+        const constraint = {
+            minWidth: 0,
+            maxWidth: cols,
+            minHeight: 0,
+            maxHeight: rows,
+        };
+        this.root.measure(constraint);
+        // Arrange
+        const arrangeRect = { x: 0, y: 0, width: cols, height: rows };
+        this.root.arrange(arrangeRect);
+        // Render control tree into buffer
+        this.root.render(this._drawingContext);
+        this._clearDirty(this.root);
+        // Mark entire screen dirty and flush to terminal
+        this._dirtyRegions.addRect({
+            x: 0,
+            y: 0,
+            width: cols,
+            height: rows,
+        });
+        this._renderTarget.render(this._dirtyRegions);
+    }
+    /** Perform an incremental render for dirty regions. */
+    _renderFrame() {
+        const cols = this._buffer.width;
+        const rows = this._buffer.height;
+        // Clear buffer
+        this._buffer.clear();
+        // Measure
+        const constraint = {
+            minWidth: 0,
+            maxWidth: cols,
+            minHeight: 0,
+            maxHeight: rows,
+        };
+        this.root.measure(constraint);
+        // Arrange
+        const arrangeRect = { x: 0, y: 0, width: cols, height: rows };
+        this.root.arrange(arrangeRect);
+        // Mark the full area as dirty (controls re-render their full bounds)
+        this._dirtyRegions.addRect({
+            x: 0,
+            y: 0,
+            width: cols,
+            height: rows,
+        });
+        // Render control tree into buffer
+        this.root.render(this._drawingContext);
+        this._clearDirty(this.root);
+        // Diff and flush to terminal
+        this._renderTarget.render(this._dirtyRegions);
+    }
+    /** Recursively clear dirty flags on the entire control tree. */
+    _clearDirty(ctrl) {
+        ctrl.dirty = false;
+        for (const child of ctrl.children) {
+            this._clearDirty(child);
+        }
+    }
+    /** Run the initial render after setup. */
+    _initialRender() {
+        this._fullRender();
+    }
+    // ── Teardown ─────────────────────────────────────────────────────
+    _teardown() {
+        if (!this._running)
+            return;
+        this._running = false;
+        // Remove stdin listener
+        if (this._stdinListener) {
+            process.stdin.removeListener("data", this._stdinListener);
+            this._stdinListener = null;
+        }
+        // Remove resize listener
+        if (this._resizeListener) {
+            process.stdout.removeListener("resize", this._resizeListener);
+            this._resizeListener = null;
+        }
+        // Remove SIGINT listener
+        if (this._sigintListener) {
+            process.removeListener("SIGINT", this._sigintListener);
+            this._sigintListener = null;
+        }
+        // Destroy input processor (clears timers)
+        if (this._processor) {
+            this._processor.destroy();
+        }
+        // Restore terminal
+        this._restoreTerminal();
+        // Disable raw mode
+        disableRawMode();
+        // Resolve the run() promise
+        if (this._resolve) {
+            const resolve = this._resolve;
+            this._resolve = null;
+            resolve();
+        }
+    }
+}

package/dist/drawing/clip.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Clip stack: manages a stack of clip rectangles for restricting drawing regions.
+ *
+ * Each push intersects the new rect with the current top to produce the effective
+ * clip. Pop restores the previous effective clip.
+ */
+import type { Rect } from "../layout/types.js";
+export declare class ClipStack {
+    /**
+     * Stack of effective clip rects. Each entry is the intersection of the
+     * pushed rect with its parent. A null entry means the clip is fully
+     * degenerate (zero-area) but we still track it so pop() works correctly.
+     */
+    private readonly stack;
+    /** Push a clip rectangle. Drawing outside this rect is ignored. */
+    push(rect: Rect): void;
+    /** Pop the last clip rectangle. */
+    pop(): void;
+    /** Check if a point is within the current clip bounds. */
+    contains(x: number, y: number): boolean;
+    /** Get the current effective clip rect (intersection of all pushed rects). */
+    current(): Rect | null;
+}

package/dist/drawing/clip.js

@@ -0,0 +1,67 @@
+/**
+ * Clip stack: manages a stack of clip rectangles for restricting drawing regions.
+ *
+ * Each push intersects the new rect with the current top to produce the effective
+ * clip. Pop restores the previous effective clip.
+ */
+/**
+ * Intersect two rectangles, returning the overlapping region.
+ * Returns null if there is no overlap.
+ */
+function intersectRects(a, b) {
+    const x0 = Math.max(a.x, b.x);
+    const y0 = Math.max(a.y, b.y);
+    const x1 = Math.min(a.x + a.width, b.x + b.width);
+    const y1 = Math.min(a.y + a.height, b.y + b.height);
+    if (x1 <= x0 || y1 <= y0)
+        return null;
+    return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+}
+export class ClipStack {
+    /**
+     * Stack of effective clip rects. Each entry is the intersection of the
+     * pushed rect with its parent. A null entry means the clip is fully
+     * degenerate (zero-area) but we still track it so pop() works correctly.
+     */
+    stack = [];
+    /** Push a clip rectangle. Drawing outside this rect is ignored. */
+    push(rect) {
+        const top = this.current();
+        if (top === null && this.stack.length > 0) {
+            // Already fully clipped — intersection stays null
+            this.stack.push(null);
+        }
+        else if (top === null) {
+            // First push — use the rect directly
+            this.stack.push(rect);
+        }
+        else {
+            this.stack.push(intersectRects(top, rect));
+        }
+    }
+    /** Pop the last clip rectangle. */
+    pop() {
+        if (this.stack.length === 0) {
+            throw new Error("ClipStack underflow: cannot pop from an empty stack");
+        }
+        this.stack.pop();
+    }
+    /** Check if a point is within the current clip bounds. */
+    contains(x, y) {
+        const clip = this.current();
+        if (clip === null) {
+            // No clip means everything is visible (empty stack) or nothing is (degenerate)
+            return this.stack.length === 0;
+        }
+        return (x >= clip.x &&
+            x < clip.x + clip.width &&
+            y >= clip.y &&
+            y < clip.y + clip.height);
+    }
+    /** Get the current effective clip rect (intersection of all pushed rects). */
+    current() {
+        if (this.stack.length === 0)
+            return null;
+        return this.stack[this.stack.length - 1] ?? null;
+    }
+}

package/dist/drawing/context.d.ts

@@ -0,0 +1,77 @@
+/**
+ * DrawingContext: the main drawing API for rendering to a PixelBuffer.
+ *
+ * Port of Consolonia's DrawingContextImpl.cs + DrawingContextImpl.Boxes.cs,
+ * simplified for the Node.js/TypeScript environment.
+ */
+import type { Rect } from "../layout/types.js";
+import type { PixelBuffer } from "../pixel/buffer.js";
+import type { Color } from "../pixel/color.js";
+import type { Pixel } from "../pixel/pixel.js";
+export interface TextStyle {
+    fg?: Color;
+    bg?: Color;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+export interface BoxStyle {
+    fg?: Color;
+    bg?: Color;
+    bold?: boolean;
+}
+export declare class DrawingContext {
+    private readonly buffer;
+    private readonly clipStack;
+    private translateStack;
+    private offsetX;
+    private offsetY;
+    constructor(buffer: PixelBuffer);
+    /** Push a clip rectangle. All drawing is clipped to this region. */
+    pushClip(rect: Rect): void;
+    /** Pop the last clip rectangle. */
+    popClip(): void;
+    /** Push a coordinate translation. All drawing coordinates are offset. */
+    pushTranslate(dx: number, dy: number): void;
+    /** Pop the last coordinate translation. */
+    popTranslate(): void;
+    /** Translate a point by the current offset. */
+    private tx;
+    private ty;
+    /** Check if a local-coord point is visible after translate. */
+    private isVisible;
+    /** Get a pixel at local coordinates (translated to buffer coords). */
+    private bufGet;
+    /** Set a pixel at local coordinates (translated to buffer coords). */
+    private bufSet;
+    /** Fill a rectangle with a solid color. */
+    fillRect(rect: Rect, color: Color): void;
+    /** Draw a single character at (x, y) with styling. */
+    drawChar(x: number, y: number, char: string, style?: TextStyle): void;
+    /** Draw a text string at (x, y). Handles wide characters and tabs. */
+    drawText(x: number, y: number, text: string, style?: TextStyle): void;
+    /**
+     * Draw an array of styled segments at (x, y).
+     * Each segment carries its own TextStyle; segments are drawn sequentially.
+     */
+    drawStyledText(x: number, y: number, segments: {
+        text: string;
+        style: TextStyle;
+    }[]): void;
+    /** Draw a box-drawing rectangle (border) with smart corner merging. */
+    drawBox(rect: Rect, style?: BoxStyle): void;
+    /**
+     * Draw a single box-drawing character at (x, y), merging with any existing
+     * box pattern at that position.
+     */
+    private drawBoxChar;
+    /** Draw a horizontal line using box-drawing characters. */
+    drawHLine(x: number, y: number, width: number, style?: TextStyle): void;
+    /** Draw a vertical line using box-drawing characters. */
+    drawVLine(x: number, y: number, height: number, style?: TextStyle): void;
+    /** Set a pixel directly. Respects clip. */
+    setPixel(x: number, y: number, pixel: Pixel): void;
+    /** Blend a pixel at (x, y) with what's already there. Respects clip. */
+    blendPixel(x: number, y: number, pixel: Pixel): void;
+}