@teammates/consolonia 0.2.0

package/dist/pixel/symbol.js

@@ -0,0 +1,192 @@
+/**
+ * Represents a single cell's character content.
+ */
+/**
+ * Check if a code point is zero-width (invisible) and should be skipped
+ * during rendering. These characters have no visual representation and
+ * occupy zero terminal columns. If drawn as individual cells, terminals
+ * typically show them as "missing glyph" boxes.
+ */
+export function isZeroWidth(codePoint) {
+    // Soft hyphen
+    if (codePoint === 0x00ad)
+        return true;
+    // Combining diacritical marks (U+0300–U+036F)
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return true;
+    // Zero-width space, non-joiner, joiner
+    if (codePoint >= 0x200b && codePoint <= 0x200d)
+        return true;
+    // Left-to-right / right-to-left marks
+    if (codePoint >= 0x200e && codePoint <= 0x200f)
+        return true;
+    // LRE, RLE, PDF, LRO, RLO
+    if (codePoint >= 0x202a && codePoint <= 0x202e)
+        return true;
+    // Word joiner
+    if (codePoint === 0x2060)
+        return true;
+    // LRI, RLI, FSI, PDI
+    if (codePoint >= 0x2066 && codePoint <= 0x2069)
+        return true;
+    // Combining grapheme joiner
+    if (codePoint === 0x034f)
+        return true;
+    // Variation selectors (VS1-VS16)
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return true;
+    // BOM / zero-width no-break space
+    if (codePoint === 0xfeff)
+        return true;
+    // Variation selectors supplement (VS17-VS256)
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return true;
+    // Tags block (used in flag sequences)
+    if (codePoint >= 0xe0001 && codePoint <= 0xe007f)
+        return true;
+    return false;
+}
+/**
+ * Determine the display width of a single character.
+ * Returns 2 for wide characters (CJK, fullwidth forms, emoji), 1 otherwise.
+ */
+export function charWidth(codePoint) {
+    // CJK Unified Ideographs
+    if (codePoint >= 0x4e00 && codePoint <= 0x9fff)
+        return 2;
+    // CJK Unified Ideographs Extension A
+    if (codePoint >= 0x3400 && codePoint <= 0x4dbf)
+        return 2;
+    // CJK Unified Ideographs Extension B
+    if (codePoint >= 0x20000 && codePoint <= 0x2a6df)
+        return 2;
+    // CJK Compatibility Ideographs
+    if (codePoint >= 0xf900 && codePoint <= 0xfaff)
+        return 2;
+    // Fullwidth Forms (excluding halfwidth range)
+    if (codePoint >= 0xff01 && codePoint <= 0xff60)
+        return 2;
+    // Fullwidth Forms (extra)
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    // CJK Radicals Supplement
+    if (codePoint >= 0x2e80 && codePoint <= 0x2eff)
+        return 2;
+    // Kangxi Radicals
+    if (codePoint >= 0x2f00 && codePoint <= 0x2fdf)
+        return 2;
+    // CJK Symbols and Punctuation
+    if (codePoint >= 0x3000 && codePoint <= 0x303f)
+        return 2;
+    // Hiragana
+    if (codePoint >= 0x3040 && codePoint <= 0x309f)
+        return 2;
+    // Katakana
+    if (codePoint >= 0x30a0 && codePoint <= 0x30ff)
+        return 2;
+    // Bopomofo
+    if (codePoint >= 0x3100 && codePoint <= 0x312f)
+        return 2;
+    // Hangul Compatibility Jamo
+    if (codePoint >= 0x3130 && codePoint <= 0x318f)
+        return 2;
+    // Kanbun
+    if (codePoint >= 0x3190 && codePoint <= 0x319f)
+        return 2;
+    // Bopomofo Extended
+    if (codePoint >= 0x31a0 && codePoint <= 0x31bf)
+        return 2;
+    // CJK Strokes
+    if (codePoint >= 0x31c0 && codePoint <= 0x31ef)
+        return 2;
+    // Katakana Phonetic Extensions
+    if (codePoint >= 0x31f0 && codePoint <= 0x31ff)
+        return 2;
+    // Enclosed CJK Letters and Months
+    if (codePoint >= 0x3200 && codePoint <= 0x32ff)
+        return 2;
+    // CJK Compatibility
+    if (codePoint >= 0x3300 && codePoint <= 0x33ff)
+        return 2;
+    // Hangul Syllables
+    if (codePoint >= 0xac00 && codePoint <= 0xd7af)
+        return 2;
+    // CJK Compatibility Ideographs Supplement
+    if (codePoint >= 0x2f800 && codePoint <= 0x2fa1f)
+        return 2;
+    // ── Emoji ranges (rendered as width 2 on modern terminals) ─────
+    // Hourglass + Watch
+    if (codePoint === 0x231a || codePoint === 0x231b)
+        return 2;
+    // Player controls (⏩-⏳)
+    if (codePoint >= 0x23e9 && codePoint <= 0x23f3)
+        return 2;
+    // Media controls (⏸-⏺)
+    if (codePoint >= 0x23f8 && codePoint <= 0x23fa)
+        return 2;
+    // Play / reverse play buttons
+    if (codePoint === 0x25b6 || codePoint === 0x25c0)
+        return 2;
+    // Geometric shapes used as emoji (◻◼◽◾)
+    if (codePoint >= 0x25fb && codePoint <= 0x25fe)
+        return 2;
+    // Miscellaneous Symbols — most have emoji presentation (☀-⛿)
+    if (codePoint >= 0x2600 && codePoint <= 0x26ff)
+        return 2;
+    // Dingbats with emoji presentation (✂-➿)
+    if (codePoint >= 0x2702 && codePoint <= 0x27b0)
+        return 2;
+    // Curly loop
+    if (codePoint === 0x27bf)
+        return 2;
+    // Supplemental arrows used as emoji
+    if (codePoint === 0x2934 || codePoint === 0x2935)
+        return 2;
+    // Misc symbols used as emoji (⬛⬜⭐⭕)
+    if (codePoint >= 0x2b05 && codePoint <= 0x2b07)
+        return 2;
+    if (codePoint === 0x2b1b || codePoint === 0x2b1c)
+        return 2;
+    if (codePoint === 0x2b50 || codePoint === 0x2b55)
+        return 2;
+    // Copyright / Registered / TM (when emoji-styled)
+    if (codePoint === 0x00a9 || codePoint === 0x00ae)
+        return 2;
+    // Wavy dash, part alternation mark
+    if (codePoint === 0x3030 || codePoint === 0x303d)
+        return 2;
+    // SMP Emoji: Mahjong through Symbols & Pictographs Extended-A
+    // Covers emoticons, transport, flags, supplemental symbols, etc.
+    if (codePoint >= 0x1f000 && codePoint <= 0x1faff)
+        return 2;
+    return 1;
+}
+/**
+ * Calculate the display width of a string (sum of charWidth per code point).
+ * Zero-width characters (variation selectors, ZWJ, etc.) are excluded.
+ * Useful for layout and wrapping where terminal column count matters.
+ */
+export function stringDisplayWidth(text) {
+    let width = 0;
+    for (const char of text) {
+        const cp = char.codePointAt(0);
+        if (!isZeroWidth(cp)) {
+            width += charWidth(cp);
+        }
+    }
+    return width;
+}
+/**
+ * Create a Symbol from a text string.
+ * Width is auto-detected from the first code point.
+ */
+export function sym(text, pattern = 0) {
+    const cp = text.codePointAt(0) ?? 0;
+    return {
+        text,
+        width: pattern !== 0 ? 1 : charWidth(cp),
+        pattern,
+    };
+}
+/** An empty symbol (space character). */
+export const EMPTY_SYMBOL = { text: " ", width: 1, pattern: 0 };

