storymode-cli 1.1.0 → 1.1.2

package/package.json

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

package/src/api.mjs

@@ -2,7 +2,7 @@ import https from 'node:https';
 import http from 'node:http';
 import { gunzipSync } from 'node:zlib';
 
-const BASE = 'https://storymode.fixmy.codes';
+const BASE = process.env.STORYMODE_BASE_URL || 'https://pixterm-server.proudisland-84e92871.westus2.azurecontainerapps.io';
 
 function request(url) {
   return new Promise((resolve, reject) => {
@@ -28,11 +28,13 @@ export async function fetchGallery() {
   return JSON.parse(buffer.toString('utf-8'));
 }
 
-export async function fetchFrames(galleryId, { size } = {}) {
+export async function fetchFrames(galleryId, { size, mode, animId } = {}) {
   let url = `${BASE}/gallery/${galleryId}/frames`;
-  if (size && size !== 'full') {
-    url += `?size=${size}`;
-  }
+  const params = [];
+  if (size && size !== 'full') params.push(`size=${size}`);
+  if (mode) params.push(`mode=${mode}`);
+  if (animId) params.push(`anim_id=${animId}`);
+  if (params.length) url += '?' + params.join('&');
   const { buffer, contentType } = await request(url);
   let json;
   if (contentType.includes('gzip') || buffer[0] === 0x1f) {

package/src/cli.mjs

@@ -14,10 +14,11 @@ const HELP = `
     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.
+  Options:
+    --sextant   Use sextant rendering (2x3 sub-pixels, sharper but needs
+                a modern terminal). Works with play, companion, show.
+    --size=compact|tiny   Size for companion mode (default: compact).
+    --detach    Return control immediately (companion mode).
 
   Controls (during playback):
     space     pause / resume
@@ -55,7 +56,9 @@ export async function run(args) {
       }
       try {
         process.stderr.write('  Loading animation...\n');
-        const framesData = await fetchFrames(id);
+        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}`);
@@ -76,7 +79,9 @@ export async function run(args) {
       // 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 });
+          const fetchOpts = { size };
+          if (flags.sextant) fetchOpts.mode = 'sextant';
+          const framesData = await fetchFrames(id, fetchOpts);
           await playCompanion(framesData);
         } catch (err) {
           console.error(`Error: ${err.message}`);
@@ -87,7 +92,8 @@ export async function run(args) {
 
       // Otherwise, open a tmux side pane
       const inTmux = !!process.env.TMUX;
-      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}`;
+      const sextantFlag = flags.sextant ? ' --sextant' : '';
+      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}${sextantFlag}`;
 
       try {
         if (inTmux) {
@@ -132,8 +138,10 @@ export async function run(args) {
       }
       try {
         process.stderr.write('  Loading...\n');
+        const fetchOpts = {};
+        if (flags.sextant) { fetchOpts.size = 'compact'; fetchOpts.mode = 'sextant'; }
         const [framesData, character] = await Promise.all([
-          fetchFrames(id),
+          fetchFrames(id, fetchOpts),
           fetchCharacter(id).catch(() => null),
         ]);
         const info = character

package/src/mcp.mjs

@@ -4,72 +4,122 @@ import { fetchGallery, fetchFrames, fetchCharacter } from './api.mjs';
 const TOOLS = [
   {
     name: 'list_characters',
-    description: 'List all characters in the Storymode gallery',
+    description: 'List all characters in the Storymode gallery with their available animations',
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'show_character',
-    description: 'Show character info and portrait (first frame as ANSI art)',
+    description: 'Show character info, portrait, and list of available animations. Use this to see what a character looks like and what animations they have.',
     inputSchema: {
       type: 'object',
-      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      properties: {
+        gallery_id: { type: 'string', description: 'Gallery item ID' },
+        animation: { type: 'string', description: 'Animation name to show a frame from (e.g. "waving hello", "casting lightning spell"). If omitted, shows the default animation.' },
+      },
       required: ['gallery_id'],
     },
   },
   {
     name: 'play_animation',
-    description: 'Get animation data for a gallery character (returns first frame as ANSI art + metadata)',
+    description: 'Show a frame from a specific animation and provide the CLI command to play it. Choose the animation contextually — "waving hello" for greetings, "thinking" for processing, "casting lightning spell" for impressive actions, "idle breathing" for ambient.',
     inputSchema: {
       type: 'object',
-      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      properties: {
+        gallery_id: { type: 'string', description: 'Gallery item ID' },
+        animation: { type: 'string', description: 'Animation name (e.g. "waving hello", "idle breathing"). Use list_characters or show_character to see available animations.' },
+      },
       required: ['gallery_id'],
     },
   },
 ];
 
+function findAnimation(animations, query) {
+  if (!query || !animations?.length) return null;
+  const q = query.toLowerCase();
+  // Exact match first
+  const exact = animations.find(a => (a.name || a.prompt || '').toLowerCase() === q);
+  if (exact) return exact;
+  // Partial match
+  const partial = animations.find(a => (a.name || a.prompt || '').toLowerCase().includes(q));
+  return partial || null;
+}
+
 async function handleToolCall(name, args) {
   switch (name) {
     case 'list_characters': {
       const items = await fetchGallery();
-      const lines = items.map((item, i) =>
-        `${i + 1}. ${item.name || 'untitled'}${item.prompt ? ' — ' + item.prompt : ''} (id: ${item.id})`
-      );
-      return lines.join('\n') || 'Gallery is empty.';
+      if (!items.length) return 'Gallery is empty.';
+      const parts = [];
+      for (const item of items) {
+        const char = await fetchCharacter(item.id).catch(() => null);
+        let line = `${item.name || 'untitled'} (id: ${item.id})`;
+        if (char?.backstory) line += `\n  ${char.backstory}`;
+        if (char?.animations?.length) {
+          const names = char.animations.map(a => a.name || a.prompt).join(', ');
+          line += `\n  Animations: ${names}`;
+        }
+        parts.push(line);
+      }
+      return parts.join('\n\n');
     }
     case 'show_character': {
       const id = args.gallery_id;
-      const [character, framesData] = await Promise.all([
-        fetchCharacter(id).catch(() => null),
-        fetchFrames(id, { size: 'tiny' }),
-      ]);
+      const character = await fetchCharacter(id).catch(() => null);
+
+      // Determine which animation to show
+      const fetchOpts = { size: 'tiny' };
+      if (args.animation && character?.animations?.length) {
+        const match = findAnimation(character.animations, args.animation);
+        if (match) fetchOpts.animId = match.id;
+      }
+      const framesData = await fetchFrames(id, fetchOpts);
+
       let text = '';
       if (character) {
         text += `Name: ${character.name || 'untitled'}\n`;
         if (character.backstory) text += `Backstory: ${character.backstory}\n`;
         if (character.animations?.length) {
-          text += `Animations: ${character.animations.map(a => a.name || a.prompt).join(', ')}\n`;
+          text += `\nAnimations (${character.animations.length}):\n`;
+          for (const a of character.animations) {
+            text += `  • ${a.name || a.prompt}\n`;
+          }
         }
         text += '\n';
       }
-      // First frame as ANSI
       if (framesData.frames?.length > 0) {
-        text += 'Portrait (ANSI):\n';
+        const label = args.animation || 'portrait';
+        text += `${label} (ANSI):\n`;
         text += framesData.frames[0].join('\n');
       }
       return text;
     }
     case 'play_animation': {
       const id = args.gallery_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.';
+
+      // Look up animation ID by name
+      const fetchOpts = { size: 'tiny' };
+      let animLabel = 'default';
+      if (args.animation) {
+        const character = await fetchCharacter(id).catch(() => null);
+        if (character?.animations?.length) {
+          const match = findAnimation(character.animations, args.animation);
+          if (match) {
+            fetchOpts.animId = match.id;
+            animLabel = match.name || match.prompt;
+          } else {
+            const names = character.animations.map(a => a.name || a.prompt).join(', ');
+            return `Animation "${args.animation}" not found. Available: ${names}`;
+          }
+        }
       }
+
+      const framesData = await fetchFrames(id, fetchOpts);
+      if (!framesData.frames?.length) return 'No frames available.';
+
+      let text = framesData.frames[0].join('\n');
+      text += `\n\n"${animLabel}" — ${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}`;
       return text;
     }
     default:
@@ -92,7 +142,7 @@ function handleMessage(msg) {
         result: {
           protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: 'storymode', version: '1.0.0' },
+          serverInfo: { name: 'storymode', version: '1.1.2' },
         },
       });
       break;