@genex-ai/cli-demo 0.51.0-dev.98 → 0.51.0-dev.99

package/dist/index.js

@@ -3183,7 +3183,8 @@ var UI_NUMBER_FLAGS = {
   "--edge-flush-max": "edgeFlushMax",
   "--quantize": "quantize",
   "--ink-dist": "inkDist",
-  "--min-frac": "minFrac"
+  "--min-frac": "minFrac",
+  "--seam-tolerance": "seamTolerance"
 };
 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
@@ -3199,7 +3200,10 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        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.`;
+                       --in), print real dims + refresh the .bbox.json sidecar.
+  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]`;
 async function runUi(opts) {
   const log = createLogger({ quiet: opts.quiet });
   try {
@@ -3216,9 +3220,12 @@ async function runUi(opts) {
       case "trim":
         await uiTrim(opts, log);
         return;
+      case "seams":
+        await uiSeams(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."
+          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim, seams.` : "Missing ui tool. Tools: extract, masks, text-color, trim, seams."
         );
         log.plain(UI_USAGE);
         process.exitCode = 1;
@@ -3925,6 +3932,78 @@ async function uiTrim(opts, log) {
 `
   );
 }
+async function uiSeams(opts, log) {
+  const input = requireOpt(opts.input, "--in", "seams");
+  const tol = opts.seamTolerance ?? 3;
+  const png = await loadPng(input);
+  const { width: w, height: h, data } = png;
+  if (w < 4 || h < 4) fail("Image is too small to test for tiling.", { width: w, height: h });
+  const chan = (x, y, ch) => data[(y * w + x) * 4 + ch] ?? 0;
+  const colDiff = (a, b) => {
+    let s = 0;
+    for (let y = 0; y < h; y++) {
+      s += Math.abs(chan(a, y, 0) - chan(b, y, 0));
+      s += Math.abs(chan(a, y, 1) - chan(b, y, 1));
+      s += Math.abs(chan(a, y, 2) - chan(b, y, 2));
+    }
+    return s / (h * 3);
+  };
+  const rowDiff = (a, b) => {
+    let s = 0;
+    for (let x = 0; x < w; x++) {
+      s += Math.abs(chan(x, a, 0) - chan(x, b, 0));
+      s += Math.abs(chan(x, a, 1) - chan(x, b, 1));
+      s += Math.abs(chan(x, a, 2) - chan(x, b, 2));
+    }
+    return s / (w * 3);
+  };
+  const seamH = colDiff(0, w - 1);
+  const seamV = rowDiff(0, h - 1);
+  const stepX = Math.max(1, Math.floor(w / 64));
+  const stepY = Math.max(1, Math.floor(h / 64));
+  let baseH = 0;
+  let nH = 0;
+  for (let x = 1; x < w - 1; x += stepX) {
+    baseH += colDiff(x, x + 1);
+    nH++;
+  }
+  let baseV = 0;
+  let nV = 0;
+  for (let y = 1; y < h - 1; y += stepY) {
+    baseV += rowDiff(y, y + 1);
+    nV++;
+  }
+  baseH = Math.max(baseH / Math.max(1, nH), 1e-6);
+  baseV = Math.max(baseV / Math.max(1, nV), 1e-6);
+  const round = (n) => Math.round(n * 100) / 100;
+  const ratioH = round(seamH / baseH);
+  const ratioV = round(seamV / baseV);
+  const worst = Math.max(ratioH, ratioV);
+  const axis = ratioH >= ratioV ? "horizontal" : "vertical";
+  const seamless = worst <= tol;
+  const name = input.split("/").pop() ?? input;
+  process.stdout.write(
+    `${JSON.stringify({
+      input,
+      width: w,
+      height: h,
+      ratioHorizontal: ratioH,
+      ratioVertical: ratioV,
+      worstRatio: worst,
+      worstAxis: axis,
+      tolerance: tol,
+      seamless
+    })}
+`
+  );
+  if (seamless) {
+    log.success(`${name}: tiles cleanly \u2014 worst seam ${worst}\xD7 the texture's own detail (\u2264 ${tol}\xD7).`);
+    return;
+  }
+  fail(
+    `Visible ${axis} tiling seam in ${name}: the tile boundary jumps ${worst}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable, or lower the mesh's UV repeat so the seam falls off-camera.`
+  );
+}
 
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.51.0-dev.98",
+  "version": "0.51.0-dev.99",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -114,6 +114,24 @@ The test: "is this fixed identity artwork, or should runtime code own it?"
 Baking a runtime value into a sprite is a failure; stripping a carved identity
 label flattens the art.
 
+## Icons & mechanics must match the game — diff before Stage 2
+
+Words are only half of it. Every ICON, slot, gauge, and pictogram in the mockup
+implies a MECHANIC: a grenade icon promises grenades, three ability slots
+promise three abilities, an armor bar promises armor. Before Stage 2, walk each
+one against the game contract — the mechanics the code actually has (or that you
+are committing to build):
+
+- **Backed by a real mechanic** → keep it and wire it to that state.
+- **No backing mechanic** → it is a promise the player will notice is empty.
+  CUT it (prompt Stage 2, or a region re-edit, to omit that icon/slot) OR add
+  the mechanic to the game. Shipping a depicted control the game can't do — a
+  grenade slot on a rifle-only HUD, an armor bar with no armor, a minimap over
+  no map — is a failure, and "the model drew it so I kept it" is how it happens.
+
+The mockup (and any concept frame) anchors STYLE; the game contract owns WHAT
+EXISTS. When the picture and the mechanics disagree, the mechanics win.
+
 ## The pipeline
 
 Each step is one command; every `<...-url>` is the R2 URL the previous command

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

@@ -129,6 +129,18 @@ Gotchas (all bite in practice):
   moving or skinned target, use a small `PlaneGeometry` quad offset along the normal
   (`hit.point + n * 0.01`, `quad.lookAt(hit.point.clone().add(n))`) instead.
 
+### Impact marks (bullet holes, scorch, blood) — spawn on the hit, not a keypress
+
+A game that shoots, throws, or explodes and leaves NO mark on what it hits reads
+as unfinished — and it's the same recipe, driven by the weapon's raycast you
+already have. Generate ONE small `--transparent` bullet-hole / scorch / impact
+image, then on each confirmed **world** hit place a decal at `hit.point` with
+`hit.face.normal` (exactly the `spray()` body above), capped in a FIFO ring
+(~30–50) reusing one shared material. On enemy/skinned hits skip the decal and
+use the quad fallback or a hit-spark VFX instead. Impact marks are a first-class
+generated surface for any weapon/collision game — inventory them up front with
+the rest of your art, don't discover the bare walls at the end.
+
 ## Multiplayer
 
 The asset URL is public, permanent, and CORS-open, so it is safe to broadcast the

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

@@ -67,6 +67,24 @@ map.repeat.set(64, 64);
 scene.add(ground);
 ```
 
+## Verify it actually tiles — don't eyeball it
+
+A texture that isn't truly seamless draws a repeating seam grid the moment
+`repeat` is raised — the single most common "asset-flip" tell, and `--terrain`
+asks for seamless but does not guarantee it. So measure the seam, don't guess:
+
+```bash
+npx genex ui seams --in <texture-url>     # a local .png works too
+```
+
+It compares the texture's opposite edges against its own interior detail and
+prints a ratio + verdict (`seamless: false` and a nonzero exit on a visible
+seam). A fail is a real defect — fix it in this order: **regenerate** (add
+"seamless tiling, no visible edges" to the prompt, or `--terrain`), then **lower
+`repeat`** so any residual seam falls off-camera. Run this on every tiled
+floor/wall texture before you call the scene done — a large flat surface with a
+high `repeat` and an unchecked texture is exactly how seams reach the player.
+
 ## Publish checklist
 
 - Load it from the **URL** the command printed — absolute and permanent, so it resolves
@@ -92,6 +110,8 @@ scene.add(ground);
 - **"Email not verified" (`email_verification_required`)** — generation credits
   unlock after the account's email is verified. Give the user the verify link the
   CLI printed, wait for them to confirm, then re-run the command.
-- **Visible tiling seams** — use `--terrain` (tuned for seamless edges), lower the
-  `repeat`, or blend two textures. Perfect seamlessness is a known v1 limitation.
+- **Visible tiling seams** — measure first (`npx genex ui seams --in <url>`): a
+  high ratio is a defect to fix, not a limitation to accept. Regenerate with
+  `--terrain` / a "seamless tiling" prompt, lower the `repeat`, or blend two
+  textures until the check passes.
 - **Colors look washed/dark** — ensure `map.colorSpace = THREE.SRGBColorSpace`.

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -195,6 +195,48 @@ edits scattered through the code:
    HUD state come from `$genex-threejs-multiplayer`; render what the SDK
    reports, don't guess at it.
 
+## Escape must pause the game — not shrink the window
+
+For a game that captures the mouse (first-person or pointer-lock aim — see the
+pointer bucket in `$genex-threejs-camera-direction`), pressing Escape does two
+**browser-reserved** things you CANNOT stop with `preventDefault`: it exits
+fullscreen and releases pointer lock, and the player sees the window "shrink".
+The real fix is the **Keyboard Lock API**, which routes Escape to your code
+instead — Chromium only, and only in fullscreen. Enter fullscreen on a gesture
+(the Deploy/Resume click), capture Escape, and own the pause:
+
+```ts
+// call ONLY from a user gesture (the Deploy click, the Resume click) — never at boot
+async function enterImmersive(): Promise<void> {
+  try {
+    if (!document.fullscreenElement)
+      await document.documentElement.requestFullscreen({ navigationUI: "hide" });
+  } catch { /* sandboxed iframe or no gesture — the pointer-lock path below still pauses */ }
+  // Chromium + fullscreen only: deliver Escape to us instead of exiting fullscreen.
+  try {
+    await (navigator as unknown as { keyboard?: { lock?: (k: string[]) => Promise<void> } })
+      .keyboard?.lock?.(["Escape"]);
+  } catch { /* Keyboard Lock unsupported — fine */ }
+}
+
+document.addEventListener("keydown", (e) => {
+  if (e.code !== "Escape") return;
+  e.preventDefault();                 // stops any *other* default; the reserved ones the lock handles
+  if (phase === "playing") { document.exitPointerLock?.(); setPhase("paused"); } // free cursor for the menu
+  else if (phase === "paused") { void enterImmersive(); canvas.requestPointerLock?.(); } // Esc resumes
+});
+```
+
+- **Degradation is built in.** Where Keyboard Lock is absent (Safari, Firefox) or
+  the game isn't fullscreen, the browser still releases pointer lock on Escape —
+  so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
+  unlocked while `playing`, `setPhase("paused")`). Escape then always pauses; it
+  only *also* drops fullscreen on browsers without the lock — unavoidable there.
+- **Only for immersive/pointer-lock games.** A top-down or menu-driven game never
+  captures the mouse and has no window to shrink — skip all of this.
+- **Dashboard embed:** full coverage needs the game iframe to permit keyboard
+  lock; standalone play (`<slug>.genex.technology`) works today regardless.
+
 ## The loader
 
 The loader is the first thing every player sees — a bare "Loading… 3/5" over