@xzzpig/pi-starline 0.7.1 → 0.7.2

package/FORK-CHANGELOG.md

@@ -1,5 +1,12 @@
 # Fork release notes
 
+## 0.7.2 — pill text contrast on terminal-owned palettes
+
+- Pick the pill text colour from the 256-colour cube (`38;5;16` black, `38;5;231` white) instead of the basic ANSI codes `30`/`97`. The basic codes belong to the terminal theme: herdr renders ANSI black as `#616161`, which left the automatic "dark" text at 1.76:1 on the muted pill background and 2.62:1 on the model pill. The cube's black and white are fixed by the standard, so contrast now holds in any palette (5.4–9.4:1 for the footer's default backgrounds).
+- The change is two constants plus their comment in `extensions/starline/pill.ts`. It covers pill bodies, the thin divider drawn between same-background pills, and the bubble's selected row, all of which share `contrastTextSgr()`. Backgrounds, separators, caps, widths and click targets are unchanged, and an explicit `fg:` in `colors.*` still wins.
+- Backgrounds that land on the terminal's own 16 colours are painted in reverse video (`\x1b[49m` + the palette colour as foreground + `\x1b[7m`): the palette colour stays the background and the text becomes the terminal's default background, a pair the palette is designed to keep readable. Only the terminal knows those RGBs — the standard table turned `48;5;3` into "dark yellow" when herdr paints it `#61AFEE`, which is why the contrast guess cannot be trusted there. Measured on the same pills: 2.62:1 → 8.61:1 (model/cwd) and 3.07:1 → 10.11:1 (cost); known-RGB backgrounds keep the cube black/white and land at 9.12:1. The predicate and SGR builders live in the fork-only `extensions/starline/fork-pill-legibility.ts`, with one seam each in `pill.ts` and `pill-bubble.ts`.
+- Fork coverage lives in `test/fork-pill-contrast.test.ts`; `subtrees/pi-starline.json` records the sync-time re-apply. Drop the constants divergence once upstream stops deriving legibility from the terminal's basic palette, and the reverse-video seam once upstream handles terminal-owned backgrounds itself.
+
 ## 0.7.1 — Pi cursor compatibility
 
 - Restore `underline` and `terminal` editor cursor styles on Pi 1.2 and later while preserving the existing Pi 1.1 cursor path.

package/extensions/starline/fork-pill-legibility.ts

