@oh-my-pi/pi-tui 16.0.11 → 16.1.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.1.0] - 2026-06-19
+
+### Added
+
+- `Box` now accepts an optional `border` (box-drawing glyphs + colorizer) and exposes `setBorder()`, drawing a colored outline around its padded/background content. The border is automatically dropped at widths too narrow to frame so a bordered box never overflows its given width.
+
 ## [16.0.11] - 2026-06-19
 
 ### Breaking Changes

package/dist/types/components/box.d.ts

@@ -1,4 +1,16 @@
 import type { Component } from "../tui";
+/** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
+export interface BoxBorder {
+    chars: {
+        topLeft: string;
+        topRight: string;
+        bottomLeft: string;
+        bottomRight: string;
+        horizontal: string;
+        vertical: string;
+    };
+    color?: (text: string) => string;
+}
 /**
  * Box component - a container that applies padding and background to all children
  */
@@ -6,13 +18,14 @@ export declare class Box implements Component {
     #private;
     children: Component[];
     setIgnoreTight(ignore: boolean): this;
-    constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string);
+    constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string, border?: BoxBorder);
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;
     setPaddingX(paddingX: number): void;
     setPaddingY(paddingY: number): void;
     setBgFn(bgFn?: (text: string) => string): void;
+    setBorder(border?: BoxBorder): void;
     invalidate(): void;
     render(width: number): readonly string[];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.0.11",
+	"version": "16.1.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.0.11",
-		"@oh-my-pi/pi-utils": "16.0.11",
+		"@oh-my-pi/pi-natives": "16.1.1",
+		"@oh-my-pi/pi-utils": "16.1.1",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/components/box.ts

@@ -4,10 +4,24 @@ import { applyBackgroundToLine, getPaddingX, padding, visibleWidth } from "../ut
 type Cache = {
 	width: number;
 	bgSample: string | undefined;
+	borderSample: string | undefined;
 	childLines: (readonly string[])[];
 	result: string[];
 };
 
+/** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
+export interface BoxBorder {
+	chars: {
+		topLeft: string;
+		topRight: string;
+		bottomLeft: string;
+		bottomRight: string;
+		horizontal: string;
+		vertical: string;
+	};
+	color?: (text: string) => string;
+}
+
 /**
  * Box component - a container that applies padding and background to all children
  */
