voxflow 1.15.4 → 1.15.5

package/lib/internal/deck-validator.js

@@ -139,6 +139,58 @@ function validateListPayload(list, i) {
 //   text    = voiceover.text    ?? card.narration
 //   enabled = voiceover.enabled ?? true
 //   rate    = voiceover.rate    ?? 1.0
+// Optional per-card image registry. Each entry declares an AI-generation
+// recipe (prompt + aspect + quality) addressable by a stable `id` so the
+// content.html in V2 LayoutTree decks (and future themes that read by id)
+// can reference the resolved URL. Generation lives in stage's /api/imagine
+// endpoint, which content-hashes (prompt, aspect, quality) and caches
+// upstream-backed `data:image/...` payloads.
+const IMAGE_PROMPT_MAX = 1000;
+const IMAGE_ID_MAX = 64;
+const IMAGES_PER_CARD_MAX = 8;
+const IMAGE_VALID_ASPECTS = new Set(['portrait', 'landscape', 'square']);
+const IMAGE_VALID_QUALITIES = new Set(['fast', 'hd']);
+function validateCardImagesShape(images, cardIdx) {
+    if (images == null) return;
+    if (!Array.isArray(images)) {
+        throw new Error(`cards[${cardIdx}].images must be an array (or null)`);
+    }
+    if (images.length > IMAGES_PER_CARD_MAX) {
+        throw new Error(`cards[${cardIdx}].images too many (${images.length} > ${IMAGES_PER_CARD_MAX})`);
+    }
+    const seen = new Set();
+    images.forEach((img, j) => {
+        if (!img || typeof img !== 'object' || Array.isArray(img)) {
+            throw new Error(`cards[${cardIdx}].images[${j}] must be an object`);
+        }
+        if (typeof img.id !== 'string' || !img.id.trim()) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id required (non-empty string)`);
+        }
+        if (img.id.length > IMAGE_ID_MAX) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id too long (${img.id.length} > ${IMAGE_ID_MAX})`);
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(img.id)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id must match [a-zA-Z0-9_-]+`);
+        }
+        if (seen.has(img.id)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id duplicate: ${img.id}`);
+        }
+        seen.add(img.id);
+        if (typeof img.prompt !== 'string' || !img.prompt.trim()) {
+            throw new Error(`cards[${cardIdx}].images[${j}].prompt required (non-empty string)`);
+        }
+        if (img.prompt.length > IMAGE_PROMPT_MAX) {
+            throw new Error(`cards[${cardIdx}].images[${j}].prompt too long (${img.prompt.length} > ${IMAGE_PROMPT_MAX})`);
+        }
+        if (img.aspect != null && !IMAGE_VALID_ASPECTS.has(img.aspect)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].aspect must be one of: ${[...IMAGE_VALID_ASPECTS].join(', ')}`);
+        }
+        if (img.quality != null && !IMAGE_VALID_QUALITIES.has(img.quality)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].quality must be one of: ${[...IMAGE_VALID_QUALITIES].join(', ')}`);
+        }
+    });
+}
+
 const VOICEOVER_TEXT_MAX = 500;
 function validateVoiceoverShape(vo, cardIdx) {
     if (vo == null) return;
@@ -279,6 +331,7 @@ function validatePaperSlideDeck(deck) {
             }
         }
         validateVoiceoverShape(card.voiceover, i);
+        validateCardImagesShape(card.images, i);
         // Optional per-card image URL — photo-feature / atmospheric themes
         // composite it as a full-bleed background; other themes ignore it.
         // Shape-check only (string, length cap, http(s) prefix); reachability
@@ -334,10 +387,16 @@ function validatePaperSlideDeck(deck) {
 // / quote / stat / steps). Anything else is rejected so a renderer that
 // silently no-ops on unknown elements doesn't ship a broken video.
 
-const V2_ALLOWED_ELEMENTS = new Set(['heading', 'body', 'paper-figure', 'quote', 'stat', 'steps']);
+const V2_ALLOWED_ELEMENTS = new Set(['heading', 'body', 'paper-figure', 'quote', 'stat', 'steps', 'raw-html']);
 const V2_HEADING_MAX = 22;
 const V2_BODY_TEXT_MAX = 30;
 const V2_STAT_LABEL_MAX = 30;
+// raw-html is the open-ended escape hatch for themes / cards that want
+// arbitrary markup. The cap is generous enough for a styled inline figure
+// (a few paragraphs of HTML, maybe one inline data URI), but small enough
+// to keep deck.json human-editable and prevent an LLM run-on from blowing
+// past the watcher debounce.
+const V2_RAW_HTML_MAX = 4096;
 
 function validateV2Children(children, cardIdx, allowedElements, opts = {}) {
     if (!Array.isArray(children) || children.length === 0) {
@@ -419,6 +478,26 @@ function validateV2Children(children, cardIdx, allowedElements, opts = {}) {
                     );
                 }
             });