@@ -0,0 +1,52 @@
+/**
+ * Fork-only legibility helpers for pill text.
+ *
+ * A pill's text colour is normally picked from the background's RGB, but the
+ * terminal owns the RGB of its own 16 colours: `38;5;3` is whatever the theme
+ * paints for palette slot 3 (herdr: `#61AFEE`), not the standard table's olive.
+ * Guessing from the standard table turned "light blue" into "dark yellow" and
+ * picked white text for a light pill.
+ *
+ * For those backgrounds the fork paints the text with reverse video instead:
+ * the palette colour becomes the background and the terminal's own default
+ * background becomes the text. A palette is designed to keep its colours
+ * readable against that default background, so the pair stays legible without
+ * the program knowing either RGB.
+ *
+ * See FORK-CHANGELOG.md; `test/fork-pill-contrast.test.ts` covers it.
+ */
+
+import { toForegroundSgr } from "./style";
+
+const DEFAULT_BG = "\x1b[49m";
+const REVERSE = "\x1b[7m";
+
+/**
+ * True when the background is one of the terminal's own 16 colours, whose RGB
+ * only the terminal knows. The 256-colour cube (`48;5;16`+) and truecolor are
+ * fixed by the standard, so those stay knowable.
+ */
+export function isTerminalOwnedBackground(background: string): boolean {
+	if (/^\x1b\[(4[0-7]|10[0-7])m$/.test(background)) return true;
+	const indexed = /^\x1b\[48;5;(\d{1,3})m$/.exec(background);
+	return indexed ? Number(indexed[1]) < 16 : false;
+}
+
+/**
+ * True when the spec names a foreground colour itself (`fg:…`). Such a pill
+ * keeps the colour the user asked for: reverse video would replace it.
+ */
+export function hasExplicitForeground(spec: string): boolean {
+	return /(^|\s)fg:/i.test(spec.trim());
+}
+
+/**
+ * The SGR that paints text on a terminal-owned background, or undefined when
+ * the background is knowable (the caller picks a contrast colour instead) or
+ * cannot be turned into a foreground colour.
+ */
+export function reverseVideoSgr(background: string): string | undefined {
+	if (!isTerminalOwnedBackground(background)) return undefined;
+	const foreground = toForegroundSgr(background);
+	return foreground ? `${DEFAULT_BG}${foreground}${REVERSE}` : undefined;
+}

package/extensions/starline/pill-bubble.ts

@@ -36,6 +36,7 @@ import type {
 	PillBubbleHandle,
 	PillBubbleSource,
 } from "../../types/pill-api";
+import { reverseVideoSgr } from "./fork-pill-legibility";
 import { requestPointerShape } from "./mouse/pointer-shape";
 import { contrastTextSgr } from "./pill";
 import { resolveBackgroundSgr, type ThemeLike, toForegroundSgr } from "./style";
@@ -211,7 +212,10 @@ function buildBubble(input: {
 	const width = Math.max(8, Math.floor(input.width));
 	const innerWidth = Math.max(1, width - 4);
 	const background = input.background;
-	const foreground = input.foreground || contrastTextSgr(background);
+	// A background the terminal owns has no knowable RGB, so its row is painted in
+	// reverse video: palette colour behind, terminal default background as text.
+	const reverse = input.foreground ? "" : (reverseVideoSgr(background) ?? "");
+	const foreground = input.foreground || (reverse ? "" : contrastTextSgr(background));
 	// The outline is the pill's colour as a foreground on the terminal's own
 	// background; nothing inside the box is filled.
 	const line = `${DEFAULT_BG}${toForegroundSgr(background) ?? ""}`;
@@ -222,7 +226,7 @@ function buildBubble(input: {
 		// underline covers the words and not the margin around them.
 		`${side} ${style}${text}${STYLE_OFF}${" ".repeat(Math.max(0, innerWidth - visibleWidth(text)))} ${side}`;
 	const selectedRow = (text: string) =>
-		`${side}${background}${foreground} ${text}${" ".repeat(
+		`${side}${reverse || background}${foreground} ${text}${" ".repeat(
 			Math.max(0, innerWidth - visibleWidth(text)),
 		)} ${RESET}${side}`;
 

package/extensions/starline/pill.ts

@@ -13,6 +13,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import type { ColorSource, ColorSpec } from "./config";
 import type { ExtensionStatusSegment } from "./extension-status";
+import { hasExplicitForeground, reverseVideoSgr } from "./fork-pill-legibility";
 import {
 	EXTENSION_STATUS_PREFIX,
 	EXTENSION_STATUS_SEGMENT,
@@ -25,9 +26,13 @@ const RESET = "\x1b[0m";
 const BOLD = "\x1b[1m";
 const DEFAULT_BG = "\x1b[49m";
 
-/** Text colours are the basic named codes, which every terminal renders correctly. */
-const TEXT_DARK = "\x1b[30m";
-const TEXT_LIGHT = "\x1b[97m";
+/**
+ * Text colours are the 256-colour cube's black and white (16/231), whose values
+ * the standard fixes. The basic named codes are not fixed: a terminal theme may
+ * map ANSI black to a mid grey, which leaves mid-tone pills hard to read.
+ */
+const TEXT_DARK = "\x1b[38;5;16m";
+const TEXT_LIGHT = "\x1b[38;5;231m";
 
 /** Catppuccin surface1 — the neutral for segments whose spec names no colour. */
 const NEUTRAL_BG = "\x1b[48;2;69;71;90m";
@@ -164,6 +169,8 @@ type PreparedPill = {
 	bg: string;
 	fg: string;
 	bold: boolean;
+	/** Body SGR for a terminal-owned background, which paints text in reverse. */
+	reverse: string;
 };
 
 const XTERM_CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
@@ -250,19 +257,25 @@ function prepare(
 		if (!text || visibleWidth(text) === 0) continue;
 
 		if (input.keepStyling) {
-			pills.push({ key: input.key, text, bg: neutral, fg: "", bold: false });
+			pills.push({ key: input.key, text, bg: neutral, fg: "", bold: false, reverse: "" });
 			continue;
 		}
 
 		const resolved = resolveColorSpec(theme, source, input.spec);
 		const bg = resolved.bg ?? resolveBackgroundSgr(theme, source, input.spec) ?? neutral;
-		// An explicit fg: in the spec wins; otherwise pick for legibility.
+		// An explicit fg: in the spec wins. A background the terminal owns has no
+		// knowable RGB, so reverse video hands both sides to the palette instead of
+		// guessing from the standard table.
+		const explicitFg = hasExplicitForeground(input.spec);
+		const reverse = explicitFg ? "" : (reverseVideoSgr(bg) ?? "");
+		const specFg = explicitFg || (resolved.bg && resolved.fg) ? resolved.fg : undefined;
 		pills.push({
 			key: input.key,
 			text,
 			bg,
-			fg: resolved.bg && resolved.fg ? resolved.fg : contrastTextSgr(bg),
+			fg: reverse ? "" : (specFg ?? contrastTextSgr(bg)),
 			bold: config.bold || resolved.bold,
+			reverse,
 		});
 	}
 
@@ -319,7 +332,7 @@ export function renderPillBar(
 		// The left cap opens the bar in the first pill's colour, so it belongs to it.
 		const startColumn = index === 0 ? capStart : column;
 		const bodyStartColumn = column;
-		emit(`${pill.bg}${pill.fg}${pill.bold ? BOLD : ""} ${pill.text} ${RESET}`);
+		emit(`${pill.reverse || pill.bg}${pill.fg}${pill.bold ? BOLD : ""} ${pill.text} ${RESET}`);
 		const bodyEndColumn = column;
 
 		const next = pills[index + 1];
@@ -329,7 +342,8 @@ export function renderPillBar(
 			// default to the same theme colour, which merged them into one blob.
 			// Fall back to the thin divider in the text colour, which stays visible.
 			if (separator && pill.bg === next.bg) {
-				emit(`${pill.bg}${pill.fg || contrastTextSgr(pill.bg)}${THIN_SEPARATOR}${RESET}`);
+				const dividerFg = pill.reverse ? "" : pill.fg || contrastTextSgr(pill.bg);
+				emit(`${pill.reverse || pill.bg}${dividerFg}${THIN_SEPARATOR}${RESET}`);
 			} else if (separator) {
 				const arrowFg = toForegroundSgr(pill.bg);
 				// Without a usable foreground the arrow would be invisible; letting the

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@xzzpig/pi-starline",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "A Starship-inspired statusline and Opencode-style TUI for Pi.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Andy8647/pi-starline.git"
+    "url": "git+https://github.com/xzzpig/pi-extensions.git"
   },
   "homepage": "https://github.com/Andy8647/pi-starline#readme",
   "bugs": {