@cel-tui/core 0.1.0

package/src/cell-buffer.ts

@@ -0,0 +1,196 @@
+import type { Color } from "@cel-tui/types";
+
+/**
+ * A single terminal cell with character content and styling.
+ *
+ * Each cell represents one column in the terminal grid.
+ * Wide characters (CJK, emoji) occupy two cells — the first cell
+ * holds the character, the second is a continuation marker.
+ */
+export interface Cell {
+  /** The grapheme cluster displayed in this cell. */
+  char: string;
+  /** Foreground color, or null for terminal default. */
+  fgColor: Color | null;
+  /** Background color, or null for terminal default. */
+  bgColor: Color | null;
+  /** Bold weight. */
+  bold: boolean;
+  /** Italic style. */
+  italic: boolean;
+  /** Underline decoration. */
+  underline: boolean;
+}
+
+/**
+ * The default empty cell — a space with no styling.
+ * Used for cleared/uninitialized cells and transparency detection.
+ */
+export const EMPTY_CELL: Readonly<Cell> = {
+  char: " ",
+  fgColor: null,
+  bgColor: null,
+  bold: false,
+  italic: false,
+  underline: false,
+};
+
+function cellsEqual(a: Cell, b: Cell): boolean {
+  return (
+    a.char === b.char &&
+    a.fgColor === b.fgColor &&
+    a.bgColor === b.bgColor &&
+    a.bold === b.bold &&
+    a.italic === b.italic &&
+    a.underline === b.underline
+  );
+}
+
+/**
+ * A 2D grid of styled terminal cells.
+ *
+ * The cell buffer is the core rendering target. The layout engine
+ * computes rects, painting writes styled cells into those rects,
+ * and the diff algorithm compares the current buffer against the
+ * previous one to produce minimal terminal updates.
+ *
+ * Empty cells (matching {@link EMPTY_CELL}) are considered transparent
+ * for layer compositing — higher layers overwrite lower layers only
+ * where they have non-empty content.
+ */
+export class CellBuffer {
+  private cells: Cell[];
+  private _width: number;
+  private _height: number;
+
+  /**
+   * Create a new cell buffer filled with empty cells.
+   *
+   * @param width - Buffer width in columns.
+   * @param height - Buffer height in rows.
+   */
+  constructor(width: number, height: number) {
+    this._width = width;
+    this._height = height;
+    this.cells = new Array(width * height);
+    this.clearCells(0, this.cells.length);
+  }
+
+  /** Buffer width in columns. */
+  get width(): number {
+    return this._width;
+  }
+
+  /** Buffer height in rows. */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * Get the cell at `(x, y)`.
+   * Returns {@link EMPTY_CELL} for out-of-bounds coordinates.
+   */
+  get(x: number, y: number): Cell {
+    if (x < 0 || x >= this._width || y < 0 || y >= this._height) {
+      return EMPTY_CELL;
+    }
+    return this.cells[y * this._width + x]!;
+  }
+
+  /**
+   * Set the cell at `(x, y)`.
+   * Out-of-bounds writes are silently ignored.
+   */
+  set(x: number, y: number, cell: Cell): void {
+    if (x < 0 || x >= this._width || y < 0 || y >= this._height) return;
+    this.cells[y * this._width + x] = cell;
+  }
+
+  /**
+   * Check if the cell at `(x, y)` is empty (transparent).
+   * A cell is empty if it matches {@link EMPTY_CELL} exactly.
+   */
+  isEmpty(x: number, y: number): boolean {
+    return cellsEqual(this.get(x, y), EMPTY_CELL);
+  }
+
+  /** Reset all cells to {@link EMPTY_CELL}. */
+  clear(): void {
+    this.clearCells(0, this.cells.length);
+  }
+
+  /**
+   * Fill a rectangular region with a cell value.
+   * Coordinates are clipped to buffer bounds.
+   *
+   * @param x - Left column (inclusive).
+   * @param y - Top row (inclusive).
+   * @param w - Width in columns.
+   * @param h - Height in rows.
+   * @param cell - Cell value to fill with.
+   */
+  fill(x: number, y: number, w: number, h: number, cell: Cell): void {
+    const x0 = Math.max(0, x);
+    const y0 = Math.max(0, y);
+    const x1 = Math.min(this._width, x + w);
+    const y1 = Math.min(this._height, y + h);
+    for (let row = y0; row < y1; row++) {
+      for (let col = x0; col < x1; col++) {
+        this.cells[row * this._width + col] = cell;
+      }
+    }
+  }
+
+  /**
+   * Resize the buffer. Existing content within the new bounds is preserved.
+   * New cells are initialized to {@link EMPTY_CELL}.
+   *
+   * @param width - New width in columns.
+   * @param height - New height in rows.
+   */
+  resize(width: number, height: number): void {
+    const newCells = new Array<Cell>(width * height);
+    // Fill with empty
+    for (let i = 0; i < newCells.length; i++) {
+      newCells[i] = { ...EMPTY_CELL };
+    }
+    // Copy existing content
+    const copyW = Math.min(this._width, width);
+    const copyH = Math.min(this._height, height);
+    for (let y = 0; y < copyH; y++) {
+      for (let x = 0; x < copyW; x++) {
+        newCells[y * width + x] = this.cells[y * this._width + x]!;
+      }
+    }
+    this.cells = newCells;
+    this._width = width;
+    this._height = height;
+  }
+
+  /**
+   * Compare this buffer against another and return positions that differ.
+   * Used for differential rendering — only changed cells need terminal updates.
+   *
+   * @param other - The buffer to compare against.
+   * @returns Array of `{ x, y }` positions where cells differ.
+   */
+  diff(other: CellBuffer): { x: number; y: number }[] {
+    const changes: { x: number; y: number }[] = [];
+    const w = Math.min(this._width, other._width);
+    const h = Math.min(this._height, other._height);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        if (!cellsEqual(this.get(x, y), other.get(x, y))) {
+          changes.push({ x, y });
+        }
+      }
+    }
+    return changes;
+  }
+
+  private clearCells(start: number, end: number): void {
+    for (let i = start; i < end; i++) {
+      this.cells[i] = { ...EMPTY_CELL };
+    }
+  }
+}

