storymode-cli 1.2.3 → 1.3.1

package/package.json

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

package/src/api.mjs

@@ -25,7 +25,9 @@ function request(url) {
 
 export async function fetchGallery() {
   const { buffer } = await request(`${BASE}/gallery`);
-  return JSON.parse(buffer.toString('utf-8'));
+  const data = JSON.parse(buffer.toString('utf-8'));
+  // Handle both new {featured_id, curated_ids, items} and legacy bare array
+  return Array.isArray(data) ? { featured_id: null, curated_ids: null, items: data } : data;
 }
 
 export async function fetchFrames(galleryId, { size, mode, animId } = {}) {

package/src/browse.mjs

@@ -19,7 +19,8 @@ export async function browse() {
   const spinner = startSpinner('Fetching gallery...');
   let items;
   try {
-    items = await fetchGallery();
+    const gallery = await fetchGallery();
+    items = gallery.items;
   } finally {
     stopSpinner(spinner);
   }

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,6 +1,9 @@
 import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { fetchFrames, fetchCharacter, fetchPngFrames } from './api.mjs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fetchFrames, fetchCharacter, fetchPngFrames, fetchGallery } from './api.mjs';
 import { playAnimation, playCompanion, playReactiveCompanion, showFrame, playHdAnimation, detectGraphicsProtocol } from './player.mjs';
 import { browse } from './browse.mjs';
 import { startMcpServer } from './mcp.mjs';
@@ -86,8 +89,8 @@ const HELP = `
     --tiny           Tiny companion pane
     --no-ai          Disable AI personality (preset speech only)
     --model=ID       Anthropic model for AI personality
-    --hd             Pixel-perfect rendering (iTerm2/Kitty/Ghostty)
     --classic        Full-screen animation viewer (non-reactive)
+    --force          Kill existing session and restart
     --detach         Return control immediately
 
   Controls:
@@ -111,26 +114,60 @@ function parseFlags(args) {
   return { flags, positional };
 }
 
-const DEFAULT_CHARACTER = 3; // Zephyr
+const DEFAULT_CHARACTER = 3; // Zephyr (fallback if server has no featured_id)
+const CONFIG_CACHE_PATH = join(homedir(), '.storymode', 'cache', 'gallery-config.json');
+
+/** Get the featured character ID: positional arg > cached config > fetch from server > fallback */
+async function resolveFeaturedId() {
+  // Try cached config first
+  try {
+    if (existsSync(CONFIG_CACHE_PATH)) {
+      const cached = JSON.parse(readFileSync(CONFIG_CACHE_PATH, 'utf-8'));
+      if (cached.featured_id != null) return cached.featured_id;
+    }
+  } catch { /* ignore corrupt cache */ }
+
+  // Fetch from server and cache
+  try {
+    const gallery = await fetchGallery();
+    const cacheDir = join(homedir(), '.storymode', 'cache');
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(CONFIG_CACHE_PATH, JSON.stringify({
+      featured_id: gallery.featured_id,
+      curated_ids: gallery.curated_ids,
+    }));
+    if (gallery.featured_id != null) return gallery.featured_id;
+  } catch { /* network failure — fall through */ }
+
+  return DEFAULT_CHARACTER;
+}
 
 export async function run(args) {
   const cmd = args[0];
   const { flags, positional } = parseFlags(args.slice(1));
-  const id = positional[0] || (cmd === 'play' || cmd === 'companion' ? DEFAULT_CHARACTER : undefined);
+  let id = positional[0];
+  if (!id && (cmd === 'play' || cmd === 'companion')) {
+    id = await resolveFeaturedId();
+  }
 
   switch (cmd) {
     // --- Main command: reactive companion ---
     case 'play':
     case 'companion': {
 
-      // --classic: old full-screen animation viewer
-      if (flags.classic) {
+      // --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 animation...\n');
-          const fetchOpts = {};
-          if (flags.sextant) { fetchOpts.size = 'compact'; fetchOpts.mode = 'sextant'; }
-          const framesData = await fetchFrames(id, fetchOpts);
-          await playAnimation(framesData);
+          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);
@@ -138,19 +175,14 @@ export async function run(args) {
         break;
       }
 
-      // --hd: pixel-perfect rendering via graphics protocol (iTerm2/Kitty/Ghostty)
-      if (flags.hd) {
-        const protocol = detectGraphicsProtocol();
-        if (!protocol) {
-          console.error('  --hd requires a terminal with graphics protocol support');
-          console.error('  (iTerm2, Kitty, Ghostty, or WezTerm)');
-          process.exit(1);
-        }
+      // --classic: old full-screen ANSI animation viewer
+      if (flags.classic) {
         try {
-          process.stderr.write('  Loading HD frames...\n');
-          const pngData = await fetchPngFrames(id);
-          process.stderr.write(`  ${pngData.frame_count} frames @ ${pngData.fps}fps (${protocol} protocol)\n`);
-          await playHdAnimation(pngData.frames, { fps: pngData.fps });
+          process.stderr.write('  Loading animation...\n');
+          const fetchOpts = {};
+          if (flags.sextant) { fetchOpts.size = 'compact'; fetchOpts.mode = 'sextant'; }
+          const framesData = await fetchFrames(id, fetchOpts);
+          await playAnimation(framesData);
         } catch (err) {
           console.error(`Error: ${err.message}`);
           process.exit(1);
@@ -165,13 +197,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, {
@@ -181,6 +217,7 @@ export async function run(args) {
               fullscreen: size === 'full',
               noAi,
               model: model || undefined,
+              renderMode: useHd ? renderMode : undefined,
             });
           } else {
             const fetchOpts = { size };
@@ -207,7 +244,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) {
@@ -216,10 +255,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/mcp.mjs

@@ -47,7 +47,8 @@ function findAnimation(animations, query) {
 async function handleToolCall(name, args) {
   switch (name) {
     case 'list_characters': {
-      const items = await fetchGallery();
+      const gallery = await fetchGallery();
+      const items = gallery.items;
       if (!items.length) return 'Gallery is empty.';
       const chars = await Promise.all(
         items.map(item => fetchCharacter(item.id).catch(() => null))

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`);
@@ -666,35 +729,85 @@ export function showFrame(framesData, info) {
 
 const CHUNK_SIZE = 4096;
 
-/** Detect terminal graphics protocol support */
+/**
+ * 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 || '';
-  if (process.env.KITTY_WINDOW_ID) return 'kitty';
-  if (term === 'xterm-ghostty' || process.env.GHOSTTY_RESOURCES_DIR) return 'kitty';
-  if (termProgram === 'WezTerm') return 'kitty';
-  if (termProgram === 'iTerm.app') return 'iterm2';
-  return null;
+  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 };
+    } catch { /* tmux command failed — fall through */ }
+    // LC_TERMINAL survives tmux env overwriting (iTerm2 sets it)
+    const lcTerminal = process.env.LC_TERMINAL || '';
+    if (lcTerminal === 'iTerm2') return { protocol: 'iterm2', inTmux };
+  }
+
+  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) {
+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`;
-  stdout.write(`\x1b]1337;File=${params}:${b64}\x07`);
+  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) {
+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}`;
-    stdout.write(`\x1b_G${params};${b64}\x1b\\`);
+    write(`\x1b_G${params};${b64}\x1b\\`);
     return;
   }
   for (let i = 0; i < b64.length; i += CHUNK_SIZE) {
@@ -708,19 +821,21 @@ function writeKitty(pngBuf, cols, rows) {
       if (rows) params += `,r=${rows}`;
       params += `,m=${isLast ? 0 : 1}`;
     }
-    stdout.write(`\x1b_G${params};${chunk}\x1b\\`);
+    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 }
+ * @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 protocol = detectGraphicsProtocol();
+  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.');
@@ -734,12 +849,16 @@ export function playHdAnimation(frames, opts = {}) {
   stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J');
 
   function drawFrame() {
-    stdout.write('\x1b[H');
     if (protocol === 'kitty') {
-      stdout.write(`\x1b_Ga=d,d=a\x1b\\`);
-      writeKitty(frames[frameIdx], cols, rows);
+      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 {
-      writeIterm2(frames[frameIdx], cols, rows);
+      // 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);
     }
   }