@teammates/consolonia 0.2.0

package/dist/layout/stack.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Stack — z-stacking container.
+ *
+ * All children overlap the same area. They are rendered back to front
+ * (first child = bottom, last child = top).
+ */
+import type { DrawingContext } from "../drawing/context.js";
+import { Control } from "./control.js";
+import type { Constraint, Rect, Size } from "./types.js";
+export interface StackOptions {
+    children?: Control[];
+}
+export declare class Stack extends Control {
+    constructor(options?: StackOptions);
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/layout/stack.js

@@ -0,0 +1,64 @@
+/**
+ * Stack — z-stacking container.
+ *
+ * All children overlap the same area. They are rendered back to front
+ * (first child = bottom, last child = top).
+ */
+import { Control, clampSize } from "./control.js";
+export class Stack extends Control {
+    constructor(options = {}) {
+        super();
+        if (options.children) {
+            for (const child of options.children) {
+                this.addChild(child);
+            }
+        }
+    }
+    // ── Layout ────────────────────────────────────────────────────────
+    measure(constraint) {
+        const visible = this.children.filter((c) => c.visible);
+        let maxWidth = 0;
+        let maxHeight = 0;
+        for (const child of visible) {
+            const childSize = child.measure(constraint);
+            maxWidth = Math.max(maxWidth, childSize.width);
+            maxHeight = Math.max(maxHeight, childSize.height);
+        }
+        const size = clampSize({ width: maxWidth, height: maxHeight }, constraint);
+        this.desiredSize = size;
+        return size;
+    }
+    arrange(rect) {
+        this.bounds = rect;
+        for (const child of this.children) {
+            if (!child.visible)
+                continue;
+            // Every child gets the full rect (positioned at origin within this stack)
+            child.arrange({
+                x: 0,
+                y: 0,
+                width: rect.width,
+                height: rect.height,
+            });
+        }
+    }
+    // ── Render ────────────────────────────────────────────────────────
+    render(ctx) {
+        // Render back to front: first child is at the bottom, last is on top
+        for (const child of this.children) {
+            if (!child.visible)
+                continue;
+            ctx.pushClip({
+                x: child.bounds.x,
+                y: child.bounds.y,
+                width: child.bounds.width,
+                height: child.bounds.height,
+            });
+            ctx.pushTranslate(child.bounds.x, child.bounds.y);
+            child.render(ctx);
+            child.dirty = false;
+            ctx.popTranslate();
+            ctx.popClip();
+        }
+    }
+}

package/dist/layout/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Core layout geometry types.
+ */
+/** A 2D size. */
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/** A 2D point. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A rectangle defined by origin and size. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Layout constraints with minimum and maximum bounds. */
+export interface Constraint {
+    readonly minWidth: number;
+    readonly minHeight: number;
+    readonly maxWidth: number;
+    readonly maxHeight: number;
+}

package/dist/layout/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core layout geometry types.
+ */
+export {};

package/dist/pixel/background.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pixel background: just a color.
+ */
+import { type Color } from "./color.js";
+/** Background of a single pixel cell. */
+export interface PixelBackground {
+    readonly color: Color;
+}
+/** Create a PixelBackground. */
+export declare function background(color?: Color): PixelBackground;
+/**
+ * Blend an upper background over a lower background using alpha compositing.
+ */
+export declare function blendBackground(above: PixelBackground, below: PixelBackground): PixelBackground;
+/** An empty (transparent) background. */
+export declare const EMPTY_BACKGROUND: PixelBackground;

package/dist/pixel/background.js

@@ -0,0 +1,16 @@
+/**
+ * Pixel background: just a color.
+ */
+import { colorBlend, TRANSPARENT } from "./color.js";
+/** Create a PixelBackground. */
+export function background(color = TRANSPARENT) {
+    return { color };
+}
+/**
+ * Blend an upper background over a lower background using alpha compositing.
+ */
+export function blendBackground(above, below) {
+    return { color: colorBlend(below.color, above.color) };
+}
+/** An empty (transparent) background. */
+export const EMPTY_BACKGROUND = { color: TRANSPARENT };

package/dist/pixel/box-pattern.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Box-drawing pattern system ported from Consolonia's BoxPattern.cs.
+ *
+ * A box pattern is a 4-bit bitmask encoding which sides of a cell have
+ * line segments. The bits correspond to:
+ *   bit 0 (0x1) = UP
+ *   bit 1 (0x2) = RIGHT
+ *   bit 2 (0x4) = DOWN
+ *   bit 3 (0x8) = LEFT
+ *
+ * This maps cleanly to Unicode box-drawing characters for single-line style.
+ */
+/** Direction bit flags. */
+export declare const UP = 1;
+export declare const RIGHT = 2;
+export declare const DOWN = 4;
+export declare const LEFT = 8;
+/** A box pattern is a 4-bit bitmask (0-15). */
+export type BoxPattern = number;
+/** No lines in any direction. */
+export declare const BOX_NONE: BoxPattern;
+/**
+ * Lookup table from 4-bit bitmask to Unicode box-drawing character (single-line style).
+ *
+ * Index 0 (no bits) maps to a space since there is no line to draw.
+ */
+export declare const BOX_CHARS: readonly string[];
+/**
+ * Get the box-drawing character for a given pattern.
+ */
+export declare function boxChar(pattern: BoxPattern): string;
+/**
+ * Merge two box patterns by ORing their bitmasks together.
+ * This produces smart corners where lines meet — e.g., merging
+ * a horizontal line (RIGHT|LEFT) with a vertical line (UP|DOWN)
+ * yields a cross (┼).
+ */
+export declare function mergeBoxPatterns(a: BoxPattern, b: BoxPattern): BoxPattern;

package/dist/pixel/box-pattern.js

@@ -0,0 +1,57 @@
+/**
+ * Box-drawing pattern system ported from Consolonia's BoxPattern.cs.
+ *
+ * A box pattern is a 4-bit bitmask encoding which sides of a cell have
+ * line segments. The bits correspond to:
+ *   bit 0 (0x1) = UP
+ *   bit 1 (0x2) = RIGHT
+ *   bit 2 (0x4) = DOWN
+ *   bit 3 (0x8) = LEFT
+ *
+ * This maps cleanly to Unicode box-drawing characters for single-line style.
+ */
+/** Direction bit flags. */
+export const UP = 0x1;
+export const RIGHT = 0x2;
+export const DOWN = 0x4;
+export const LEFT = 0x8;
+/** No lines in any direction. */
+export const BOX_NONE = 0;
+/**
+ * Lookup table from 4-bit bitmask to Unicode box-drawing character (single-line style).
+ *
+ * Index 0 (no bits) maps to a space since there is no line to draw.
+ */
+export const BOX_CHARS = [
+    " ", // 0b0000 = none
+    "\u2502", // 0b0001 = UP             │
+    "\u2500", // 0b0010 = RIGHT          ─
+    "\u2514", // 0b0011 = UP+RIGHT       └
+    "\u2502", // 0b0100 = DOWN           │
+    "\u2502", // 0b0101 = UP+DOWN        │
+    "\u250C", // 0b0110 = DOWN+RIGHT     ┌
+    "\u251C", // 0b0111 = UP+DOWN+RIGHT  ├
+    "\u2500", // 0b1000 = LEFT           ─
+    "\u2518", // 0b1001 = UP+LEFT        ┘
+    "\u2500", // 0b1010 = RIGHT+LEFT     ─
+    "\u2534", // 0b1011 = UP+RIGHT+LEFT  ┴
+    "\u2510", // 0b1100 = DOWN+LEFT      ┐
+    "\u2524", // 0b1101 = UP+DOWN+LEFT   ┤
+    "\u252C", // 0b1110 = DOWN+RIGHT+LEFT┬
+    "\u253C", // 0b1111 = all            ┼
+];
+/**
+ * Get the box-drawing character for a given pattern.
+ */
+export function boxChar(pattern) {
+    return BOX_CHARS[pattern & 0xf];
+}
+/**
+ * Merge two box patterns by ORing their bitmasks together.
+ * This produces smart corners where lines meet — e.g., merging
+ * a horizontal line (RIGHT|LEFT) with a vertical line (UP|DOWN)
+ * yields a cross (┼).
+ */
+export function mergeBoxPatterns(a, b) {
+    return (a | b) & 0xf;
+}

package/dist/pixel/buffer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PixelBuffer: a 2D grid of Pixel cells representing a terminal surface.
+ */
+import type { Rect } from "../layout/types.js";
+import type { Pixel } from "./pixel.js";
+/**
+ * A 2D pixel buffer backed by a flat array.
+ * Cells are stored row-major: index = y * width + x.
+ */
+export declare class PixelBuffer {
+    readonly width: number;
+    readonly height: number;
+    private readonly cells;
+    constructor(width: number, height: number);
+    /** Check whether (x, y) is within bounds. */
+    private inBounds;
+    /** Get the pixel at (x, y). Returns PIXEL_SPACE for out-of-bounds. */
+    get(x: number, y: number): Pixel;
+    /** Set the pixel at (x, y). Silently ignores out-of-bounds writes. */
+    set(x: number, y: number, pixel: Pixel): void;
+    /** Fill a rectangular region with a pixel value, clipped to buffer bounds. */
+    fill(rect: Rect, pixel: Pixel): void;
+    /** Reset all cells to PIXEL_SPACE. */
+    clear(): void;
+}

package/dist/pixel/buffer.js

@@ -0,0 +1,51 @@
+/**
+ * PixelBuffer: a 2D grid of Pixel cells representing a terminal surface.
+ */
+import { PIXEL_SPACE } from "./pixel.js";
+/**
+ * A 2D pixel buffer backed by a flat array.
+ * Cells are stored row-major: index = y * width + x.
+ */
+export class PixelBuffer {
+    width;
+    height;
+    cells;
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+        this.cells = new Array(width * height);
+        this.cells.fill(PIXEL_SPACE);
+    }
+    /** Check whether (x, y) is within bounds. */
+    inBounds(x, y) {
+        return x >= 0 && x < this.width && y >= 0 && y < this.height;
+    }
+    /** Get the pixel at (x, y). Returns PIXEL_SPACE for out-of-bounds. */
+    get(x, y) {
+        if (!this.inBounds(x, y))
+            return PIXEL_SPACE;
+        return this.cells[y * this.width + x];
+    }
+    /** Set the pixel at (x, y). Silently ignores out-of-bounds writes. */
+    set(x, y, pixel) {
+        if (!this.inBounds(x, y))
+            return;
+        this.cells[y * this.width + x] = pixel;
+    }
+    /** Fill a rectangular region with a pixel value, clipped to buffer bounds. */
+    fill(rect, pixel) {
+        const x0 = Math.max(0, rect.x);
+        const y0 = Math.max(0, rect.y);
+        const x1 = Math.min(this.width, rect.x + rect.width);
+        const y1 = Math.min(this.height, rect.y + rect.height);
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                this.cells[y * this.width + x] = pixel;
+            }
+        }
+    }
+    /** Reset all cells to PIXEL_SPACE. */
+    clear() {
+        this.cells.fill(PIXEL_SPACE);
+    }
+}

