@genex-ai/cli-demo 0.80.2-dev.213 → 0.84.0-dev.215

package/dist/index.js

@@ -2006,21 +2006,27 @@ var UI_NUMBER_FLAGS = {
   "--quantize": "quantize",
   "--ink-dist": "inkDist",
   "--min-frac": "minFrac",
-  "--seam-tolerance": "seamTolerance"
+  "--seam-tolerance": "seamTolerance",
+  "--erode": "erode"
 };
 var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or https URL>)")}
   ui extract           --out-dir <dir> --names a,b,c (reading order) \u2014 split an
                        asset sheet into per-element transparent PNGs + .bbox.json
-                       sidecars. [--expect N: hard-error unless exactly N
-                       components] [--min-pixels 2000] [--padding 8] [--chroma 240]
-                       [--dilate 0]
+                       sidecars. Where extract keys the white itself it also
+                       defringes the 2px sprite rim (matte un-blend \u2014 kills the
+                       white halo over dark scenes). [--expect N: hard-error
+                       unless exactly N components] [--min-pixels 2000]
+                       [--padding 8] [--chroma 240] [--dilate 0] [--no-defringe]
   ui masks             --out-dir <dir> --pairs "name:cX,cY,w,h:aX,aY,w,h[:n];\u2026"
                        OR --auto (detect clean/annotated cell pairs itself) \u2014
                        clean frame + green-annotated duplicate \u2192 frame + fill mask
                        + fillBox + per-segment fillBoxes (+ overlay + provenance
-                       JSON). [--names a,b,c with --auto] [--registration-
+                       JSON). Hard-refuses provable sheet defects (white-painted
+                       fill trough, a crop catching a neighboring element).
+                       [--names a,b,c with --auto] [--expect N with --auto: every
+                       pair must yield exactly N fill components] [--registration-
                        tolerance 0.04] [--coverage-min 0.01] [--coverage-max 0.85]
-                       [--component-min-pixels 100] [--edge-flush-max 0.04]
+                       [--component-min-pixels 100]
   ui text-color        --box x,y,w,h \u2014 eyedropper a text region: plate color +
                        ink candidates as JSON. [--quantize 12] [--ink-dist 60]
                        [--min-frac 0.004] [--out <json>] [--crop <png>]
@@ -2029,11 +2035,21 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
   ui seams             measure a tiling texture's wrap seam (opposite edges vs
                        interior detail) \u2192 ratio + verdict as JSON; nonzero exit on
                        a visible seam. [--seam-tolerance 3]
