@zakmandhro/bunti 0.1.5 → 0.2.0

package/dist/layout.d.ts

@@ -2,39 +2,104 @@
  * Bunti Functional Layout & Drawing
  * Strictly functional primitives for buffer manipulation and layout generation.
  */
+import type { Rect } from './geometry';
 import type { Cell, RGB, ScreenState } from './state';
+import type { ThemeColor } from './theme';
+/**
+ * Writes one cell into the back buffer (bounds-checked). Wide glyphs mark
+ * their tail cells as skip so the differ keeps columns aligned.
+ */
 export declare function setCell(state: ScreenState, x: number, y: number, cell: Partial<Cell>): void;
+/**
+ * Repaints existing back-buffer cells inside `area` at reduced luminance.
+ * Each cell's current fg/bg is resolved to exact RGB (numeric ANSI-256 codes
+ * via the xterm table) and scaled toward black by `amount` (0 = unchanged,
+ * 1 = fully black). Cells with an undefined bg keep their transparent
+ * background (fg-only dim); undefined fg is left alone (there is no color to
+ * scale). Wide-glyph tail cells (skip) are dimmed too so they stay in sync
+ * with their head cell. No-op on the mono tier — there is no color to dim.
+ */
+export declare function dimRect(state: ScreenState, area: Rect, amount: number): void;
 import type { Gradient } from './colors';
+/** Fill style for rect(). */
 export interface RectOptions {
+    /** Fill glyph; omitted = pure background fill that keeps existing chars. */
     char?: string;
-    fg?: string | number | RGB;
-    bg?: string | number | RGB | Gradient;
+    /** Foreground color for the fill glyphs. */
+    fg?: string | number | RGB | ThemeColor;
+    /** Background color (Gradients resolve per-cell across the rect). */
+    bg?: string | number | RGB | Gradient | ThemeColor;
 }
+/**
+ * Fills a w×h cell rectangle at absolute coordinates — bars, panels,
+ * charts, backgrounds. Pure-background fills (no `char`) preserve the
+ * characters already painted underneath.
+ * @example rect(state, 0, 0, state.width, 3, { bg: 'midnight' });
+ */
 export declare function rect(state: ScreenState, x: number, y: number, w: number, h: number, style: RectOptions): void;
+/**
+ * Paints a multi-line, ANSI-styled string into the back buffer at absolute
+ * cell coordinates, parsing SGR codes into per-cell attributes. Grapheme-
+ * aware: emoji and wide glyphs occupy their real column width.
+ * @example blit(state, 2, 1, fg('gold', 'FPS 60'));
+ */
 export declare function blit(state: ScreenState, startX: number, startY: number, content: string, style?: Partial<Cell>): void;
+/**
+ * Border glyph sets. Wireframe: 'default' | 'rounded' | 'double' |
+ * 'dashed' | 'dotted'. Block: 'frame' | 'thick-frame'. ASCII: 'classic'.
+ * 'none' keeps the box purely structural.
+ */
 export type BorderStyle = 'default' | 'rounded' | 'double' | 'dashed' | 'dotted' | 'frame' | 'thick-frame' | 'classic' | 'none';
+/** Per-side border colors; missing sides inherit top (or left/right). */
 export interface SideColors {
     top?: any;
     bottom?: any;
     left?: any;
     right?: any;
 }
+/**
+ * A dimension: absolute cells (20), percent of parent ('50%'), or fill
+ * fraction ('1fr'). undefined/'auto' sizes to content.
+ */
 export type SizeUnit = number | string;
