@genex-ai/cli-demo 0.47.0-dev.70 → 0.47.0-dev.74

package/dist/index.js

@@ -445,7 +445,7 @@ async function authorize(authBaseUrl, options) {
       cleanup();
       resolve(token);
     };
-    const fail = (err) => {
+    const fail2 = (err) => {
       if (settled) return;
       settled = true;
       cleanup();
@@ -462,7 +462,7 @@ async function authorize(authBaseUrl, options) {
         }
       });
     });
-    server.on("error", (err) => fail(err));
+    server.on("error", (err) => fail2(err));
     server.listen(0, "127.0.0.1", () => {
       const { port } = server.address();
       const redirectUri = `http://127.0.0.1:${port}/callback`;
@@ -493,7 +493,7 @@ async function authorize(authBaseUrl, options) {
         );
       }
       timer = setTimeout(() => {
-        fail(
+        fail2(
           new Error(
             "Timed out waiting for authorization. Re-run the command to try again."
           )
@@ -1825,6 +1825,13 @@ function advisoryNudges(log, d) {
     );
   }
 }
+async function firstPreviewNudge(log, cwd = process.cwd()) {
+  const meta = await readProject(cwd);
+  if (!meta || meta.lastDeployAt || meta.status === "published") return;
+  log.dim(
+    "  \u279C Draft page still the placeholder? Ship the first rough build now: npx genex preview \u2014 then keep building."
+  );
+}
 
 // src/commands/publish.ts
 async function runPublish(opts) {
@@ -1861,6 +1868,8 @@ async function runPublish(opts) {
       process.exitCode = 1;
       return;
     }
+    meta.lastDeployAt = (/* @__PURE__ */ new Date()).toISOString();
+    await writeProject(meta);
   } else {
     log.info("Skipping build + deploy (--no-push).");
   }
@@ -1944,8 +1953,9 @@ async function runPreview(opts) {
   const freshStatus = await fetchProjectStatus(apiUrl, token, meta.slug);
   if (freshStatus && freshStatus !== meta.status) {
     meta.status = freshStatus;
-    await writeProject(meta);
   }
+  meta.lastDeployAt = (/* @__PURE__ */ new Date()).toISOString();
+  await writeProject(meta);
   const published = meta.status === "published";
   log.plain("");
   if (published) {
@@ -2001,6 +2011,40 @@ async function* readSSE(body) {
 
 // src/commands/generate.ts
 var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function buildGenOptions(kind, opts) {
+  const options = {};
+  if (kind === "texture" && opts.terrain) options.terrain = true;
+  if (kind === "sfx" && opts.duration) options.durationSeconds = opts.duration;
+  if (kind === "image") {
+    if (opts.transparent) options.transparent = true;
+    if (opts.aspect) options.aspect = opts.aspect;
+    if (opts.quality) options.quality = opts.quality;
+    if (opts.candidates !== void 0 && opts.candidates > 1) options.candidates = opts.candidates;
+    if (opts.width && opts.height) {
+      options.width = opts.width;
+      options.height = opts.height;
+    }
+    if (opts.editUrl) {
+      options.sourceUrl = opts.editUrl;
+      options.op = "edit";
+    }
+    if (opts.cleanUrl) {
+      options.sourceUrl = opts.cleanUrl;
+      options.op = "remove-bg";
+      options.bgMode = opts.bgMode ?? "sheet";
+    }
+    if (opts.removeBackground) options.removeBackground = true;
+    if (opts.bgMode) options.bgMode = opts.bgMode;
+  }
+  if (kind === "video") {
+    if (opts.duration) options.durationSeconds = opts.duration;
+    if (opts.loop) options.loop = true;
+    if (opts.frameUrl) options.frameUrl = opts.frameUrl;
+    if (opts.firstFrameUrl) options.firstFrameUrl = opts.firstFrameUrl;
+    if (opts.lastFrameUrl) options.lastFrameUrl = opts.lastFrameUrl;
+  }
+  return options;
+}
 async function runGenerate(kind, opts) {
   const log = createLogger({ quiet: opts.quiet });
   const prompt = opts.prompt?.trim();
@@ -2017,13 +2061,7 @@ async function runGenerate(kind, opts) {
   }
   const meta = await readProject();
   const apiUrl = getApiUrl(opts.apiUrl ?? meta?.apiUrl);
-  const options = {};
-  if (kind === "texture" && opts.terrain) options.terrain = true;
-  if (kind === "sfx" && opts.duration) options.durationSeconds = opts.duration;
-  if (kind === "image" && opts.transparent) options.transparent = true;
-  if (kind === "image" && opts.aspect) options.aspect = opts.aspect;
-  if (kind === "video" && opts.duration) options.durationSeconds = opts.duration;
-  if (kind === "video" && opts.loop) options.loop = true;
+  const options = buildGenOptions(kind, opts);
   log.plain(c.bold(`genex ${kind}`));
   log.dim(`  ${prompt}`);
   log.plain("");
@@ -2044,7 +2082,15 @@ async function runGenerate(kind, opts) {
       return;
     }
     if (!res.ok) {
-      log.error(`Generation request failed (HTTP ${res.status}).`);
+      let message;
+      if (res.status >= 400 && res.status < 500) {
+        try {
+          const body = await res.json();
+          if (typeof body.message === "string" && body.message.trim()) message = body.message;
+        } catch {
+        }
+      }
+      log.error(message ?? `Generation request failed (HTTP ${res.status}).`);
       process.exitCode = 1;
       return;
     }
@@ -2055,9 +2101,14 @@ async function runGenerate(kind, opts) {
     return;
   }
   if (opts.noWait) {
-    log.success(`Queued (${id}). Re-run without --no-wait to get the finished asset URL.`);
+    log.success(`Queued (${id}).`);
+    log.plain(`  Pick it up any time with: ${c.cyan(`npx genex wait ${id}`)}`);
+    log.dim("  (Re-running the generate command would start \u2014 and bill \u2014 a NEW generation.)");
     return;
   }
+  await awaitAndReport(apiUrl, token, id, kind, log);
+}
+async function awaitAndReport(apiUrl, token, id, kind, log) {
   log.step("Generating\u2026 (this can take up to a minute)");
   const onProgress = (p) => log.dim(`  ${p}%`);
   const timeoutMs = waitTimeoutFor(kind);
@@ -2069,6 +2120,9 @@ async function runGenerate(kind, opts) {
     process.exitCode = 1;
     return;
   }
+  await reportTerminal(kind, view, log);
+}
+async function reportTerminal(kind, view, log) {
   if (view.status !== "completed") {
     log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
     process.exitCode = 1;
@@ -2088,6 +2142,7 @@ async function runGenerate(kind, opts) {
   }
   log.plain("");
   printHint(kind, files, log);
+  await firstPreviewNudge(log);
 }
 var WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
 var KIND_WAIT_TIMEOUT_MS = {
@@ -2185,6 +2240,63 @@ function printHint(kind, files, log) {
   log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
 }
 
+// src/commands/wait.ts
+var TERMINAL2 = /* @__PURE__ */ new Set(["completed", "failed"]);
+async function runWait(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const id = opts.id?.trim();
+  if (!id) {
+    log.error(
+      `Missing generation id. Usage: ${c.cyan("genex wait <id>")} \u2014 the id printed when you enqueued with --no-wait.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const token = opts.token ?? await readUserToken(opts.envPath);
+  if (!token) {
+    log.error("Not authorized. Run `genex init` first to sign in.");
+    process.exitCode = 1;
+    return;
+  }
+  const meta = await readProject();
+  const apiUrl = getApiUrl(opts.apiUrl ?? meta?.apiUrl);
+  let view;
+  try {
+    const res = await apiFetch(`${apiUrl}/api/generations/${id}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.status === 401) {
+      log.error("Unauthorized \u2014 your token may have expired. Re-run `genex init`.");
+      process.exitCode = 1;
+      return;
+    }
+    if (res.status === 404) {
+      log.error(`No generation ${id} on this account \u2014 check the id printed by --no-wait.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!res.ok) {
+      log.error(`Couldn't look up the generation (HTTP ${res.status}).`);
+      process.exitCode = 1;
+      return;
+    }
+    ({ generation: view } = await res.json());
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  const kind = view.kind ?? "image";
+  log.plain(c.bold("genex wait"));
+  log.dim(`  ${kind} ${id}`);
+  log.plain("");
+  if (TERMINAL2.has(view.status)) {
+    await reportTerminal(kind, view, log);
+    return;
+  }
+  await awaitAndReport(apiUrl, token, id, kind, log);
+}
+
 // src/commands/controller.ts
 import fs12 from "fs/promises";
 import path13 from "path";
@@ -2658,6 +2770,7 @@ async function runController(opts) {
   for (const line of set.sketch) {
     log.dim(`       ${line}`);
   }
+  await firstPreviewNudge(log);
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
@@ -2764,6 +2877,906 @@ function rank(items, query) {
   }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.p.playsCount - a.p.playsCount).map((x) => x.p);
 }
 
+// src/commands/ui.ts
+import fs14 from "fs/promises";
+import path14 from "path";
+import { PNG as PNG2 } from "pngjs";
+
+// src/lib/png-tools.ts
+import fs13 from "fs/promises";
+import { PNG } from "pngjs";
+var ALPHA_TRANSPARENT_MAX = 16;
+var isHttpUrl = (s) => /^https?:\/\//i.test(s);
+async function loadPng(input) {
+  let buf;
+  if (isHttpUrl(input)) {
+    const res = await fetch(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);
+  }
+  return PNG.sync.read(buf);
+}
+async function writePng(file, png) {
+  await fs13.writeFile(file, PNG.sync.write(png));
+}
+function cropPng(image, box) {
+  const out = new PNG({ width: box.w, height: box.h });
+  PNG.bitblt(image, out, box.x, box.y, box.w, box.h, 0, 0);
+  return out;
+}
+function floodFill(width, height, visited, queue, startX, startY, inRegion, onPixel) {
+  let head = 0;
+  let tail = 0;
+  const start = startY * width + startX;
+  visited[start] = 1;
+  queue[tail++] = start;
+  let pixels = 0;
+  let minX = startX;
+  let minY = startY;
+  let maxX = startX;
+  let maxY = startY;
+  let touchesEdge = false;
+  while (head < tail) {
+    const idx = queue[head++];
+    const x = idx % width;
+    const y = idx / width | 0;
+    pixels++;
+    if (onPixel) onPixel(idx);
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+    if (x === 0 || x === width - 1 || y === 0 || y === height - 1) touchesEdge = true;
+    if (x + 1 < width && !visited[idx + 1] && inRegion(idx + 1)) {
+      visited[idx + 1] = 1;
+      queue[tail++] = idx + 1;
+    }
+    if (x > 0 && !visited[idx - 1] && inRegion(idx - 1)) {
+      visited[idx - 1] = 1;
+      queue[tail++] = idx - 1;
+    }
+    if (y + 1 < height && !visited[idx + width] && inRegion(idx + width)) {
+      visited[idx + width] = 1;
+      queue[tail++] = idx + width;
+    }
+    if (y > 0 && !visited[idx - width] && inRegion(idx - width)) {
+      visited[idx - width] = 1;
+      queue[tail++] = idx - width;
+    }
+  }
+  return { pixels, minX, minY, maxX, maxY, touchesEdge };
+}
+function scanComponents(width, height, inRegion, onComponent, onPixel) {
+  const visited = new Uint8Array(width * height);
+  const queue = new Int32Array(width * height);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = y * width + x;
+      if (visited[idx] || !inRegion(idx)) continue;
+      onComponent(floodFill(width, height, visited, queue, x, y, inRegion, onPixel));
+    }
+  }
+}
+function alphaBBoxPx(png) {
+  const { width, height, data } = png;
+  let minX = width;
+  let minY = height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (data[(y * width + x) * 4 + 3] > ALPHA_TRANSPARENT_MAX) {
+        if (x < minX) minX = x;
+        if (x > maxX) maxX = x;
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+      }
+    }
+  }
+  return maxX < 0 ? null : { minX, minY, maxX, maxY };
+}
+function computeBBoxes(png) {
+  const { width, height, data } = png;
+  const r3 = (n) => Math.round(n * 1e3) / 1e3;
+  const result = {
+    size: { w: width, h: height },
+    aspectRatio: r3(width / height),
+    outerBBox: null,
+    innerBBox: null
+  };
+  const outer = alphaBBoxPx(png);
+  if (!outer) return result;
+  const { minX, minY, maxX, maxY } = outer;
+  result.outerBBox = {
+    x: r3(minX / width),
+    y: r3(minY / height),
+    w: r3((maxX - minX + 1) / width),
+    h: r3((maxY - minY + 1) / height)
+  };
+  const cx = Math.floor((minX + maxX) / 2);
+  const cy = Math.floor((minY + maxY) / 2);
+  if (data[(cy * width + cx) * 4 + 3] > ALPHA_TRANSPARENT_MAX) return result;
+  const cavity = floodFill(
+    width,
+    height,
+    new Uint8Array(width * height),
+    new Int32Array(width * height),
+    cx,
+    cy,
+    (idx) => data[idx * 4 + 3] <= ALPHA_TRANSPARENT_MAX
+  );
+  if (cavity.touchesEdge) return result;
+  const cavW = cavity.maxX - cavity.minX + 1;
+  const cavH = cavity.maxY - cavity.minY + 1;
+  if (cavW > width * 0.1 && cavH > height * 0.1) {
+    result.innerBBox = {
+      x: r3(cavity.minX / width),
+      y: r3(cavity.minY / height),
+      w: r3(cavW / width),
+      h: r3(cavH / height)
+    };
+  }
+  return result;
+}
+
+// src/commands/ui.ts
+var UI_NUMBER_FLAGS = {
+  "--min-pixels": "minPixels",
+  "--padding": "padding",
+  "--chroma": "chroma",
+  "--dilate": "dilate",
+  "--registration-tolerance": "registrationTolerance",
+  "--coverage-min": "coverageMin",
+  "--coverage-max": "coverageMax",
+  "--component-min-pixels": "componentMinPixels",
+  "--edge-flush-max": "edgeFlushMax",
+  "--quantize": "quantize",
+  "--ink-dist": "inkDist",
+  "--min-frac": "minFrac"
+};
+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. [--min-pixels 2000] [--padding 8] [--chroma 240]
+                       [--dilate 0]
+  ui masks             --out-dir <dir> --pairs "name:cX,cY,w,h:aX,aY,w,h[:n];\u2026" \u2014
+                       clean frame + green-annotated duplicate \u2192 frame + fill mask
+                       + fillBox (+ overlay + provenance JSON). [--registration-
+                       tolerance 0.04] [--coverage-min 0.01] [--coverage-max 0.85]
+                       [--component-min-pixels 100] [--edge-flush-max 0.04]
+  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>]
+  ui trim              [--out <png>] \u2014 crop to the alpha bbox (default: overwrite
+                       --in), print real dims + refresh the .bbox.json sidecar.`;
+async function runUi(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  try {
+    switch (opts.sub?.trim()) {
+      case "extract":
+        await uiExtract(opts, log);
+        return;
+      case "masks":
+        await uiMasks(opts, log);
+        return;
+      case "text-color":
+        await uiTextColor(opts, log);
+        return;
+      case "trim":
+        await uiTrim(opts, log);
+        return;
+      default:
+        log.error(
+          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim.` : "Missing ui tool. Tools: extract, masks, text-color, trim."
+        );
+        log.plain(UI_USAGE);
+        process.exitCode = 1;
+        return;
+    }
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+function fail(message, details) {
+  throw new Error(details === void 0 ? message : `${message} ${JSON.stringify(details)}`);
+}
+function requireOpt(value, flag, sub) {
+  if (!value?.trim()) fail(`Missing ${flag}. Run \`genex ui ${sub}\` \u2014 see \`genex --help\`.`);
+  return value.trim();
+}
+async function uiExtract(opts, log) {
+  const input = requireOpt(opts.input, "--in", "extract");
+  const outDir = requireOpt(opts.outDir, "--out-dir", "extract");
+  const names = (opts.names ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (names.length === 0) fail("Missing --names (comma-separated element names, reading order).");
+  const minPixels = opts.minPixels ?? 2e3;
+  const padding = opts.padding ?? 8;
+  const chroma = opts.chroma ?? 240;
+  const dilatePx = opts.dilate ?? 0;
+  const sheet = await loadPng(input);
+  const { width: W, height: H, data } = sheet;
+  await fs14.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;
+  for (let i = 0; i < W * H; i++) {
+    if (data[i * 4 + 3] < 250) {
+      hasTransparency = true;
+      break;
+    }
+  }
+  const inputMode = hasTransparency ? "alpha" : "chroma";
+  const subject = new Uint8Array(W * H);
+  let subjectCount = 0;
+  for (let i = 0; i < W * H; i++) {
+    const a = data[i * 4 + 3];
+    const isOpaque = a > ALPHA_TRANSPARENT_MAX;
+    let isSubject = false;
+    if (inputMode === "alpha") {
+      isSubject = isOpaque;
+    } else {
+      const r = data[i * 4 + 0];
+      const g = data[i * 4 + 1];
+      const b = data[i * 4 + 2];
+      const isWhite = r >= chroma && g >= chroma && b >= chroma;
+      isSubject = isOpaque && !isWhite;
+    }
+    if (isSubject) {
+      subject[i] = 1;
+      subjectCount++;
+    }
+  }
+  log.dim(
+    `  mask: ${inputMode} mode, ${subjectCount} subject px (${(subjectCount / (W * H) * 100).toFixed(1)}%)`
+  );
+  let connect = subject;
+  if (dilatePx > 0) {
+    const tmp = new Uint8Array(W * H);
+    for (let y = 0; y < H; y++) {
+      let run2 = 0;
+      for (let x = 0; x < W; x++) {
+        if (subject[y * W + x]) run2 = dilatePx;
+        else if (run2 > 0) run2--;
+        tmp[y * W + x] = run2 > 0 || subject[y * W + x] ? 1 : 0;
+      }
+      run2 = 0;
+      for (let x = W - 1; x >= 0; x--) {
+        if (subject[y * W + x]) run2 = dilatePx;
+        else if (run2 > 0) run2--;
+        if (run2 > 0) tmp[y * W + x] = 1;
+      }
+    }
+    const tmp2 = new Uint8Array(W * H);
+    for (let x = 0; x < W; x++) {
+      let run2 = 0;
+      for (let y = 0; y < H; y++) {
+        if (tmp[y * W + x]) run2 = dilatePx;
+        else if (run2 > 0) run2--;
+        tmp2[y * W + x] = run2 > 0 || tmp[y * W + x] ? 1 : 0;
+      }
+      run2 = 0;
+      for (let y = H - 1; y >= 0; y--) {
+        if (tmp[y * W + x]) run2 = dilatePx;
+        else if (run2 > 0) run2--;
+        if (run2 > 0) tmp2[y * W + x] = 1;
+      }
+    }
+    connect = tmp2;
+  }
+  const components = [];
+  let realSubjectPixels = 0;
+  scanComponents(
+    W,
+    H,
+    (idx) => connect[idx] !== 0,
+    (stats) => {
+      components.push({
+        minX: stats.minX,
+        minY: stats.minY,
+        maxX: stats.maxX,
+        maxY: stats.maxY,
+        pixels: stats.pixels,
+        subjectPixels: realSubjectPixels,
+        cx: 0,
+        cy: 0
+      });
+      realSubjectPixels = 0;
+    },
+    (idx) => {
+      if (subject[idx]) realSubjectPixels++;
+    }
+  );
+  const big = components.filter((comp) => comp.subjectPixels >= minPixels);
+  log.dim(
+    `  components: ${big.length} kept, ${components.length - big.length} discarded (< ${minPixels} px)`
+  );
+  if (big.length < names.length) {
+    log.warn(
+      `Only ${big.length} components \u2265 ${minPixels}px; expected ${names.length}. Lower --min-pixels or check the sheet.`
+    );
+  }
+  const heights = big.map((comp) => comp.maxY - comp.minY + 1).sort((a, b) => a - b);
+  const medianH = heights[Math.floor(heights.length / 2)] || 50;
+  const bandH = Math.max(20, medianH * 0.6);
+  for (const comp of big) {
+    comp.cx = (comp.minX + comp.maxX) / 2;
+    comp.cy = (comp.minY + comp.maxY) / 2;
+  }
+  big.sort((a, b) => a.cy - b.cy);
+  const bands = [];
+  for (const comp of big) {
+    const last = bands[bands.length - 1];
+    if (!last || comp.cy - last.maxCy > bandH) {
+      bands.push({ items: [comp], maxCy: comp.cy });
+    } else {
+      last.items.push(comp);
+      last.maxCy = Math.max(last.maxCy, comp.cy);
+    }
+  }
+  const sorted = [];
+  for (const band of bands) {
+    band.items.sort((a, b) => a.cx - b.cx);
+    sorted.push(...band.items);
+  }
+  const extractions = [];
+  for (let i = 0; i < sorted.length; i++) {
+    const comp = sorted[i];
+    const name = i < names.length ? names[i] : `extra-${i - names.length}`;
+    const padX0 = Math.max(0, comp.minX - padding);
+    const padY0 = Math.max(0, comp.minY - padding);
+    const padX1 = Math.min(W, comp.maxX + padding + 1);
+    const padY1 = Math.min(H, comp.maxY + padding + 1);
+    const cropW = padX1 - padX0;
+    const cropH = padY1 - padY0;
+    if (cropW < 4 || cropH < 4) {
+      log.warn(`Skipping "${name}" \u2014 crop too small (${cropW}x${cropH}).`);
+      continue;
+    }
+    const out = new PNG2({ width: cropW, height: cropH });
+    for (let yo = 0; yo < cropH; yo++) {
+      const sy = padY0 + yo;
+      for (let xo = 0; xo < cropW; xo++) {
+        const sx = padX0 + xo;
+        const sIdx = (sy * W + sx) * 4;
+        const oIdx = (yo * cropW + xo) * 4;
+        const r = data[sIdx + 0];
+        const g = data[sIdx + 1];
+        const b = data[sIdx + 2];
+        const a = data[sIdx + 3];
+        out.data[oIdx + 0] = r;
+        out.data[oIdx + 1] = g;
+        out.data[oIdx + 2] = b;
+        if (inputMode === "alpha") {
+          out.data[oIdx + 3] = a;
+        } else {
+          const isWhite = r >= chroma && g >= chroma && b >= chroma;
+          out.data[oIdx + 3] = isWhite ? 0 : 255;
+        }
+      }
+    }
+    const outPath = path14.join(outDir, `${name}.png`);
+    await writePng(outPath, out);
+    const sidecar = {
+      name,
+      out: outPath,
+      sheet: { w: W, h: H },
+      sheetBBox: { x: padX0, y: padY0, w: cropW, h: cropH },
+      sheetBBoxNorm: {
+        x: +(padX0 / W).toFixed(3),
+        y: +(padY0 / H).toFixed(3),
+        w: +(cropW / W).toFixed(3),
+        h: +(cropH / H).toFixed(3)
+      },
+      cropDims: { w: cropW, h: cropH },
+      aspectRatio: +(cropW / cropH).toFixed(3),
+      componentPixels: comp.pixels
+    };
+    const { name: _n, out: _o, ...sidecarBody } = sidecar;
+    await fs14.writeFile(
+      outPath.replace(/\.png$/i, "") + ".bbox.json",
+      JSON.stringify(sidecarBody, null, 2)
+    );
+    extractions.push(sidecar);
+    log.success(
+      `${name}.png  ${cropW}x${cropH} (ar ${sidecar.aspectRatio}) at sheet ${padX0},${padY0}`
+    );
+  }
+  const debugPath = path14.join(outDir, "extract-debug.json");
+  await fs14.writeFile(
+    debugPath,
+    JSON.stringify(
+      {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        input,
+        sheet: { w: W, h: H },
+        mode: inputMode,
+        rawComponentCount: components.length,
+        filteredComponentCount: big.length,
+        bandH,
+        extractions: extractions.map((e) => ({
+          name: e.name,
+          sheetBBox: e.sheetBBox,
+          sheetBBoxNorm: e.sheetBBoxNorm,
+          ar: e.aspectRatio
+        }))
+      },
+      null,
+      2
+    )
+  );
+  const missing = names.filter((n) => !extractions.some((e) => e.name === n));
+  log.plain("");
+  log.success(`Extracted ${extractions.length} elements \u2192 ${outDir} (+ .bbox.json sidecars).`);
+  if (missing.length > 0) {
+    log.warn(`Missing: ${missing.join(", ")} \u2014 fewer components than names on the sheet.`);
+  }
+}
+function parseBox(raw, label) {
+  const parts = raw.split(",").map((part) => Number.parseInt(part.trim(), 10));
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+    fail(`Invalid ${label} box \u2014 expected x,y,w,h.`, { raw });
+  }
+  const [x, y, w, h] = parts;
+  if (w <= 0 || h <= 0) fail(`Invalid ${label} box dimensions.`, { raw });
+  return { x, y, w, h };
+}
+function parsePairs(raw) {
+  return raw.split(";").map((part) => part.trim()).filter(Boolean).map((part) => {
+    const pieces = part.split(":");
+    if (pieces.length !== 3 && pieces.length !== 4) {
+      fail(
+        "Invalid pair \u2014 expected name:cleanX,cleanY,w,h:annX,annY,w,h[:expectedComponents].",
+        { pair: part }
+      );
+    }
+    const [name, cleanRaw, annotatedRaw, expectedRaw] = pieces;
+    if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) fail("Invalid pair name.", { name });
+    const expectedComponents = expectedRaw === void 0 ? null : Number.parseInt(expectedRaw, 10);
+    if (expectedRaw !== void 0 && (!Number.isFinite(expectedComponents) || expectedComponents < 1)) {
+      fail("Invalid expected component count.", { name, expectedRaw });
+    }
+    return {
+      name,
+      cleanBox: parseBox(cleanRaw, `${name} clean`),
+      annotatedBox: parseBox(annotatedRaw, `${name} annotated`),
+      expectedComponents
+    };
+  });
+}
+function assertInside(box, image, label) {
+  if (box.x < 0 || box.y < 0 || box.x + box.w > image.width || box.y + box.h > image.height) {
+    fail(`${label} crop is outside the source image.`, {
+      box,
+      image: { w: image.width, h: image.height }
+    });
+  }
+}
+function edgeOpaqueFraction(png, alphaThresh = 40) {
+  const { width: w, height: h, data } = png;
+  const alphaAt = (x, y) => data[(y * w + x << 2) + 3];
+  let top = 0;
+  let bottom = 0;
+  let left = 0;
+  let right = 0;
+  for (let x = 0; x < w; x += 1) {
+    if (alphaAt(x, 0) > alphaThresh) top += 1;
+    if (alphaAt(x, h - 1) > alphaThresh) bottom += 1;
+  }
+  for (let y = 0; y < h; y += 1) {
+    if (alphaAt(0, y) > alphaThresh) left += 1;
+    if (alphaAt(w - 1, y) > alphaThresh) right += 1;
+  }
+  return { top: top / w, bottom: bottom / w, left: left / h, right: right / h };
+}
+function assertNotFlush(png, label, maxFrac) {
+  const edges = edgeOpaqueFraction(png);
+  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).`,
+      {
+        flushEdges: flush2.map(([edge, frac]) => ({ edge, opaqueFraction: Number(frac.toFixed(3)) })),
+        maxFraction: maxFrac
+      }
+    );
+  }
+}
+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) {
+  if (a === 0) return 0;
+  const greenStrength = g - Math.max(r, b);
+  const isGreen = g > r * 1.4 && g > b * 1.4 && greenStrength >= 50 && g >= 45;
+  if (isGreen) {
+    return Math.max(160, Math.min(255, Math.round(greenStrength / 180 * 255)));
+  }
+  return 0;
+}
+function convertGreenMask(annotatedCrop) {
+  const out = new PNG2({ width: annotatedCrop.width, height: annotatedCrop.height });
+  let filled = 0;
+  let minX = annotatedCrop.width;
+  let minY = annotatedCrop.height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < annotatedCrop.height; y += 1) {
+    for (let x = 0; x < annotatedCrop.width; x += 1) {
+      const idx = y * annotatedCrop.width + x << 2;
+      const alpha = greenAlpha(
+        annotatedCrop.data[idx],
+        annotatedCrop.data[idx + 1],
+        annotatedCrop.data[idx + 2],
+        annotatedCrop.data[idx + 3]
+      );
+      out.data[idx] = 255;
+      out.data[idx + 1] = 255;
+      out.data[idx + 2] = 255;
+      out.data[idx + 3] = alpha;
+      if (alpha > 0) {
+        filled += 1;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+  const coverage = filled / (annotatedCrop.width * annotatedCrop.height);
+  const bbox = filled > 0 ? {
+    x: minX / annotatedCrop.width,
+    y: minY / annotatedCrop.height,
+    w: (maxX - minX + 1) / annotatedCrop.width,
+    h: (maxY - minY + 1) / annotatedCrop.height
+  } : null;
+  return { png: out, coverage, filledPixels: filled, bbox };
+}
+function subjectBBox(image) {
+  let pixels = 0;
+  let minX = image.width;
+  let minY = image.height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const idx = y * image.width + x << 2;
+      if (!isSubjectPx(image.data, idx)) continue;
+      pixels += 1;
+      minX = Math.min(minX, x);
+      minY = Math.min(minY, y);
+      maxX = Math.max(maxX, x);
+      maxY = Math.max(maxY, y);
+    }
+  }
+  return pixels > 0 ? {
+    pixels,
+    x: minX / image.width,
+    y: minY / image.height,
+    w: (maxX - minX + 1) / image.width,
+    h: (maxY - minY + 1) / image.height
+  } : null;
+}
+function bboxDelta(a, b) {
+  if (!a || !b) return Infinity;
+  return Math.max(
+    Math.abs(a.x - b.x),
+    Math.abs(a.y - b.y),
+    Math.abs(a.w - b.w),
+    Math.abs(a.h - b.h)
+  );
+}
+function greenComponents(mask, minPixels) {
+  const components = [];
+  scanComponents(
+    mask.width,
+    mask.height,
+    (idx) => mask.data[(idx << 2) + 3] > 0,
+    (stats) => {
+      if (stats.pixels < minPixels) return;
+      components.push({
+        pixels: stats.pixels,
+        bbox: {
+          x: stats.minX / mask.width,
+          y: stats.minY / mask.height,
+          w: (stats.maxX - stats.minX + 1) / mask.width,
+          h: (stats.maxY - stats.minY + 1) / mask.height
+        }
+      });
+    }
+  );
+  return components;
+}
+function blendPixel(image, x, y, rgba) {
+  if (x < 0 || y < 0 || x >= image.width || y >= image.height) return;
+  const idx = y * image.width + x << 2;
+  const a = rgba[3] / 255;
+  image.data[idx] = Math.round(rgba[0] * a + image.data[idx] * (1 - a));
+  image.data[idx + 1] = Math.round(rgba[1] * a + image.data[idx + 1] * (1 - a));
+  image.data[idx + 2] = Math.round(rgba[2] * a + image.data[idx + 2] * (1 - a));
+  image.data[idx + 3] = Math.max(image.data[idx + 3], rgba[3]);
+}
+function makeOverlay(clean2, mask) {
+  const out = new PNG2({ width: clean2.width, height: clean2.height });
+  clean2.data.copy(out.data);
+  for (let y = 0; y < mask.height; y += 1) {
+    for (let x = 0; x < mask.width; x += 1) {
+      const idx = y * mask.width + x << 2;
+      const alpha = mask.data[idx + 3];
+      if (alpha > 0) blendPixel(out, x, y, [0, 255, 0, Math.min(190, alpha)]);
+    }
+  }
+  return out;
+}
+async function uiMasks(opts, log) {
+  const input = requireOpt(opts.input, "--in", "masks");
+  const outDir = requireOpt(opts.outDir, "--out-dir", "masks");
+  const pairs = parsePairs(requireOpt(opts.pairs, "--pairs", "masks"));
+  const minCoverage = opts.coverageMin ?? 0.01;
+  const maxCoverage = opts.coverageMax ?? 0.85;
+  const minComponentPixels = opts.componentMinPixels ?? 100;
+  const registrationTolerance = opts.registrationTolerance ?? 0.04;
+  const edgeFlushMax = opts.edgeFlushMax ?? 0.04;
+  const image = await loadPng(input);
+  await fs14.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 = [];
+  for (const pair of pairs) {
+    if (pair.cleanBox.w !== pair.annotatedBox.w || pair.cleanBox.h !== pair.annotatedBox.h) {
+      fail("Clean and annotated crop boxes must have identical dimensions.", pair);
+    }
+    assertInside(pair.cleanBox, image, `${pair.name} clean`);
+    assertInside(pair.annotatedBox, image, `${pair.name} annotated`);
+    const clean2 = cropPng(image, pair.cleanBox);
+    const annotated = cropPng(image, pair.annotatedBox);
+    assertNotFlush(clean2, `${pair.name} clean frame`, edgeFlushMax);
+    const cleanBBox = subjectBBox(clean2);
+    const annotatedBBox = subjectBBox(annotated);
+    const registrationDelta = bboxDelta(cleanBBox, annotatedBBox);
+    if (registrationDelta > registrationTolerance) {
+      fail("Annotated copy registration differs too much from the clean asset.", {
+        name: pair.name,
+        registrationDelta: Number(registrationDelta.toFixed(4)),
+        registrationTolerance,
+        cleanBBox,
+        annotatedBBox
+      });
+    }
+    const converted = convertGreenMask(annotated);
+    if (converted.coverage < minCoverage || converted.coverage > maxCoverage) {
+      fail("Green mask coverage outside the accepted range.", {
+        name: pair.name,
+        coverage: converted.coverage,
+        minCoverage,
+        maxCoverage
+      });
+    }
+    const components = greenComponents(converted.png, minComponentPixels);
+    if (pair.expectedComponents && components.length !== pair.expectedComponents) {
+      fail("Green mask component count mismatch.", {
+        name: pair.name,
+        expectedComponents: pair.expectedComponents,
+        actualComponents: components.length
+      });
+    }
+    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`);
+    await writePng(framePath, clean2);
+    await writePng(maskPath, converted.png);
+    await writePng(annotatedPath, annotated);
+    await writePng(overlayPath, overlay);
+    const meta = {
+      name: pair.name,
+      provenance: "clean asset + annotated duplicate green-key",
+      source: input,
+      // The DOM fill's channel box (FB) — duplicated from mask.bbox at the top
+      // level so the HUD skill reads it without digging into the mask object.
+      fillBox: converted.bbox,
+      clean: {
+        path: framePath,
+        crop: pair.cleanBox,
+        size: { w: clean2.width, h: clean2.height },
+        subjectBBox: cleanBBox
+      },
+      annotated: {
+        path: annotatedPath,
+        crop: pair.annotatedBox,
+        size: { w: annotated.width, h: annotated.height },
+        subjectBBox: annotatedBBox
+      },
+      registration: {
+        bboxDelta: Number(registrationDelta.toFixed(4)),
+        tolerance: registrationTolerance
+      },
+      mask: {
+        path: maskPath,
+        size: { w: converted.png.width, h: converted.png.height },
+        coverage: Number(converted.coverage.toFixed(4)),
+        filledPixels: converted.filledPixels,
+        bbox: converted.bbox,
+        components,
+        expectedComponents: pair.expectedComponents
+      },
+      overlay: overlayPath
+    };
+    await fs14.writeFile(metaPath, `${JSON.stringify(meta, null, 2)}
+`);
+    results.push(meta);
+    const fb = converted.bbox;
+    const fbText = fb ? ` fillBox ${[fb.x, fb.y, fb.w, fb.h].map((v) => Number(v.toFixed(4))).join(",")},` : "";
+    log.success(
+      `${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)}
+`);
+  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.");
+}
+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;
+var chromaOf = (r, g, b) => (Math.max(r, g, b) - Math.min(r, g, b)) / 255;
+var rgbDist = (a, r, g, b) => Math.hypot(a[0] - r, a[1] - g, a[2] - b);
+var newBucket = () => ({
+  n: 0,
+  r: 0,
+  g: 0,
+  b: 0,
+  minX: Infinity,
+  minY: Infinity,
+  maxX: -1,
+  maxY: -1
+});
+function addToBucket(bucket, r, g, b, x, y) {
+  bucket.n += 1;
+  bucket.r += r;
+  bucket.g += g;
+  bucket.b += b;
+  bucket.minX = Math.min(bucket.minX, x);
+  bucket.minY = Math.min(bucket.minY, y);
+  bucket.maxX = Math.max(bucket.maxX, x);
+  bucket.maxY = Math.max(bucket.maxY, y);
+}
+function summarizeBucket(bucket, total, box) {
+  if (bucket.n === 0) return null;
+  const r = bucket.r / bucket.n;
+  const g = bucket.g / bucket.n;
+  const b = bucket.b / bucket.n;
+  return {
+    hex: hexColor(r, g, b),
+    rgb: [Math.round(r), Math.round(g), Math.round(b)],
+    coverage: Number((bucket.n / total).toFixed(4)),
+    // bbox of these pixels, as fractions of the sampled box (the footprint)
+    bbox: {
+      x: Number((bucket.minX / box.w).toFixed(3)),
+      y: Number((bucket.minY / box.h).toFixed(3)),
+      w: Number(((bucket.maxX - bucket.minX + 1) / box.w).toFixed(3)),
+      h: Number(((bucket.maxY - bucket.minY + 1) / box.h).toFixed(3))
+    }
+  };
+}
+async function uiTextColor(opts, log) {
+  const input = requireOpt(opts.input, "--in", "text-color");
+  const box = parseBox(requireOpt(opts.box, "--box", "text-color"), "sample");
+  const quantize = opts.quantize ?? 12;
+  const inkDist = opts.inkDist ?? 60;
+  const minFrac = opts.minFrac ?? 4e-3;
+  const image = await loadPng(input);
+  if (box.x < 0 || box.y < 0 || box.x + box.w > image.width || box.y + box.h > image.height) {
+    fail("Box is outside the source image.", { box, image: { w: image.width, h: image.height } });
+  }
+  const region = cropPng(image, box);
+  if (opts.cropPath) await writePng(opts.cropPath, region);
+  const total = box.w * box.h;
+  const q = Math.max(1, quantize);
+  const hist = /* @__PURE__ */ new Map();
+  for (let i = 0; i < region.data.length; i += 4) {
+    const r = region.data[i];
+    const g = region.data[i + 1];
+    const b = region.data[i + 2];
+    const key = `${Math.round(r / q) * q},${Math.round(g / q) * q},${Math.round(b / q) * q}`;
+    let e = hist.get(key);
+    if (!e) hist.set(key, e = { n: 0, r: 0, g: 0, b: 0 });
+    e.n += 1;
+    e.r += r;
+    e.g += g;
+    e.b += b;
+  }
+  const dominant = [...hist.values()].sort((a, b) => b.n - a.n).slice(0, 10).map((e) => ({
+    hex: hexColor(e.r / e.n, e.g / e.n, e.b / e.n),
+    rgb: [Math.round(e.r / e.n), Math.round(e.g / e.n), Math.round(e.b / e.n)],
+    coverage: Number((e.n / total).toFixed(4))
+  }));
+  const background = dominant[0];
+  const bg = background.rgb;
+  const ink = newBucket();
+  const dark = newBucket();
+  const light = newBucket();
+  const chromatic = newBucket();
+  for (let y = 0; y < region.height; y += 1) {
+    for (let x = 0; x < region.width; x += 1) {
+      const i = y * region.width + x << 2;
+      const r = region.data[i];
+      const g = region.data[i + 1];
+      const b = region.data[i + 2];
+      if (rgbDist(bg, r, g, b) < inkDist) continue;
+      addToBucket(ink, r, g, b, x, y);
+      const L = luminance(r, g, b);
+      const C = chromaOf(r, g, b);
+      if (C > 0.22) addToBucket(chromatic, r, g, b, x, y);
+      else if (L < 0.4) addToBucket(dark, r, g, b, x, y);
+      else if (L > 0.62) addToBucket(light, r, g, b, x, y);
+    }
+  }
+  const pick = (bucket) => {
+    const s = summarizeBucket(bucket, total, box);
+    return s && s.coverage >= minFrac ? s : null;
+  };
+  const result = {
+    status: "ok",
+    source: input,
+    box,
+    background,
+    dominant,
+    ink: pick(ink),
+    candidates: {
+      darkInk: pick(dark),
+      lightInk: pick(light),
+      chromaticInk: pick(chromatic)
+    },
+    params: { quantize: q, inkDist, minFrac }
+  };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  if (opts.out) await fs14.writeFile(opts.out, `${JSON.stringify(result, null, 2)}
+`);
+  if (opts.cropPath) log.dim(`  crop \u2192 ${opts.cropPath}`);
+}
+async function uiTrim(opts, log) {
+  const input = requireOpt(opts.input, "--in", "trim");
+  const outPath = opts.out ?? input;
+  if (/^https?:\/\//i.test(outPath)) {
+    fail("--in is a URL \u2014 pass --out <png> to say where the trimmed copy goes.");
+  }
+  const png = await loadPng(input);
+  const bbox = alphaBBoxPx(png);
+  if (!bbox) fail("Image is fully transparent \u2014 nothing to trim.", { input });
+  const cropBox = {
+    x: bbox.minX,
+    y: bbox.minY,
+    w: bbox.maxX - bbox.minX + 1,
+    h: bbox.maxY - bbox.minY + 1
+  };
+  const trimmed = cropPng(png, cropBox);
+  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));
+  log.success(
+    `Trimmed ${png.width}x${png.height} \u2192 ${trimmed.width}x${trimmed.height} (${outPath}).`
+  );
+  process.stdout.write(
+    `${JSON.stringify({
+      out: outPath,
+      width: trimmed.width,
+      height: trimmed.height,
+      aspectRatio: sidecar.aspectRatio,
+      outerBBox: sidecar.outerBBox,
+      innerBBox: sidecar.innerBBox,
+      sidecar: sidecarPath
+    })}
+`
+  );
+}
+
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);
 var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize, and publish 3D games.
