@umang-boss/claudemon 1.0.0

package/src/state/schemas.ts

@@ -0,0 +1,131 @@
+/**
+ * Zod validation schemas for state files.
+ * Catches disk corruption early at load boundaries.
+ */
+
+import { z } from "zod";
+
+import {
+  BADGE_TYPES,
+  CODING_STATS,
+  EVENT_COUNTER_KEYS,
+} from "../engine/types.js";
+
+// ---- Shared Primitives ----
+
+const BadgeTypeSchema = z.enum(BADGE_TYPES);
+
+// ---- Coding Stats ----
+
+export const CodingStatsSchema = z.object({
+  stamina: z.number(),
+  debugging: z.number(),
+  stability: z.number(),
+  velocity: z.number(),
+  wisdom: z.number(),
+});
+
+// ---- Owned Pokemon ----
+
+export const OwnedPokemonSchema = z.object({
+  id: z.string(),
+  pokemonId: z.number().int().min(1).max(151),
+  nickname: z.string().nullable(),
+  level: z.number().int().min(1).max(100),
+  currentXp: z.number().int().min(0),
+  totalXp: z.number().int().min(0),
+  codingStats: CodingStatsSchema,
+  happiness: z.number().int().min(0).max(255),
+  caughtAt: z.string(),
+  evolvedAt: z.string().nullable(),
+  isActive: z.boolean(),
+  personality: z.string().nullable(),
+  shiny: z.boolean().default(false),
+  isStarter: z.boolean().default(false),
+});
+
+// ---- Event Counters ----
+
+// Cast needed: Object.fromEntries loses key specificity, but keys are guaranteed by EVENT_COUNTER_KEYS
+export const EventCountersSchema = z.object(
+  Object.fromEntries(
+    EVENT_COUNTER_KEYS.map((key) => [key, z.number().int().min(0).default(0)])
+  ) as Record<(typeof EVENT_COUNTER_KEYS)[number], z.ZodDefault<z.ZodNumber>>
+);
+
+// ---- Streak Data ----
+
+export const StreakDataSchema = z.object({
+  currentStreak: z.number().int().min(0).default(0),
+  longestStreak: z.number().int().min(0).default(0),
+  lastActiveDate: z.string().nullable().default(null),
+  totalDaysActive: z.number().int().min(0).default(0),
+});
+
+// ---- Buddy Config ----
+
+export const BuddyConfigSchema = z.object({
+  muted: z.boolean().default(false),
+  reactionCooldownMs: z.number().int().min(0).default(30_000),
+  statusLineEnabled: z.boolean().default(true),
+  bellEnabled: z.boolean().default(true),
+});
+
+// ---- Pokedex ----
+
+export const PokedexEntrySchema = z.object({
+  seen: z.boolean(),
+  caught: z.boolean(),
+  firstSeen: z.string().nullable(),
+  firstCaught: z.string().nullable(),
+});
+
+export const PokedexStateSchema = z.object({
+  entries: z.record(z.coerce.number(), PokedexEntrySchema).default({}),
+  totalSeen: z.number().int().min(0).default(0),
+  totalCaught: z.number().int().min(0).default(0),
+});
+
+// ---- Achievements ----
+
+export const UnlockedAchievementSchema = z.object({
+  achievementId: z.string(),
+  unlockedAt: z.string(),
+});
+
+// ---- Catch Condition ----
+
+export const CatchConditionSchema = z.object({
+  requiredStat: z.enum(CODING_STATS).nullable(),
+  minStatValue: z.number(),
+  requiredLevel: z.number(),
+});
+
+// ---- Wild Encounter ----
+
+export const WildEncounterSchema = z.object({
+  pokemonId: z.number().int().min(1).max(151),
+  level: z.number().int().min(1).max(100),
+  catchCondition: CatchConditionSchema,
+});
+
+// ---- Player State (top-level) ----
+
+export const PlayerStateSchema = z.object({
+  trainerId: z.string(),
+  trainerName: z.string(),
+  party: z.array(OwnedPokemonSchema).max(6),
+  pcBox: z.array(OwnedPokemonSchema).default([]),
+  pokedex: PokedexStateSchema,
+  badges: z.array(BadgeTypeSchema).default([]),
+  achievements: z.array(UnlockedAchievementSchema).default([]),
+  counters: EventCountersSchema,
+  streak: StreakDataSchema,
+  config: BuddyConfigSchema,
+  startedAt: z.string(),
+  totalXpEarned: z.number().int().min(0).default(0),
+  totalSessions: z.number().int().min(0).default(0),
+  pendingEncounter: WildEncounterSchema.nullable().default(null),
+  xpSinceLastEncounter: z.number().int().min(0).default(0),
+});
+