+/**
+ * Box styling shared by box()/table()/components.
+ */
 export interface StyleOptions {
+    /** Outer width: cells, '50%', '1fr', or 'auto' (content-sized). */
     width?: SizeUnit;
+    /** Lower bound on the outer width in cells. */
     minWidth?: number;
+    /** Upper bound on the outer width in cells. */
     maxWidth?: number;
+    /** Outer height: rows, '50%', '1fr', or 'auto' (content-sized). */
     height?: SizeUnit;
+    /** Lower bound on the outer height in rows. */
     minHeight?: number;
+    /** Upper bound on the outer height in rows. */
     maxHeight?: number;
+    /**
+     * [vertical, horizontal] padding INSIDE the border, in cells —
+     * [1, 2] = 1 blank row above/below, 2 blank columns left/right.
+     * Note the order: rows first (a 2:1 h:v ratio usually looks balanced
+     * because terminal cells are taller than wide).
+     */
     padding?: [number, number];
+    /** Border glyph set (default 'none'). */
     border?: BorderStyle;
-    borderColor?: string | number | RGB | ((s: string) => string) | SideColors;
-    bgColor?: string | number | RGB | Gradient;
+    /** Border color: color value, styler function, or per-side SideColors. */
+    borderColor?: string | number | RGB | ThemeColor | ((s: string) => string) | SideColors;
+    /** Background fill (Gradient backgrounds apply in direct/rect mode). */
+    bgColor?: string | number | RGB | Gradient | ThemeColor;
+    /** Horizontal content alignment (default 'left'). */
     align?: 'left' | 'center' | 'right';
+    /** Vertical content alignment (default 'top'). */
     valign?: 'top' | 'middle' | 'bottom';
+    /** Word-wraps content to the inner width instead of truncating. */
     wrap?: boolean;
+    /** Title rendered into the top border. */
     title?: string;
+    /** Styler applied to the rendered title. */
     titleStyle?: (s: string) => string;
 }
 /**
@@ -42,47 +107,87 @@ export interface StyleOptions {
  */
 export declare function resolveSize(unit: SizeUnit | undefined, parentDim: number, contentDim: number): number;
 /**
- * Generates a styled box string with perfect alignment and optional wrapping.
+ * Generates a styled box string with perfect alignment and optional
+ * wrapping. This is the pure string-building form; ctx.box() adds
+ * placement and painting on top of it.
+ * @example box('hello', { width: 20, border: 'rounded', padding: [0, 1] });
  */
 export declare function box(content: string, options?: StyleOptions, parentW?: number, parentH?: number): string;
+/** Joins rendered blocks side-by-side, padding each to its own width. */
 export declare function joinHorizontal(...blocks: string[]): string;
+/** Stacks rendered blocks vertically (skips empty strings). */
 export declare function joinVertical(...blocks: string[]): string;
+/** Returns a box() partially applied with default StyleOptions. */
 export declare function createStyle(defaults: StyleOptions): (content: string, overrides?: StyleOptions) => string;
+/** Uppercased ` TEXT ` chip, wrapped by the given styler. */
 export declare function badge(text: string, colorFn?: (s: string) => string): string;
+/** Options for table() / ctx.table(). */
 export interface TableOptions {
+    /** Overall table width: cells, '50%', or '100%' (default 80 cells). */
     width?: SizeUnit;
+    /** Per-column width/alignment overrides, by column index. */
     columns?: {
         width?: SizeUnit;
         align?: 'left' | 'center' | 'right';
     }[];
+    /** Outer border glyph set (default 'default'). */
     border?: BorderStyle;
+    /** [vertical, horizontal] cell padding (default [0, 1]). */
     padding?: [number, number];
 }
 /**
  * Renders a data table with perfectly aligned columns and shared borders.
  */
 export declare function table(rows: string[][], options?: TableOptions, parentW?: number): string;
+/**
+ * Computes the scroll window that keeps `selectedIndex` visible in
+ * `maxVisible` rows (used by list windowing).
+ */
 export declare function getWindow<T>(items: T[], selectedIndex: number, maxVisible: number): {
     visible: T[];
     start: number;
     hasMoreAbove: boolean;
     hasMoreBelow: boolean;
 };
+/** Options for list() / ctx.list(). */
 export interface ListOptions {
+    /** Prefix rendered before every item (e.g. '• '). */
     bullet?: string;
+    /** Leading spaces before each row. */
     indent?: number;
+    /** Row rendered as selected (ctx.list manages this from state). */
     focusedIndex?: number;
+    /** Styler for the selected row's text (default theme.focus). */
     focusStyle?: (s: string) => string;
-    selectedBg?: string | number | RGB;
+    /** Background wash behind the selected row (default theme.selection). */
+    selectedBg?: string | number | RGB | ThemeColor;
+    /** Mouse-hovered row (styled with hoverBg; selection wins over hover). */
+    hoveredIndex?: number;
+    /** Background wash for the hovered row. */
+    hoverBg?: string | number | RGB | ThemeColor;
+    /** Row width for background washes: cells, '50%', or '100%'. */
     width?: SizeUnit;
+    /** Windows the list to N rows, scrolled to keep the selection visible. */
     maxVisible?: number;
+    /** Set false to disable ctx.list's built-in keyboard/mouse handling. */
     interactive?: boolean;
 }
