@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/src/theme/mermaid-cache.ts

@@ -0,0 +1,92 @@
+import { type MermaidAsciiRenderOptions, renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils/mermaid-ascii";
+
+/**
+ * Options controlling how fenced Mermaid source is resolved to terminal ASCII.
+ * Extends the raw render options (theme, color mode, spacing, `useAscii`) with a
+ * viewport-fitting hint.
+ */
+export interface MermaidResolveOptions extends MermaidAsciiRenderOptions {
+	/**
+	 * Maximum display width (terminal columns) the diagram should occupy. A
+	 * layout that overflows this width is re-rendered in the perpendicular
+	 * orientation — a wide horizontal chain collapses to a tall vertical column
+	 * (which the terminal can scroll), and a wide vertical fan-out collapses to a
+	 * tall horizontal column. Omit to keep the source's own layout regardless of
+	 * width.
+	 */
+	maxWidth?: number;
+}
+
+// Memoizes rendered ASCII (and failures) keyed on the render options + the
+// layout-direction variant + source. Width selection happens per call against
+// the cached renders, so a terminal resize re-decides without re-rendering.
+const cache = new Map<string, string | null>();
+
+/** Widest rendered row in display columns (ANSI- and CJK-aware). */
+function asciiDisplayWidth(ascii: string): number {
+	let max = 0;
+	for (const line of ascii.split("\n")) {
+		const width = Bun.stringWidth(line);
+		if (width > max) max = width;
+	}
+	return max;
+}
+
+function renderVariant(
+	source: string,
+	baseOptions: MermaidAsciiRenderOptions,
+	baseKey: string,
+	direction: "TD" | "LR" | null,
+): string | null {
+	const key = `${baseKey}\x00${direction ?? ""}\x00${source}`;
+	const cached = cache.get(key);
+	if (cached !== undefined) return cached;
+
+	const ascii = renderMermaidAsciiSafe(source, direction ? { ...baseOptions, direction } : baseOptions);
+	cache.set(key, ascii);
+	return ascii;
+}
+
+/**
+ * Resolve mermaid ASCII from fenced block source text.
+ * Returns null when rendering fails, while memoizing failures to avoid repeated work.
+ */
+export function resolveMermaidAscii(source: string, options?: MermaidResolveOptions): string | null {
+	const normalizedSource = source.replace(/\r\n?/g, "\n").trim();
+	if (!normalizedSource) return null;
+
+	const { maxWidth, ...rest } = options ?? {};
+	// Default to uncolored output; callers opt into a themed palette explicitly.
+	const baseOptions: MermaidAsciiRenderOptions = { colorMode: "none", ...rest };
+	const baseKey = JSON.stringify(baseOptions);
+
+	const base = renderVariant(normalizedSource, baseOptions, baseKey, null);
+	if (base === null) return null;
+	if (maxWidth === undefined) return base;
+
+	let best = base;
+	let bestWidth = asciiDisplayWidth(base);
+	if (bestWidth <= maxWidth) return base;
+
+	// The as-authored layout overflows. Render both forced orientations and keep
+	// the narrowest (clipping at the call site handles any residual overflow).
+	// Re-rendering the already-authored orientation is a cache hit, so this stays
+	// cheap, and one of the two will be the perpendicular fit.
+	for (const direction of ["TD", "LR"] as const) {
+		const variant = renderVariant(normalizedSource, baseOptions, baseKey, direction);
+		if (variant === null) continue;
+		const variantWidth = asciiDisplayWidth(variant);
+		if (variantWidth < bestWidth) {
+			best = variant;
+			bestWidth = variantWidth;
+		}
+	}
+	return best;
+}
+
+/**
+ * Clear the mermaid cache.
+ */
+export function clearMermaidCache(): void {
+	cache.clear();
+}

package/src/theme/schema-validation.ts

@@ -0,0 +1,119 @@
+import { type } from "@oh-my-pi/omptype";
+import type { SpinnerFramesOverride } from "./symbols";
+import type { ThemeJson } from "./schema";
+
+const themeColorsSchema = type({
+	accent: "string | number",
+	border: "string | number",
+	borderAccent: "string | number",
+	borderMuted: "string | number",
+	success: "string | number",
+	error: "string | number",
+	warning: "string | number",
+	muted: "string | number",
+	dim: "string | number",
+	text: "string | number",
+	thinkingText: "string | number",
+	selectedBg: "string | number",
+	userMessageBg: "string | number",
+	userMessageText: "string | number",
+	customMessageBg: "string | number",
+	customMessageText: "string | number",
+	customMessageLabel: "string | number",
+	toolPendingBg: "string | number",
+	toolSuccessBg: "string | number",
+	toolErrorBg: "string | number",
+	toolTitle: "string | number",
+	toolOutput: "string | number",
+	mdHeading: "string | number",
+	mdLink: "string | number",
+	mdLinkUrl: "string | number",
+	mdCode: "string | number",
+	mdCodeBlock: "string | number",
+	mdCodeBlockBorder: "string | number",
+	mdQuote: "string | number",
+	mdQuoteBorder: "string | number",
+	mdHr: "string | number",
+	mdListBullet: "string | number",
+	toolDiffAdded: "string | number",
+	toolDiffRemoved: "string | number",
+	toolDiffContext: "string | number",
+	syntaxComment: "string | number",
+	syntaxKeyword: "string | number",
+	syntaxFunction: "string | number",
+	syntaxVariable: "string | number",
+	syntaxString: "string | number",
+	syntaxNumber: "string | number",
+	syntaxType: "string | number",
+	syntaxOperator: "string | number",
+	syntaxPunctuation: "string | number",
+	thinkingOff: "string | number",
+	thinkingMinimal: "string | number",
+	thinkingLow: "string | number",
+	thinkingMedium: "string | number",
+	thinkingHigh: "string | number",
+	thinkingXhigh: "string | number",
+	"thinkingMax?": "string | number",
+	bashMode: "string | number",
+	pythonMode: "string | number",
+	statusLineBg: "string | number",
+	statusLineSep: "string | number",
+	statusLineModel: "string | number",
+	statusLinePath: "string | number",
+	statusLineGitClean: "string | number",
+	statusLineGitDirty: "string | number",
+	statusLineContext: "string | number",
+	statusLineSpend: "string | number",
+	statusLineStaged: "string | number",
+	statusLineDirty: "string | number",
+	statusLineUntracked: "string | number",
+	statusLineOutput: "string | number",
+	statusLineCost: "string | number",
+	statusLineSubagents: "string | number",
+});
+
+const spinnerFramesSchema = type("unknown").narrow((value): value is SpinnerFramesOverride => {
+	if (Array.isArray(value)) return value.length >= 1 && value.every(item => typeof item === "string");
+	if (!value || typeof value !== "object") return false;
+	const obj = value as Record<string, unknown>;
+	const status = obj.status;
+	const activity = obj.activity;
+	if (status === undefined && activity === undefined) return false;
+	if (
+		status !== undefined &&
+		(!Array.isArray(status) || status.length < 1 || !status.every(item => typeof item === "string"))
+	) {
+		return false;
+	}
+	if (
+		activity !== undefined &&
+		(!Array.isArray(activity) || activity.length < 1 || !activity.every(item => typeof item === "string"))
+	) {
+		return false;
+	}
+	return true;
+});
+
+const themeJsonSchema = type({
+	"$schema?": "string",
+	name: "string",
+	"vars?": { "[string]": "string | number" },
+	colors: themeColorsSchema,
+	"export?": {
+		"pageBg?": "string | number",
+		"cardBg?": "string | number",
+		"infoBg?": "string | number",
+	},
+	"symbols?": {
+		"preset?": "'unicode' | 'nerd' | 'ascii'",
+		"overrides?": { "[string]": "string" },
+		"spinnerFrames?": spinnerFramesSchema,
+	},
+});
+
+/** Validate a custom theme with the full omptype contract. */
+export function validateThemeJson(value: unknown): ThemeJson {
+	const parsed = themeJsonSchema(value);
+	if (parsed instanceof type.errors) throw new Error(parsed.summary);
+	return parsed as ThemeJson;
+}

package/src/theme/schema.ts

@@ -0,0 +1,168 @@
+import type { SpinnerFramesOverride } from "./symbols";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ColorValue = string | number;
+
+export interface ThemeJson {
+	$schema?: string;
+	name: string;
+	vars?: Record<string, ColorValue>;
+	colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax"> & { thinkingMax?: ColorValue };
+	export?: {
+		pageBg?: ColorValue;
+		cardBg?: ColorValue;
+		infoBg?: ColorValue;
+	};
+	symbols?: {
+		preset?: "unicode" | "nerd" | "ascii";
+		overrides?: Record<string, string>;
+		spinnerFrames?: SpinnerFramesOverride;
+	};
+}
+
+export type ThemeColor =
+	| "accent"
+	| "border"
+	| "borderAccent"
+	| "borderMuted"
+	| "success"
+	| "error"
+	| "warning"
+	| "muted"
+	| "dim"
+	| "text"
+	| "thinkingText"
+	| "userMessageText"
+	| "customMessageText"
+	| "customMessageLabel"
+	| "toolTitle"
+	| "toolOutput"
+	| "mdHeading"
+	| "mdLink"
+	| "mdLinkUrl"
+	| "mdCode"
+	| "mdCodeBlock"
+	| "mdCodeBlockBorder"
+	| "mdQuote"
+	| "mdQuoteBorder"
+	| "mdHr"
+	| "mdListBullet"
+	| "toolDiffAdded"
+	| "toolDiffRemoved"
+	| "toolDiffContext"
+	| "syntaxComment"
+	| "syntaxKeyword"
+	| "syntaxFunction"
+	| "syntaxVariable"
+	| "syntaxString"
+	| "syntaxNumber"
+	| "syntaxType"
+	| "syntaxOperator"
+	| "syntaxPunctuation"
+	| "thinkingOff"
+	| "thinkingMinimal"
+	| "thinkingLow"
+	| "thinkingMedium"
+	| "thinkingHigh"
+	| "thinkingXhigh"
+	| "thinkingMax"
+	| "bashMode"
+	| "pythonMode"
+	| "statusLineSep"
+	| "statusLineModel"
+	| "statusLinePath"
+	| "statusLineGitClean"
+	| "statusLineGitDirty"
+	| "statusLineContext"
+	| "statusLineSpend"
+	| "statusLineStaged"
+	| "statusLineDirty"
+	| "statusLineUntracked"
+	| "statusLineOutput"
+	| "statusLineCost"
+	| "statusLineSubagents";
+
+/** Set of all valid ThemeColor string values for runtime validation */
+const THEME_COLOR_RECORD = {
+	accent: true,
+	border: true,
+	borderAccent: true,
+	borderMuted: true,
+	success: true,
+	error: true,
+	warning: true,
+	muted: true,
+	dim: true,
+	text: true,
+	thinkingText: true,
+	userMessageText: true,
+	customMessageText: true,
+	customMessageLabel: true,
+	toolTitle: true,
+	toolOutput: true,
+	mdHeading: true,
+	mdLink: true,
+	mdLinkUrl: true,
+	mdCode: true,
+	mdCodeBlock: true,
+	mdCodeBlockBorder: true,
+	mdQuote: true,
+	mdQuoteBorder: true,
+	mdHr: true,
+	mdListBullet: true,
+	toolDiffAdded: true,
+	toolDiffRemoved: true,
+	toolDiffContext: true,
+	syntaxComment: true,
+	syntaxKeyword: true,
+	syntaxFunction: true,
+	syntaxVariable: true,
+	syntaxString: true,
+	syntaxNumber: true,
+	syntaxType: true,
+	syntaxOperator: true,
+	syntaxPunctuation: true,
+	thinkingOff: true,
+	thinkingMinimal: true,
+	thinkingLow: true,
+	thinkingMedium: true,
+	thinkingHigh: true,
+	thinkingXhigh: true,
+	thinkingMax: true,
+	bashMode: true,
+	pythonMode: true,
+	statusLineSep: true,
+	statusLineModel: true,
+	statusLinePath: true,
+	statusLineGitClean: true,
+	statusLineGitDirty: true,
+	statusLineContext: true,
+	statusLineSpend: true,
+	statusLineStaged: true,
+	statusLineDirty: true,
+	statusLineUntracked: true,
+	statusLineOutput: true,
+	statusLineCost: true,
+	statusLineSubagents: true,
+} satisfies Record<ThemeColor, true>;
+
+const VALID_THEME_COLORS: ReadonlySet<string> = new Set(Object.keys(THEME_COLOR_RECORD));
+
+/** Check if a string is a valid ThemeColor value */
+export function isValidThemeColor(color: string): color is ThemeColor {
+	return VALID_THEME_COLORS.has(color);
+}
+
+export type ThemeBg =
+	| "selectedBg"
+	| "userMessageBg"
+	| "customMessageBg"
+	| "toolPendingBg"
+	| "toolSuccessBg"
+	| "toolErrorBg"
+	| "statusLineBg";
+
+export type ColorMode = "truecolor" | "256color";

package/src/theme/session-color.ts

@@ -0,0 +1,253 @@
+import { TERMINAL } from "../terminal-capabilities";
+import { hexToOklch, oklchCusp, oklchToHex, relativeLuminance } from "@oh-my-pi/pi-utils";
+
+/**
+ * Derive a stable 32-bit hash from a string using djb2.
+ */
+function nameToHash(name: string): number {
+	let hash = 5381;
+	for (let i = 0; i < name.length; i++) {
+		hash = ((hash << 5) + hash) ^ name.charCodeAt(i);
+		hash = hash >>> 0; // keep 32-bit unsigned
+	}
+	return hash;
+}
+
+/**
+ * Fallback cusp-chroma fraction when the theme accent is unparseable or
+ * near-gray: sits at each hue's gamut cusp at 70% of its peak chroma,
+ * matching a typical vivid accent.
+ */
+const FALLBACK_CUSP_CHROMA_FRACTION = 0.7;
+
+/**
+ * Chroma bounds for the carried theme-accent chroma: the floor keeps the
+ * hash-derived hue readable when the theme accent is near-gray, the ceiling
+ * tempers neon accents so six sessions don't turn the status line into a
+ * highlighter set.
+ */
+const MIN_CHROMA = 0.05;
+const MAX_CHROMA = 0.21;
+
+/** Lightness bounds on dark themes so a carried accent lightness stays visible on dark surfaces. */
+const DARK_MIN_LIGHTNESS = 0.65;
+const DARK_MAX_LIGHTNESS = 0.88;
+
+/** Minimum contrast ratio (WCAG AA large text) between a light-theme accent and its surface. */
+const ACCENT_MIN_CONTRAST = 3;
+
+/**
+ * Largest relative luminance an accent may have while still meeting
+ * {@link ACCENT_MIN_CONTRAST} against a surface of the given luminance.
+ */
+function accentLuminanceCap(surfaceLuminance: number): number {
+	return Math.max(0, (surfaceLuminance + 0.05) / ACCENT_MIN_CONTRAST - 0.05);
+}
+
+/** Minimum angular distance in hue degrees from any theme color to avoid visual collision. */
+const MIN_HUE_DISTANCE = 10;
+/** OKLCH chroma threshold below which hue is meaningless (near-gray). */
+const MIN_CHROMA_FOR_HUE = 0.03;
+
+/** Angular distance between two hue values (0-360). */
+function hueDistance(a: number, b: number): number {
+	const d = Math.abs(a - b);
+	return Math.min(d, 360 - d);
+}
+
+/**
+ * Parse OKLCH hue (0-360) from a hex color string.
+ * Returns undefined for near-gray colors where hue is not meaningful.
+ */
+function hexToHue(hex: string): number | undefined {
+	const { c, h } = hexToOklch(hex);
+	if (!Number.isFinite(h) || c < MIN_CHROMA_FOR_HUE) return undefined;
+	return h;
+}
+
+/**
+ * Find a hue at least {@link MIN_HUE_DISTANCE} from all occupied hues,
+ * walked outward in arc positions so it never leaves the admissible arc.
+ * Returns the hue at `pos` unchanged if no safe hue exists within the arc.
+ */
+function findSafeHue(pos: number, occupied: number[], intervals: readonly HueInterval[]): number {
+	const total = arcLength(intervals);
+	const hueAt = (p: number) => arcToHue(intervals, Math.max(0, Math.min(total - 1, p)));
+	const target = hueAt(pos);
+	if (occupied.length === 0) return target;
+	if (occupied.every(h => hueDistance(target, h) >= MIN_HUE_DISTANCE)) {
+		return target;
+	}
+	for (let d = 1; d < total; d++) {
+		for (const dir of [1, -1]) {
+			const candidate = hueAt(pos + d * dir);
+			if (occupied.every(h => hueDistance(candidate, h) >= MIN_HUE_DISTANCE)) {
+				return candidate;
+			}
+		}
+	}
+	// fallback: keep the original target if no safe spot exists within the arc
+	return target;
+}
+
+/** Inclusive hue interval [start, end] in OKLCH degrees. */
+type HueInterval = readonly [number, number];
+
+/** Number of integer hue positions across all intervals. */
+function arcLength(intervals: readonly HueInterval[]): number {
+	let n = 0;
+	for (const [a, b] of intervals) n += b - a + 1;
+	return n;
+}
+
+/** Map an arc position (`0..arcLength-1`) to its hue degree. */
+function arcToHue(intervals: readonly HueInterval[], pos: number): number {
+	let p = pos;
+	for (const [a, b] of intervals) {
+		const n = b - a + 1;
+		if (p < n) return a + p;
+		p -= n;
+	}
+	return intervals[intervals.length - 1]?.[1] ?? 0;
+}
+
+/**
+ * Dark themes draw hues from the full wheel, restricted to hues whose
+ * sRGB gamut cusp is reachable under {@link DARK_MAX_LIGHTNESS}. A hue whose
+ * vividness peak needs more lightness than the cap can only render as a
+ * darkened version of itself, and yellow (cusp L ≈ 0.97) is the one hue
+ * that shifts category when darkened — to olive/mustard — so the derivation
+ * excludes the yellow/chartreuse core (≈94–138°) and the over-light cyan
+ * peak (≈158–200°) for every theme. Collisions with theme-semantic hues are
+ * handled per-theme by {@link findSafeHue}, not by narrowing the arc.
+ */
+const DARK_HUE_INTERVALS: readonly HueInterval[] = (() => {
+	const intervals: Array<[number, number]> = [];
+	let start = -1;
+	for (let h = 0; h <= 360; h++) {
+		if (h < 360 && oklchCusp(h).l <= DARK_MAX_LIGHTNESS) {
+			if (start < 0) start = h;
+		} else if (start >= 0) {
+			intervals.push([start, h - 1]);
+			start = -1;
+		}
+	}
+	return intervals;
+})();
+
+/**
+ * Light themes keep a declared cool band (cyan → blue → purple); lightness
+ * there is governed by the contrast bisection against the surface, not the
+ * dark cap, and darkened cool hues stay categorical (dark blue is blue).
+ */
+const LIGHT_HUE_INTERVALS: readonly HueInterval[] = [[195, 330]];
+
+/** Theme-derived inputs for {@link getSessionAccentHex}; see `Theme.sessionAccentInputs`. */
+export interface SessionAccentTheme {
+	/** Theme accent hex; the session accent adopts its OKLCH lightness and chroma. */
+	accentHex: string;
+	/** Major theme color hexes checked for hue collision. */
+	colorHexes: string[];
+	/** WCAG luminance of the status-line surface on light themes; undefined on dark themes. */
+	surfaceLuminance?: number;
+}
+
+/**
+ * Derive a stable CSS hex accent color from a session name and the active theme.
+ *
+ * The session name hash picks only the **hue**, from a dark/light-specific
+ * hue arc so the accent feels natural for the theme type: the full wheel on
+ * dark minus hues whose vividness peak is unreachable under the dark
+ * lightness cap (see {@link DARK_HUE_INTERVALS}); cool on light. **Lightness and chroma are carried over from the theme's own accent
+ * color**, normalized to the sRGB gamut cusp of each hue: the lightness at
+ * which a hue peaks in chroma varies wildly (yellow ≈ 0.97, blue ≈ 0.45), so
+ * absolute OKLCH lightness cannot transfer between hues — a pink accent's
+ * l≈0.67 re-hued to yellow is mustard, not vivid yellow. Instead the
+ * accent's position relative to its own hue's cusp (lightness side and
+ * chroma fraction) is re-applied at the target hue's cusp, so the session
+ * accent inherits the theme's vividness at every hue. The hue is checked against all
+ * theme color hues and shifted if it lands within {@link MIN_HUE_DISTANCE}
+ * of one, but the shift walks along the admissible arc so it never drifts
+ * into an unrelated or excluded part of the spectrum.
+ *
+ * On dark themes (`surfaceLuminance` undefined) the carried lightness is
+ * clamped to stay visible on dark surfaces. On light themes it is reduced
+ * until the accent's luminance clears {@link ACCENT_MIN_CONTRAST} against
+ * the actual surface it renders on — legible on near-white *and* mid-light
+ * backgrounds.
+ *
+ * @param name — session name for per-session uniqueness.
+ * @param theme — accent hex, collision colors, and surface luminance of the active theme.
+ */
+export function getSessionAccentHex(name: string, theme: SessionAccentTheme): string {
+	// 1. Pick hue range based on theme mode
+	const isDark = theme.surfaceLuminance === undefined;
+	const intervals = isDark ? DARK_HUE_INTERVALS : LIGHT_HUE_INTERVALS;
+
+	// 2. Session name picks a position along the admissible arc
+	const pos = nameToHash(name) % arcLength(intervals);
+
+	// 3. Shift away if too close to any theme color — stays within the arc
+	const themeHues = theme.colorHexes.map(hexToHue).filter((h): h is number => h !== undefined);
+	const targetHue = findSafeHue(pos, themeHues, intervals);
+
+	// 4. Carry the theme accent's perceived weight, re-normalized to the
+	//    target hue's gamut cusp (see doc comment above).
+	const accent = hexToOklch(theme.accentHex);
+	const usable =
+		Number.isFinite(accent.l) &&
+		Number.isFinite(accent.c) &&
+		Number.isFinite(accent.h) &&
+		accent.c >= MIN_CHROMA_FOR_HUE;
+	const target = oklchCusp(targetHue);
+	let lightness: number;
+	let chromaFraction: number;
+	if (usable) {
+		const source = oklchCusp(accent.h);
+		// Preserve which side of the cusp the accent sits on and how far along:
+		// below-cusp accents map proportionally into [0, targetCusp.l], above-cusp
+		// (pastel) accents into [targetCusp.l, 1].
+		lightness =
+			accent.l <= source.l
+				? (accent.l / source.l) * target.l
+				: target.l + ((accent.l - source.l) / (1 - source.l)) * (1 - target.l);
+		chromaFraction = accent.c / source.c;
+	} else {
+		lightness = target.l;
+		chromaFraction = FALLBACK_CUSP_CHROMA_FRACTION;
+	}
+	const chroma = Math.max(MIN_CHROMA, Math.min(MAX_CHROMA, chromaFraction * target.c));
+
+	// 5. Lightness/contrast — clamped visible on dark, bisected for AA on light
+	if (theme.surfaceLuminance === undefined) {
+		const l = Math.max(DARK_MIN_LIGHTNESS, Math.min(DARK_MAX_LIGHTNESS, lightness));
+		return oklchToHex({ l, c: chroma, h: targetHue });
+	}
+
+	const cap = accentLuminanceCap(theme.surfaceLuminance);
+	const top = oklchToHex({ l: lightness, c: chroma, h: targetHue });
+	if ((relativeLuminance(top) ?? 0) <= cap) return top;
+
+	// Bisect lightness: `lo` always yields luminance <= cap, `hi` always above it.
+	let lo = 0;
+	let hi = lightness;
+	for (let i = 0; i < 20; i++) {
+		const mid = (lo + hi) / 2;
+		if ((relativeLuminance(oklchToHex({ l: mid, c: chroma, h: targetHue })) ?? 0) > cap) {
+			hi = mid;
+		} else {
+			lo = mid;
+		}
+	}
+	return oklchToHex({ l: lo, c: chroma, h: targetHue });
+}
+
+/**
+ * Convert a hex accent color to an ANSI foreground escape sequence matching
+ * the detected terminal color depth.
+ * Returns `undefined` if `hex` is nullish or Bun.color conversion fails.
+ */
+export function getSessionAccentAnsi(hex: string | undefined): string | undefined {
+	if (!hex) return undefined;
+	return Bun.color(hex, TERMINAL.trueColor ? "ansi-16m" : "ansi-256") ?? undefined;
+}