package/dist/render/regions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Dirty-region tracking for incremental rendering.
+ * Port of Consolonia's Regions.cs / Snapshot pattern.
+ *
+ * Maintains a list of dirty rectangles and provides a snapshot mechanism
+ * so the renderer can consume the current set while new rects accumulate.
+ */
+import type { Rect } from "../layout/types.js";
+/**
+ * A frozen snapshot of dirty rectangles at the moment it was taken.
+ * The renderer iterates cells and calls `contains(x, y)` to decide
+ * whether a given cell needs to be re-drawn.
+ */
+export declare class DirtySnapshot {
+    private readonly _rects;
+    constructor(rects: readonly Rect[]);
+    /**
+     * Returns true if (x, y) falls inside any of the snapshot's rectangles.
+     * Uses exclusive upper bounds: a Rect {x:0, y:0, width:10, height:5}
+     * contains columns 0-9 and rows 0-4.
+     */
+    contains(x: number, y: number): boolean;
+}
+/**
+ * Accumulates dirty rectangles.  Before each render pass the renderer
+ * calls `getSnapshotAndClear()` which atomically captures the current
+ * set and resets the internal list so new mutations can be collected
+ * while the frame is being drawn.
+ */
+export declare class DirtyRegions {
+    private _rects;
+    /**
+     * Register a rectangle as dirty.
+     *
+     * Optimisations (mirroring the C# Regions.AddRect):
+     *  - If `rect` is empty (width or height <= 0), it is ignored.
+     *  - If an existing rect already fully contains the new one, skip.
+     *  - If the new rect fully contains an existing one, remove the existing one.
+     */
+    addRect(rect: Rect): void;
+    /**
+     * Check whether a point is inside any tracked dirty region.
+     * Uses exclusive upper bounds (same semantics as DirtySnapshot.contains).
+     */
+    contains(x: number, y: number): boolean;
+    /**
+     * Capture a snapshot of the current dirty rects and reset the list.
+     */
+    getSnapshotAndClear(): DirtySnapshot;
+    /**
+     * Discard all tracked regions without creating a snapshot.
+     */
+    clear(): void;
+}

