@genex-ai/cli-demo 0.62.0-dev.143 → 0.62.0-dev.144

package/dist/index.js

@@ -1929,11 +1929,69 @@ async function runMakeRemixable(opts) {
 }
 
 // src/lib/detect-features.ts
+import fs11 from "fs/promises";
+import path12 from "path";
+
+// src/lib/generation-ledger.ts
 import fs10 from "fs/promises";
 import path11 from "path";
+var ledgerPath = (cwd) => path11.join(cwd, ".genex", "generations.ndjson");
+async function append(cwd, event) {
+  try {
+    await fs10.access(path11.join(cwd, ".genex"));
+    await fs10.appendFile(ledgerPath(cwd), `${JSON.stringify(event)}
+`, "utf8");
+  } catch {
+  }
+}
+async function readLedger(cwd = process.cwd()) {
+  let raw;
+  try {
+    raw = await fs10.readFile(ledgerPath(cwd), "utf8");
+  } catch {
+    return [];
+  }
+  const entries = /* @__PURE__ */ new Map();
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.t === "q" && typeof e.id === "string" && typeof e.kind === "string") {
+        if (!entries.has(e.id)) {
+          entries.set(e.id, {
+            id: e.id,
+            kind: e.kind,
+            prompt: typeof e.prompt === "string" ? e.prompt : "",
+            queuedAt: typeof e.at === "string" ? e.at : "",
+            status: "queued"
+          });
+        }
+      } else if (e.t === "done" && typeof e.id === "string") {
+        const entry = entries.get(e.id);
+        if (entry && (e.status === "completed" || e.status === "failed")) {
+          entry.status = e.status;
+          if (Array.isArray(e.urls)) entry.urls = e.urls.filter((u) => typeof u === "string");
+        }
+      }
+    } catch {
+    }
+  }
+  return [...entries.values()];
+}
+async function recordQueued(id, kind, prompt, cwd = process.cwd()) {
+  await append(cwd, { t: "q", id, kind, prompt: prompt.slice(0, 120), at: (/* @__PURE__ */ new Date()).toISOString() });
+}
+async function recordTerminal(id, status, urls, cwd = process.cwd()) {
+  await append(cwd, { t: "done", id, status, ...urls?.length ? { urls } : {} });
+}
+async function countFailed(kind, cwd = process.cwd()) {
+  return (await readLedger(cwd)).filter((e) => e.kind === kind && e.status === "failed").length;
+}
+
+// src/lib/detect-features.ts
 async function detectEmbedSdkVersion(cwd = process.cwd()) {
   try {
-    const raw = await fs10.readFile(path11.join(cwd, "package.json"), "utf8");
+    const raw = await fs11.readFile(path12.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     const version = pkg.dependencies?.["@genex-ai/embed-sdk"] ?? pkg.devDependencies?.["@genex-ai/embed-sdk"];
     return typeof version === "string" && version ? version : null;
@@ -1943,7 +2001,7 @@ async function detectEmbedSdkVersion(cwd = process.cwd()) {
 }
 async function detectMultiplayer(cwd = process.cwd()) {
   try {
-    const raw = await fs10.readFile(path11.join(cwd, "package.json"), "utf8");
+    const raw = await fs11.readFile(path12.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     return Boolean(
       pkg.dependencies?.["@genex-ai/multiplayer"] ?? pkg.devDependencies?.["@genex-ai/multiplayer"]
@@ -1955,7 +2013,7 @@ async function detectMultiplayer(cwd = process.cwd()) {
 async function detectMatchmaking(log, cwd = process.cwd()) {
   let pkg;
   try {
-    pkg = JSON.parse(await fs10.readFile(path11.join(cwd, "package.json"), "utf8"));
+    pkg = JSON.parse(await fs11.readFile(path12.join(cwd, "package.json"), "utf8"));
   } catch (err) {
     log.dim(`  (skipping matchmaking \u2014 couldn't read package.json: ${String(err)})`);
     return null;
@@ -1972,10 +2030,10 @@ async function detectMatchmaking(log, cwd = process.cwd()) {
 }
 var GAME_STATE_CALLS = /savePlayerState|saveWorldState|submitScore/;
 async function detectGameStateUsage(cwd = process.cwd()) {
-  const srcDir = path11.join(cwd, "src");
+  const srcDir = path12.join(cwd, "src");
   let entries;
   try {
-    entries = await fs10.readdir(srcDir, { recursive: true });
+    entries = await fs11.readdir(srcDir, { recursive: true });
   } catch {
     return false;
   }
@@ -1983,7 +2041,7 @@ async function detectGameStateUsage(cwd = process.cwd()) {
     if (rel.includes("node_modules")) continue;
     if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
     try {
-      const content = await fs10.readFile(path11.join(srcDir, rel), "utf8");
+      const content = await fs11.readFile(path12.join(srcDir, rel), "utf8");
       if (GAME_STATE_CALLS.test(content)) return true;
     } catch {
     }
@@ -1993,14 +2051,14 @@ async function detectGameStateUsage(cwd = process.cwd()) {
 var UI_PHASE_MARKERS = /data-phase|setPhase/;
 async function detectUiPhases(cwd = process.cwd()) {
   try {
-    const html = await fs10.readFile(path11.join(cwd, "index.html"), "utf8").catch(() => "");
+    const html = await fs11.readFile(path12.join(cwd, "index.html"), "utf8").catch(() => "");
     if (UI_PHASE_MARKERS.test(html)) return true;
-    const srcDir = path11.join(cwd, "src");
-    const entries = await fs10.readdir(srcDir, { recursive: true });
+    const srcDir = path12.join(cwd, "src");
+    const entries = await fs11.readdir(srcDir, { recursive: true });
     for (const rel of entries) {
       if (rel.includes("node_modules")) continue;
       if (!/\.(ts|js|mts|mjs|tsx|jsx|html|css)$/.test(rel)) continue;
-      const content = await fs10.readFile(path11.join(srcDir, rel), "utf8").catch(() => "");
+      const content = await fs11.readFile(path12.join(srcDir, rel), "utf8").catch(() => "");
       if (UI_PHASE_MARKERS.test(content)) return true;
     }
     return false;
@@ -2045,17 +2103,17 @@ var lineOf = (content, index) => content.slice(0, index).split("\n").length;
 var DEPTH_RATIO_LIMIT = 1e6;
 async function detectSurfaceScan(cwd = process.cwd()) {
   const found = { guessedRepeat: [], squarePoints: [], depthRange: [] };
-  const srcDir = path11.join(cwd, "src");
+  const srcDir = path12.join(cwd, "src");
   let entries;
   try {
-    entries = await fs10.readdir(srcDir, { recursive: true });
+    entries = await fs11.readdir(srcDir, { recursive: true });
   } catch {
     return found;
   }
   for (const rel of entries) {
     if (rel.includes("node_modules")) continue;
     if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
-    const raw = await fs10.readFile(path11.join(srcDir, rel), "utf8").catch(() => "");
+    const raw = await fs11.readFile(path12.join(srcDir, rel), "utf8").catch(() => "");
     if (!raw) continue;
     const content = raw.replace(/\/\*[\s\S]*?\*\//g, (m2) => m2.replace(/[^\n]/g, " ")).replace(/(^|[^:])\/\/[^\n]*/gm, (m2, p1) => p1 + " ".repeat(m2.length - p1.length));
     const repeatRe = /\.repeat\.set\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
@@ -2093,6 +2151,54 @@ async function detectSurfaceScan(cwd = process.cwd()) {
   }
   return found;
 }
+var WIRED_BY_URL = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "video"]);
+var UNPICKED_AFTER_MS = 15 * 60 * 1e3;
+async function detectGenerationAudit(cwd = process.cwd()) {
+  const ledger = await readLedger(cwd);
+  const audited = ledger.filter((e) => WIRED_BY_URL.has(e.kind));
+  if (audited.length === 0) return { unwired: [], unpicked: [] };
+  let haystack = "";
+  const read = async (file) => {
+    try {
+      haystack += await fs11.readFile(file, "utf8");
+    } catch {
+    }
+  };
+  try {
+    for (const entry of await fs11.readdir(cwd, { withFileTypes: true })) {
+      if (entry.isFile() && /\.(ts|tsx|js|jsx|css|html|json)$/.test(entry.name)) {
+        await read(path12.join(cwd, entry.name));
+      }
+    }
+  } catch {
+  }
+  for (const sub of ["src", "public"]) {
+    try {
+      const entries = await fs11.readdir(path12.join(cwd, sub), { recursive: true });
+      for (const rel of entries) {
+        if (rel.includes("node_modules")) continue;
+        if (!/\.(ts|tsx|js|jsx|css|html|json|txt)$/.test(rel)) continue;
+        await read(path12.join(cwd, sub, rel));
+      }
+    } catch {
+    }
+  }
+  const ref = ({ id, kind, prompt }) => ({
+    id,
+    kind,
+    prompt
+  });
+  const now = Date.now();
+  return {
+    unwired: audited.filter((e) => e.status === "completed" && !haystack.includes(e.id)).map(ref),
+    // An id already referenced in the game was obviously picked up — a stale
+    // "queued" record (e.g. `genex wait` ran from another directory) must not
+    // nag about an asset that's wired in and working.
+    unpicked: audited.filter(
+      (e) => e.status === "queued" && !haystack.includes(e.id) && now - Date.parse(e.queuedAt) > UNPICKED_AFTER_MS
+    ).map(ref)
+  };
+}
 async function detectFeatures(log, cwd = process.cwd()) {
   return {
     embedSdkVersion: await detectEmbedSdkVersion(cwd),
@@ -2100,7 +2206,8 @@ async function detectFeatures(log, cwd = process.cwd()) {
     matchmaking: await detectMatchmaking(log, cwd),
     gameStateUsed: await detectGameStateUsage(cwd),
     uiPhases: await detectUiPhases(cwd),
-    surfaces: await detectSurfaceScan(cwd)
+    surfaces: await detectSurfaceScan(cwd),
+    generations: await detectGenerationAudit(cwd)
   };
 }
 function advisoryNudges(log, d) {
@@ -2125,6 +2232,20 @@ function advisoryNudges(log, d) {
     );
   }
   surfaceNudges(log, d.surfaces);
+  generationNudges(log, d.generations);
+}
+function generationNudges(log, g) {
+  const describe = (refs) => refs.map((r) => `${r.kind} ${r.id} ("${r.prompt.slice(0, 48)}")`).join("; ");
+  if (g.unpicked.length) {
+    log.warn(
+      `${g.unpicked.length} generation(s) enqueued 15+ minutes ago were never picked up: ${describe(g.unpicked)}. Run npx genex wait <id> on each \u2014 landed assets get wired in before the last push of a session, never parked for "later".`
+    );
+  }
+  if (g.unwired.length) {
+    log.warn(
+      `${g.unwired.length} finished generation(s) are wired nowhere in the game: ${describe(g.unwired)}. Each was paid for \u2014 wire it in (its URL embeds the id) or tell the user in one plain line why it stays unused.`
+    );
+  }
 }
 function surfaceNudges(log, s) {
   if (s.guessedRepeat.length) {
@@ -2518,6 +2639,7 @@ async function runGenerate(kind, opts) {
     process.exitCode = 1;
     return;
   }
+  await recordQueued(id, kind, prompt);
   if (opts.noWait) {
     log.success(`Queued (${id}).`);
     log.plain(`  Pick it up any time with: ${c.cyan(`npx genex wait ${id}`)}`);
@@ -2544,6 +2666,13 @@ async function awaitAndReport(apiUrl, token, id, kind, log, open = false) {
 async function reportTerminal(kind, view, log, open = false) {
   if (view.status !== "completed") {
     log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
+    if (view.status === "failed") {
+      await recordTerminal(view.id, "failed");
+      if (kind === "video") {
+        const failures = await countFailed("video");
+        (failures >= 2 ? log.plain : log.dim)(videoFailureAdvice(failures));
+      }
+    }
     process.exitCode = 1;
     return;
   }
@@ -2553,6 +2682,7 @@ async function reportTerminal(kind, view, log, open = false) {
     process.exitCode = 1;
     return;
   }
+  await recordTerminal(view.id, "completed", files.map((f) => f.url));
   log.plain("");
   log.success("Done \u2014 live on R2 (nothing downloaded or committed):");
   for (const f of files) {
@@ -2572,6 +2702,12 @@ async function reportTerminal(kind, view, log, open = false) {
   printHint(kind, view, files, log);
   await firstPreviewNudge(log);
 }
+function videoFailureAdvice(failures) {
+  if (failures >= 2) {
+    return `  ${c.bold(`\u270B ${failures} failed videos in this project \u2014 don't queue another attempt of the same clip.`)} One retry per clip is the budget. Use its key-art still as the backdrop instead (the genex-ai-menu skill's built-in fallback; a slow CSS pan gives it life), tell the user in one plain line, and spend the minutes in the game.`;
+  }
+  return "  Video renders fail server-side sometimes. One retry is fair \u2014 shorter clip (4\u20136 s), simpler motion. After a second failure, switch to the key-art still (genex-ai-menu's fallback) instead of a third attempt.";
+}
 var WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
 var KIND_WAIT_TIMEOUT_MS = {
   video: 15 * 60 * 1e3,
@@ -2752,8 +2888,8 @@ async function runWait(opts) {
 }
 
 // src/commands/controller.ts
-import fs12 from "fs/promises";
-import path13 from "path";
+import fs13 from "fs/promises";
+import path14 from "path";
 
 // ../../packages/meshy-animation-catalog/src/index.ts
 import { createHash } from "crypto";
@@ -11883,9 +12019,9 @@ function searchMeshyAnimations(query, options = {}) {
 }
 
 // src/lib/anims.ts
-import fs11 from "fs/promises";
-import path12 from "path";
-var ANIMS_DEST = path12.join("public", "assets", "anims");
+import fs12 from "fs/promises";
+import path13 from "path";
+var ANIMS_DEST = path13.join("public", "assets", "anims");
 var HIDDEN_TAG = "reference";
 async function runAnims(opts) {
   const log = createLogger({ quiet: opts.quiet });
@@ -11901,7 +12037,7 @@ async function runAnims(opts) {
     printCatalog(log, manifest, selectors);
     return;
   }
-  const controllerMarker = path12.join(root, "src", "controllers", "character");
+  const controllerMarker = path13.join(root, "src", "controllers", "character");
   if (!await exists2(controllerMarker)) {
     log.error(
       `No character controller in this game (missing ${c.cyan("src/controllers/character/")}).`
@@ -11910,11 +12046,11 @@ async function runAnims(opts) {
     process.exitCode = 1;
     return;
   }
-  const destDir = path12.join(root, ANIMS_DEST);
-  const gameManifestPath = path12.join(destDir, "manifest.json");
+  const destDir = path13.join(root, ANIMS_DEST);
+  const gameManifestPath = path13.join(destDir, "manifest.json");
   if (opts.reset) {
-    await fs11.rm(destDir, { recursive: true, force: true });
-    log.step(`Cleared ${c.cyan(ANIMS_DEST + path12.sep)} (--reset)`);
+    await fs12.rm(destDir, { recursive: true, force: true });
+    log.step(`Cleared ${c.cyan(ANIMS_DEST + path13.sep)} (--reset)`);
   }
   if (selectors.length === 0) {
     const installed = await readGameManifest(gameManifestPath);
@@ -11952,35 +12088,35 @@ async function runAnims(opts) {
     }
   }
   const wanted = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-  const cacheDir = path12.join(
+  const cacheDir = path13.join(
     opts.cacheDir ?? getAnimsCacheDir(),
     `${manifest.library}-v${manifest.version}`
   );
-  await fs11.mkdir(cacheDir, { recursive: true });
-  await fs11.mkdir(destDir, { recursive: true });
+  await fs12.mkdir(cacheDir, { recursive: true });
+  await fs12.mkdir(destDir, { recursive: true });
   const base = getAnimsBase(opts.animsBase);
   let installedCount = 0;
   let presentCount = 0;
   let addedBytes = 0;
   const failures = [];
   for (const entry of wanted) {
-    const dest = path12.join(destDir, entry.file);
+    const dest = path13.join(destDir, entry.file);
     if (await hasSize(dest, entry.bytes)) {
       presentCount++;
       continue;
     }
     try {
-      const cached = path12.join(cacheDir, entry.file);
+      const cached = path13.join(cacheDir, entry.file);
       if (!await hasSize(cached, entry.bytes)) {
         const res = await fetch(base + entry.file);
         if (!res.ok) throw new Error(`HTTP ${res.status}`);
         const buf = Buffer.from(await res.arrayBuffer());
-        await fs11.writeFile(cached, buf);
+        await fs12.writeFile(cached, buf);
       }
-      await fs11.copyFile(cached, dest);
+      await fs12.copyFile(cached, dest);
       installedCount++;
       addedBytes += entry.bytes;
-      log.dim(`  ${path12.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
+      log.dim(`  ${path13.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
     } catch (err) {
       failures.push(`${entry.name} (${err instanceof Error ? err.message : String(err)})`);
     }
@@ -11996,13 +12132,13 @@ async function runAnims(opts) {
     version: manifest.version,
     clips: [...union].sort((a, b) => a.localeCompare(b))
   };
-  await fs11.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
+  await fs12.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
   log.plain("");
   const parts = [`${installedCount} clip${installedCount === 1 ? "" : "s"} installed`];
   if (presentCount > 0) parts.push(`${presentCount} already present`);
   if (bundledSkips > 0) parts.push(`${bundledSkips} already bundled in animation-library.glb`);
   log.success(
-    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path12.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
+    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path13.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
   );
   for (const [selector, entries] of resolved) {
     const names = entries.filter((e) => !coreNames.has(e.name)).map((e) => e.name);
@@ -12034,8 +12170,8 @@ async function loadManifest(baseOverride) {
     }
   } catch {
   }
-  const snapshotPath = path12.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
-  const manifest = JSON.parse(await fs11.readFile(snapshotPath, "utf8"));
+  const snapshotPath = path13.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
+  const manifest = JSON.parse(await fs12.readFile(snapshotPath, "utf8"));
   return { manifest, source: "snapshot" };
 }
 function resolveSelectors(manifest, selectors) {
@@ -12153,21 +12289,21 @@ function printCatalog(log, manifest, selectors) {
 }
 async function readGameManifest(file) {
   try {
-    return JSON.parse(await fs11.readFile(file, "utf8"));
+    return JSON.parse(await fs12.readFile(file, "utf8"));
   } catch {
     return null;
   }
 }
 async function hasSize(file, bytes) {
   try {
-    return (await fs11.stat(file)).size === bytes;
+    return (await fs12.stat(file)).size === bytes;
   } catch {
     return false;
   }
 }
 async function exists2(p) {
   try {
-    await fs11.access(p);
+    await fs12.access(p);
     return true;
   } catch {
     return false;
@@ -12300,8 +12436,8 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path13.join("src", "controllers");
-var ASSETS_DEST = path13.join("public", "assets");
+var CODE_DEST = path14.join("src", "controllers");
+var ASSETS_DEST = path14.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
   if (opts.kind?.trim() === "anims") {
@@ -12318,31 +12454,31 @@ async function runController(opts) {
     process.exitCode = 1;
     return;
   }
-  const srcDir = path13.join(getTemplatesDir(), "controllers");
+  const srcDir = path14.join(getTemplatesDir(), "controllers");
   const root = opts.cwd ?? process.cwd();
   const set = CONTROLLER_FILE_SETS[kind];
   log.plain(c.bold(`genex controller ${kind}`));
   log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path14.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path14.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path13.join(ASSETS_DEST, path13.basename(rel))
+      rel: path14.join(ASSETS_DEST, path14.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path13.join(root, file.rel);
+      const dest = path14.join(root, file.rel);
       if (!opts.force && await exists3(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs12.mkdir(path13.dirname(dest), { recursive: true });
-      await fs12.copyFile(path13.join(srcDir, file.from), dest);
+      await fs13.mkdir(path14.dirname(dest), { recursive: true });
+      await fs13.copyFile(path14.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -12427,9 +12563,9 @@ async function installMeshyCharacterManifest(args) {
     throw new Error("The API returned an invalid Meshy character manifest.");
   }
   assertCompleteMeshyControllerPack(manifest);
-  const destination = path13.join(args.root, ASSETS_DEST, "meshy-character.json");
-  await fs12.mkdir(path13.dirname(destination), { recursive: true });
-  await fs12.writeFile(
+  const destination = path14.join(args.root, ASSETS_DEST, "meshy-character.json");
+  await fs13.mkdir(path14.dirname(destination), { recursive: true });
+  await fs13.writeFile(
     destination,
     `${JSON.stringify(manifest, null, 2)}
 `
@@ -12550,8 +12686,8 @@ function assertCompleteMeshyControllerPack(manifest) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs12.mkdir(path13.dirname(dest), { recursive: true });
+  const dest = path14.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs13.mkdir(path14.dirname(dest), { recursive: true });
   if (token) {
     try {
       const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
@@ -12563,7 +12699,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs12.writeFile(dest, buf);
+            await fs13.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -12574,14 +12710,14 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs12.copyFile(path13.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs13.copyFile(path14.join(srcDir, "assets", "default-avatar.vrm"), dest);
   log.dim(
     token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
   );
 }
 async function exists3(p) {
   try {
-    await fs12.access(p);
+    await fs13.access(p);
     return true;
   } catch {
     return false;
@@ -12866,12 +13002,12 @@ function rank(items, query) {
 }
 
 // src/commands/ui.ts
-import fs14 from "fs/promises";
-import path14 from "path";
+import fs15 from "fs/promises";
+import path15 from "path";
 import { PNG as PNG3 } from "pngjs";
 
 // src/lib/png-tools.ts
-import fs13 from "fs/promises";
+import fs14 from "fs/promises";
 import { PNG as PNG2 } from "pngjs";
 var ALPHA_TRANSPARENT_MAX = 16;
 var isHttpUrl = (s) => /^https?:\/\//i.test(s);
@@ -12882,12 +13018,12 @@ async function loadPng(input) {
     if (!res.ok) throw new Error(`Couldn't fetch ${input} (HTTP ${res.status}).`);
     buf = Buffer.from(await res.arrayBuffer());
   } else {
-    buf = await fs13.readFile(input);
+    buf = await fs14.readFile(input);
   }
   return PNG2.sync.read(buf);
 }
 async function writePng(file, png) {
-  await fs13.writeFile(file, PNG2.sync.write(png));
+  await fs14.writeFile(file, PNG2.sync.write(png));
 }
 function cropPng(image, box) {
   const out = new PNG2({ width: box.w, height: box.h });
@@ -13093,7 +13229,7 @@ async function uiExtract(opts, log) {
   const dilatePx = opts.dilate ?? 0;
   const sheet = await loadPng(input);
   const { width: W, height: H, data } = sheet;
-  await fs14.mkdir(outDir, { recursive: true });
+  await fs15.mkdir(outDir, { recursive: true });
   log.plain(c.bold("genex ui extract"));
   log.dim(`  ${input} (${W}x${H}) \u2192 ${outDir}, ${names.length} names`);
   let hasTransparency = false;
@@ -13252,7 +13388,7 @@ async function uiExtract(opts, log) {
         }
       }
     }
-    const outPath = path14.join(outDir, `${name}.png`);
+    const outPath = path15.join(outDir, `${name}.png`);
     await writePng(outPath, out);
     const sidecar = {
       name,
@@ -13270,7 +13406,7 @@ async function uiExtract(opts, log) {
       componentPixels: comp.pixels
     };
     const { name: _n, out: _o, ...sidecarBody } = sidecar;
-    await fs14.writeFile(
+    await fs15.writeFile(
       outPath.replace(/\.png$/i, "") + ".bbox.json",
       JSON.stringify(sidecarBody, null, 2)
     );
@@ -13279,8 +13415,8 @@ async function uiExtract(opts, log) {
       `${name}.png  ${cropW}x${cropH} (ar ${sidecar.aspectRatio}) at sheet ${padX0},${padY0}`
     );
   }
-  const debugPath = path14.join(outDir, "extract-debug.json");
-  await fs14.writeFile(
+  const debugPath = path15.join(outDir, "extract-debug.json");
+  await fs15.writeFile(
     debugPath,
     JSON.stringify(
       {
@@ -13514,7 +13650,7 @@ async function uiMasks(opts, log) {
   const registrationTolerance = opts.registrationTolerance ?? 0.04;
   const edgeFlushMax = opts.edgeFlushMax ?? 0.04;
   const image = await loadPng(input);
-  await fs14.mkdir(outDir, { recursive: true });
+  await fs15.mkdir(outDir, { recursive: true });
   log.plain(c.bold("genex ui masks"));
   log.dim(`  ${input} (${image.width}x${image.height}), ${pairs.length} pair(s) \u2192 ${outDir}`);
   const results = [];
@@ -13557,11 +13693,11 @@ async function uiMasks(opts, log) {
       });
     }
     const overlay = makeOverlay(clean2, converted.png);
-    const framePath = path14.join(outDir, `${pair.name}-frame.png`);
-    const maskPath = path14.join(outDir, `${pair.name}-mask.png`);
-    const annotatedPath = path14.join(outDir, `${pair.name}-annotated-source.png`);
-    const overlayPath = path14.join(outDir, `${pair.name}-overlay.png`);
-    const metaPath = path14.join(outDir, `${pair.name}.annotated-progress.json`);
+    const framePath = path15.join(outDir, `${pair.name}-frame.png`);
+    const maskPath = path15.join(outDir, `${pair.name}-mask.png`);
+    const annotatedPath = path15.join(outDir, `${pair.name}-annotated-source.png`);
+    const overlayPath = path15.join(outDir, `${pair.name}-overlay.png`);
+    const metaPath = path15.join(outDir, `${pair.name}.annotated-progress.json`);
     await writePng(framePath, clean2);
     await writePng(maskPath, converted.png);
     await writePng(annotatedPath, annotated);
@@ -13600,7 +13736,7 @@ async function uiMasks(opts, log) {
       },
       overlay: overlayPath
     };
-    await fs14.writeFile(metaPath, `${JSON.stringify(meta, null, 2)}
+    await fs15.writeFile(metaPath, `${JSON.stringify(meta, null, 2)}
 `);
     results.push(meta);
     const fb = converted.bbox;
@@ -13609,8 +13745,8 @@ async function uiMasks(opts, log) {
       `${pair.name}: coverage ${meta.mask.coverage},${fbText} ${components.length} component(s), registration \u0394 ${meta.registration.bboxDelta}`
     );
   }
-  const indexPath = path14.join(outDir, "annotated-progress.json");
-  await fs14.writeFile(indexPath, `${JSON.stringify({ input, pairs: results }, null, 2)}
+  const indexPath = path15.join(outDir, "annotated-progress.json");
+  await fs15.writeFile(indexPath, `${JSON.stringify({ input, pairs: results }, null, 2)}
 `);
   log.plain("");
   log.success(`Wrote ${pairs.length} frame+mask pair(s) \u2192 ${outDir} (index: ${indexPath}).`);
@@ -13731,7 +13867,7 @@ async function uiTextColor(opts, log) {
   };
   process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
-  if (opts.out) await fs14.writeFile(opts.out, `${JSON.stringify(result, null, 2)}
+  if (opts.out) await fs15.writeFile(opts.out, `${JSON.stringify(result, null, 2)}
 `);
   if (opts.cropPath) log.dim(`  crop \u2192 ${opts.cropPath}`);
 }
@@ -13754,7 +13890,7 @@ async function uiTrim(opts, log) {
   await writePng(outPath, trimmed);
   const sidecar = computeBBoxes(trimmed);
   const sidecarPath = outPath.replace(/\.png$/i, "") + ".bbox.json";
-  await fs14.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2));
+  await fs15.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2));
   log.success(
     `Trimmed ${png.width}x${png.height} \u2192 ${trimmed.width}x${trimmed.height} (${outPath}).`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.62.0-dev.143",
+  "version": "0.62.0-dev.144",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-menu/SKILL.md

@@ -126,6 +126,19 @@ after the UI plan gate, enqueue the video with `--no-wait`, ship the CSS menu
 (R2) — permanent, public, CORS-open; you load them straight from the printed
 URLs, nothing is downloaded or committed.
 
+**Two failed video attempts = ship the still. Hard stop.** Video is the one
+generation that fails server-side with real frequency (render timeouts), and
+every attempt costs minutes of waiting. One retry is fair — shorten the clip
+(4–6 s) and simplify the motion prompt. After a SECOND failure, stop
+generating: keep the key-art still as the menu background and give it life
+for free with a slow CSS pan/zoom (`transform: scale(1.06)` over ~20 s,
+alternating), tell the user in one plain line ("the animated menu backdrop
+kept failing, so your menu uses the key art — looks great, costs nothing"),
+and spend those minutes in the game. A third attempt is how half an hour
+disappears into chrome — the CLI counts failures and reminds you at the
+second one. The still-image menu is a real menu: this rule is the built-in
+fallback, not a downgrade to apologize for.
+
 ## Wire it as a phase screen
 
 The menu is one `data-phase` screen in the `$genex-threejs-game-ui`