@@ -2783,6 +3796,9 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   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 wait <id>                    Attach to a generation enqueued with --no-wait and
+                                     print its asset URL(s) when it finishes. Safe to
+                                     re-run \u2014 it never creates a new generation.
   genex controller <type> [--force]  Install a physics controller
                                      (character|car|drone|networked-physics)
                                      into src/controllers (+ assets into public/assets).
@@ -2793,14 +3809,31 @@ ${c.bold("Usage")}
   genex explore ["<query>"] [options] Search the curated community gallery \u2014 proven
                                      Three.js systems you can clone or borrow parts
                                      from. No query lists the whole catalog.
+  genex ui <tool> [options]          Local pixel toolbox for generated UI art \u2014
+                                     extract | masks | text-color | trim. Pure
+                                     local PNG work (no API), reads a file or URL.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --duration <sec>     (sfx, video) target clip length in seconds.
   --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
   --aspect <ratio>     (image) aspect preset (e.g. square, landscape, portrait).
+  --quality <q>        (image) quality preset: low | medium | high.
+  --candidates <n>     (image) generate 2-4 variants in ONE call and print every
+                       URL \u2014 pick the best instead of re-rolling. Needs
+                       --quality or --size; not with --remove-bg/--transparent.
+  --size <WxH>         (image) exact output size in px (e.g. 2560x1440).
+  --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.
+  --remove-bg          (image) chain ML background removal after the gen/edit.
+  --bg-mode <mode>     (image) background-removal model: sprite | glyph | sheet.
   --loop               (video) generate a seamless loop.
