@bismawy/pi-arnative 0.4.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.5.2] - 2026-10-13
+
+### Fixed
+- Restored the footer's two-tone labels. `0.5.1` moved the label colour onto `softOf(accent)`, which softens the *accent* hue, so cwd/branch/clock/status text inherited the accent (pink) instead of the border-accent (blue) tier and the footer collapsed into a single hue (`extensions/footer.ts`).
+- Added `vars.secondarySoft` to all 11 themes, softened from the same value the `borderAccent` token resolves to (L 0.82, chroma × 0.18, hue kept), and `softSecondaryOf` in `lib/ansi.ts` to derive the identical value at runtime — `vars` names are not addressable via `fg()`, and Pi 1.2 rejects custom `colors` keys, so the declared and derived values must be produced by one recipe.
+- Routed the header's model/thinking/token text, tool bodies, list rows and the usage dashboard onto the label tier. Icons, marks and the logo's second tone stay on the accent tier, so each line keeps its two tones (`extensions/section-headers.ts`, `extensions/tools.ts`, `extensions/usage.ts`, `extensions/arnative.ts`, `extensions/ui-render-tweaks.ts`).
+
+### Added
+- `soften()` is now shared by the generator and the runtime, and `extensions/ui-render-tweaks.ts` asserts every declared `*Soft` var equals its derived value — a drifting or rogue soft colour fails `npm test` instead of shipping (`themes/gen-themes.mjs`, `lib/ansi.ts`).
+- Behavioral test pinning the two-tone rule: labels take the border-accent hue, icons keep the accent hue (`test/footer-minimal.test.ts`).
+
+### Notes
+- Label colour is deliberately softer than the pre-0.5.1 `#05dee7`. `SOFT_CHROMA_SCALE` in `lib/ansi.ts` is the single knob: `0.18` gives `#b2c9ca` on cyberpunk, `0.30` gives `#b2dadc`, `0.50` gives `#9adfe3`. Changing it regenerates all 11 themes and the guard forces them to stay in sync.
+
+## [0.5.1] - 2026-10-13
+
+### Fixed
+- Restored all 11 arnative themes on Pi 1.2.0, which validates the `colors` object with `additionalProperties: false` and rejected the whole theme — "must not have additional properties" followed by "Theme not found" (`lib/ansi.ts`, `themes/gen-themes.mjs`, `themes/*.json`, `extensions/ui-render-tweaks.ts`). Arnative's own colors (`accentSoft`, `primary`, `secondary`, `primarySoft`, `secondarySoft`) moved from `colors` to `vars`.
+- Kept the two-tone soft tier instead of collapsing it to grey: `softOf` replaces `accentSoftOf` and derives the soft accent from the resolved `accent` color when `fg("accentSoft")` throws, so the header logo, tab labels, model line, footer labels, tool titles and the usage dashboard keep their tint (`lib/ansi.ts`).
+- Updated `$schema` in every theme and the generator from the raw GitHub `theme-schema.json` path to the published `https://pi.dev/schemas/theme.schema.json` (`themes/gen-themes.mjs`, `themes/*.json`).
+- Replaced the footer's raw `fg("accentSoft")` probe with the shared painter and mapped `primary`/`secondary` onto the official tokens they carry (`mdHeading`, `borderAccent`), since Pi 1.2 rejects custom `colors` keys (`extensions/footer.ts`).
+- Mapped the usage dashboard's name/value/arrow colors off `accentSoft` onto the shared soft painter and plain `dim`/`text`, keeping provider rows distinguishable (`extensions/usage.ts`).
+- Added a self-check that fails when a theme puts a non-schema key in `colors`, so a rogue token breaks `npm test` instead of the user's startup (`extensions/ui-render-tweaks.ts`).
+
+### Notes
+- `0.5.0` is intentionally skipped on the npm registry. It was tagged and merged, but never published, and its themes are the ones Pi 1.2.0 rejects. `0.5.1` carries everything from v0.5.0 plus this fix. The tag stays in the history; install from npm and you get `0.5.1`.
+
+## [0.5.0] - 2026-10-13
+
+### Added
+- Extended theme token hierarchy in `vars` with `primary`, `primarySoft`, `secondary`, and `secondarySoft` across all 11 themes (`themes/gen-themes.mjs`), ensuring unique hex mappings and full perceptual OKLCH color space discipline.
+- Tri-color multi-palette overhauls for expressive themes (`arnative-cyberpunk`, `arnative-synthwave`, `arnative-dracula`, `arnative-gruvbox`, and `arnative-nord`), mapping `mdHeading` to `primary` and `borderAccent`/`mdCode` to `secondary`.
+- Footer multi-color pairing (`extensions/footer.ts`): paired vibrant `accent` icons with readable `secondarySoft` labels and highlighted the model name with `primary`.
+
+### Changed
+- Increased message bubble background lightness (`surfaceMsg` / `userMessageBg`) on `arnative-cyberpunk`, `arnative-matrix`, and `arnative-synthwave` to 24% (`oklch(24% 0.035 ...)`) to ensure container boundaries remain clearly defined against pitch-black terminal canvases.
+
+### Fixed
+- Fixed parenthetical suffix per-row dimming in `/arnative` → **Animations** so `(system)` on `Pi (system)` renders softly in `dim` even when descriptive frame notes are present (`extensions/arnative.ts`).
+- Fixed inline image preview layout spacing by dropping the redundant spacer gap between the tool execution box and the image payload (`extensions/tools.ts`).
+
 ## [0.4.0] - 2026-10-12
 
 ### Added

