novac 2.3.0 → 2.4.0

package/kits/kitpet/kitdef.js

@@ -0,0 +1,752 @@
+'use strict';
+
+/**
+ * kitpet — Persistent terminal pet (Tamagotchi-style)
+ *
+ * Your pet lives on disk between sessions. It gets hungry, bored, tired,
+ * and dirty if you neglect it. Take care of it and it levels up.
+ *
+ * kitdef API (same contract as kitarcade):
+ *   .start()        load or hatch a new pet
+ *   .input(key)     'f'=feed 'p'=play 's'=sleep 'b'=bath 'm'=medicine
+ *                   'n'=name  'enter'/'space'=interact  'escape'=cancel
+ *   .tick(dt)       advance time (pass real dt; pet also ages on real-world time)
+ *   .frame()        → ANSI string
+ *   .state          → 'idle'|'playing'|'sleeping'|'sick'|'dead'|'hatching'
+ *   .score          → pet happiness score
+ *   .on(ev, fn)     events: 'levelup' 'death' 'hatch' 'score'
+ *
+ * Quick-start:
+ *   const { kitdef } = require('./kitpet');
+ *   const { RunGame } = require('./run_game');
+ *   RunGame(kitdef.Pet({ savePath: './mypet.json' }));
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// ─── ANSI UTILS ──────────────────────────────────────────────────────────────
+
+const FC = {
+  blk:30,red:31,grn:32,yel:33,blu:34,mag:35,cyn:36,wht:37,
+  BLK:90,RED:91,GRN:92,YEL:93,BLU:94,MAG:95,CYN:96,WHT:97,
+};
+const BC = {
+  blk:40,red:41,grn:42,yel:43,blu:44,mag:45,cyn:46,wht:47,
+  BLK:100,RED:101,GRN:102,YEL:103,BLU:104,MAG:105,CYN:106,WHT:107,
+};
+const RST = '\x1b[0m';
+const BLD = '\x1b[1m';
+
+function fc(c, s) { return `\x1b[${c}m${s}${RST}`; }
+function bc(c, s) { return `\x1b[${c}m${s}${RST}`; }
+function bold(s)  { return `${BLD}${s}${RST}`; }
+
+function makeCanvas(W, H) {
+  const ch = Array.from({length:H}, () => new Array(W).fill(' '));
+  const fg = Array.from({length:H}, () => new Array(W).fill(FC.wht));
+  const bg = Array.from({length:H}, () => new Array(W).fill(BC.blk));
+  const cv = {
+    W, H,
+    clear(c=' ', f=FC.wht, b=BC.blk) {
+      for (let y=0;y<H;y++) for (let x=0;x<W;x++) { ch[y][x]=c;fg[y][x]=f;bg[y][x]=b; }
+    },
+    set(x, y, c, f=FC.wht, b=BC.blk) {
+      if (x<0||x>=W||y<0||y>=H) return;
+      ch[y][x]=(String(c)[0])||' '; fg[y][x]=f; bg[y][x]=b;
+    },
+    put(x, y, s, f=FC.wht, b=BC.blk) {
+      for (let i=0;i<s.length;i++) cv.set(x+i, y, s[i], f, b);
+    },
+    fill(x, y, w, h, c, f=FC.wht, b=BC.blk) {
+      for (let dy=0;dy<h;dy++) for (let dx=0;dx<w;dx++) cv.set(x+dx,y+dy,c,f,b);
+    },
+    box(x, y, w, h, f=FC.wht, b=BC.blk) {
+      cv.put(x, y, '┌'+'─'.repeat(w-2)+'┐', f, b);
+      for (let dy=1;dy<h-1;dy++) { cv.set(x,y+dy,'│',f,b); cv.set(x+w-1,y+dy,'│',f,b); }
+      cv.put(x, y+h-1, '└'+'─'.repeat(w-2)+'┘', f, b);
+    },
+    render() {
+      const lines = [];
+      for (let y=0;y<H;y++) {
+        let row='', cf=-1, cb=-1;
+        for (let x=0;x<W;x++) {
+          const f=fg[y][x], b=bg[y][x];
+          if (f!==cf||b!==cb) { row+=`\x1b[${f};${b}m`; cf=f; cb=b; }
+          row+=ch[y][x];
+        }
+        lines.push(row+RST);
+      }
+      return lines.join('\n');
+    },
+  };
+  return cv;
+}
+
+function makeEmitter() {
+  const L = new Map();
+  return {
+    on(ev,fn)  { if(!L.has(ev)) L.set(ev,[]); L.get(ev).push(fn); },
+    off(ev,fn) { if(L.has(ev)) L.set(ev,L.get(ev).filter(f=>f!==fn)); },
+    emit(ev,...a) { (L.get(ev)??[]).forEach(fn=>fn(...a)); },
+  };
+}
+
+const rng = n => Math.random()*n|0;
+const clamp = (x,lo,hi) => Math.max(lo,Math.min(hi,x));
+const bar = (val, max, len, filledChar='█', emptyChar='░') => {
+  const filled = Math.round(val/max*len);
+  return filledChar.repeat(filled) + emptyChar.repeat(len-filled);
+};
+
+// ─── PET SPRITES ─────────────────────────────────────────────────────────────
+// Each sprite is an array of lines. Multiple frames for animation.
+
+const SPRITES = {
+  egg: [
+    [
+      '   .~~~.   ',
+      '  /     \\  ',
+      ' |  ~~~  | ',
+      ' |       | ',
+      '  \\ ._. /  ',
+      '   \\___/   ',
+    ],
+  ],
+  happy: [
+    [
+      '  (=^.^=)  ',
+      '  (       )',
+      '  (  u u  )',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|     |_)',
+    ],
+    [
+      '  (=^.^=)  ',
+      '  (       )',
+      '  (  u u  )',
+      '   \\     / ',
+      ' \\(|     |)/',
+      '   |     |  ',
+    ],
+  ],
+  idle: [
+    [
+      '  (-_- )   ',
+      '  (      ) ',
+      '  ( o o ) ',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|     |_)',
+    ],
+    [
+      '  (-_- )   ',
+      '  (      ) ',
+      '  ( - - ) ',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|     |_)',
+    ],
+  ],
+  eating: [
+    [
+      '  (^o^ )   ',
+      '  (      ) ',
+      '  ( o o ) ',
+      '   \\     / ',
+      '  /| nom |\\ ',
+      ' (_|     |_)',
+    ],
+    [
+      '  (^O^ )   ',
+      '  (      ) ',
+      '  ( o o ) ',
+      '   \\     / ',
+      '  /| NOM |\\ ',
+      ' (_|     |_)',
+    ],
+  ],
+  playing: [
+    [
+      '  (^  ^ )  ',
+      '  (      ) ',
+      '  ( ^ ^ ) ',
+      '   \\     / ',
+      ' \\(|     |)/',
+      '   \\     /  ',
+    ],
+    [
+      '  ( ^  ^)  ',
+      '  (      ) ',
+      '  ( ^ ^ ) ',
+      '   \\     / ',
+      '/(|     |)\\',
+      '   \\     /  ',
+    ],
+  ],
+  sleeping: [
+    [
+      '  (-_- )   ',
+      '  (  zzz   ',
+      '  ( - - )  ',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|_____|_)',
+    ],
+    [
+      '  (-_- )   ',
+      '  (   Zzz  ',
+      '  ( - - )  ',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|_____|_)',
+    ],
+  ],
+  sick: [
+    [
+      '  (@_@ )   ',
+      '  (      ) ',
+      '  ( x x ) ',
+      '   \\     / ',
+      '  /|  ~  |\\ ',
+      ' (_|     |_)',
+    ],
+  ],
+  dirty: [
+    [
+      '  (*_* )   ',
+      '  ( .    ) ',
+      '  ( o o ) ',
+      '   \\ . . / ',
+      '  /| . . |\\ ',
+      ' (_|  .  |_)',
+    ],
+  ],
+  dead: [
+    [
+      '  (x_x )   ',
+      '  (      ) ',
+      '  ( x x ) ',
+      '   \\     / ',
+      '  /|     |\\ ',
+      ' (_|     |_)',
+    ],
+  ],
+  bathing: [
+    [
+      '  (o_o )   ',
+      ' ~(      )~',
+      ' ~( o o )~ ',
+      ' ~ \\   / ~ ',
+      '~~/|   |\\~~',
+      '  (_   _)  ',
+    ],
+    [
+      '  (^_^ )   ',
+      '~~ (    )~~',
+      '~~ ( o o)~~',
+      '~~  \\   /~~',
+      '~~/|   |\\~~',
+      '  (_   _)  ',
+    ],
+  ],
+};
+
+// ─── FOOD / ITEM TABLES ───────────────────────────────────────────────────────
+
+const FOODS = [
+  { name: 'Apple',   hunger: 20, happy:  5, icon: '🍎' },
+  { name: 'Pizza',   hunger: 40, happy: 15, icon: '🍕' },
+  { name: 'Cake',    hunger: 30, happy: 25, icon: '🎂' },
+  { name: 'Salad',   hunger: 15, happy:  2, icon: '🥗' },
+  { name: 'Ramen',   hunger: 45, happy: 20, icon: '🍜' },
+  { name: 'Donut',   hunger: 25, happy: 30, icon: '🍩' },
+];
+
+const GAMES_LIST = [
+  { name: 'Fetch',   happy: 20, energy: -15, icon: '🎾' },
+  { name: 'Chase',   happy: 25, energy: -20, icon: '🏃' },
+  { name: 'Puzzle',  happy: 15, energy: -10, icon: '🧩' },
+  { name: 'Dance',   happy: 30, energy: -25, icon: '💃' },
+];
+
+const NAMES = [
+  'Byte','Pixel','Noodle','Mochi','Glitch','Boop','Fuzz','Blob',
+  'Chip','Widget','Snoot','Doodle','Kiwi','Pebble','Ziggy','Flux',
+];
+
+// ─── PERSISTENCE ─────────────────────────────────────────────────────────────
+
+function defaultSavePath(opts) {
+  return opts?.savePath ?? path.join(os.homedir(), '.kitpet.json');
+}
+
+function loadPet(savePath) {
+  try {
+    const raw = fs.readFileSync(savePath, 'utf8');
+    return JSON.parse(raw);
+  } catch { return null; }
+}
+
+function savePet(savePath, data) {
+  try { fs.writeFileSync(savePath, JSON.stringify(data, null, 2), 'utf8'); } catch {}
+}
+
+// ─── OFFLINE AGING ───────────────────────────────────────────────────────────
+// When you re-open kitpet after being away, real time has passed.
+// We simulate what happened (hunger/boredom/dirtiness) at a compressed rate.
+
+function applyOfflineTime(pet) {
+  const now    = Date.now();
+  const elapsed = Math.min((now - pet.lastSeen) / 1000, 3600 * 8); // cap at 8 hrs
+  if (elapsed < 10) return;
+
+  // rates per second (offline is gentler so you don't always come back to a dead pet)
+  const hungerRate  = 0.5;   // hunger points per second
+  const boredRate   = 0.3;
+  const dirtyRate   = 0.2;
+  const energyRate  = -0.1;  // energy trickles back while resting
+
+  pet.hunger  = clamp(pet.hunger  - elapsed * hungerRate, 0, 100);
+  pet.happy   = clamp(pet.happy   - elapsed * boredRate,  0, 100);
+  pet.clean   = clamp(pet.clean   - elapsed * dirtyRate,  0, 100);
+  pet.energy  = clamp(pet.energy  + elapsed * energyRate, 0, 100);
+  pet.age    += elapsed / 60; // age in minutes
+
+  pet.offlineMsg = `Away ${(elapsed/60).toFixed(0)}m — hunger, mood, cleanliness dropped.`;
+}
+
+// ─── MAKE PET ─────────────────────────────────────────────────────────────────
+
+function makePet(opts = {}) {
+  const savePath = defaultSavePath(opts);
+  const em       = makeEmitter();
+
+  // ── state ──────────────────────────────────────────────────────────────────
+
+  let pet;          // the persisted data object
+  let state;        // current game state string
+  let animFrame;    // current sprite frame index
+  let animTimer;    // ms until next frame flip
+  let tickElapsed;  // accumulator for stat decay
+  let msgQueue;     // [ { text, ttl } ]  — status messages
+  let subMenu;      // null | { type:'food'|'play'|'name', idx:0 }
+  let inputBuf;     // for name entry
+  let score;        // happiness score (accumulates over life)
+  let frameCount;
+
+  function newPetData() {
+    return {
+      name:    NAMES[rng(NAMES.length)],
+      species: ['Cat','Dog','Dragon','Bunny','Ghost'][rng(5)],
+      hunger:  80,   // 0=starving 100=full
+      happy:   80,   // 0=sad 100=ecstatic
+      energy:  80,   // 0=exhausted 100=rested
+      clean:   90,   // 0=filthy 100=spotless
+      health:  100,  // 0=dead 100=perfect
+      age:     0,    // minutes since hatch
+      level:   1,
+      xp:      0,
+      xpNext:  100,
+      hatchTime: Date.now(),
+      lastSeen:  Date.now(),
+      totalScore: 0,
+      alive:  true,
+      hatched: false,
+    };
+  }
+
+  function start() {
+    const saved = loadPet(savePath);
+    if (saved && saved.alive) {
+      pet = saved;
+      applyOfflineTime(pet);
+      if (pet.offlineMsg) { pushMsg(pet.offlineMsg, 4000); }
+    } else {
+      pet = newPetData();
+      pushMsg(`${pet.name} the ${pet.species} has hatched! 🥚`, 3000);
+      pet.hatched = true;
+      em.emit('hatch', pet);
+    }
+    state       = pet.hatched ? (pet.alive ? 'idle' : 'dead') : 'hatching';
+    animFrame   = 0;
+    animTimer   = 500;
+    tickElapsed = 0;
+    msgQueue    = [];
+    subMenu     = null;
+    inputBuf    = '';
+    score       = pet.totalScore;
+    frameCount  = 0;
+  }
+
+  function save() {
+    pet.lastSeen   = Date.now();
+    pet.totalScore = score;
+    savePet(savePath, pet);
+  }
+
+  // ── messages ───────────────────────────────────────────────────────────────
+
+  function pushMsg(text, ttl = 2000) {
+    msgQueue.unshift({ text, ttl });
+    if (msgQueue.length > 5) msgQueue.pop();
+  }
+
+  // ── stat helpers ───────────────────────────────────────────────────────────
+
+  function gainXP(n) {
+    pet.xp += n;
+    while (pet.xp >= pet.xpNext) {
+      pet.xp    -= pet.xpNext;
+      pet.level += 1;
+      pet.xpNext = pet.level * 100;
+      pushMsg(`⬆️  ${pet.name} reached level ${pet.level}!`, 3000);
+      em.emit('levelup', pet.level);
+    }
+  }
+
+  function currentSprite() {
+    if (!pet.hatched) return 'egg';
+    if (!pet.alive)   return 'dead';
+    if (state === 'sleeping') return 'sleeping';
+    if (state === 'eating')   return 'eating';
+    if (state === 'playing')  return 'playing';
+    if (state === 'bathing')  return 'bathing';
+    if (pet.health < 30)      return 'sick';
+    if (pet.clean  < 30)      return 'dirty';
+    if (pet.happy  > 70)      return 'happy';
+    return 'idle';
+  }
+
+  // ── actions ────────────────────────────────────────────────────────────────
+
+  function feed(foodIdx) {
+    const food = FOODS[foodIdx ?? rng(FOODS.length)];
+    if (pet.hunger >= 95) { pushMsg(`${pet.name} is already full!`); return; }
+    pet.hunger = clamp(pet.hunger + food.hunger, 0, 100);
+    pet.happy  = clamp(pet.happy  + food.happy,  0, 100);
+    gainXP(10);
+    score += food.happy;
+    em.emit('score', score);
+    pushMsg(`${pet.name} ate ${food.icon} ${food.name}! Yum!`);
+    state = 'eating';
+    setTimeout(() => { if (state === 'eating') state = 'idle'; }, 1500);
+    save();
+  }
+
+  function play(gameIdx) {
+    const g = GAMES_LIST[gameIdx ?? rng(GAMES_LIST.length)];
+    if (pet.energy < 20) { pushMsg(`${pet.name} is too tired to play!`); return; }
+    if (pet.health < 20) { pushMsg(`${pet.name} is too sick to play!`); return; }
+    pet.happy  = clamp(pet.happy  + g.happy,  0, 100);
+    pet.energy = clamp(pet.energy + g.energy, 0, 100);
+    gainXP(15);
+    score += g.happy;
+    em.emit('score', score);
+    pushMsg(`${pet.name} played ${g.icon} ${g.name}! So fun!`);
+    state = 'playing';
+    setTimeout(() => { if (state === 'playing') state = 'idle'; }, 2000);
+    save();
+  }
+
+  function sleep() {
+    if (state === 'sleeping') {
+      pushMsg(`${pet.name} woke up!`);
+      state = 'idle'; save(); return;
+    }
+    pushMsg(`${pet.name} is going to sleep... 💤`);
+    state = 'sleeping';
+    save();
+  }
+
+  function bathe() {
+    if (pet.clean >= 95) { pushMsg(`${pet.name} is already clean!`); return; }
+    pet.clean  = 100;
+    pet.health = clamp(pet.health + 10, 0, 100);
+    gainXP(8);
+    score += 10;
+    pushMsg(`${pet.name} had a bath! Squeaky clean! 🛁`);
+    state = 'bathing';
+    setTimeout(() => { if (state === 'bathing') state = 'idle'; }, 2000);
+    save();
+  }
+
+  function medicine() {
+    if (pet.health >= 90) { pushMsg(`${pet.name} doesn't need medicine.`); return; }
+    pet.health = clamp(pet.health + 30, 0, 100);
+    gainXP(5);
+    pushMsg(`${pet.name} took medicine! 💊 Feeling better.`);
+    save();
+  }
+
+  function rename(newName) {
+    const old = pet.name;
+    pet.name = newName || NAMES[rng(NAMES.length)];
+    pushMsg(`Renamed ${old} → ${pet.name}!`);
+    save();
+  }
+
+  // ── stat decay (called each tick) ─────────────────────────────────────────
+
+  function decayStats(dt) {
+    tickElapsed += dt;
+    if (tickElapsed < 2000) return; // decay every 2 real seconds
+    const secs = tickElapsed / 1000;
+    tickElapsed = 0;
+
+    if (state === 'sleeping') {
+      pet.energy = clamp(pet.energy + secs * 3, 0, 100);
+      pet.hunger = clamp(pet.hunger - secs * 0.2, 0, 100);
+      return;
+    }
+
+    pet.hunger = clamp(pet.hunger - secs * 1.2, 0, 100);
+    pet.happy  = clamp(pet.happy  - secs * 0.8, 0, 100);
+    pet.energy = clamp(pet.energy - secs * 0.5, 0, 100);
+    pet.clean  = clamp(pet.clean  - secs * 0.4, 0, 100);
+    pet.age   += secs / 60;
+
+    // health consequences
+    if (pet.hunger < 15) pet.health = clamp(pet.health - secs * 1.5, 0, 100);
+    if (pet.clean  < 20) pet.health = clamp(pet.health - secs * 0.8, 0, 100);
+    if (pet.energy <  5) pet.health = clamp(pet.health - secs * 0.5, 0, 100);
+
+    // passive health recovery when all stats are decent
+    if (pet.hunger > 50 && pet.clean > 50 && pet.energy > 40) {
+      pet.health = clamp(pet.health + secs * 0.3, 0, 100);
+    }
+
+    // spontaneous mood messages
+    if (rng(120) === 0) {
+      const moods = [
+        pet.hunger < 30 && `${pet.name} is hungry... 🍽️`,
+        pet.happy  < 30 && `${pet.name} looks bored. Play with them!`,
+        pet.clean  < 30 && `${pet.name} is getting smelly... 🦨`,
+        pet.energy < 20 && `${pet.name} is exhausted! Let them sleep.`,
+        pet.health < 40 && `${pet.name} doesn't look well... 💊`,
+        pet.happy  > 80 && `${pet.name} is doing a happy wiggle! 🎉`,
+      ].filter(Boolean);
+      if (moods.length) pushMsg(moods[rng(moods.length)], 3000);
+    }
+
+    // death check
+    if (pet.health <= 0) {
+      pet.alive = false;
+      state = 'dead';
+      pushMsg(`💀 ${pet.name} has passed away... Press ENTER to hatch a new egg.`, 99999);
+      em.emit('death', pet);
+      save();
+    }
+
+    // score accumulates while pet is happy/healthy
+    const wellBeing = (pet.hunger + pet.happy + pet.energy + pet.clean + pet.health) / 5;
+    score += (wellBeing / 100) | 0;
+    em.emit('score', score);
+    save();
+  }
+
+  // ── input ──────────────────────────────────────────────────────────────────
+
+  function input(key) {
+    if (state === 'dead') {
+      if (key === 'enter' || key === 'space') {
+        pet = newPetData();
+        pushMsg(`A new ${pet.species} has hatched! 🥚`, 3000);
+        state = 'idle'; save();
+      }
+      return;
+    }
+
+    // name entry mode
+    if (subMenu?.type === 'name') {
+      if (key === 'escape') { subMenu = null; inputBuf = ''; return; }
+      if (key === 'enter')  { rename(inputBuf); subMenu = null; inputBuf = ''; return; }
+      if (key === 'backspace') { inputBuf = inputBuf.slice(0,-1); return; }
+      if (key.length === 1 && inputBuf.length < 12) { inputBuf += key; return; }
+      return;
+    }
+
+    // sub-menu navigation (food / play)
+    if (subMenu) {
+      const list = subMenu.type === 'food' ? FOODS : GAMES_LIST;
+      if (key === 'escape')           { subMenu = null; return; }
+      if (key === 'up')               { subMenu.idx = (subMenu.idx - 1 + list.length) % list.length; return; }
+      if (key === 'down')             { subMenu.idx = (subMenu.idx + 1) % list.length; return; }
+      if (key === 'enter' || key === 'space') {
+        if (subMenu.type === 'food')  feed(subMenu.idx);
+        else                          play(subMenu.idx);
+        subMenu = null;
+      }
+      return;
+    }
+
+    // main controls
+    if (key === 'f')                    { subMenu = { type:'food', idx:0 }; return; }
+    if (key === 'p')                    { subMenu = { type:'play', idx:0 }; return; }
+    if (key === 's')                    { sleep(); return; }
+    if (key === 'b')                    { bathe(); return; }
+    if (key === 'm')                    { medicine(); return; }
+    if (key === 'n')                    { subMenu = { type:'name' }; inputBuf = ''; return; }
+    if (key === 'enter'||key==='space') {
+      // generic interact — gives a random small happy boost
+      pet.happy = clamp(pet.happy + 5, 0, 100);
+      const pats = [`${pet.name} purrs!`, `${pet.name} wags their tail!`,
+                    `${pet.name} nuzzles you!`, `*pat pat*`];
+      pushMsg(pats[rng(pats.length)]);
+    }
+  }
+
+  // ── tick ───────────────────────────────────────────────────────────────────
+
+  function tick(dt = 16) {
+    frameCount++;
+    animTimer -= dt;
+    if (animTimer <= 0) {
+      animTimer = 500;
+      const spr = SPRITES[currentSprite()];
+      animFrame = (animFrame + 1) % spr.length;
+    }
+
+    // decay messages
+    for (const m of msgQueue) m.ttl -= dt;
+    while (msgQueue.length && msgQueue[msgQueue.length-1].ttl <= 0) msgQueue.pop();
+
+    if (pet.alive) decayStats(dt);
+  }
+
+  // ── frame ──────────────────────────────────────────────────────────────────
+
+  function statBar(label, val, len=12) {
+    const pct = val / 100;
+    const col = pct > 0.6 ? FC.GRN : pct > 0.3 ? FC.YEL : FC.RED;
+    return `${label} \x1b[${col}m${bar(val,100,len)}\x1b[0m ${Math.round(val)}%`;
+  }
+
+  function frame() {
+    const W=62, H=28;
+    const cv = makeCanvas(W, H);
+    cv.clear(' ', FC.wht, BC.blk);
+
+    // ── header ──
+    const age = pet.age < 60
+      ? `${pet.age.toFixed(0)}m`
+      : `${(pet.age/60).toFixed(1)}h`;
+    cv.put(0, 0, ` 🐾 KITPET  ${pet.name} the ${pet.species}  Lv.${pet.level}  Age:${age}  Score:${score}`, FC.YEL, BC.blk);
+    cv.put(0, 1, '─'.repeat(W), FC.BLK, BC.blk);
+
+    // ── sprite ──
+    const sprKey = currentSprite();
+    const spr    = SPRITES[sprKey];
+    const frame_ = spr[animFrame % spr.length];
+    const sprCol = {
+      happy:FC.YEL, idle:FC.CYN, eating:FC.GRN, playing:FC.MAG,
+      sleeping:FC.BLU, sick:FC.RED, dirty:FC.yel, dead:FC.BLK,
+      bathing:FC.CYN, egg:FC.WHT,
+    }[sprKey] ?? FC.wht;
+
+    for (let i=0; i<frame_.length; i++) {
+      cv.put(2, i+3, frame_[i], sprCol, BC.blk);
+    }
+
+    // ── stats panel ──
+    const sx = 16;
+    cv.put(sx, 2, bold('── STATS ─────────────────'), FC.wht, BC.blk);
+    cv.put(sx, 3,  statBar('🍔 Hunger', pet.hunger), FC.wht, BC.blk);
+    cv.put(sx, 4,  statBar('😊 Happy ', pet.happy),  FC.wht, BC.blk);
+    cv.put(sx, 5,  statBar('⚡ Energy', pet.energy), FC.wht, BC.blk);
+    cv.put(sx, 6,  statBar('🧼 Clean ', pet.clean),  FC.wht, BC.blk);
+    cv.put(sx, 7,  statBar('❤️  Health', pet.health), FC.wht, BC.blk);
+
+    // xp bar
+    const xpPct = pet.xp / pet.xpNext;
+    cv.put(sx, 8, `XP ${bar(pet.xp, pet.xpNext, 20, '▰','▱')} ${pet.xp}/${pet.xpNext}`, FC.MAG, BC.blk);
+
+    // ── action menu ──
+    cv.put(sx, 10, bold('── ACTIONS ───────────────'), FC.wht, BC.blk);
+
+    if (subMenu?.type === 'name') {
+      cv.put(sx, 11, 'Enter new name:', FC.CYN, BC.blk);
+      cv.put(sx, 12, `> ${inputBuf}▌`, FC.WHT, BC.blk);
+      cv.put(sx, 13, 'ENTER confirm  ESC cancel', FC.BLK, BC.blk);
+    } else if (subMenu) {
+      const list = subMenu.type === 'food' ? FOODS : GAMES_LIST;
+      cv.put(sx, 11, subMenu.type === 'food' ? 'Choose food:' : 'Choose game:', FC.CYN, BC.blk);
+      for (let i=0; i<list.length; i++) {
+        const item = list[i];
+        const sel  = i === subMenu.idx;
+        const icon = item.icon ?? '•';
+        const label = `${sel?'▶':' '} ${icon} ${item.name}`;
+        cv.put(sx, 12+i, label, sel ? FC.YEL : FC.BLK, BC.blk);
+      }
+      cv.put(sx, 12+list.length+1, '↑↓ select  ENTER confirm  ESC back', FC.BLK, BC.blk);
+    } else {
+      const actions = [
+        '[F] Feed', '[P] Play', '[S] Sleep/Wake',
+        '[B] Bathe', '[M] Medicine', '[N] Rename',
+        '[SPACE] Pat',
+      ];
+      for (let i=0; i<actions.length; i++) {
+        cv.put(sx + (i%2)*22, 11 + (i>>1), actions[i], FC.wht, BC.blk);
+      }
+    }
+
+    // ── status / mood ──
+    cv.put(0, 16, '─'.repeat(W), FC.BLK, BC.blk);
+
+    // mood emoji line
+    const mood =
+      !pet.alive        ? '💀 Passed away...' :
+      state==='sleeping' ? '💤 Sleeping...' :
+      state==='eating'   ? '😋 Nom nom nom...' :
+      state==='playing'  ? '🎮 Playing!' :
+      state==='bathing'  ? '🛁 Splish splash!' :
+      pet.health < 30    ? '🤒 Not feeling well...' :
+      pet.clean  < 30    ? '🦨 Could use a bath...' :
+      pet.hunger < 25    ? '😰 Very hungry!' :
+      pet.happy  < 25    ? '😔 Feeling lonely...' :
+      pet.energy < 20    ? '😴 So sleepy...' :
+      pet.happy  > 80    ? '😄 Feeling great!' :
+                           '😌 Chilling.';
+    cv.put(1, 17, mood, FC.WHT, BC.blk);
+
+    // ── message log ──
+    cv.put(0, 18, '─'.repeat(W), FC.BLK, BC.blk);
+    for (let i=0; i<Math.min(msgQueue.length, 5); i++) {
+      const m = msgQueue[i];
+      const alpha = m.ttl > 1000 ? FC.WHT : FC.BLK;
+      cv.put(1, 19+i, m.text.slice(0,W-2), alpha, BC.blk);
+    }
+
+    // ── footer ──
+    cv.put(0, H-1, '─'.repeat(W), FC.BLK, BC.blk);
+    if (state === 'dead') {
+      cv.put(1, H-1, '  ENTER to hatch a new egg  ', FC.WHT, BC.red);
+    }
+
+    return cv.render();
+  }
+
+  return {
+    start, input, tick, frame, save,
+    on:  em.on.bind(em),
+    off: em.off.bind(em),
+    get state()  { return state; },
+    get score()  { return score; },
+    get pet()    { return pet;   },
+  };
+}
+
+// ─── EXPORT ──────────────────────────────────────────────────────────────────
+
+const kitdef = {
+  Pet: (opts) => {
+    const g = makePet(opts);
+    g.start();
+    return g;
+  },
+  makePet,
+};
+
+module.exports = { kitdef };