package/src/state/state-manager.ts

@@ -0,0 +1,321 @@
+/**
+ * Singleton state manager for Claudemon.
+ * All state reads/writes flow through this class.
+ */
+
+import { getStateDir, getStateFile, getStatusFile } from "../engine/constants.js";
+import type {
+  PlayerState,
+  OwnedPokemon,
+  EventCounterKey,
+  EventCounters,
+  StreakData,
+  BuddyConfig,
+  PokedexState,
+  WildEncounter,
+} from "../engine/types.js";
+import { EVENT_COUNTER_KEYS } from "../engine/types.js";
+import { atomicWrite, safeRead, ensureDir, backupCorrupted, withLock } from "./io.js";
+import { PlayerStateSchema } from "./schemas.js";
+
+/** Compact status payload for the shell status line script */
+interface StatusPayload {
+  name: string;
+  level: number;
+  xpPercent: number;
+  speciesId: number;
+  evolutionReady: boolean;
+}
+
+/** Build a zeroed-out EventCounters record */
+function emptyCounters(): EventCounters {
+  const counters = {} as Record<string, number>;
+  for (const key of EVENT_COUNTER_KEYS) {
+    counters[key] = 0;
+  }
+  return counters as EventCounters;
+}
+
+/** Build default streak data */
+function emptyStreak(): StreakData {
+  return {
+    currentStreak: 0,
+    longestStreak: 0,
+    lastActiveDate: null,
+    totalDaysActive: 0,
+  };
+}
+
+/** Build default config */
+function defaultConfig(): BuddyConfig {
+  return {
+    muted: false,
+    reactionCooldownMs: 30_000,
+    statusLineEnabled: true,
+    bellEnabled: true,
+  };
+}
+
+/** Build empty pokedex */
+function emptyPokedex(): PokedexState {
+  return {
+    entries: {},
+    totalSeen: 0,
+    totalCaught: 0,
+  };
+}
+
+/** Get today's date as YYYY-MM-DD in local timezone */
+function todayDateString(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export class StateManager {
+  private static instance: StateManager | null = null;
+  private state: PlayerState | null = null;
+
+  private constructor() {}
+
+  /** Get the singleton StateManager instance */
+  static getInstance(): StateManager {
+    if (!StateManager.instance) {
+      StateManager.instance = new StateManager();
+    }
+    return StateManager.instance;
+  }
+
+  /** Load state from disk. Returns null on first run (no file) or if data is corrupted. */
+  async load(): Promise<PlayerState | null> {
+    await ensureDir(getStateDir());
+
+    const stateFile = getStateFile();
+    const fileExists = await Bun.file(stateFile).exists();
+    if (!fileExists) {
+      return null;
+    }
+
+    const raw = await safeRead<unknown>(stateFile);
+    if (raw === null) {
+      // File exists but safeRead returned null — empty or invalid JSON
+      const backupPath = await backupCorrupted(stateFile);
+      process.stderr.write(
+        `[claudemon] State file was corrupted and has been backed up to ${backupPath}\n` +
+          `[claudemon] You'll need to pick a new starter with buddy_starter.\n`,
+      );
+      return null;
+    }
+
+    try {
+      // Zod output is structurally compatible but not nominally identical to PlayerState
+      const parsed = PlayerStateSchema.parse(raw) as PlayerState;
+      this.state = parsed;
+      return this.state;
+    } catch (err: unknown) {
+      // Schema validation failed — data on disk doesn't match expected shape
+      const backupPath = await backupCorrupted(stateFile);
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `[claudemon] State validation failed: ${message}\n` +
+          `[claudemon] Corrupted data backed up to ${backupPath}\n` +
+          `[claudemon] You'll need to pick a new starter with buddy_starter.\n`,
+      );
+      return null;
+    }
+  }
+
+  /** Save current state to disk atomically, protected by file lock */
+  async save(): Promise<void> {
+    if (!this.state) {
+      throw new Error("Cannot save: state not loaded. Call load() or initializePlayer() first.");
+    }
+    const stateDir = getStateDir();
+    await ensureDir(stateDir);
+    const lockPath = `${stateDir}/state.lock`;
+    await withLock(lockPath, async () => {
+      const json = JSON.stringify(this.state, null, 2);
+      await atomicWrite(getStateFile(), json);
+    });
+  }
+
+  /** Get current state (throws if not loaded) */
+  getState(): PlayerState {
+    if (!this.state) {
+      throw new Error("State not loaded. Call load() first.");
+    }
+    return this.state;
+  }
+
+  /** Check if this is first run (no state file exists) */
+  async isFirstRun(): Promise<boolean> {
+    const file = Bun.file(getStateFile());
+    return !(await file.exists());
+  }
+
+  /** Initialize new player state after starter selection */
+  async initializePlayer(
+    trainerId: string,
+    trainerName: string,
+    starter: OwnedPokemon,
+  ): Promise<PlayerState> {
+    const now = new Date().toISOString();
+
+    const state: PlayerState = {
+      trainerId,
+      trainerName,
+      party: [starter],
+      pcBox: [],
+      pokedex: emptyPokedex(),
+      badges: [],
+      achievements: [],
+      counters: emptyCounters(),
+      streak: emptyStreak(),
+      config: defaultConfig(),
+      startedAt: now,
+      totalXpEarned: 0,
+      totalSessions: 0,
+      pendingEncounter: null,
+      xpSinceLastEncounter: 0,
+    };
+
+    this.state = state;
+    await this.save();
+    return this.state;
+  }
+
+  /** Get the active Pokemon from the party (isActive === true) */
+  getActivePokemon(): OwnedPokemon | null {
+    if (!this.state) {
+      return null;
+    }
+    return this.state.party.find((p) => p.isActive) ?? null;
+  }
+
+  /** Increment an event counter by amount (default 1) and save (lock-protected) */
+  async incrementCounter(key: EventCounterKey, amount: number = 1): Promise<void> {
+    const state = this.getState();
+    state.counters[key] += amount;
+    await this.save();
+  }
+
+  /** Update daily streak based on today vs lastActiveDate, then save */
+  async updateStreak(): Promise<void> {
+    const state = this.getState();
+    const today = todayDateString();
+    const { streak } = state;
+
+    if (streak.lastActiveDate === today) {
+      // Already recorded today, nothing to do
+      return;
+    }
+
+    if (streak.lastActiveDate === null) {
+      // First ever activity
+      streak.currentStreak = 1;
+      streak.totalDaysActive = 1;
+    } else {
+      const last = new Date(streak.lastActiveDate);
+      const now = new Date(today);
+      const diffMs = now.getTime() - last.getTime();
+      const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
+
+      if (diffDays === 1) {
+        // Consecutive day
+        streak.currentStreak += 1;
+      } else {
+        // Streak broken
+        streak.currentStreak = 1;
+      }
+      streak.totalDaysActive += 1;
+    }
+
+    if (streak.currentStreak > streak.longestStreak) {
+      streak.longestStreak = streak.currentStreak;
+    }
+
+    streak.lastActiveDate = today;
+    await this.save();
+  }
+
+  /** Write compact status JSON for the shell status line script. */
+  async writeStatus(evolutionReady: boolean = false): Promise<void> {
+    const active = this.getActivePokemon();
+    if (!active) {
+      return;
+    }
+
+    // XP percent is currentXp as a rough percentage toward next level
+    // Exact formula depends on exp group; use a simple ratio for the status line
+    const xpPercent = active.level >= 100 ? 100 : Math.min(100, Math.floor((active.currentXp / Math.max(1, active.currentXp + 50)) * 100));
+
+    // Look up species name if no nickname
+    let displayName = active.nickname ?? "";
+    if (!displayName) {
+      const { POKEMON_BY_ID } = await import("../engine/pokemon-data.js");
+      const species = POKEMON_BY_ID.get(active.pokemonId);
+      displayName = species?.name ?? `Pokemon #${active.pokemonId}`;
+    }
+
+    const payload: StatusPayload = {
+      name: displayName,
+      level: active.level,
+      xpPercent,
+      speciesId: active.pokemonId,
+      evolutionReady,
+    };
+
+    const stateDir = getStateDir();
+    await ensureDir(stateDir);
+    await atomicWrite(getStatusFile(), JSON.stringify(payload));
+  }
+
+  /** Set a pending wild encounter on state. */
+  setPendingEncounter(encounter: WildEncounter): void {
+    const state = this.getState();
+    state.pendingEncounter = encounter;
+  }
+
+  /** Clear the pending wild encounter from state. */
+  clearPendingEncounter(): void {
+    const state = this.getState();
+    state.pendingEncounter = null;
+  }
+
+  /** Write encounter notification to status JSON so status line can show it. */
+  async writeEncounterStatus(pokemonName: string): Promise<void> {
+    const active = this.getActivePokemon();
+    if (!active) return;
+
+    const xpPercent =
+      active.level >= 100
+        ? 100
+        : Math.min(100, Math.floor((active.currentXp / Math.max(1, active.currentXp + 50)) * 100));
+
+    let displayName = active.nickname ?? "";
+    if (!displayName) {
+      const { POKEMON_BY_ID } = await import("../engine/pokemon-data.js");
+      const species = POKEMON_BY_ID.get(active.pokemonId);
+      displayName = species?.name ?? `Pokemon #${active.pokemonId}`;
+    }
+
+    const payload = {
+      name: displayName,
+      level: active.level,
+      xpPercent,
+      speciesId: active.pokemonId,
+      evolutionReady: false,
+      encounter: `Wild ${pokemonName} appeared!`,
+    };
+
+    await ensureDir(getStateDir());
+    await atomicWrite(getStatusFile(), JSON.stringify(payload));
+  }
+
+  /** Reset singleton for testing purposes */
+  static resetInstance(): void {
+    StateManager.instance = null;
+  }
+}

