take4-console 0.15.0 → 0.25.0

package/src/Screen/controls/ListBox.mts

@@ -1,22 +1,35 @@
-import type { ListBoxProperties, WindowProperties, StyleId } from '../types.mjs';
+import type {
+	ListBoxProperties,
+	ListBoxRenderContext,
+	ListBoxRowSegment,
+	ListBoxRowSegments,
+	StyleId,
+	WindowProperties,
+} from '../types.mjs';
 import { Window } from '../Window.mjs';
 import { getRegistry } from '../RegistryHolder.mjs';
 
-/** A scrollable list of single-line items. The selected item is highlighted and may
- *  be moved with arrow keys, PgUp/PgDn, and Home/End. Emits onChange whenever the
- *  selection index changes via keyboard. Appearance follows the same built-in style
- *  naming scheme as the other focusable controls. */
-export class ListBox extends Window {
-	private items: string[];
+/** A scrollable list of items. Generic over the item type T (default: string).
+ *  The selected item is highlighted and may be moved with arrow keys, PgUp/PgDn,
+ *  and Home/End. Emits onChange whenever the selection index changes via keyboard.
+ *  Consumers may customise per-row rendering via `renderItem`, which returns either a
+ *  plain string (single left-aligned segment) or an array of styled ListBoxRowSegment
+ *  entries supporting `left`/`right`/`fill` alignment. Appearance follows the same
+ *  built-in style naming scheme as the other focusable controls. */
+export class ListBox<T = string> extends Window {
+	private items: T[];
 	private selectedIndex: number;
 	private scrollTop: number;
-	private onChange?: (index: number, item: string) => void;
+	private onChange?: (index: number, item: T) => void;
+	private renderItem?: (item: T, ctx: ListBoxRenderContext) => ListBoxRowSegments;
+	private rowHeight: number;
+	private keyFn?: (item: T) => string;
 	private selectedStyleId:  StyleId;
 	private focusedSelStyle:  StyleId;
 
 	/** Creates a ListBox from window properties and optional control-specific properties.
 	 *  Uses the global StyleRegistry set by the Screen constructor. */
-	public constructor(wp: WindowProperties, cp?: ListBoxProperties) {
+	public constructor(wp: WindowProperties, cp?: ListBoxProperties<T>) {
 		super({
 			...wp,
 			defaultBorder: { top: true, right: true, bottom: true, left: true, style: 'single' },
@@ -24,6 +37,9 @@ export class ListBox extends Window {
 
 		this.items         = cp?.items ?? [];
 		this.onChange      = cp?.onChange;
+		this.renderItem    = cp?.renderItem;
+		this.rowHeight     = Math.max(1, cp?.rowHeight ?? 1);
+		this.keyFn         = cp?.keyFn;
 		this.scrollTop     = 0;
 		this.selectedIndex = cp?.selectedIndex ?? (this.items.length > 0 ? 0 : -1);
 
@@ -34,14 +50,14 @@ export class ListBox extends Window {
 	}
 
 	/** Replaces the list items. Resets selection to 0 (or -1 if empty) and scrolls to top. */
-	public setItems(items: string[]): void {
+	public setItems(items: T[]): void {
 		this.items         = items;
 		this.selectedIndex = items.length > 0 ? 0 : -1;
 		this.scrollTop     = 0;
 	}
 
 	/** Returns the current list items. */
-	public getItems(): string[] {
+	public getItems(): T[] {
 		return this.items;
 	}
 
@@ -60,18 +76,33 @@ export class ListBox extends Window {
 		return this.selectedIndex;
 	}
 
-	/** Returns the currently selected item string, or undefined when nothing is selected. */
-	public getSelectedItem(): string | undefined {
+	/** Returns the currently selected item, or undefined when nothing is selected. */
+	public getSelectedItem(): T | undefined {
 		if (this.selectedIndex < 0 || this.selectedIndex >= this.items.length) return undefined;
 		return this.items[this.selectedIndex];
 	}
 
+	/** Replaces the per-row renderer after construction. Pass undefined to restore default behaviour. */
+	public setRenderItem(fn: ((item: T, ctx: ListBoxRenderContext) => ListBoxRowSegments) | undefined): void {
+		this.renderItem = fn;
+	}
+
+	/** Returns the configured row height in cells. */
+	public getRowHeight(): number {
+		return this.rowHeight;
+	}
+
+	/** Returns the stable key for an item, computed via the configured keyFn (falls back to String(item)). */
+	public getItemKey(item: T): string {
+		return this.keyFn ? this.keyFn(item) : String(item);
+	}
+
 	/** Processes a key press: arrow keys, Home/End, PgUp/PgDn move the selection. */
 	public handleKey(key: string): void {
 		if (this.disabled || this.items.length === 0) return;
 
 		const prev   = this.selectedIndex;
-		const pageSz = Math.max(1, this.getInnerSize().height);
+		const pageSz = Math.max(1, this.getVisibleRowCount());
 
 		switch (key) {
 			case '\x1b[A': // Up arrow
@@ -104,9 +135,14 @@ export class ListBox extends Window {
 		}
 	}
 
+	/** Returns the number of item slots that fit in the current inner area (>= 1). */
+	private getVisibleRowCount(): number {
+		return Math.max(1, Math.floor(this.getInnerSize().height / this.rowHeight));
+	}
+
 	/** Adjusts scrollTop so that the selected index remains within the visible window. */
 	private ensureVisible(): void {
-		const visibleRows = Math.max(1, this.getInnerSize().height);
+		const visibleRows = this.getVisibleRowCount();
 		if (this.selectedIndex < this.scrollTop) {
 			this.scrollTop = this.selectedIndex;
 		} else if (this.selectedIndex >= this.scrollTop + visibleRows) {
@@ -117,7 +153,7 @@ export class ListBox extends Window {
 		this.scrollTop  = Math.max(0, Math.min(maxScroll, this.scrollTop));
 	}
 
-	/** Rebuilds the list: renders visible rows with styles. */
+	/** Rebuilds the list: renders visible rows with styles and optional custom renderer. */
 	public override render(): void {
 		this.clear();
 
@@ -129,26 +165,109 @@ export class ListBox extends Window {
 
 		this.ensureVisible();
 
-		const visibleCount = Math.min(height, this.items.length - this.scrollTop);
-		for (let row = 0; row < visibleCount; row++) {
-			const itemIndex = this.scrollTop + row;
-			const rawText   = this.items[itemIndex];
-			// Truncate to fit width; pad with spaces so the highlight covers the whole row.
-			const text      = rawText.length > width ? rawText.slice(0, width) : rawText;
-			const padded    = text + ' '.repeat(width - text.length);
-
-			let style: StyleId;
-			if (this.disabled) {
-				style = this.disabledStyleId;
-			} else if (itemIndex === this.selectedIndex) {
-				style = this.focused ? this.focusedSelStyle : this.selectedStyleId;
-			} else {
-				style = this.normalStyleId;
+		const slotCount    = this.getVisibleRowCount();
+		const visibleCount = Math.min(slotCount, this.items.length - this.scrollTop);
+
+		for (let slot = 0; slot < visibleCount; slot++) {
+			const itemIndex = this.scrollTop + slot;
+			const item      = this.items[itemIndex];
+			const topRow    = slot * this.rowHeight;
+
+			// Pick the base row style from the current focus/selection/disabled state.
+			const baseStyle = this.pickRowStyle(itemIndex);
+
+			// Paint every row of this slot with the base style so selection highlights span the full slot.
+			for (let r = 0; r < this.rowHeight && topRow + r < height; r++) {
+				this.writeText(' '.repeat(width), { x: 0, y: topRow + r, style: baseStyle });
 			}
 
-			this.writeText(padded, { x: 0, y: row, style });
+			const segments = this.resolveSegments(item, {
+				index:    itemIndex,
+				focused:  this.focused,
+				selected: itemIndex === this.selectedIndex,
+				width,
+			});
+
+			this.drawRowSegments(topRow, segments, width, baseStyle);
 		}
 
 		super.render();
 	}
+
+	/** Returns the row-level base style ID for the given item index. */
+	private pickRowStyle(itemIndex: number): StyleId {
+		if (this.disabled) return this.disabledStyleId;
+		if (itemIndex === this.selectedIndex) {
+			return this.focused ? this.focusedSelStyle : this.selectedStyleId;
+		}
+		return this.normalStyleId;
+	}
+
+	/** Invokes the configured renderItem (or a default stringifier) and normalises the result into segments. */
+	private resolveSegments(item: T, ctx: ListBoxRenderContext): ListBoxRowSegment[] {
+		const out: ListBoxRowSegments = this.renderItem
+			? this.renderItem(item, ctx)
+			: String(item);
+		if (typeof out === 'string') {
+			return [{ text: out, align: 'left' }];
+		}
+		return out;
+	}
+
+	/** Draws a single row's segments onto the inner area at the given top row. */
+	private drawRowSegments(topRow: number, segments: ListBoxRowSegment[], width: number, baseStyle: StyleId): void {
+		const left:  ListBoxRowSegment[] = [];
+		const right: ListBoxRowSegment[] = [];
+		let fill: ListBoxRowSegment | undefined;
+
+		for (const seg of segments) {
+			const align = seg.align ?? 'left';
+			if (align === 'left')       left.push(seg);
+			else if (align === 'right') right.push(seg);
+			else if (align === 'fill' && !fill) fill = seg;
+		}
+
+		// Render left-aligned segments left-to-right starting at column 0.
+		let leftCursor = 0;
+		for (const seg of left) {
+			if (leftCursor >= width) break;
+			const available = width - leftCursor;
+			const text      = seg.text.length > available ? seg.text.slice(0, available) : seg.text;
+			const style     = this.segmentStyle(seg, baseStyle);
+			this.writeText(text, { x: leftCursor, y: topRow, style });
+			leftCursor += text.length;
+		}
+
+		// Measure right-aligned segments and render them starting at their computed offset.
+		let rightWidth = 0;
+		for (const seg of right) rightWidth += seg.text.length;
+		let rightCursor = Math.max(leftCursor, width - rightWidth);
+		for (const seg of right) {
+			if (rightCursor >= width) break;
+			const available = width - rightCursor;
+			const text      = seg.text.length > available ? seg.text.slice(0, available) : seg.text;
+			const style     = this.segmentStyle(seg, baseStyle);
+			this.writeText(text, { x: rightCursor, y: topRow, style });
+			rightCursor += text.length;
+		}
+
+		// Render the single fill segment (if any) between the left and right groups.
+		if (fill) {
+			const fillStart = leftCursor;
+			const fillEnd   = Math.max(fillStart, width - rightWidth);
+			const fillWidth = fillEnd - fillStart;
+			if (fillWidth > 0) {
+				const text  = fill.text.length >= fillWidth
+					? fill.text.slice(0, fillWidth)
+					: fill.text + ' '.repeat(fillWidth - fill.text.length);
+				const style = this.segmentStyle(fill, baseStyle);
+				this.writeText(text, { x: fillStart, y: topRow, style });
+			}
+		}
+	}
+
+	/** Merges a segment's optional style onto the row's base style, preserving the highlight background. */
+	private segmentStyle(seg: ListBoxRowSegment, baseStyle: StyleId): StyleId {
+		return seg.style !== undefined ? this.registry.merge(baseStyle, seg.style) : baseStyle;
+	}
 }

package/src/Screen/controls/TextArea.mts

@@ -14,6 +14,12 @@ export class TextArea extends Window {
 	private placeholderStyleId: StyleId;
 	private cursorStyleId: StyleId;
 
+	private onChange?: (value: string) => void;
+	private onSubmit?: (value: string) => void;
+	private onKeyDown?: (key: string) => boolean | void;
+	private insertTabAsSpaces: number;
+	private ctrlDDeletesForward: boolean;
+
 	/** Creates a TextArea from window properties and optional control-specific properties.
 	 *  Uses the global StyleRegistry set by the Screen constructor. */
 	public constructor(wp: WindowProperties, cp?: TextAreaProperties) {
@@ -34,6 +40,12 @@ export class TextArea extends Window {
 		};
 		this.cursor.x = Math.max(0, Math.min(rawCursor.x, this.lines[this.cursor.y].length));
 
+		this.onChange            = cp?.onChange;
+		this.onSubmit            = cp?.onSubmit;
+		this.onKeyDown           = cp?.onKeyDown;
+		this.insertTabAsSpaces   = Math.max(0, cp?.insertTabAsSpaces ?? 0);
+		this.ctrlDDeletesForward = cp?.ctrlDDeletesForward ?? false;
+
 		const reg = getRegistry();
 		this.placeholderStyleId = reg.getNamed(BUILTIN_TEXT_PLACEHOLDER)!;
 		this.cursorStyleId      = reg.getNamed(BUILTIN_CURSOR)!;
@@ -41,7 +53,7 @@ export class TextArea extends Window {
 		this.clampScroll();
 	}
 
-	/** Replaces the current value; cursor and scroll are clamped to fit. */
+	/** Replaces the current value; cursor and scroll are clamped to fit. Does NOT fire onChange. */
 	public setValue(text: string): void {
 		this.lines  = text.split('\n');
 		this.cursor.y = Math.min(this.cursor.y, this.lines.length - 1);
@@ -49,6 +61,27 @@ export class TextArea extends Window {
 		this.clampScroll();
 	}
 
+	/** Replaces the onChange callback. */
+	public setOnChange(fn?: (value: string) => void): void {
+		this.onChange = fn;
+	}
+
+	/** Replaces the onSubmit callback. */
+	public setOnSubmit(fn?: (value: string) => void): void {
+		this.onSubmit = fn;
+	}
+
+	/** Replaces the onKeyDown pre-dispatch hook. */
+	public setOnKeyDown(fn?: (key: string) => boolean | void): void {
+		this.onKeyDown = fn;
+	}
+
+	/** Opt-in to Tab interception: when `insertTabAsSpaces > 0`, the
+	 *  WindowManager forwards Tab to handleKey() instead of cycling focus. */
+	public capturesTab(): boolean {
+		return this.insertTabAsSpaces > 0;
+	}
+
 	/** Returns the current text value (lines joined with '\n'). */
 	public getValue(): string {
 		return this.lines.join('\n');
@@ -73,6 +106,53 @@ export class TextArea extends Window {
 	 *  Any single printable character is inserted at the cursor. */
 	public handleKey(key: string): void {
 		if (this.disabled) return;
+
+		// Give the caller a chance to intercept before built-in logic runs.
+		if (this.onKeyDown?.(key) === true) {
+			this.clampScroll();
+			return;
+		}
+
+		const before = this.getValue();
+
+		// Tab → soft-tab insert when configured, otherwise pass-through.
+		if ((key === '\t' || key === 'tab') && this.insertTabAsSpaces > 0) {
+			const spaces  = ' '.repeat(this.insertTabAsSpaces);
+			const lineTab = this.lines[this.cursor.y];
+			this.lines[this.cursor.y] = lineTab.slice(0, this.cursor.x) + spaces + lineTab.slice(this.cursor.x);
+			this.cursor.x += spaces.length;
+			this.clampScroll();
+			if (this.getValue() !== before) this.onChange?.(this.getValue());
+			return;
+		}
+		if (key === '\t' || key === 'tab') {
+			// insertTabAsSpaces === 0 → leave Tab for WindowManager focus cycling.
+			return;
+		}
+
+		// Ctrl+D forward-delete when enabled — same behaviour as \x1b[3~.
+		if (key === '\x04' && this.ctrlDDeletesForward) {
+			const lineD = this.lines[this.cursor.y];
+			if (this.cursor.x < lineD.length) {
+				this.lines[this.cursor.y] = lineD.slice(0, this.cursor.x) + lineD.slice(this.cursor.x + 1);
+			} else if (this.cursor.y < this.lines.length - 1) {
+				this.lines[this.cursor.y] = lineD + this.lines[this.cursor.y + 1];
+				this.lines.splice(this.cursor.y + 1, 1);
+			}
+			this.clampScroll();
+			if (this.getValue() !== before) this.onChange?.(this.getValue());
+			return;
+		}
+
+		// Ctrl+Enter submits without inserting a newline. In xterm this arrives
+		// as '\x1b\r' (ESC + CR) or '\n' depending on terminal; we treat the
+		// explicit alias 'ctrl+enter' plus '\n' (LF on its own) as the submit
+		// key, keeping plain '\r' for newline insertion.
+		if (key === 'ctrl+enter') {
+			this.onSubmit?.(this.getValue());
+			return;
+		}
+
 		const line = this.lines[this.cursor.y];
 		switch (key) {
 			case '\x7f': case '\b': case 'backspace':
@@ -142,6 +222,7 @@ export class TextArea extends Window {
 				}
 		}
 		this.clampScroll();
+		if (this.getValue() !== before) this.onChange?.(this.getValue());
 	}
 
 	/** Rebuilds the TextArea: renders visible lines, draws cursor. */

package/src/Screen/controls/TextBox.mts

@@ -14,6 +14,13 @@ export class TextBox extends Window {
 	private placeholderStyleId: StyleId;
 	private cursorStyleId: StyleId;
 
+	/** Invoked after every value change driven by handleKey. Not called by setValue. */
+	private onChange?: (value: string) => void;
+	/** Invoked when Enter is pressed while focused. */
+	private onSubmit?: (value: string) => void;
+	/** Pre-dispatch hook — return true to short-circuit built-in handling. */
+	private onKeyDown?: (key: string) => boolean | void;
+
 	/** Creates a TextBox from window properties and optional control-specific properties.
 	 *  Uses the global StyleRegistry set by the Screen constructor. */
 	public constructor(wp: WindowProperties, cp?: TextBoxProperties) {
@@ -29,6 +36,10 @@ export class TextBox extends Window {
 			? Math.max(0, Math.min(cp.cursor, this.value.length))
 			: this.value.length;
 
+		this.onChange  = cp?.onChange;
+		this.onSubmit  = cp?.onSubmit;
+		this.onKeyDown = cp?.onKeyDown;
+
 		const reg = getRegistry();
 		this.placeholderStyleId = reg.getNamed(BUILTIN_TEXT_PLACEHOLDER)!;
 		this.cursorStyleId      = reg.getNamed(BUILTIN_CURSOR)!;
@@ -36,13 +47,28 @@ export class TextBox extends Window {
 		this.clampScroll();
 	}
 
-	/** Replaces the current value; clamps cursor and scroll to fit. */
+	/** Replaces the current value; clamps cursor and scroll to fit. Does NOT fire onChange. */
 	public setValue(value: string): void {
 		this.value  = value;
 		this.cursor = Math.min(this.cursor, value.length);
 		this.clampScroll();
 	}
 
+	/** Replaces the onChange callback (passing undefined clears it). */
+	public setOnChange(fn?: (value: string) => void): void {
+		this.onChange = fn;
+	}
+
+	/** Replaces the onSubmit callback. */
+	public setOnSubmit(fn?: (value: string) => void): void {
+		this.onSubmit = fn;
+	}
+
+	/** Replaces the onKeyDown pre-dispatch hook. */
+	public setOnKeyDown(fn?: (key: string) => boolean | void): void {
+		this.onKeyDown = fn;
+	}
+
 	/** Returns the current text value. */
 	public getValue(): string {
 		return this.value;
@@ -66,7 +92,19 @@ export class TextBox extends Window {
 	 *  Any single printable character is inserted at the cursor position. */
 	public handleKey(key: string): void {
 		if (this.disabled) return;
+
+		// Give the caller a chance to intercept before built-in logic runs.
+		if (this.onKeyDown?.(key) === true) {
+			this.clampScroll();
+			return;
+		}
+
+		const before = this.value;
 		switch (key) {
+			case '\r': case '\n': case 'enter':
+				this.onSubmit?.(this.value);
+				this.clampScroll();
+				return; // Enter never mutates value by itself in TextBox.
 			case '\x7f': case '\b': case 'backspace':
 				if (this.cursor > 0) {
 					this.value = this.value.slice(0, this.cursor - 1) + this.value.slice(this.cursor);
@@ -97,6 +135,7 @@ export class TextBox extends Window {
 				}
 		}
 		this.clampScroll();
+		if (this.value !== before) this.onChange?.(this.value);
 	}
 
 	/** Rebuilds the TextBox: renders text or placeholder, draws cursor. */

package/src/Screen/textWidth.mts

@@ -0,0 +1,186 @@
+// Unicode display width for monospace terminals.
+//
+// Maps a codepoint to its visible cell width (0, 1 or 2). Used by
+// Window.writeText so wide characters (CJK, emoji, NerdFonts double-width)
+// occupy two consecutive cells in the buffer, and by Window.getTextWidth /
+// stringWidth() so consumers can size labels correctly.
+//
+// The internal tables are derived from the Unicode East Asian Width data
+// (W and F categories) plus a curated set of zero-width / control / combining
+// ranges. They are intentionally compact rather than exhaustive — the goal is
+// "good enough for labels and log output", not full Unicode normalization.
+
+/** Configurable display width for the Private Use Area (NerdFonts glyphs).
+ *  Most NerdFonts ship single-cell glyphs but some patched fonts use 2 cells. */
+let puaWidth: 1 | 2 = 1;
+
+/** Sets the display width used for codepoints in the Unicode Private Use Areas
+ *  (U+E000–F8FF, U+F0000–FFFFD, U+100000–10FFFD). NerdFonts glyphs typically
+ *  render as one cell; some patched fonts render them as two cells. Default: 1. */
+export const setPuaWidth = (width: 1 | 2): void => {
+	puaWidth = width;
+};
+
+/** Returns the currently configured Private Use Area width. */
+export const getPuaWidth = (): 1 | 2 => puaWidth;
+
+/** Zero-width ranges: control characters, combining marks, format characters,
+ *  variation selectors, joiners. Sorted by start codepoint for binary search. */
+const ZERO_RANGES: ReadonlyArray<readonly [number, number]> = [
+	[0x0000,  0x001F],
+	[0x007F,  0x009F],
+	[0x00AD,  0x00AD],
+	[0x0300,  0x036F],
+	[0x0483,  0x0489],
+	[0x0591,  0x05BD],
+	[0x05BF,  0x05BF],
+	[0x05C1,  0x05C2],
+	[0x05C4,  0x05C5],
+	[0x05C7,  0x05C7],
+	[0x0610,  0x061A],
+	[0x061C,  0x061C],
+	[0x064B,  0x065F],
+	[0x0670,  0x0670],
+	[0x06D6,  0x06DC],
+	[0x06DF,  0x06E4],
+	[0x06E7,  0x06E8],
+	[0x06EA,  0x06ED],
+	[0x0711,  0x0711],
+	[0x0730,  0x074A],
+	[0x07A6,  0x07B0],
+	[0x07EB,  0x07F3],
+	[0x07FD,  0x07FD],
+	[0x0816,  0x0819],
+	[0x081B,  0x0823],
+	[0x0825,  0x0827],
+	[0x0829,  0x082D],
+	[0x0859,  0x085B],
+	[0x08D3,  0x08E1],
+	[0x08E3,  0x0902],
+	[0x093A,  0x093A],
+	[0x093C,  0x093C],
+	[0x0941,  0x0948],
+	[0x094D,  0x094D],
+	[0x0951,  0x0957],
+	[0x0962,  0x0963],
+	[0x180B,  0x180E],
+	[0x200B,  0x200F],
+	[0x202A,  0x202E],
+	[0x2060,  0x2064],
+	[0x2066,  0x206F],
+	[0xFE00,  0xFE0F],
+	[0xFEFF,  0xFEFF],
+	[0xE0100, 0xE01EF],
+];
+
+/** Wide (W or F) ranges: characters that occupy two terminal cells. */
+const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+	[0x1100,  0x115F],
+	[0x231A,  0x231B],
+	[0x2329,  0x232A],
+	[0x23E9,  0x23EC],
+	[0x23F0,  0x23F0],
+	[0x23F3,  0x23F3],
+	[0x25FD,  0x25FE],
+	[0x2614,  0x2615],
+	[0x2648,  0x2653],
+	[0x267F,  0x267F],
+	[0x2693,  0x2693],
+	[0x26A1,  0x26A1],
+	[0x26AA,  0x26AB],
+	[0x26BD,  0x26BE],
+	[0x26C4,  0x26C5],
+	[0x26CE,  0x26CE],
+	[0x26D4,  0x26D4],
+	[0x26EA,  0x26EA],
+	[0x26F2,  0x26F3],
+	[0x26F5,  0x26F5],
+	[0x26FA,  0x26FA],
+	[0x26FD,  0x26FD],
+	[0x2705,  0x2705],
+	[0x270A,  0x270B],
+	[0x2728,  0x2728],
+	[0x274C,  0x274C],
+	[0x274E,  0x274E],
+	[0x2753,  0x2755],
+	[0x2757,  0x2757],
+	[0x2795,  0x2797],
+	[0x27B0,  0x27B0],
+	[0x27BF,  0x27BF],
+	[0x2B1B,  0x2B1C],
+	[0x2B50,  0x2B50],
+	[0x2B55,  0x2B55],
+	[0x2E80,  0x303E],
+	[0x3041,  0x33FF],
+	[0x3400,  0x4DBF],
+	[0x4E00,  0x9FFF],
+	[0xA000,  0xA4CF],
+	[0xA960,  0xA97F],
+	[0xAC00,  0xD7A3],
+	[0xF900,  0xFAFF],
+	[0xFE10,  0xFE19],
+	[0xFE30,  0xFE6F],
+	[0xFF00,  0xFF60],
+	[0xFFE0,  0xFFE6],
+	[0x16FE0, 0x16FE4],
+	[0x17000, 0x187F7],
+	[0x18800, 0x18AFF],
+	[0x1B000, 0x1B11F],
+	[0x1F004, 0x1F004],
+	[0x1F0CF, 0x1F0CF],
+	[0x1F18E, 0x1F18E],
+	[0x1F191, 0x1F19A],
+	[0x1F200, 0x1F320],
+	[0x1F330, 0x1F335],
+	[0x1F337, 0x1F37C],
+	[0x1F380, 0x1F39F],
+	[0x1F3A0, 0x1F3FA],
+	[0x1F400, 0x1F4FD],
+	[0x1F500, 0x1F53D],
+	[0x1F549, 0x1F54E],
+	[0x1F550, 0x1F567],
+	[0x1F57A, 0x1F57A],
+	[0x1F595, 0x1F596],
+	[0x1F5A4, 0x1F5A4],
+	[0x1F5FB, 0x1F64F],
+	[0x1F680, 0x1F6FF],
+	[0x1F900, 0x1F9FF],
+	[0x1FA70, 0x1FAFF],
+	[0x20000, 0x2FFFD],
+	[0x30000, 0x3FFFD],
+];
+
+/** Binary search: returns true when codepoint lies inside any [start, end] interval. */
+const inRanges = (cp: number, ranges: ReadonlyArray<readonly [number, number]>): boolean => {
+	let lo = 0;
+	let hi = ranges.length - 1;
+	while (lo <= hi) {
+		const mid = (lo + hi) >>> 1;
+		const r   = ranges[mid];
+		if (cp < r[0])      hi = mid - 1;
+		else if (cp > r[1]) lo = mid + 1;
+		else                return true;
+	}
+	return false;
+};
+
+/** Returns the display width (0, 1 or 2 cells) of a single Unicode codepoint. */
+export const charWidth = (codepoint: number): 0 | 1 | 2 => {
+	// Private Use Areas — checked first because they overlap with neither
+	// zero nor wide tables and we want the configured width to win.
+	if (codepoint >= 0xE000   && codepoint <= 0xF8FF)   return puaWidth;
+	if (codepoint >= 0xF0000  && codepoint <= 0xFFFFD)  return puaWidth;
+	if (codepoint >= 0x100000 && codepoint <= 0x10FFFD) return puaWidth;
+	if (inRanges(codepoint, ZERO_RANGES)) return 0;
+	if (inRanges(codepoint, WIDE_RANGES)) return 2;
+	return 1;
+};
+
+/** Returns the total display width of a string in monospace terminal cells.
+ *  Iterates by codepoint, so surrogate pairs are counted once with their
+ *  combined width (typically 2 for emoji and supplementary CJK). */
+export const stringWidth = (str: string): number => {
+	let total = 0;
+	for (const ch of str) total += charWidth(ch.codePointAt(0)!);
+	return total;
+};