package/src/emitter.ts

@@ -0,0 +1,192 @@
+import type { Color } from "@cel-tui/types";
+import type { Cell } from "./cell-buffer.js";
+import { CellBuffer, EMPTY_CELL } from "./cell-buffer.js";
+
+// --- Color mapping ---
+
+const FG_CODES: Record<Color, number> = {
+  black: 30,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  magenta: 35,
+  cyan: 36,
+  white: 37,
+  brightBlack: 90,
+  brightRed: 91,
+  brightGreen: 92,
+  brightYellow: 93,
+  brightBlue: 94,
+  brightMagenta: 95,
+  brightCyan: 96,
+  brightWhite: 97,
+};
+
+const BG_CODES: Record<Color, number> = {
+  black: 40,
+  red: 41,
+  green: 42,
+  yellow: 43,
+  blue: 44,
+  magenta: 45,
+  cyan: 46,
+  white: 47,
+  brightBlack: 100,
+  brightRed: 101,
+  brightGreen: 102,
+  brightYellow: 103,
+  brightBlue: 104,
+  brightMagenta: 105,
+  brightCyan: 106,
+  brightWhite: 107,
+};
+
+// --- SGR generation ---
+
+function sgrForCell(cell: Cell): string {
+  const codes: number[] = [];
+  if (cell.bold) codes.push(1);
+  if (cell.italic) codes.push(3);
+  if (cell.underline) codes.push(4);
+  if (cell.fgColor) codes.push(FG_CODES[cell.fgColor]);
+  if (cell.bgColor) codes.push(BG_CODES[cell.bgColor]);
+  if (codes.length === 0) return "";
+  return `\x1b[${codes.join(";")}m`;
+}
+
+function styleEquals(a: Cell, b: Cell): boolean {
+  return (
+    a.fgColor === b.fgColor &&
+    a.bgColor === b.bgColor &&
+    a.bold === b.bold &&
+    a.italic === b.italic &&
+    a.underline === b.underline
+  );
+}
+
+function hasStyle(cell: Cell): boolean {
+  return (
+    cell.bold ||
+    cell.italic ||
+    cell.underline ||
+    cell.fgColor !== null ||
+    cell.bgColor !== null
+  );
+}
+
+// --- Synchronized output markers ---
+
+const SYNC_START = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+const CURSOR_HOME = "\x1b[H";
+const RESET = "\x1b[0m";
+
+/**
+ * Emit a full cell buffer as an ANSI string for terminal output.
+ *
+ * Generates cursor positioning, SGR styling codes, and character content
+ * for every cell. Output is wrapped in synchronized output markers
+ * (CSI 2026) for flicker-free rendering.
+ *
+ * Optimizes by batching consecutive cells with the same style and
+ * only emitting SGR codes when the style changes.
+ *
+ * @param buf - The cell buffer to render.
+ * @returns A complete ANSI string ready to write to the terminal.
+ */
+export function emitBuffer(buf: CellBuffer): string {
+  let out = SYNC_START + CURSOR_HOME;
+
+  let lastStyle: Cell | null = null;
+
+  for (let y = 0; y < buf.height; y++) {
+    if (y > 0) out += "\r\n";
+
+    for (let x = 0; x < buf.width; x++) {
+      const cell = buf.get(x, y);
+
+      // Emit style change if needed
+      if (lastStyle === null || !styleEquals(cell, lastStyle)) {
+        // Reset before applying new style
+        if (lastStyle !== null && hasStyle(lastStyle)) {
+          out += RESET;
+        }
+        const sgr = sgrForCell(cell);
+        if (sgr) out += sgr;
+        lastStyle = cell;
+      }
+
+      out += cell.char;
+    }
+  }
+
+  // Final reset if any style was active
+  if (lastStyle !== null && hasStyle(lastStyle)) {
+    out += RESET;
+  }
+
+  out += SYNC_END;
+  return out;
+}
+
+/**
+ * Emit only the cells that differ between two buffers.
+ *
+ * Uses cursor positioning (CSI row;col H) to jump to changed cells,
+ * batching consecutive changes on the same row into a single run.
+ * Output is wrapped in synchronized output markers for flicker-free updates.
+ *
+ * @param prev - The previous buffer.
+ * @param next - The new buffer.
+ * @returns An ANSI string with only the changed cells.
+ */
+export function emitDiff(prev: CellBuffer, next: CellBuffer): string {
+  let out = SYNC_START;
+
+  const changes = prev.diff(next);
+  if (changes.length === 0) {
+    return out + SYNC_END;
+  }
+
+  let lastStyle: Cell | null = null;
+  let lastX = -1;
+  let lastY = -1;
+
+  for (const { x, y } of changes) {
+    const cell = next.get(x, y);
+
+    // Position cursor if not consecutive
+    if (y !== lastY || x !== lastX + 1) {
+      // Reset style before repositioning
+      if (lastStyle !== null && hasStyle(lastStyle)) {
+        out += RESET;
+        lastStyle = null;
+      }
+      // CSI row;col H (1-indexed)
+      out += `\x1b[${y + 1};${x + 1}H`;
+    }
+
+    // Emit style change if needed
+    if (lastStyle === null || !styleEquals(cell, lastStyle)) {
+      if (lastStyle !== null && hasStyle(lastStyle)) {
+        out += RESET;
+      }
+      const sgr = sgrForCell(cell);
+      if (sgr) out += sgr;
+      lastStyle = cell;
+    }
+
+    out += cell.char;
+    lastX = x;
+    lastY = y;
+  }
+
+  // Final reset
+  if (lastStyle !== null && hasStyle(lastStyle)) {
+    out += RESET;
+  }
+
+  out += SYNC_END;
+  return out;
+}

