pi-libtui 0.3.2

package/src/background-surface.ts

@@ -0,0 +1,125 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type TuiBackgroundPaint, type TuiBackgroundToken, tuiTheme } from "./color/theme.ts";
+import { TEXT_INTERACTION_TARGET, type TextInteractionTarget, type TuiMouseEvent } from "./mouse.ts";
+import { getTuiRenderEpoch } from "./render-epoch.ts";
+
+export interface BackgroundSurfaceOptions {
+	theme: Theme;
+	component: Component;
+	background?: TuiBackgroundPaint;
+	/** Leave shorter content unpainted. Defaults to one rendered row. */
+	minimumRows?: number;
+}
+
+export type HalfBlockSurfaceEdge = "top" | "bottom";
+
+/** Canonical background for multiline tool and foldable content. */
+export const TOOL_SURFACE_BACKGROUND: TuiBackgroundToken = "surface.raised";
+
+/** Paint a half-cell cap for a raised or selected surface. */
+export function halfBlockSurfaceEdge(
+	theme: Theme,
+	background: TuiBackgroundPaint,
+	edge: HalfBlockSurfaceEdge,
+	width: number,
+): string {
+	const boundedWidth = Math.max(0, Math.floor(width));
+	const colors = tuiTheme(theme);
+	const foreground = typeof background === "string" ? colors.color(background) : background;
+	return colors.fg(foreground, (edge === "top" ? "▄" : "▀").repeat(boundedWidth));
+}
+
+/** Paint a component's rows edge-to-edge without adding a border, padding, or indentation. */
+export class BackgroundSurface implements Component, TextInteractionTarget {
+	readonly [TEXT_INTERACTION_TARGET] = true as const;
+	private cachedWidth = -1;
+	private cachedEpoch = -1;
+	private cachedInput: string[] | undefined;
+	private cachedOutput: string[] | undefined;
+
+	constructor(private readonly options: BackgroundSurfaceOptions) {}
+
+	render(width: number): string[] {
+		const boundedWidth = Math.max(0, Math.floor(width));
+		if (boundedWidth === 0) return [];
+		const epoch = getTuiRenderEpoch();
+		const input = this.options.component.render(boundedWidth);
+		if (
+			this.cachedWidth === boundedWidth &&
+			this.cachedEpoch === epoch &&
+			this.cachedInput?.length === input.length &&
+			this.cachedInput.every((line, index) => line === input[index]) &&
+			this.cachedOutput
+		)
+			return this.cachedOutput;
+		const minimumRows = Math.max(1, Math.floor(this.options.minimumRows ?? 1));
+		const output =
+			input.length < minimumRows
+				? input
+				: paintRows(
+						input,
+						boundedWidth,
+						tuiTheme(this.options.theme).bgAnsi(this.options.background ?? TOOL_SURFACE_BACKGROUND),
+					);
+		this.cachedWidth = boundedWidth;
+		this.cachedEpoch = epoch;
+		this.cachedInput = [...input];
+		this.cachedOutput = output;
+		return output;
+	}
+
+	invalidate(): void {
+		this.cachedInput = undefined;
+		this.cachedOutput = undefined;
+		this.options.component.invalidate();
+	}
+
+	setViewportFocus(focused: boolean): void {
+		this.target().setViewportFocus?.(focused);
+	}
+
+	isViewportFocused(): boolean {
+		return this.target().isViewportFocused?.() ?? false;
+	}
+
+	handleViewportInput(data: string): boolean {
+		const target = this.target();
+		return target.handleViewportInput?.(data) ?? target.handleInput?.(data) ?? false;
+	}
+
+	handleInput(data: string): void {
+		this.target().handleInput?.(data);
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		return this.target().onMouse?.(event) ?? false;
+	}
+
+	dispose(): void {
+		(this.options.component as Component & { dispose?(): void }).dispose?.();
+	}
+
+	private target() {
+		return this.options.component as Component & {
+			setViewportFocus?(focused: boolean): void;
+			isViewportFocused?(): boolean;
+			handleViewportInput?(data: string): boolean;
+			handleInput?(data: string): boolean;
+			onMouse?(event: TuiMouseEvent): boolean;
+		};
+	}
+}
+
+function paintRows(input: readonly string[], width: number, background: string): string[] {
+	return input.map((line) => {
+		const clipped = truncateToWidth(line, width, "…")
+			.replaceAll("\x1b[49m", `\x1b[49m${background}`)
+			.replaceAll("\x1b[0m", `\x1b[0m${background}`);
+		// Child content may leave a foreground/style SGR active (for example an
+		// underline or an external background). Reset before painting padding so
+		// that a short row cannot leak that style across the rest of the surface.
+		const padded = `${clipped}\x1b[0m${background}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+		return `${background}${padded}\x1b[49m`;
+	});
+}

package/src/color/palette.ts

@@ -0,0 +1,186 @@
+export interface RgbColor {
+	readonly r: number;
+	readonly g: number;
+	readonly b: number;
+}
+
+export type TuiHue = "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "gray";
+export type TuiShade = 0 | 1 | 2 | 3 | 4 | 5;
+
+export interface TuiSwatch {
+	readonly hue: TuiHue;
+	readonly shade: TuiShade;
+}
+
+declare const COLOR256_INDEX: unique symbol;
+
+/** An ANSI 0..255 index produced by one of the validated palette constructors. */
+export type Color256Index = number & { readonly [COLOR256_INDEX]: true };
+
+// CIELAB conversion and interpolation are a TypeScript port of the public-domain
+// color256 implementation: https://github.com/jake-stewart/color256
+
+type LabColor = readonly [number, number, number];
+
+const XTERM_BASE_16 = [
+	[0, 0, 0],
+	[128, 0, 0],
+	[0, 128, 0],
+	[128, 128, 0],
+	[0, 0, 128],
+	[128, 0, 128],
+	[0, 128, 128],
+	[192, 192, 192],
+	[128, 128, 128],
+	[255, 0, 0],
+	[0, 255, 0],
+	[255, 255, 0],
+	[0, 0, 255],
+	[255, 0, 255],
+	[0, 255, 255],
+	[255, 255, 255],
+] as const;
+
+export function rgb(r: number, g: number, b: number): RgbColor {
+	return Object.freeze({ r: channel(r), g: channel(g), b: channel(b) });
+}
+
+/** Simple YIQ luminance for choosing between light and dark text. */
+export function yiqLuminance(color: RgbColor): number {
+	return color.r * 0.299 + color.g * 0.587 + color.b * 0.114;
+}
+
+export function xtermColor(index: number): RgbColor {
+	const bounded = Math.max(0, Math.min(255, Math.floor(index)));
+	if (bounded < 16) {
+		const [red, green, blue] = XTERM_BASE_16[bounded]!;
+		return rgb(red, green, blue);
+	}
+	if (bounded >= 232) {
+		const value = 8 + (bounded - 232) * 10;
+		return rgb(value, value, value);
+	}
+	const cubeOffset = bounded - 16;
+	return rgb(
+		xtermChannel(Math.floor(cubeOffset / 36) % 6),
+		xtermChannel(Math.floor(cubeOffset / 6) % 6),
+		xtermChannel(cubeOffset % 6),
+	);
+}
+
+/** Select a color256 entry using logical red, green, and blue channels from 0 through 5. */
+export function color256Index(red: number, green: number, blue: number): Color256Index {
+	validateColor256Level(red);
+	validateColor256Level(green);
+	validateColor256Level(blue);
+	return (16 + red * 36 + green * 6 + blue) as Color256Index;
+}
+
+/** Select a grayscale entry while preserving logical dark/light ordering. */
+export function gray256Index(value: number): Color256Index {
+	if (!Number.isInteger(value) || value < 0 || value > 23) {
+		throw new RangeError(`Gray palette channel must be an integer from 0 through 23; received ${value}`);
+	}
+	return (232 + value) as Color256Index;
+}
+
+/** Resolve a six-level hue and shade to its corresponding color256 index. */
+export function swatch(hue: TuiHue, shade: TuiShade): Color256Index {
+	if (hue === "gray") return gray256Index(Math.round((shade * 23) / 5));
+	const channels: Record<Exclude<TuiHue, "gray">, readonly [number, number, number]> = {
+		red: [shade, 0, 0],
+		green: [0, shade, 0],
+		yellow: [shade, shade, 0],
+		blue: [0, 0, shade],
+		magenta: [shade, 0, shade],
+		cyan: [0, shade, shade],
+	};
+	return color256Index(...channels[hue]);
+}
+
+function validateColor256Level(value: number): void {
+	if (!Number.isInteger(value) || value < 0 || value > 5) {
+		throw new RangeError(`Color cube channel must be an integer from 0 through 5; received ${value}`);
+	}
+}
+
+/** Generate the extended palette described by jake-stewart/color256. */
+export function generateColor256(
+	base16: readonly RgbColor[],
+	background: RgbColor,
+	foreground: RgbColor,
+): readonly RgbColor[] {
+	if (base16.length < 16) throw new RangeError("A base16 palette needs 16 colors");
+	const backgroundLab = rgbToLab(background);
+	const foregroundLab = rgbToLab(foreground);
+	const corners = [
+		backgroundLab,
+		rgbToLab(base16[1]!),
+		rgbToLab(base16[2]!),
+		rgbToLab(base16[3]!),
+		rgbToLab(base16[4]!),
+		rgbToLab(base16[5]!),
+		rgbToLab(base16[6]!),
+		foregroundLab,
+	] as const;
+	const palette: RgbColor[] = base16.slice(0, 16).map((color) => rgb(color.r, color.g, color.b));
+
+	for (let red = 0; red < 6; red += 1) {
+		const c0 = lerpLab(red / 5, corners[0], corners[1]);
+		const c1 = lerpLab(red / 5, corners[2], corners[3]);
+		const c2 = lerpLab(red / 5, corners[4], corners[5]);
+		const c3 = lerpLab(red / 5, corners[6], corners[7]);
+		for (let green = 0; green < 6; green += 1) {
+			const c4 = lerpLab(green / 5, c0, c1);
+			const c5 = lerpLab(green / 5, c2, c3);
+			for (let blue = 0; blue < 6; blue += 1) {
+				palette.push(labToRgb(lerpLab(blue / 5, c4, c5)));
+			}
+		}
+	}
+
+	for (let shade = 0; shade < 24; shade += 1) {
+		palette.push(labToRgb(lerpLab((shade + 1) / 25, corners[0], corners[7])));
+	}
+	return Object.freeze(palette);
+}
+
+function rgbToLab(color: RgbColor): LabColor {
+	const [red, green, blue] = [color.r, color.g, color.b].map((value) => {
+		const normalized = value / 255;
+		return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+	});
+	const x = (red! * 0.4124 + green! * 0.3576 + blue! * 0.1805) / 0.95047;
+	const y = red! * 0.2126 + green! * 0.7152 + blue! * 0.0722;
+	const z = (red! * 0.0193 + green! * 0.1192 + blue! * 0.9505) / 1.08883;
+	const [fx, fy, fz] = [x, y, z].map((value) => (value > 0.008856 ? value ** (1 / 3) : 7.787 * value + 16 / 116));
+	return [116 * fy! - 16, 500 * (fx! - fy!), 200 * (fy! - fz!)];
+}
+
+function labToRgb([lightness, a, b]: LabColor): RgbColor {
+	const fy = (lightness + 16) / 116;
+	const fx = a / 500 + fy;
+	const fz = fy - b / 200;
+	const [x0, y0, z0] = [fx, fy, fz].map((value) => (value ** 3 > 0.008856 ? value ** 3 : (value - 16 / 116) / 7.787));
+	const x = x0! * 0.95047;
+	const y = y0!;
+	const z = z0! * 1.08883;
+	const values = [
+		x * 3.2406 + y * -1.5372 + z * -0.4986,
+		x * -0.9689 + y * 1.8758 + z * 0.0415,
+		x * 0.0557 + y * -0.204 + z * 1.057,
+	].map((value) => (value <= 0.0031308 ? 12.92 * value : 1.055 * value ** (1 / 2.4) - 0.055));
+	return rgb(values[0]! * 255, values[1]! * 255, values[2]! * 255);
+}
+
+function lerpLab(t: number, left: LabColor, right: LabColor): LabColor {
+	return [left[0] + t * (right[0] - left[0]), left[1] + t * (right[1] - left[1]), left[2] + t * (right[2] - left[2])];
+}
+
+function channel(value: number): number {
+	return Math.max(0, Math.min(255, Math.round(value)));
+}
+
+function xtermChannel(value: number): number {
+	return value === 0 ? 0 : 55 + value * 40;
+}

package/src/color/preview.ts

@@ -0,0 +1,157 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, type Focusable, matchesKey } from "@earendil-works/pi-tui";
+import { color256Index } from "./palette.ts";
+
+type ChannelMask = readonly [red: boolean, green: boolean, blue: boolean];
+
+const HUE_EDGES: readonly ChannelMask[] = [
+	[true, false, false],
+	[true, true, false],
+	[false, true, false],
+	[false, true, true],
+	[false, false, true],
+	[true, false, true],
+];
+
+/** Width of the upstream color256 terminal preview, including its base16 legend. */
+export const COLOR256_PREVIEW_WIDTH = 69;
+
+/**
+ * Render the active terminal's 256-color palette in color256's perceptual grid.
+ * Layout ported from the public-domain `preview_theme` implementation:
+ * https://github.com/jake-stewart/color256/blob/master/color256.py
+ */
+export function renderColor256Preview(name: string): string[] {
+	const grays = grayCells(24, 6);
+	const colors = [
+		...colorSlices({ reverse: true, includeFinal: true, background: true }),
+		...colorSlices({ reverse: false, includeFinal: false, background: false }),
+	];
+	const body = grays.map((gray, row) => `${gray}${colors[row] ?? ""}${gray}`);
+	const title = `${grayCells(5, 0).join("")}${center(name.slice(0, 24), 24)}${grayCells(0, 5).join("")}`;
+	const grid = [...body, title];
+	const legend = base16Legend();
+	return grid.map((line, row) => `${line}   ${legend[row] ?? "      "}`);
+}
+
+/** Focusable screen used by the `/libtui:colors` diagnostic command. */
+export class Color256Preview implements Component, Focusable {
+	focused = false;
+
+	constructor(
+		private readonly theme: Theme,
+		private readonly close: () => void,
+	) {}
+
+	render(): string[] {
+		return renderColor256Preview(this.theme.name ?? "Active Theme");
+	}
+
+	handleInput(data: string): void {
+		if (data === "q" || matchesKey(data, "escape")) this.close();
+	}
+
+	invalidate(): void {}
+}
+
+interface SliceOptions {
+	reverse: boolean;
+	includeFinal: boolean;
+	background: boolean;
+}
+
+function colorSlices(options: SliceOptions): string[] {
+	const columns: string[][] = [];
+	for (let edge = 0; edge < HUE_EDGES.length; edge += 1) {
+		const current = HUE_EDGES[edge]!;
+		const next = HUE_EDGES[(edge + 1) % HUE_EDGES.length]!;
+		for (let step = 0; step < 3; step += 1) {
+			columns.push(
+				colorSlice(
+					[...Array.from({ length: 3 - step }, () => current), ...Array.from({ length: step }, () => next)],
+					options,
+				),
+			);
+		}
+	}
+	const rows = Array.from({ length: columns[0]?.length ?? 0 }, () => "");
+	for (const column of columns) {
+		for (let row = 0; row < rows.length; row += 1) rows[row] += column[row] ?? "   ";
+	}
+	return rows;
+}
+
+function colorSlice(masks: readonly ChannelMask[], options: SliceOptions): string[] {
+	const cells: string[] = [];
+	for (let level = 1; level < 6; level += 1) {
+		const [red, green, blue] = averageChannels(masks, level, false);
+		const brightness = Math.floor(((red + green + blue) / 15) * 16).toString(16);
+		cells.push(indexedCell(color256Index(red, green, blue), ` ${brightness} `, options.background));
+	}
+	for (let level = 1; level < (options.includeFinal ? 6 : 5); level += 1) {
+		const [red, green, blue] = averageChannels(masks, level, true);
+		const brightness = Math.floor(((red + green + blue) / 16) * 16).toString(16);
+		cells.push(indexedCell(color256Index(red, green, blue), ` ${brightness} `, options.background));
+	}
+	if (options.reverse) cells.reverse();
+	return cells;
+}
+
+function averageChannels(masks: readonly ChannelMask[], level: number, inverted: boolean): [number, number, number] {
+	const channels = [0, 0, 0];
+	for (const mask of masks) {
+		for (let channel = 0; channel < 3; channel += 1) {
+			channels[channel] += mask[channel] ? (inverted ? 5 : level) : inverted ? level : 0;
+		}
+	}
+	return channels.map((value) => Math.floor(value / masks.length)) as [number, number, number];
+}
+
+function grayCells(from: number, to: number): string[] {
+	const direction = from <= to ? 1 : -1;
+	const cells: string[] = [];
+	for (let shade = from; shade !== to + direction; shade += direction) {
+		const index = shade === 24 ? 231 : 232 + shade;
+		const label = Math.min(15, Math.floor((shade / 24) * 16)).toString(16);
+		cells.push(indexedCell(index, ` ${label} `, true));
+	}
+	return cells;
+}
+
+function base16Legend(): string[] {
+	return [
+		"      ",
+		...Array.from(
+			{ length: 8 },
+			(_, index) =>
+				`${indexedCell(index, ` ${index.toString(16)} `, true)}${indexedCell(index + 8, ` ${(index + 8).toString(16)} `, true)}`,
+		),
+		"      ",
+		"      ",
+		...Array.from(
+			{ length: 8 },
+			(_, index) =>
+				`${indexedCell(index, ` ${index.toString(16)} `, false)}${indexedCell(index + 8, ` ${(index + 8).toString(16)} `, false)}`,
+		),
+		"      ",
+	];
+}
+
+function center(text: string, width: number): string {
+	const left = Math.floor((width - text.length) / 2);
+	return `${" ".repeat(left)}${text}${" ".repeat(width - left - text.length)}`;
+}
+
+function indexedCell(index: number, text: string, background: boolean): string {
+	if (!background) return `\x1b[38;5;${index}m${text}\x1b[0m`;
+	return isDark(index) ? `\x1b[48;5;${index}m${text}\x1b[0m` : `\x1b[38;5;${index};7m${text}\x1b[0m`;
+}
+
+function isDark(index: number): boolean {
+	if (index >= 16 && index <= 231) {
+		const cube = index - 16;
+		return Math.floor(cube / 36) < 4 && Math.floor(cube / 6) % 6 < 4 && cube % 6 < 4;
+	}
+	if (index >= 232) return index - 232 < 11;
+	return index % 8 === 0;
+}

package/src/color/resolver.ts

@@ -0,0 +1,75 @@
+import { type Color256Index, color256Index, type RgbColor, xtermColor } from "./palette.ts";
+
+/** A resolved palette entry or an exact color measured at a terminal boundary. */
+export type ColorValue = Color256Index | RgbColor;
+
+const closestXtermCache = new Map<string, number>();
+
+/** Render and measure one direct value through the active terminal policy. */
+export function createColorResolver(context: {
+	readonly resolvedPalette?: readonly RgbColor[];
+	readonly output: "direct-indexed" | "quantized-indexed" | "truecolor";
+}) {
+	const dark = color256Index(0, 0, 0);
+	const light = color256Index(5, 5, 5);
+	const rgb = (value: ColorValue): RgbColor => {
+		return typeof value === "number" ? (context.resolvedPalette?.[value] ?? xtermColor(value)) : value;
+	};
+	const ansi = (value: ColorValue, background: boolean): string => {
+		const prefix = background ? 48 : 38;
+		if (context.output !== "truecolor") {
+			const index =
+				typeof value === "number" && context.output === "direct-indexed" ? value : closestXtermIndex(rgb(value));
+			return `\x1b[${prefix};5;${index}m`;
+		}
+		const color = rgb(value);
+		return `\x1b[${prefix};2;${color.r};${color.g};${color.b}m`;
+	};
+	return {
+		rgb,
+		ansi,
+		contrast(value: ColorValue) {
+			const background = rgb(value);
+			return contrastRatio(background, rgb(dark)) >= contrastRatio(background, rgb(light)) ? dark : light;
+		},
+		contrastRatio(left: ColorValue, right: ColorValue) {
+			return contrastRatio(rgb(left), rgb(right));
+		},
+	};
+}
+
+function contrastRatio(left: RgbColor, right: RgbColor): number {
+	const lighter = Math.max(relativeLuminance(left), relativeLuminance(right));
+	const darker = Math.min(relativeLuminance(left), relativeLuminance(right));
+	return (lighter + 0.05) / (darker + 0.05);
+}
+
+function relativeLuminance(color: RgbColor): number {
+	const channel = (value: number): number => {
+		const normalized = value / 255;
+		return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+	};
+	return channel(color.r) * 0.2126 + channel(color.g) * 0.7152 + channel(color.b) * 0.0722;
+}
+
+function closestXtermIndex(color: RgbColor): number {
+	const key = `${color.r},${color.g},${color.b}`;
+	const cached = closestXtermCache.get(key);
+	if (cached !== undefined) return cached;
+	let best = 0;
+	let distance = Number.POSITIVE_INFINITY;
+	for (let index = 0; index < 256; index += 1) {
+		const candidate = xtermColor(index);
+		const next =
+			(color.r - candidate.r) ** 2 * 0.299 +
+			(color.g - candidate.g) ** 2 * 0.587 +
+			(color.b - candidate.b) ** 2 * 0.114;
+		if (next < distance) {
+			best = index;
+			distance = next;
+		}
+	}
+	if (closestXtermCache.size >= 4096) closestXtermCache.clear();
+	closestXtermCache.set(key, best);
+	return best;
+}