storymode-cli 1.2.1 → 1.2.3

package/README.md

@@ -3,29 +3,31 @@
 AI-animated pixel art companions for your terminal. Reacts to Claude Code in real time.
 
 ```
-npx storymode-cli play 3
+npx storymode-cli play
 ```
 
 ## Quick Start
 
 ```bash
-# Browse available characters
-npx storymode-cli browse
-
-# Run a companion alongside Claude Code
-npx storymode-cli play 3
+npx storymode-cli play
 ```
 
-The companion opens in a tmux side pane and reacts to what Claude Code is doing — switching animations when it reads files, writes code, hits errors, etc. Speech bubbles show in-character lines.
+That's it. A companion opens in a tmux side pane and reacts to what Claude Code is doing — switching animations when it reads files, writes code, hits errors, etc.
+
+Use `browse` to switch characters or visit [storymode.fixmy.codes](https://storymode.fixmy.codes) to see the full gallery.
+
+```bash
+npx storymode-cli browse
+```
 
 ## Options
 
 ```bash
-npx storymode-cli play 3              # full size (default)
-npx storymode-cli play 3 --compact    # smaller pane
-npx storymode-cli play 3 --tiny       # tiny pane
-npx storymode-cli play 3 --no-ai      # disable AI personality
-npx storymode-cli play 3 --classic    # full-screen animation viewer
+npx storymode-cli play              # full size (default)
+npx storymode-cli play --compact    # smaller pane
+npx storymode-cli play --tiny       # tiny pane
+npx storymode-cli play --no-ai      # disable AI personality
+npx storymode-cli play --classic    # full-screen animation viewer
 ```
 
 **Keyboard:** `a` add API key (enables AI personality), `q` quit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymode-cli",
-  "version": "1.2.1",
+  "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';
@@ -78,14 +78,15 @@ const HELP = `
   storymode-cli — AI-animated pixel art companions for your terminal
 
   Usage:
-    storymode play <id>       Run a reactive companion alongside Claude Code
-    storymode browse          Browse the gallery and pick a character
+    storymode play            Run a reactive companion alongside Claude Code
+    storymode browse          Browse the gallery and switch characters
 
   Options:
     --compact        Smaller companion pane (default: full)
     --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
 
@@ -110,19 +111,17 @@ function parseFlags(args) {
   return { flags, positional };
 }
 
+const DEFAULT_CHARACTER = 3; // Zephyr
+
 export async function run(args) {
   const cmd = args[0];
   const { flags, positional } = parseFlags(args.slice(1));
-  const id = positional[0];
+  const id = positional[0] || (cmd === 'play' || cmd === 'companion' ? DEFAULT_CHARACTER : undefined);
 
   switch (cmd) {
     // --- Main command: reactive companion ---
     case 'play':
     case 'companion': {
-      if (!id) {
-        console.error('Usage: storymode play <id>');
-        process.exit(1);
-      }
 
       // --classic: old full-screen animation viewer
       if (flags.classic) {
@@ -139,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();
+  });
+}