+/**
+ * Renders items as list rows with selection/hover washes and optional
+ * maxVisible windowing. Pure string form; ctx.list() adds the keyboard
+ * and mouse behavior on top.
+ */
 export declare function list(items: string[], options?: ListOptions, parentW?: number): string;
+/**
+ * Crops a multi-line string to a width×height window starting at
+ * `scrollY` — the primitive for scrollable content.
+ */
 export declare function viewport(content: string, width: number, height: number, scrollY?: number): string;
+/** Fills the whole screen background with a solid color. */
 export declare function wallpaper(state: any, options: {
     bg: any;
 }): void;
+/** Fills the whole screen background with a multi-stop gradient. */
 export declare function gradient(state: any, colors: any[], options?: {
     direction?: 'vertical' | 'horizontal';
 }): void;

package/dist/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAKtD,wBAAgB,OAAO,CACrB,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,QAwCpB;AAED,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,CAAC;IAC3B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC;CACvC;AAED,wBAAgB,IAAI,CAClB,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,WAAW,QA2CnB;AAED,wBAAgB,IAAI,CAClB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,OAAO,CAAC,IAAI,CAAM,QA8E1B;AAID,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,UAAU,CAAC;IAC3E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACrC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CACpC;AAsBD;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,GAAG,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,EAC1B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CA8LR;AAED,wBAAgB,cAAc,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAsB1D;AAED,wBAAgB,YAAY,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAExD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,IACxC,SAAS,MAAM,EAAE,YAAW,YAAiB,YAGtD;AAED,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAiB,GACxC,MAAM,CAER;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;KAAE,EAAE,CAAC;IACtE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EAAE,EAAE,EAChB,OAAO,GAAE,YAAiB,EAC1B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAmDR;AAED,wBAAgB,SAAS,CAAC,CAAC,EACzB,KAAK,EAAE,CAAC,EAAE,EACV,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM;;;;;EAgBnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,CAAC;IACnC,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,IAAI,CAClB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,WAAgB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAgDR;AAED,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAU,GAClB,MAAM,CASR;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,QAGzD;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,GAAG,EACV,MAAM,EAAE,GAAG,EAAE,EACb,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,UAAU,GAAG,YAAY,CAAA;CAAO,QAWxD"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}

package/dist/layout.js

@@ -2,10 +2,15 @@
  * Bunti Functional Layout & Drawing
  * Strictly functional primitives for buffer manipulation and layout generation.
  */
-import { resolveColor } from './colors';
+import { fg as fgColor, isThemeColor, resolveColor, resolveColorToRGB, } from './colors';
+import { colorTier } from './detect';
 import { replaceEmojis } from './icons';
 import { charWidth, truncate, visibleWidth, wrapText } from './utils';
 // --- Functional Primitives (Buffer Manipulation) ---
