First commit

.gitignore

@@ -37,3 +37,4 @@ next-env.d.ts
 /sandbox/
 .env
 .env
+/backup

src/app/server/actions/generateImage.ts

@@ -6,6 +6,7 @@ import { getValidNumber } from "@/lib/getValidNumber";
 
 const BASE = (process.env.AI_FAST_IMAGE_SERVER_API_GRADIO_URL || "").replace(/\/+$/, "");
 const SECRET = process.env.AI_FAST_IMAGE_SERVER_API_SECRET_TOKEN || "";
+const HF_TOKEN = process.env.HF_TOKEN || process.env.HUGGING_FACE_HUB_TOKEN || "";
 const DEBUG = (process.env.DEBUG_IMAGE_API || "").toLowerCase() === "true";
 
 function assertEnv() {
@@ -13,9 +14,16 @@ function assertEnv() {
   if (!SECRET) throw new Error("Missing AI_FAST_IMAGE_SERVER_API_SECRET_TOKEN");
 }
 
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = {};
+  if (HF_TOKEN) h.Authorization = `Bearer ${HF_TOKEN}`;
+  return h;
+}
+
 function abbrev(s: unknown, n = 1200) {
+  if (s == null) return String(s);
   const t = typeof s === "string" ? s : JSON.stringify(s);
-  return t && t.length > n ? t.slice(0, n) + "…" : t;
+  return t.length > n ? t.slice(0, n) + "…" : t;
 }
 
 async function withTimeout<T>(p: Promise<T>, ms = 120_000) {
@@ -24,122 +32,235 @@ async function withTimeout<T>(p: Promise<T>, ms = 120_000) {
     new Promise<T>((_, rej) => setTimeout(() => rej(new Error(`Timeout after ${ms}ms`)), ms)) as Promise<T>,
   ]);
 }
+
 async function timedFetch(url: string, init?: RequestInit) {
   const t0 = Date.now();
-  const res = await withTimeout(fetch(url, init));
+  const res = await withTimeout(fetch(url, init), 120_000);
   return { res, ms: Date.now() - t0 };
 }
+
 function stripToJson(text: string) {
   if (!text) return "";
   const iBrace = text.indexOf("{");
   const iBrack = text.indexOf("[");
-  const i = [iBrace === -1 ? 1e9 : iBrace, iBrack === -1 ? 1e9 : iBrack].reduce((a, b) => Math.min(a, b), 1e9);
-  return i === 1e9 ? text : text.slice(i);
+  const picks = [iBrace, iBrack].filter((i) => i >= 0);
+  if (!picks.length) return text;
+  const i = Math.min(...picks);
+  return text.slice(i);
 }
