@stemtrooper/learningcode 0.2.0 → 0.3.0

package/README.md

@@ -66,12 +66,23 @@ The LEARNINGCODE block banner replaces Pi's header at startup:
 The figlet "ANSI Shadow" face, 97 columns wide, kept verbatim because the
 double-line box characters only align if every row keeps its exact offset.
 
-Colour comes from the active theme, so it stays legible in light and dark.
+It steps down through three tiers, because a phone will never have 97 columns and
+clipping box characters looks like a rendering bug rather than a design:
+
+| Terminal width | Shows |
+|---|---|
+| 99 or more | the figlet face above |
+| 51 to 98 | a condensed 4 row face, 47 columns |
+| under 51 | the wordmark |
 
-**It needs a 99 column terminal.** Below that it collapses to a wordmark,
-rather than drawing art that would be clipped into something that looks broken.
-An 80 column terminal will show the compact form, so widen the window or reduce
-the art.
+The condensed tier still spells LEARNINGCODE:
+
+\\n  █   ███  █  ███ █ █ ███ █ █ ███ ███ ███ ███ ███
+  █   █   █ █ █ █ ███  █  ███ █   █   █ █ █ █ █
+  █   ███ ███ ███ █ █  █  █ █ █ █ █   █ █ █ █ ███
+  ███ ███ █ █ █ █ █ █ ███ █ █ ███ ███ ███ ███ ███
+\\n
+Colour comes from the active theme, so it stays legible in light and dark.
 
 It installs via `ctx.ui.setHeader`, the supported way to brand a fork.
 

package/extensions/banner.ts

@@ -1,26 +1,36 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { foregroundAnsi, rgbColor } from "@earendil-works/pi-tui";
 
 /**
  * LEARNINGCODE startup banner.
  *
  * Pi lets an extension replace the whole header, which is the supported way to
- * brand a fork without touching Pi's internals. The built-in header is Pi's own
- * logo plus key hints; we trade that for the TLC banner and a line of slash
- * commands, so nothing is claimed about keybindings we cannot read.
+ * brand a fork without touching Pi's internals.
  *
- * The art is the figlet "ANSI Shadow" face, kept verbatim rather than rebuilt from
- * a glyph map: the double-line box characters only line up if every row keeps
- * its exact offset, and a one-space drift makes the whole thing look broken.
+ * Three tiers, because the full face does not fit everywhere. A phone will never
+ * have 97 columns, and clipping box characters looks like a rendering bug rather
+ * than a design, so the banner steps down instead:
  *
- * Rendering uses the active theme's colour tokens (`accent`, `border`, `dim`,
- * `muted`) so the banner stays legible in light and dark terminals instead of
- * hard-coding colours that break on one of them.
+ *   >= 99 columns   figlet "ANSI Shadow", 97 wide, 6 rows
+ *   >= 51 columns   condensed 4 row face, 47 wide
+ *   below that     the wordmark
+ *
+ * The full art is stored verbatim rather than rebuilt from a glyph map. That face
+ * only aligns because every row keeps its exact offset, the top row flush left
+ * and the rest flush too; a one-space drift makes the whole banner look broken.
+ * A test asserts those offsets.
  */
 
-/** Structural types, so this file needs no runtime import from Pi's packages. */
+/**
+ * Only the parts of Pi's Theme this file touches, to keep the runtime import down
+ * to the two colour helpers actually needed.
+ */
 type ThemeLike = {
   fg(token: string, text: string): string;
-  getColorMode?(): "light" | "dark";
+  /** "light" | "dark" - the background the active theme is designed for. */
+  appearance?: "light" | "dark";
+  /** The terminal's colour capability, e.g. "truecolor". Not light or dark. */
+  getColorMode?(): string;
 };
 type HeaderComponent = { render(width: number): string[] };
 
@@ -35,10 +45,23 @@ type HeaderComponent = { render(width: number): string[] };
  *
  * Two values because the logo ships two: the darker cyan holds contrast on a
  * white field, the brighter one on black.
+ *
+ * Note this must not go through `theme.fg()`. That resolves theme *tokens*, and
+ * `Theme.tokenAnsi` throws `Unknown theme color: #29c8f2` for anything that is
+ * not one, so a raw hex there crashes the header at render time.
+ * `foregroundAnsi` takes a colour value directly, and unlike a hand-rolled escape
+ * it still degrades to 256 colour on terminals without truecolour support.
  */
-const CYAN_DARK_BG = "#29c8f2";
-const CYAN_LIGHT_BG = "#0dacd6";
+const CYAN_DARK_BG = rgbColor(0x29, 0xc8, 0xf2);
+const CYAN_LIGHT_BG = rgbColor(0x0d, 0xac, 0xd6);
+const RESET = "\x1b[0m";
+
+const WORD = "LEARNINGCODE";
+const PAD = "  ";
+const TAGLINE = "The Learning Curve · Sarawak";
+const HINTS = "/help commands · /quota today's spend · /hotkeys keys";
 