package/README.md

@@ -113,10 +113,18 @@ Theme definitions are generated via `themes/gen-themes.mjs` using OKLCH color ma
 ```bash
 npm test        # Run unit tests and self-checks
 npm run themes  # Rebuild all theme variants
+npm run preview # Live preview the working tree in your own Pi (stamps a pushable commit)
 ```
 
 Pre-publish verification and tag validation are enforced via `scripts/release-check.mjs`.
 
+**Local-first push gate:** the global pre-push hook rejects any branch push whose commit
+carries no live-preview stamp, so a fix cannot reach GitHub unseen. `npm run preview`
+launches Pi with this working tree and writes `.git/arnative-preview` for the exact commit
+that was shown; editing `extensions/`, `lib/`, `themes/`, or `package.json` afterwards
+invalidates it and the hook asks for a fresh preview. The preview must run on a clean tree
+— commit or stash first.
+
 </details>
 
 ## License

package/extensions/arnative.ts

@@ -7,7 +7,7 @@
  */
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth, type AutocompleteItem, type Component } from "@earendil-works/pi-tui";
-import { accentSoftOf, stripAnsi, thinkingColorOf } from "../lib/ansi.ts";
+import { softSecondaryOf, stripAnsi, thinkingColorOf } from "../lib/ansi.ts";
 import { renderScreen, screenTitle, type ScreenText } from "../lib/box.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { markedLabels } from "../lib/format.ts";
