storymode-cli 1.0.0 → 1.1.0

package/package.json

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

package/src/api.mjs

@@ -28,8 +28,12 @@ export async function fetchGallery() {
   return JSON.parse(buffer.toString('utf-8'));
 }
 
-export async function fetchFrames(galleryId) {
-  const { buffer, contentType } = await request(`${BASE}/gallery/${galleryId}/frames`);
+export async function fetchFrames(galleryId, { size } = {}) {
+  let url = `${BASE}/gallery/${galleryId}/frames`;
+  if (size && size !== 'full') {
+    url += `?size=${size}`;
+  }
+  const { buffer, contentType } = await request(url);
   let json;
   if (contentType.includes('gzip') || buffer[0] === 0x1f) {
     json = gunzipSync(buffer).toString('utf-8');

package/src/cli.mjs

@@ -1,5 +1,6 @@
+import { execSync } from 'node:child_process';
 import { fetchFrames, fetchCharacter } from './api.mjs';
-import { playAnimation, showFrame } from './player.mjs';
+import { playAnimation, playCompanion, showFrame } from './player.mjs';
 import { browse } from './browse.mjs';
 import { startMcpServer } from './mcp.mjs';
 
@@ -7,10 +8,16 @@ const HELP = `
   storymode-cli — play AI-animated pixel art in your terminal
 
   Usage:
-    storymode play <gallery_id>    Play an animation
-    storymode show <gallery_id>    Show first frame as static portrait
-    storymode browse               Browse the gallery interactively
-    storymode mcp                  Start MCP server (for Claude Code)
+    storymode play <gallery_id>         Play an animation (full screen)
+    storymode companion <gallery_id>    Play compact sprite alongside your session
+    storymode show <gallery_id>         Show first frame as static portrait
+    storymode browse                    Browse the gallery interactively
+    storymode mcp                       Start MCP server (for Claude Code)
+
+  Companion mode:
+    Opens a tmux side pane with a small looping sprite.
+    Use --detach to return control immediately.
+    Use --size=compact (default) or --size=tiny for smaller sprites.
 
   Controls (during playback):
     space     pause / resume
@@ -21,9 +28,24 @@ const HELP = `
   https://storymode.fixmy.codes
 `;
 
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const [key, val] = arg.slice(2).split('=');
+      flags[key] = val ?? true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
 export async function run(args) {
   const cmd = args[0];
-  const id = args[1];
+  const { flags, positional } = parseFlags(args.slice(1));
+  const id = positional[0];
 
   switch (cmd) {
     case 'play': {
@@ -42,6 +64,67 @@ export async function run(args) {
       break;
     }
 
+    case 'companion': {
+      if (!id) {
+        console.error('Usage: storymode companion <gallery_id> [--detach] [--size=compact|tiny]');
+        process.exit(1);
+      }
+      const size = flags.size || 'compact';
+      const detach = !!flags.detach;
+      const paneWidth = size === 'tiny' ? 14 : 22;
+
+      // If we're already the companion pane (spawned by tmux split), play inline
+      if (process.env.STORYMODE_COMPANION === '1') {
+        try {
+          const framesData = await fetchFrames(id, { size });
+          await playCompanion(framesData);
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      // Otherwise, open a tmux side pane
+      const inTmux = !!process.env.TMUX;
+      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}`;
+
+      try {
+        if (inTmux) {
+          // Split current window with a side pane
+          execSync(
+            `tmux split-window -h -l ${paneWidth} '${companionCmd}'`,
+            { stdio: 'ignore' }
+          );
+          if (!detach) {
+            process.stderr.write(`  Companion sprite opened in side pane (${size}).\n`);
+            process.stderr.write('  Close the pane or press q in it to stop.\n');
+          }
+        } else {
+          // Not in tmux — start a new tmux session with the split
+          process.stderr.write('  Starting tmux session with companion pane...\n');
+          execSync(
+            `tmux new-session -d -s storymode -x 100 -y 30 \\; ` +
+            `split-window -h -l ${paneWidth} '${companionCmd}' \\; ` +
+            `select-pane -L`,
+            { stdio: 'ignore' }
+          );
+          if (detach) {
+            process.stderr.write('  Companion running in tmux session "storymode".\n');
+            process.stderr.write('  Attach with: tmux attach -t storymode\n');
+          } else {
+            // Attach to the session so the user sees it
+            execSync('tmux attach -t storymode', { stdio: 'inherit' });
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        console.error('  Make sure tmux is installed: brew install tmux');
+        process.exit(1);
+      }
+      break;
+    }
+
     case 'show': {
       if (!id) {
         console.error('Usage: storymode show <gallery_id>');

package/src/mcp.mjs

@@ -40,7 +40,7 @@ async function handleToolCall(name, args) {
       const id = args.gallery_id;
       const [character, framesData] = await Promise.all([
         fetchCharacter(id).catch(() => null),
-        fetchFrames(id),
+        fetchFrames(id, { size: 'tiny' }),
       ]);
       let text = '';
       if (character) {
@@ -60,12 +60,13 @@ async function handleToolCall(name, args) {
     }
     case 'play_animation': {
       const id = args.gallery_id;
-      const framesData = await fetchFrames(id);
+      const framesData = await fetchFrames(id, { size: 'tiny' });
       let text = '';
       if (framesData.frames?.length > 0) {
         text += framesData.frames[0].join('\n');
         text += `\n\n${framesData.frames.length} frames @ ${framesData.fps || 16} fps`;
         text += `\n\nTo see the full animation, run:\n  npx storymode-cli play ${id}`;
+        text += `\n\nTo play as a companion sprite alongside your session:\n  npx storymode-cli companion ${id}`;
       } else {
         text = 'No frames available.';
       }

package/src/player.mjs

@@ -120,6 +120,87 @@ export function playAnimation(framesData) {
   });
 }
 
+export function playCompanion(framesData) {
+  const frames = framesData.frames;
+  const baseFps = framesData.fps || 16;
+  const nFrames = frames.length;
+
+  if (nFrames === 0) {
+    console.log('No frames to play.');
+    return Promise.resolve();
+  }
+
+  const maxLines = Math.max(...frames.map(f => f.length));
+  let frameIdx = 0;
+  let currentFps = baseFps;
+  let interval = 1000 / currentFps;
+  let quit = false;
+
+  // No alt screen — render inline. Hide cursor only.
+  stdout.write('\x1b[?25l');
+
+  // Reserve space by printing blank lines, then move cursor back up
+  for (let i = 0; i < maxLines + 1; i++) {
+    stdout.write('\n');
+  }
+  stdout.write(`\x1b[${maxLines + 1}A`);
+
+  // Save cursor position (we'll return here each frame)
+  stdout.write('\x1b7');
+
+  function drawFrame(idx) {
+    // Restore saved cursor position
+    let out = '\x1b8';
+    const frameLines = frames[idx];
+    for (let i = 0; i < maxLines; i++) {
+      if (i < frameLines.length) {
+        out += frameLines[i];
+      }
+      out += '\x1b[K\n';
+    }
+    out += `\x1b[0m\x1b[K  [q]=quit\n`;
+    stdout.write(out);
+  }
+
+  function cleanup() {
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.removeAllListeners('data');
+    stdin.pause();
+    stdout.write('\x1b[?25h');
+  }
+
+  function handleKey(data) {
+    const key = data.toString();
+    if (key === 'q' || key === '\x03') {
+      quit = true;
+    }
+  }
+
+  if (stdin.isTTY) {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', handleKey);
+  }
+
+  return new Promise((resolve) => {
+    function tick() {
+      if (quit) {
+        cleanup();
+        resolve();
+        return;
+      }
+      drawFrame(frameIdx);
+      frameIdx = (frameIdx + 1) % nFrames;
+      setTimeout(tick, interval);
+    }
+    tick();
+
+    process.on('SIGINT', () => {
+      quit = true;
+    });
+  });
+}
+
 export function showFrame(framesData, info) {
   const frames = framesData.frames;
   if (!frames || frames.length === 0) {