@zakmandhro/bunti 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zak Mandhro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# 🥟 Bunti (Bun Terminal Interface)
+
+**A high-performance, functional TUI engine built specifically for Bun.**
+
+Bunti (pronounced *Bun-ty*) is a zero-dependency, double-buffered layout engine for building terminal user interfaces. Unlike traditional TUI libraries, Bunti uses a **functional, state-driven architecture** and a **surgical diff-renderer** to deliver 60+ FPS layouts with minimal CPU and TTY overhead.
+
+## ✨ Features
+
+- 🏗️ **Contextual DSL**: Build complex UIs with a declarative, nested closure API.
+- 🏎️ **Double-Buffered Diffing**: Only dirty row spans are sent to the terminal. Zero flicker.
+- 📏 **Mathematically Absolute**: 100% precision in width, padding, and border alignment.
+- 📐 **Tactical Standard**: Opinionated border styles (`default`, `rounded`, `frame`, `thick-frame`).
+- 🌈 **24-bit TrueColor**: High-fidelity RGB gradients with native hex parsing and relative contrast.
+- 🖱️ **Interactive**: Built-in SGR mouse tracking and focus detection with automatic FPS throttling.
+
+## 📦 Installation
+
+Bunti is designed for Bun, but works in standard Node.js environments (v18+) as well.
+
+```bash
+bun add @zakmandhro/bunti
+```
+
+Or using npm/pnpm/yarn:
+
+```bash
+npm install @zakmandhro/bunti
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { bunti } from '@zakmandhro/bunti';
+
+bunti.render(({ wallpaper, box, color, icon, span }) => {
+  // 1. Set a dynamic gradient background
+  wallpaper(bunti.gradient({ colors: ['midnight', 'plasma'] }));
+
+  // 2. Define a centered high-contrast card
+  box({
+    size: "auto",
+    bgColor: "white",
+    color: "blank", // Automatic high-contrast black
+    border: 'frame' // Tactical block border
+  }, ({ text }) => {
+    text(` ${icon('rocket')} `);
+    text(color.bold("MISSION CONTROL\n\n"));
+    
+    span({ color: color.dim }, ({ text }) => {
+      text("STATUS: ");
+    });
+    text("NOMINAL");
+  });
+}, { fps: 60, mouse: true });
+```
+
+## 📐 Border Archetypes
+
+Bunti categorizes containers into three visual archetypes:
+
+| Category | Styles | Description |
+| :--- | :--- | :--- |
+| **Wireframe** | `default`, `rounded`, `double`, `dashed`, `dotted` | Clean, 1-width lines. Zero visual mass. |
+| **Frame** | `frame`, `thick-frame` | Block-based containers. High physical presence. |
+| **Ghost** | `none` | Purely structural containers for grouping and alignment. |
+
+## 🏁 Performance
+
+Bunti is built for speed. By leveraging `Bun.stdout.writer()` and surgical diffing, it can maintain **60-120 FPS** on complex layouts while keeping TTY bytes significantly lower than standard stream-based libraries.
+
+## 🛠️ Tooling
+
+### TSGO (High-Performance TypeScript)
+Bunti uses **[tsgo](https://github.com/d-ts/tsgo)** for its type-checking pipeline. 
+
+We chose `tsgo` over the standard `tsc` because:
+- **Speed**: It leverages a Go-based core to provide near-instant feedback during development.
+- **Agent-Friendly**: Its predictable and high-performance output makes it ideal for automated engineering workflows.
+- **Strict Integrity**: It ensures that Bunti's functional architecture remains 100% type-safe without the overhead of standard Node-based compilers.
+
+Run a full check with: `npm run type-check`
+
+## 📚 Documentation
+
+Dive deeper into Bunti's architecture and layout engine:
+
+- [The Box Model & Layout Math](./docs/layout.md)
+- [Bunti Components & Primitives](./docs/components.md)
+- [Bunti vs. The TUI Ecosystem](./docs/comparison.md)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. Since Bunti prioritizes mathematical precision and performance, please ensure you run the benchmark and type-check scripts before submitting.
+
+```bash
+bun run lint
+bun run typecheck
+bun run test
+bun run bench
+```
+
+## 📄 License
+
+MIT © Zak Mandhro

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zakmandhro/bunti",
+  "version": "0.1.0",
+  "description": "Bun Terminal Interface (bunti) - A minimalist, utility-first terminal layout engine built for Bun.",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./components": "./src/components/index.ts",
+    "./icons": "./src/icons.ts",
+    "./layout": "./src/layout.ts",
+    "./render": "./src/render.ts"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "bench": "bun scripts/bench.ts",
+    "typecheck": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "demo": "bun demo/runner.ts",
+    "example": "bun demo/runner.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "keywords": [
+    "tui",
+    "cli",
+    "terminal",
+    "layout",
+    "bun",
+    "bunti"
+  ],
+  "author": "Zak Mandhro <zakmandhro@gmail.com>",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "picocolors": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^25.6.2",
+    "typescript": "^5.4.0",
+    "vitepress": "^1.6.4"
+  }
+}

