@genex-ai/cli-demo 1.16.0-dev.586 → 1.17.0-dev.588

package/dist/index.js

@@ -730,7 +730,7 @@ Important note: put soul into your creations, with many details and love. Aim to
 6. Generated UI art is a tool you reach for, not a pipeline you owe. A restrained interface built in clean CSS is a finished, legitimate HUD \u2014 not a placeholder. Reach for the sprite lane (\`genex-ai-hud\`) when the game's own style genuinely wants drawn chrome \u2014 ornate, painterly, comic, hand-made \u2014 or when the player asks for HUD art. Generating ONE element you decided the game needs \u2014 a frame, a mask, an icon, a wordmark, a menu backdrop, a menu video \u2014 is a normal use of these tools, never a half-run pipeline. There is NO global game-concept image and no UI plan recited in chat: the art direction lives in the game's brief in words. A lane's own concept step survives only where the player is choosing a concrete thing (a character's candidates). Whatever you do generate, run its quality steps in full \u2014 extraction, masks, wiring, \`npx genex ui audit\`.
 7. Never draw a rectangular backing plate behind bars, digits, or icons \u2014 in sprites or CSS. Ornament lives on the widget's own silhouette; a truly needed shaped plate comes from \`npx genex ui plate\`.
 8. Never park ready work behind a question, and never stall on an unanswered one \u2014 decide, state the decision in chat, record it, keep building.
-9. Before any publish and before ending a session: run \`npx genex wait\` on every generation you enqueued and wire in what landed \u2014 never park landed assets. Fonts the brief names are LOADED for real, Escape pauses, the loader shows something of the game rather than a black screen, and the player wears the game's own generated character (or DESIGN.md records why it doesn't).
+9. Before any publish and before ending a session: run \`npx genex wait\` on every generation you enqueued and wire in what landed \u2014 never park landed assets. Fonts the brief names are LOADED for real, Escape pauses, the loader shows something of the game rather than a black screen (the renderer draws before any \`await waitForPlayer()\` \u2014 identity takes seconds on a hosted page), and the player wears the game's own generated character (or DESIGN.md records why it doesn't).
 10. The player's body is the game's own generated character (\`npx genex character "<look>"\` \u2192 \`npx genex controller character --character <id>\`), enqueued with your first art actions, not after them. It applies wherever a human body appears on screen \u2014 first-person included, the moment remotes, a look-down body, a shadow, or a menu portrait shows one. Games whose player is not a person (car, ship, RTS cursor, board) generate that object with \`npx genex model\` instead, or build it procedurally \u2014 held to law 22's bar like everything else the player looks at. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
 11. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification. Local-test evidence proves visuals and controls ONLY \u2014 label it that way when you show the player, and never work around the draft sign-in gate any other way.
 12. Treat every \`genex\` warning line \u2014 preflight, \`ui audit\`, \`wait\` nudges \u2014 as work, not noise.
@@ -5856,6 +5856,101 @@ function splitArgs(text) {
   return out;
 }
 var lineOf = (content, index) => content.slice(0, index).split("\n").length;
+function blankComments(raw) {
+  return raw.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:])\/\/[^\n]*/gm, (m, p1) => p1 + " ".repeat(m.length - p1.length));
+}
+var IDENTITY_AWAIT = /\bawait\s+(waitForPlayer|waitForAuth)\s*\(/;
+var RENDERER_CTOR = /\bnew\s+(?:THREE\.)?(?:WebGLRenderer|WebGPURenderer)\s*\(/;
+var INIT_EMBED_CALL = /\binitEmbed\s*\(/;
+async function detectEmbedBoot(cwd = process.cwd()) {
+  const found = { awaitsIdentity: [], callsInitEmbed: false, rendererAfterAwait: [] };
+  const srcDir = path14.join(cwd, "src");
+  let entries;
+  try {
+    entries = await fs15.readdir(srcDir, { recursive: true });
+  } catch {
+    return found;
+  }
+  for (const nativeRel of entries) {
+    if (nativeRel.includes("node_modules")) continue;
+    if (nativeRel.split(path14.sep)[0] === "controllers") continue;
+    if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(nativeRel)) continue;
+    const raw = await fs15.readFile(path14.join(srcDir, nativeRel), "utf8").catch(() => "");
+    if (!raw) continue;
+    const rel = nativeRel.split(path14.sep).join("/");
+    const content = blankComments(raw);
+    if (INIT_EMBED_CALL.test(content)) found.callsInitEmbed = true;
+    const awaits = [];
+    const awaitRe = new RegExp(IDENTITY_AWAIT.source, "g");
+    let m;
+    while (m = awaitRe.exec(content)) {
+      awaits.push({ index: m.index, name: m[1], flowEnd: enclosingFlowEnd(content, m.index) });
+      found.awaitsIdentity.push({
+        where: `${rel}:${lineOf(content, m.index)}`,
+        detail: `${m[1]}()`
+      });
+    }
+    if (awaits.length === 0) continue;
+    const rendererRe = new RegExp(RENDERER_CTOR.source, "g");
+    while (m = rendererRe.exec(content)) {
+      const at = m.index;
+      const blocking = awaits.find((a) => a.index < at && at < a.flowEnd);
+      if (!blocking) continue;
+      found.rendererAfterAwait.push({
+        where: `${rel}:${lineOf(content, at)}`,
+        detail: `\`await ${blocking.name}()\` (line ${lineOf(content, blocking.index)})`
+      });
+    }
+  }
+  return found;
+}
+var CONTROL_HEADS = /* @__PURE__ */ new Set(["if", "for", "while", "switch", "catch", "with", "await"]);
+function isFunctionBrace(tail) {
+  const t = tail.trimEnd();
+  if (t.endsWith("=>")) return true;
+  if (!t.endsWith(")")) return false;
+  let depth = 0;
+  let i = t.length - 1;
+  for (; i >= 0; i--) {
+    const ch = t[i];
+    if (ch === ")") depth++;
+    else if (ch === "(" && --depth === 0) break;
+  }
+  if (i < 0) return false;
+  const head = /([A-Za-z_$][\w$]*)\s*$/.exec(t.slice(0, i))?.[1];
+  return head !== void 0 && !CONTROL_HEADS.has(head);
+}
+function enclosingFlowEnd(content, index) {
+  const stack = [];
+  let boundary = 0;
+  for (let i = 0; i < index; i++) {
+    const ch = content[i];
+    if (ch === "{") {
+      stack.push({ fn: isFunctionBrace(content.slice(boundary, i)) });
+      boundary = i + 1;
+    } else if (ch === "}") {
+      stack.pop();
+      boundary = i + 1;
+    } else if (ch === ";") {
+      boundary = i + 1;
+    }
+  }
+  let fnAt = -1;
+  for (let s = stack.length - 1; s >= 0; s--) {
+    if (stack[s].fn) {
+      fnAt = s;
+      break;
+    }
+  }
+  if (fnAt === -1) return content.length;
+  let depth = stack.length - fnAt;
+  for (let i = index; i < content.length; i++) {
+    const ch = content[i];
+    if (ch === "{") depth++;
+    else if (ch === "}" && --depth === 0) return i;
+  }
+  return content.length;
+}
 var DEPTH_RATIO_LIMIT = 1e6;
 async function detectSurfaceScan(cwd = process.cwd()) {
   const found = {
@@ -5879,7 +5974,7 @@ async function detectSurfaceScan(cwd = process.cwd()) {
     const raw = await fs15.readFile(path14.join(srcDir, nativeRel), "utf8").catch(() => "");
     if (!raw) continue;
     const rel = nativeRel.split(path14.sep).join("/");
-    const content = raw.replace(/\/\*[\s\S]*?\*\//g, (m2) => m2.replace(/[^\n]/g, " ")).replace(/(^|[^:])\/\/[^\n]*/gm, (m2, p1) => p1 + " ".repeat(m2.length - p1.length));
+    const content = blankComments(raw);
     const repeatRe = /\.repeat\.set\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
     let m;
     while (m = repeatRe.exec(content)) {
@@ -6016,7 +6111,8 @@ async function detectFeatures(log, cwd = process.cwd()) {
     gameStateUsed: await detectGameStateUsage(cwd),
     mobileControls: await detectMobileControls(cwd),
     surfaces: await detectSurfaceScan(cwd),
-    generations: await detectGenerationAudit(cwd)
+    generations: await detectGenerationAudit(cwd),
+    embedBoot: await detectEmbedBoot(cwd)
   };
 }
 function advisoryNudges(log, d) {
@@ -6035,9 +6131,24 @@ function advisoryNudges(log, d) {
       "package.json declares genex.matchmaking but @genex-ai/multiplayer is not installed \u2014 matchmaking cannot work. Install the SDK and use matchmake() (see genex-threejs-multiplayer)."
     );
   }
+  embedBootNudges(log, d);
   surfaceNudges(log, d.surfaces);
   generationNudges(log, d.generations);
 }
+function embedBootNudges(log, d) {
+  const boot = d.embedBoot;
+  if (d.embedSdkVersion && boot.awaitsIdentity.length > 0 && !boot.callsInitEmbed) {
+    const list = boot.awaitsIdentity.map((a) => `\`${a.detail}\` at ${a.where}`).join(", ");
+    log.warn(
+      `This game awaits ${list} but never calls \`initEmbed(\u2026)\`, so identity never resolves and the page stays black for every player. \`initEmbed({ slug, apiUrl, dashboardOrigins })\` from \`src/genex.config.ts\` is the first statement of the boot (genex-threejs-embed-auth).`
+    );
+  }
+  for (const r of boot.rendererAfterAwait) {
+    log.warn(
+      `${r.where} creates the renderer after ${r.detail}. Draw first, await identity where you need the name: on a hosted page identity takes seconds and the player sees black until then.`
+    );
+  }
+}
 function generationNudges(log, g) {
   const describe = (refs) => refs.map((r) => `${r.kind} ${r.id} ("${r.prompt.slice(0, 48)}")`).join("; ");
   if (g.unpicked.length) {
@@ -6694,6 +6805,36 @@ function solveMagentaGlass(source) {
   return { ...base, png: out, ok: true };
 }
 
+// src/lib/generation-failure.ts
+var BILLING_ERROR_MARKERS = [
+  /"code"\s*:\s*2010\b/,
+  /not enough credit/i,
+  /returned HTTP 402\b/,
+  /failed:\s*402\b/,
+  /insufficient funds/i
+];
+function isProviderBillingError(error) {
+  if (!error) return false;
+  return BILLING_ERROR_MARKERS.some((re) => re.test(error));
+}
+var RAW_ERROR_MAX_CHARS = 120;
+function oneLineError(error, max = RAW_ERROR_MAX_CHARS) {
+  const flat = error.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+function describeGenerationFailure(kind, error) {
+  if (!isProviderBillingError(error)) {
+    return { billing: false, lines: error ? [c.red(error)] : [] };
+  }
+  return {
+    billing: true,
+    lines: [
+      `${c.red("\u2717")} The ${kind} provider is out of credit on this stand \u2014 not your prompt and not your Genex credits (auto-refunded). Do not re-generate: fall back to procedural/VRM for this asset and tell the player in one plain line.`,
+      c.dim(oneLineError(error))
+    ]
+  };
+}
+
 // src/lib/download-assets.ts
 import fs16 from "fs/promises";
 import path15 from "path";
@@ -6752,6 +6893,7 @@ function localDeliveryFor(mode, opts, prompt) {
 }
 
 // src/lib/lanes.ts
+var LANE_CREDITS = /* @__PURE__ */ new Set(["ok", "exhausted", "unknown"]);
 async function fetchLanes(apiUrl, token, timeoutMs = 4e3) {
   try {
     const res = await apiFetch(`${apiUrl}/api/generations/lanes`, {
@@ -6764,7 +6906,14 @@ async function fetchLanes(apiUrl, token, timeoutMs = 4e3) {
     return {
       lanes: body.lanes.filter(
         (l) => !!l && typeof l.kind === "string" && typeof l.provider === "string"
-      ),
+      ).map((l) => ({
+        kind: l.kind,
+        provider: l.provider,
+        mock: l.mock === true,
+        // A value this CLI does not know is dropped, not passed through: the
+        // doctor branches on the exact string.
+        ...typeof l.credit === "string" && LANE_CREDITS.has(l.credit) ? { credit: l.credit } : {}
+      })),
       paused: body.paused === true
     };
   } catch {
@@ -7367,14 +7516,16 @@ async function waitForTerminalView(apiUrl, token, id, kind, onProgress = () => {
 }
 async function reportTerminal(kind, view, log, open = false, json = false, local) {
   if (view.status !== "completed") {
+    const failure = view.status === "failed" ? describeGenerationFailure(kind, view.error) : null;
     if (json) writeJson({ kind, id: view.id, status: view.status, error: view.error ?? null });
+    else if (failure?.billing) for (const line of failure.lines) log.plain(line);
     else log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
     if (view.status === "failed") {
       await recordTerminal(view.id, "failed");
-      if (kind === "video") {
+      if (!failure?.billing && kind === "video") {
         const failures = await countFailed("video");
         (failures >= 2 ? log.plain : log.dim)(videoFailureAdvice(failures));
-      } else {
+      } else if (!failure?.billing) {
         const advice = laneFailureAdvice(kind, await countOutcomes(kind));
         if (advice) log.plain(advice);
       }
@@ -8015,14 +8166,24 @@ async function runWaitAll(opts) {
     const mark = r.status === "done" ? c.green("\u2713") : r.status === "failed" ? c.red("\u2717") : c.yellow("\u2026");
     const label = r.status === "running" && typeof r.progress === "number" ? `running ${r.progress}%` : r.status;
     log.plain(`  ${mark} ${label.padEnd(12)} ${r.kind.padEnd(8)} ${r.id}  ${c.dim(`"${r.prompt.slice(0, 56)}"`)}`);
-    if (r.status === "failed" && r.error) log.plain(`      ${c.red(r.error)}`);
+    if (r.status === "failed" && r.error) {
+      for (const line of describeGenerationFailure(r.kind, r.error).lines) log.plain(`      ${line}`);
+    }
   }
   const count = (s) => rows.filter((r) => r.status === s).length;
+  const billingFailed = rows.filter(
+    (r) => r.status === "failed" && isProviderBillingError(r.error)
+  ).length;
   log.plain("");
   log.plain(
     `  ${count("done")} done \xB7 ${count("running")} running \xB7 ${count("queued")} queued \xB7 ${count("failed")} failed`
   );
-  if (count("failed") > 0) {
+  if (billingFailed > 0) {
+    log.dim(
+      `  ${count("failed")} failed \xB7 ${billingFailed} of them: provider out of credit \u2014 do not retry those lanes (every attempt fails the same way and refunds); fall back to procedural/VRM and tell the player in one plain line.`
+    );
+  }
+  if (count("failed") > billingFailed) {
     log.dim(
       "  A failed generation never produces its URL \u2014 anything wired to it silently won't appear. Re-plan or re-generate (that bills a new one)."
     );
@@ -17562,9 +17723,15 @@ var CONTROLLER_FILE_SETS = {
     // ONE sketch, with or without --character. The lane is a runtime decision
     // inside loadPlayerCharacter, never a code edit the agent has to remember
     // to make once the generated character lands.
+    // The first two lines are the boot ORDER, not controller wiring: a hosted
+    // build (2026-09-03) copied this sketch, opened main.ts with the identity
+    // await, made the renderer after it and never called initEmbed — black
+    // forever. Identity takes seconds on a hosted page; the frame comes first.
     sketch: [
+      `initEmbed({ slug: GENEX.slug, apiUrl: GENEX.apiUrl, dashboardOrigins: GENEX.dashboardOrigins }); // @genex-ai/embed-sdk + ./genex.config \u2014 FIRST statement, before any await`,
+      `const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias, ...depthRendererOptions() }); // draw a frame before awaiting identity`,
       `const physics = await PhysicsWorld.create();`,
-      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk`,
+      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk \u2014 only where the name/avatar is needed`,
       `const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl }); // this game's character, else the avatar fallback`,
       `const fit = capsuleFromModel(player.scene);`,
       `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...fit, position: { x: 0, y: 2, z: 0 } });`,
@@ -21214,6 +21381,7 @@ async function runDoctor(opts = {}) {
     if (row.fix) log.dim(`               ${row.fix}`);
   }
   let laneProblem = false;
+  let creditProblem = false;
   if (authState === "ok") {
     log.plain("");
     if (!lanes) {
@@ -21228,9 +21396,10 @@ async function runDoctor(opts = {}) {
       log.dim("               The daily spend breaker is tripped \u2014 nothing generates until it resets.");
     } else {
       const mocks = lanes.lanes.filter((l) => l.mock);
-      const mark = mocks.length > 0 ? c.yellow("!") : c.green("\u2713");
+      const exhausted = lanes.lanes.filter((l) => !l.mock && l.credit === "exhausted");
+      const mark = exhausted.length > 0 ? c.red("\u2717") : mocks.length > 0 ? c.yellow("!") : c.green("\u2713");
       log.plain(
-        `  ${mark} Lanes      ${lanes.lanes.length - mocks.length}/${lanes.lanes.length} live${mocks.length > 0 ? ` \xB7 ${mocks.length} in SAMPLE mode` : ""}`
+        `  ${mark} Lanes      ${lanes.lanes.length - mocks.length}/${lanes.lanes.length} live${mocks.length > 0 ? ` \xB7 ${mocks.length} in SAMPLE mode` : ""}${exhausted.length > 0 ? ` \xB7 ${exhausted.length} OUT OF CREDIT` : ""}`
       );
       for (const kind of laneOrder(lanes)) {
         const lane = lanes.lanes.find((l) => l.kind === kind);
@@ -21242,6 +21411,12 @@ async function runDoctor(opts = {}) {
           log.plain(
             `      ${c.yellow("!")} ${kind.padEnd(17)}${"SAMPLE (no provider key)".padEnd(26)}${cost}`
           );
+        } else if (lane.credit === "exhausted") {
+          creditProblem = true;
+          log.plain(
+            `      ${c.red("\u2717")} ${kind.padEnd(17)}${c.red(`live (${lane.provider}) \xB7 OUT OF CREDIT on this stand`)}${cost ? `  ${cost}` : ""}`
+          );
+          log.dim("        Generations on this lane fail and auto-refund; fall back to procedural/VRM.");
         } else {
           log.dim(`      \xB7 ${kind.padEnd(17)}${`live (${lane.provider})`.padEnd(26)}${cost}`);
         }
@@ -21254,7 +21429,7 @@ async function runDoctor(opts = {}) {
       }
     }
   }
-  const failed = rows.some((r) => r.bad) || laneProblem && mode !== "game";
+  const failed = rows.some((r) => r.bad) || laneProblem && mode !== "game" || creditProblem;
   log.plain("");
   if (failed) {
     log.plain(`  ${c.red("Something above needs fixing.")}`);

package/package.json

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

package/templates/controllers/character/follow-camera.ts

@@ -376,7 +376,22 @@ export class FollowCamera {
       if (this._aimState === "unlocked" && e.pointerType === "mouse" && e.button === 0) {
         this._requestLock();
       }
-      this._domElement.setPointerCapture(e.pointerId);
+      // Capture may be REFUSED, and a refusal must not throw out of the
+      // handler. MEASURED 2026-09-04 across five graded games (`Uncaught
+      // InvalidStateError: Failed to execute 'setPointerCapture'`): the click
+      // above requests pointer lock, and once the lock lands Chromium retires
+      // the pointer, so the capture call on that same pointerdown throws — an
+      // uncaught exception on the first click of every game with this camera,
+      // which failed the eval prober's no-errors check while the drag path
+      // beneath it still worked. Same guard the touch kit uses (drag-zone.ts).
+      if (typeof this._domElement.setPointerCapture === "function") {
+        try {
+          this._domElement.setPointerCapture(e.pointerId);
+        } catch {
+          // the pointer is already gone (pointer lock took it, or it was released
+          // between the event and the call) — the drag works without capture
+        }
+      }
       this._pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
       if (this._pointers.size === 1) {
         this._orbiting = true;

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

@@ -305,6 +305,16 @@ game with a generated character, every remote wears it — one
   `Player character: VRM — out of credits` in DESIGN.md, and mark the spot with
   `// TODO(genex): regenerate when credits refill`. Do not stop the session over
   this, and do not hand-build a stand-in humanoid.
+- **"The character provider is out of credit on this stand"** (the line `npx genex
+  wait` / `npx genex character` prints when the VENDOR refused for money — Meshy
+  "Insufficient funds", Tripo code 2010) — this is the platform's own provider
+  account, not your prompt and not the user's credits (the charge auto-refunds),
+  and no re-run changes it. Take the same fallback: keep the profile VRM avatar,
+  tell the user in one plain line that the game is wearing the platform avatar
+  because the character lane is unavailable on this stand, record
+  `Player character: VRM — provider out of credit` in DESIGN.md, and mark the spot
+  with `// TODO(genex): regenerate when credits refill`. `npx genex doctor` shows
+  the lane as OUT OF CREDIT while it lasts.
 - **"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.

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -135,6 +135,9 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 ## Minimal wiring
 
 ```ts
+import { initEmbed, waitForPlayer } from "@genex-ai/embed-sdk";
+import { GENEX } from "./genex.config";
+import * as THREE from "three";
 import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
 import { CharacterController } from "./controllers/character/character-controller.ts";
 import { CharacterAnimations } from "./controllers/character/character-animations.ts";
@@ -145,7 +148,15 @@ import { createAimCue } from "./controllers/character/aim-cue.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
 import { loadPlayerCharacter } from "./controllers/character/player-character.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
-import { waitForPlayer } from "@genex-ai/embed-sdk";
+
+initEmbed({ slug: GENEX.slug, apiUrl: GENEX.apiUrl, dashboardOrigins: GENEX.dashboardOrigins }); // FIRST — before any await
+
+// draw first; identity takes seconds on a hosted page
+const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias, ...depthRendererOptions() }); // tier + depthRendererOptions: the quality kit
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, near, far);
+document.body.appendChild(renderer.domElement);
+renderer.render(scene, camera); // a frame is on screen before anything below is awaited
 
 const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run before this resolves
 
@@ -154,13 +165,13 @@ const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run b
 // (with that character's exact-rig clips and locomotion profile), and falls
 // back to the visiting player's own profile avatar when it isn't — retargeting
 // the bundled core library plus any packs installed by `genex controller
-// anims`. `user.avatarUrl` comes from the embed identity
-// ($genex-threejs-embed-auth boots before this) and is used only in that
+// anims`. `user.avatarUrl` comes from the embed identity (the `initEmbed`
+// call above — $genex-threejs-embed-auth owns it) and is used only in that
 // fallback lane; the baked `./assets/avatar.vrm` covers local dev and load
 // failures. WRITE THIS ONCE: when the generated character lands mid-build,
 // `genex controller character --character <id>` drops the manifest in and the
 // next reload swaps the body. Nothing below changes.
-const { user } = await waitForPlayer();          // from "@genex-ai/embed-sdk"
+const { user } = await waitForPlayer();          // identity, awaited HERE — where the avatar is needed, never as the first line of the boot
 const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
 
 const fit = capsuleFromModel(player.scene);    // collider fits THIS body's bounds

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -54,6 +54,14 @@ initEmbed({
 });
 ```
 
+**Create the renderer and draw a frame BEFORE you await identity; `await
+waitForPlayer()` only where you need the name or the token.** On a hosted page
+identity takes seconds (the dashboard handshake, or the standalone bounce), so
+a `main.ts` whose first statement is `const { user } = await waitForPlayer()`
+shows black for all of them — and forever when `initEmbed()` was never called,
+because nothing else resolves that promise. Renderer, scene, camera, first
+frame, then the await, down where the name or the avatar is actually used.
+
 Also give `<body>` a dark background in `index.html` (e.g.
 `<body style="margin:0;background:#080a14">`) — it makes the pre-boot frame
 (before any JS runs) match the SDK's own loading overlay instead of flashing