+/** figlet "ANSI Shadow", verbatim. 97 columns, 6 rows. */
 const ART: readonly string[] = [
   "██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗",
   "██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝",
@@ -48,45 +71,77 @@ const ART: readonly string[] = [
   "╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝",
 ];
 
-const TAGLINE = "The Learning Curve · Sarawak";
-const HINTS = "/help commands · /quota today's spend · /hotkeys keys";
+/**
+ * Condensed fallback for narrow terminals. Three columns per glyph, which is
+ * the most a twelve letter word can be compressed before the letterforms stop
+ * reading: an N needs four columns to show its diagonal, and dropping it to
+ * three turns the letter into a filled block.
+ */
+const CONDENSED_GLYPHS: Record<string, readonly string[]> = {
+  L: ["█  ", "█  ", "█  ", "███"],
+  E: ["███", "█  ", "███", "███"],
+  A: [" █ ", "█ █", "███", "█ █"],
+  R: ["███", "█ █", "███", "█ █"],
+  N: ["█ █", "███", "█ █", "█ █"],
+  I: ["███", " █ ", " █ ", "███"],
+  G: ["███", "█  ", "█ █", "███"],
+  C: ["███", "█  ", "█  ", "███"],
+  O: ["███", "█ █", "█ █", "███"],
+  D: ["███", "█ █", "█ █", "███"],
+};
 
-const PAD = "  ";
+const condensedArt = (): string[] => {
+  const rows = CONDENSED_GLYPHS[WORD[0]].length;
+  return Array.from({ length: rows }, (_, row) =>
+    [...WORD].map((letter) => CONDENSED_GLYPHS[letter][row]).join(" ").trimEnd(),
+  );
+};
 
 /** A copy, so a caller mutating the result cannot corrupt later renders. */
 export const bannerArt = (): string[] => [...ART];
 
+export const condensedArt_ = condensedArt;
+
 export const bannerWidth = (): number => Math.max(...ART.map((line) => line.length));
+export const condensedWidth = (): number => Math.max(...condensedArt().map((line) => line.length));
 
-/**
- * The art is 97 columns, which does not fit the classic 80 column terminal.
- * Below the art plus its indent we show a wordmark instead, because clipped box
- * characters look like a rendering bug rather than a design.
- */
+/** Art plus its indent. Derived, never guessed. */
 const MIN_FULL_WIDTH = bannerWidth() + PAD.length;
+const MIN_CONDENSED_WIDTH = condensedWidth() + PAD.length;
 
 export function createBanner(theme: ThemeLike): HeaderComponent {
-	const art = bannerArt();
-	const artWidth = bannerWidth();
+	const full = bannerArt();
+	const small = condensedArt();
 
-	// Fall back to the theme's accent only if a caller cannot report its colour
-	// mode, which keeps the banner legible rather than dropping colour entirely.
-	const mode = typeof theme.getColorMode === "function" ? theme.getColorMode() : "dark";
-	const brand = mode === "light" ? CYAN_LIGHT_BG : CYAN_DARK_BG;
-	const ink = (text: string) => theme.fg(brand as never, text);
+	// Two different things, easy to swap by accident:
+	//   appearance    light or dark, decides which brand cyan is readable
+	//   getColorMode  the terminal's colour capability, decides how to emit it
+	// Default to dark so the banner keeps its colour on a host that reports
+	// neither, rather than dropping the brand.
+	const isLight = theme.appearance === "light";
+	const mode = typeof theme.getColorMode === "function" ? theme.getColorMode() : "truecolor";
+	const brand = foregroundAnsi(isLight ? CYAN_LIGHT_BG : CYAN_DARK_BG, mode as never);
+	const ink = (text: string) => `${brand}${text}${RESET}`;
 
 	return {
 		render(width: number): string[] {
-			if (width < MIN_FULL_WIDTH) {
-				return ["", ink(PAD + "learningcode"), theme.fg("muted", PAD + TAGLINE)];
+			if (width >= MIN_FULL_WIDTH) {
+				const lines = ["", ...full.map((line) => ink(PAD + line))];
+				lines.push(theme.fg("border", PAD + "═".repeat(bannerWidth())));
+				lines.push(theme.fg("muted", PAD + TAGLINE));
+				lines.push(theme.fg("dim", PAD + HINTS));
+				lines.push("");
+				return lines;
+			}
+
+			if (width >= MIN_CONDENSED_WIDTH) {
+				const lines = ["", ...small.map((line) => ink(PAD + line))];
+				lines.push(theme.fg("muted", PAD + TAGLINE));
+				lines.push("");
+				return lines;
 			}
 
-			const lines = ["", ...art.map((line) => ink(PAD + line))];
-			lines.push(theme.fg("border", PAD + "═".repeat(artWidth)));
-			lines.push(theme.fg("muted", PAD + TAGLINE));
-			lines.push(theme.fg("dim", PAD + HINTS));
-			lines.push("");
-			return lines;
+			return ["", ink(PAD + "learningcode"), theme.fg("muted", PAD + TAGLINE)];
 		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "TLC Spark coding agent for students: Pi wired to the Spark OpenAI-compatible endpoint with per-student tokens, quota and seat-queue awareness.",
 	"type": "module",
 	"license": "MIT",
@@ -17,10 +17,12 @@
 	],
 	"scripts": {
 		"start": "node ./bin/learningcode.mjs",
-		"test": "node --test \"test/**/*.test.mjs\""
+		"test": "node --test \"test/**/*.test.mjs\"",
+		"preview": "node ./scripts/preview.mjs"
 	},
 	"dependencies": {
-		"@earendil-works/pi-coding-agent": "1.0.4"
+		"@earendil-works/pi-coding-agent": "1.0.4",
+		"@earendil-works/pi-tui": "1.0.4"
 	},
 	"devDependencies": {
 		"jiti": "2.7.0"