package/src/hit-test.ts

@@ -0,0 +1,146 @@
+import type { ContainerProps } from "@cel-tui/types";
+import type { LayoutNode, Rect } from "./layout.js";
+
+/**
+ * Test if a point is inside a rect.
+ */
+function pointInRect(x: number, y: number, rect: Rect): boolean {
+  return (
+    x >= rect.x &&
+    x < rect.x + rect.width &&
+    y >= rect.y &&
+    y < rect.y + rect.height
+  );
+}
+
+/**
+ * Find the path from root to the deepest node at `(x, y)`.
+ *
+ * Returns an array of {@link LayoutNode}s from root (index 0) to the
+ * deepest hit node (last index). Returns empty array if the point is
+ * outside the root.
+ *
+ * @param root - Root of the layout tree.
+ * @param x - Column position.
+ * @param y - Row position.
+ * @returns Path from root to deepest node at the position.
+ */
+export function hitTest(root: LayoutNode, x: number, y: number): LayoutNode[] {
+  if (!pointInRect(x, y, root.rect)) return [];
+
+  const path: LayoutNode[] = [root];
+
+  // Recurse into children (depth-first, last child wins for overlaps)
+  let current = root;
+  let found = true;
+
+  while (found) {
+    found = false;
+    for (let i = current.children.length - 1; i >= 0; i--) {
+      const child = current.children[i]!;
+      if (pointInRect(x, y, child.rect)) {
+        path.push(child);
+        current = child;
+        found = true;
+        break;
+      }
+    }
+  }
+
+  return path;
+}
+
+// --- Handler lookups ---
+
+function getProps(ln: LayoutNode): ContainerProps | null {
+  const node = ln.node;
+  if (node.type === "text") return null;
+  return node.props;
+}
+
+/**
+ * Find the nearest ancestor with an `onClick` handler (innermost wins).
+ * Walks the path from deepest to root.
+ *
+ * @param path - Hit test path (root to deepest).
+ * @returns The handler and its layout node, or null.
+ */
+export function findClickHandler(
+  path: LayoutNode[],
+): { layoutNode: LayoutNode; handler: () => void } | null {
+  for (let i = path.length - 1; i >= 0; i--) {
+    const props = getProps(path[i]!);
+    if (props?.onClick) {
+      return { layoutNode: path[i]!, handler: props.onClick };
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the nearest scrollable ancestor (innermost wins).
+ * Matches containers with `overflow: "scroll"` or TextInput nodes.
+ *
+ * @param path - Hit test path (root to deepest).
+ * @returns The scrollable layout node, or null.
+ */
+export function findScrollTarget(path: LayoutNode[]): LayoutNode | null {
+  for (let i = path.length - 1; i >= 0; i--) {
+    const node = path[i]!.node;
+    if (node.type === "textinput") return path[i]!;
+    const props = getProps(path[i]!);
+    if (props?.overflow === "scroll") return path[i]!;
+  }
+  return null;
+}
+
+/**
+ * Find the nearest ancestor with an `onKeyPress` handler.
+ * Walks from deepest to root (bubbling).
+ *
+ * @param path - Path from root to current node.
+ * @returns The handler and its layout node, or null.
+ */
+export function findKeyPressHandler(
+  path: LayoutNode[],
+): { layoutNode: LayoutNode; handler: (key: string) => void } | null {
+  for (let i = path.length - 1; i >= 0; i--) {
+    const props = getProps(path[i]!);
+    if (props?.onKeyPress) {
+      return { layoutNode: path[i]!, handler: props.onKeyPress };
+    }
+  }
+  return null;
+}
+
+/**
+ * Collect all focusable nodes in document order (depth-first traversal).
+ *
+ * A node is focusable if:
+ * - It's a TextInput (always focusable), OR
+ * - It's a container with `onClick` and `focusable` is not `false`
+ *
+ * @param root - Root of the layout tree.
+ * @returns Focusable nodes in document order.
+ */
+export function collectFocusable(root: LayoutNode): LayoutNode[] {
+  const result: LayoutNode[] = [];
+  collectFocusableRecursive(root, result);
+  return result;
+}
+
+function collectFocusableRecursive(ln: LayoutNode, result: LayoutNode[]): void {
+  const node = ln.node;
+
+  if (node.type === "textinput") {
+    result.push(ln);
+  } else if (node.type === "vstack" || node.type === "hstack") {
+    if (node.props.onClick && node.props.focusable !== false) {
+      result.push(ln);
+    }
+  }
+
+  for (const child of ln.children) {
+    collectFocusableRecursive(child, result);
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @module @cel-tui/core
+ *
+ * Core framework package. Provides the four primitives ({@link VStack},
+ * {@link HStack}, {@link Text}, {@link TextInput}) and the framework
+ * entrypoint ({@link cel}).
+ *
+ * All types are re-exported from `@cel-tui/types`.
+ *
+ * @example
+ * ```ts
+ * import { cel, VStack, HStack, Text, TextInput, ProcessTerminal } from "@cel-tui/core";
+ *
+ * let name = "";
+ *
+ * cel.init(new ProcessTerminal());
+ * cel.viewport(() =>
+ *   VStack({ height: "100%" }, [
+ *     Text("What is your name?", { bold: true }),
+ *     TextInput({
+ *       value: name,
+ *       onChange: (v) => { name = v; cel.render(); },
+ *     }),
+ *   ])
+ * );
+ * ```
+ */
+
+export type {
+  Color,
+  StyleProps,
+  SizeValue,
+  ContainerProps,
+  TextProps,
+  TextInputProps,
+  TextNode,
+  TextInputNode,
+  ContainerNode,
+  Node,
+} from "@cel-tui/types";
+
+export { VStack, HStack } from "./primitives/stacks.js";
+export { Text } from "./primitives/text.js";
+export { TextInput } from "./primitives/text-input.js";
+export { cel } from "./cel.js";
+export { CellBuffer, EMPTY_CELL, type Cell } from "./cell-buffer.js";
+export { emitBuffer } from "./emitter.js";
+export { visibleWidth, extractAnsiCode } from "./width.js";
+export { type Terminal, ProcessTerminal, MockTerminal } from "./terminal.js";