storymode-cli 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymode-cli",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Play AI-animated pixel art characters in your terminal",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -49,3 +49,26 @@ export async function fetchCharacter(galleryId) {
   const { buffer } = await request(`${BASE}/gallery/${galleryId}/character`);
   return JSON.parse(buffer.toString('utf-8'));
 }
+
+/**
+ * Fetch raw PNG frames (base64) for a gallery animation.
+ * Returns { fps, frame_count, frames: [Buffer, ...] }
+ */
+export async function fetchPngFrames(galleryId, { animId } = {}) {
+  let url = `${BASE}/gallery/${galleryId}/png-frames`;
+  if (animId) url += `?anim_id=${animId}`;
+  const { buffer, contentType } = await request(url);
+  let json;
+  if (contentType.includes('gzip') || buffer[0] === 0x1f) {
+    json = gunzipSync(buffer).toString('utf-8');
+  } else {
+    json = buffer.toString('utf-8');
+  }
+  const data = JSON.parse(json);
+  // Decode base64 frames to Buffers
+  return {
+    fps: data.fps,
+    frame_count: data.frame_count,
+    frames: data.frames.map(b64 => Buffer.from(b64, 'base64')),
+  };
+}

package/src/cache.mjs

@@ -1,7 +1,7 @@
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { fetchFrames, fetchCharacter } from './api.mjs';
+import { fetchFrames, fetchCharacter, fetchPngFrames } from './api.mjs';
 
 const STORYMODE_DIR = join(homedir(), '.storymode');
 