-  --no-wait            Enqueue only; don't block waiting for the asset.
+  --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.
+  --no-wait            Enqueue only; don't block waiting for the asset. Prints
+                       the id that "genex wait <id>" picks the result up with.
   --api-url <url>      Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
@@ -2851,6 +3884,8 @@ ${c.bold("Options for `explore`")}
   --api-url <url>      Override the API base URL.
                        (No query at all lists the entire curated catalog.)
 
+${UI_USAGE}
+
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -2877,8 +3912,12 @@ ${c.bold("Examples")}
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
   genex image "retro arcade poster art" --aspect portrait
-  genex image "neon graffiti tag, spray-paint style" --transparent
-  genex video "swirling neon plasma, seamless loop" --loop
+  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 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
   genex controller character
   genex controller networked-physics
   genex explore "grass"
@@ -2906,6 +3945,24 @@ function parseArgs(argv) {
     "--timeout",
     "--duration",
     "--aspect",
+    "--quality",
+    "--candidates",
+    "--size",
+    "--edit",
+    "--clean",
+    "--bg-mode",
+    "--frame",
+    "--first-frame",
+    "--last-frame",
+    // `genex ui` string flags (the numeric ones come from UI_NUMBER_FLAGS).
+    "--in",
+    "--out-dir",
+    "--names",
+    "--pairs",
+    "--box",
+    "--out",
+    "--crop",
+    ...Object.keys(UI_NUMBER_FLAGS),
     "--source-repo-url",
     "--source-author",
     "--license",
@@ -2946,6 +4003,9 @@ function parseArgs(argv) {
       case "--loop":
         parsed.options.loop = true;
         break;
+      case "--remove-bg":
+        parsed.options.removeBackground = true;
+        break;
       case "--force":
         parsed.options.force = true;
         break;
@@ -2997,6 +4057,15 @@ function parseArgs(argv) {
   return parsed;
 }
 function applyValueFlag(options, flag, value) {
+  const uiNumKey = UI_NUMBER_FLAGS[flag];
+  if (uiNumKey) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0) {
+      throw new Error(`Invalid ${flag} value: ${value}`);
+    }
+    options[uiNumKey] = n;
+    return;
+  }
   switch (flag) {
     case "--dir":
       options.dir = value;
@@ -3065,6 +4134,73 @@ function applyValueFlag(options, flag, value) {
     case "--aspect":
       options.aspect = value;
       break;
+    case "--quality":
+      if (!["low", "medium", "high"].includes(value)) {
+        throw new Error(`Invalid --quality value: ${value} (expected low|medium|high)`);
+      }
+      options.quality = value;
+      break;
+    case "--candidates": {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1 || n > 4) {
+        throw new Error(`Invalid --candidates value: ${value} (expected an integer 1-4)`);
+      }
+      options.candidates = n;
+      break;
+    }
+    case "--size": {
+      const m = /^(\d+)\s*[x×]\s*(\d+)$/i.exec(value.trim());
+      const w = m ? Number(m[1]) : NaN;
+      const h = m ? Number(m[2]) : NaN;
+      if (!m || !Number.isInteger(w) || !Number.isInteger(h) || w <= 0 || h <= 0) {
+        throw new Error(`Invalid --size value: ${value} (expected WxH, e.g. 2560x1440)`);
+      }
+      options.width = w;
+      options.height = h;
+      break;
+    }
+    case "--edit":
+      options.editUrl = value;
+      break;
+    case "--clean":
+      options.cleanUrl = value;
+      break;
+    case "--bg-mode":
+      if (!["sprite", "glyph", "sheet"].includes(value)) {
+        throw new Error(`Invalid --bg-mode value: ${value} (expected sprite|glyph|sheet)`);
+      }
+      options.bgMode = value;
+      break;
+    case "--frame":
+      options.frameUrl = value;
+      break;
+    case "--first-frame":
+      options.firstFrameUrl = value;
+      break;
+    case "--last-frame":
+      options.lastFrameUrl = value;
+      break;
+    case "--in":
+      options.input = value;
+      break;
+    case "--out-dir":
+      options.outDir = value;
+      break;
+    case "--names":
+      options.names = value;
+      break;
+    case "--pairs":
+      options.pairs = value;
+      break;
+    case "--box":
+      options.box = value;
+      break;
+    case "--out":
+      options.out = value;
+      break;
+    case "--crop":
+      options.cropPath = value;
+      break;
   }
 }
 async function main() {
@@ -3135,6 +4271,12 @@ async function main() {
       case "explore":
         await runExplore({ ...parsed.options, query: parsed.options.name });
         break;
+      case "ui":
+        await runUi({ ...parsed.options, sub: parsed.options.name });
+        break;
+      case "wait":
+        await runWait({ ...parsed.options, id: parsed.options.name });
+        break;
       default:
         log.error(`Unknown command: ${parsed.command}`);
         log.plain(`Run ${c.cyan("genex --help")} for usage.`);