-  ui audit             mechanical HUD-wiring scan (no --in): extracted-but-never-
-                       wired sprites, generated-but-unreferenced masks, naive
-                       JS %-width fills, phones-preload-video heuristic. Warn-only
-                       (findings may be fine \u2014 check them). [--dir public/assets/
-                       hud] [--src src] [--strict: exit 1 on findings]`;
+  ui plate             [--out <png>] \u2014 trace a frame sprite's REAL interior
+                       (art footprint + enclosed cavity) into a silhouette mask
+                       PNG. Wire it as the CSS plate's mask-image so rgba/
+                       backdrop-filter plates fit arbitrary art exactly \u2014 never
+                       a bare rounded rectangle. [--erode 2]
+  ui audit             mechanical HUD-wiring scan (no --in): mask\u2194frame pairing
+                       mismatches (recorded crops disagree \u2014 PROVABLE, exit 1),
+                       white-painted meter troughs (baked sheet-white inside a
+                       fill channel \u2014 PROVABLE, exit 1), loosened-check stamps,
+                       extracted-but-never-wired sprites, generated-but-
+                       unreferenced masks, naive JS %-width fills, phones-
+                       preload-video heuristic. Everything but the two provable
+                       kinds is warn-only (findings may be fine \u2014 check them).
+                       [--dir public/assets/hud] [--src src] [--strict: exit 1 on
+                       any findings]`;
 async function runUi(opts) {
   const log = createLogger({ quiet: opts.quiet });
   try {
@@ -2053,12 +2069,15 @@ async function runUi(opts) {
       case "seams":
         await uiSeams(opts, log);
         return;
+      case "plate":
+        await uiPlate(opts, log);
+        return;
       case "audit":
         await uiAudit(opts, log);
         return;
       default:
         log.error(
-          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim, seams, audit.` : "Missing ui tool. Tools: extract, masks, text-color, trim, seams, audit."
+          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim, seams, plate, audit.` : "Missing ui tool. Tools: extract, masks, text-color, trim, seams, plate, audit."
         );
         log.plain(UI_USAGE);
         process.exitCode = 1;
@@ -2240,6 +2259,33 @@ async function uiExtract(opts, log) {
     band.items.sort((a, b) => a.cx - b.cx);
     sorted.push(...band.items);
   }
+  const nameOf = (i) => i < names.length ? names[i] : `extra-${i - names.length}`;
+  for (let i = 0; i < sorted.length; i++) {
+    const comp = sorted[i];
+    const x0 = Math.max(0, comp.minX - padding);
+    const y0 = Math.max(0, comp.minY - padding);
+    const x1 = Math.min(W, comp.maxX + padding + 1);
+    const y1 = Math.min(H, comp.maxY + padding + 1);
+    for (let j = 0; j < sorted.length; j++) {
+      if (j === i) continue;
+      const other = sorted[j];
+      const oMinX = other.minX + 2;
+      const oMinY = other.minY + 2;
+      const oMaxX = other.maxX - 2;
+      const oMaxY = other.maxY - 2;
+      if (oMinX < x1 && oMaxX >= x0 && oMinY < y1 && oMaxY >= y0) {
+        const w = other.maxX - other.minX + 1;
+        const h = other.maxY - other.minY + 1;
+        fail(
+          `"${nameOf(i)}": the crop (component + ${padding}px padding) catches "${nameOf(j)}" at ${other.minX},${other.minY} (${w}x${h}) \u2014 its edge would ship baked into this sprite. Nothing written. Regenerate the sheet with more margin between elements, or lower --padding.`,
+          {
+            crop: { x: x0, y: y0, w: x1 - x0, h: y1 - y0 },
+            neighbor: { name: nameOf(j), x: other.minX, y: other.minY, w, h }
+          }
+        );
+      }
+    }
+  }
   const extractions = [];
   for (let i = 0; i < sorted.length; i++) {
     const comp = sorted[i];
@@ -2276,6 +2322,10 @@ async function uiExtract(opts, log) {
         }
       }
     }
+    let defringed = false;
+    if (inputMode === "chroma" && opts.defringe !== false) {
+      defringed = defringeAgainstMatte(out) > 0;
+    }
     const outPath = path10.join(outDir, `${name}.png`);
     await writePng(outPath, out);
     const sidecar = {
@@ -2291,7 +2341,8 @@ async function uiExtract(opts, log) {
       },
       cropDims: { w: cropW, h: cropH },
       aspectRatio: +(cropW / cropH).toFixed(3),
-      componentPixels: comp.pixels
+      componentPixels: comp.pixels,
+      defringed
     };
     const { name: _n, out: _o, ...sidecarBody } = sidecar;
     await fs10.writeFile(
@@ -2395,7 +2446,7 @@ function assertNotFlush(png, label, maxFrac) {
   const flush2 = Object.entries(edges).filter(([, frac]) => frac > maxFrac);
   if (flush2.length > 0) {
     fail(
-      `${label}: crop box is slicing the element \u2014 opaque content is flush against the image edge. Widen the crop box (or pass --edge-flush-max 1 for a deliberate full-bleed asset).`,
+      `${label}: the crop box is slicing the element \u2014 opaque content is flush against the crop edge. The sheet needs more margin here: widen the crop box if there is room, otherwise region-edit or regenerate the sheet with more spacing around this element (see genex-ai-hud troubleshooting), then re-run.`,
       {
         flushEdges: flush2.map(([edge, frac]) => ({ edge, opaqueFraction: Number(frac.toFixed(3)) })),
         maxFraction: maxFrac
@@ -2403,6 +2454,70 @@ function assertNotFlush(png, label, maxFrac) {
     );
   }
 }
+function whiteTroughFraction(clean2, mask) {
+  let fill = 0;
+  let white = 0;
+  for (let i = 0; i < mask.width * mask.height; i += 1) {
+    const idx = i << 2;
+    if (mask.data[idx + 3] === 0) continue;
+    fill += 1;
+    if (clean2.data[idx + 3] > 200 && clean2.data[idx] >= 240 && clean2.data[idx + 1] >= 240 && clean2.data[idx + 2] >= 240) {
+      white += 1;
+    }
+  }
+  return fill === 0 ? 0 : white / fill;
+}
+var WHITE_TROUGH_MAX = 0.4;
+function detectSheetComponents(image, minPixels) {
+  const { width: W, height: H, data } = image;
+  let hasTransparency = false;
+  for (let i = 0; i < W * H; i += 1) {
+    if (data[i * 4 + 3] < 250) {
+      hasTransparency = true;
+      break;
+    }
+  }
+  const isSubjectIdx = (idx) => {
+    const o = idx * 4;
+    if (data[o + 3] <= ALPHA_TRANSPARENT_MAX) return false;
+    if (hasTransparency) return true;
+    return !(data[o] >= 240 && data[o + 1] >= 240 && data[o + 2] >= 240);
+  };
+  const components = [];
+  scanComponents(W, H, isSubjectIdx, (stats) => {
+    if (stats.pixels < minPixels) return;
+    components.push({
+      minX: stats.minX,
+      minY: stats.minY,
+      maxX: stats.maxX,
+      maxY: stats.maxY,
+      pixels: stats.pixels
+    });
+  });
+  return components;
+}
+var OVERLAP_TOLERANCE_PX = 2;
+function assertNoNeighborInCrop(box, components, label) {
+  for (const comp of components) {
+    const cx = (comp.minX + comp.maxX) / 2;
+    const cy = (comp.minY + comp.maxY) / 2;
+    const centerInside = cx >= box.x && cx < box.x + box.w && cy >= box.y && cy < box.y + box.h;
+    if (centerInside) continue;
+    const nMinX = comp.minX + OVERLAP_TOLERANCE_PX;
+    const nMinY = comp.minY + OVERLAP_TOLERANCE_PX;
+    const nMaxX = comp.maxX - OVERLAP_TOLERANCE_PX;
+    const nMaxY = comp.maxY - OVERLAP_TOLERANCE_PX;
+    const intersects = nMinX < box.x + box.w && nMaxX >= box.x && nMinY < box.y + box.h && nMaxY >= box.y;
+    if (intersects) {
+      const w = comp.maxX - comp.minX + 1;
+      const h = comp.maxY - comp.minY + 1;
+      fail(
+        `${label}: the crop catches another sheet element at ${comp.minX},${comp.minY} (${w}x${h}) \u2014 its edge would ship baked into this asset. Regenerate the sheet with more margin between elements, or tighten the crop so it stays clear of the neighbor.`,
+        { crop: box, neighbor: { x: comp.minX, y: comp.minY, w, h } }
+      );
+    }
+  }
+}
 var isWhitePx = (data, idx) => data[idx + 3] > 16 && data[idx] >= 245 && data[idx + 1] >= 245 && data[idx + 2] >= 245;
 var isSubjectPx = (data, idx) => data[idx + 3] > 16 && !isWhitePx(data, idx);
 function greenAlpha(r, g, b, a) {
@@ -2677,7 +2792,10 @@ function autoDetectPairs(image, opts, log) {
       name: names[i] ?? `meter-${i + 1}`,
       cleanBox: place(best.cell.minX, best.cell.minY, cw, ch),
       annotatedBox: place(ann.minX, ann.minY, aw, ah),
-      expectedComponents: null
+      // D6: --auto used to leave the component count ungated (null). --expect N
+      // now gates every auto pair (a continuous bar is --expect 1; a segmented
+      // meter its segment count).
+      expectedComponents: opts.expect ?? null
     });
   });
   log.dim(
@@ -2698,9 +2816,11 @@ async function uiMasks(opts, log) {
   const minComponentPixels = opts.componentMinPixels ?? 100;
   const registrationTolerance = opts.registrationTolerance ?? 0.04;
   const edgeFlushMax = opts.edgeFlushMax ?? 0.04;
+  const loosened = registrationTolerance > 0.04 || edgeFlushMax > 0.04 || minCoverage < 0.01 || maxCoverage > 0.85;
   await fs10.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 sheetComponents = detectSheetComponents(image, opts.minPixels ?? 2e3);
   const results = [];
   for (const pair of pairs) {
     if (pair.cleanBox.w !== pair.annotatedBox.w || pair.cleanBox.h !== pair.annotatedBox.h) {
@@ -2708,6 +2828,8 @@ async function uiMasks(opts, log) {
     }
     assertInside(pair.cleanBox, image, `${pair.name} clean`);
     assertInside(pair.annotatedBox, image, `${pair.name} annotated`);
+    assertNoNeighborInCrop(pair.cleanBox, sheetComponents, `${pair.name} clean frame`);
+    assertNoNeighborInCrop(pair.annotatedBox, sheetComponents, `${pair.name} annotated copy`);
     const clean2 = cropPng(image, pair.cleanBox);
     const annotated = cropPng(image, pair.annotatedBox);
     assertNotFlush(clean2, `${pair.name} clean frame`, edgeFlushMax);
@@ -2732,6 +2854,13 @@ async function uiMasks(opts, log) {
         maxCoverage
       });
     }
+    const whiteTrough = whiteTroughFraction(clean2, converted.png);
+    if (whiteTrough >= WHITE_TROUGH_MAX) {
+      fail(
+        `${pair.name}: the fill channel is painted filled in the frame art \u2014 ${Math.round(whiteTrough * 100)}% of the fill region is opaque near-white in the clean frame. The sheet model ignored "REMOVE the fill": as the value drops, that baked white shows through the mask. Regenerate the sheet (region-edit the bar to an empty trough) and re-run \u2014 do not wire this frame.`,
+        { name: pair.name, whiteTroughFraction: Number(whiteTrough.toFixed(3)) }
+      );
+    }
     const components = greenComponents(converted.png, minComponentPixels);
     if (pair.expectedComponents && components.length !== pair.expectedComponents) {
       fail("Green mask component count mismatch.", {
@@ -2778,6 +2907,9 @@ async function uiMasks(opts, log) {
         bboxDelta: Number(registrationDelta.toFixed(4)),
         tolerance: registrationTolerance
       },
+      // D6: true when any gate tolerance was relaxed beyond its default for
+      // this run — preview/publish read this and warn (they never block).
+      loosened,
       mask: {
         path: maskPath,
         size: { w: converted.png.width, h: converted.png.height },
@@ -2806,11 +2938,16 @@ async function uiMasks(opts, log) {
     }
   }
   const indexPath = path10.join(outDir, "annotated-progress.json");
-  await fs10.writeFile(indexPath, `${JSON.stringify({ input, pairs: results }, null, 2)}
+  await fs10.writeFile(indexPath, `${JSON.stringify({ input, loosened, pairs: results }, null, 2)}
 `);
   log.plain("");
   log.success(`Wrote ${pairs.length} frame+mask pair(s) \u2192 ${outDir} (index: ${indexPath}).`);
   log.dim("  Eyeball each *-overlay.png \u2014 green must cover exactly the fill region.");
+  if (loosened) {
+    log.warn(
+      "These masks were produced with loosened checks (a tolerance beyond its default). That is stamped in the metadata; eyeball the wired result in-game \u2014 with the meter NOT at full \u2014 before shipping."
+    );
+  }
 }
 var hexColor = (r, g, b) => `#${[r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
 var luminance = (r, g, b) => (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
@@ -2988,6 +3125,179 @@ async function uiSeams(opts, log) {
     `Visible ${r.worstAxis} tiling seam in ${name}: the tile boundary jumps ${r.worstRatio}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable. Don't hide it behind a hand-picked UV repeat \u2014 that trades a seam for a stretched texture (scale belongs in the UVs: worldUV, genex-ai-texture).`
   );
 }
+function traceInterior(png, erode = 0) {
+  const { width: W, height: H, data } = png;
+  const opaque = (idx) => data[idx * 4 + 3] > ALPHA_TRANSPARENT_MAX;
+  const visited = new Uint8Array(W * H);
+  const queue = new Int32Array(W * H);
+  const inRegion = (idx) => !opaque(idx);
+  for (let x = 0; x < W; x++) {
+    for (const y of [0, H - 1]) {
+      const idx = y * W + x;
+      if (!visited[idx] && inRegion(idx)) floodFill(W, H, visited, queue, x, y, inRegion);
+    }
+  }
+  for (let y = 0; y < H; y++) {
+    for (const x of [0, W - 1]) {
+      const idx = y * W + x;
+      if (!visited[idx] && inRegion(idx)) floodFill(W, H, visited, queue, x, y, inRegion);
+    }
+  }
+  let interior = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) interior[i] = visited[i] ? 0 : 1;
+  for (let pass = 0; pass < erode; pass++) {
+    const next = new Uint8Array(W * H);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const i = y * W + x;
+        if (!interior[i]) continue;
+        const ok = x > 0 && interior[i - 1] && x < W - 1 && interior[i + 1] && y > 0 && interior[i - W] && y < H - 1 && interior[i + W];
+        if (ok) next[i] = 1;
+      }
+    }
+    interior = next;
+  }
+  return interior;
+}
+async function uiPlate(opts, log) {
+  const input = requireOpt(opts.input, "--in", "plate");
+  let outPath = opts.out;
+  if (!outPath) {
+    if (/^https?:\/\//i.test(input)) fail("--in is a URL \u2014 pass --out <png> to say where the plate mask goes.");
+    outPath = input.replace(/\.png$/i, "") + "-plate.png";
+  }
+  const erode = opts.erode ?? 2;
+  const png = await loadPng(input);
+  const { width: W, height: H } = png;
+  const interior = traceInterior(png, erode);
+  let count = 0;
+  const out = new PNG2({ width: W, height: H });
+  for (let i = 0; i < W * H; i++) {
+    const o = i * 4;
+    out.data[o] = 255;
+    out.data[o + 1] = 255;
+    out.data[o + 2] = 255;
+    out.data[o + 3] = interior[i] ? 255 : 0;
+    if (interior[i]) count++;
+  }
+  if (count === 0) {
+    fail("No interior found \u2014 the image is fully transparent (or erode ate everything). Check --in / lower --erode.");
+  }
+  await writePng(outPath, out);
+  const name = path10.basename(outPath);
+  log.plain(c.bold("genex ui plate"));
+  log.success(`${outPath}  ${W}x${H}, interior ${(count / (W * H) * 100).toFixed(1)}% (erode ${erode}px)`);
+  log.dim("  Wire it as the plate's silhouette (same box as the frame <img>, plate UNDER the art):");
+  log.dim(`    .plate { position:absolute; inset:0; background:rgba(14,10,22,.55); backdrop-filter:blur(5px);`);
+  log.dim(`             -webkit-mask-image:url(${name}); mask-image:url(${name});`);
+  log.dim(`             -webkit-mask-size:100% 100%; mask-size:100% 100%; mask-repeat:no-repeat; }`);
+  process.stdout.write(
+    `${JSON.stringify({ out: outPath, width: W, height: H, interiorFraction: Number((count / (W * H)).toFixed(4)), erode })}
+`
+  );
+}
+var DEFRINGE_BAND_PX = 2;
+function defringeAgainstMatte(png, matte = { r: 255, g: 255, b: 255 }) {
+  const { width: W, height: H, data } = png;
+  const opaque = (i) => data[i * 4 + 3] > ALPHA_TRANSPARENT_MAX;
+  const dist = new Uint8Array(W * H);
+  let ring = [];
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const i = y * W + x;
+      if (!opaque(i)) continue;
+      const nearTransparent = x > 0 && !opaque(i - 1) || x < W - 1 && !opaque(i + 1) || y > 0 && !opaque(i - W) || y < H - 1 && !opaque(i + W) || x === 0 || x === W - 1 || y === 0 || y === H - 1;
+      if (nearTransparent) {
+        dist[i] = 1;
+        ring.push(i);
+      }
+    }
+  }
+  for (let d = 2; d <= DEFRINGE_BAND_PX; d++) {
+    const next = [];
+    for (const i of ring) {
+      const x = i % W;
+      const y = i / W | 0;
+      for (const n of [x > 0 ? i - 1 : -1, x < W - 1 ? i + 1 : -1, y > 0 ? i - W : -1, y < H - 1 ? i + W : -1]) {
+        if (n >= 0 && opaque(n) && dist[n] === 0) {
+          dist[n] = d;
+          next.push(n);
+        }
+      }
+    }
+    ring = next;
+  }
+  const CH = [0, 1, 2];
+  const matteCh = [matte.r, matte.g, matte.b];
+  let rewritten = 0;
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const i = y * W + x;
+      if (dist[i] === 0) continue;
+      const cIn = [0, 0, 0];
+      let n = 0;
+      outer: for (let r = 1; r <= 6; r++) {
+        for (let dy = -r; dy <= r; dy++) {
+          for (let dx = -r; dx <= r; dx++) {
+            if (Math.max(Math.abs(dx), Math.abs(dy)) !== r) continue;
+            const nx = x + dx;
+            const ny = y + dy;
+            if (nx < 0 || ny < 0 || nx >= W || ny >= H) continue;
+            const ni = ny * W + nx;
+            if (!opaque(ni) || dist[ni] !== 0) continue;
+            cIn[0] += data[ni * 4];
+            cIn[1] += data[ni * 4 + 1];
+            cIn[2] += data[ni * 4 + 2];
+            n++;
+            if (n >= 24) break outer;
+          }
+        }
+      }
+      if (n === 0) continue;
+      for (const ch of CH) cIn[ch] = cIn[ch] / n;
+      let alphaSum = 0;
+      let alphaN = 0;
+      for (const ch of CH) {
+        const contrast = matteCh[ch] - cIn[ch];
+        if (Math.abs(contrast) < 30) continue;
+        const a = (matteCh[ch] - data[i * 4 + ch]) / contrast;
+        alphaSum += Math.min(1, Math.max(0, a));
+        alphaN++;
+      }
+      if (alphaN === 0) continue;
+      const alpha = alphaSum / alphaN;
+      if (alpha > 0.98) continue;
+      data[i * 4] = Math.round(cIn[0]);
+      data[i * 4 + 1] = Math.round(cIn[1]);
+      data[i * 4 + 2] = Math.round(cIn[2]);
+      data[i * 4 + 3] = Math.round(alpha * 255);
+      rewritten++;
+    }
+  }
+  return rewritten;
+}
+var HARD_AUDIT_KINDS = /* @__PURE__ */ new Set([
+  "mask-frame-mismatch",
+  "white-trough"
+]);
+var TROUGH_OPAQUE_MIN_ALPHA = 200;
+var TROUGH_WHITE_MIN = 235;
+var TROUGH_WHITE_MAX_FRACTION = 0.25;
+function whiteTroughAuditFraction(frame, mask) {
+  const interior = traceInterior(frame, 0);
+  let channel = 0;
+  let white = 0;
+  for (let i = 0; i < mask.width * mask.height; i++) {
+    if (mask.data[i * 4 + 3] === 0) continue;
+    if (!interior[i]) continue;
+    channel++;
+    const o = i * 4;
+    if (frame.data[o + 3] > TROUGH_OPAQUE_MIN_ALPHA && frame.data[o] >= TROUGH_WHITE_MIN && frame.data[o + 1] >= TROUGH_WHITE_MIN && frame.data[o + 2] >= TROUGH_WHITE_MIN) {
+      white++;
+    }
+  }
+  return channel === 0 ? 0 : white / channel;
+}
 var AUDIT_SRC_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".css", ".html"]);
 async function walkFiles(dir) {
   const out = [];
@@ -3006,11 +3316,29 @@ async function walkFiles(dir) {
   return out;
 }
 async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
+  const viewportFindings = [];
+  try {
+    const indexHtml = await fs10.readFile(path10.join(cwd, "index.html"), "utf8");
+    if (!/<meta[^>]+name=["']viewport["']/i.test(indexHtml)) {
+      viewportFindings.push({
+        kind: "viewport-meta",
+        message: `index.html has no viewport meta \u2014 phones will render a zoomed-out desktop canvas. Add: <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`
+      });
+    } else if (!/viewport-fit\s*=/i.test(indexHtml)) {
+      viewportFindings.push({
+        kind: "viewport-meta",
+        message: `index.html's viewport meta lacks viewport-fit=cover \u2014 env(safe-area-inset-*) (touch-kit widget offsets) is 0 without it. Append ", viewport-fit=cover" to the meta's content.`
+      });
+    }
+  } catch {
+  }
   const absAssets = path10.resolve(cwd, assetDir);
   try {
-    if (!(await fs10.stat(absAssets)).isDirectory()) return null;
+    if (!(await fs10.stat(absAssets)).isDirectory()) {
+      return viewportFindings.length > 0 ? viewportFindings : null;
+    }
   } catch {
-    return null;
+    return viewportFindings.length > 0 ? viewportFindings : null;
   }
   const srcFiles = (await walkFiles(path10.resolve(cwd, srcDir))).filter(
     (p) => AUDIT_SRC_EXTS.has(path10.extname(p).toLowerCase())
@@ -3030,8 +3358,94 @@ async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
     }
   }
   const referenced = (basename) => sources.some((s) => s.text.includes(basename));
-  const findings = [];
+  const findings = [...viewportFindings];
   const assetFiles = await walkFiles(absAssets);
+  const metaByName = /* @__PURE__ */ new Map();
+  const bboxByPng = /* @__PURE__ */ new Map();
+  for (const p of assetFiles) {
+    const base = path10.basename(p);
+    const metaMatch = /^(.+)\.annotated-progress\.json$/.exec(base);
+    if (metaMatch) {
+      try {
+        const meta = JSON.parse(await fs10.readFile(p, "utf8"));
+        metaByName.set(metaMatch[1], {
+          cleanCrop: meta.clean?.crop ?? null,
+          loosened: meta.loosened === true
+        });
+      } catch {
+      }
+      continue;
+    }
+    if (base.endsWith(".bbox.json")) {
+      try {
+        const sidecar = JSON.parse(await fs10.readFile(p, "utf8"));
+        if (sidecar.sheetBBox) bboxByPng.set(base.replace(/\.bbox\.json$/, ".png"), sidecar.sheetBBox);
+      } catch {
+      }
+    }
+  }
+  for (const [name, meta] of metaByName) {
+    if (!meta.cleanCrop || !referenced(`${name}-mask.png`)) continue;
+    for (const p of assetFiles) {
+      const base = path10.basename(p);
+      if (!base.toLowerCase().endsWith(".png")) continue;
+      if (base !== `${name}.png` && !base.startsWith(`${name}-`)) continue;
+      if (/-mask\.png$|-frame\.png$|-overlay\.png$|-annotated-source\.png$/.test(base)) continue;
+      if (!referenced(base)) continue;
+      const cut = bboxByPng.get(base);
+      if (!cut) continue;
+      const crop = meta.cleanCrop;
+      const delta = Math.max(
+        Math.abs(cut.x - crop.x),
+        Math.abs(cut.y - crop.y),
+        Math.abs(cut.w - crop.w),
+        Math.abs(cut.h - crop.h)
+      );
+      if (delta > 4) {
+        findings.push({
+          kind: "mask-frame-mismatch",
+          message: `${name}: ${name}-mask.png was derived against the sheet crop ${crop.x},${crop.y} (${crop.w}x${crop.h}), but the shipped ${base} was cut at ${cut.x},${cut.y} (${cut.w}x${cut.h}) \u2014 stretched over one box, the fill floats off the frame. Re-derive the mask against the shipped frame (genex ui masks --in <sheet> \u2026) or ship ${name}-frame.png (the crop this mask matches).`
+        });
+      }
+    }
+  }
+  const pngByBase = /* @__PURE__ */ new Map();
+  for (const p of assetFiles) {
+    const base = path10.basename(p);
+    if (base.toLowerCase().endsWith(".png")) pngByBase.set(base, p);
+  }
+  for (const [maskBase, maskPath] of pngByBase) {
+    const m = /^(.+)-mask\.png$/.exec(maskBase);
+    if (!m) continue;
+    const name = m[1];
+    for (const frameBase of [`${name}-frame.png`, `${name}.png`]) {
+      const framePath = pngByBase.get(frameBase);
+      if (!framePath) continue;
+      let frame;
+      let mask;
+      try {
+        frame = PNG2.sync.read(await fs10.readFile(framePath));
+        mask = PNG2.sync.read(await fs10.readFile(maskPath));
+      } catch {
+        continue;
+      }
+      if (frame.width !== mask.width || frame.height !== mask.height) continue;
+      const fraction = whiteTroughAuditFraction(frame, mask);
+      if (fraction > TROUGH_WHITE_MAX_FRACTION) {
+        findings.push({
+          kind: "white-trough",
+          message: `${frameBase}: the fill channel contains baked sheet-white (${Math.round(fraction * 100)}% of the channel \u2014 the model drew the trough white and the cleaner can't reach enclosed regions). Repair: regenerate the sheet with the empty-dark-track rule, or region-repaint the trough (genex image "<in-style empty track>" --edit <sheet-url> [--inpaint <channel-mask>]), then re-clean and re-extract. Do not ship this frame.`
+        });
+      }
+    }
+  }
+  const loosenedNames = [...metaByName.entries()].filter(([, meta]) => meta.loosened).map(([name]) => name);
+  if (loosenedNames.length > 0) {
+    findings.push({
+      kind: "loosened-masks",
+      message: `HUD masks for ${loosenedNames.join(", ")} were produced with loosened checks \u2014 eyeball each wired meter in-game, NOT at full value, before shipping.`
+    });
+  }
   const maskReported = /* @__PURE__ */ new Set();
   for (const p of assetFiles) {
     const m = /^(.+)\.annotated-progress\.json$/.exec(path10.basename(p));
@@ -3095,11 +3509,14 @@ async function uiAudit(opts, log) {
     log.success("HUD wiring audit clean \u2014 every asset referenced, no naive %-fill patterns.");
     return;
   }
-  log.warn(
-    `${findings.length} finding(s). These are heuristics \u2014 check each one; some may be fine:`
-  );
-  for (const finding of findings) log.warn(`  [${finding.kind}] ${finding.message}`);
-  if (opts.strict) process.exitCode = 1;
+  const hard = findings.filter((finding) => HARD_AUDIT_KINDS.has(finding.kind));
+  const soft = findings.filter((finding) => !HARD_AUDIT_KINDS.has(finding.kind));
+  for (const finding of hard) log.error(`[${finding.kind}] ${finding.message}`);
+  if (soft.length > 0) {
+    log.warn(`${soft.length} finding(s). These are heuristics \u2014 check each one; some may be fine:`);
+    for (const finding of soft) log.warn(`  [${finding.kind}] ${finding.message}`);
+  }
+  if (opts.strict || hard.length > 0) process.exitCode = 1;
 }
 
 // src/lib/deploy.ts
@@ -3943,7 +4360,7 @@ async function detectSurfaceScan(cwd = process.cwd()) {
   }
   return found;
 }
-var WIRED_BY_URL = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "video"]);
+var WIRED_BY_URL = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "music", "texture", "video"]);
 var UNPICKED_AFTER_MS = 15 * 60 * 1e3;
 async function detectGenerationAudit(cwd = process.cwd()) {
   const ledger = await readLedger(cwd);
@@ -4267,7 +4684,86 @@ async function runPreview(opts) {
 }
 
 // src/commands/generate.ts
+import fs14 from "fs/promises";
+import path14 from "path";
+import { PNG as PNG4 } from "pngjs";
+
+// src/lib/glass.ts
 import { PNG as PNG3 } from "pngjs";
+var GLASS_PROMPT_SUFFIX = " Rendered on a perfectly flat, uniform, solid pure magenta background, hex #FF00FF, like a studio chroma-key screen: absolutely no shading, no gradient, no vignette, no glow, no shadows on the background. Subject centered, sharp edge silhouette.";
+var GLASS_MIN_FLATNESS = 0.99;
+var GLASS_MIN_KEY_STRENGTH = 180;
+var FLATNESS_DEV_MAX = 12;
+var clamp255 = (v) => v < 0 ? 0 : v > 255 ? 255 : Math.round(v);
+function median(values) {
+  const s = values.slice().sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)] ?? 0;
+}
+function solveMagentaGlass(source) {
+  const { width: W, height: H, data } = source;
+  const ringW = Math.max(2, Math.round(Math.min(W, H) * 0.04));
+  const rs = [];
+  const gs = [];
+  const bs = [];
+  const ringIdx = [];
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const inRing = x < ringW || y < ringW || x >= W - ringW || y >= H - ringW;
+      if (!inRing) continue;
+      const i = (y * W + x) * 4;
+      ringIdx.push(i);
+      rs.push(data[i]);
+      gs.push(data[i + 1]);
+      bs.push(data[i + 2]);
+    }
+  }
+  const K = { r: median(rs), g: median(gs), b: median(bs) };
+  const keyHex = `#${[K.r, K.g, K.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+  const keyStrength = Math.min(K.r, K.b) - K.g;
+  let flat = 0;
+  for (const i of ringIdx) {
+    const dev = Math.max(
+      Math.abs(data[i] - K.r),
+      Math.abs(data[i + 1] - K.g),
+      Math.abs(data[i + 2] - K.b)
+    );
+    if (dev < FLATNESS_DEV_MAX) flat++;
+  }
+  const flatness = ringIdx.length === 0 ? 0 : flat / ringIdx.length;
+  const base = { keyColor: K, keyHex, keyStrength, flatness };
+  if (flatness < GLASS_MIN_FLATNESS || keyStrength < GLASS_MIN_KEY_STRENGTH) {
+    return {
+      ...base,
+      png: source,
+      ok: false,
+      rejected: `backdrop not keyable (flatness ${flatness.toFixed(3)}, key strength ${keyStrength} \u2014 want \u2265${GLASS_MIN_FLATNESS}/${GLASS_MIN_KEY_STRENGTH}): the model shaded the magenta screen instead of painting it flat. Regenerate (same prompt \u2014 this is a rare roll), or steer harder: keep the --glass suffix intact and avoid magenta/pink art in the subject.`
+    };
+  }
+  const out = new PNG3({ width: W, height: H });
+  const mKey = Math.max(1, keyStrength);
+  for (let p = 0; p < W * H; p++) {
+    const i = p * 4;
+    const R = data[i];
+    const G = data[i + 1];
+    const B = data[i + 2];
+    const m = Math.max(0, Math.min(R, B) - G);
+    let a = 1 - m / mKey;
+    if (a < 0) a = 0;
+    if (a > 1) a = 1;
+    if (a <= 0.02) {
+      out.data[i] = 0;
+      out.data[i + 1] = 0;
+      out.data[i + 2] = 0;
+      out.data[i + 3] = 0;
+      continue;
+    }
+    out.data[i] = clamp255((R - (1 - a) * K.r) / a);
+    out.data[i + 1] = clamp255((G - (1 - a) * K.g) / a);
+    out.data[i + 2] = clamp255((B - (1 - a) * K.b) / a);
+    out.data[i + 3] = Math.round(a * 255);
+  }
+  return { ...base, png: out, ok: true };
+}
 
 // src/lib/open.ts
 import { spawn as spawn4 } from "child_process";
@@ -4348,10 +4844,22 @@ async function* readSSE(body) {
 
 // src/commands/generate.ts
 var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var SKYBOX_ENVIRONMENT_SUFFIX = ". Pure environment: sky, clouds, atmosphere, distant horizon haze. No buildings, no structures, no trees, no objects, no ground detail.";
+var SKYBOX_PROMPT_MAX = 2e3;
+function applySkyboxGuard(prompt, raw) {
+  if (raw) return { prompt, guarded: false };
+  const guarded = `${prompt}${SKYBOX_ENVIRONMENT_SUFFIX}`;
+  if (guarded.length > SKYBOX_PROMPT_MAX) return { prompt, guarded: false };
+  return { prompt: guarded, guarded: true };
+}
 function buildGenOptions(kind, opts) {
   const options = { ...opts.generationOptions };
   if (kind === "texture" && opts.terrain) options.terrain = true;
-  if (kind === "sfx" && opts.duration) options.durationSeconds = opts.duration;
+  if ((kind === "sfx" || kind === "music") && opts.duration) options.durationSeconds = opts.duration;
+  if (kind === "voice") {
+    if (opts.voice) options.voice = opts.voice;
+    if (opts.voiceId) options.voiceId = opts.voiceId;
+  }
   if (kind === "image") {
     if (opts.transparent) options.transparent = true;
     if (opts.aspect) options.aspect = opts.aspect;
@@ -4370,6 +4878,11 @@ function buildGenOptions(kind, opts) {
       options.op = "remove-bg";
       options.bgMode = opts.bgMode ?? "sheet";
     }
+    if (opts.upscaleUrl) {
+      options.sourceUrl = opts.upscaleUrl;
+      options.op = "upscale";
+    }
+    if (opts.inpaintUrl) options.maskUrl = opts.inpaintUrl;
     if (opts.removeBackground) options.removeBackground = true;
     if (opts.bgMode) options.bgMode = opts.bgMode;
   }
@@ -4385,12 +4898,45 @@ function buildGenOptions(kind, opts) {
 }
 async function runGenerate(kind, opts) {
   const log = createLogger({ quiet: opts.quiet || opts.json });
-  const prompt = opts.prompt?.trim();
-  if (!prompt) {
+  const typedPrompt = opts.prompt?.trim();
+  if (!typedPrompt) {
     log.error(`Missing prompt. Usage: ${c.cyan(`genex ${kind} "<prompt>"`)}`);
     process.exitCode = 1;
     return;
   }
+  const skyboxGuard = kind === "skybox" ? applySkyboxGuard(typedPrompt, opts.raw) : void 0;
+  let prompt = skyboxGuard?.prompt ?? typedPrompt;
+  if (kind === "image" && opts.glass) {
+    const conflict = opts.transparent ? "--transparent" : opts.removeBackground ? "--remove-bg" : opts.editUrl ? "--edit" : opts.cleanUrl ? "--clean" : opts.upscaleUrl ? "--upscale" : opts.noWait ? "--no-wait" : void 0;
+    if (conflict) {
+      log.error(
+        conflict === "--no-wait" ? "--glass runs a local key-solve on the finished image \u2014 it has to wait. Drop --no-wait." : `--glass generates a NEW panel on a magenta key screen \u2014 it cannot combine with ${conflict}. The solved RGBA ships real translucency; no removal pass applies.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    prompt = `${prompt}${GLASS_PROMPT_SUFFIX}`;
+  }
+  if (kind === "image" && opts.inpaintUrl && !/^https?:\/\//i.test(opts.inpaintUrl)) {
+    if (!opts.editUrl) {
+      log.error("--inpaint targets an edit \u2014 pass --edit <asset-url> alongside it.");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const bytes = await fs14.readFile(opts.inpaintUrl);
+      opts = { ...opts, inpaintUrl: `data:image/png;base64,${bytes.toString("base64")}` };
+    } catch {
+      log.error(`Couldn't read the --inpaint mask at ${opts.inpaintUrl}.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  if (kind === "voice" && prompt.length > 1e3) {
+    log.warn(
+      `Voice text is ${prompt.length} chars \u2014 the server clamps at 1000 (billing follows the clamp). Split longer copy into separate lines.`
+    );
+  }
   const token = opts.token ?? await readUserToken(opts.envPath);
   if (!token) {
     log.error("Not authorized. Run `genex init` first to sign in.");
@@ -4402,6 +4948,7 @@ async function runGenerate(kind, opts) {
   const options = buildGenOptions(kind, opts);
   log.plain(c.bold(`genex ${kind}`));
   log.dim(`  ${prompt}`);
+  if (skyboxGuard?.guarded) log.dim("  \u21B3 environment-only guard applied (--raw to disable)");
   log.plain("");
   let id;
   try {
@@ -4454,9 +5001,104 @@ async function runGenerate(kind, opts) {
     }
     return id;
   }
+  if (kind === "image" && opts.glass) {
+    if (!opts.json) log.step("Generating\u2026 (this can take up to a minute)");
+    const view = await waitForTerminalView(
+      apiUrl,
+      token,
+      id,
+      kind,
+      opts.json ? () => {
+      } : (p) => log.dim(`  ${p}%`)
+    );
+    if (!view) {
+      if (opts.json) writeJson({ kind, id, status: "failed", error: "Timed out waiting for the generation." });
+      else log.error("Timed out waiting for the generation.");
+      process.exitCode = 1;
+      return id;
+    }
+    await reportGlassTerminal(view, opts.outDir ?? ".", log, opts.json ?? false);
+    return id;
+  }
   await awaitAndReport(apiUrl, token, id, kind, log, opts.open, opts.json);
   return id;
 }
+async function reportGlassTerminal(view, outDir, log, json) {
+  const files = (view.files ?? []).filter((f) => /^image-(main|alt-\d+)$/.test(f.role));
+  if (view.status !== "completed" || files.length === 0) {
+    await reportTerminal("image", view, log, false, json);
+    return;
+  }
+  await recordTerminal(view.id, "completed", files.map((f) => f.url));
+  await fs14.mkdir(outDir, { recursive: true });
+  const solved = [];
+  for (let i = 0; i < files.length; i++) {
+    const f = files[i];
+    let png;
+    try {
+      const res = await fetch(f.url);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      png = PNG4.sync.read(Buffer.from(await res.arrayBuffer()));
+    } catch (err) {
+      solved.push({
+        path: null,
+        url: f.url,
+        keyHex: "",
+        keyStrength: 0,
+        flatness: 0,
+        rejected: `couldn't fetch the candidate (${String(err)}) \u2014 re-run later; the URL stays live.`
+      });
+      continue;
+    }
+    const r = solveMagentaGlass(png);
+    if (!r.ok) {
+      solved.push({
+        path: null,
+        url: f.url,
+        keyHex: r.keyHex,
+        keyStrength: r.keyStrength,
+        flatness: r.flatness,
+        rejected: r.rejected
+      });
+      continue;
+    }
+    const outPath = path14.join(outDir, `glass-${i + 1}.png`);
+    await fs14.writeFile(outPath, PNG4.sync.write(r.png));
+    solved.push({
+      path: outPath,
+      url: f.url,
+      keyHex: r.keyHex,
+      keyStrength: r.keyStrength,
+      flatness: r.flatness
+    });
+  }
+  const shipped = solved.filter((s) => s.path !== null);
+  if (json) {
+    writeJson({ kind: "image", id: view.id, status: view.status, glass: solved });
+    if (shipped.length === 0) process.exitCode = 1;
+    return;
+  }
+  log.plain("");
+  if (shipped.length > 0) {
+    log.success(`Solved ${shipped.length} glass panel(s) \u2014 real translucency baked in the alpha:`);
+  }
+  for (const s of solved) {
+    if (s.path) {
+      log.plain(`  ${s.path}  ${c.dim(`key ${s.keyHex}, strength ${s.keyStrength}, flatness ${s.flatness.toFixed(3)}`)}`);
+    } else {
+      log.error(`Candidate rejected: ${s.rejected}`);
+      log.dim(`  raw candidate stays at ${s.url}`);
+    }
+  }
+  if (shipped.length > 0) {
+    log.plain("");
+    log.dim(
+      "  Wire the PNG like any sprite (TextureLoader / <img>): its alpha IS the glass \u2014 no CSS opacity, no plate underneath. See genex-ai-image (--glass) and genex-ai-menu."
+    );
+  } else {
+    process.exitCode = 1;
+  }
+}
 async function awaitAndReport(apiUrl, token, id, kind, log, open = false, json = false) {
   if (!json) log.step("Generating\u2026 (this can take up to a minute)");
   const view = await waitForTerminalView(
@@ -4640,7 +5282,7 @@ async function reportTextureSeam(url, log) {
   try {
     const res = await fetch(url);
     if (!res.ok) return;
-    const png = PNG3.sync.read(Buffer.from(await res.arrayBuffer()));
+    const png = PNG4.sync.read(Buffer.from(await res.arrayBuffer()));
     if (png.width < 4 || png.height < 4) return;
     const r = measureSeam(png);
     if (r.seamless) {
@@ -4664,6 +5306,8 @@ function printHint(kind, view, files, log) {
     model: `Standard GLB \u2014 load with GLTFLoader straight from the URL \u2014 see the genex-ai-model skill. url = "${url}"`,
     skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. url = "${url}"`,
     sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. url = "${url}"`,
+    music: `Load with AudioLoader into a non-positional THREE.Audio: setLoop(true), setVolume(0.30), start on the first user gesture \u2014 and the settings screen MUST have Music + SFX volume sliders \u2014 see genex-ai-music. url = "${url}"`,
+    voice: `Load with AudioLoader into a THREE.Audio (or PositionalAudio at the speaker); voice lines are content \u2014 keep them short, SUBTITLED, and skippable \u2014 see genex-ai-voice. url = "${url}"`,
     texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`,
     image: `Load with TextureLoader (set colorSpace = SRGBColorSpace) onto any mesh/plane/sprite \u2014 see genex-ai-image. url = "${url}"`,
     video: `Wire an HTMLVideoElement (crossOrigin="anonymous", muted, loop, playsInline) into a THREE.VideoTexture \u2014 see genex-ai-video. url = "${url}"`,
@@ -4998,8 +5642,8 @@ async function toRow(e, v, cwd) {
 }
 
 // src/commands/controller.ts
-import fs15 from "fs/promises";
-import path15 from "path";
+import fs16 from "fs/promises";
+import path16 from "path";
 
 // ../../packages/meshy-animation-catalog/src/index.ts
 import { createHash } from "crypto";
@@ -14129,9 +14773,9 @@ function searchMeshyAnimations(query, options = {}) {
 }
 
 // src/lib/anims.ts
-import fs14 from "fs/promises";
-import path14 from "path";
-var ANIMS_DEST = path14.join("public", "assets", "anims");
+import fs15 from "fs/promises";
+import path15 from "path";
+var ANIMS_DEST = path15.join("public", "assets", "anims");
 var HIDDEN_TAG = "reference";
 async function runAnims(opts) {
   const log = createLogger({ quiet: opts.quiet });
@@ -14147,7 +14791,7 @@ async function runAnims(opts) {
     printCatalog(log, manifest, selectors);
     return;
   }
-  const controllerMarker = path14.join(root, "src", "controllers", "character");
+  const controllerMarker = path15.join(root, "src", "controllers", "character");
   if (!await exists2(controllerMarker)) {
     log.error(
       `No character controller in this game (missing ${c.cyan("src/controllers/character/")}).`
@@ -14156,11 +14800,11 @@ async function runAnims(opts) {
     process.exitCode = 1;
     return;
   }
-  const destDir = path14.join(root, ANIMS_DEST);
-  const gameManifestPath = path14.join(destDir, "manifest.json");
+  const destDir = path15.join(root, ANIMS_DEST);
+  const gameManifestPath = path15.join(destDir, "manifest.json");
   if (opts.reset) {
-    await fs14.rm(destDir, { recursive: true, force: true });
-    log.step(`Cleared ${c.cyan(ANIMS_DEST + path14.sep)} (--reset)`);
+    await fs15.rm(destDir, { recursive: true, force: true });
+    log.step(`Cleared ${c.cyan(ANIMS_DEST + path15.sep)} (--reset)`);
   }
   if (selectors.length === 0) {
     const installed = await readGameManifest(gameManifestPath);
@@ -14198,35 +14842,35 @@ async function runAnims(opts) {
     }
   }
   const wanted = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-  const cacheDir = path14.join(
+  const cacheDir = path15.join(
     opts.cacheDir ?? getAnimsCacheDir(),
     `${manifest.library}-v${manifest.version}`
   );
-  await fs14.mkdir(cacheDir, { recursive: true });
-  await fs14.mkdir(destDir, { recursive: true });
+  await fs15.mkdir(cacheDir, { recursive: true });
+  await fs15.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 = path14.join(destDir, entry.file);
+    const dest = path15.join(destDir, entry.file);
     if (await hasSize(dest, entry.bytes)) {
       presentCount++;
       continue;
     }
     try {
-      const cached = path14.join(cacheDir, entry.file);
+      const cached = path15.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 fs14.writeFile(cached, buf);
+        await fs15.writeFile(cached, buf);
       }
-      await fs14.copyFile(cached, dest);
+      await fs15.copyFile(cached, dest);
       installedCount++;
       addedBytes += entry.bytes;
-      log.dim(`  ${path14.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
+      log.dim(`  ${path15.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
     } catch (err) {
       failures.push(`${entry.name} (${err instanceof Error ? err.message : String(err)})`);
     }
@@ -14242,13 +14886,13 @@ async function runAnims(opts) {
     version: manifest.version,
     clips: [...union].sort((a, b) => a.localeCompare(b))
   };
-  await fs14.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
+  await fs15.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 + path14.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
+    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path15.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
   );
   for (const [selector, entries] of resolved) {
     const names = entries.filter((e) => !coreNames.has(e.name)).map((e) => e.name);
@@ -14280,8 +14924,8 @@ async function loadManifest(baseOverride) {
     }
   } catch {
   }
-  const snapshotPath = path14.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
-  const manifest = JSON.parse(await fs14.readFile(snapshotPath, "utf8"));
+  const snapshotPath = path15.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
+  const manifest = JSON.parse(await fs15.readFile(snapshotPath, "utf8"));
   return { manifest, source: "snapshot" };
 }
 function resolveSelectors(manifest, selectors) {
@@ -14399,21 +15043,21 @@ function printCatalog(log, manifest, selectors) {
 }
 async function readGameManifest(file) {
   try {
-    return JSON.parse(await fs14.readFile(file, "utf8"));
+    return JSON.parse(await fs15.readFile(file, "utf8"));
   } catch {
     return null;
   }
 }
 async function hasSize(file, bytes) {
   try {
-    return (await fs14.stat(file)).size === bytes;
+    return (await fs15.stat(file)).size === bytes;
   } catch {
     return false;
   }
 }
 async function exists2(p) {
   try {
-    await fs14.access(p);
+    await fs15.access(p);
     return true;
   } catch {
     return false;
@@ -14445,6 +15089,7 @@ var TOUCH_KIT = [
 var INPUT_AND_CAMERA = [
   "character/follow-camera.ts",
   "character/aim-cue.ts",
+  "character/first-person.ts",
   "character/keyboard-input.ts",
   "character/touch-joystick.ts",
   ...TOUCH_KIT
@@ -14571,8 +15216,8 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path15.join("src", "controllers");
-var ASSETS_DEST = path15.join("public", "assets");
+var CODE_DEST = path16.join("src", "controllers");
+var ASSETS_DEST = path16.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
   if (opts.kind?.trim() === "anims") {
@@ -14589,31 +15234,31 @@ async function runController(opts) {
     process.exitCode = 1;
     return;
   }
-  const srcDir = path15.join(getTemplatesDir(), "controllers");
+  const srcDir = path16.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 + path15.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path16.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path15.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path16.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path15.join(ASSETS_DEST, path15.basename(rel))
+      rel: path16.join(ASSETS_DEST, path16.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path15.join(root, file.rel);
+      const dest = path16.join(root, file.rel);
       if (!opts.force && await exists3(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs15.mkdir(path15.dirname(dest), { recursive: true });
-      await fs15.copyFile(path15.join(srcDir, file.from), dest);
+      await fs16.mkdir(path16.dirname(dest), { recursive: true });
+      await fs16.copyFile(path16.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -14698,9 +15343,9 @@ async function installMeshyCharacterManifest(args) {
     throw new Error("The API returned an invalid Meshy character manifest.");
   }
   assertCompleteMeshyControllerPack(manifest);
-  const destination = path15.join(args.root, ASSETS_DEST, "meshy-character.json");
-  await fs15.mkdir(path15.dirname(destination), { recursive: true });
-  await fs15.writeFile(
+  const destination = path16.join(args.root, ASSETS_DEST, "meshy-character.json");
+  await fs16.mkdir(path16.dirname(destination), { recursive: true });
+  await fs16.writeFile(
     destination,
     `${JSON.stringify(manifest, null, 2)}
 `
@@ -14837,8 +15482,8 @@ function assertCompleteMeshyControllerPack(manifest) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path15.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs15.mkdir(path15.dirname(dest), { recursive: true });
+  const dest = path16.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs16.mkdir(path16.dirname(dest), { recursive: true });
   if (token) {
     try {
       const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
@@ -14850,7 +15495,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs15.writeFile(dest, buf);
+            await fs16.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -14861,14 +15506,14 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs15.copyFile(path15.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs16.copyFile(path16.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 fs15.access(p);
+    await fs16.access(p);
     return true;
   } catch {
     return false;
@@ -15464,7 +16109,7 @@ function rank(items, query) {
 }
 
 // src/index.ts
-var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);
+var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "music", "voice", "texture", "image", "video"]);
 var HELP = `${c.bold("genex")} \u2014 set up your project's agent workspace, authorize, and publish 3D games.
 
 ${c.bold("Usage")}
@@ -15479,10 +16124,17 @@ ${c.bold("Usage")}
   genex publish [options]            Build + push, then list the game in the gallery.
   genex make-remixable [options]     Make THIS game remixable by everyone \u2014 migrates a
                                      private source onto a public managed genex repo.
-  genex model "<prompt>" [options]   Generate a 3D model (GLB) into public/assets/models.
-  genex skybox "<prompt>" [options]  Generate a skybox (equirect) into public/assets/skybox.
-  genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into public/assets/sfx.
-  genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
+  genex model "<prompt>" [options]   Generate a 3D model (GLB); prints a public asset URL.
+  genex skybox "<prompt>" [options]  Generate a skybox (equirect); prints a public asset URL.
+  genex sfx "<prompt>" [options]     Generate a sound effect (mp3); prints a public asset URL.
+  genex music "<prompt>" [options]   Generate an instrumental music track (mp3); prints a
+                                     public asset URL. --duration 10-300s (default 90).
+  genex voice "<line>" [options]     Speak a short line (mp3, ElevenLabs TTS); prints a
+                                     public asset URL. --voice picks a cast archetype
+                                     (narrator|heroine|gruff|elder|robot|imp; default
+                                     narrator), --voice-id any raw ElevenLabs voice id.
+                                     Billed per character, hard-capped at 1000.
+  genex texture "<prompt>" [options] Generate a PBR texture; prints public asset URLs.
   genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
   genex character "<brief>"          Generate 3 character concepts for user selection.
@@ -15493,6 +16145,10 @@ ${c.bold("Usage")}
                                      Finalize an approved preview as a 10,000-face
                                      controller-ready Meshy character.
   genex character animate <id>       Add Meshy library actions to that character.
+  genex creature "<desc>"            One-shot rigged enemy/creature (biped-shaped
+                                     bodies only \u2014 Meshy rig limit): model \u2192 rig \u2192
+                                     bind library clips via --animation. No approval
+                                     ceremony, no player controller pack.
   genex animations search "<intent>" Search Meshy's animation library by gameplay intent.
   genex wait <id>                    Attach to a generation enqueued with --no-wait and
                                      print its asset URL(s) when it finishes. Safe to
@@ -15519,10 +16175,19 @@ ${c.bold("Usage")}
                                      Pure local work (no API); the PNG tools read
                                      a file or URL, audit scans the project.
 
-${c.bold("Options for the generators (`model` `skybox` `sfx` `texture` `image` `video`)")}
+${c.bold("Options for the generators (`model` `skybox` `sfx` `music` `voice` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
-  --duration <sec>     (sfx, video) target clip length in seconds.
+  --raw                (skybox) send the prompt exactly as written \u2014 skip the
+                       appended environment-only guard.
+  --duration <sec>     (sfx, video, music) target clip length in seconds
+                       (music: 10-300, default 90 \u2014 a looping gameplay track).
   --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
+  --glass              (image) magenta-key glass lane: generate the panel on a
+                       flat #FF00FF screen, then locally solve REAL per-pixel
+                       translucency and write RGBA files (glass-1.png\u2026) into
+                       --out-dir (default .). For genuinely glassy panels; not
+                       for magenta/pink-hued art. Conflicts with --edit/--clean/
+                       --upscale/--transparent/--remove-bg/--no-wait.
   --open               (image/video) open the finished asset in the user's browser +
                        print a link \u2014 show them the concept frame / anything they approve.
   --aspect <ratio>     (image) aspect preset (e.g. square, landscape, portrait).
@@ -15534,11 +16199,20 @@ ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture` `image` `
   --edit <url>         (image) edit THIS image (asset URL) with the prompt (i2i).
   --clean <url>        (image) ML-remove the background of THIS image (asset URL);
                        prompt is recorded but unused. Defaults --bg-mode sheet.
+  --upscale <url>      (image) upscale THIS image 2x (clarity upscaler); prompt
+                       is recorded but unused. ~2 credits class.
+  --inpaint <mask>     (image, with --edit) region mask: local PNG path or asset
+                       URL; TRANSPARENT hole = the zone to change. Targets WHERE
+                       the edit lands (other regions keep their design) but the
+                       whole image still re-renders and alpha is destroyed \u2014
+                       re-run --clean + re-extract afterwards.
   --remove-bg          (image) chain ML background removal after the gen/edit.
-  --bg-mode <mode>     (image) background-removal model: sprite | glyph | sheet.
+  --bg-mode <mode>     (image) background-removal model: sprite | glyph | sheet |
+                       matte (BiRefNet soft alpha \u2014 hair/glow/smoke edges).
   --loop               (video) generate a seamless loop.
-  --resolution <r>     (video) 720p | 1080p (default 1080p; use 720p to save
-                       credits \u2014 loop clips ignore it, model default).
+  --resolution <r>     (video) 720p | 1080p (default 1080p; 720p halves the cost
+                       when quality genuinely doesn't matter \u2014 loop clips
+                       ignore it, model default).
   --frame <url>        (video) animate from THIS frame back to itself (seamless loop).
   --first-frame <url>  (video) start frame for a two-frame motion \u2026
   --last-frame <url>   (video) \u2026 and its end frame.
@@ -15649,11 +16323,14 @@ ${c.bold("Examples")}
   genex model "weathered wooden barrel with iron bands"
   genex skybox "golden hour over a misty mountain range"
   genex sfx "punchy laser zap" --duration 2
+  genex music "brooding orchestral battle loop, seamless loop, no intro or outro" --no-wait
+  genex voice "You shall not pass!" --voice gruff
   genex texture "mossy cracked cobblestone" --terrain
   genex image "retro arcade poster art" --aspect portrait
   genex image "chalk graffiti tag, hand-drawn style" --transparent
   genex video "candle flame flickering in the dark, seamless loop" --loop
   genex image "misty citadel at dusk, cinematic wide shot" --aspect 16:9 --quality high
+  genex image "frosted translucent sci-fi status panel, about 40 percent opacity" --glass --size 1280x832 --quality high
   genex video "slow drifting fog, embers rising" --frame <that-image-url> --duration 8 --no-wait
   genex wait <that-generation-id>
   genex ui extract --in <sheet-url> --out-dir ui/ --names health-bar,minimap,ammo
@@ -15664,6 +16341,7 @@ ${c.bold("Examples")}
   genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
   genex character "stylized sci-fi courier" --direct-text --no-wait
   genex character animate <character-id> --action <action-id>
+  genex creature "hulking bone seraph, upright stance" --animation <walk-id> --animation <attack-id> --no-wait
   genex controller character --character <character-id>
   genex controller anims sword pistol
   genex controller touch
@@ -15696,7 +16374,11 @@ function parseArgs(argv) {
     "--size",
     "--edit",
     "--clean",
+    "--upscale",
+    "--inpaint",
     "--bg-mode",
+    "--voice",
+    "--voice-id",
     "--frame",
     "--first-frame",
     "--last-frame",
@@ -15770,9 +16452,18 @@ function parseArgs(argv) {
       case "--terrain":
         parsed.options.terrain = true;
         break;
+      case "--raw":
+        parsed.options.raw = true;
+        break;
       case "--transparent":
         parsed.options.transparent = true;
         break;
+      case "--glass":
+        parsed.options.glass = true;
+        break;
+      case "--no-defringe":
+        parsed.options.defringe = false;
+        break;
       case "--loop":
         parsed.options.loop = true;
         break;
@@ -15841,6 +16532,8 @@ function parseArgs(argv) {
             parsed.error = `Unexpected argument: ${arg}`;
             return parsed;
           }
+        } else if (parsed.command === "creature") {
+          parsed.options.name = `${parsed.options.name} ${arg}`;
         } else if (parsed.command === "animations") {
           parsed.options.query = parsed.options.query ? `${parsed.options.query} ${arg}` : arg;
         } else {
@@ -16014,9 +16707,21 @@ function applyValueFlag(options, flag, value) {
     case "--clean":
       options.cleanUrl = value;
       break;
+    case "--upscale":
+      options.upscaleUrl = value;
+      break;
+    case "--inpaint":
+      options.inpaintUrl = value;
+      break;
+    case "--voice":
+      options.voice = value;
+      break;
+    case "--voice-id":
+      options.voiceId = value;
+      break;
     case "--bg-mode":
-      if (!["sprite", "glyph", "sheet"].includes(value)) {
-        throw new Error(`Invalid --bg-mode value: ${value} (expected sprite|glyph|sheet)`);
+      if (!["sprite", "glyph", "sheet", "matte"].includes(value)) {
+        throw new Error(`Invalid --bg-mode value: ${value} (expected sprite|glyph|sheet|matte)`);
       }
       options.bgMode = value;
       break;
@@ -16137,6 +16842,19 @@ async function main() {
           await runCharacter({ ...parsed.options, prompt: parsed.options.name });
         }
         break;
+      case "creature":
+        if (!parsed.options.json && !parsed.options.quiet) {
+          log.dim(
+            "  Biped-shaped creatures only (Meshy rig limit) \u2014 for true quadrupeds/fliers use a static model + the genex-threejs-creatures procedural recipes."
+          );
+        }
+        await runCharacter({
+          ...parsed.options,
+          prompt: parsed.options.name,
+          directText: true,
+          controllerPack: false
+        });
+        break;
       case "animations":
         if (parsed.options.name !== "search") {
           log.error('Unknown animations command. Use `genex animations search "<intent>"`.');