@@ -19,7 +19,7 @@ export function readCached(galleryId, size) {
   const map = new Map();
   if (!existsSync(dir)) return map;
   for (const file of readdirSync(dir)) {
-    if (!file.endsWith('.json') || file === 'character.json') continue;
+    if (!file.endsWith('.json') || file === 'character.json' || file === 'personality.json') continue;
     try {
       const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
       const name = file.replace(/\.json$/, '').replace(/-/g, ' ');
@@ -89,6 +89,41 @@ export function readLocalPersonality(galleryId) {
   }
 }
 
+// --- PNG frame cache ---
+
+function getPngCacheDir(galleryId) {
+  return join(STORYMODE_DIR, 'cache', String(galleryId), 'png');
+}
+
+/** Read cached PNG frames for an animation. Returns Buffer[] or null. */
+export function readCachedPng(galleryId, animName) {
+  const dir = getPngCacheDir(galleryId);
+  const filename = animName.replace(/ /g, '-') + '.json';
+  const file = join(dir, filename);
+  if (!existsSync(file)) return null;
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf-8'));
+    return {
+      fps: data.fps,
+      frames: data.frames.map(b64 => Buffer.from(b64, 'base64')),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Write PNG frames to cache (stored as base64 JSON). */
+export function writeCachePng(galleryId, animName, fps, frames) {
+  const dir = getPngCacheDir(galleryId);
+  mkdirSync(dir, { recursive: true });
+  const filename = animName.replace(/ /g, '-') + '.json';
+  const data = {
+    fps,
+    frames: frames.map(buf => buf.toString('base64')),
+  };
+  writeFileSync(join(dir, filename), JSON.stringify(data));
+}
+
 /** Read local animation overrides. Returns Map<name, {fps, frames}> */
 export function readLocalOverrides(galleryId) {
   const dir = getLocalDir(galleryId);
@@ -109,14 +144,18 @@ export function readLocalOverrides(galleryId) {
 
 /**
  * Load all animations for a gallery: local overrides > cache > server fetch.
- * Returns { animMap: Map<name, {fps, frames}>, character, personality }
+ * Returns { animMap: Map<name, {fps, frames, pngFrames?}>, character, personality }
+ *
+ * When opts.hd is true, PNG frames are loaded alongside ANSI frames:
+ *   - Idle animation: loaded blocking (needed immediately)
+ *   - Other animations: loaded in background (falls back to ANSI until ready)
  *
  * Personality loading priority:
  *   1. ~/.storymode/characters/{id}/personality.json (user-authored)
  *   2. Cached personality.json (from server, if it provides one)
  *   3. null (no personality — instant + fallback sleep only)
  */
-export async function loadAnimations(galleryId, { size = 'compact', mode } = {}) {
+export async function loadAnimations(galleryId, { size = 'compact', mode, hd = false } = {}) {
   const localOverrides = readLocalOverrides(galleryId);
   const cached = readCached(galleryId, size);
   let character = readCachedCharacter(galleryId, size);
@@ -161,6 +200,50 @@ export async function loadAnimations(galleryId, { size = 'compact', mode } = {})
     animMap.set(name, data);
   }
 
+  // --- HD: load PNG frames ---
+  if (hd && character) {
+    const anims = character.animations || [];
+    const idleAnim = anims.find(a => a.name === 'idle breathing');
+
+    // Helper: load PNG for one animation (cache or fetch)
+    async function loadPngForAnim(anim) {
+      const cachedPng = readCachedPng(galleryId, anim.name);
+      if (cachedPng) return cachedPng;
+      try {
+        const data = await fetchPngFrames(galleryId, { animId: anim.id });
+        writeCachePng(galleryId, anim.name, data.fps, data.frames);
+        return data;
+      } catch {
+        return null; // PNG not available — ANSI fallback
+      }
+    }
+
+    // Idle: load blocking (needed immediately for first frame)
+    if (idleAnim) {
+      process.stderr.write('  Loading HD frames (idle)...\r');
+      const pngData = await loadPngForAnim(idleAnim);
+      if (pngData && animMap.has(idleAnim.name)) {
+        animMap.get(idleAnim.name).pngFrames = pngData.frames;
+      }
+      process.stderr.write('  Loading HD frames (idle)... done.\n');
+    }
+
+    // Rest: load in background (companion starts immediately with ANSI fallback)
+    const otherAnims = anims.filter(a => a.name !== 'idle breathing');
+    if (otherAnims.length > 0) {
+      Promise.all(otherAnims.map(async (anim) => {
+        const pngData = await loadPngForAnim(anim);
+        if (pngData && animMap.has(anim.name)) {
+          animMap.get(anim.name).pngFrames = pngData.frames;
+        }
+      })).then(() => {
+        process.stderr.write('  HD frames loaded for all animations.\n');
+      }).catch(() => {
+        // Silently fall back to ANSI for any that failed
+      });
+    }
+  }
+
   // Load personality: local file > cached > null
   const personality = readLocalPersonality(galleryId)
     || readCachedPersonality(galleryId, size)

package/src/cli.mjs

@@ -1,7 +1,7 @@
 import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { fetchFrames, fetchCharacter } from './api.mjs';
-import { playAnimation, playCompanion, playReactiveCompanion, showFrame } from './player.mjs';
+import { fetchFrames, fetchCharacter, fetchPngFrames } from './api.mjs';
+import { playAnimation, playCompanion, playReactiveCompanion, showFrame, playHdAnimation, detectGraphicsProtocol } from './player.mjs';
 import { browse } from './browse.mjs';
 import { startMcpServer } from './mcp.mjs';
 import { loadAnimations, clearCache } from './cache.mjs';
@@ -87,6 +87,7 @@ const HELP = `
     --no-ai          Disable AI personality (preset speech only)
     --model=ID       Anthropic model for AI personality
     --classic        Full-screen animation viewer (non-reactive)
+    --force          Kill existing session and restart
     --detach         Return control immediately
 
   Controls:
@@ -122,7 +123,27 @@ export async function run(args) {
     case 'play':
     case 'companion': {
 
-      // --classic: old full-screen animation viewer
+      // --classic --hd: pixel-perfect full-screen viewer (non-reactive)
+      if (flags.classic && flags.hd) {
+        const renderMode = detectGraphicsProtocol();
+        if (!renderMode.protocol) {
+          console.error('  --hd requires a terminal with graphics protocol support');
+          console.error('  (iTerm2, Kitty, Ghostty, or WezTerm)');
+          process.exit(1);
+        }
+        try {
+          process.stderr.write('  Loading HD frames...\n');
+          const pngData = await fetchPngFrames(id);
+          process.stderr.write(`  ${pngData.frame_count} frames @ ${pngData.fps}fps (${renderMode.protocol} protocol)\n`);
+          await playHdAnimation(pngData.frames, { fps: pngData.fps, renderMode });
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      // --classic: old full-screen ANSI animation viewer
       if (flags.classic) {
         try {
           process.stderr.write('  Loading animation...\n');
@@ -144,13 +165,17 @@ export async function run(args) {
       const model = flags.model || '';
       // Reactive is always on unless --classic
       const reactive = !flags['no-reactive'];
-      const paneWidth = size === 'full' ? 62 : size === 'tiny' ? 14 : 22;
+
+      // Auto-detect graphics protocol for HD rendering
+      const renderMode = detectGraphicsProtocol();
+      const useHd = !!renderMode.protocol; // auto-detect only
+      const paneWidth = useHd && size === 'full' ? 80 : size === 'full' ? 62 : size === 'tiny' ? 14 : 22;
 
       // If we're already the companion pane (spawned by tmux split), play inline
       if (process.env.STORYMODE_COMPANION === '1') {
         try {
           if (reactive) {
-            const fetchOpts = { size };
+            const fetchOpts = { size, hd: useHd };
             if (flags.sextant) fetchOpts.mode = 'sextant';
             const { animMap, character, personality } = await loadAnimations(id, fetchOpts);
             await playReactiveCompanion(animMap, {
@@ -160,6 +185,7 @@ export async function run(args) {
               fullscreen: size === 'full',
               noAi,
               model: model || undefined,
+              renderMode: useHd ? renderMode : undefined,
             });
           } else {
             const fetchOpts = { size };
@@ -186,7 +212,9 @@ export async function run(args) {
       const reactiveFlag = reactive ? ' --reactive' : '';
       const noAiFlag = noAi ? ' --no-ai' : '';
       const modelFlag = model ? ` --model=${model}` : '';
-      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli play ${id} --size=${size}${sextantFlag}${reactiveFlag}${noAiFlag}${modelFlag}`;
+      // Enable tmux passthrough for graphics protocols when HD is active
+      const passthroughPrefix = useHd ? 'tmux set allow-passthrough on; ' : '';
+      const companionCmd = `${passthroughPrefix}STORYMODE_COMPANION=1 npx storymode-cli play ${id} --size=${size}${sextantFlag}${reactiveFlag}${noAiFlag}${modelFlag}`;
 
       try {
         if (inTmux) {
@@ -195,10 +223,24 @@ export async function run(args) {
             { stdio: 'ignore' }
           );
           if (!detach) {
-            process.stderr.write(`  Companion opened in side pane (${size}).\n`);
+            const hdNote = useHd ? ` HD/${renderMode.protocol}` : '';
+            process.stderr.write(`  Companion opened in side pane (${size}${hdNote}).\n`);
             process.stderr.write('  Close the pane or press q in it to stop.\n');
           }
         } else {
+          // Check for existing session
+          try {
+            execSync('tmux has-session -t storymode', { stdio: 'ignore' });
+            if (flags.force) {
+              execSync('tmux kill-session -t storymode', { stdio: 'ignore' });
+            } else {
+              console.error('  A storymode tmux session already exists.');
+              console.error('  Attach to it:  tmux attach -t storymode');
+              console.error('  Or kill it:    tmux kill-session -t storymode');
+              console.error('  Or restart:    npx storymode-cli play --force');
+              process.exit(1);
+            }
+          } catch { /* no existing session — good */ }
           process.stderr.write('  Starting tmux session with companion pane...\n');
           execSync(
             `tmux new-session -d -s storymode -x 100 -y 30 \\; ` +

package/src/player.mjs

@@ -1,5 +1,6 @@
 import { createServer } from 'node:net';
 import { unlinkSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { mapEventToAnimation, pickSpeech, ONE_SHOT_ANIMS, IDLE_ANIM, SLEEP_ANIM, SLEEP_TIMEOUT_S, narrateEvent, SessionContext, StateEngine } from './reactive.mjs';
 import { createAgent } from './agent.mjs';
 import { getApiKey, hasSeenKeyPrompt, promptForApiKey } from './config.mjs';
@@ -210,7 +211,7 @@ export function playCompanion(framesData) {
 /**
  * Reactive companion player — responds to Claude Code events via Unix socket.
  *
- * @param {Map<string, {fps: number, frames: string[][]}>} animMap - All animations keyed by name
+ * @param {Map<string, {fps: number, frames: string[][], pngFrames?: Buffer[]}>} animMap - All animations keyed by name
  * @param {object} [opts]
  * @param {string} [opts.characterName] - Character name for status display
  * @param {object} [opts.character] - Character data {name, backstory, ...} for LLM personality
@@ -218,12 +219,16 @@ export function playCompanion(framesData) {
  * @param {boolean} [opts.fullscreen] - Use alt screen (full-screen mode)
  * @param {boolean} [opts.noAi] - Disable LLM personality layer
  * @param {string} [opts.model] - Anthropic model ID for personality layer
+ * @param {object} [opts.renderMode] - { protocol: 'kitty'|'iterm2'|null, inTmux: boolean }
  */
 export async function playReactiveCompanion(animMap, opts = {}) {
   const characterName = opts.characterName || 'companion';
   const personality = opts.personality || null;
   let character = opts.noAi ? null : (personality || opts.character || null);
   const fullscreen = !!opts.fullscreen;
+  const renderMode = opts.renderMode || { protocol: null, inTmux: false };
+  const hdProtocol = renderMode.protocol;
+  const hdInTmux = renderMode.inTmux;
 
   // --- API key prompt (before terminal setup) ---
   if (character && !opts.noAi && !getApiKey()) {
@@ -243,11 +248,30 @@ export async function playReactiveCompanion(animMap, opts = {}) {
     return Promise.resolve();
   }
 
+  // HD mode: compute image rows from PNG dimensions + pane width
+  let imageRows = 0;
+  if (hdProtocol && idleData.pngFrames && idleData.pngFrames.length > 0) {
+    const dim = pngDimensions(idleData.pngFrames[0]);
+    // Terminal cells are roughly 2:1 (height:width in pixels).
+    // Estimate: pane columns → pixel width, then derive rows from aspect ratio.
+    const paneCols = process.stdout.columns || 80;
+    const cellPixelW = 8;  // approximate pixel width per cell
+    const cellPixelH = 16; // approximate pixel height per cell
+    const panePixelW = paneCols * cellPixelW;
+    const scale = panePixelW / dim.width;
+    imageRows = Math.ceil((dim.height * scale) / cellPixelH);
+  }
+
   // Calculate maxLines across ALL animations for stable layout
   let maxLines = 0;
-  for (const [, data] of animMap) {
-    for (const frame of data.frames) {
-      if (frame.length > maxLines) maxLines = frame.length;
+  if (hdProtocol && imageRows > 0) {
+    // In HD mode, all images render at the same row height
+    maxLines = imageRows;
+  } else {
+    for (const [, data] of animMap) {
+      for (const frame of data.frames) {
+        if (frame.length > maxLines) maxLines = frame.length;
+      }
     }
   }
 
@@ -262,6 +286,7 @@ export async function playReactiveCompanion(animMap, opts = {}) {
   // Animation state
   let currentAnimName = IDLE_ANIM;
   let currentFrames = idleData.frames;
+  let currentPngFrames = idleData.pngFrames || null;
   let currentFps = idleData.fps || 16;
   let frameIdx = 0;
   let loopCount = 0;
@@ -343,6 +368,7 @@ export async function playReactiveCompanion(animMap, opts = {}) {
     const data = animMap.get(animName);
     currentAnimName = animName;
     currentFrames = data.frames;
+    currentPngFrames = data.pngFrames || null;
     currentFps = data.fps || 16;
     frameIdx = 0;
     loopCount = 0;
@@ -392,8 +418,11 @@ export async function playReactiveCompanion(animMap, opts = {}) {
     return lines;
   }
 
-  // Estimate sprite width from first frame of idle animation
+  // Estimate sprite width from first frame of idle animation (for bubble sizing)
   const spriteWidth = (() => {
+    if (hdProtocol && imageRows > 0) {
+      return process.stdout.columns || 80;
+    }
     const firstLine = idleData.frames[0]?.[0] || '';
     // Strip ANSI escape sequences to get visible character count
     return firstLine.replace(/\x1b\[[0-9;]*m/g, '').length;
@@ -401,30 +430,60 @@ export async function playReactiveCompanion(animMap, opts = {}) {
   const bubbleWidth = Math.max(20, Math.min(spriteWidth, 60));
 
   function drawFrame(idx) {
-    let out = fullscreen ? '\x1b[H' : '\x1b8'; // cursor home vs restore
-    const frameLines = currentFrames[idx] || [];
-    for (let i = 0; i < maxLines; i++) {
-      if (i < frameLines.length) {
-        out += frameLines[i];
+    const useHd = hdProtocol && currentPngFrames && currentPngFrames[idx];
+
+    if (useHd) {
+      // --- HD path: render PNG via graphics protocol, then text below ---
+      if (hdProtocol === 'kitty') {
+        stdout.write(fullscreen ? '\x1b[H' : '\x1b8');
+        const delSeq = `\x1b_Ga=d,d=a\x1b\\`;
+        stdout.write(hdInTmux ? wrapForTmux(delSeq) : delSeq);
+        writeKitty(currentPngFrames[idx], null, imageRows || undefined, hdInTmux);
+      } else {
+        // iTerm2: clear to release previous images from memory
+        stdout.write(fullscreen ? '\x1b[2J\x1b[H' : '\x1b8');
+        if (!fullscreen) {
+          // Clear the image area to release old images
+          for (let i = 0; i < maxLines; i++) stdout.write('\x1b[K\n');
+          stdout.write(fullscreen ? '\x1b[H' : '\x1b8');
+        }
+        writeIterm2(currentPngFrames[idx], null, imageRows || undefined, hdInTmux);
       }
-      out += '\x1b[K\n';
+      // Move cursor below the image area for text rendering
+      if (imageRows > 0) {
+        stdout.write(`\x1b[${imageRows}B`);
+      }
+    } else {
+      // --- ANSI fallback path ---
+      let out = fullscreen ? '\x1b[H' : '\x1b8'; // cursor home vs restore
+      const frameLines = currentFrames[idx] || [];
+      for (let i = 0; i < maxLines; i++) {
+        if (i < frameLines.length) {
+          out += frameLines[i];
+        }
+        out += '\x1b[K\n';
+      }
+      stdout.write(out);
     }
 
+    // --- Text below image (shared between HD and ANSI) ---
+
     // Auto-clear speech after timeout
     if (speechText && (Date.now() - speechSetAt > SPEECH_CLEAR_MS)) {
       speechText = null;
     }
 
     // Speech bubble or empty space
+    let textOut = '';
     if (speechText) {
       const bubble = renderBubble(speechText, bubbleWidth);
       for (const bl of bubble) {
-        out += bl + '\x1b[K\n';
+        textOut += bl + '\x1b[K\n';
       }
     } else {
       // Empty lines to keep layout stable
       for (let i = 0; i < bubbleLines - 1; i++) {
-        out += '\x1b[K\n';
+        textOut += '\x1b[K\n';
       }
     }
 
@@ -433,8 +492,9 @@ export async function playReactiveCompanion(animMap, opts = {}) {
       ? '  ' + Object.entries(stateEngine.toJSON()).map(([k, v]) => `${k.slice(0,3)}:${v}`).join(' ')
       : '';
     const keyHints = !agent && character && !opts.noAi ? '[a]=AI key [q]=quit' : '[q]=quit';
-    out += `\x1b[0m\x1b[K  ${characterName} [${currentAnimName}]${stateStr}  ${keyHints}\n`;
-    stdout.write(out);
+    const hdTag = useHd ? ' HD' : '';
+    textOut += `\x1b[0m\x1b[K  ${characterName} [${currentAnimName}]${hdTag}${stateStr}  ${keyHints}\n`;
+    stdout.write(textOut);
   }
 
   // --- Socket server ---
@@ -620,6 +680,9 @@ export async function playReactiveCompanion(animMap, opts = {}) {
 
     // Print socket path so hooks can find it
     process.stderr.write(`  Socket: ${sockPath}\n`);
+    if (hdProtocol) {
+      process.stderr.write(`  Render: HD (${hdProtocol}${hdInTmux ? ' via tmux' : ''})\n`);
+    }
     if (agent) {
       const modelName = opts.model || 'claude-haiku-4-5';
       process.stderr.write(`  AI personality: ON (${modelName})\n`);
@@ -661,3 +724,166 @@ export function showFrame(framesData, info) {
   }
   console.log('');
 }
+
+// --- Graphics Protocol Rendering (HD mode) ---
+
+const CHUNK_SIZE = 4096;
+
+/**
+ * Detect terminal graphics protocol support.
+ * Returns { protocol: 'kitty'|'iterm2'|null, inTmux: boolean }
+ */
+export function detectGraphicsProtocol() {
+  const inTmux = !!process.env.TMUX;
+
+  // Inside tmux: check the outer terminal, not tmux's own TERM
+  const termProgram = process.env.TERM_PROGRAM || '';
+  const term = process.env.TERM || '';
+  const kittyId = process.env.KITTY_WINDOW_ID;
+  const ghosttyDir = process.env.GHOSTTY_RESOURCES_DIR;
+
+  if (inTmux) {
+    // tmux overwrites env vars. Try to detect the parent terminal.
+    try {
+      const clientTerm = execSync('tmux display-message -p "#{client_termname}"', {
+        encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      // Map client_termname back to protocol
+      if (clientTerm === 'xterm-ghostty') return { protocol: 'kitty', inTmux };
+      if (clientTerm.includes('kitty')) return { protocol: 'kitty', inTmux };
+      // For iTerm2, client_termname is usually "xterm-256color" — check LC_TERMINAL
+      const lcTerminal = process.env.LC_TERMINAL || '';
+      if (lcTerminal === 'iTerm2') return { protocol: 'iterm2', inTmux };
+    } catch { /* fall through to env-based detection */ }
+  }
+
+  if (kittyId) return { protocol: 'kitty', inTmux };
+  if (term === 'xterm-ghostty' || ghosttyDir) return { protocol: 'kitty', inTmux };
+  if (termProgram === 'WezTerm') return { protocol: 'kitty', inTmux };
+  if (termProgram === 'iTerm.app') return { protocol: 'iterm2', inTmux };
+  return { protocol: null, inTmux };
+}
+
+/**
+ * Wrap an escape sequence for tmux DCS passthrough.
+ * Doubles any ESC characters inside the payload.
+ */
+function wrapForTmux(sequence) {
+  // Double all ESC bytes inside the payload
+  const escaped = sequence.replace(/\x1b/g, '\x1b\x1b');
+  return `\x1bPtmux;${escaped}\x1b\\`;
+}
+
+/**
+ * Parse PNG IHDR chunk to get width and height in pixels.
+ * @param {Buffer} buf - PNG file buffer
+ * @returns {{ width: number, height: number }}
+ */
+export function pngDimensions(buf) {
+  // PNG signature (8 bytes) + IHDR length (4 bytes) + "IHDR" (4 bytes) = offset 16
+  // Width at offset 16 (4 bytes BE), Height at offset 20 (4 bytes BE)
+  return {
+    width: buf.readUInt32BE(16),
+    height: buf.readUInt32BE(20),
+  };
+}
+
+/** Display PNG via iTerm2 inline images protocol */
+function writeIterm2(pngBuf, cols, rows, inTmux = false) {
+  const b64 = pngBuf.toString('base64');
+  let params = `inline=1;size=${pngBuf.length}`;
+  if (cols) params += `;width=${cols}`;
+  if (rows) params += `;height=${rows}`;
+  params += `;preserveAspectRatio=1`;
+  const seq = `\x1b]1337;File=${params}:${b64}\x07`;
+  stdout.write(inTmux ? wrapForTmux(seq) : seq);
+}
+
+/** Display PNG via Kitty graphics protocol */
+function writeKitty(pngBuf, cols, rows, inTmux = false) {
+  const b64 = pngBuf.toString('base64');
+  const write = (s) => stdout.write(inTmux ? wrapForTmux(s) : s);
+  if (b64.length <= CHUNK_SIZE) {
+    let params = `a=T,f=100`;
+    if (cols) params += `,c=${cols}`;
+    if (rows) params += `,r=${rows}`;
+    write(`\x1b_G${params};${b64}\x1b\\`);
+    return;
+  }
+  for (let i = 0; i < b64.length; i += CHUNK_SIZE) {
+    const chunk = b64.slice(i, i + CHUNK_SIZE);
+    const isFirst = i === 0;
+    const isLast = i + CHUNK_SIZE >= b64.length;
+    let params = `m=${isLast ? 0 : 1}`;
+    if (isFirst) {
+      params = `a=T,f=100`;
+      if (cols) params += `,c=${cols}`;
+      if (rows) params += `,r=${rows}`;
+      params += `,m=${isLast ? 0 : 1}`;
+    }
+    write(`\x1b_G${params};${chunk}\x1b\\`);
+  }
+}
+
+/**
+ * Play PNG frames using native graphics protocol.
+ * @param {Buffer[]} frames - Array of PNG buffers
+ * @param {object} opts - { fps, cols, rows, renderMode: {protocol, inTmux} }
+ */
+export function playHdAnimation(frames, opts = {}) {
+  const { fps = 16, cols, rows } = opts;
+  const interval = 1000 / fps;
+  const renderMode = opts.renderMode || { protocol: null, inTmux: false };
+  const protocol = renderMode.protocol;
+  const inTmux = renderMode.inTmux;
+
+  if (!protocol) {
+    console.error('  No graphics protocol supported. Use without --hd.');
+    process.exit(1);
+  }
+
+  let frameIdx = 0;
+  let quit = false;
+
+  // Alt screen, hide cursor, clear
+  stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J');
+
+  function drawFrame() {
+    if (protocol === 'kitty') {
+      stdout.write('\x1b[H');
+      const delSeq = `\x1b_Ga=d,d=a\x1b\\`;
+      stdout.write(inTmux ? wrapForTmux(delSeq) : delSeq);
+      writeKitty(frames[frameIdx], cols, rows, inTmux);
+    } else {
+      // iTerm2: clear screen before each frame to release previous inline images
+      // from memory. Without this, iTerm2 accumulates every image indefinitely.
+      stdout.write('\x1b[2J\x1b[H');
+      writeIterm2(frames[frameIdx], cols, rows, inTmux);
+    }
+  }
+
+  if (stdin.isTTY) {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', (data) => {
+      const key = data.toString();
+      if (key === 'q' || key === '\x03') quit = true;
+    });
+  }
+
+  return new Promise((resolve) => {
+    function tick() {
+      if (quit) {
+        stdout.write('\x1b[?1049l\x1b[?25h');
+        if (stdin.isTTY) stdin.setRawMode(false);
+        stdin.pause();
+        resolve();
+        return;
+      }
+      drawFrame();
+      frameIdx = (frameIdx + 1) % frames.length;
+      setTimeout(tick, interval);
+    }
+    tick();
+  });
+}