package/src/colors.ts

@@ -0,0 +1,255 @@
+/**
+ * Bunti Semantic & Palette Color System
+ */
+
+import type { RGB } from './state';
+
+export interface Gradient {
+  colors: RGB[];
+  direction: 'vertical' | 'horizontal';
+  steps: number;
+}
+
+export const PALETTE = {
+  // Greyscale
+  slate: '235',
+  ash: '240',
+  gray: '244',
+  silver: '247',
+  white: '255',
+  black: '0',
+
+  // Deep Blues & Space
+  midnight: '17',
+  ocean: '24',
+  sky: '33',
+  'bunti-blue': '38',
+  'deep-navy': '17',
+  nebula: '61',
+  plasma: '165',
+
+  // Semantic
+  success: '40',
+  warning: '214',
+  error: '196',
+  info: '39',
+
+  // Accents
+  gold: '220',
+  rose: '211',
+  mint: '121',
+} as const;
+
+const RGB_REGISTRY: Record<string, RGB> = {
+  black: { r: 0, g: 0, b: 0 },
+  red: { r: 200, g: 50, b: 50 },
+  green: { r: 50, g: 200, b: 50 },
+  yellow: { r: 200, g: 200, b: 50 },
+  blue: { r: 50, g: 50, b: 200 },
+  magenta: { r: 200, g: 50, b: 200 },
+  cyan: { r: 50, g: 200, b: 200 },
+  white: { r: 255, g: 255, b: 255 },
+  gray: { r: 128, g: 128, b: 128 },
+  // Greyscale
+  slate: { r: 40, g: 44, b: 52 },
+  ash: { r: 75, g: 82, b: 99 },
+  silver: { r: 188, g: 192, b: 204 },
+  // Deep Blues & Space
+  midnight: { r: 15, g: 15, b: 35 },
+  ocean: { r: 20, g: 40, b: 80 },
+  sky: { r: 0, g: 135, b: 255 },
+  'bunti-blue': { r: 59, g: 188, b: 225 },
+  'deep-navy': { r: 0, g: 51, b: 102 },
+  nebula: { r: 95, g: 95, b: 175 },
+  plasma: { r: 201, g: 0, b: 255 },
+  // Semantic
+  success: { r: 0, g: 215, b: 0 },
+  warning: { r: 255, g: 175, b: 0 },
+  error: { r: 215, g: 0, b: 0 },
+  info: { r: 0, g: 175, b: 255 },
+  // Accents
+  gold: { r: 255, g: 215, b: 0 },
+  rose: { r: 255, g: 175, b: 175 },
+  mint: { r: 175, g: 255, b: 175 },
+};
+
+// Map standard names to ANSI-256 for basic compat
+const NAME_TO_ANSI: Record<string, string> = {
+  red: '160',
+  green: '40',
+  yellow: '220',
+  blue: '33',
+  magenta: '165',
+  cyan: '39',
+  white: '255',
+  black: '0',
+  gray: '244',
+};
+
+export type PaletteColor = keyof typeof PALETTE;
+
+/**
+ * Parses a hex color string (#RRGGBB or #RGB) to an RGB object.
+ */
+export function hexToRGB(hex: string): RGB {
+  const h = hex.replace('#', '');
+  if (h.length === 3) {
+    return {
+      r: parseInt(h[0] + h[0], 16),
+      g: parseInt(h[1] + h[1], 16),
+      b: parseInt(h[2] + h[2], 16),
+    };
+  }
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16),
+  };
+}
+
+/**
+ * Resolves a palette name, color code, or RGB object to a string for ANSI.
+ */
+export function resolveColor(
+  color: PaletteColor | string | number | RGB,
+): string | number {
+  if (typeof color === 'object' && 'r' in color) {
+    return `2;${color.r};${color.g};${color.b}`;
+  }
+  if (typeof color === 'string') {
+    if (color.startsWith('#')) {
+      const rgb = hexToRGB(color);
+      return `2;${rgb.r};${rgb.g};${rgb.b}`;
+    }
+    return (PALETTE as any)[color] || NAME_TO_ANSI[color] || color;
+  }
+  return color;
+}
+
+/**
+ * Creates a multi-stop gradient (array of RGB objects) between multiple colors.
+ */
+export function createGradient(
+  arg1: (string | number | RGB)[] | string | number | RGB,
+  arg2?: string | number | RGB | number,
+  arg3?: number,
+): RGB[] {
+  let colors: (string | number | RGB)[] = [];
+  let steps = 5;
+
+  if (Array.isArray(arg1)) {
+    colors = arg1;
+    steps = typeof arg2 === 'number' ? arg2 : 5;
+  } else if (arg1 && arg2) {
+    colors = [arg1, arg2 as any];
+    steps = typeof arg3 === 'number' ? arg3 : 5;
+  }
+
+  if (colors.length === 0) return [];
+  if (colors.length === 1)
+    return Array(steps).fill(resolveColorToRGB(colors[0]));
+  if (steps <= 1) return [resolveColorToRGB(colors[0])];
+
+  const result: RGB[] = [];
+  const rgbColors = colors.map(resolveColorToRGB);
+
+  for (let i = 0; i < steps; i++) {
+    const globalT = i / (steps - 1);
+    const segmentCount = rgbColors.length - 1;
+    const segmentIdx = Math.min(
+      Math.floor(globalT * segmentCount),
+      segmentCount - 1,
+    );
+
+    const start = rgbColors[segmentIdx];
+    const end = rgbColors[segmentIdx + 1];
+    const t = globalT * segmentCount - segmentIdx;
+
+    result.push({
+      r: Math.round(start.r + (end.r - start.r) * t),
+      g: Math.round(start.g + (end.g - start.g) * t),
+      b: Math.round(start.b + (end.b - start.b) * t),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Helper to resolve any color type to an RGB object.
+ */
+function resolveColorToRGB(color: any): RGB {
+  if (typeof color === 'object' && 'r' in color) return color;
+  if (typeof color === 'string' && color.startsWith('#'))
+    return hexToRGB(color);
+
+  // 1. Check registry
+  if (typeof color === 'string' && RGB_REGISTRY[color])
+    return RGB_REGISTRY[color];
+
+  // 2. Check Palette
+  const paletteValue = (PALETTE as any)[color];
+  if (paletteValue) {
+    // If palette value is a name, look it up in registry
+    const registered = RGB_REGISTRY[color];
+    if (registered) return registered;
+  }
+
+  // Fallback
+  return { r: 128, g: 128, b: 128 };
+}
+
+/**
+ * Adjusts the brightness of a color.
+ */
+export function adjustBrightness(color: any, amount: number): RGB {
+  const rgb = resolveColorToRGB(color);
+  const factor = 1 + amount / 100;
+  return {
+    r: Math.max(0, Math.min(255, Math.round(rgb.r * factor))),
+    g: Math.max(0, Math.min(255, Math.round(rgb.g * factor))),
+    b: Math.max(0, Math.min(255, Math.round(rgb.b * factor))),
+  };
+}
+
+/**
+ * Returns a function that darkens a color and can be used as a style wrapper.
+ */
+export function darken(color: any, amount: number = 20) {
+  const adjusted = adjustBrightness(color, -amount);
+  return (text: string) => fg(adjusted, text);
+}
+
+/**
+ * Returns a function that lightens a color and can be used as a style wrapper.
+ */
+export function lighten(color: any, amount: number = 20) {
+  const adjusted = adjustBrightness(color, amount);
+  return (text: string) => fg(adjusted, text);
+}
+
+/**
+ * Returns an RGB object for TrueColor rendering.
+ */
+export function rgb(r: number, g: number, b: number) {
+  return { r, g, b };
+}
+
+/**
+ * Returns an ANSI escape sequence for a color.
+ */
+export function fg(color: any, text: string): string {
+  const code = resolveColor(color);
+  const codeStr = String(code);
+  const prefix =
+    typeof color === 'object' || codeStr.startsWith('2;') ? '38' : '38;5';
+  return `\x1b[${prefix};${codeStr}m${text}\x1b[0m`;
+}
+
+export function bg(color: any, text: string): string {
+  const code = resolveColor(color);
+  const codeStr = String(code);
+  const prefix =
+    typeof color === 'object' || codeStr.startsWith('2;') ? '48' : '48;5';
+  return `\x1b[${prefix};${codeStr}m${text}\x1b[0m`;
+}

package/src/components/Button.ts

@@ -0,0 +1,104 @@
+import type { BuntiContext } from '../dsl';
+import type { StyleOptions } from '../layout';
+
+export interface ButtonProps extends StyleOptions {
+  id: string;
+  label: string;
+  icon?: string;
+  variant?: 'primary' | 'secondary' | 'danger';
+  onClick?: () => void;
+}
+
+/**
+ * Tactical Button Component
+ * Fully reactive to keyboard focus and action events.
+ */
+export function Button(ctx: BuntiContext, props: ButtonProps) {
+  const {
+    box,
+    color,
+    focusable,
+    state,
+    offsetX,
+    offsetY,
+    mouseX,
+    mouseY,
+    isMouseDown,
+  } = ctx;
+
+  // 1. Register in the global focus loop (for TAB navigation)
+  const isSelected = focusable(props.id);
+
+  // 2. Resolve final dimensions to perform Mouse Hit-Testing
+  const finalLabel = props.icon ? `${props.icon} ${props.label}` : props.label;
+  const w = props.width || Math.max(12, finalLabel.length + 4);
+  const h = props.height || 3;
+
+  const resolvedW = typeof w === 'number' ? w : ctx.width;
+  const absX =
+    props.width === '100%'
+      ? offsetX
+      : offsetX + Math.max(0, Math.floor((ctx.width - resolvedW) / 2));
+  const absY = offsetY + ctx.cursorY;
+
+  const isHovered =
+    mouseX >= absX &&
+    mouseX < absX + resolvedW &&
+    mouseY >= absY &&
+    mouseY < absY + (h as number);
+
+  // 3. Resolve Theme & State
+  let bg: any = 254; // Near white
+  let fg: any = 'black';
+  let borderCol: any = { r: 217, g: 216, b: 213 };
+
+  if (props.variant === 'primary') {
+    bg = 'black';
+    fg = 'white';
+    borderCol = 'black';
+  } else if (props.variant === 'danger') {
+    bg = 'error';
+    borderCol = color.lighten('error', 20);
+    fg = 'white';
+  }
+
+  // Active Interactive State
+  const isActive = isSelected || isHovered;
+
+  if (isActive) {
+    if (props.variant === 'primary') {
+      bg = 'ash'; // Hover state for primary
+    } else {
+      borderCol = 'black';
+      if (isMouseDown && isHovered) {
+        bg = color.darken(bg, 5); // Pressed state
+      }
+    }
+  }
+
+  // 4. Handle Interaction
+  const wasClicked = isHovered && isMouseDown && state.mouseButton === 0;
+  const wasActivated =
+    isSelected && (state.lastKey === 'enter' || state.lastKey === ' ');
+
+  if (wasClicked || wasActivated) {
+    if (props.onClick) props.onClick();
+  }
+
+  // 5. Render the Primitive
+  return box(
+    {
+      width: w,
+      height: h,
+      border: props.variant === 'primary' ? 'none' : props.border || 'rounded',
+      borderColor: borderCol,
+      bgColor: bg,
+      align: props.align || 'center',
+      valign: props.valign || 'middle',
+      padding: props.padding || [0, 1],
+    },
+    ({ text }) => {
+      text(color.fg(fg, isActive ? color.bold(finalLabel) : finalLabel));
+    },
+  );
+}

package/src/components/Card.ts

@@ -0,0 +1,53 @@
+import type { BuntiContext, DSLBoxOptions } from '../dsl';
+
+export interface CardProps extends DSLBoxOptions {
+  title?: string;
+  theme?: 'default' | 'accent' | 'danger';
+}
+
+/**
+ * Tactical Card Component
+ * A structural container with an integrated header.
+ */
+export function Card(
+  ctx: BuntiContext,
+  props: CardProps,
+  callback: (sub: BuntiContext) => void,
+) {
+  const { box, color } = ctx;
+
+  const neutralGray = { r: 217, g: 216, b: 213 };
+  let borderColor: any = neutralGray;
+  let titleColor: any = neutralGray;
+
+  if (props.theme === 'accent') {
+    titleColor = 'black';
+    // Border remains neutral gray
+  } else if (props.theme === 'danger') {
+    borderColor = 'error';
+    titleColor = 'error';
+  }
+
+  return box(
+    {
+      x: props.x,
+      y: props.y,
+      anchor: props.anchor,
+      width: props.width || '100%',
+      height: props.height,
+      minHeight: props.minHeight,
+      border: props.border || 'frame',
+      borderColor: props.borderColor || borderColor,
+      padding: props.padding || [1, 2],
+      bgColor: props.bgColor,
+    },
+    (sub) => {
+      if (props.title) {
+        sub.text(
+          color.fg(titleColor, color.bold(`${props.title.toUpperCase()}\n\n`)),
+        );
+      }
+      callback(sub);
+    },
+  );
+}

package/src/components/Header.ts

@@ -0,0 +1,65 @@
+import type { BuntiContext } from '../dsl';
+import { box as engineBox } from '../layout';
+
+export interface HeaderProps {
+  title: string;
+  leftIcon?: string;
+  rightLabel?: string;
+  theme?: 'light' | 'dark';
+}
+
+/**
+ * Enterprise Tactical Header
+ * A full-width, high-signal branding bar.
+ */
+export function Header(ctx: BuntiContext, props: HeaderProps) {
+  const { box, color, width, joinHorizontal } = ctx;
+
+  // Resolve Theme Colors
+  const isLight = props.theme !== 'dark';
+  const bg = isLight ? 'white' : 'midnight';
+  const fg = isLight ? 236 : 'silver';
+
+  // Master Background Box
+  box(
+    {
+      anchor: 'top',
+      width: '100%',
+      height: 1,
+      bgColor: bg,
+      border: 'none',
+      padding: [0, 2],
+    },
+    ({ text }) => {
+      // 1. Left: Branding
+      const leftStr = props.leftIcon ? color.fg('plasma', props.leftIcon) : '';
+      const leftNode = engineBox(leftStr, {
+        width: 12,
+        align: 'left',
+        border: 'none',
+        padding: [0, 0],
+      });
+
+      // 2. Center: Title
+      const midStr = color.fg(fg, color.bold(props.title));
+      const midNode = engineBox(midStr, {
+        width: width - 28,
+        align: 'center',
+        border: 'none',
+        padding: [0, 0],
+      });
+
+      // 3. Right: Telemetry / Exit
+      const rightStr = props.rightLabel ? color.dim(props.rightLabel) : '';
+      const rightNode = engineBox(rightStr, {
+        width: 12,
+        align: 'right',
+        border: 'none',
+        padding: [0, 0],
+      });
+
+      // Join and push to render pipeline
+      text(joinHorizontal(leftNode, midNode, rightNode));
+    },
+  );
+}