package/statusline/buddy-status.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+# Claude Code status line for Claudemon.
+# Two-column layout:
+#   LEFT:  model, context remaining, usage, buddy speech
+#   RIGHT: colorscript sprite + name + level (hideable via /buddy hide)
+
+STATE_DIR="$HOME/.claudemon"
+STATUS_FILE="$STATE_DIR/status.json"
+CONFIG_FILE="$STATE_DIR/config.json"
+
+[ -f "$STATUS_FILE" ] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+# ── Check hide/show toggle ──────────────────────────────────
+SPRITE_HIDDEN="false"
+if [ -f "$CONFIG_FILE" ]; then
+  SPRITE_HIDDEN=$(jq -r '.spriteHidden // false' "$CONFIG_FILE" 2>/dev/null)
+fi
+
+# ── Read Claude Code stdin JSON ─────────────────────────────
+STDIN_DATA=""
+if [ ! -t 0 ]; then
+  STDIN_DATA=$(timeout 1 cat 2>/dev/null || true)
+fi
+
+CC_MODEL="" CC_CONTEXT=""
+if [ -n "$STDIN_DATA" ]; then
+  CC_MODEL=$(echo "$STDIN_DATA" | jq -r '.model.display_name // empty' 2>/dev/null)
+
+  # Context memory: count conversation messages from transcript
+  TRANSCRIPT=$(echo "$STDIN_DATA" | jq -r '.transcript_path // empty' 2>/dev/null)
+  if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+    # Count message objects in transcript as a rough context indicator
+    MSG_COUNT=$(jq '[.[] | select(.type == "message" or .type == "human" or .type == "assistant")] | length' "$TRANSCRIPT" 2>/dev/null || echo 0)
+    # Rough estimate: ~50 messages fills a 200K context window
+    # (each message averages ~4K tokens including tool calls)
+    MAX_MSGS=50
+    if [ "$MSG_COUNT" -gt 0 ]; then
+      USED_PCT=$(( (MSG_COUNT * 100) / MAX_MSGS ))
+      [ "$USED_PCT" -gt 100 ] && USED_PCT=100
+      LEFT_PCT=$(( 100 - USED_PCT ))
+      CC_CONTEXT="${LEFT_PCT}% context"
+    fi
+  fi
+fi
+
+# ── Read buddy status ───────────────────────────────────────
+STATUS=$(cat "$STATUS_FILE" 2>/dev/null) || exit 0
+[ -n "$STATUS" ] || exit 0
+
+NAME=$(echo "$STATUS" | jq -r '.name // empty')
+[ -n "$NAME" ] || exit 0
+
+LEVEL=$(echo "$STATUS" | jq -r '.level // 0')
+SPECIES_ID=$(echo "$STATUS" | jq -r '.speciesId // 0')
+EVOLVING=$(echo "$STATUS" | jq -r '.evolutionReady // false')
+REACTION=$(echo "$STATUS" | jq -r '.reaction // empty')
+ENCOUNTER=$(echo "$STATUS" | jq -r '.encounter // empty')
+
+# ── Colors ──────────────────────────────────────────────────
+NC=$'\033[0m'
+DIM=$'\033[2m'
+CYAN=$'\033[38;2;100;200;220m'
+GRAY=$'\033[38;2;120;120;130m'
+GREEN=$'\033[38;2;100;200;100m'
+B=$'\xe2\xa0\x80'
+
+# ── Terminal width ──────────────────────────────────────────
+COLS=0
+PID=$$
+for _ in 1 2 3 4 5; do
+  PID=$(ps -o ppid= -p "$PID" 2>/dev/null | tr -d ' ')
+  [ -z "$PID" ] || [ "$PID" = "1" ] && break
+  PTY=$(readlink "/proc/${PID}/fd/0" 2>/dev/null)
+  if [ -c "$PTY" ] 2>/dev/null; then
+    COLS=$(stty size < "$PTY" 2>/dev/null | awk '{print $2}')
+    [ "${COLS:-0}" -gt 40 ] 2>/dev/null && break
+  fi
+done
+[ "${COLS:-0}" -lt 40 ] 2>/dev/null && COLS=${COLUMNS:-0}
+[ "${COLS:-0}" -lt 40 ] 2>/dev/null && COLS=125
+[ "$COLS" -lt 40 ] && exit 0
+
+# ── Build name line ─────────────────────────────────────────
+if [ "$EVOLVING" = "true" ]; then
+  INFO_LINE="${NAME} Lv.${LEVEL} *EVOLVING*"
+else
+  INFO_LINE="${NAME} Lv.${LEVEL}"
+fi
+
+# ── If sprite hidden, show minimal text-only ────────────────
+if [ "$SPRITE_HIDDEN" = "true" ]; then
+  # Left info only, no sprite
+  LEFT=""
+  [ -n "$CC_MODEL" ] && LEFT="${CYAN}${CC_MODEL}${NC}"
+  [ -n "$CC_CONTEXT" ] && LEFT="${LEFT:+${LEFT} ${GRAY}·${NC} }${GREEN}${CC_CONTEXT}${NC}"
+
+  SPACER=""
+  RIGHT_PAD=$(( COLS - ${#INFO_LINE} - 4 ))
+  [ "$RIGHT_PAD" -lt 0 ] && RIGHT_PAD=0
+  for (( i=0; i<RIGHT_PAD; i++ )); do SPACER+="$B"; done
+
+  echo "${LEFT}"
+  echo "${SPACER}${INFO_LINE}"
+  exit 0
+fi
+
+# ── Load sprite ─────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SPRITE_DIR="$SCRIPT_DIR/../sprites/colorscripts/small"
+NAME_LOWER=$(echo "$NAME" | tr '[:upper:]' '[:lower:]' | sed "s/♀/-f/;s/♂/-m/;s/'//;s/\. /-/;s/ /-/")
+SPRITE_FILE="$SPRITE_DIR/${SPECIES_ID}-${NAME_LOWER}.txt"
+
+[ -f "$SPRITE_FILE" ] || exit 0
+
+mapfile -t SPRITE_LINES < "$SPRITE_FILE"
+
+# Strip empty lines
+while [ ${#SPRITE_LINES[@]} -gt 0 ] && [ -z "${SPRITE_LINES[0]}" ]; do
+  SPRITE_LINES=("${SPRITE_LINES[@]:1}")
+done
+while [ ${#SPRITE_LINES[@]} -gt 0 ] && [ -z "${SPRITE_LINES[-1]}" ]; do
+  unset 'SPRITE_LINES[-1]'
+done
+
+# Trim to max 8 sprite lines (top = head)
+MAX_SPRITE=8
+if [ ${#SPRITE_LINES[@]} -gt "$MAX_SPRITE" ]; then
+  SPRITE_LINES=("${SPRITE_LINES[@]:0:$MAX_SPRITE}")
+fi
+
+SPRITE_COUNT=${#SPRITE_LINES[@]}
+[ "$SPRITE_COUNT" -eq 0 ] && exit 0
+
+# ── Sprite width ────────────────────────────────────────────
+ART_W=0
+for line in "${SPRITE_LINES[@]}"; do
+  stripped=$(echo -e "$line" | sed 's/\x1b\[[0-9;]*m//g')
+  w=${#stripped}
+  [ "$w" -gt "$ART_W" ] && ART_W=$w
+done
+[ "$ART_W" -lt 5 ] && ART_W=12
+
+# ── Build left-side lines ───────────────────────────────────
+# Line 1: model · context left
+LEFT_1=""
+[ -n "$CC_MODEL" ] && LEFT_1="${CYAN}${CC_MODEL}${NC}"
+[ -n "$CC_CONTEXT" ] && LEFT_1="${LEFT_1:+${LEFT_1} ${GRAY}·${NC} }${GREEN}${CC_CONTEXT}${NC}"
+
+# Line 2: (empty)
+LEFT_2=""
+
+# Line 3: buddy speech (rotates every 10s, or shows reaction)
+SPEECH=""
+if [ -n "$ENCOUNTER" ]; then
+  # Wild encounter takes priority — flash to get attention
+  SPEECH="! ${ENCOUNTER} Use /buddy catch !"
+elif [ -n "$REACTION" ]; then
+  SPEECH="$REACTION"
+else
+  NOW=$(date +%s)
+  IDX=$(( (NOW / 30) % 12 ))
+  SPEECHES=(
+    "*${NAME} looks at your code curiously*"
+    ""
+    "*${NAME} nods along as you type*"
+    ""
+    "*${NAME} is watching closely*"
+    ""
+    "*${NAME} hums softly*"
+    ""
+    "*${NAME} stretches and yawns*"
+    ""
+    "*${NAME} bounces excitedly*"
+    ""
+  )
+  SPEECH="${SPEECHES[$IDX]}"
+fi
+if [ -n "$ENCOUNTER" ]; then
+  # Bright yellow for encounter alerts
+  SPEECH_COLOR=$'\033[1;38;2;255;220;50m'
+else
+  # Warm muted for idle speech
+  SPEECH_COLOR=$'\033[38;2;180;180;120m'
+fi
+LEFT_3="${SPEECH_COLOR}${SPEECH}${NC}"
+
+# ── Merge left + right ──────────────────────────────────────
+TOTAL_LINES=$SPRITE_COUNT
+
+RIGHT_MARGIN=4
+RIGHT_PAD=$(( COLS - ART_W - RIGHT_MARGIN ))
+[ "$RIGHT_PAD" -lt 0 ] && RIGHT_PAD=0
+
+# Build left array — line 1: model+context, line 2: buddy speech, rest empty
+LEFT_LINES=()
+LEFT_LINES+=("$LEFT_1")  # line 1: model · context
+LEFT_LINES+=("$LEFT_3")  # line 2: buddy speech
+
+# Pad rest with empty lines
+while [ ${#LEFT_LINES[@]} -lt "$TOTAL_LINES" ]; do
+  LEFT_LINES+=("")
+done
+LEFT_COUNT=${#LEFT_LINES[@]}
+
+# ── Build full right-side spacer ─────────────────────────────
+FULL_SPACER=""
+for (( s=0; s<RIGHT_PAD; s++ )); do FULL_SPACER+="$B"; done
+
+# ── Output name line ABOVE sprite ────────────────────────────
+echo "${FULL_SPACER}${INFO_LINE}"
+
+# ── Output sprite lines (right-aligned, left content merged) ──
+for (( i=0; i<SPRITE_COUNT; i++ )); do
+  left="${LEFT_LINES[$i]}"
+  left_visible=$(echo -e "$left" | sed 's/\x1b\[[0-9;]*m//g')
+  left_w=${#left_visible}
+
+  right="${SPRITE_LINES[$i]}${NC}"
+
+  if [ -n "$left" ]; then
+    gap=$(( RIGHT_PAD - left_w ))
+    [ "$gap" -lt 1 ] && gap=1
+    GAP_STR=""
+    for (( g=0; g<gap; g++ )); do GAP_STR+="$B"; done
+    echo "${left}${GAP_STR}${right}"
+  else
+    echo "${FULL_SPACER}${right}"
+  fi
+done
+
+
+exit 0