novac 2.3.0 → 2.4.0

package/kits/kitascii/kitdef.js

@@ -0,0 +1,839 @@
+'use strict';
+
+/**
+ * kitascii — ASCII / ANSI art toolkit
+ *
+ * Four tools in one kit:
+ *
+ *   kitdef.TextArt(opts)     Big ASCII-font text renderer (figlet-style)
+ *   kitdef.Animate(opts)     Preset ASCII animations (fire, matrix, starfield, plasma, rain)
+ *   kitdef.BoxArt(opts)      Interactive box / border / banner composer
+ *   kitdef.ImageToAscii(px)  Convert a 2-D pixel array to ASCII art (for use with sharp etc.)
+ *
+ * All four share the kitarcade API:
+ *   .start()  .input(key)  .tick(dt)  .frame()  .state  .score
+ *
+ * Quick-start (animation):
+ *   const { kitdef } = require('./kitascii');
+ *   const { RunGame } = require('./run_game');
+ *   RunGame(kitdef.Animate({ preset: 'matrix' }));
+ */
+
+// ─── ANSI / CANVAS ───────────────────────────────────────────────────────────
+
+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';
+const DIM = '\x1b[2m';
+
+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);
+    },
+    get(x, y) {
+      if (x<0||x>=W||y<0||y>=H) return [' ', FC.wht, BC.blk];
+      return [ch[y][x], fg[y][x], bg[y][x]];
+    },
+    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));
+
+// ─── FONT DATA ───────────────────────────────────────────────────────────────
+// 5-row tall block font. Each character is an array of 5 strings (rows).
+// Width varies per character.
+
+const FONT = {
+  ' ': ['   ','   ','   ','   ','   '],
+  'A': [' ██ ','█  █','████','█  █','█  █'],
+  'B': ['███ ','█  █','███ ','█  █','███ '],
+  'C': [' ███','█   ','█   ','█   ',' ███'],
+  'D': ['██  ','█ █ ','█  █','█  █','███ '],
+  'E': ['████','█   ','███ ','█   ','████'],
+  'F': ['████','█   ','███ ','█   ','█   '],
+  'G': [' ███','█   ','█ ██','█  █',' ███'],
+  'H': ['█  █','█  █','████','█  █','█  █'],
+  'I': ['███',' █ ',' █ ',' █ ','███'],
+  'J': ['  █','  █','  █','█ █',' █ '],
+  'K': ['█  █','█ █ ','██  ','█ █ ','█  █'],
+  'L': ['█   ','█   ','█   ','█   ','████'],
+  'M': ['█   █','██ ██','█ █ █','█   █','█   █'],
+  'N': ['█   █','██  █','█ █ █','█  ██','█   █'],
+  'O': [' ██ ','█  █','█  █','█  █',' ██ '],
+  'P': ['███ ','█  █','███ ','█   ','█   '],
+  'Q': [' ██ ','█  █','█  █','█ ██',' ███'],
+  'R': ['███ ','█  █','███ ','█ █ ','█  █'],
+  'S': [' ███','█   ',' ██ ','   █','███ '],
+  'T': ['████',' █  ',' █  ',' █  ',' █  '],
+  'U': ['█  █','█  █','█  █','█  █',' ██ '],
+  'V': ['█   █','█   █','█   █',' █ █ ','  █  '],
+  'W': ['█   █','█   █','█ █ █','██ ██','█   █'],
+  'X': ['█  █',' ██ ','  ██',' ██ ','█  █'],  // fixed
+  'Y': ['█  █','█  █',' ██ ',' █  ',' █  '],
+  'Z': ['████','  █ ',' █  ','█   ','████'],
+  '0': [' ██ ','█ ██','██ █','█  █',' ██ '],
+  '1': [' █ ','██ ',' █ ',' █ ','███'],
+  '2': [' ██ ','   █',' ██ ','█   ','████'],
+  '3': ['███ ','   █',' ██ ','   █','███ '],
+  '4': ['█  █','█  █','████','   █','   █'],
+  '5': ['████','█   ','███ ','   █','███ '],
+  '6': [' ██ ','█   ','███ ','█  █',' ██ '],
+  '7': ['████','   █','  █ ',' █  ',' █  '],
+  '8': [' ██ ','█  █',' ██ ','█  █',' ██ '],
+  '9': [' ██ ','█  █',' ███','   █',' ██ '],
+  '!': [' █ ',' █ ',' █ ','   ',' █ '],
+  '?': [' ██ ','   █',' ██ ','   ','  █ '],
+  '.': ['  ','  ','  ','  ',' █'],
+  ',': ['  ','  ','  ',' █','█ '],
+  ':': [' █','  ',' █','  ','  '],
+  '-': ['   ','   ','███','   ','   '],
+  '+': ['   ',' █ ','███',' █ ','   '],
+  '/': ['   █','  █ ',' █  ','█   ','    '],
+  '(': [' █','█ ','█ ','█ ',' █'],
+  ')': ['█ ',' █',' █',' █','█ '],
+  '#': [' █ █ ',' ████',' █ █ ',' ████',' █ █ '],
+  '@': [' ███ ','█   █','█ ██ ','█    ',' ███ '],
+  '*': ['     ','█ █ █',' ███ ','█ █ █','     '],
+};
+
+// ─── TEXT ART ─────────────────────────────────────────────────────────────────
+
+function makeTextArt(opts = {}) {
+  const em = makeEmitter();
+  const W = 80, H = 24;
+
+  let text, colorIdx, styleIdx, animTick, state, score;
+  let inputBuf, scrollX;
+
+  const COLORS = [
+    [FC.YEL, FC.yel],
+    [FC.CYN, FC.cyn],
+    [FC.GRN, FC.grn],
+    [FC.MAG, FC.mag],
+    [FC.RED, FC.red],
+    [FC.WHT, FC.BLK],
+    [FC.BLU, FC.blu],
+  ];
+
+  const STYLES = ['solid','shadow','outline','rainbow','wave','neon'];
+
+  const PRESETS = [
+    'HELLO', 'NOVA', 'KITASCII', 'ARCADE', 'PURCE',
+    '12345', 'CODE IS ART', 'HACK THE PLANET',
+  ];
+
+  function renderText(str, style, colors, tick) {
+    const rows = [[], [], [], [], []];
+    const chars = [...str.toUpperCase()];
+    for (let ci = 0; ci < chars.length; ci++) {
+      const ch = chars[ci];
+      const glyph = FONT[ch] ?? FONT[' '];
+      for (let row = 0; row < 5; row++) {
+        rows[row].push({ glyphRow: glyph[row], charIdx: ci });
+      }
+    }
+    return rows;
+  }
+
+  function start() {
+    text     = opts.text ?? PRESETS[rng(PRESETS.length)];
+    colorIdx = 0;
+    styleIdx = 0;
+    animTick = 0;
+    scrollX  = 0;
+    state    = 'playing';
+    score    = 0;
+    inputBuf = text;
+    em.emit('start');
+  }
+
+  function input(key) {
+    if (key === 'escape')     { return; }
+    if (key === 'up')         { colorIdx = (colorIdx + 1) % COLORS.length; return; }
+    if (key === 'down')       { colorIdx = (colorIdx - 1 + COLORS.length) % COLORS.length; return; }
+    if (key === 'left')       { styleIdx = (styleIdx - 1 + STYLES.length) % STYLES.length; return; }
+    if (key === 'right')      { styleIdx = (styleIdx + 1) % STYLES.length; return; }
+    if (key === 'tab')        { text = PRESETS[(PRESETS.indexOf(text)+1)%PRESETS.length]; inputBuf=text; return; }
+    if (key === 'backspace')  { inputBuf = inputBuf.slice(0,-1); text=inputBuf; return; }
+    if (key === 'enter')      { text = inputBuf || 'HELLO'; return; }
+    if (key.length === 1 && inputBuf.length < 16) { inputBuf += key.toUpperCase(); text=inputBuf; }
+  }
+
+  function tick(dt=16) {
+    animTick += dt;
+  }
+
+  function frame() {
+    const cv = makeCanvas(W, H);
+    cv.clear(' ', FC.wht, BC.blk);
+
+    const style  = STYLES[styleIdx];
+    const colors = COLORS[colorIdx];
+    const t      = animTick / 100;
+
+    // compute rendered glyph rows
+    const str    = (text || ' ').toUpperCase();
+    const chars  = [...str];
+    const glyphs = chars.map(c => FONT[c] ?? FONT[' ']);
+
+    // measure total width
+    let totalW = 0;
+    for (const g of glyphs) totalW += (g[0]?.length ?? 3) + 1;
+
+    const startX = Math.max(0, (W - totalW) >> 1);
+    const startY = 5;
+
+    let cx = startX;
+    for (let ci = 0; ci < glyphs.length; ci++) {
+      const glyph = glyphs[ci];
+      const gw    = glyph[0]?.length ?? 3;
+
+      for (let row = 0; row < 5; row++) {
+        const glyphRow = glyph[row] ?? '';
+        for (let gc = 0; gc < glyphRow.length; gc++) {
+          const ch = glyphRow[gc];
+          if (ch === ' ' || ch === '') continue;
+
+          const x = cx + gc;
+          const y = startY + row;
+
+          let col;
+          if (style === 'rainbow') {
+            const hue = (ci / glyphs.length + t * 0.2) % 1;
+            const palette = [FC.RED, FC.YEL, FC.GRN, FC.CYN, FC.BLU, FC.MAG];
+            col = palette[Math.floor(hue * palette.length)];
+          } else if (style === 'wave') {
+            const wave = Math.sin(t + ci * 0.8 + row * 0.3);
+            col = wave > 0.3 ? colors[0] : wave > -0.3 ? FC.WHT : colors[1];
+          } else if (style === 'neon') {
+            const pulse = Math.sin(t * 2 + ci * 0.5) > 0 ? colors[0] : FC.WHT;
+            col = pulse;
+          } else {
+            col = colors[row < 2 ? 0 : 1];
+          }
+
+          if (style === 'shadow') {
+            cv.set(x+1, y+1, '░', FC.BLK, BC.blk);
+          }
+          if (style === 'outline') {
+            for (const [dx,dy] of [[-1,0],[1,0],[0,-1],[0,1]]) {
+              cv.set(x+dx, y+dy, '▒', FC.BLK, BC.blk);
+            }
+          }
+
+          cv.set(x, y, '█', col, BC.blk);
+        }
+      }
+      cx += gw + 1;
+    }
+
+    // decorative border
+    const borderStyle = ['┌','─','┐','│','└','┘'][0];
+    cv.put(0, 0, '╔' + '═'.repeat(W-2) + '╗', FC.BLK, BC.blk);
+    cv.put(0, H-1, '╚' + '═'.repeat(W-2) + '╝', FC.BLK, BC.blk);
+    for (let y=1; y<H-1; y++) { cv.set(0,y,'║',FC.BLK,BC.blk); cv.set(W-1,y,'║',FC.BLK,BC.blk); }
+
+    // controls
+    cv.put(2, 1,  ` TEXT ART  ↑↓ color  ←→ style  TAB preset  Type to edit  ENTER set`, FC.YEL, BC.blk);
+    cv.put(2, 2,  ` Style: ${STYLES[styleIdx].padEnd(10)}  Color: ${colorIdx+1}/${COLORS.length}  Text: "${text}"`, FC.BLK, BC.blk);
+
+    // input display
+    const cursor = Math.floor(animTick/500)%2 === 0 ? '▌' : ' ';
+    cv.put(2, H-3, ` > ${inputBuf}${cursor}`.padEnd(W-3,' '), FC.CYN, BC.blk);
+    cv.put(2, H-2, ` BACKSPACE delete  ENTER render  TAB next preset`, FC.BLK, BC.blk);
+
+    return cv.render();
+  }
+
+  return { start, input, tick, frame,
+    on: em.on.bind(em), off: em.off.bind(em),
+    get state() { return state; }, get score() { return score; },
+  };
+}
+
+// ─── ANIMATIONS ──────────────────────────────────────────────────────────────
+
+function makeAnimate(opts = {}) {
+  const em = makeEmitter();
+  const W  = opts.width  ?? 80;
+  const H  = opts.height ?? 24;
+
+  const PRESETS = ['matrix','fire','starfield','plasma','rain','snow','worms'];
+  let presetIdx, t, state, score, speed;
+
+  // ── per-preset state ──
+  let matrix_cols, fire_buf, stars, worms;
+
+  function initPreset(name) {
+    t = 0;
+    if (name === 'matrix') {
+      // each column: { y (head position), speed, chars[] }
+      const KATAKANA = 'アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン';
+      matrix_cols = Array.from({length: W}, (_, x) => ({
+        y:     -rng(H),
+        speed: 0.3 + Math.random() * 0.7,
+        chars: Array.from({length: H+5}, () => KATAKANA[rng(KATAKANA.length)]),
+        bright: rng(H),
+      }));
+    }
+    if (name === 'fire') {
+      fire_buf = new Float32Array((W) * (H+2)).fill(0);
+    }
+    if (name === 'starfield') {
+      stars = Array.from({length: 120}, () => ({
+        x: (Math.random() * 2 - 1),
+        y: (Math.random() * 2 - 1),
+        z: Math.random(),
+      }));
+    }
+    if (name === 'worms') {
+      worms = Array.from({length: 8}, (_, i) => ({
+        x: rng(W), y: rng(H),
+        dx: (rng(3)-1)||1, dy: (rng(3)-1)||1,
+        col: [FC.GRN,FC.CYN,FC.MAG,FC.YEL,FC.RED,FC.BLU,FC.WHT,FC.grn][i],
+        tail: [],
+        tailLen: 12 + rng(20),
+      }));
+    }
+  }
+
+  function start() {
+    presetIdx = PRESETS.indexOf(opts.preset ?? 'matrix');
+    if (presetIdx < 0) presetIdx = 0;
+    speed  = opts.speed ?? 1;
+    state  = 'running';
+    score  = 0;
+    initPreset(PRESETS[presetIdx]);
+    em.emit('start');
+  }
+
+  function input(key) {
+    if (key === 'left'  || key === 'p') {
+      presetIdx = (presetIdx - 1 + PRESETS.length) % PRESETS.length;
+      initPreset(PRESETS[presetIdx]);
+    }
+    if (key === 'right' || key === 'n') {
+      presetIdx = (presetIdx + 1) % PRESETS.length;
+      initPreset(PRESETS[presetIdx]);
+    }
+    if (key === 'space')  { state = state === 'running' ? 'paused' : 'running'; }
+    if (key === '+' || key === '=') speed = clamp(speed + 0.2, 0.2, 3);
+    if (key === '-')                speed = clamp(speed - 0.2, 0.2, 3);
+    if (key === 'r')      { initPreset(PRESETS[presetIdx]); }
+  }
+
+  function tick(dt = 16) {
+    if (state !== 'running') return;
+    t += dt * speed / 1000;
+    score++;
+
+    const name = PRESETS[presetIdx];
+
+    if (name === 'matrix') {
+      for (const col of matrix_cols) {
+        col.y += col.speed * speed;
+        if (col.y > H + 5) {
+          col.y = -rng(H) - 3;
+          col.speed = 0.3 + Math.random() * 0.7;
+          col.bright = rng(H);
+          // refresh chars
+          const KATAKANA = 'アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン';
+          col.chars = Array.from({length: H+5}, () => KATAKANA[rng(KATAKANA.length)]);
+        }
+        // occasionally mutate a char
+        if (Math.random() < 0.05) {
+          const KATAKANA = 'アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン';
+          col.chars[rng(col.chars.length)] = KATAKANA[rng(KATAKANA.length)];
+        }
+      }
+    }
+
+    if (name === 'fire') {
+      // seed bottom row
+      for (let x=0; x<W; x++) {
+        fire_buf[(H+1)*W+x] = Math.random() < 0.6 ? 28 + rng(8) : 0;
+      }
+      // propagate upward
+      for (let y=H; y>=0; y--) {
+        for (let x=0; x<W; x++) {
+          const below = fire_buf[(y+1)*W+x];
+          const wind  = rng(3) - 1;
+          const decay = rng(3);
+          const tx    = clamp(x + wind, 0, W-1);
+          fire_buf[y*W+tx] = Math.max(0, below - decay);
+        }
+      }
+    }
+
+    if (name === 'starfield') {
+      for (const s of stars) {
+        s.z -= 0.01 * speed;
+        if (s.z <= 0) {
+          s.x = (Math.random() * 2 - 1);
+          s.y = (Math.random() * 2 - 1);
+          s.z = 1;
+        }
+      }
+    }
+
+    if (name === 'worms') {
+      for (const w of worms) {
+        w.tail.unshift([w.x, w.y]);
+        if (w.tail.length > w.tailLen) w.tail.pop();
+        // random direction change
+        if (Math.random() < 0.15) {
+          w.dx = (rng(3)-1);
+          w.dy = (rng(3)-1);
+          if (!w.dx && !w.dy) w.dx = 1;
+        }
+        w.x = clamp(w.x + w.dx, 0, W-1);
+        w.y = clamp(w.y + w.dy, 0, H-2);
+        if (w.x <= 0 || w.x >= W-1) w.dx = -w.dx;
+        if (w.y <= 0 || w.y >= H-2) w.dy = -w.dy;
+      }
+    }
+  }
+
+  function frame() {
+    const cv = makeCanvas(W, H);
+    cv.clear(' ', FC.wht, BC.blk);
+
+    const name = PRESETS[presetIdx];
+
+    // ── MATRIX ──
+    if (name === 'matrix') {
+      for (let x=0; x<W; x++) {
+        const col = matrix_cols[x];
+        const headY = Math.floor(col.y);
+        for (let y=0; y<H; y++) {
+          const dist = headY - y;
+          if (dist < 0 || dist > H) continue;
+          const charIdx = ((y - Math.floor(col.y - H)) + col.chars.length) % col.chars.length;
+          const ch = col.chars[charIdx] ?? '0';
+          if (dist === 0) {
+            cv.set(x, y, ch, FC.WHT, BC.blk); // bright head
+          } else if (dist < 3) {
+            cv.set(x, y, ch, FC.GRN, BC.blk);
+          } else if (dist < 8) {
+            cv.set(x, y, ch, FC.grn, BC.blk);
+          } else if (dist < 15) {
+            cv.set(x, y, ch, FC.BLK, BC.blk);
+          }
+        }
+      }
+    }
+
+    // ── FIRE ──
+    if (name === 'fire') {
+      const FIRE_CHARS  = ' .\'`^",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$';
+      const FIRE_COLORS = [
+        FC.BLK, FC.red, FC.red, FC.RED, FC.RED,
+        FC.yel, FC.YEL, FC.YEL, FC.WHT, FC.WHT,
+      ];
+      for (let y=0; y<H; y++) {
+        for (let x=0; x<W; x++) {
+          const v = fire_buf[y*W+x];
+          if (v <= 0) continue;
+          const vi  = clamp(Math.floor(v), 0, FIRE_CHARS.length-1);
+          const ci  = clamp(Math.floor(v / 35 * FIRE_COLORS.length), 0, FIRE_COLORS.length-1);
+          cv.set(x, y, FIRE_CHARS[vi], FIRE_COLORS[ci], BC.blk);
+        }
+      }
+    }
+
+    // ── STARFIELD ──
+    if (name === 'starfield') {
+      const STAR_CHARS = ['.', '+', '*', '✦', '★', '✸'];
+      for (const s of stars) {
+        const sx = Math.floor((s.x / s.z + 1) / 2 * W);
+        const sy = Math.floor((s.y / s.z + 1) / 2 * H);
+        if (sx < 0 || sx >= W || sy < 0 || sy >= H) continue;
+        const brightness = 1 - s.z;
+        const ci  = Math.floor(brightness * (STAR_CHARS.length-1));
+        const col = brightness > 0.8 ? FC.WHT : brightness > 0.5 ? FC.BLK : FC.BLK;
+        cv.set(sx, sy, STAR_CHARS[ci], col, BC.blk);
+      }
+      // center crosshair
+      cv.put((W>>1)-1, H>>1, '─┼─', FC.BLK, BC.blk);
+      cv.set(W>>1, (H>>1)-1, '│', FC.BLK, BC.blk);
+      cv.set(W>>1, (H>>1)+1, '│', FC.BLK, BC.blk);
+    }
+
+    // ── PLASMA ──
+    if (name === 'plasma') {
+      const PLASMA_CHARS = ' ░▒▓█';
+      const palettes = [
+        [FC.red,FC.RED,FC.yel,FC.YEL,FC.WHT],
+        [FC.blu,FC.BLU,FC.cyn,FC.CYN,FC.WHT],
+        [FC.mag,FC.MAG,FC.red,FC.RED,FC.WHT],
+        [FC.grn,FC.GRN,FC.yel,FC.YEL,FC.WHT],
+      ];
+      const pal = palettes[Math.floor(t*0.1) % palettes.length];
+      for (let y=0; y<H; y++) {
+        for (let x=0; x<W; x++) {
+          const v =
+            Math.sin(x / 6 + t) +
+            Math.sin(y / 3 + t * 0.7) +
+            Math.sin((x + y) / 9 + t * 0.5) +
+            Math.sin(Math.sqrt(((x-W/2)**2 + (y-H/2)**2)) / 4 + t);
+          const n  = (v + 4) / 8;
+          const ci = clamp(Math.floor(n * PLASMA_CHARS.length), 0, PLASMA_CHARS.length-1);
+          const fc = pal[clamp(Math.floor(n * pal.length), 0, pal.length-1)];
+          cv.set(x, y, PLASMA_CHARS[ci], fc, BC.blk);
+        }
+      }
+    }
+
+    // ── RAIN ──
+    if (name === 'rain') {
+      // simple: re-derive each frame from t
+      for (let x=0; x<W; x++) {
+        const offset = Math.sin(x * 1.7) * 10 + x * 0.3;
+        for (let y=0; y<H; y++) {
+          const drop = (y + offset + t * 8) % H;
+          if (drop < 1) {
+            cv.set(x, y, '│', FC.CYN, BC.blk);
+          } else if (drop < 3) {
+            cv.set(x, y, '│', FC.BLU, BC.blk);
+          } else if (drop < 5) {
+            cv.set(x, y, '╵', FC.blu, BC.blk);
+          }
+        }
+      }
+      // puddle bottom
+      for (let x=0; x<W; x++) {
+        const splash = Math.sin(t * 3 + x * 0.5) > 0.8;
+        cv.set(x, H-1, splash ? '~' : '_', FC.BLU, BC.blk);
+      }
+    }
+
+    // ── SNOW ──
+    if (name === 'snow') {
+      for (let x=0; x<W; x++) {
+        for (let y=0; y<H; y++) {
+          const drift  = Math.sin(t * 0.5 + x * 0.3 + y * 0.1) * 3;
+          const offset = x * 2.3 + y * 1.7 + drift;
+          const phase  = (t * 2 + offset) % H;
+          if (phase < 0.8) {
+            const ch = ['*','·','❄','❅'][rng(4)];
+            cv.set(x, y, ch, FC.WHT, BC.blk);
+          }
+        }
+      }
+      // snow pile
+      for (let x=0; x<W; x++) {
+        const pile = 1 + Math.floor(Math.sin(x * 0.3) * 1 + 1);
+        for (let p=0; p<pile; p++) cv.set(x, H-1-p, '▓', FC.WHT, BC.blk);
+      }
+    }
+
+    // ── WORMS ──
+    if (name === 'worms') {
+      for (const w of worms) {
+        for (let i=0; i<w.tail.length; i++) {
+          const [tx,ty] = w.tail[i];
+          const alpha = 1 - i / w.tail.length;
+          const ch = i===0 ? '●' : alpha > 0.5 ? '▪' : '·';
+          const col = i===0 ? FC.WHT : w.col;
+          cv.set(tx, ty, ch, col, BC.blk);
+        }
+      }
+    }
+
+    // ── HUD ──
+    const hud = ` ${name.toUpperCase().padEnd(10)} ← → change  SPACE pause  +/- speed  R reset`;
+    cv.put(0, 0, hud, FC.YEL, BC.blk);
+
+    return cv.render();
+  }
+
+  return { start, input, tick, frame,
+    on: em.on.bind(em), off: em.off.bind(em),
+    get state() { return state; }, get score() { return score; },
+  };
+}
+
+// ─── BOX ART ─────────────────────────────────────────────────────────────────
+
+function makeBoxArt(opts = {}) {
+  const em = makeEmitter();
+  const W  = 72, H = 28;
+
+  const BOX_STYLES = [
+    { name:'Single',  tl:'┌',tr:'┐',bl:'└',br:'┘',h:'─',v:'│',tee:'┬',bee:'┴',lef:'├',rig:'┤',crs:'┼' },
+    { name:'Double',  tl:'╔',tr:'╗',bl:'╚',br:'╝',h:'═',v:'║',tee:'╦',bee:'╩',lef:'╠',rig:'╣',crs:'╬' },
+    { name:'Thick',   tl:'┏',tr:'┓',bl:'┗',br:'┛',h:'━',v:'┃',tee:'┳',bee:'┻',lef:'┣',rig:'┫',crs:'╋' },
+    { name:'Rounded', tl:'╭',tr:'╮',bl:'╰',br:'╯',h:'─',v:'│',tee:'┬',bee:'┴',lef:'├',rig:'┤',crs:'┼' },
+    { name:'Ascii',   tl:'+',tr:'+',bl:'+',br:'+',h:'-',v:'|',tee:'+',bee:'+',lef:'+',rig:'+',crs:'+' },
+    { name:'Hash',    tl:'#',tr:'#',bl:'#',br:'#',h:'#',v:'#',tee:'#',bee:'#',lef:'#',rig:'#',crs:'#' },
+    { name:'Stars',   tl:'*',tr:'*',bl:'*',br:'*',h:'*',v:'*',tee:'*',bee:'*',lef:'*',rig:'*',crs:'*' },
+    { name:'Fancy',   tl:'╓',tr:'╖',bl:'╙',br:'╜',h:'─',v:'║',tee:'╥',bee:'╨',lef:'╟',rig:'╢',crs:'╫' },
+  ];
+
+  const FILLS = [' ', '░', '▒', '▓', '·', '∙', '•', '◦', '·'];
+  const FC_LIST = Object.values(FC);
+
+  let bx, by, bw, bh, styleIdx, fillIdx, fgIdx, bgIdx;
+  let title, inputBuf, inputMode;
+  let state, score;
+
+  function start() {
+    bx=4; by=4; bw=40; bh=14;
+    styleIdx=0; fillIdx=0; fgIdx=0; bgIdx=0;
+    title   = opts.title ?? 'MY BOX';
+    inputBuf= ''; inputMode=null;
+    state='playing'; score=0;
+    em.emit('start');
+  }
+
+  function input(key) {
+    if (inputMode) {
+      if (key==='escape')    { inputMode=null; inputBuf=''; return; }
+      if (key==='enter')     { title=inputBuf; inputMode=null; inputBuf=''; return; }
+      if (key==='backspace') { inputBuf=inputBuf.slice(0,-1); return; }
+      if (key.length===1 && inputBuf.length<30) { inputBuf+=key; return; }
+      return;
+    }
+    // resize
+    if (key==='right') bw = clamp(bw+2, 6, W-bx-2);
+    if (key==='left')  bw = clamp(bw-2, 6, W-bx-2);
+    if (key==='down')  bh = clamp(bh+1, 4, H-by-2);
+    if (key==='up')    bh = clamp(bh-1, 4, H-by-2);
+    // cycle options
+    if (key==='s') styleIdx = (styleIdx+1) % BOX_STYLES.length;
+    if (key==='f') fillIdx  = (fillIdx+1)  % FILLS.length;
+    if (key==='c') fgIdx    = (fgIdx+1)    % FC_LIST.length;
+    if (key==='b') bgIdx    = (bgIdx+1)    % Object.values(BC).length;
+    if (key==='t') { inputMode='title'; inputBuf=title; }
+    // move box
+    if (key==='w') by = clamp(by-1, 2, H-bh-2);
+    if (key==='a') bx = clamp(bx-1, 0, W-bw-2);
+    if (key==='z') by = clamp(by+1, 2, H-bh-2);
+    if (key==='x') bx = clamp(bx+1, 0, W-bw-2);
+    // export
+    if (key==='e') { score++; em.emit('score', score); }
+  }
+
+  function tick(dt=16) {}
+
+  function frame() {
+    const cv = makeCanvas(W, H);
+    cv.clear(' ', FC.wht, BC.blk);
+
+    cv.put(0, 0, ` BOX ART  S=style F=fill C=fg-color B=bg-color T=title  WASD/↑↓←→ move/resize  E=export`, FC.YEL, BC.blk);
+    cv.put(0, 1, '─'.repeat(W), FC.BLK, BC.blk);
+
+    const style   = BOX_STYLES[styleIdx];
+    const fill    = FILLS[fillIdx];
+    const fgColor = FC_LIST[fgIdx];
+    const bgVals  = Object.values(BC);
+    const bgColor = bgVals[bgIdx];
+
+    // fill interior
+    if (fillIdx > 0) {
+      cv.fill(bx+1, by+1, bw-2, bh-2, fill, fgColor, BC.blk);
+    }
+
+    // draw box
+    cv.set(bx,       by,       style.tl, fgColor, BC.blk);
+    cv.set(bx+bw-1,  by,       style.tr, fgColor, BC.blk);
+    cv.set(bx,       by+bh-1,  style.bl, fgColor, BC.blk);
+    cv.set(bx+bw-1,  by+bh-1,  style.br, fgColor, BC.blk);
+    for (let x=bx+1; x<bx+bw-1; x++) {
+      cv.set(x, by,       style.h, fgColor, BC.blk);
+      cv.set(x, by+bh-1,  style.h, fgColor, BC.blk);
+    }
+    for (let y=by+1; y<by+bh-1; y++) {
+      cv.set(bx,       y, style.v, fgColor, BC.blk);
+      cv.set(bx+bw-1,  y, style.v, fgColor, BC.blk);
+    }
+
+    // title
+    if (inputMode === 'title') {
+      const t = `[ ${inputBuf}▌ ]`;
+      const tx = bx + ((bw - t.length) >> 1);
+      cv.put(tx, by, t, FC.YEL, BC.blk);
+    } else if (title) {
+      const t = `[ ${title} ]`;
+      const tx = bx + ((bw - t.length) >> 1);
+      cv.put(tx, by, t, FC.YEL, BC.blk);
+    }
+
+    // info panel
+    const px = 1, py = H - 6;
+    cv.put(px, py,   `Style:  ${style.name.padEnd(10)}  tl:${style.tl} h:${style.h} v:${style.v}`, FC.wht, BC.blk);
+    cv.put(px, py+1, `Fill:   "${fill}"`, FC.wht, BC.blk);
+    cv.put(px, py+2, `Size:   ${bw}×${bh}  at ${bx},${by}`, FC.wht, BC.blk);
+    cv.put(px, py+3, `Exports: ${score}`, FC.BLK, BC.blk);
+    cv.put(px, py+4,
+      `\x1b[${fgColor}m████\x1b[0m FG   \x1b[${bgColor}m████\x1b[0m BG`, FC.wht, BC.blk);
+
+    return cv.render();
+  }
+
+  return { start, input, tick, frame,
+    on: em.on.bind(em), off: em.off.bind(em),
+    get state() { return state; }, get score() { return score; },
+  };
+}
+
+// ─── IMAGE → ASCII ───────────────────────────────────────────────────────────
+/**
+ * ImageToAscii(pixelGrid, opts)
+ *
+ * Converts a 2-D pixel grid to ASCII art string.
+ * pixelGrid: Array<Array<{r,g,b}>>  (rows of pixels)
+ *
+ * opts:
+ *   width:    target character width  (default 80)
+ *   color:    use ANSI colors          (default true)
+ *   charset:  'block'|'shade'|'ascii'|'braille' (default 'shade')
+ *   invert:   invert brightness       (default false)
+ *
+ * Returns: ANSI string ready to write to stdout.
+ *
+ * Example with jimp:
+ *   const Jimp = require('jimp');
+ *   const { ImageToAscii } = require('./kitascii');
+ *   const img = await Jimp.read('photo.jpg');
+ *   img.resize(80, 40);
+ *   const grid = [];
+ *   img.scan(0,0,img.width,img.height,(x,y,idx)=>{
+ *     if (!grid[y]) grid[y]=[];
+ *     grid[y][x]={ r:img.bitmap.data[idx], g:img.bitmap.data[idx+1], b:img.bitmap.data[idx+2] };
+ *   });
+ *   console.log(ImageToAscii(grid, { color:true }));
+ */
+
+const CHARSETS = {
+  shade:  ' ░▒▓█',
+  block:  ' ▏▎▍▌▋▊▉█',
+  ascii:  ' .\'`^",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$',
+  braille:'⠀⠁⠂⠃⠄⠅⠆⠇⠈⠉⠊⠋⠌⠍⠎⠏⠐⠑⠒⠓⠔⠕⠖⠗⠘⠙⠚⠛⠜⠝⠞⠟⠠⠡⠢⠣⠤⠥⠦⠧⠨⠩⠪⠫⠬⠭⠮⠯⠰⠱⠲⠳⠴⠵⠶⠷⠸⠹⠺⠻⠼⠽⠾⠿',
+  minimal:' ·∙•●',
+};
+
+function ImageToAscii(pixelGrid, opts = {}) {
+  if (!pixelGrid || !pixelGrid.length) return '';
+
+  const charset = CHARSETS[opts.charset ?? 'shade'];
+  const color   = opts.color   ?? true;
+  const invert  = opts.invert  ?? false;
+
+  const srcH  = pixelGrid.length;
+  const srcW  = pixelGrid[0].length;
+  const tgtW  = opts.width ?? 80;
+  // terminal chars are ~2:1 height:width, so scale height by 0.5
+  const tgtH  = Math.round(tgtW * (srcH / srcW) * 0.5);
+
+  const lines = [];
+
+  for (let ty = 0; ty < tgtH; ty++) {
+    let line = '';
+    const sy = Math.floor(ty / tgtH * srcH);
+    const row = pixelGrid[clamp(sy, 0, srcH-1)];
+
+    for (let tx = 0; tx < tgtW; tx++) {
+      const sx  = Math.floor(tx / tgtW * srcW);
+      const px  = row[clamp(sx, 0, srcW-1)] ?? {r:0,g:0,b:0};
+      const {r, g, b} = px;
+
+      // luminance (perceptual)
+      const lum = 0.2126*r + 0.7152*g + 0.0722*b;
+      const n   = invert ? 1 - lum/255 : lum/255;
+      const ci  = clamp(Math.floor(n * charset.length), 0, charset.length-1);
+      const ch  = charset[ci];
+
+      if (color) {
+        // find closest ANSI 8-color
+        const ansiCol = closestAnsi(r, g, b);
+        line += `\x1b[${ansiCol}m${ch}`;
+      } else {
+        line += ch;
+      }
+    }
+    lines.push(line + RST);
+  }
+
+  return lines.join('\n');
+}
+
+function closestAnsi(r, g, b) {
+  const ANSI_RGB = [
+    [0,0,0],[128,0,0],[0,128,0],[128,128,0],
+    [0,0,128],[128,0,128],[0,128,128],[192,192,192],
+    [128,128,128],[255,0,0],[0,255,0],[255,255,0],
+    [0,0,255],[255,0,255],[0,255,255],[255,255,255],
+  ];
+  const FC_VALS = [30,31,32,33,34,35,36,37,90,91,92,93,94,95,96,97];
+  let best=Infinity, bestIdx=0;
+  for (let i=0;i<ANSI_RGB.length;i++) {
+    const [ar,ag,ab]=ANSI_RGB[i];
+    const d=(r-ar)**2+(g-ag)**2+(b-ab)**2;
+    if(d<best){best=d;bestIdx=i;}
+  }
+  return FC_VALS[bestIdx];
+}
+
+// ─── EXPORT ──────────────────────────────────────────────────────────────────
+
+const kitdef = {
+  TextArt:     (opts) => { const g = makeTextArt(opts);  g.start(); return g; },
+  Animate:     (opts) => { const g = makeAnimate(opts);  g.start(); return g; },
+  BoxArt:      (opts) => { const g = makeBoxArt(opts);   g.start(); return g; },
+
+  // standalone function (not a game loop)
+  ImageToAscii,
+
+  // animation presets
+  animPresets: ['matrix','fire','starfield','plasma','rain','snow','worms'],
+  makeTextArt, makeAnimate, makeBoxArt, ImageToAscii
+};
+
+module.exports = { kitdef };