+        } else if (el.el === 'raw-html') {
+            // Schema-only support: validator accepts the element and the
+            // V2 normalizer (video-present/src/compositions/PaperSlide/
+            // layout-tree.ts) maps it to a `rawHtml` field on the V1
+            // normalized output. PaperSlide composition rendering of
+            // arbitrary HTML lands in a follow-up PR — for now the
+            // composition silently skips this element, so a deck with
+            // raw-html validates + saves + edits cleanly but renders blank
+            // until the JSX side is updated.
+            if (typeof el.html !== 'string') {
+                throw new Error(`cards[${cardIdx}].children[${j}].html must be string`);
+            }
+            if (!el.html.trim()) {
+                throw new Error(`cards[${cardIdx}].children[${j}].html empty`);
+            }
+            if (el.html.length > V2_RAW_HTML_MAX) {
+                throw new Error(
+                    `cards[${cardIdx}].children[${j}].html too long (${el.html.length} > ${V2_RAW_HTML_MAX})`
+                );
+            }
         }
     });
     return elements;
@@ -461,12 +540,22 @@ function validatePaperSlideDeckV2(deck) {
         if (!nonEmptyString(card.narration)) throw new Error(`cards[${i}].narration empty`);
 
         if (card.kind === 'title') {
-            const els = validateV2Children(card.children, i, new Set(['heading']), { maxChildren: 3 });
-            if (els.length === 0) throw new Error(`cards[${i}] title must have at least one heading`);
+            const els = validateV2Children(card.children, i, new Set(['heading', 'raw-html']), { maxChildren: 3 });
+            if (els.filter((e) => e.el === 'heading').length === 0) {
+                throw new Error(`cards[${i}] title must have at least one heading`);
+            }
         } else if (card.kind === 'body') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'paper-figure']), { maxChildren: 4 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'paper-figure', 'raw-html']), { maxChildren: 4 });
             const figs = els.filter((e) => e.el === 'paper-figure');
-            if (figs.length !== 1) throw new Error(`cards[${i}] body must contain exactly one paper-figure (got ${figs.length})`);
+            const rawEls = els.filter((e) => e.el === 'raw-html');
+            // A body card needs either a figure OR a raw-html block — raw
+            // HTML can stand in as the entire visual when the theme wants
+            // a custom panel instead of the canned figure renderer.
+            if (figs.length + rawEls.length !== 1) {
+                throw new Error(
+                    `cards[${i}] body must contain exactly one paper-figure OR one raw-html (got ${figs.length} figure + ${rawEls.length} raw-html)`
+                );
+            }
             const heads = els.filter((e) => e.el === 'heading');
             if (heads.length === 0) throw new Error(`cards[${i}] body must contain at least one heading`);
         } else if (card.kind === 'quote') {
@@ -475,22 +564,23 @@ function validatePaperSlideDeckV2(deck) {
             // stat / steps directly and ignores any non-discriminator elements
             // on these kinds). Discriminator element must still be present
             // exactly once. Cap at 3 children to keep output bounded.
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'quote']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'quote', 'raw-html']), { maxChildren: 3 });
             const quoteEls = els.filter((e) => e.el === 'quote');
             if (quoteEls.length !== 1) throw new Error(`cards[${i}] quote card must contain exactly one quote element (got ${quoteEls.length})`);
             richCounts.quote += 1;
         } else if (card.kind === 'data') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'stat']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'stat', 'raw-html']), { maxChildren: 3 });
             const statEls = els.filter((e) => e.el === 'stat');
             if (statEls.length !== 1) throw new Error(`cards[${i}] data card must contain exactly one stat element (got ${statEls.length})`);
             richCounts.data += 1;
         } else if (card.kind === 'list') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'steps']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'steps', 'raw-html']), { maxChildren: 3 });
             const stepsEls = els.filter((e) => e.el === 'steps');
             if (stepsEls.length !== 1) throw new Error(`cards[${i}] list card must contain exactly one steps element (got ${stepsEls.length})`);
             richCounts.list += 1;
         }
         validateVoiceoverShape(card.voiceover, i);