package/dist/pixel/color.d.ts

@@ -0,0 +1,48 @@
+/**
+ * RGBA color representation and compositing functions.
+ * All channel values are integers in the range 0-255.
+ */
+/** RGBA color with each channel in 0-255. */
+export interface Color {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/** Create a color from RGBA values (all 0-255). */
+export declare function color(r: number, g: number, b: number, a?: number): Color;
+/**
+ * Alpha-composite `source` over `target` using standard "over" operator.
+ * Both colors use premultiplied-style blending with 0-255 alpha.
+ */
+export declare function colorBlend(target: Color, source: Color): Color;
+/**
+ * Brighten a color by a factor (0-1). 1.0 produces white.
+ */
+export declare function colorBrighten(c: Color, factor: number): Color;
+/**
+ * Shade (darken) a color by a factor (0-1). 1.0 produces black.
+ */
+export declare function colorShade(c: Color, factor: number): Color;
+export declare const TRANSPARENT: Color;
+export declare const BLACK: Color;
+export declare const RED: Color;
+export declare const GREEN: Color;
+export declare const YELLOW: Color;
+export declare const BLUE: Color;
+export declare const MAGENTA: Color;
+export declare const CYAN: Color;
+export declare const WHITE: Color;
+export declare const BLACK_BRIGHT: Color;
+export declare const RED_BRIGHT: Color;
+export declare const GREEN_BRIGHT: Color;
+export declare const YELLOW_BRIGHT: Color;
+export declare const BLUE_BRIGHT: Color;
+export declare const MAGENTA_BRIGHT: Color;
+export declare const CYAN_BRIGHT: Color;
+export declare const WHITE_BRIGHT: Color;
+/** chalk.gray / chalk.grey = blackBright (ANSI 90) */
+export declare const GRAY: Color;
+export declare const GREY: Color;
+export declare const DARK_GRAY: Color;
+export declare const LIGHT_GRAY: Color;

package/dist/pixel/color.js

@@ -0,0 +1,92 @@
+/**
+ * RGBA color representation and compositing functions.
+ * All channel values are integers in the range 0-255.
+ */
+/** Create a color from RGBA values (all 0-255). */
+export function color(r, g, b, a = 255) {
+    return { r, g, b, a };
+}
+/** Clamp a value to 0-255 integer range. */
+function clamp(v) {
+    return Math.max(0, Math.min(255, Math.round(v)));
+}
+/**
+ * Alpha-composite `source` over `target` using standard "over" operator.
+ * Both colors use premultiplied-style blending with 0-255 alpha.
+ */
+export function colorBlend(target, source) {
+    if (source.a === 0)
+        return target;
+    if (source.a === 255)
+        return source;
+    if (target.a === 0)
+        return source;
+    const sa = source.a / 255;
+    const ta = target.a / 255;
+    // Standard Porter-Duff "over" operator
+    const outA = sa + ta * (1 - sa);
+    if (outA === 0)
+        return TRANSPARENT;
+    const outR = (source.r * sa + target.r * ta * (1 - sa)) / outA;
+    const outG = (source.g * sa + target.g * ta * (1 - sa)) / outA;
+    const outB = (source.b * sa + target.b * ta * (1 - sa)) / outA;
+    return {
+        r: clamp(outR),
+        g: clamp(outG),
+        b: clamp(outB),
+        a: clamp(outA * 255),
+    };
+}
+/**
+ * Brighten a color by a factor (0-1). 1.0 produces white.
+ */
+export function colorBrighten(c, factor) {
+    const f = Math.max(0, Math.min(1, factor));
+    return {
+        r: clamp(c.r + (255 - c.r) * f),
+        g: clamp(c.g + (255 - c.g) * f),
+        b: clamp(c.b + (255 - c.b) * f),
+        a: c.a,
+    };
+}
+/**
+ * Shade (darken) a color by a factor (0-1). 1.0 produces black.
+ */
+export function colorShade(c, factor) {
+    const f = 1 - Math.max(0, Math.min(1, factor));
+    return {
+        r: clamp(c.r * f),
+        g: clamp(c.g * f),
+        b: clamp(c.b * f),
+        a: c.a,
+    };
+}
+// ── Common color constants ──────────────────────────────────────────
+//
+// Standard colors match chalk's ANSI-16 palette names.
+// RGB values are chosen for truecolor terminals (sent as 24-bit RGB).
+export const TRANSPARENT = { r: 0, g: 0, b: 0, a: 0 };
+// ── Standard ANSI colors (chalk: black, red, green, … white) ────────
+export const BLACK = { r: 0, g: 0, b: 0, a: 255 };
+export const RED = { r: 255, g: 0, b: 0, a: 255 };
+export const GREEN = { r: 0, g: 255, b: 0, a: 255 };
+export const YELLOW = { r: 255, g: 255, b: 0, a: 255 };
+export const BLUE = { r: 0, g: 0, b: 255, a: 255 };
+export const MAGENTA = { r: 255, g: 0, b: 255, a: 255 };
+export const CYAN = { r: 0, g: 255, b: 255, a: 255 };
+export const WHITE = { r: 255, g: 255, b: 255, a: 255 };
+// ── Bright ANSI colors (chalk: blackBright … whiteBright) ───────────
+export const BLACK_BRIGHT = { r: 128, g: 128, b: 128, a: 255 };
+export const RED_BRIGHT = { r: 255, g: 85, b: 85, a: 255 };
+export const GREEN_BRIGHT = { r: 85, g: 255, b: 85, a: 255 };
+export const YELLOW_BRIGHT = { r: 255, g: 255, b: 85, a: 255 };
+export const BLUE_BRIGHT = { r: 85, g: 85, b: 255, a: 255 };
+export const MAGENTA_BRIGHT = { r: 255, g: 85, b: 255, a: 255 };
+export const CYAN_BRIGHT = { r: 85, g: 255, b: 255, a: 255 };
+export const WHITE_BRIGHT = { r: 255, g: 255, b: 255, a: 255 };
+// ── Convenience aliases ─────────────────────────────────────────────
+/** chalk.gray / chalk.grey = blackBright (ANSI 90) */
+export const GRAY = BLACK_BRIGHT;
+export const GREY = BLACK_BRIGHT;
+export const DARK_GRAY = { r: 64, g: 64, b: 64, a: 255 };
+export const LIGHT_GRAY = { r: 192, g: 192, b: 192, a: 255 };

package/dist/pixel/foreground.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pixel foreground: the character, its color, and text style attributes.
+ */
+import { type Color } from "./color.js";
+import { type Symbol } from "./symbol.js";
+/** Foreground of a single pixel cell. */
+export interface PixelForeground {
+    readonly symbol: Symbol;
+    readonly color: Color;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    readonly strikethrough: boolean;
+}
+/** Create a PixelForeground with defaults for style flags. */
+export declare function foreground(symbol?: Symbol, color?: Color, opts?: {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}): PixelForeground;
+/**
+ * Blend an upper foreground over a lower foreground.
+ *
+ * If the upper symbol is a space (and not a box pattern), the lower shows through
+ * but colors are still blended. If both have box patterns, they merge via OR.
+ * Otherwise the upper symbol wins.
+ */
+export declare function blendForeground(above: PixelForeground, below: PixelForeground): PixelForeground;
+/** An empty foreground (space, transparent, no styles). */
+export declare const EMPTY_FOREGROUND: PixelForeground;

package/dist/pixel/foreground.js

@@ -0,0 +1,64 @@
+/**
+ * Pixel foreground: the character, its color, and text style attributes.
+ */
+import { boxChar, mergeBoxPatterns } from "./box-pattern.js";
+import { colorBlend, TRANSPARENT } from "./color.js";
+import { EMPTY_SYMBOL } from "./symbol.js";
+/** Create a PixelForeground with defaults for style flags. */
+export function foreground(symbol = EMPTY_SYMBOL, color = TRANSPARENT, opts = {}) {
+    return {
+        symbol,
+        color,
+        bold: opts.bold ?? false,
+        italic: opts.italic ?? false,
+        underline: opts.underline ?? false,
+        strikethrough: opts.strikethrough ?? false,
+    };
+}
+/**
+ * Blend an upper foreground over a lower foreground.
+ *
+ * If the upper symbol is a space (and not a box pattern), the lower shows through
+ * but colors are still blended. If both have box patterns, they merge via OR.
+ * Otherwise the upper symbol wins.
+ */
+export function blendForeground(above, below) {
+    const aboveSym = above.symbol;
+    const belowSym = below.symbol;
+    // Both have box patterns: merge them
+    if (aboveSym.pattern !== 0 && belowSym.pattern !== 0) {
+        const merged = mergeBoxPatterns(aboveSym.pattern, belowSym.pattern);
+        const mergedChar = boxChar(merged);
+        return {
+            symbol: { text: mergedChar, width: 1, pattern: merged },
+            color: above.color.a > 0 ? colorBlend(below.color, above.color) : below.color,
+            bold: above.bold || below.bold,
+            italic: above.italic || below.italic,
+            underline: above.underline || below.underline,
+            strikethrough: above.strikethrough || below.strikethrough,
+        };
+    }
+    // Above is a transparent space — lower shows through
+    if (aboveSym.text === " " && aboveSym.pattern === 0 && above.color.a === 0) {
+        return below;
+    }
+    // Above has content — it wins, colors are blended
+    const blendedColor = colorBlend(below.color, above.color);
+    return {
+        symbol: aboveSym.text === " " && aboveSym.pattern === 0 ? belowSym : aboveSym,
+        color: blendedColor,
+        bold: aboveSym.text !== " " ? above.bold : below.bold,
+        italic: aboveSym.text !== " " ? above.italic : below.italic,
+        underline: aboveSym.text !== " " ? above.underline : below.underline,
+        strikethrough: aboveSym.text !== " " ? above.strikethrough : below.strikethrough,
+    };
+}
+/** An empty foreground (space, transparent, no styles). */
+export const EMPTY_FOREGROUND = {
+    symbol: EMPTY_SYMBOL,
+    color: TRANSPARENT,
+    bold: false,
+    italic: false,
+    underline: false,
+    strikethrough: false,
+};

package/dist/pixel/pixel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A Pixel represents a single terminal cell: foreground (character + style) over background.
+ */
+import { type PixelBackground } from "./background.js";
+import { type PixelForeground } from "./foreground.js";
+/** A single terminal cell combining foreground and background. */
+export interface Pixel {
+    readonly foreground: PixelForeground;
+    readonly background: PixelBackground;
+}
+/** Create a Pixel. */
+export declare function pixel(fg?: PixelForeground, bg?: PixelBackground): Pixel;
+/**
+ * Composite `above` pixel onto `below` pixel.
+ * Both foreground and background are blended independently.
+ */
+export declare function blendPixel(above: Pixel, below: Pixel): Pixel;
+/** A fully transparent, empty pixel. */
+export declare const PIXEL_EMPTY: Pixel;
+/** A space character with transparent colors — the default cell state. */
+export declare const PIXEL_SPACE: Pixel;

package/dist/pixel/pixel.js

@@ -0,0 +1,38 @@
+/**
+ * A Pixel represents a single terminal cell: foreground (character + style) over background.
+ */
+import { blendBackground, EMPTY_BACKGROUND, } from "./background.js";
+import { TRANSPARENT } from "./color.js";
+import { blendForeground, EMPTY_FOREGROUND, } from "./foreground.js";
+import { EMPTY_SYMBOL } from "./symbol.js";
+/** Create a Pixel. */
+export function pixel(fg = EMPTY_FOREGROUND, bg = EMPTY_BACKGROUND) {
+    return { foreground: fg, background: bg };
+}
+/**
+ * Composite `above` pixel onto `below` pixel.
+ * Both foreground and background are blended independently.
+ */
+export function blendPixel(above, below) {
+    return {
+        foreground: blendForeground(above.foreground, below.foreground),
+        background: blendBackground(above.background, below.background),
+    };
+}
+/** A fully transparent, empty pixel. */
+export const PIXEL_EMPTY = {
+    foreground: EMPTY_FOREGROUND,
+    background: EMPTY_BACKGROUND,
+};
+/** A space character with transparent colors — the default cell state. */
+export const PIXEL_SPACE = {
+    foreground: {
+        symbol: EMPTY_SYMBOL,
+        color: TRANSPARENT,
+        bold: false,
+        italic: false,
+        underline: false,
+        strikethrough: false,
+    },
+    background: EMPTY_BACKGROUND,
+};

package/dist/pixel/symbol.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents a single cell's character content.
+ */
+import type { BoxPattern } from "./box-pattern.js";
+/** A single terminal cell's character data. */
+export interface Symbol {
+    /** The character or grapheme cluster to display. */
+    readonly text: string;
+    /** Display width: 1 for normal chars, 2 for wide (CJK) chars. */
+    readonly width: 1 | 2;
+    /** Box-drawing pattern bitmask. 0 for normal characters. */
+    readonly pattern: BoxPattern;
+}
+/**
+ * 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 declare function isZeroWidth(codePoint: number): boolean;
+/**
+ * Determine the display width of a single character.
+ * Returns 2 for wide characters (CJK, fullwidth forms, emoji), 1 otherwise.
+ */
+export declare function charWidth(codePoint: number): 1 | 2;
+/**
+ * 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 declare function stringDisplayWidth(text: string): number;
+/**
+ * Create a Symbol from a text string.
+ * Width is auto-detected from the first code point.
+ */
+export declare function sym(text: string, pattern?: BoxPattern): Symbol;
+/** An empty symbol (space character). */
+export declare const EMPTY_SYMBOL: Symbol;