storymode-cli 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymode-cli",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "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/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';
@@ -86,6 +86,7 @@ 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)
     --detach         Return control immediately
 
@@ -137,6 +138,26 @@ 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);
+        }
+        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 });
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        break;
+      }
+
       // Determine size: default full, --compact, --tiny, or explicit --size=
       const size = flags.tiny ? 'tiny' : flags.compact ? 'compact' : (flags.size || 'full');
       const detach = !!flags.detach;

package/src/player.mjs

@@ -661,3 +661,110 @@ export function showFrame(framesData, info) {
   }
   console.log('');
 }
+
+// --- Graphics Protocol Rendering (HD mode) ---
+
+const CHUNK_SIZE = 4096;
+
+/** Detect terminal graphics protocol support */
+export function detectGraphicsProtocol() {
+  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;
+}
+
+/** Display PNG via iTerm2 inline images protocol */
+function writeIterm2(pngBuf, cols, rows) {
+  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`);
+}
+
+/** Display PNG via Kitty graphics protocol */
+function writeKitty(pngBuf, cols, rows) {
+  const b64 = pngBuf.toString('base64');
+  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\\`);
+    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}`;
+    }
+    stdout.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 }
+ */
+export function playHdAnimation(frames, opts = {}) {
+  const { fps = 16, cols, rows } = opts;
+  const interval = 1000 / fps;
+  const protocol = detectGraphicsProtocol();
+
+  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() {
+    stdout.write('\x1b[H');
+    if (protocol === 'kitty') {
+      stdout.write(`\x1b_Ga=d,d=a\x1b\\`);
+      writeKitty(frames[frameIdx], cols, rows);
+    } else {
+      writeIterm2(frames[frameIdx], cols, rows);
+    }
+  }
+
+  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();
+  });
+}