package/dist/render/regions.js

@@ -0,0 +1,102 @@
+/**
+ * Dirty-region tracking for incremental rendering.
+ * Port of Consolonia's Regions.cs / Snapshot pattern.
+ *
+ * Maintains a list of dirty rectangles and provides a snapshot mechanism
+ * so the renderer can consume the current set while new rects accumulate.
+ */
+// ── Snapshot ────────────────────────────────────────────────────────
+/**
+ * A frozen snapshot of dirty rectangles at the moment it was taken.
+ * The renderer iterates cells and calls `contains(x, y)` to decide
+ * whether a given cell needs to be re-drawn.
+ */
+export class DirtySnapshot {
+    _rects;
+    constructor(rects) {
+        this._rects = rects;
+    }
+    /**
+     * Returns true if (x, y) falls inside any of the snapshot's rectangles.
+     * Uses exclusive upper bounds: a Rect {x:0, y:0, width:10, height:5}
+     * contains columns 0-9 and rows 0-4.
+     */
+    contains(x, y) {
+        for (const r of this._rects) {
+            if (x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+// ── DirtyRegions ────────────────────────────────────────────────────
+/**
+ * Accumulates dirty rectangles.  Before each render pass the renderer
+ * calls `getSnapshotAndClear()` which atomically captures the current
+ * set and resets the internal list so new mutations can be collected
+ * while the frame is being drawn.
+ */
+export class DirtyRegions {
+    _rects = [];
+    /**
+     * Register a rectangle as dirty.
+     *
+     * Optimisations (mirroring the C# Regions.AddRect):
+     *  - If `rect` is empty (width or height <= 0), it is ignored.
+     *  - If an existing rect already fully contains the new one, skip.
+     *  - If the new rect fully contains an existing one, remove the existing one.
+     */
+    addRect(rect) {
+        if (rect.width <= 0 || rect.height <= 0)
+            return;
+        for (let i = 0; i < this._rects.length; i++) {
+            const existing = this._rects[i];
+            // Existing rect contains the new one — nothing to add.
+            if (rectContains(existing, rect))
+                return;
+            // New rect contains the existing one — remove existing.
+            if (rectContains(rect, existing)) {
+                this._rects.splice(i, 1);
+                i--;
+            }
+        }
+        this._rects.push(rect);
+    }
+    /**
+     * Check whether a point is inside any tracked dirty region.
+     * Uses exclusive upper bounds (same semantics as DirtySnapshot.contains).
+     */
+    contains(x, y) {
+        for (const r of this._rects) {
+            if (x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Capture a snapshot of the current dirty rects and reset the list.
+     */
+    getSnapshotAndClear() {
+        const snapshot = new DirtySnapshot([...this._rects]);
+        this._rects = [];
+        return snapshot;
+    }
+    /**
+     * Discard all tracked regions without creating a snapshot.
+     */
+    clear() {
+        this._rects = [];
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+/**
+ * Returns true when `outer` fully contains `inner` (exclusive upper bound).
+ */
+function rectContains(outer, inner) {
+    return (inner.x >= outer.x &&
+        inner.y >= outer.y &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y + inner.height <= outer.y + outer.height);
+}

package/dist/render/render-target.d.ts

@@ -0,0 +1,42 @@
+/**
+ * RenderTarget — incremental pixel renderer.
+ * Port of Consolonia's RenderTarget.cs.
+ *
+ * Compares the current PixelBuffer against a cached copy of what was
+ * last written to output, and only emits ANSI sequences for cells that
+ * have actually changed *and* fall inside the current dirty regions.
+ */
+import type { AnsiOutput } from "../ansi/output.js";
+import type { PixelBuffer } from "../pixel/buffer.js";
+import type { Pixel } from "../pixel/pixel.js";
+import { DirtyRegions } from "./regions.js";
+export declare class RenderTarget {
+    private readonly _buffer;
+    private readonly _output;
+    /** 2-D cache indexed [y][x]. null means "never rendered at this cell". */
+    private _cache;
+    constructor(buffer: PixelBuffer, output: AnsiOutput);
+    /**
+     * Render only the cells that are both inside a dirty region *and*
+     * differ from the cached version last written to output.
+     */
+    render(dirtyRegions: DirtyRegions): void;
+    /**
+     * Recreate the cache at new dimensions.  Every cell is set to null
+     * so the next render pass will treat everything as dirty.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Mark the entire buffer as dirty and perform a full render pass.
+     */
+    fullRender(): void;
+    /**
+     * Retrieve the cached pixel at (x, y) — useful for tests.
+     * Returns null if the cell has never been rendered.
+     */
+    getCachePixel(x: number, y: number): Pixel | null;
+    /**
+     * Build a fresh cache grid filled with null (meaning "unknown / never rendered").
+     */
+    private _initCache;
+}

package/dist/render/render-target.js

@@ -0,0 +1,118 @@
+/**
+ * RenderTarget — incremental pixel renderer.
+ * Port of Consolonia's RenderTarget.cs.
+ *
+ * Compares the current PixelBuffer against a cached copy of what was
+ * last written to output, and only emits ANSI sequences for cells that
+ * have actually changed *and* fall inside the current dirty regions.
+ */
+import { DirtyRegions } from "./regions.js";
+export class RenderTarget {
+    _buffer;
+    _output;
+    /** 2-D cache indexed [y][x]. null means "never rendered at this cell". */
+    _cache;
+    constructor(buffer, output) {
+        this._buffer = buffer;
+        this._output = output;
+        this._cache = this._initCache(buffer.width, buffer.height);
+    }
+    // ── Public API ──────────────────────────────────────────────────
+    /**
+     * Render only the cells that are both inside a dirty region *and*
+     * differ from the cached version last written to output.
+     */
+    render(dirtyRegions) {
+        const snapshot = dirtyRegions.getSnapshotAndClear();
+        this._output.hideCursor();
+        for (let y = 0; y < this._buffer.height; y++) {
+            for (let x = 0; x < this._buffer.width; x++) {
+                if (!snapshot.contains(x, y))
+                    continue;
+                const pixel = this._buffer.get(x, y);
+                const cached = this._cache[y][x];
+                if (cached !== null && pixelsEqual(pixel, cached))
+                    continue;
+                this._output.writePixel(x, y, pixel);
+                this._cache[y][x] = pixel;
+            }
+        }
+        this._output.flush();
+    }
+    /**
+     * Recreate the cache at new dimensions.  Every cell is set to null
+     * so the next render pass will treat everything as dirty.
+     */
+    resize(width, height) {
+        this._cache = this._initCache(width, height);
+    }
+    /**
+     * Mark the entire buffer as dirty and perform a full render pass.
+     */
+    fullRender() {
+        const regions = new DirtyRegions();
+        regions.addRect({
+            x: 0,
+            y: 0,
+            width: this._buffer.width,
+            height: this._buffer.height,
+        });
+        this.render(regions);
+    }
+    /**
+     * Retrieve the cached pixel at (x, y) — useful for tests.
+     * Returns null if the cell has never been rendered.
+     */
+    getCachePixel(x, y) {
+        if (y < 0 || y >= this._cache.length)
+            return null;
+        if (x < 0 || x >= this._cache[y].length)
+            return null;
+        return this._cache[y][x];
+    }
+    // ── Internal ────────────────────────────────────────────────────
+    /**
+     * Build a fresh cache grid filled with null (meaning "unknown / never rendered").
+     */
+    _initCache(width, height) {
+        const cache = [];
+        for (let y = 0; y < height; y++) {
+            const row = new Array(width).fill(null);
+            cache.push(row);
+        }
+        return cache;
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+/**
+ * Shallow structural equality for two Pixel values.
+ *
+ * Pixels are plain data objects so reference equality is almost never
+ * true.  We compare every leaf field instead.  The implementation is
+ * kept deliberately simple — if the Pixel type grows, this function
+ * must be updated.
+ */
+function pixelsEqual(a, b) {
+    // Fast path: same reference.
+    if (a === b)
+        return true;
+    // Compare foreground
+    const af = a.foreground;
+    const bf = b.foreground;
+    if (af.symbol.text !== bf.symbol.text)
+        return false;
+    if (af.symbol.width !== bf.symbol.width)
+        return false;
+    if (!colorsEq(af.color, bf.color))
+        return false;
+    // Compare background
+    const ab = a.background;
+    const bb = b.background;
+    if (!colorsEq(ab.color, bb.color))
+        return false;
+    return true;
+}
+/** Fast inline color equality (avoids importing colorsEqual). */
+function colorsEq(a, b) {
+    return a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;
+}

package/dist/styled.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Styled — a chalk-like fluent API for building styled text segments.
+ *
+ * Instead of producing ANSI escape codes (which only work on raw stdout),
+ * Styled produces {text, style} segment arrays that can be rendered into
+ * a pixel buffer via DrawingContext.
+ *
+ * Usage:
+ *   import { pen } from "@teammates/consolonia";
+ *
+ *   // Single styled segment
+ *   pen.cyan("hello")            → [{ text: "hello", style: { fg: CYAN } }]
+ *
+ *   // Chained styles
+ *   pen.bold.red("error")        → [{ text: "error", style: { fg: RED, bold: true } }]
+ *
+ *   // Concatenation with +
+ *   pen.green("✔ ") + pen.white("done")
+ *     → [{ text: "✔ ", style: { fg: GREEN } }, { text: "done", style: { fg: WHITE } }]
+ *
+ *   // Mixed plain + styled
+ *   pen("prefix ") + pen.cyan("@name")
+ *     → [{ text: "prefix ", style: {} }, { text: "@name", style: { fg: CYAN } }]
+ *
+ *   // Gray is dim white (like chalk.gray)
+ *   pen.gray("muted")           → [{ text: "muted", style: { fg: GRAY } }]
+ */
+import type { TextStyle } from "./drawing/context.js";
+import type { Color } from "./pixel/color.js";
+/** A piece of text with an associated style. */
+export interface StyledSegment {
+    text: string;
+    style: TextStyle;
+}
+/**
+ * An array of styled segments that supports + concatenation with
+ * other StyledSpan values or plain strings.
+ */
+export type StyledSpan = StyledSegment[] & {
+    __brand: "StyledSpan";
+};
+/** Check if a value is a StyledSpan. */
+export declare function isStyledSpan(v: unknown): v is StyledSpan;
+/** Concatenate styled spans and/or plain strings. */
+export declare function concat(...parts: (StyledSpan | string)[]): StyledSpan;
+/** Get the visible (unstyled) text from a StyledSpan. */
+export declare function spanText(s: StyledSpan): string;
+/** Get the visible display width of a StyledSpan (accounts for wide characters). */
+export declare function spanLength(s: StyledSpan): number;
+interface PenCallable {
+    /** Create an unstyled span from a plain string. */
+    (text: string): StyledSpan;
+}
+type Pen = PenCallable & {
+    readonly black: Pen;
+    readonly red: Pen;
+    readonly green: Pen;
+    readonly yellow: Pen;
+    readonly blue: Pen;
+    readonly magenta: Pen;
+    readonly cyan: Pen;
+    readonly white: Pen;
+    readonly blackBright: Pen;
+    readonly redBright: Pen;
+    readonly greenBright: Pen;
+    readonly yellowBright: Pen;
+    readonly blueBright: Pen;
+    readonly magentaBright: Pen;
+    readonly cyanBright: Pen;
+    readonly whiteBright: Pen;
+    readonly gray: Pen;
+    readonly grey: Pen;
+    readonly darkGray: Pen;
+    readonly lightGray: Pen;
+    readonly bgBlack: Pen;
+    readonly bgRed: Pen;
+    readonly bgGreen: Pen;
+    readonly bgYellow: Pen;
+    readonly bgBlue: Pen;
+    readonly bgMagenta: Pen;
+    readonly bgCyan: Pen;
+    readonly bgWhite: Pen;
+    readonly bgBlackBright: Pen;
+    readonly bgRedBright: Pen;
+    readonly bgGreenBright: Pen;
+    readonly bgYellowBright: Pen;
+    readonly bgBlueBright: Pen;
+    readonly bgMagentaBright: Pen;
+    readonly bgCyanBright: Pen;
+    readonly bgWhiteBright: Pen;
+    readonly bgGray: Pen;
+    readonly bgGrey: Pen;
+    /** Set foreground to an arbitrary Color. */
+    readonly fg: (c: Color) => Pen;
+    /** Set background to an arbitrary Color. */
+    readonly bg: (c: Color) => Pen;
+    readonly bold: Pen;
+    readonly italic: Pen;
+    readonly underline: Pen;
+    readonly strikethrough: Pen;
+    readonly dim: Pen;
+};
+/**
+ * The default pen — starting point for building styled text.
+ *
+ * Usage:
+ *   pen("plain text")
+ *   pen.cyan("colored")
+ *   pen.bold.red("bold red")
+ *   pen.bgBlue.white("white on blue")
+ */
+export declare const pen: Pen;
+export {};