-async function readSSEJson(res: Response, maxMs = 120_000): Promise<any | null> {
+
+/** Parse Gradio SSE and return the JSON payload of the **complete** event (throw on error). */
+async function readSSEComplete(res: Response, { maxMs = 120_000 } = {}): Promise<any | null> {
   const ct = (res.headers.get("content-type") || "").toLowerCase();
+
+  // Some deployments return JSON directly (no SSE) — accept that.
   if (ct.includes("application/json")) {
     const txt = await res.text();
-    try { return JSON.parse(stripToJson(txt)); } catch { return null; }
+    try {
+      return JSON.parse(stripToJson(txt));
+    } catch {
+      return null;
+    }
   }
+
   const reader = res.body?.getReader();
   if (!reader) return null;
+
   const decoder = new TextDecoder();
   let buf = "";
-  let lastJson: any | null = null;
-  const start = Date.now();
-
-  const flush = (chunk: string) => {
-    buf += chunk;
-    let m: RegExpMatchArray | null;
-    while ((m = buf.match(/([\s\S]*?)\r?\n\r?\n/)) !== null) {
-      const block = m[1];
-      buf = buf.slice(m[0].length);
-      const lines = block.split(/\r?\n/);
-      const dataLines: string[] = [];
-      for (const line of lines) {
-        if (!line) continue;
-        const idx = line.indexOf(":");
-        const field = idx === -1 ? line.trim() : line.slice(0, idx).trim();
-        const value = idx === -1 ? "" : line.slice(idx + 1).replace(/^\s/, "");
-        if (DEBUG && line.trim()) console.log("[SSE]", line);
-        if (field === "data") dataLines.push(value);
+  let currEvent: string | null = null;
+  let dataLines: string[] = [];
+  const started = Date.now();
+
+  const handleBlock = () => {
+    if (!currEvent) return undefined;
+    const payloadText = dataLines.join("\n");
+    if (DEBUG) console.log(`   [SSE event=${currEvent}] ${abbrev(payloadText, 600)}`);
+
+    if (currEvent === "complete") {
+      if (!payloadText) return { type: "complete", json: null as any };
+      try {
+        return { type: "complete", json: JSON.parse(stripToJson(payloadText)) };
+      } catch {
+        return { type: "complete", json: null as any };
       }
-      if (dataLines.length) {
-        const payload = dataLines.join("\n");
-        try {
-          lastJson = JSON.parse(stripToJson(payload));
-        } catch { /* ignore */ }
+    }
+
+    if (currEvent === "error") {
+      let detail: unknown = null;
+      try {
+        detail = payloadText ? JSON.parse(stripToJson(payloadText)) : null;
+      } catch {
+        detail = payloadText;
       }
+      return { type: "error", detail };
     }
+
+    return undefined;
   };
 
   while (true) {
-    if (Date.now() - start > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
+    if (Date.now() - started > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
     const { value, done } = await reader.read();
     if (done) break;
-    flush(decoder.decode(value, { stream: true }));
+
+    buf += decoder.decode(value, { stream: true });
+
+    // split stream into event blocks on blank line
+    let idx: number;
+    while ((idx = buf.search(/\r?\n\r?\n/)) !== -1) {
+      const raw = buf.slice(0, idx);
+      buf = buf.slice(idx).replace(/^\r?\n\r?\n/, ""); // drop exactly one blank separator
+      const lines = raw.split(/\r?\n/);
+
+      // parse fields in this block
+      currEvent = null;
+      dataLines = [];
+      for (const line of lines) {
+        if (!line) continue;
+        if (line[0] === ":") continue; // comment/keepalive
+        const c = line.indexOf(":");
+        const field = (c === -1 ? line : line.slice(0, c)).trim();
+        const val = (c === -1 ? "" : line.slice(c + 1)).replace(/^\s/, "");
+        if (field === "event") currEvent = val;
+        else if (field === "data") dataLines.push(val);
+      }
+
+      const outcome = handleBlock();
+      if (outcome?.type === "complete") return outcome.json;
+      if (outcome?.type === "error") {
+        const msg = typeof outcome.detail === "string" ? outcome.detail : JSON.stringify(outcome.detail);
+        throw new Error(`SSE error event: ${abbrev(msg ?? "null", 1200)}`);
+      }
+    }
+  }
+
+  // process any trailing block (stream ended without final blank line)
+  if (buf.trim().length) {
+    const lines = buf.split(/\r?\n/);
+    currEvent = null;
+    dataLines = [];
+    for (const line of lines) {
+      if (!line || line[0] === ":") continue;
+      const c = line.indexOf(":");
+      const field = (c === -1 ? line : line.slice(0, c)).trim();
+      const val = (c === -1 ? "" : line.slice(c + 1)).replace(/^\s/, "");
+      if (field === "event") currEvent = val;
+      else if (field === "data") dataLines.push(val);
+    }
+    const outcome = handleBlock();
+    if (outcome?.type === "complete") return outcome.json;
+    if (outcome?.type === "error") {
+      const msg = typeof outcome.detail === "string" ? outcome.detail : JSON.stringify(outcome.detail);
+      throw new Error(`SSE error event: ${abbrev(msg ?? "null", 1200)}`);
+    }
   }
-  return lastJson;
+
+  return null;
 }
 
+/** v5 call API: POST /gradio_api/call/<fn> → {event_id} → GET /gradio_api/call/<fn>/<event_id> (SSE complete). */
 async function gradioCallV5(base: string, fnName: string, dataArray: any[]) {
   const callUrl = `${base}/gradio_api/call/${fnName}`;
+
   const { res: postRes, ms: postMs } = await timedFetch(callUrl, {
     method: "POST",
-    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...authHeaders(),
+    },
     body: JSON.stringify({ data: dataArray }),
     cache: "no-store",
   });
+
   const postTxt = await postRes.text();
-  const postJson = (() => { try { return JSON.parse(stripToJson(postTxt)); } catch { return null; } })();
+  const postJson = (() => {
+    try {
+      return JSON.parse(stripToJson(postTxt));
+    } catch {
+      return null;
+    }
+  })();
+
   if (!postRes.ok) {
     const detail = postJson?.detail ?? postJson?.error ?? postJson?.message ?? postTxt ?? "(empty body)";
     throw new Error(`POST ${callUrl} → ${postRes.status} in ${postMs}ms — ${abbrev(detail)}`);
   }
+
   const eventId = postJson?.event_id || postJson?.eventId || postJson?.eventID;
   if (!eventId) throw new Error(`POST ${callUrl} returned no event_id`);
 
   const getUrl = `${base}/gradio_api/call/${fnName}/${eventId}`;
-  const { res: getRes, ms: getMs } = await timedFetch(getUrl, { method: "GET", headers: { Accept: "text/event-stream" }});
+  const { res: getRes, ms: getMs } = await timedFetch(getUrl, {
+    method: "GET",
+    headers: {
+      Accept: "text/event-stream",
+      Connection: "keep-alive",
+      ...authHeaders(),
+    },
+    cache: "no-store",
+  });
+
   if (getRes.status !== 200) {
     const txt = await getRes.text();
     throw new Error(`GET ${getUrl} → ${getRes.status} in ${getMs}ms — ${abbrev(txt)}`);
   }
-  const json = await readSSEJson(getRes);
-  if (json == null) throw new Error(`GET ${getUrl} returned no payload (SSE error/null).`);
+
+  const json = await readSSEComplete(getRes);
+  if (json == null) {
+    // Common causes: invalid secret (server raises gr.Error), or ZeroGPU quota/denied.
+    throw new Error(`GET ${getUrl} returned no payload (SSE error/null — check secret/quota).`);
+  }
   return json;
 }
 
+/** Legacy /api|/run/predict fallback (rarely present on v5 Spaces). */
 async function gradioPredictLegacy(base: string, body: any) {
   const endpoints = [`${base}/api/predict`, `${base}/run/predict`];
   for (const url of endpoints) {
     try {
-      const { res } = await timedFetch(url, {
+      const { res, ms } = await timedFetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          ...authHeaders(),
+        },
         body: JSON.stringify(body),
         cache: "no-store",
       });
       const txt = await res.text();
-      const json = (() => { try { return JSON.parse(stripToJson(txt)); } catch { return null; } })();
+      const json = (() => {
+        try {
+          return JSON.parse(stripToJson(txt));
+        } catch {
+          return null;
+        }
+      })();
       if (res.ok) return json;
-    } catch {}
+      if (DEBUG) console.warn(`Legacy ${url} → ${res.status} in ${ms}ms — ${abbrev(txt)}`);
+    } catch (e) {
+      if (DEBUG) console.warn(`Legacy ${url} failed:`, (e as any)?.message || e);
+    }
   }
   throw new Error("Legacy /predict endpoints unavailable.");
 }
 
-/** Normalize image payload to a single URL string (or data URI) */
+/** Normalize image payload to a single URL string (or data URI). */
 function extractImageUrl(payload: any): string {
-  // v5 often returns an array of FileData objects: [{ url, ... }]
-  let d = payload?.data ?? payload;
-  if (Array.isArray(d)) {
+  // v5 often returns: { data: [ { url, name, size, … } ] }
+  let d: any = payload?.data ?? payload;
+
+  if (Array.isArray(d) && d.length > 0) {
     const first = d[0];
-    if (!first) throw new Error("Image response was empty.");
-    if (typeof first === "string") return first;
-    if (first?.url) return String(first.url);
+    if (typeof first === "string") return first;                  // direct url/data URI
+    if (first?.url) return String(first.url);                     // FileData.url
+    if (first?.path) return String(first.path);                   // legacy file path
   }
   if (d?.url) return String(d.url);
+  if (d?.path) return String(d.path);
+
   throw new Error(`Unexpected image response: ${abbrev(payload)}`);
 }
 
@@ -160,36 +281,29 @@ export async function generateImage(options: {
   const seed = (options?.seed ? options.seed : 0) || generateSeed();
   const width = getValidNumber(options?.width, 256, 1024, 512);
   const height = getValidNumber(options?.height, 256, 1024, 512);
-  const nbSteps = getValidNumber(options?.nbSteps, 1, 12, 4); // server clamps to <=12 anyway
-
-  const positive = [
-    "beautiful",
-    positivePrompt,
-    "award winning",
-    "high resolution",
-  ].filter(Boolean).join(", ");
-
-  const negative = [
-    negativePrompt,
-    "watermark",
-    "copyright",
-    "blurry",
-    "low quality",
-    "ugly",
-  ].filter(Boolean).join(", ");
+  const nbSteps = getValidNumber(options?.nbSteps, 1, 12, 4); // server clamps to <=12
+
+  const positive = ["beautiful", positivePrompt, "award winning", "high resolution"]
+    .filter(Boolean)
+    .join(", ");
+
+  const negative = [negativePrompt, "watermark", "copyright", "blurry", "low quality", "ugly"]
+    .filter(Boolean)
+    .join(", ");
 
   // Order must match the Space: [prompt, negative, seed, width, height, guidance, steps, secret_token]
   const dataArray = [positive, negative, seed, width, height, 0.0, nbSteps, SECRET];
 
-  // 1) Gradio v5
+  // 1) Gradio v5 call API (preferred)
   try {
     const json = await gradioCallV5(BASE, "generate", dataArray);
     return extractImageUrl(json);
   } catch (e) {
+    // If you see "SSE error/null", it’s almost always invalid secret or quota.
     console.warn("Gradio v5 image call failed:", (e as any)?.message || e);
   }
 
-  // 2) Legacy fallback (if enabled)
+  // 2) Legacy fallback (very likely 404 on v5 Spaces)
   const legacy = await gradioPredictLegacy(BASE, { fn_index: 0, data: dataArray });
   return extractImageUrl(legacy);
 }

src/app/server/actions/generateStoryLines.ts

@@ -3,9 +3,11 @@
 import "server-only";
 import type { StoryLine, TTSVoice } from "@/types";
 
+// ---- env / config ----
 const BASE = (process.env.AI_STORY_API_GRADIO_URL || "").replace(/\/+$/, "");
 const SECRET = process.env.AI_STORY_API_SECRET_TOKEN || "";
-const LEGACY_FN_INDEX = Number(process.env.AI_STORY_API_FN_INDEX ?? 0); // not used on v5; fallback only
+const LEGACY_FN_INDEX = Number(process.env.AI_STORY_API_FN_INDEX ?? 0); // fallback only
+const HF_TOKEN = process.env.HF_TOKEN || process.env.HUGGING_FACE_HUB_TOKEN || "";
 const DEBUG = (process.env.DEBUG_STORY_API || "").toLowerCase() === "true";
 
 function assertEnv() {
@@ -13,9 +15,16 @@ function assertEnv() {
   if (!SECRET) throw new Error("Missing AI_STORY_API_SECRET_TOKEN");
 }
 
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = {};
+  if (HF_TOKEN) h.Authorization = `Bearer ${HF_TOKEN}`;
+  return h;
+}
+
 function abbrev(s: unknown, n = 1200) {
+  if (s == null) return String(s);
   const t = typeof s === "string" ? s : JSON.stringify(s);
-  return t && t.length > n ? t.slice(0, n) + "…" : t;
+  return t.length > n ? t.slice(0, n) + "…" : t;
 }
 
 async function withTimeout<T>(p: Promise<T>, ms = 120_000) {
@@ -27,7 +36,7 @@ async function withTimeout<T>(p: Promise<T>, ms = 120_000) {
 
 async function timedFetch(url: string, init?: RequestInit) {
   const t0 = Date.now();
-  const res = await withTimeout(fetch(url, init));
+  const res = await withTimeout(fetch(url, init), 120_000);
   return { res, ms: Date.now() - t0 };
 }
 
@@ -35,99 +44,174 @@ function stripToJson(text: string) {
   if (!text) return "";
   const iBrace = text.indexOf("{");
   const iBrack = text.indexOf("[");
-  const i = [iBrace === -1 ? 1e9 : iBrace, iBrack === -1 ? 1e9 : iBrack].reduce((a, b) => Math.min(a, b), 1e9);
-  return i === 1e9 ? text : text.slice(i);
+  const picks = [iBrace, iBrack].filter((i) => i >= 0);
+  if (!picks.length) return text;
+  const i = Math.min(...picks);
+  return text.slice(i);
 }
 
-/** Read a Gradio v5 SSE stream and return the last JSON payload sent in `data:` lines. */
-async function readSSEJson(res: Response, maxMs = 120_000): Promise<any | null> {
+/** Parse SSE and return the JSON payload of the **complete** event (throws on error). */
+async function readSSEComplete(res: Response, { maxMs = 120_000 } = {}): Promise<any | null> {
   const ct = (res.headers.get("content-type") || "").toLowerCase();
+
+  // Some deployments return plain JSON (no SSE) — accept that.
   if (ct.includes("application/json")) {
     const txt = await res.text();
-    try { return JSON.parse(stripToJson(txt)); } catch { return null; }
+    try {
+      return JSON.parse(stripToJson(txt));
+    } catch {
+      return null;
+    }
   }
 
-  // Parse text/event-stream
   const reader = res.body?.getReader();
   if (!reader) return null;
 
   const decoder = new TextDecoder();
   let buf = "";
-  let lastJson: any | null = null;
-  const start = Date.now();
-
-  const flush = (chunk: string) => {
-    buf += chunk;
-    // split events on blank line
-    let m: RegExpMatchArray | null;
-    while ((m = buf.match(/([\s\S]*?)\r?\n\r?\n/)) !== null) {
-      const eventBlock = m[1];
-      buf = buf.slice(m[0].length);
-      const lines = eventBlock.split(/\r?\n/);
-      const dataLines: string[] = [];
-      for (const line of lines) {
-        if (!line) continue;
-        const idx = line.indexOf(":");
-        const field = idx === -1 ? line.trim() : line.slice(0, idx).trim();
-        const value = idx === -1 ? "" : line.slice(idx + 1).replace(/^\s/, "");
-        if (DEBUG && line.trim()) console.log("[SSE]", line);
-        if (field === "data") dataLines.push(value);
+  let currEvent: string | null = null;
+  let dataLines: string[] = [];
+  const started = Date.now();
+
+  const handleBlock = () => {
+    if (!currEvent) return undefined;
+    const payloadText = dataLines.join("\n");
+    if (DEBUG) console.log(`   [SSE event=${currEvent}] ${abbrev(payloadText, 600)}`);
+
+    if (currEvent === "complete") {
+      if (!payloadText) return { type: "complete", json: null as any };
+      try {
+        return { type: "complete", json: JSON.parse(stripToJson(payloadText)) };
+      } catch {
+        return { type: "complete", json: null as any };
       }
-      if (dataLines.length) {
-        const payload = dataLines.join("\n");
-        try {
-          const maybe = JSON.parse(stripToJson(payload));
-          lastJson = maybe;
-        } catch {
-          /* ignore non-JSON frames */
-        }
+    }
+
+    if (currEvent === "error") {
+      let detail: unknown = null;
+      try {
+        detail = payloadText ? JSON.parse(stripToJson(payloadText)) : null;
+      } catch {
+        detail = payloadText;
       }
+      return { type: "error", detail };
     }
+
+    return undefined;
   };
 
   while (true) {
-    if (Date.now() - start > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
+    if (Date.now() - started > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
     const { value, done } = await reader.read();
     if (done) break;
-    flush(decoder.decode(value, { stream: true }));
+
+    buf += decoder.decode(value, { stream: true });
+
+    // split stream into event blocks on blank line
+    let idx: number;
+    // handle consecutive CRLF CRLF properly
+    while ((idx = buf.search(/\r?\n\r?\n/)) !== -1) {
+      const raw = buf.slice(0, idx);
+      buf = buf.slice(idx).replace(/^\r?\n\r?\n/, ""); // remove exactly one blank-separator
+      const lines = raw.split(/\r?\n/);
+
+      // parse fields in this block
+      currEvent = null;
+      dataLines = [];
+      for (const line of lines) {
+        if (!line) continue;
+        if (line[0] === ":") continue; // comment/keepalive
+        const c = line.indexOf(":");
+        const field = (c === -1 ? line : line.slice(0, c)).trim();
+        const val = (c === -1 ? "" : line.slice(c + 1)).replace(/^\s/, "");
+        if (field === "event") currEvent = val;
+        else if (field === "data") dataLines.push(val);
+      }
+
+      const outcome = handleBlock();
+      if (outcome?.type === "complete") return outcome.json;
+      if (outcome?.type === "error") {
+        const msg = typeof outcome.detail === "string" ? outcome.detail : JSON.stringify(outcome.detail);
+        throw new Error(`SSE error event: ${abbrev(msg ?? "null", 1200)}`);
+      }
+    }
+  }
+
+  // Process any trailing block (if stream ended without final blank line)
+  if (buf.trim().length) {
+    const lines = buf.split(/\r?\n/);
+    currEvent = null;
+    dataLines = [];
+    for (const line of lines) {
+      if (!line || line[0] === ":") continue;
+      const c = line.indexOf(":");
+      const field = (c === -1 ? line : line.slice(0, c)).trim();
+      const val = (c === -1 ? "" : line.slice(c + 1)).replace(/^\s/, "");
+      if (field === "event") currEvent = val;
+      else if (field === "data") dataLines.push(val);
+    }
+    const outcome = handleBlock();
+    if (outcome?.type === "complete") return outcome.json;
+    if (outcome?.type === "error") {
+      const msg = typeof outcome.detail === "string" ? outcome.detail : JSON.stringify(outcome.detail);
+      throw new Error(`SSE error event: ${abbrev(msg ?? "null", 1200)}`);
+    }
   }
-  return lastJson;
+
+  return null;
 }
 
-/** v5 call API: POST /gradio_api/call/<fn> → {event_id} → GET /gradio_api/call/<fn>/<event_id> (SSE). */
+/** v5 call API: POST /gradio_api/call/<fn> → {event_id} → GET /gradio_api/call/<fn>/<event_id> (SSE complete). */
 async function gradioCallV5(base: string, fnName: string, dataArray: any[]) {
   const callUrl = `${base}/gradio_api/call/${fnName}`;
 
   const { res: postRes, ms: postMs } = await timedFetch(callUrl, {
     method: "POST",
-    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...authHeaders(),
+    },
     body: JSON.stringify({ data: dataArray }),
     cache: "no-store",
   });
 
   const postText = await postRes.text();
-  const postJson = (() => { try { return JSON.parse(stripToJson(postText)); } catch { return null; } })();
+  const postJson = (() => {
+    try {
+      return JSON.parse(stripToJson(postText));
+    } catch {
+      return null;
+    }
+  })();
 
   if (!postRes.ok) {
     const detail = postJson?.detail ?? postJson?.error ?? postJson?.message ?? postText ?? "(empty body)";
     throw new Error(`POST ${callUrl} → ${postRes.status} in ${postMs}ms — ${abbrev(detail)}`);
   }
+
   const eventId = postJson?.event_id || postJson?.eventId || postJson?.eventID;
   if (!eventId) throw new Error(`POST ${callUrl} returned no event_id`);
 
   const getUrl = `${base}/gradio_api/call/${fnName}/${eventId}`;
   const { res: getRes, ms: getMs } = await timedFetch(getUrl, {
     method: "GET",
-    headers: { Accept: "text/event-stream" },
+    headers: {
+      Accept: "text/event-stream",
+      Connection: "keep-alive",
+      ...authHeaders(),
+    },
+    cache: "no-store",
   });
+
   if (getRes.status !== 200) {
     const txt = await getRes.text();
     throw new Error(`GET ${getUrl} → ${getRes.status} in ${getMs}ms — ${abbrev(txt)}`);
   }
 
-  const json = await readSSEJson(getRes);
+  const json = await readSSEComplete(getRes);
   if (json == null) {
-    // Gradio sometimes sends `event:error` with `data:null`
+    // Gradio sometimes sends event:error with data:null
     throw new Error(`GET ${getUrl} returned no payload (SSE error/null).`);
   }
   return json;
@@ -140,12 +224,24 @@ async function gradioPredictLegacy(base: string, body: any) {
     try {
       const { res, ms } = await timedFetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          ...authHeaders(),
+        },
         body: JSON.stringify(body),
         cache: "no-store",
       });
+
       const txt = await res.text();
-      const json = (() => { try { return JSON.parse(stripToJson(txt)); } catch { return null; } })();
+      const json = (() => {
+        try {
+          return JSON.parse(stripToJson(txt));
+        } catch {
+          return null;
+        }
+      })();
+
       if (res.ok) return json;
       if (DEBUG) console.warn(`Legacy ${url} → ${res.status} in ${ms}ms — ${abbrev(txt)}`);
     } catch (e) {
@@ -158,11 +254,11 @@ async function gradioPredictLegacy(base: string, body: any) {
 /** Normalize various Gradio payload shapes into StoryLine[] */
 function extractStoryLines(payload: any): StoryLine[] {
   let d = payload?.data ?? payload;
+  if (Array.isArray(d) && Array.isArray(d[0])) d = d[0];
   if (!Array.isArray(d)) throw new Error(`Unexpected response: ${abbrev(payload)}`);
-  if (Array.isArray(d[0])) d = d[0];
-  if (!Array.isArray(d)) throw new Error(`Unexpected response: ${abbrev(payload)}`);
-  return d.map((l: any) => ({
-    text: String(l?.text || "")
+
+  return d.map((l: any): StoryLine => ({
+    text: String(l?.text ?? "")
       .replaceAll(" .", ".")
       .replaceAll(" ,", ",")
       .replaceAll(" !", "!")
@@ -179,19 +275,17 @@ export async function generateStoryLines(prompt: string, voice: TTSVoice): Promi
     throw new Error("prompt is too short!");
   }
   const cropped = prompt.slice(0, 30);
-  console.log(`user requested "${cropped}${cropped !== prompt ? "..." : ""}"`);
+  if (DEBUG) console.log(`user requested "${cropped}${cropped !== prompt ? "..." : ""}"`);
 
-  // 1) Preferred: Gradio v5 call API
+  // 1) Preferred: Gradio v5 call API (SSE complete)
   try {
     const json = await gradioCallV5(BASE, "predict", [SECRET, prompt, voice]);
     return extractStoryLines(json);
   } catch (e) {
-    // If the backend returned SSE error/null, surface a clean message,
-    // but still try legacy endpoints once for maximum compatibility.
     console.warn("Gradio v5 call failed:", (e as any)?.message || e);
   }
 
-  // 2) Fallback: legacy JSON endpoints (many Spaces disabled these; may 404)
+  // 2) Fallback: legacy JSON endpoints
   const legacy = await gradioPredictLegacy(BASE, { fn_index: LEGACY_FN_INDEX, data: [SECRET, prompt, voice] });
   return extractStoryLines(legacy);
 }

tests/test_connections/test_endpoints.mjs

@@ -7,86 +7,135 @@ const STORY_SECRET = process.env.AI_STORY_API_SECRET_TOKEN || '';
 const IMG_BASE = (process.env.AI_FAST_IMAGE_SERVER_API_GRADIO_URL || '').replace(/\/+$/, '');
 const IMG_SECRET = process.env.AI_FAST_IMAGE_SERVER_API_SECRET_TOKEN || '';
 
+const HF_TOKEN = process.env.HF_TOKEN || process.env.HUGGING_FACE_HUB_TOKEN || '';
+
 const FN_INDEX = Number(process.env.AI_STORY_API_FN_INDEX ?? 0); // legacy only
 const DEBUG = (process.env.DEBUG_STORY_API || '').toLowerCase() === 'true';
 
 function abbrev(s, n = 1800) {
   if (s == null) return String(s);
-  s = typeof s === 'string' ? s : JSON.stringify(s);
-  return s.length > n ? s.slice(0, n) + '…' : s;
+  const str = typeof s === 'string' ? s : JSON.stringify(s);
+  return str.length > n ? str.slice(0, n) + '…' : str;
 }
+
 function assertEnv() {
   if (!STORY_BASE) throw new Error('Missing AI_STORY_API_GRADIO_URL in .env');
   if (!STORY_SECRET) throw new Error('Missing AI_STORY_API_SECRET_TOKEN in .env');
 }
+
+function authHeaders() {
+  const h = {};
+  if (HF_TOKEN) h.Authorization = `Bearer ${HF_TOKEN}`;
+  return h;
+}
+
 async function withTimeout(promise, ms = 120_000) {
   return Promise.race([
     promise,
     new Promise((_, rej) => setTimeout(() => rej(new Error(`Timeout after ${ms}ms`)), ms)),
   ]);
 }
+
 async function timedFetch(url, init) {
   const t0 = Date.now();
   const res = await withTimeout(fetch(url, init));
   const ms = Date.now() - t0;
   return { res, ms };
 }
+
 function stripToJson(text) {
   if (!text) return '';
-  const i = Math.min(
-    ...['{', '['].map(ch => {
-      const p = text.indexOf(ch);
-      return p === -1 ? Number.POSITIVE_INFINITY : p;
-    }),
-  );
-  return i === Number.POSITIVE_INFINITY ? text : text.slice(i);
+  const ixBrace = text.indexOf('{');
+  const ixBracket = text.indexOf('[');
+  const pick = [ixBrace, ixBracket].filter((i) => i >= 0);
+  if (!pick.length) return text;
+  const i = Math.min(...pick);
+  return text.slice(i);
 }
 
-/** Parse SSE and return the last JSON payload carried in `data:` lines. */
-async function readSSEJson(res, { maxMs = 120_000 } = {}) {
+/** Parse SSE and return the JSON payload of the **complete** event (throw on error). */
+async function readSSEComplete(res, { maxMs = 120_000 } = {}) {
   const ct = (res.headers.get('content-type') || '').toLowerCase();
+  // Some deployments reply JSON directly (no SSE) — accept that.
   if (ct.includes('application/json')) {
     const txt = await res.text();
-    try { return JSON.parse(stripToJson(txt)); } catch { return null; }
+    try {
+      return JSON.parse(stripToJson(txt));
+    } catch {
+      return null;
+    }
   }
 
+  // Proper SSE parse: look for event: complete / event: error
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buf = '';
-  let lastJson = null;
-  const start = Date.now();
-
-  const flush = (chunk) => {
-    buf += chunk;
-    let sep;
-    while ((sep = buf.search(/\r?\n\r?\n/)) !== -1) {
-      const raw = buf.slice(0, sep);
-      buf = buf.slice(sep).replace(/^\r?\n/, '');
-      const lines = raw.split(/\r?\n/);
-      const dataLines = [];
-      for (const line of lines) {
-        if (!line) continue;
-        if (DEBUG && line.trim()) console.log('  [SSE]', abbrev(line, 300));
-        const idx = line.indexOf(':');
-        if (idx === -1) continue;
-        const field = line.slice(0, idx).trim();
-        const value = line.slice(idx + 1).replace(/^\s/, '');
-        if (field === 'data') dataLines.push(value);
+  let currEvent = null;
+  let dataLines = [];
+  const started = Date.now();
+
+  const handleBlock = () => {
+    if (!currEvent) return;
+    const payloadText = dataLines.join('\n');
+    if (DEBUG) console.log(`   [SSE event=${currEvent}] ${abbrev(payloadText, 600)}`);
+    if (currEvent === 'complete') {
+      if (!payloadText) return { type: 'complete', json: null };
+      try {
+        return { type: 'complete', json: JSON.parse(stripToJson(payloadText)) };
+      } catch {
+        return { type: 'complete', json: null };
       }
-      if (dataLines.length) {
-        const payload = dataLines.join('\n');
-        try { lastJson = JSON.parse(stripToJson(payload)); } catch {}
+    }
+    if (currEvent === 'error') {
+      let detail = null;
+      try {
+        detail = payloadText ? JSON.parse(stripToJson(payloadText)) : null;
+      } catch {
+        detail = payloadText;
       }
+      return { type: 'error', detail };
     }
+    return undefined;
   };
 
   while (true) {
-    if (Date.now() - start > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
+    if (Date.now() - started > maxMs) throw new Error(`SSE read timeout after ${maxMs}ms`);
     const { value, done } = await reader.read();
     if (done) break;
-    flush(decoder.decode(value, { stream: true }));
+    buf += decoder.decode(value, { stream: true });
+
+    // Normalize CRLF and split into blocks
+    let idx;
+    while ((idx = buf.search(/\r?\n\r?\n/)) !== -1) {
+      const raw = buf.slice(0, idx);
+      buf = buf.slice(idx).replace(/^\r?\n/, '');
+      const lines = raw.split(/\r?\n/);
+
+      // Parse fields inside this SSE block
+      currEvent = null;
+      dataLines = [];
+      for (const line of lines) {
+        if (!line) continue;
+        // comment keep-alive lines start with ':'
+        if (line[0] === ':') continue;
+        const c = line.indexOf(':');
+        const field = (c === -1 ? line : line.slice(0, c)).trim();
+        const val = (c === -1 ? '' : line.slice(c + 1)).replace(/^\s/, '');
+        if (field === 'event') currEvent = val;
+        else if (field === 'data') dataLines.push(val);
+      }
+
+      const outcome = handleBlock();
+      if (outcome?.type === 'complete') return outcome.json;
+      if (outcome?.type === 'error') {
+        const msg = typeof outcome.detail === 'string'
+          ? outcome.detail
+          : JSON.stringify(outcome.detail);
+        throw new Error(`SSE error event: ${abbrev(msg ?? 'null', 1200)}`);
+      }
+    }
   }
-  return lastJson;
+  return null;
 }
 
 /** Gradio v5: POST /gradio_api/call/<fn> -> {event_id}, then GET /gradio_api/call/<fn>/<event_id> (SSE) */
@@ -99,13 +148,19 @@ async function tryCallApi(base, fnName, dataArray) {
 
   const { res: postRes, ms: postMs } = await timedFetch(callUrl, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...authHeaders() },
     body: JSON.stringify(postBody),
     cache: 'no-store',
   });
 
   const postText = await postRes.text();
-  const postJson = (() => { try { return JSON.parse(stripToJson(postText)); } catch { return null; } })();
+  const postJson = (() => {
+    try {
+      return JSON.parse(stripToJson(postText));
+    } catch {
+      return null;
+    }
+  })();
 
   if (!postRes.ok) {
     const detail = postJson?.detail ?? postJson?.error ?? postJson?.message ?? postText ?? '(empty body)';
@@ -123,7 +178,8 @@ async function tryCallApi(base, fnName, dataArray) {
 
   const { res: getRes, ms: getMs } = await timedFetch(getUrl, {
     method: 'GET',
-    headers: { Accept: 'text/event-stream' },
+    headers: { Accept: 'text/event-stream', ...authHeaders() },
+    cache: 'no-store',
   });
 
   if (getRes.status !== 200) {
@@ -131,8 +187,8 @@ async function tryCallApi(base, fnName, dataArray) {
     throw new Error(`HTTP ${getRes.status} ${getRes.statusText} in ${getMs}ms — ${abbrev(txt, 800)}`);
   }
 
-  const json = await readSSEJson(getRes);
-  console.log(`  ✅ OK 200 in ${getMs}ms`);
+  const json = await readSSEComplete(getRes);
+  console.log(`   ✅ OK 200 in ${getMs}ms`);
   if (DEBUG) console.log('  json:', abbrev(JSON.stringify(json), 2000));
   return { ok: true, url: getUrl, json, ms: getMs };
 }
@@ -148,24 +204,26 @@ async function tryPredictLegacy(base, body) {
 
       const { res, ms } = await timedFetch(url, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...authHeaders() },
         body: JSON.stringify(body),
         cache: 'no-store',
       });
 
       const text = await res.text();
       let json = null;
-      try { json = JSON.parse(stripToJson(text)); } catch {}
+      try {
+        json = JSON.parse(stripToJson(text));
+      } catch {}
       if (res.ok) {
-        console.log(`  ✅ OK ${res.status} in ${ms}ms`);
+        console.log(`   ✅ OK ${res.status} in ${ms}ms`);
         if (DEBUG) console.log('  json:', abbrev(JSON.stringify(json), 2000));
         return { ok: true, url, json, ms };
       }
 
       const detail = json?.detail ?? json?.error ?? json?.message ?? text ?? '(empty body)';
-      console.error(`  ❌ HTTP ${res.status} ${res.statusText} in ${ms}ms — ${abbrev(String(detail), 1200)}`);
+      console.error(`   ❌ HTTP ${res.status} ${res.statusText} in ${ms}ms — ${abbrev(String(detail), 1200)}`);
     } catch (e) {
-      console.error(`  ❌ ${url} failed: ${e?.message || e}`);
+      console.error(`   ❌ ${url} failed: ${e?.message || e}`);
     }
   }
   return { ok: false };
@@ -186,9 +244,9 @@ async function testStoryEndpoint() {
   console.log('TOKEN:', STORY_SECRET ? '(present)' : '(MISSING)');
   console.log('FN   :', FN_INDEX);
 
-  // HEAD liveness
+  // HEAD liveness (with auth if provided)
   try {
-    const { res, ms } = await timedFetch(STORY_BASE + '/', { method: 'HEAD' });
+    const { res, ms } = await timedFetch(STORY_BASE + '/', { method: 'HEAD', headers: authHeaders() });
     console.log(`HEAD ${STORY_BASE}/ -> ${res.status} in ${ms}ms`);
   } catch (e) {
     console.warn('HEAD failed:', e?.message || e);
@@ -204,12 +262,11 @@ async function testStoryEndpoint() {
 
     const lines = extractStoryLines(out.json);
     if (Array.isArray(lines)) {
-      console.log(`  ✅ Received ${lines.length} story lines`);
+      console.log(`   ✅ Received ${lines.length} story lines`);
       return;
     }
 
-    // If SSE returned null or unparseable, treat as liveness pass with a warning.
-    console.warn('⚠️ Story endpoint returned no JSON payload (SSE error/null). Treating as reachable.');
+    console.warn('⚠️ Story endpoint returned no recognized payload (SSE complete missing/empty). Treating as reachable.');
     return;
   } catch (e) {
     console.warn('Gradio v5 call API failed for story:', e?.message || e);
@@ -222,7 +279,7 @@ async function testStoryEndpoint() {
   if (!Array.isArray(lines)) {
     console.warn('⚠️ Legacy story payload not recognized, but endpoint responded. Treating as reachable.');
   } else {
-    console.log(`  ✅ Legacy story returned ${lines.length} lines`);
+    console.log(`   ✅ Legacy story returned ${lines.length} lines`);
   }
 }
 
@@ -249,7 +306,7 @@ async function testImageEndpoint() {
       (payload && typeof payload === 'object' && ('url' in payload || 'path' in payload));
 
     if (ok) {
-      console.log('  ✅ Image endpoint responded.');
+      console.log('   ✅ Image endpoint responded.');
       return;
     }
     console.warn('⚠️ Image payload not recognized, but endpoint responded. Treating as reachable.');
@@ -266,7 +323,7 @@ async function testImageEndpoint() {
     Array.isArray(payload) ||
     (payload && typeof payload === 'object' && ('url' in payload || 'path' in payload));
   if (!ok) console.warn('⚠️ Legacy image payload not recognized, but endpoint responded. Treating as reachable.');
-  else console.log('  ✅ Legacy image endpoint responded.');
+  else console.log('   ✅ Legacy image endpoint responded.');
 }
 
 (async () => {
@@ -279,4 +336,4 @@ async function testImageEndpoint() {
     console.error('\nTests failed ❌:', e?.message || e);
     process.exit(1);
   }
-})();
+})();

tests/test_connections/test_endpoints.sh

@@ -22,6 +22,12 @@ STORY_PROMPT="${1:-A short wholesome bedtime story about a friendly dragon.}"
 VOICE="${2:-Cloée}"
 IMG_PROMPT="${3:-a cute cat sticker}"
 
+# Optional Bearer (for private Space / ZeroGPU quota)
+AUTH_HEADER=()
+if [[ -n "${HF_TOKEN:-}" ]]; then
+  AUTH_HEADER=(-H "Authorization: Bearer ${HF_TOKEN}")
+fi
+
 has_jq() { command -v jq >/dev/null 2>&1; }
 pretty() { if has_jq; then jq . || cat; else cat; fi; }
 
@@ -41,28 +47,75 @@ strip_to_json() {
 post_json() {
   local url="$1" json="$2"
   echo "POST $url" >&2
-  curl -sS -H "Content-Type: application/json" -X POST "$url" -d "$json" -w "\nHTTP_STATUS:%{http_code}"
+  curl -sS -H "Content-Type: application/json" "${AUTH_HEADER[@]}" \
+       -X POST "$url" -d "$json" -w "\nHTTP_STATUS:%{http_code}"
 }
 
 # GET helper (returns BODY + trailing HTTP_STATUS line)
 get_url() {
   local url="$1"
   echo "GET  $url" >&2
-  curl -sS "$url" -w "\nHTTP_STATUS:%{http_code}"
+  curl -sS "${AUTH_HEADER[@]}" "$url" -w "\nHTTP_STATUS:%{http_code}"
 }
 
-# New Gradio v4/v5 call API: POST -> event_id -> GET result
+# --- Parse a Gradio SSE GET stream and echo the `complete` JSON object ---
+# Returns 0 on success and prints the JSON object to stdout.
+# Returns 1 on SSE `error` (prints details to stderr if present).
+# Returns 2 on malformed/unknown stream.
+parse_sse_complete() {
+  local stream_file="$1"
+  local event="" data_buf="" complete_json="" error_json=""
+
+  # Normalize CRLF in stream (if any)
+  sed -i 's/\r$//' "$stream_file"
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ "$line" == event:* ]]; then
+      event="${line#event: }"
+      continue
+    fi
+    if [[ "$line" == data:* ]]; then
+      local d="${line#data: }"
+      if [[ -z "$data_buf" ]]; then data_buf="$d"; else data_buf+=$'\n'"$d"; fi
+      continue
+    fi
+    # blank line = event separator
+    if [[ -z "$line" ]]; then
+      if [[ "$event" == "complete" ]]; then
+        complete_json="$data_buf"; break
+      elif [[ "$event" == "error" ]]; then
+        error_json="$data_buf"; break
+      fi
+      event=""; data_buf=""
+    fi
+  done < "$stream_file"
+
+  if [[ -n "$complete_json" ]]; then
+    printf '%s' "$complete_json"
+    return 0
+  fi
+  if [[ -n "$error_json" && "$error_json" != "null" ]]; then
+    echo "SSE error event:" >&2
+    echo "$error_json" >&2
+    return 1
+  fi
+
+  echo "SSE stream had no complete/error event. Raw stream follows:" >&2
+  cat "$stream_file" >&2
+  return 2
+}
+
+# New Gradio v4/v5 call API: POST -> event_id -> GET SSE -> complete JSON
 try_call_api() {
   local base="$1" func="$2" json="$3"
   local call_url="${base%/}/gradio_api/call/$func"
-  local out status body body_json event_id get_url_full get_out get_status get_body get_json
+  local out status body body_json event_id get_url_full stream_file comp_json
 
   out="$(post_json "$call_url" "$json" || true)"
   status="${out##*HTTP_STATUS:}"
   body="${out%HTTP_STATUS:*}"
   body_json="$(printf '%s' "$body" | strip_to_json)"
 
-  # Always show the POST response JSON (event_id or error)
   echo "---- ${func}: POST response ----"
   printf '%s\n' "$body_json" | pretty
   echo "--------------------------------"
@@ -73,34 +126,44 @@ try_call_api() {
     return 1
   fi
 
-  # Parse event_id safely
+  # Parse event_id
   if has_jq; then
     event_id="$(printf '%s' "$body_json" | jq -r '.event_id // .eventId // .eventID // empty' 2>/dev/null || echo "")"
   else
     event_id="$(printf '%s' "$body_json" | sed -n 's/.*"event_id"[[:space:]]*:[[:space:]]*"\([^"]\+\)".*/\1/p')"
   fi
-
   if [[ -z "${event_id:-}" ]]; then
     echo "-> Missing event_id in response." >&2
     return 1
   fi
 
+  # GET SSE
   get_url_full="${base%/}/gradio_api/call/$func/$event_id"
-  get_out="$(get_url "$get_url_full" || true)"
-  get_status="${get_out##*HTTP_STATUS:}"
-  get_body="${get_out%HTTP_STATUS:*}"
-  get_json="$(printf '%s' "$get_body" | strip_to_json)"
-
-  # Always show the GET result JSON
-  echo "---- ${func}: GET result ----"
-  printf '%s\n' "$get_json" | pretty
-  echo "-----------------------------"
-
-  if [[ "$get_status" != "200" ]]; then
-    echo "-> ${get_status} from $get_url_full" >&2
-    printf '%s\n' "$get_body" | head -c 500 >&2; echo >&2
+  stream_file="$(mktemp)"
+  echo "GET  $get_url_full" >&2
+  curl -sS -N -H "Accept: text/event-stream" "${AUTH_HEADER[@]}" \
+       "$get_url_full" > "$stream_file"
+
+  # Parse SSE to the complete event JSON object
+  if ! comp_json="$(parse_sse_complete "$stream_file")"; then
+    rm -f "$stream_file"
     return 1
   fi
+  rm -f "$stream_file"
+
+  # Show full `complete` JSON (wrapper includes {"data":[ ... ], ...})
+  echo "---- ${func}: GET (complete event) ----"
+  printf '%s\n' "$comp_json" | pretty
+  echo "--------------------------------------"
+
+  # If this is the story function, also print ONLY the story component (.data[0])
+  if [[ "$base" == "$STORY_BASE" && "$func" == "predict" ]]; then
+    if has_jq && jq -e '.data | type == "array" and (.data | length) > 0' >/dev/null 2>&1 <<<"$comp_json"; then
+      echo "---- story data (.data[0]) ----"
+      jq -r '.data[0]' <<<"$comp_json"
+      echo "-------------------------------"
+    fi
+  fi
 
   echo "-> 200 OK (call API)"
   return 0

tests/test_connections/test_story.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# tests/test_connections/test_story.sh
+# One-file cURL client for ruslanmv/ai-story-server-cpu -> /predict (SSE aware)
+# Loads .env automatically from repo root if present.
+
+set -euo pipefail
+
+# Optional debug
+[[ "${DEBUG:-}" == "1" ]] && set -x
+
+# Ensure UTF-8 (for "Cloée")
+export LANG="${LANG:-C.UTF-8}"
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+# --- requirements ---
+for dep in curl jq; do
+  command -v "$dep" >/dev/null 2>&1 || { echo "Error: $dep is required." >&2; exit 1; }
+done
+
+# --- load .env from repo root (two levels up from this script) ---
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd -P)"
+ENV_FILE="${ENV_FILE:-${REPO_ROOT}/.env}"
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$ENV_FILE"
+  set +a
+fi
+
+# --- config (env > .env > defaults) ---
+SPACE_URL="${SPACE_URL:-${AI_STORY_API_GRADIO_URL:-https://ruslanmv-ai-story-server-cpu.hf.space}}"
+API_PATH="/gradio_api/call/predict"
+
+SECRET="${SECRET_TOKEN:-${AI_STORY_API_SECRET_TOKEN:-secret}}"
+PROMPT="${STORY_PROMPT:-${1:-A cozy bedtime story about a friendly dragon who learns to paint}}"
+ROLE="${STORY_ROLE:-${2:-Cloée}}"
+
+case "$ROLE" in
+  "Cloée"|"Julian"|"Pirate"|"Thera") ;;
+  *) echo "Error: STORY_ROLE must be one of: Cloée, Julian, Pirate, Thera" >&2; exit 1;;
+esac
+
+AUTH_HEADER=()
+[[ -n "${HF_TOKEN:-}" ]] && AUTH_HEADER+=(-H "Authorization: Bearer ${HF_TOKEN}")
+
+# --- body (order matters: [secret, prompt, role]) ---
+POST_BODY="$(jq -cn --arg s "$SECRET" --arg p "$PROMPT" --arg r "$ROLE" '{data: [$s, $p, $r]}')"
+
+# --- temp files ---
+POST_OUT="$(mktemp)"
+STREAM_OUT="$(mktemp)"
+cleanup() { rm -f "$POST_OUT" "$STREAM_OUT"; }
+trap cleanup EXIT
+
+# --- 1) POST -> get event_id ---
+HTTP_CODE="$(curl -sS -o "$POST_OUT" -w "%{http_code}" \
+  -X POST "${SPACE_URL}${API_PATH}" \
+  -H "Content-Type: application/json" "${AUTH_HEADER[@]}" \
+  -d "$POST_BODY")"
+
+if [[ "$HTTP_CODE" != "200" ]]; then
+  echo "Error: POST returned HTTP $HTTP_CODE" >&2
+  cat "$POST_OUT" >&2
+  exit 3
+fi
+if ! jq -e '.event_id' "$POST_OUT" >/dev/null 2>&1; then
+  echo "Error: POST did not return JSON with .event_id" >&2
+  cat "$POST_OUT" >&2
+  exit 3
+fi
+EVENT_ID="$(jq -r '.event_id' "$POST_OUT")"
+
+# --- 2) GET SSE stream (single attempt) ---
+curl -sS -N "${SPACE_URL}${API_PATH}/${EVENT_ID}" \
+     -H "Accept: text/event-stream" "${AUTH_HEADER[@]}" > "$STREAM_OUT"
+
+# --- 3) Parse SSE in pure bash (no awk) ---
+event=""
+data_buf=""
+complete_json=""
+error_json=""
+
+while IFS= read -r line || [[ -n "$line" ]]; do
+  if [[ "$line" == event:* ]]; then
+    event="${line#event: }"
+    continue
+  fi
+  if [[ "$line" == data:* ]]; then
+    d="${line#data: }"
+    if [[ -z "$data_buf" ]]; then data_buf="$d"; else data_buf+=$'\n'"$d"; fi
+    continue
+  fi
+  # blank line = event separator
+  if [[ -z "$line" ]]; then
+    if [[ "$event" == "complete" ]]; then
+      complete_json="$data_buf"; break
+    elif [[ "$event" == "error" ]]; then
+      error_json="$data_buf"; break
+    fi
+    event=""; data_buf=""
+  fi
+done < "$STREAM_OUT"
+
+# --- 4) Decide outcome ---
+if [[ -n "$complete_json" ]]; then
+  if ! jq -e '.data | type == "array" and (.data | length) > 0' >/dev/null 2>&1 <<<"$complete_json"; then
+    echo "Error: Unexpected JSON from complete event:" >&2
+    echo "$complete_json" >&2
+    exit 2
+  fi
+  jq -r '.data[0]' <<<"$complete_json"
+  exit 0
+fi
+
+# error or nothing
+if [[ -n "$error_json" && "$error_json" != "null" ]]; then
+  echo "Error: Server error:" >&2
+  echo "$error_json" >&2
+else
+  echo "Error: Space returned SSE error with no details (likely ZeroGPU quota or invalid secret)." >&2
+  echo "Hints: verify SECRET, set HF_TOKEN (loaded from .env if present), or try later." >&2
+fi
+exit 1