+/**
+ * Writes one cell into the back buffer (bounds-checked). Wide glyphs mark
+ * their tail cells as skip so the differ keeps columns aligned.
+ */
 export function setCell(state, x, y, cell) {
     if (x >= 0 && x < state.width && y >= 0 && y < state.height) {
         const target = state.backBuffer[y * state.width + x];
@@ -20,6 +25,10 @@ export function setCell(state, x, y, cell) {
             target.fg = undefined;
             target.fgCode = undefined;
             target.bold = false;
+            target.italic = false;
+            target.underline = false;
+            target.dim = false;
+            target.strike = false;
         }
         if (cell.fg !== undefined) {
             target.fg = cell.fg;
@@ -31,6 +40,14 @@ export function setCell(state, x, y, cell) {
         }
         if (cell.bold !== undefined)
             target.bold = cell.bold;
+        if (cell.italic !== undefined)
+            target.italic = cell.italic;
+        if (cell.underline !== undefined)
+            target.underline = cell.underline;
+        if (cell.dim !== undefined)
+            target.dim = cell.dim;
+        if (cell.strike !== undefined)
+            target.strike = cell.strike;
         target.skip = cell.skip ?? false;
         for (let dx = 1; dx < displayWidth; dx++) {
             const skipX = x + dx;
@@ -43,10 +60,67 @@ export function setCell(state, x, y, cell) {
             skip.fgCode = target.fgCode;
             skip.bgCode = target.bgCode;
             skip.bold = target.bold;
+            skip.italic = target.italic;
+            skip.underline = target.underline;
+            skip.dim = target.dim;
+            skip.strike = target.strike;
             skip.skip = true;
         }
     }
 }
+/**
+ * Repaints existing back-buffer cells inside `area` at reduced luminance.
+ * Each cell's current fg/bg is resolved to exact RGB (numeric ANSI-256 codes
+ * via the xterm table) and scaled toward black by `amount` (0 = unchanged,
+ * 1 = fully black). Cells with an undefined bg keep their transparent
+ * background (fg-only dim); undefined fg is left alone (there is no color to
+ * scale). Wide-glyph tail cells (skip) are dimmed too so they stay in sync
+ * with their head cell. No-op on the mono tier — there is no color to dim.
+ */
+export function dimRect(state, area, amount) {
+    if (colorTier() === 'mono')
+        return;
+    const t = Math.max(0, Math.min(1, amount));
+    if (t === 0)
+        return;
+    const keep = 1 - t;
+    const x0 = Math.max(0, area.x);
+    const y0 = Math.max(0, area.y);
+    const x1 = Math.min(state.width, area.x + area.width);
+    const y1 = Math.min(state.height, area.y + area.height);
+    for (let y = y0; y < y1; y++) {
+        const rowOffset = y * state.width;
+        for (let x = x0; x < x1; x++) {
+            const cell = state.backBuffer[rowOffset + x];
+            if (cell.fg !== undefined) {
+                const rgb = resolveColorToRGB(cell.fg);
+                const dimmed = {
+                    r: Math.round(rgb.r * keep),
+                    g: Math.round(rgb.g * keep),
+                    b: Math.round(rgb.b * keep),
+                };
+                cell.fg = dimmed;
+                cell.fgCode = resolveColor(dimmed);
+            }
+            if (cell.bg !== undefined) {
+                const rgb = resolveColorToRGB(cell.bg);
+                const dimmed = {
+                    r: Math.round(rgb.r * keep),
+                    g: Math.round(rgb.g * keep),
+                    b: Math.round(rgb.b * keep),
+                };
+                cell.bg = dimmed;
+                cell.bgCode = resolveColor(dimmed);
+            }
+        }
+    }
+}
+/**
+ * Fills a w×h cell rectangle at absolute coordinates — bars, panels,
+ * charts, backgrounds. Pure-background fills (no `char`) preserve the
+ * characters already painted underneath.
+ * @example rect(state, 0, 0, state.width, 3, { bg: 'midnight' });
+ */
 export function rect(state, x, y, w, h, style) {
     const isGradient = style.bg && typeof style.bg === 'object' && 'colors' in style.bg;
     for (let dy = 0; dy < h; dy++) {
@@ -88,6 +162,12 @@ export function rect(state, x, y, w, h, style) {
         }
     }
 }
+/**
+ * Paints a multi-line, ANSI-styled string into the back buffer at absolute
+ * cell coordinates, parsing SGR codes into per-cell attributes. Grapheme-
+ * aware: emoji and wide glyphs occupy their real column width.
+ * @example blit(state, 2, 1, fg('gold', 'FPS 60'));
+ */
 export function blit(state, startX, startY, content, style = {}) {
     const lines = content.split('\n');
     for (let row = 0; row < lines.length; row++) {
@@ -95,6 +175,10 @@ export function blit(state, startX, startY, content, style = {}) {
         let x = startX;
         let currentFg, currentBg;
         let currentBold = false;
+        let currentItalic = false;
+        let currentUnderline = false;
+        let currentDim = false;
+        let currentStrike = false;
         const regex = /\x1B\[([0-9;]*)m|([^\x1B]+)/g;
         let match = null;
         while ((match = regex.exec(line)) !== null) {
@@ -106,11 +190,32 @@ export function blit(state, startX, startY, content, style = {}) {
                         currentFg = undefined;
                         currentBg = undefined;
                         currentBold = false;
+                        currentItalic = false;
+                        currentUnderline = false;
+                        currentDim = false;
+                        currentStrike = false;
                     }
                     else if (code === 1)
                         currentBold = true;
-                    else if (code === 22)
+                    else if (code === 2)
+                        currentDim = true;
+                    else if (code === 3)
+                        currentItalic = true;
+                    else if (code === 4)
+                        currentUnderline = true;
+                    else if (code === 9)
+                        currentStrike = true;
+                    else if (code === 22) {
+                        // SGR 22 resets intensity: clears BOTH bold and dim.
                         currentBold = false;
+                        currentDim = false;
+                    }
+                    else if (code === 23)
+                        currentItalic = false;
+                    else if (code === 24)
+                        currentUnderline = false;
+                    else if (code === 29)
+                        currentStrike = false;
                     else if (code >= 30 && code <= 37)
                         currentFg = (code - 30).toString();
                     else if (code >= 40 && code <= 47)
@@ -172,6 +277,14 @@ export function blit(state, startX, startY, content, style = {}) {
                         cell.bg = style.bg;
                     if (currentBold)
                         cell.bold = true;
+                    if (currentItalic)
+                        cell.italic = true;
+                    if (currentUnderline)
+                        cell.underline = true;
+                    if (currentDim)
+                        cell.dim = true;
+                    if (currentStrike)
+                        cell.strike = true;
                     setCell(state, x, startY + row, cell);
                     x += w;
                 }
@@ -218,7 +331,10 @@ export function resolveSize(unit, parentDim, contentDim) {
     return contentDim;
 }
 /**
- * Generates a styled box string with perfect alignment and optional wrapping.
+ * Generates a styled box string with perfect alignment and optional
+ * wrapping. This is the pure string-building form; ctx.box() adds
+ * placement and painting on top of it.
+ * @example box('hello', { width: 20, border: 'rounded', padding: [0, 1] });
  */
 export function box(content, options = {}, parentW, parentH) {
     // Ensure we operate on the swapped glyphs for all layout math
@@ -257,8 +373,13 @@ export function box(content, options = {}, parentW, parentH) {
         ? null
         : BORDERS[borderStyle] || BORDERS.default;
     // Color Resolution
-    const { fg } = require('./colors');
-    const resolveSide = (color) => typeof color === 'function' ? color : (s) => fg(color, s);
+    // ThemeColors are callable, so they must be detected BEFORE the
+    // function-style border-wrapper path (brand check via isThemeColor).
+    const resolveSide = (color) => isThemeColor(color)
+        ? (s) => fgColor(color.rgb, s)
+        : typeof color === 'function'
+            ? color
+            : (s) => fgColor(color, s);
     const wrapBg = (s) => {
         if (!options.bgColor)
             return s;
@@ -267,12 +388,12 @@ export function box(content, options = {}, parentW, parentH) {
             // In string-building mode, we must ignore gradients. They are handled in absolute rect mode.
             return s;
         }
-        const { resolveColor } = require('./colors');
         const code = resolveColor(options.bgColor);
-        const prefix = typeof options.bgColor === 'object' || String(code).startsWith('2;')
-            ? '48'
-            : '48;5';
-        const bgOn = `\x1b[${prefix};${code}m`;
+        if (code === undefined)
+            return s; // mono tier: no color output
+        const codeStr = String(code);
+        const prefix = codeStr.startsWith('2;') ? '48' : '48;5';
+        const bgOn = `\x1b[${prefix};${codeStr}m`;
         // Apply bg, and if the string contains resets, re-apply the bg right after the reset.
         // We add a final reset at the very end to clean up.
         return `${bgOn + s.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[0m`;
@@ -374,6 +495,7 @@ export function box(content, options = {}, parentW, parentH) {
     }
     return out.join('\n');
 }
+/** Joins rendered blocks side-by-side, padding each to its own width. */
 export function joinHorizontal(...blocks) {
     const parsed = blocks.map((b) => b.split('\n'));
     const maxH = Math.max(...parsed.map((p) => p.length));
@@ -397,14 +519,17 @@ export function joinHorizontal(...blocks) {
     }
     return out.join('\n');
 }
+/** Stacks rendered blocks vertically (skips empty strings). */
 export function joinVertical(...blocks) {
     return blocks.filter(Boolean).join('\n');
 }
+/** Returns a box() partially applied with default StyleOptions. */
 export function createStyle(defaults) {
     return (content, overrides = {}) => {
         return box(content, { ...defaults, ...overrides });
     };
 }
+/** Uppercased ` TEXT ` chip, wrapped by the given styler. */
 export function badge(text, colorFn = (s) => s) {
     return colorFn(` ${text.toUpperCase()} `);
 }
@@ -448,6 +573,10 @@ export function table(rows, options = {}, parentW) {
         align: 'left',
     });
 }
+/**
+ * Computes the scroll window that keeps `selectedIndex` visible in
+ * `maxVisible` rows (used by list windowing).
+ */
 export function getWindow(items, selectedIndex, maxVisible) {
     const start = Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), items.length - maxVisible));
     const visible = items.slice(start, start + maxVisible);
@@ -458,22 +587,27 @@ export function getWindow(items, selectedIndex, maxVisible) {
         hasMoreBelow: start + maxVisible < items.length,
     };
 }
+/**
+ * Renders items as list rows with selection/hover washes and optional
+ * maxVisible windowing. Pure string form; ctx.list() adds the keyboard
+ * and mouse behavior on top.
+ */
 export function list(items, options = {}, parentW) {
     const bullet = options.bullet || '';
     const indent = ' '.repeat(options.indent || 0);
     const resolvedW = resolveSize(options.width, parentW || 0, 0);
-    const { resolveColor } = require('./colors');
-    const wrapSelectedBg = (line) => {
-        if (!options.selectedBg)
-            return line;
-        const code = resolveColor(options.selectedBg);
+    const wrapLineBg = (line, bg) => {
+        const code = resolveColor(bg);
+        if (code === undefined)
+            return line; // mono tier: no color output
         const codeStr = String(code);
-        const prefix = typeof options.selectedBg === 'object' || codeStr.startsWith('2;')
-            ? '48'
-            : '48;5';
+        const prefix = codeStr.startsWith('2;') ? '48' : '48;5';
         const bgOn = `\x1b[${prefix};${codeStr}m`;
         return `${bgOn + line.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[0m`;
     };
+    const padToWidth = (line) => resolvedW > 0
+        ? line + ' '.repeat(Math.max(0, resolvedW - visibleWidth(line)))
+        : line;
     let targetItems = items, offset = 0, hasMoreAbove = false, hasMoreBelow = false;
     if (options.maxVisible && items.length > options.maxVisible) {
         const win = getWindow(items, options.focusedIndex || 0, options.maxVisible);
@@ -490,11 +624,11 @@ export function list(items, options = {}, parentW) {
             const styledLine = options.focusStyle ? options.focusStyle(line) : line;
             if (!options.selectedBg)
                 return styledLine;
-            const paddedLine = resolvedW > 0
-                ? styledLine +
-                    ' '.repeat(Math.max(0, resolvedW - visibleWidth(styledLine)))
-                : styledLine;
-            return wrapSelectedBg(paddedLine);
+            return wrapLineBg(padToWidth(styledLine), options.selectedBg);
+        }
+        // Hover wash (selection wins: checked above).
+        if (options.hoveredIndex === actualIdx && options.hoverBg) {
+            return wrapLineBg(padToWidth(line), options.hoverBg);
         }
         return line;
     })
@@ -506,6 +640,10 @@ export function list(items, options = {}, parentW) {
         out = `${out}\n${indent}  ↓ more…`;
     return out;
 }
+/**
+ * Crops a multi-line string to a width×height window starting at
+ * `scrollY` — the primitive for scrollable content.
+ */
 export function viewport(content, width, height, scrollY = 0) {
     const lines = content.split('\n');
     const visibleLines = lines.slice(scrollY, scrollY + height);
@@ -515,10 +653,12 @@ export function viewport(content, width, height, scrollY = 0) {
     })
         .join('\n');
 }
+/** Fills the whole screen background with a solid color. */
 export function wallpaper(state, options) {
     const { bg } = options;
     rect(state, 0, 0, state.width, state.height, { char: ' ', bg });
 }
+/** Fills the whole screen background with a multi-stop gradient. */
 export function gradient(state, colors, options = {}) {
     const { direction = 'vertical' } = options;
     rect(state, 0, 0, state.width, state.height, {