@@ -16,6 +30,7 @@ export class Box implements Component {
 	#paddingX: number;
 	#paddingY: number;
 	#bgFn?: (text: string) => string;
+	#border?: BoxBorder;
 
 	#ignoreTight = false;
 
@@ -28,10 +43,11 @@ export class Box implements Component {
 	// Cache for rendered output
 	#cached?: Cache;
 
-	constructor(paddingX = 1, paddingY = 1, bgFn?: (text: string) => string) {
+	constructor(paddingX = 1, paddingY = 1, bgFn?: (text: string) => string, border?: BoxBorder) {
 		this.#paddingX = paddingX;
 		this.#paddingY = paddingY;
 		this.#bgFn = bgFn;
+		this.#border = border;
 	}
 
 	addChild(component: Component): void {
@@ -72,6 +88,11 @@ export class Box implements Component {
 		// Don't invalidate here - we'll detect bgFn changes by sampling output
 	}
 
+	setBorder(border?: BoxBorder): void {
+		this.#border = border;
+		this.#invalidateCache();
+	}
+
 	#invalidateCache(): void {
 		this.#cached = undefined;
 	}
@@ -87,10 +108,18 @@ export class Box implements Component {
 		const children = this.children;
 		const count = children.length;
 		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
-		const contentWidth = Math.max(1, width - paddingX * 2);
-		// bgFn output can change without the function reference changing (theme
-		// mutation); sample it so a silent palette swap still misses the cache.
+		// A border eats one column on each side; skip it unless the interior can still
+		// hold the horizontal padding plus at least one content column, so a bordered
+		// Box never overflows the width it was given.
+		const border = this.#border && width - 2 >= paddingX * 2 + 1 ? this.#border : undefined;
+		const innerWidth = border ? width - 2 : width;
+		const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+		// bgFn / border output can change without the function reference changing
+		// (theme mutation); sample both so a silent palette swap still misses the cache.
 		const bgSample = this.#bgFn ? this.#bgFn("test") : undefined;
+		const borderSample = border
+			? `${border.color ? border.color("|") : "|"}${border.chars.topLeft}${border.chars.vertical}`
+			: undefined;
 
 		// Render every child every frame (renders may carry side effects); the
 		// memo only skips re-deriving the padded/background rows. Per the
@@ -101,6 +130,7 @@ export class Box implements Component {
 			cached !== undefined &&
 			cached.width === width &&
 			cached.bgSample === bgSample &&
+			cached.borderSample === borderSample &&
 			cached.childLines.length === count;
 		const childLines: (readonly string[])[] = new Array(count);
 		let contentRows = 0;
@@ -115,23 +145,39 @@ export class Box implements Component {
 		const result: string[] = [];
 		if (contentRows > 0) {
 			const leftPad = padding(paddingX);
+			const interior: string[] = [];
 			// Top padding
 			for (let i = 0; i < this.#paddingY; i++) {
-				result.push(this.#applyBg("", width));
+				interior.push(this.#applyBg("", innerWidth));
 			}
 			// Content
 			for (const lines of childLines) {
 				for (const line of lines) {
-					result.push(this.#applyBg(leftPad + line, width));
+					interior.push(this.#applyBg(leftPad + line, innerWidth));
 				}
 			}
 			// Bottom padding
 			for (let i = 0; i < this.#paddingY; i++) {
-				result.push(this.#applyBg("", width));
+				interior.push(this.#applyBg("", innerWidth));
+			}
+
+			if (border) {
+				const paint = border.color ?? (s => s);
+				const rule = border.chars.horizontal.repeat(Math.max(0, innerWidth));
+				const side = paint(border.chars.vertical);
+				result.push(paint(border.chars.topLeft + rule + border.chars.topRight));
+				for (const row of interior) {
+					result.push(side + row + side);
+				}
+				result.push(paint(border.chars.bottomLeft + rule + border.chars.bottomRight));
+			} else {
+				for (const row of interior) {
+					result.push(row);
+				}
 			}
 		}
 
-		this.#cached = { width, bgSample, childLines, result };
+		this.#cached = { width, bgSample, borderSample, childLines, result };
 		return result;
 	}
 

package/src/components/markdown.ts

@@ -222,6 +222,56 @@ markdownParser.setOptions({
 // never math. Inline extensions run before marked's escape tokenizer, so
 // `\(…\)` becomes math while a genuinely escaped `\$` is left to `escape` and
 // renders as a literal dollar.
+const CUSTOM_HR_START_REGEX = /(?:^|\n) {0,3}([-*_─━═=–—])[ \t]*(?:\1[ \t]*){2,}(?:\n+|$)/;
+const CUSTOM_HR_TOKENIZER_REGEX = /^ {0,3}([-*_─━═=–—])[ \t]*(?:\1[ \t]*){2,}(?:\n+|$)/;
+
+function getHrChar(char: string, hrChar: string): string {
+	const isAscii = hrChar === "-";
+	switch (char) {
+		case "=":
+			return "=";
+		case "═":
+			return isAscii ? "=" : "═";
+		case "━":
+			return isAscii ? "-" : "━";
+		case "─":
+			return isAscii ? "-" : "─";
+		case "–":
+			return isAscii ? "-" : "–";
+		case "—":
+			return isAscii ? "-" : "—";
+		default:
+			return hrChar;
+	}
+}
+
+const customHrExtension: TokenizerAndRendererExtension = {
+	name: "customHr",
+	level: "block",
+	start(src) {
+		const match = CUSTOM_HR_START_REGEX.exec(src);
+		if (!match) return undefined;
+		let idx = match.index;
+		if (src[idx] === "\n") {
+			idx += 1;
+		}
+		return idx;
+	},
+	tokenizer(src) {
+		const match = CUSTOM_HR_TOKENIZER_REGEX.exec(src);
+		if (match) {
+			return {
+				type: "hr",
+				raw: match[0],
+			};
+		}
+		return undefined;
+	},
+	renderer() {
+		return "";
+	},
+};
+
 const mathExtension: TokenizerAndRendererExtension = {
 	name: "math",
 	level: "inline",
@@ -332,7 +382,7 @@ const mathEnvBlockExtension: TokenizerAndRendererExtension = {
 		return (token as { text?: string }).text ?? "";
 	},
 };
-markdownParser.use({ extensions: [mathBlockExtension, mathEnvBlockExtension, mathExtension] });
+markdownParser.use({ extensions: [customHrExtension, mathBlockExtension, mathEnvBlockExtension, mathExtension] });
 
 // ---------------------------------------------------------------------------
 // Module-level LRU render cache
@@ -360,16 +410,14 @@ export function clearRenderCache(): void {
 }
 
 // Stable numeric IDs for structural theme/style objects (no ID field on type).
-// Symbol-keyed so the id travels with the object and is invisible to consumers.
-const kObjectId = Symbol("markdown.objectId");
-type WithObjectId = object & { [kObjectId]?: number };
+// WeakMap-keyed so the ID matches strict object identity and doesn't get copied by spread/cloning.
+const themeObjectIds = new WeakMap<object, number>();
 let nextObjectId = 0;
 function objectId(o: object): number {
-	const tagged = o as WithObjectId;
-	let id = tagged[kObjectId];
+	let id = themeObjectIds.get(o);
 	if (id === undefined) {
 		id = nextObjectId++;
-		tagged[kObjectId] = id;
+		themeObjectIds.set(o, id);
 	}
 	return id;
 }
@@ -1150,12 +1198,16 @@ export class Markdown implements Component {
 				break;
 			}
 
-			case "hr":
-				lines.push(this.#theme.hr(this.#theme.symbols.hrChar.repeat(Math.min(width, 80))));
+			case "hr": {
+				const raw = "raw" in token && typeof token.raw === "string" ? token.raw.trim() : "";
+				const char = raw[0] || "";
+				const fillChar = getHrChar(char, this.#theme.symbols.hrChar);
+				lines.push(this.#theme.hr(fillChar.repeat(Math.min(width, 80))));
 				if (nextTokenType && nextTokenType !== "space") {
 					lines.push(""); // Add spacing after horizontal rules (unless space token follows)
 				}
 				break;
+			}
 
 			case "html":
 				if ("raw" in token && typeof token.raw === "string") {