+        validateCardImagesShape(card.images, i);
     });
     // Cap on rich-kind variety — at most 1 of each (same as V1 prompt rule)
     for (const k of Object.keys(richCounts)) {
@@ -523,6 +613,7 @@ module.exports = {
     validateDataPayload,
     validateListPayload,
     validateVoiceoverShape,
+    validateCardImagesShape,
     QUOTE_TEXT_MAX,
     QUOTE_ATTRIBUTION_MAX,
     DATA_VALUE_MAX,
@@ -532,4 +623,8 @@ module.exports = {
     LIST_ITEM_MIN_COUNT,
     LIST_ITEM_MAX_COUNT,
     VOICEOVER_TEXT_MAX,
+    IMAGE_PROMPT_MAX,
+    IMAGE_ID_MAX,
+    IMAGES_PER_CARD_MAX,
+    V2_RAW_HTML_MAX,
 };

package/lib/stage-core/image-gen.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Stage → backend bridge for AI image generation (hunyuan-image).
+ *
+ * Mirror of tts-audition.js for the visual side: stage's per-card 🎨 button
+ * resolves `card.images[i] = { id, prompt, aspect?, quality? }`, hashes the
+ * generation recipe, and either returns a cached PNG/JPG or asks the backend
+ * to produce one. JWT lives on the server (same posture as cloud-render /
+ * audition).
+ *
+ * Public surface:
+ *   createImageGenClient({ apiBase?, tokenLoader?, cacheDir?, fetchImpl? })
+ *     → { imagine({ prompt, aspect, quality }), cacheDir }
+ *
+ * Cache layout: <cacheDir>/<sha256(prompt|aspect|quality)>.<ext>
+ * Default cacheDir: ~/.config/voxflow/stage-image-cache/ — global so a
+ * prompt repeated across decks resolves to one file on disk.
+ *
+ * Backend contract: POST /api/image/generate { prompt, ratio, quality }
+ *   → { code: 'success', image: 'data:image/png;base64,...', quota }
+ *   We parse the data URL, persist the raw bytes, and serve them with the
+ *   declared MIME so <img src> works in the browser without a base64 hop.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const https = require('https');
+
+const { API_BASE } = require('../core/config');
+const { readCachedToken } = require('../core/auth');
+
+const DEFAULT_TIMEOUT_MS = 180_000;          // backend hunyuan-image takes 30-90s p95
+const DEFAULT_ASPECT = 'portrait';            // 9:16 matches Slice frame
+const DEFAULT_QUALITY = 'fast';               // 200-quota tier; 'hd' is 500
+// Catalog references — surfaced so the stage UI can show "🎨 costs N quota"
+// without an extra round-trip. Authoritative deduction is server-side.
+const IMAGE_GEN_COST_FAST = 200;
+const IMAGE_GEN_COST_HD = 500;
+
+function defaultCacheDir() {
+  return path.join(os.homedir(), '.config', 'voxflow', 'stage-image-cache');
+}
+
+function cacheKey({ prompt, aspect, quality }) {
+  // Stable content hash — every parameter that affects image output is
+  // included so the same (prompt, aspect, quality) maps to the same file.
+  const h = crypto.createHash('sha256');
+  h.update(prompt);
+  h.update(' ');
+  h.update(aspect);
+  h.update(' ');
+  h.update(quality);
+  return h.digest('hex');
+}
+
+function extensionFor(mime) {
+  // Backend hunyuan-image currently returns PNG; map other common MIMEs in
+  // case the provider swap underneath produces JPEG / WebP.
+  if (mime === 'image/png') return 'png';
+  if (mime === 'image/jpeg' || mime === 'image/jpg') return 'jpg';
+  if (mime === 'image/webp') return 'webp';
+  return 'bin';
+}
+
+function cachePath(dir, key, ext) {
+  return path.join(dir, `${key}.${ext}`);
+}
+
+function parseDataUrl(dataUrl) {
+  if (typeof dataUrl !== 'string') return null;
+  // RFC 2397 base64 form: data:<mime>;base64,<bytes>
+  const m = /^data:([^;,]+);base64,(.+)$/.exec(dataUrl);
+  if (!m) return null;
+  let buf;
+  try { buf = Buffer.from(m[2], 'base64'); }
+  catch { return null; }
+  if (!buf.length) return null;
+  return { mime: m[1].toLowerCase(), buf };
+}
+
+function requestJson(targetUrl, opts = {}, body = null, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(targetUrl);
+    const mod = u.protocol === 'https:' ? https : http;
+    const headers = Object.assign({}, opts.headers || {});
+    let payload = null;
+    if (body !== null && body !== undefined) {
+      payload = Buffer.from(JSON.stringify(body), 'utf8');
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = payload.length;
+    }
+    const req = mod.request({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname + u.search,
+      method: opts.method || 'GET',
+      headers,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = null;
+        try { parsed = JSON.parse(raw); } catch { /* keep null */ }
+        resolve({ status: res.statusCode, data: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => { req.destroy(new Error(`upstream timeout after ${timeoutMs}ms`)); });
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.apiBase=API_BASE]
+ * @param {() => ({access_token:string}|null)} [opts.tokenLoader]
+ * @param {string} [opts.cacheDir]
+ * @param {(args:object) => Promise<{status:number, data:object|null}>} [opts.fetchImpl]
+ *   Test injection point — receives `{ prompt, ratio, quality, headers }`.
+ * @returns {{ imagine: (params:object) => Promise<object>, cacheDir: string }}
+ */
+function createImageGenClient(opts = {}) {
+  const apiBase = (opts.apiBase || API_BASE).replace(/\/$/, '');
+  const tokenLoader = typeof opts.tokenLoader === 'function' ? opts.tokenLoader : readCachedToken;
+  const cacheDir = opts.cacheDir || defaultCacheDir();
+  const fetchImpl = typeof opts.fetchImpl === 'function' ? opts.fetchImpl : null;
+
+  try { fs.mkdirSync(cacheDir, { recursive: true }); } catch { /* best-effort */ }
+
+  function authHeaders() {
+    const cached = tokenLoader();
+    if (!cached || !cached.access_token) return null;
+    return { Authorization: 'Bearer ' + cached.access_token };
+  }
+
+  async function imagine({ prompt, aspect, quality } = {}) {
+    if (typeof prompt !== 'string' || !prompt.trim()) {
+      return { code: 'invalid_prompt', message: 'prompt required (non-empty string)' };
+    }
+    const asp = (aspect === 'portrait' || aspect === 'landscape' || aspect === 'square') ? aspect : DEFAULT_ASPECT;
+    const qual = (quality === 'fast' || quality === 'hd') ? quality : DEFAULT_QUALITY;
+    const key = cacheKey({ prompt, aspect: asp, quality: qual });
+
+    // Cache check — same recipe = same bytes. Walk known extensions so a
+    // stored PNG is found whether the cache layer tracks the MIME or not.
+    for (const ext of ['png', 'jpg', 'webp', 'bin']) {
+      const fp = cachePath(cacheDir, key, ext);
+      try {
+        const buf = fs.readFileSync(fp);
+        const mime = ({ png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp', bin: 'application/octet-stream' })[ext];
+        return {
+          code: 'success',
+          buf,
+          contentType: mime,
+          fromCache: true,
+          cacheKey: key,
+          ext,
+        };
+      } catch { /* try next ext */ }
+    }
+
+    const headers = authHeaders();
+    if (!headers) {
+      return { code: 'not_logged_in', message: 'Run `voxflow login` first.' };
+    }
+
+    let r;
+    try {
+      if (fetchImpl) {
+        r = await fetchImpl({ prompt: prompt.trim(), ratio: asp, quality: qual, headers });
+      } else {
+        r = await requestJson(`${apiBase}/api/image/generate`, { method: 'POST', headers }, {
+          prompt: prompt.trim(),
+          ratio: asp,
+          quality: qual,
+        });
+      }
+    } catch (err) {
+      return { code: 'network_error', message: err.message || String(err) };
+    }
+
+    if (r.status === 401) return { code: 'not_logged_in', message: 'Token expired — run `voxflow login`.' };
+    if (r.status === 402 || r.status === 429) return { code: 'quota_exceeded', message: r.data?.message || 'Insufficient quota' };
+    if (r.status >= 400 || !r.data || r.data.code !== 'success') {
+      return {
+        code: r.data?.code || 'imagine_failed',
+        message: r.data?.message || `HTTP ${r.status}`,
+      };
+    }
+    const parsed = parseDataUrl(r.data.image);
+    if (!parsed) {
+      return { code: 'imagine_failed', message: 'response missing or malformed image data URL' };
+    }
+    const ext = extensionFor(parsed.mime);
+    const filePath = cachePath(cacheDir, key, ext);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      fs.writeFileSync(tmp, parsed.buf);
+      fs.renameSync(tmp, filePath);
+    } catch {
+      try { fs.unlinkSync(tmp); } catch { /* */ }
+    }
+    return {
+      code: 'success',
+      buf: parsed.buf,
+      contentType: parsed.mime,
+      fromCache: false,
+      cacheKey: key,
+      ext,
+    };
+  }
+
+  return { imagine, cacheDir };
+}
+
+module.exports = {
+  createImageGenClient,
+  cacheKey,
+  cachePath,
+  defaultCacheDir,
+  parseDataUrl,
+  extensionFor,
+  IMAGE_GEN_COST_FAST,
+  IMAGE_GEN_COST_HD,
+  DEFAULT_ASPECT,
+  DEFAULT_QUALITY,
+};

package/lib/stage-core/local-render.js

@@ -46,7 +46,8 @@ const {
   DEFAULT_THEME,
 } = require('../commands/slice-render');
 const { createTtsAuditionClient } = require('./tts-audition');
-const { startVoiceoverServer, prepareVoiceovers } = require('./voiceover-mux');
+const { createImageGenClient } = require('./image-gen');
+const { startVoiceoverServer, prepareVoiceovers, prepareImages } = require('./voiceover-mux');
 
 // In-memory job table. We never persist jobs — a stage restart wipes history,
 // which is fine because the produced mp4 lives on disk under the user's deck
@@ -164,18 +165,26 @@ async function runRender({ job, deck, onProgress, onDone, onError }) {
   try {
     job.state = 'preparing';
 
-    // ─── Voiceover prep (Phase 1) ──────────────────────────────────────
-    // Stage's Render button defaults to including audio — users in stage
-    // are iterating and expect a richer preview. The audition cache makes
-    // re-renders effectively free for cards they already previewed.
-    // Falls back to silent video on not_logged_in / quota_exceeded
-    // (recorded in job.voiceoverSkipped so the UI can surface the reason).
+    // ─── Voiceover + Image prep (Phase 1 + Phase B) ─────────────────────
+    // Stage's Render button defaults to BOTH audio + AI image generation.
+    // Users in stage are iterating and expect a fully-rendered preview;
+    // hitting the cache makes re-renders effectively free for content they
+    // already auditioned / regenerated. Either pass can fail to silent
+    // fallback without aborting the render — failures land in
+    // job.voiceoverSkipped / job.imageSkipped so the UI can surface the
+    // reason post hoc.
     let voiceoverByIdx = {};
+    let imageByIdx = {};
     let voiceoverSkipped = [];
+    let imageSkipped = [];
     try {
       const audClient = createTtsAuditionClient();
-      voiceoverServer = await startVoiceoverServer({ cacheDir: audClient.cacheDir });
-      const prep = await prepareVoiceovers({
+      const imgClient = createImageGenClient();
+      voiceoverServer = await startVoiceoverServer({
+        cacheDir: audClient.cacheDir,
+        imageCacheDir: imgClient.cacheDir,
+      });
+      const voPrep = await prepareVoiceovers({
         deck,
         auditionClient: audClient,
         baseUrl: voiceoverServer.url,
@@ -196,12 +205,36 @@ async function runRender({ job, deck, onProgress, onDone, onError }) {
           }
         },
       });
-      voiceoverByIdx = prep.byIdx;
-      voiceoverSkipped = prep.skipped;
+      voiceoverByIdx = voPrep.byIdx;
+      voiceoverSkipped = voPrep.skipped;
+
+      const imgPrep = await prepareImages({
+        deck,
+        imgClient,
+        baseUrl: voiceoverServer.url,
+        onProgress: (p) => {
+          if (typeof onProgress === 'function') {
+            try {
+              onProgress({
+                jobId,
+                progress: 0,
+                framesRendered: 0,
+                framesTotal: 0,
+                phase: 'image',
+                imageIndex: p.cardIdx + 1,
+                imageTotal: p.total,
+                imageFromCache: p.fromCache,
+              });
+            } catch { /* swallow */ }
+          }
+        },
+      });
+      imageByIdx = imgPrep.byIdx;
+      imageSkipped = imgPrep.skipped;
     } catch (err) {
-      // Voiceover prep failure is non-fatal — fall back to silent render
-      // so a TTS outage / first-run-without-login still produces an mp4.
-      voiceoverSkipped = [{ cardIdx: -1, reason: 'voiceover_prep_failed', message: err.message }];
+      // Media prep failure is non-fatal — fall back to silent + no-AI
+      // images so a TTS / image outage still produces an mp4.
+      voiceoverSkipped = [{ cardIdx: -1, reason: 'media_prep_failed', message: err.message }];
       if (voiceoverServer) {
         try { await voiceoverServer.close(); } catch { /* */ }
         voiceoverServer = null;
@@ -209,9 +242,11 @@ async function runRender({ job, deck, onProgress, onDone, onError }) {
     }
     job.voiceoverCount = Object.keys(voiceoverByIdx).length;
     job.voiceoverSkipped = voiceoverSkipped;
+    job.imageCount = Object.keys(imageByIdx).length;
+    job.imageSkipped = imageSkipped;
 
     const serveUrl = resolveServeUrl();
-    const inputProps = buildInputProps(deck, { voiceoverByIdx });
+    const inputProps = buildInputProps(deck, { voiceoverByIdx, imageByIdx });
 
     const renderer = loadRenderer();
     job.coldStart = !chromeBinaryExists();

package/lib/stage-core/server.js

@@ -66,6 +66,7 @@ async function startStageServer(opts) {
     localRender = null,
     deckSaver = null,
     audition = null,
+    imagine = null,
     publishEvent = null,
     tokenAvailable = false,
     preferredPort = 5180,
@@ -249,12 +250,15 @@ async function startStageServer(opts) {
         code === 'invalid_id' ||
         code === 'invalid_card_index' ||
         code === 'invalid_voice' ||
-        code === 'invalid_text'
+        code === 'invalid_text' ||
+        code === 'invalid_prompt' ||
+        code === 'invalid_image_id'
       ) return 400;
       if (
         code === 'job_not_found' ||
         code === 'no_deck' ||
-        code === 'card_not_found'
+        code === 'card_not_found' ||
+        code === 'image_not_found'
       ) return 404;
       if (code === 'voiceover_disabled') return 409;
       if (code === 'success') return 200;
@@ -458,6 +462,55 @@ async function startStageServer(opts) {
       return;
     }
 
+    // ─── Image generation (per-card 🎨) ─────────────────────────────────────
+    // GET /api/imagine?card=<int>&img=<id>
+    //   Resolves card.images[?] → calls /api/image/generate via the imagine
+    //   bridge → streams PNG/JPG bytes. Content-hash caches identical
+    //   (prompt, aspect, quality) so iterating on visuals is free after the
+    //   first call. Symmetric with /api/audition.
+    if (imagine && req.method === 'GET' && req.url.startsWith('/api/imagine')) {
+      let parsed;
+      try { parsed = new URL(req.url, `http://127.0.0.1:${port}`); }
+      catch {
+        return sendJson(400, { code: 'bad_request', message: 'invalid /api/imagine url' });
+      }
+      const cardIndexStr = parsed.searchParams.get('card');
+      const cardIndex = Number.parseInt(cardIndexStr, 10);
+      if (!Number.isInteger(cardIndex) || cardIndex < 0) {
+        return sendJson(400, {
+          code: 'invalid_card_index',
+          message: '?card= must be a non-negative integer',
+        });
+      }
+      const imageId = parsed.searchParams.get('img') || '';
+      if (typeof imageId !== 'string' || !imageId.trim()) {
+        return sendJson(400, {
+          code: 'invalid_image_id',
+          message: '?img= must be a non-empty image id',
+        });
+      }
+      (async () => {
+        let result;
+        try {
+          result = await imagine.play({ cardIndex, imageId });
+        } catch (err) {
+          return sendJson(502, { code: 'upstream_error', message: err.message });
+        }
+        if (result.code !== 'success') {
+          return sendJson(statusForCode(result.code), result);
+        }
+        res.writeHead(200, {
+          'Content-Type': result.contentType || 'image/png',
+          'Content-Length': result.buf.length,
+          'Cache-Control': 'no-store',
+          'X-Imagine-Cache': result.fromCache ? 'HIT' : 'MISS',
+          'X-Imagine-Key': result.cacheKey || '',
+        });
+        res.end(result.buf);
+      })();
+      return;
+    }
+
     // ─── Inline deck save (Task B) ──────────────────────────────────────────
     // POST /api/deck  body: full deck JSON  → validates + writes to disk.
     // The file watcher picks up the write and broadcasts the deck event, so