@@ -172,7 +172,7 @@ export class ListPicker implements Component {
 	render(width: number): string[] {
 		const th = this.theme;
 		const bold = th.bold ?? ((t: string) => `\x1b[1m${t}\x1b[22m`);
-		const soft = accentSoftOf(th);
+		const soft = softSecondaryOf(th);
 		const edge = (text: string) => this.edge(text);
 		const column = Math.max(0, ...this.rows.map((r) => visibleWidth(r.label)));
 		const body: string[] = [];
@@ -183,7 +183,7 @@ export class ListPicker implements Component {
 			const pad = " ".repeat(Math.max(0, column - visibleWidth(item.label)));
 			const note = item.note ? `${th.fg("dim", ROW_DIVIDER)}${th.fg("dim", item.note)}` : "";
 			// Extract parenthetical suffix to render softly
-			const suffix = item.note ? "" : /(\(.*\))$/.exec(item.label)?.[1] ?? "";
+			const suffix = /(\(.*\))$/.exec(item.label)?.[1] ?? "";
 			const head = suffix ? item.label.slice(0, item.label.length - suffix.length) : item.label;
 			const tail = suffix ? th.fg("dim", suffix) : "";
 			const content = `${isSelected ? th.fg("accent", "→ ") : "  "}${paint(head)}${tail}${pad}${note}`;
@@ -673,5 +673,16 @@ if (isMain(import.meta.url)) {
 	assert(footerLines.some((l) => l.includes("Arnative (Minimal)")), "footers picker lists the minimal preset");
 	assert(footerLines.filter((l) => l.includes("Arnative (")).length === 2, "both arnative footer presets are selectable");
 
+	// Animations picker: "Pi (system)" carries a note AND renders "(system)" in dim
+	const animPicker = new ListPicker(
+		{ fg: (c, t) => `<${c}>${t}</${c}>`, bold: (t) => `<bold>${t}</bold>` },
+		animationRows(),
+		"Pi (system)",
+		{ preview: () => {}, revert: () => {}, done: () => {}, requestRender: () => {} },
+		ANIMATIONS_PICKER_TEXT,
+	);
+	const animLines = animPicker.render(120);
+	assert(animLines.some((l) => l.includes("Pi ") && l.includes("<dim>(system)</dim>")), "animations picker dims (system)");
+
 	console.log("arnative.ts self-check OK");
 }

package/extensions/footer.ts

@@ -11,7 +11,7 @@ import { execFile } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { stripAnsi } from "../lib/ansi.ts";
+import { softOf, softSecondaryOf, stripAnsi } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { capitalize, markedLabels, modelDisplayParts } from "../lib/format.ts";
 import { IS_WINDOWS_LIKE, SHORTCUT_RELOAD, SHORTCUT_TOGGLE_FOOTER } from "../lib/shortcuts.ts";
@@ -398,6 +398,7 @@ function formatModelName(
 	thinkingLevel: string | undefined,
 	acc: (t: string) => string,
 	soft: (t: string) => string,
+	primary: (t: string) => string,
 	dim: (t: string) => string,
 ): string {
 	if (!model) return dim("No Model");
@@ -405,7 +406,7 @@ function formatModelName(
 	const provStr = provider ? ` ${dim(`(${provider})`)}` : "";
 	const capThinking = thinkingLevel && thinkingLevel !== "off" ? capitalize(thinkingLevel) : "";
 	const thinkStr = capThinking ? `${acc("\uee9c")} ${soft(capThinking)} ${dim("·")} ` : "";
-	return `${thinkStr}${acc(name)}${provStr}`;
+	return `${thinkStr}${primary(name)}${provStr}`;
 }
 
 // Footer is a single line: a deep cwd (`/Users/x/Workspace/personal/proj`)
@@ -888,14 +889,12 @@ export default function (pi: ExtensionAPI) {
 							const acc = (text: string) => theme.fg("accent", text);
 							const dim = (text: string) => theme.fg("dim", text);
 							const fgAny = theme.fg.bind(theme) as (color: string, text: string) => string;
-							let softName = "accent";
-							try {
-								fgAny("accentSoft", "");
-								softName = "accentSoft";
-							} catch {
-								// fallback
-							}
-							const soft = (text: string) => fgAny(softName, text);
+							// `accentSoft`/`secondarySoft` are vars-only tokens on Pi 1.2+, so both soft tiers
+							// are resolved through the shared painters instead of a raw fg() probe. Icons keep
+							// `accent`; the cwd/branch/clock/status text takes the border-accent tier, so the
+							// footer stays two-toned instead of the text inheriting the accent hue.
+							const soft = softOf(theme as never);
+							const softLabel = softSecondaryOf(theme as never);
 							// Diff colors: the same theme slots pi uses for a diff body, with the
 							// plain soft color as fallback for a theme that omits them.
 							const colorOr = (name: string, fallback: (t: string) => string) => (t: string) => {
@@ -905,6 +904,10 @@ export default function (pi: ExtensionAPI) {
 									return fallback(t);
 								}
 							};
+							// `primary` is a var, not a token (Pi 1.2+ rejects custom `colors` keys); its
+							// arnative carrier is the official token it maps to.
+							const primary = colorOr("mdHeading", acc);
+							const secondarySoft = softLabel;
 							const diffAdd = colorOr("toolDiffAdded", soft);
 							const diffDel = colorOr("toolDiffRemoved", soft);
 							const sep = dim(" | ");
@@ -914,7 +917,7 @@ export default function (pi: ExtensionAPI) {
 							const paused = clock.idle();
 							idlePauseShown = paused;
 							const clockIcon = paused ? dim("\uf017") : acc("\uf017");
-							const clockText = paused ? dim(durationStr) : soft(durationStr);
+							const clockText = paused ? dim(durationStr) : secondarySoft(durationStr);
 							const pDuration = `${clockIcon} ${clockText}${diffStat ? `${sep}${diffStat}` : ""}`;
 							const cwdShort = shortenCwd(cwd);
 							const isMinimal = activeFooterPreset() === "Arnative (Minimal)";
@@ -922,10 +925,10 @@ export default function (pi: ExtensionAPI) {
 							const arrow = (expanded: boolean) => dim(expanded ? " ▼" : " ▲");
 							let left1 = `${acc("\uf07b")} ${dim(cwdShort)}${sep}${pDuration}`;
 							if (git) {
-								left1 = `${acc("\uf07b")} ${dim(cwdShort)}${sep}${pDuration}${gitParts(git, acc, soft).map((p) => `${sep}${p}`).join("")}`;
+								left1 = `${acc("\uf07b")} ${dim(cwdShort)}${sep}${pDuration}${gitParts(git, acc, secondarySoft).map((p) => `${sep}${p}`).join("")}`;
 							}
 							if (isMinimal) left1 += arrow(open.left);
-							const right1 = formatModelName(currentModel, currentThinkingLevel, acc, soft, dim) + (isMinimal ? arrow(open.right) : "");
+							const right1 = formatModelName(currentModel, currentThinkingLevel, acc, secondarySoft, primary, dim) + (isMinimal ? arrow(open.right) : "");
 
 							const statuses: ReadonlyMap<string, string> = (() => {
 								try {
@@ -942,9 +945,9 @@ export default function (pi: ExtensionAPI) {
 									let rest = (idx >= 0 ? clean.slice(idx) : clean).replace(/\uFFFD/g, "").trim();
 									rest = rest.replace(/[\p{Extended_Pictographic}\uFE0F\u200D\u2800-\u28FF]/gu, "").replace(/\s{2,}/g, " ").trim();
 									const m = rest.match(/MCP:\s*\d+\s*servers?\s*enabled/i);
-									return `${acc("\uf233")} ${soft(m ? m[0] : rest || "MCP")}`;
+									return `${acc("\uf233")} ${secondarySoft(m ? m[0] : rest || "MCP")}`;
 								}
-								if (s.includes("ponytail")) return ponytailStatusLine(s, acc, dim, soft);
+								if (s.includes("ponytail")) return ponytailStatusLine(s, acc, dim, secondarySoft);
 								if (s.includes("jev-eye")) {
 									const isOff = s.includes("OFF") || s.includes("○");
 									const isReview = /REVIEW/i.test(s);
@@ -959,11 +962,11 @@ export default function (pi: ExtensionAPI) {
 									const label = isOff ? "OFF" : isReview ? "REVIEW" : "ON";
 									// Two spaces: \uedcf's ink is wider than MCP's \uf233 or ponytail's \uef04,
 									// so it needs the extra cell to clear the label.
-									return `${acc("\uedcf")}  ${soft("Jev:")} ${bullet} ${soft(label)}`;
+									return `${acc("\uedcf")}  ${secondarySoft("Jev:")} ${bullet} ${secondarySoft(label)}`;
 								}
 								let clean = stripAnsi(s);
 								clean = clean.replace(/\uFFFD/g, "").replace(/\?{1,2}\s*/g, "");
-								return soft(clean.trim());
+								return secondarySoft(clean.trim());
 							};
 
 							const groups: string[] = [];
@@ -976,12 +979,12 @@ export default function (pi: ExtensionAPI) {
 							const opt = parseOptimizer(rawCache);
 							let usageStr = "";
 							try {
-								usageStr = getUsage(ctx, acc, soft);
+								usageStr = getUsage(ctx, acc, secondarySoft);
 							} catch {
 								// fallback
 							}
-							const speedStr = latestSpeed !== null && latestSpeed > 0 ? `${acc("\udb81\udcc5")} ${soft(`${latestSpeed.toFixed(1)} tok/s`)}` : "";
-							const metricCells = [speedStr, opt ? `${acc("\udb80\udf5b")} ${soft(opt)}` : "", usageStr].filter(Boolean);
+							const speedStr = latestSpeed !== null && latestSpeed > 0 ? `${acc("\udb81\udcc5")} ${secondarySoft(`${latestSpeed.toFixed(1)} tok/s`)}` : "";
+							const metricCells = [speedStr, opt ? `${acc("\udb80\udf5b")} ${secondarySoft(opt)}` : "", usageStr].filter(Boolean);
 
 							// Fixed 3-row grid: head (cwd/model), then statuses and metrics each
 							// wrapped inside their half of the width. Arnative (Minimal) starts collapsed
@@ -1042,11 +1045,7 @@ export default function (pi: ExtensionAPI) {
 						try {
 							const th = this.getActiveTheme();
 							if (!th) return text;
-							try {
-								return th.fg("accentSoft", text);
-							} catch {
-								return th.fg("muted", text);
-							}
+							return softSecondaryOf(th as never)(text);
 						} catch {
 							return text;
 						}
@@ -1428,7 +1427,7 @@ if (isMain(import.meta.url)) {
 	resetPresetCache();
 
 	// Self-check: formatModelName thinking icon
-	const fmnRes = formatModelName({ id: "claude-3-7-sonnet", name: "Sonnet" }, "low", (s) => s, (s) => s, (s) => s);
+	const fmnRes = formatModelName({ id: "claude-3-7-sonnet", name: "Sonnet" }, "low", (s) => s, (s) => s, (s) => s, (s) => s);
 	assert(fmnRes.includes("\uee9c Low"), "formatModelName includes \\uee9c Low thinking indicator");
 
 	// Self-check: the ponytail glyph. \uef51 carries no outline in the Windows Nerd Font

package/extensions/section-headers.ts

@@ -33,7 +33,7 @@ import {
 } from "@earendil-works/pi-tui";
 import type { BoxTheme } from "../lib/box.ts";
 import { BRAND, renderBoxLines } from "../lib/box.ts";
-import { getActiveTheme, setActiveTheme, stripAnsi, themeOf } from "../lib/ansi.ts";
+import { getActiveTheme, setActiveTheme, softOf, softSecondaryOf, stripAnsi, themeOf } from "../lib/ansi.ts";
 import { capitalize, expandKeyName, modelDisplayParts } from "../lib/format.ts";
 import { SHORTCUT_NEW_SESSION, SHORTCUT_NEXT_TAB, SHORTCUT_RELOAD } from "../lib/shortcuts.ts";
 import { HEADER_PRESET_KEY as HEADER_PRESET_CONFIG_KEY, loadChoice, saveChoice } from "../lib/preset-store.ts";
@@ -78,6 +78,34 @@ export function fgFirst(th: Themeish, names: string[], text: string): string {
 	return text;
 }
 
+/**
+ * Painter for the header's soft *accent* tier — the logo mark's second tone, paired with
+ * the accent `P`. Keeps the mark in one hue family instead of blue.
+ *
+ * Pi 1.2.0 rejects a custom `accentSoft` key in `colors`, so `fgFirst(["accentSoft", …])`
+ * silently degrades to plain text there and the two-tone look flattens. `softOf` derives
+ * the same tint from the resolved accent; a theme that genuinely defines `accentSoft`
+ * still wins first.
+ */
+export function softFirst(th: Themeish, fallbacks: string[], text: string): string {
+	return softOnTier(softOf(th as never), th, fallbacks, text);
+}
+
+/**
+ * Painter for the soft *label* tier of header text (model name, thinking level, token
+ * counts). Same colour language as the footer: marks take `accent`, their text takes the
+ * soft border-accent tier, so a header line and the footer under it agree.
+ */
+export function softLabelFirst(th: Themeish, fallbacks: string[], text: string): string {
+	return softOnTier(softSecondaryOf(th as never), th, fallbacks, text);
+}
+
+/** Shared tail of the two soft painters: use the resolved soft tone, else the fallback tokens. */
+function softOnTier(paint: (s: string) => string, th: Themeish, fallbacks: string[], text: string): string {
+	const out = paint(text);
+	return out !== text ? out : fgFirst(th, fallbacks, text);
+}
+
 /**
  * Collapsed body of a pi startup section ("[Skills]\n  a, b"). pi 0.99 dropped
  * ExpandableText's own getCollapsedText/getExpandedText fields for a `build` callback
@@ -279,7 +307,7 @@ export function centerLine(text: string, width: number, side = "│"): string {
 // bar, column 3) in the theme soft — same P/i split as the old wordmark.
 export function buildLogoLines(th: Themeish): string[] {
 	const a = (s: string) => fgFirst(th, ["accent"], s);
-	const t = (s: string) => fgFirst(th, ["accentSoft", "text"], s);
+	const t = (s: string) => softFirst(th, ["accentSoft", "text"], s);
 	return [
 		`${a("██████")}  `,
 		`${a("██  ██")}  `,
@@ -483,7 +511,7 @@ export class ArnativeHeader implements Component {
 		const side = fgFirst(th, ["dim"], "│");
 
 		const infoLines: string[] = [];
-		const brand = (name: string) => fgFirst(th, ["accent", "accentSoft"], `\x1b[1m${name}\x1b[22m`);
+		const brand = (name: string) => fgFirst(th, ["accent"], `\x1b[1m${name}\x1b[22m`);
 		const dim = (text: string) => fgFirst(th, ["dim"], text);
 
 		// Left column: the mark with the pi version under it (no gap). The column is as
@@ -529,7 +557,7 @@ export class ArnativeHeader implements Component {
 			const isActive = t.key === this.activeTab;
 			const iconStyled = isActive ? fgFirst(th, ["accent"], t.icon) : fgFirst(th, ["dim"], t.icon);
 			const labelStyled = isActive
-				? fgFirst(th, ["accentSoft", "text"], `\x1b[1m${label}\x1b[22m`)
+				? softLabelFirst(th, ["accentSoft", "text"], `\x1b[1m${label}\x1b[22m`)
 				: fgFirst(th, ["dim"], label);
 			return { key: t.key, plain, formatted: `${iconStyled} ${labelStyled}` };
 		};
@@ -593,19 +621,19 @@ export class ArnativeHeader implements Component {
 			// Model name in soft, its "(Provider)" tail dim.
 			const provSuffix = fullName.match(/(\s*\([^()]*\))$/)?.[1] ?? "";
 			const nameMain = provSuffix ? fullName.slice(0, -provSuffix.length) : fullName;
-			let line = `${fgFirst(th, ["accentSoft", "text"], nameMain)}${provSuffix ? fgFirst(th, ["dim"], provSuffix) : ""}${sep}${fgFirst(th, ["accentSoft", "text"], `Thinking: ${thinkLevel}`)}`;
+			let line = `${softLabelFirst(th, ["accentSoft", "text"], nameMain)}${provSuffix ? fgFirst(th, ["dim"], provSuffix) : ""}${sep}${softLabelFirst(th, ["accentSoft", "text"], `Thinking: ${thinkLevel}`)}`;
 
 			// All-time usage of that model (same as /usage): ↑... ↓...  ...
 			const usage = getModelAllTimeUsage(modelObj?.id);
 			const tokenParts: string[] = [];
 			if (usage.input > 0) {
-				tokenParts.push(`${fgFirst(th, ["accent"], "↑")}${fgFirst(th, ["accentSoft", "text"], formatTokens(usage.input))}`);
+				tokenParts.push(`${fgFirst(th, ["accent"], "↑")}${softLabelFirst(th, ["accentSoft", "text"], formatTokens(usage.input))}`);
 			}
 			if (usage.output > 0) {
-				tokenParts.push(`${fgFirst(th, ["accent"], "↓")}${fgFirst(th, ["accentSoft", "text"], formatTokens(usage.output))}`);
+				tokenParts.push(`${fgFirst(th, ["accent"], "↓")}${softLabelFirst(th, ["accentSoft", "text"], formatTokens(usage.output))}`);
 			}
 			if (usage.cacheRead > 0) {
-				tokenParts.push(`${fgFirst(th, ["accent"], "\uf49b ")}${fgFirst(th, ["accentSoft", "text"], formatTokens(usage.cacheRead))}`);
+				tokenParts.push(`${fgFirst(th, ["accent"], "\uf49b ")}${softLabelFirst(th, ["accentSoft", "text"], formatTokens(usage.cacheRead))}`);
 			}
 			if (tokenParts.length > 0) {
 				line += `${sep}${tokenParts.join(" ")}`;
@@ -618,11 +646,11 @@ export class ArnativeHeader implements Component {
 
 		if (this.activeTab === "Directory") {
 			for (const line of wrapPath(getCwd(this.ctx), infoW)) {
-				infoLines.push(fgFirst(th, ["accentSoft", "text"], line));
+				infoLines.push(softLabelFirst(th, ["accentSoft", "text"], line));
 			}
 		} else if (this.activeTab === "Shortcut") {
 			for (const line of wrapTokens(SHORTCUTS, infoW)) {
-				infoLines.push(fgFirst(th, ["accentSoft", "text"], line));
+				infoLines.push(softLabelFirst(th, ["accentSoft", "text"], line));
 			}
 		} else if (activeItems.length === 0) {
 			infoLines.push(
@@ -634,7 +662,7 @@ export class ArnativeHeader implements Component {
 		} else {
 			for (const line of wrapCommaItems(activeItems, infoW)) {
 				// Point 5: selected menu data uses soft only
-				infoLines.push(fgFirst(th, ["accentSoft", "text"], line));
+				infoLines.push(softLabelFirst(th, ["accentSoft", "text"], line));
 			}
 		}
 

package/extensions/tools.ts

@@ -39,7 +39,7 @@ import {
 import { Markdown, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { homedir } from "node:os";
 import { renderBoxLines as box } from "../lib/box.ts";
-import { stripAnsi, accentSoftOf } from "../lib/ansi.ts";
+import { stripAnsi, softSecondaryOf } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { expandKeyName } from "../lib/format.ts";
 
@@ -233,15 +233,17 @@ const hasOwnRendererDef = (self: { toolDefinition?: { renderCall?: unknown; rend
 // sequence. Not exported by pi-tui, so match both prefixes.
 export const isImageLine = (line: string): boolean => line.includes("\x1b_G") || line.includes("\x1b]1337;File=");
 
-/** Drop the leading Spacer only when an image preview follows: its blank tail rows
- *  are the image's vertical space, and deleting them made the terminal draw the
- *  image over the rows below (chat text, editor, footer). */
+/** Drop the leading Spacer and the gap between box and image preview:
+ *  its blank tail rows are kept as the image's vertical space so the
+ *  terminal draws the image with balanced spacing above and below. */
 export function stripEdgesKeepingImages(lines: string[]): string[] {
 	const firstImage = lines.findIndex(isImageLine);
 	if (firstImage < 0) return stripBlankEdges(lines);
 	let s = 0;
 	while (s < firstImage && isBlankLine(lines[s])) s++;
-	return lines.slice(s);
+	const head = lines.slice(s, firstImage);
+	while (head.length > 0 && isBlankLine(head[head.length - 1]!)) head.pop();
+	return [...head, ...lines.slice(firstImage)];
 }
 
 const GAP_KEY = Symbol.for("pi-arnative.toolGapStripped");
@@ -441,7 +443,7 @@ if (ToolExecutionComponent?.prototype?.render && !(globalThis as Record<symbol,
 					? safeCall(() => own.call(this, { content: result.content, details: result.details }, opts, th, ctx))
 					: null;
 			return new Lines((width) => {
-				const soft = accentSoftOf(th);
+				const soft = softSecondaryOf(th);
 				const inner = Math.max(8, width - 4);
 				const icon = isErr ? th.fg("error", "x") : th.fg("success", "✓");
 				const boxed2 = componentLines(theirs, width - 6);
@@ -604,7 +606,7 @@ function minimal(
 			return new Lines((width) => {
 				// Read context.state live (never capture): renderResult may create it after renderCall.
 				if (context.state?.hasResult) return [];
-				const soft = accentSoftOf(theme);
+				const soft = softSecondaryOf(theme);
 				const inner = Math.max(8, width - 4);
 				const rows = titleRow(
 					theme,
@@ -633,7 +635,7 @@ function minimal(
 			const dur = fmtMs(context.toolCallId ? TIMINGS.get(context.toolCallId) : undefined);
 			const icon = isErr ? theme.fg("error", "x") : theme.fg("success", "✓");
 			return new Lines((width) => {
-				const soft = accentSoftOf(theme);
+				const soft = softSecondaryOf(theme);
 				const inner = Math.max(8, width - 4);
 				const rows = titleRow(
 					theme,
@@ -893,9 +895,9 @@ if (isMain(import.meta.url)) {
 	const itermSeq = "\x1b]1337;File=inline=1:AAAA\x07";
 	const withImage = ["", "╭─╮", "│ ✓ read form_crop.png │", "╰─╯", "", kittySeq, "", ""];
 	const kept = stripEdgesKeepingImages(withImage);
-	assert(kept.length === 7, "image: only the leading gap dropped, blank tail kept");
+	assert(kept.length === 6, "image: leading gap and box-image spacer dropped, blank tail kept");
 	assert(kept[0] === "╭─╮", "image: leading Spacer removed");
-	assert(kept.indexOf(kittySeq) === 4 && kept.length - 5 === 2, "image: rows after the sequence intact");
+	assert(kept.indexOf(kittySeq) === 3 && kept.length - 4 === 2, "image: rows after the sequence intact");
 	assert(
 		stripEdgesKeepingImages(["", "a", "", "b", "  ", ""]).join() === "a,,b",
 		"no image: falls back to plain edge stripping",

package/extensions/ui-render-tweaks.ts

@@ -39,9 +39,9 @@ import {
 } from "@earendil-works/pi-tui";
 import { readdirSync, readFileSync } from "node:fs";
 import { renderBoxLines } from "../lib/box.ts";
-import { ansiBgOpen, getActiveTheme, setActiveTheme, stripAnsi, themeOf, accentSoftOf } from "../lib/ansi.ts";
+import { ansiBgOpen, getActiveTheme, setActiveTheme, stripAnsi, themeOf, softSecondaryOf } from "../lib/ansi.ts";
 import { assert, isMain } from "../lib/check.ts";
-import { contrast, parseOklch, toHex } from "../lib/color.ts";
+import { contrast, oklchToRgb, parseOklch, toHex } from "../lib/color.ts";
 import { expandKeyName } from "../lib/format.ts";
 
 type ActiveTheme = { fg(color: string, text: string): string; bg?(color: string, text: string): string } | null;
@@ -174,7 +174,7 @@ const SELECT_ROW_KEY = Symbol.for("pi-arnative.selectRowColors");
 
 /** Selected row body: `·` separators accent, the text around them soft. */
 export function selectRowText(row: string, th: { fg(c: string, t: string): string }): string {
-	const soft = accentSoftOf(th);
+	const soft = softSecondaryOf(th);
 	return row
 		.split("·")
 		.map((part) => soft(part))
@@ -396,9 +396,21 @@ if (isMain(import.meta.url)) {
 	// hex, so resolve every token through lib/color before constructing it.
 	const resolve = (value: string) => toHex(themeJson.vars[value] ?? value);
 	const hex = (tok: string) => resolve(themeJson.colors[tok] ?? tok);
+	// Mirrors `soften()` (themes/gen-themes.mjs) and `softenColor` (lib/ansi.ts): the soft
+	// tier is the base color at L 0.82 with a fifth of its chroma. Both sides read the
+	// declared OKLCH string (not the 8-bit hex), so the comparison is not rounded twice.
+	const softenToHex = (base: string) => {
+		const o = parseOklch(base);
+		assert(o !== null, `cannot soften a non-oklch color: ${base}`);
+		return toHex(`oklch(82% ${oklchToRgb(0.82, o.C * 0.18, o.H).chroma} ${o.H})`);
+	};
 	// The built-in theme adds fallbacks (scrollbarTrack<-muted, thinkingMax<-thinkingXhigh),
 	// so the fg map must be complete; take the whole palette like pi's loader does.
-	const fgPalette = Object.fromEntries(Object.entries(themeJson.colors).map(([k, v]) => [k, resolve(v)]));
+	const fgPalette = Object.fromEntries(
+		Object.entries(themeJson.colors)
+			.filter(([k]) => k !== "accentSoft")
+			.map(([k, v]) => [k, resolve(v)]),
+	);
 	const thPill = new Theme(fgPalette, { toolPendingBg: hex("toolPendingBg"), selectedBg: hex("selectedBg") }, "truecolor");
 	const pillOriginal = thPill.bg("selectedBg", thPill.fg("text", " ↓ Jump to latest message · End "));
 	const rgb = (h: string) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)).join(";");
@@ -445,13 +457,38 @@ if (isMain(import.meta.url)) {
 		thinkingMedium: 2.7, thinkingHigh: 3.6, thinkingXhigh: 4.0,
 	};
 	const isColor = (v: string) => /^#[0-9a-f]{6}$/i.test(v) || parseOklch(v) !== null;
+	// The tokens pi's published theme schema allows as keys in `colors`. Pi 1.2.0 validates
+	// with `additionalProperties: false`, so ANY other key (arnative's `accentSoft` was the
+	// offender) fails the whole theme at startup with "must not have additional properties"
+	// and "Theme not found". Arnative's own colors belong in `vars`, referenced from these.
+	const SCHEMA_TOKENS = new Set([
+		"accent", "border", "borderAccent", "borderMuted", "success", "error", "warning",
+		"muted", "dim", "text", "thinkingText", "scrollbarTrack", "scrollbarThumb",
+		"selectedBg", "searchMatchBg", "searchMatchText", "userMessageBg", "userMessageText",
+		"customMessageBg", "customMessageText", "customMessageLabel", "toolPendingBg",
+		"toolSuccessBg", "toolErrorBg", "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",
+	]);
 	for (const f of readdirSync(themesDir).filter((n) => n.endsWith(".json")).sort()) {
 		const d = JSON.parse(readFileSync(new URL(f, themesDir), "utf8")) as {
+			$schema?: string;
 			name: string;
 			vars: Record<string, string>;
 			colors: Record<string, string>;
 		};
 		assert(d.name === f.replace(/\.json$/, ""), `theme ${f}: name = file name`);
+		// Pi 1.2.0 validates `colors` strictly; an extra key rejects the theme at startup.
+		const rogue = Object.keys(d.colors).filter((k) => !SCHEMA_TOKENS.has(k));
+		assert(rogue.length === 0, `theme ${f}: colors has non-schema keys [${rogue.join(", ")}] — move them to vars`);
+		assert(
+			d.$schema === "https://pi.dev/schemas/theme.schema.json",
+			`theme ${f}: $schema must be the published pi.dev theme schema (got ${d.$schema})`,
+		);
 		const missing = required.filter((k) => !(k in d.colors));
 		assert(missing.length === 0, `theme ${f}: required colors complete (missing ${missing.join(",")})`);
 		// colors values may only be: hex, oklch, 256-index, empty, or a REAL variable name —
@@ -479,6 +516,18 @@ if (isMain(import.meta.url)) {
 		// Accent pill: accent bg + toolPendingBg colored text.
 		assert(contrast(hex("accent"), hex("toolPendingBg")) >= 4.5, `theme ${f}: accent vs toolPendingBg contrast >= 4.5`);
 		assert(isColor(d.vars.accentSoft ?? ""), `theme ${f}: vars.accentSoft is a color`);
+		assert(isColor(d.vars.secondarySoft ?? ""), `theme ${f}: vars.secondarySoft is a color`);
+		assert(isColor(d.vars.primary ?? ""), `theme ${f}: vars.primary is a color`);
+		assert(isColor(d.vars.secondary ?? ""), `theme ${f}: vars.secondary is a color`);
+		// The declared soft vars must equal what the extensions derive at runtime, or the
+		// footer label colour drifts from the theme file. `softenToHex` mirrors
+		// `soften()` in gen-themes.mjs and `softenColor` in lib/ansi.ts.
+		for (const [softName, baseName] of [["accentSoft", "accent"], ["secondarySoft", "borderAccent"]] as const) {
+			const base = d.vars[d.colors[baseName] ?? baseName]!;
+			const declared = toHex(d.vars[softName]!);
+			const derived = softenToHex(base);
+			assert(declared === derived, `theme ${f}: vars.${softName} ${declared} != runtime ${derived} (derived from ${baseName})`);
+		}
 		const canvas = hex("userMessageBg");
 		for (const tok of Object.keys(d.colors)) {
 			if (nonText.has(tok) || tok === "thinkingMax") continue;

package/extensions/usage.ts

@@ -11,7 +11,7 @@ import { matchesKey, truncateToWidth, visibleWidth, type Component, type TUI, ty
 import { renderScreen, screenTitle } from "../lib/box.ts";
 import { assert, isMain } from "../lib/check.ts";
 import { capitalize } from "../lib/format.ts";
-import { thinkingColorOf } from "../lib/ansi.ts";
+import { thinkingColorOf, softSecondaryOf } from "../lib/ansi.ts";
 import { legendUsage, matchesBack } from "../lib/shortcuts.ts";
 import { collectUsageSummary, estimateCost, formatTokens, getModelAllTimeUsage, hasPrice, loadPriceTable, type UsageSummary } from "../lib/usage-store.ts";
 
@@ -196,7 +196,12 @@ export class UsageModalComponent implements Component {
 		// dashboard reads as belonging to the model that produced the usage.
 		const edge = (t: string) => this.edgeOf(t);
 		const boxW = width;
-		const soft = (s: string) => th.fg("accentSoft", s);
+		// `secondarySoft` is a vars-only token on Pi 1.2+; softSecondaryOf resolves the soft
+		// label tier (the border-accent hue) and falls back to the accent tier.
+		const soft = softSecondaryOf(th);
+		const acc = (s: string) => th.fg("accent", s);
+		const dim = (s: string) => th.fg("dim", s);
+		const plain = (s: string) => th.fg("text", s);
 
 		const rows = this.buildFlatRows();
 		if (this.selectedIndex >= rows.length) {
@@ -255,21 +260,21 @@ export class UsageModalComponent implements Component {
 			const actualIdx = startIdx + i;
 			const isSelected = actualIdx === this.selectedIndex;
 
-			const nameColor = isSelected ? "accent" : item.type === "provider" ? "accentSoft" : "text";
-			const valColor = isSelected ? "accent" : "dim";
+			const paintName = isSelected ? acc : item.type === "provider" ? soft : plain;
+			const paintVal = isSelected ? acc : dim;
 
-			const cName = formatCol(th.fg(nameColor, isSelected ? bold(item.label) : item.label), rowNameW, false);
-			const cSess = formatCol(th.fg(valColor, formatCount(item.sessions)), sessionW);
-			const cMsgs = formatCol(th.fg(valColor, formatCount(item.msgs)), messagesW);
-			const cToks = formatCol(th.fg(valColor, formatTokens(item.tokens)), colW.tokens);
+			const cName = formatCol(paintName(isSelected ? bold(item.label) : item.label), rowNameW, false);
+			const cSess = formatCol(paintVal(formatCount(item.sessions)), sessionW);
+			const cMsgs = formatCol(paintVal(formatCount(item.msgs)), messagesW);
+			const cToks = formatCol(paintVal(formatTokens(item.tokens)), colW.tokens);
 			// A row with no reported cost but a rate shows `~$x` in place of `-`, so the guess is
 			// visible exactly where it is one; the report line still keeps it out of the headline.
 			const costCell = item.cost > 0 ? formatCost(item.cost) : item.estimatedCost > 0 ? `~${formatCost(item.estimatedCost)}` : "-";
-			const cCost = formatCol(th.fg(valColor, costCell), colW.cost);
+			const cCost = formatCol(paintVal(costCell), colW.cost);
 
 			// Gutter: expand arrow for provider or blank indent for model.
 			const gutterText =
-				item.type === "provider" ? th.fg(item.expanded ? "accentSoft" : "dim", item.expanded ? "▾" : "▸") : " ";
+				item.type === "provider" ? (item.expanded ? soft("▾") : dim("▸")) : " ";
 			const line = gutterText + " " + cName + cSess + cMsgs + cToks + cCost;
 			this.rowHitboxes.push({ line: CHROME_ROWS + body.length, index: actualIdx });
 			body.push(line);
@@ -277,7 +282,7 @@ export class UsageModalComponent implements Component {
 
 		// The selected row's detail sits under the table, where the eye lands after scanning it.
 		body.push("");
-		body.push(this.selectedDetail(rows[this.selectedIndex], (t) => th.fg("accent", t), (t) => th.fg("accentSoft", t)));
+		body.push(this.selectedDetail(rows[this.selectedIndex], acc, soft));
 
 		// Table-width separator above Total band (skill arnative-pi §6 rule 7).
 		const tableW = colW.name + sessionW + messagesW + colW.tokens + colW.cost;
@@ -285,11 +290,11 @@ export class UsageModalComponent implements Component {
 
 		// Total row
 		const t = this.summary.totals;
-		const totalName = formatCol(th.fg("accentSoft", bold("Total")), colW.name, false);
-		const totalSess = formatCol(th.fg("accentSoft", bold(formatCount(t.sessions))), sessionW);
-		const totalMsgs = formatCol(th.fg("accentSoft", bold(formatCount(t.msgs))), messagesW);
-		const totalToks = formatCol(th.fg("accentSoft", bold(formatTokens(t.totalTokens))), colW.tokens);
-		const totalCost = formatCol(th.fg("accentSoft", bold(formatCost(t.cost))), colW.cost);
+		const totalName = formatCol(soft(bold("Total")), colW.name, false);
+		const totalSess = formatCol(soft(bold(formatCount(t.sessions))), sessionW);
+		const totalMsgs = formatCol(soft(bold(formatCount(t.msgs))), messagesW);
+		const totalToks = formatCol(soft(bold(formatTokens(t.totalTokens))), colW.tokens);
+		const totalCost = formatCol(soft(bold(formatCost(t.cost))), colW.cost);
 
 		// Same left edge as the header: one table, three bands, one column grid.
 		body.push(totalName + totalSess + totalMsgs + totalToks + totalCost);