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

package/dist/index.js

@@ -2755,602 +2755,8 @@ async function runWait(opts) {
 import fs12 from "fs/promises";
 import path13 from "path";
 
-// src/lib/anims.ts
-import fs11 from "fs/promises";
-import path12 from "path";
-var ANIMS_DEST = path12.join("public", "assets", "anims");
-var HIDDEN_TAG = "reference";
-async function runAnims(opts) {
-  const log = createLogger({ quiet: opts.quiet });
-  const root = opts.cwd ?? process.cwd();
-  const selectors = opts.selectors ?? [];
-  log.plain(c.bold("genex controller anims"));
-  log.plain("");
-  const { manifest, source } = await loadManifest(opts.animsBase);
-  if (source === "snapshot") {
-    log.dim("  (offline or CDN unreachable \u2014 using the bundled catalog snapshot)");
-  }
-  if (opts.list) {
-    printCatalog(log, manifest, selectors);
-    return;
-  }
-  const controllerMarker = path12.join(root, "src", "controllers", "character");
-  if (!await exists2(controllerMarker)) {
-    log.error(
-      `No character controller in this game (missing ${c.cyan("src/controllers/character/")}).`
-    );
-    log.plain(`  Run ${c.cyan("genex controller character")} first, then re-run this command.`);
-    process.exitCode = 1;
-    return;
-  }
-  const destDir = path12.join(root, ANIMS_DEST);
-  const gameManifestPath = path12.join(destDir, "manifest.json");
-  if (opts.reset) {
-    await fs11.rm(destDir, { recursive: true, force: true });
-    log.step(`Cleared ${c.cyan(ANIMS_DEST + path12.sep)} (--reset)`);
-  }
-  if (selectors.length === 0) {
-    const installed = await readGameManifest(gameManifestPath);
-    if (installed === null || installed.clips.length === 0) {
-      log.plain("  No animation packs installed yet.");
-    } else {
-      log.plain(`  Installed (${installed.clips.length} clips): ${installed.clips.join(", ")}`);
-    }
-    log.plain("");
-    log.plain(
-      `  Install with ${c.cyan("genex controller anims <tag|clip \u2026>")}; browse with ${c.cyan(
-        "genex controller anims --list"
-      )}.`
-    );
-    return;
-  }
-  let resolved;
-  try {
-    resolved = resolveSelectors(manifest, selectors);
-  } catch (err) {
-    log.error(err instanceof Error ? err.message : String(err));
-    process.exitCode = 1;
-    return;
-  }
-  const coreNames = new Set(manifest.core);
-  const byName = /* @__PURE__ */ new Map();
-  let bundledSkips = 0;
-  for (const entries of resolved.values()) {
-    for (const entry of entries) {
-      if (coreNames.has(entry.name)) {
-        bundledSkips++;
-        continue;
-      }
-      byName.set(entry.name, entry);
-    }
-  }
-  const wanted = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-  const cacheDir = path12.join(
-    opts.cacheDir ?? getAnimsCacheDir(),
-    `${manifest.library}-v${manifest.version}`
-  );
-  await fs11.mkdir(cacheDir, { recursive: true });
-  await fs11.mkdir(destDir, { recursive: true });
-  const base = getAnimsBase(opts.animsBase);
-  let installedCount = 0;
-  let presentCount = 0;
-  let addedBytes = 0;
-  const failures = [];
-  for (const entry of wanted) {
-    const dest = path12.join(destDir, entry.file);
-    if (await hasSize(dest, entry.bytes)) {
-      presentCount++;
-      continue;
-    }
-    try {
-      const cached = path12.join(cacheDir, entry.file);
-      if (!await hasSize(cached, entry.bytes)) {
-        const res = await fetch(base + entry.file);
-        if (!res.ok) throw new Error(`HTTP ${res.status}`);
-        const buf = Buffer.from(await res.arrayBuffer());
-        await fs11.writeFile(cached, buf);
-      }
-      await fs11.copyFile(cached, dest);
-      installedCount++;
-      addedBytes += entry.bytes;
-      log.dim(`  ${path12.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
-    } catch (err) {
-      failures.push(`${entry.name} (${err instanceof Error ? err.message : String(err)})`);
-    }
-  }
-  const previous = await readGameManifest(gameManifestPath);
-  const union = new Set(previous?.clips ?? []);
-  for (const entry of wanted) {
-    if (!failures.some((f) => f.startsWith(`${entry.name} (`))) union.add(entry.name);
-  }
-  const gameManifest = {
-    schema: 1,
-    library: manifest.library,
-    version: manifest.version,
-    clips: [...union].sort((a, b) => a.localeCompare(b))
-  };
-  await fs11.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
-  log.plain("");
-  const parts = [`${installedCount} clip${installedCount === 1 ? "" : "s"} installed`];
-  if (presentCount > 0) parts.push(`${presentCount} already present`);
-  if (bundledSkips > 0) parts.push(`${bundledSkips} already bundled in animation-library.glb`);
-  log.success(
-    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path12.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
-  );
-  for (const [selector, entries] of resolved) {
-    const names = entries.filter((e) => !coreNames.has(e.name)).map((e) => e.name);
-    if (names.length > 0) log.dim(`  ${selector}: ${names.join(", ")}`);
-  }
-  log.info(
-    `Wiring: load the ${c.cyan("genex-threejs-character-controller")} skill \u2192 "Animation packs" (loadCharacterClips picks these up automatically).`
-  );
-  if (failures.length > 0) {
-    log.plain("");
-    log.error(
-      `${failures.length} clip${failures.length === 1 ? "" : "s"} failed to download: ${failures.join(", ")}`
-    );
-    log.plain(
-      "  Each clip needs the network once per machine \u2014 check your connection and re-run the same command (already-installed clips are skipped)."
-    );
-    process.exitCode = 1;
-  }
-}
-async function loadManifest(baseOverride) {
-  const base = getAnimsBase(baseOverride);
-  try {
-    const res = await fetch(base + "manifest.json", { signal: AbortSignal.timeout(5e3) });
-    if (res.ok) {
-      const manifest2 = await res.json();
-      if (manifest2.schema === 1 && Array.isArray(manifest2.clips)) {
-        return { manifest: manifest2, source: "cdn" };
-      }
-    }
-  } catch {
-  }
-  const snapshotPath = path12.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
-  const manifest = JSON.parse(await fs11.readFile(snapshotPath, "utf8"));
-  return { manifest, source: "snapshot" };
-}
-function resolveSelectors(manifest, selectors) {
-  const byName = new Map(manifest.clips.map((entry) => [entry.name, entry]));
-  const byLowerName = new Map(manifest.clips.map((entry) => [entry.name.toLowerCase(), entry]));
-  const tags = /* @__PURE__ */ new Map();
-  for (const entry of manifest.clips) {
-    for (const tag of entry.tags) {
-      const list = tags.get(tag) ?? [];
-      list.push(entry);
-      tags.set(tag, list);
-    }
-  }
-  const out = /* @__PURE__ */ new Map();
-  for (const selector of selectors) {
-    const exact = byName.get(selector) ?? byLowerName.get(selector.toLowerCase());
-    if (exact) {
-      out.set(selector, [exact]);
-      continue;
-    }
-    const tagHit = tags.get(selector) ?? tags.get(selector.toLowerCase());
-    if (tagHit) {
-      out.set(selector, tagHit);
-      continue;
-    }
-    const candidates = [...tags.keys(), ...byName.keys()];
-    const close = suggest(selector, candidates);
-    throw new Error(
-      `unknown clip/tag "${selector}"${close.length > 0 ? ` \u2014 closest: ${close.join(", ")}` : ""}. Run ${c.cyan(
-        "genex controller anims --list"
-      )} for the catalog.`
-    );
-  }
-  return out;
-}
-function suggest(input, candidates) {
-  const lower = input.toLowerCase();
-  const scored = [];
-  for (const candidate of candidates) {
-    const candidateLower = candidate.toLowerCase();
-    if (candidateLower.includes(lower) || lower.includes(candidateLower)) {
-      scored.push({ name: candidate, score: 0 });
-      continue;
-    }
-    const distance = levenshtein(lower, candidateLower, 2);
-    if (distance <= 2) scored.push({ name: candidate, score: distance });
-  }
-  scored.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
-  return scored.slice(0, 4).map((s) => s.name);
-}
-function levenshtein(a, b, max) {
-  if (Math.abs(a.length - b.length) > max) return max + 1;
-  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    const curr = [i];
-    let rowMin = i;
-    for (let j = 1; j <= b.length; j++) {
-      curr[j] = Math.min(
-        prev[j] + 1,
-        curr[j - 1] + 1,
-        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
-      );
-      if (curr[j] < rowMin) rowMin = curr[j];
-    }
-    if (rowMin > max) return max + 1;
-    prev = curr;
-  }
-  return prev[b.length];
-}
-function printCatalog(log, manifest, selectors) {
-  const coreNames = new Set(manifest.core);
-  if (selectors.length > 0) {
-    let resolved;
-    try {
-      resolved = resolveSelectors(manifest, selectors);
-    } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err));
-      process.exitCode = 1;
-      return;
-    }
-    for (const [selector, entries] of resolved) {
-      log.plain(c.bold(selector));
-      for (const entry of entries) {
-        const bundled = coreNames.has(entry.name) ? " (bundled)" : "";
-        log.plain(
-          `  ${entry.name.padEnd(26)} ${entry.duration.toFixed(1)}s  ${formatMb(entry.bytes)}${bundled}  ${c.dim(entry.desc)}`
-        );
-      }
-    }
-    return;
-  }
-  const tags = /* @__PURE__ */ new Map();
-  for (const entry of manifest.clips) {
-    for (const tag of entry.tags) {
-      if (tag === HIDDEN_TAG) continue;
-      const list = tags.get(tag) ?? [];
-      list.push(entry);
-      tags.set(tag, list);
-    }
-  }
-  log.plain(
-    `${c.bold(`Animation packs`)} (${manifest.library} v${manifest.version}, ${manifest.clips.length} clips)`
-  );
-  log.plain(
-    `  Install: ${c.cyan("genex controller anims <tag|clip \u2026>")}   Details: ${c.cyan(
-      "genex controller anims --list <tag>"
-    )}`
-  );
-  log.plain("");
-  for (const [tag, entries] of [...tags.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-    const bytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
-    const suffix = tag === "core" ? " \u2014 bundled in animation-library.glb" : ` (${formatMb(bytes)})`;
-    log.plain(`  ${c.bold(tag.padEnd(18))} ${entries.map((e) => e.name).join(", ")}${suffix}`);
-  }
-}
-async function readGameManifest(file) {
-  try {
-    return JSON.parse(await fs11.readFile(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-async function hasSize(file, bytes) {
-  try {
-    return (await fs11.stat(file)).size === bytes;
-  } catch {
-    return false;
-  }
-}
-async function exists2(p) {
-  try {
-    await fs11.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function formatMb(bytes) {
-  return bytes >= 1e6 ? `${(bytes / 1e6).toFixed(1)} MB` : `${Math.round(bytes / 1e3)} KB`;
-}
-
-// src/commands/controller.ts
-var CONTROLLER_KINDS = [
-  "character",
-  "car",
-  "drone",
-  "touch",
-  "networked-physics"
-];
-var SHARED = [
-  "shared/math.ts",
-  "shared/physics-world.ts",
-  "shared/colliders.ts"
-];
-var TOUCH_KIT = [
-  "touch/touch-joystick.ts",
-  "touch/drag-zone.ts",
-  "touch/rotate-overlay.ts"
-];
-var INPUT_AND_CAMERA = [
-  "character/follow-camera.ts",
-  "character/keyboard-input.ts",
-  "character/touch-joystick.ts",
-  ...TOUCH_KIT
-];
-var NOTICE = "NOTICE.md";
-var CONTROLLER_FILE_SETS = {
-  character: {
-    code: [
-      ...SHARED,
-      "character/character-controller.ts",
-      "character/character-animations.ts",
-      "character/animation-packs.ts",
-      "character/motion-actions.ts",
-      "character/meshy/meshy-loader.ts",
-      "character/presets.ts",
-      // VRM avatar support (three-vrm): load + retarget the UAL clips + auto-fit
-      // the capsule + optional foot IK. Owner's avatar replaces the old mannequin.
-      "character/vrm/vrm-loader.ts",
-      "character/vrm/vrm-retarget.ts",
-      "character/vrm/capsule-fit.ts",
-      "character/vrm/foot-ik.ts",
-      ...INPUT_AND_CAMERA,
-      NOTICE
-    ],
-    // The player's VRM is written to public/assets/avatar.vrm at install time by
-    // installOwnerAvatar (owner's avatar, or the bundled default) — so it is NOT
-    // a static manifest asset. animation-library.glb (the 12-clip core) still is;
-    // extra clips arrive via `genex controller anims` into public/assets/anims/.
-    assets: ["assets/animation-library.glb"],
-    skill: "genex-threejs-character-controller",
-    sketch: [
-      `const physics = await PhysicsWorld.create();`,
-      `const { scene, vrm } = await loadVrm("./assets/avatar.vrm");`,
-      `const clips = await loadCharacterClips(vrm); // core library + every genex-controller-anims pack`,
-      `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...capsuleFromModel(scene), position: { x: 0, y: 2, z: 0 } });`,
-      `character.root.add(scene); const anims = new CharacterAnimations(scene, clips);`,
-      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); vrm.update(dt);`
-    ]
-  },
-  car: {
-    code: [
-      ...SHARED,
-      "vehicle/vehicle-controller.ts",
-      "vehicle/wheel.ts",
-      "vehicle/presets.ts",
-      "interact/enter-exit.ts",
-      ...INPUT_AND_CAMERA,
-      NOTICE
-    ],
-    assets: [],
-    skill: "genex-threejs-vehicle-controllers",
-    sketch: [
-      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
-      `const car = new VehicleController({ world: physics.world, position, carConfig: vehiclePresets["arcade-kart"].carConfig }); // + chassis colliders + car.addWheel(...) per preset slot`,
-      `scene.add(car.chassisObject); physics.onBeforeStep(() => { car.setMovement(keyboard.getCarMovement()); car.update(); });`
-    ]
-  },
-  drone: {
-    code: [
-      ...SHARED,
-      "drone/drone-controller.ts",
-      "drone/presets.ts",
-      "interact/enter-exit.ts",
-      ...INPUT_AND_CAMERA,
-      NOTICE
-    ],
-    assets: [],
-    skill: "genex-threejs-vehicle-controllers",
-    sketch: [
-      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
-      `const drone = new DroneController({ world: physics.world, body, chassis, propellers, config: dronePresets["camera-drone"].config });`,
-      `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
-    ]
-  },
-  touch: {
-    code: [...TOUCH_KIT, NOTICE],
-    assets: [],
-    skill: "genex-threejs-touch-controls",
-    sketch: [
-      `const joy = new TouchJoystick({ floating: true }); // safe-area-aware defaults; static circle without the flag`,
-      `const jump = new VirtualButton({ label: "Jump", onPress: () => player.jump() });`,
-      `const look = new DragZone(); // right half; per frame: const { dx, dy } = look.consumeDelta()`,
-      `[joy, jump, look].forEach((w) => w.setVisible(navigator.maxTouchPoints > 0));`
-    ]
-  },
-  "networked-physics": {
-    code: [
-      ...SHARED,
-      "network/pose.ts",
-      "network/networked-pushable.ts",
-      "network/networked-vehicle.ts",
-      "NETWORKING.md",
-      NOTICE
-    ],
-    assets: [],
-    skill: "genex-threejs-multiplayer",
-    sketch: [
-      `const box = new NetworkedPushable({ id: "box:1", room: () => room, body, object: mesh });`,
-      `physics.onBeforeStep(() => box.update()); physics.onAfterStep(() => box.publish());`,
-      `contacts.onChange((active) => box.setContact(active)); // retries held claims while contact persists`
-    ]
-  }
-};
-var CODE_DEST = path13.join("src", "controllers");
-var ASSETS_DEST = path13.join("public", "assets");
-async function runController(opts) {
-  const log = createLogger({ quiet: opts.quiet });
-  if (opts.kind?.trim() === "anims") {
-    await runAnims(opts);
-    return;
-  }
-  const kind = opts.kind?.trim();
-  if (!kind || !CONTROLLER_KINDS.includes(kind)) {
-    log.error(
-      `Missing or unknown controller type${kind ? ` "${kind}"` : ""}. Usage: ${c.cyan(
-        "genex controller <character|car|drone|touch|networked-physics> [--force]"
-      )} or ${c.cyan("genex controller anims <tag|clip \u2026>")}`
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const srcDir = path13.join(getTemplatesDir(), "controllers");
-  const root = opts.cwd ?? process.cwd();
-  const set = CONTROLLER_FILE_SETS[kind];
-  log.plain(c.bold(`genex controller ${kind}`));
-  log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
-  const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
-    ...set.assets.map((rel) => ({
-      from: rel,
-      rel: path13.join(ASSETS_DEST, path13.basename(rel))
-    }))
-  ];
-  let copied = 0;
-  let skipped = 0;
-  try {
-    for (const file of plan) {
-      const dest = path13.join(root, file.rel);
-      if (!opts.force && await exists3(dest)) {
-        skipped++;
-        log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
-        continue;
-      }
-      await fs12.mkdir(path13.dirname(dest), { recursive: true });
-      await fs12.copyFile(path13.join(srcDir, file.from), dest);
-      copied++;
-      log.dim(`  ${file.rel}`);
-    }
-  } catch (err) {
-    log.error(`Copy failed: ${String(err)}`);
-    process.exitCode = 1;
-    return;
-  }
-  log.success(
-    `Controller files ready (${copied} copied${skipped > 0 ? `, ${skipped} skipped` : ""}).`
-  );
-  log.plain("");
-  if (kind === "character") {
-    if (opts.character) {
-      try {
-        const token = opts.token !== void 0 ? opts.token : await readUserToken();
-        if (!token) throw new Error("Not authorized. Run `genex init` before installing a Meshy character.");
-        await installMeshyCharacterManifest({
-          root,
-          characterId: opts.character,
-          apiUrl: getApiUrl(opts.apiUrl),
-          token,
-          log
-        });
-      } catch (error) {
-        log.error(error instanceof Error ? error.message : String(error));
-        process.exitCode = 1;
-        return;
-      }
-    } else {
-      const token = opts.token !== void 0 ? opts.token : await readUserToken();
-      await installOwnerAvatar({ root, srcDir, apiUrl: getApiUrl(opts.apiUrl), token, log });
-    }
-    log.plain("");
-  }
-  log.plain(c.bold("Next steps"));
-  if (kind !== "touch") {
-    log.plain(
-      `  1. ${c.cyan(
-        kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : kind === "networked-physics" ? "npm i @dimforge/rapier3d-compat @genex-ai/multiplayer" : "npm i @dimforge/rapier3d-compat"
-      )} (three is already in the scaffold).`
-    );
-  }
-  const stepOffset = kind === "touch" ? 0 : 1;
-  log.plain(
-    `  ${stepOffset + 1}. Load the ${c.cyan(set.skill)} skill for wiring, presets, and tuning.`
-  );
-  log.plain(
-    kind === "touch" ? `  ${stepOffset + 2}. Wiring sketch (create behind a touch check; read per frame):` : `  ${stepOffset + 2}. Wiring sketch (controllers update BEFORE the physics step):`
-  );
-  const sketch = kind === "character" && opts.character ? [
-    `const physics = await PhysicsWorld.create();`,
-    `const native = await loadMeshyCharacter("./assets/meshy-character.json");`,
-    `const fit = capsuleFromModel(native.scene); const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...fit, position: { x: 0, y: 2, z: 0 } });`,
-    `character.root.add(native.scene); const anims = new CharacterAnimations(native.scene, native.clips, { locomotionProfile: native.locomotionProfile });`,
-    `physics.onBeforeStep(() => character.update(dt, input)); // Rapier owns movement; then anims.update(character, dt)`
-  ] : set.sketch;
-  for (const line of sketch) {
-    log.dim(`       ${line}`);
-  }
-  await firstPreviewNudge(log);
-}
-async function installMeshyCharacterManifest(args) {
-  const response = await apiFetch(
-    `${args.apiUrl}/api/characters/${encodeURIComponent(args.characterId)}/manifest`,
-    { headers: { Authorization: `Bearer ${args.token}` } }
-  );
-  if (response.status === 404) throw new Error(`Meshy character ${args.characterId} was not found on this account.`);
-  if (!response.ok) throw new Error(`Couldn't fetch the Meshy character manifest (HTTP ${response.status}).`);
-  const body = await response.json();
-  const manifest = body.manifest;
-  if (!manifest || manifest.schema !== 1 || manifest.rig !== "meshy-biped" || manifest.characterId !== args.characterId) {
-    throw new Error("The API returned an invalid Meshy character manifest.");
-  }
-  const destination = path13.join(args.root, ASSETS_DEST, "meshy-character.json");
-  await fs12.mkdir(path13.dirname(destination), { recursive: true });
-  await fs12.writeFile(
-    destination,
-    `${JSON.stringify(manifest, null, 2)}
-`
-  );
-  args.log.dim(`  public/assets/meshy-character.json (${args.characterId}, current revision)`);
-  const pack = manifest.controllerPack;
-  if (typeof pack?.key === "string" && typeof pack.version === "number") {
-    args.log.success(`Meshy controller pack ${pack.key} v${pack.version}`);
-  } else {
-    args.log.warn("Legacy Meshy manifest \u2014 regenerate the character for the preview-reviewed neutral-v2 locomotion pack.");
-  }
-  const actionIds = (manifest.clips ?? []).map((clip) => clip.actionId).filter((actionId) => typeof actionId === "number");
-  args.log.dim(`  installed action ids: ${actionIds.length > 0 ? actionIds.join(", ") : "none"}`);
-  const slots = Object.keys(manifest.locomotion?.bindings ?? manifest.locomotion?.slots ?? {}).sort();
-  args.log.dim(`  locomotion slots: ${slots.length > 0 ? slots.join(", ") : "none"}`);
-  const crouchCovered = slots.includes("crouch.idle") && slots.includes("crouch.forward");
-  if (crouchCovered) args.log.success("Visual crouch coverage: idle + move");
-  else args.log.warn("Visual crouch coverage is incomplete; physics crouch may fall back to a standing pose.");
-}
-async function installOwnerAvatar(args) {
-  const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs12.mkdir(path13.dirname(dest), { recursive: true });
-  if (token) {
-    try {
-      const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
-        headers: { Authorization: `Bearer ${token}` }
-      });
-      if (res.ok) {
-        const me = await res.json();
-        if (me.vrmUrl) {
-          const vrmRes = await fetch(me.vrmUrl);
-          if (vrmRes.ok) {
-            const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs12.writeFile(dest, buf);
-            log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
-            return;
-          }
-        }
-      }
-      log.dim("  couldn't fetch your avatar; using the bundled default.");
-    } catch {
-      log.dim("  avatar fetch failed (offline?); using the bundled default.");
-    }
-  }
-  await fs12.copyFile(path13.join(srcDir, "assets", "default-avatar.vrm"), dest);
-  log.dim(
-    token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
-  );
-}
-async function exists3(p) {
-  try {
-    await fs12.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
+// ../../packages/meshy-animation-catalog/src/index.ts
+import { createHash } from "crypto";
 
 // ../../packages/meshy-animation-catalog/src/generated.ts
 var MESHY_ANIMATION_CATALOG = [
@@ -12194,215 +11600,992 @@ var MESHY_ANIMATION_CATALOG = [
     "isFree": false,
     "createdAt": 1750829526124
   }
-];
-
-// ../../packages/meshy-animation-catalog/src/curation.ts
-var CURATED = {
-  [-2]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["walk.forward"] },
-  [-1]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["run.forward"] },
-  [0]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["idle.default"] },
-  [243]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: ["idle.default"],
-    reviewStatus: "preview-reviewed"
-  },
-  [466]: {
-    loop: false,
-    motionPolicy: "anchored-action",
-    controllerSlots: ["jump.full"],
-    reviewStatus: "preview-reviewed"
-  },
-  [613]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: ["walk.forward"],
-    reviewStatus: "preview-reviewed"
-  },
-  [616]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: ["crouch.forward"],
-    reviewStatus: "preview-reviewed"
-  },
-  [657]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: ["run.forward"],
-    reviewStatus: "preview-reviewed"
-  },
-  [658]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: [],
-    reviewStatus: "rejected"
-  },
-  [659]: {
-    loop: true,
-    motionPolicy: "controller-loop",
-    controllerSlots: [],
-    reviewStatus: "rejected"
+];
+
+// ../../packages/meshy-animation-catalog/src/curation.ts
+var CURATED = {
+  [-2]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["walk.forward"] },
+  [-1]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["run.forward"] },
+  [0]: { loop: true, motionPolicy: "controller-loop", controllerSlots: ["idle.default"] },
+  [243]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: ["idle.default"],
+    reviewStatus: "preview-reviewed"
+  },
+  [466]: {
+    loop: false,
+    motionPolicy: "anchored-action",
+    controllerSlots: ["jump.full"],
+    reviewStatus: "preview-reviewed"
+  },
+  [613]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: ["walk.forward"],
+    reviewStatus: "preview-reviewed"
+  },
+  [616]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: ["crouch.forward"],
+    reviewStatus: "preview-reviewed"
+  },
+  [657]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: ["run.forward"],
+    reviewStatus: "preview-reviewed"
+  },
+  [658]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: [],
+    reviewStatus: "rejected"
+  },
+  [659]: {
+    loop: true,
+    motionPolicy: "controller-loop",
+    controllerSlots: [],
+    reviewStatus: "rejected"
+  }
+};
+var LOOP_SUBCATEGORIES = /* @__PURE__ */ new Set(["Idle", "Walking", "Running", "CrouchWalking", "Swimming"]);
+var CHOREOGRAPHY_SUBCATEGORIES = /* @__PURE__ */ new Set([
+  "Climbing",
+  "HangingfromLedge",
+  "VaultingOverObstacle",
+  "Interacting",
+  "PickingUpItem",
+  "Pushing",
+  "Sleeping"
+]);
+var PLANAR_ACTION = /(?:roll|dodge|lunge|charge|step[_ -](?:back|forward)|slide)/i;
+var NON_LOOP_ACTION = /(?:transition|start|stop|turn)/i;
+function words(value) {
+  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
+}
+function inferRequirements(key, subCategory) {
+  const lower = `${key} ${subCategory}`.toLowerCase().replace(/[^a-z0-9]+/g, " ");
+  const props = [
+    ["gun", /\b(?:gun|rifle|pistol)\b/],
+    ["sword", /\b(?:sword|blade)\b/],
+    ["bow", /\b(?:bow|arrow)\b/],
+    ["shield", /\bshield\b/],
+    ["chair", /\b(?:chair|sit|sitting)\b/],
+    ["ladder", /\bladder\b/],
+    ["rope", /\brope\b/]
+  ].filter(([, pattern]) => pattern.test(lower)).map(([name]) => name);
+  const environment = [
+    ["climbable", /\b(?:climb|climbing|ladder|ledge|wall|rope)\b/],
+    ["vault obstacle", /\b(?:vault|vaulting|obstacle)\b/],
+    ["water", /\b(?:swim|swimming)\b/],
+    ["seat", /\b(?:sit|sitting|chair)\b/]
+  ].filter(([, pattern]) => pattern.test(lower)).map(([name]) => name);
+  return { props, environment, partner: /\b(?:partner|carry person|hug|handshake)\b/.test(lower) };
+}
+function inferSlots(key) {
+  const lower = key.toLowerCase();
+  const band = lower.includes("crouch") ? "crouch" : lower.includes("run") || lower.includes("sprint") ? "run" : lower.includes("walk") ? "walk" : null;
+  if (!band) return [];
+  const direction = lower.includes("backleft") ? "back-left" : lower.includes("backright") ? "back-right" : lower.includes("backward") || lower.includes("_back") ? "backward" : lower.includes("left") ? "left" : lower.includes("right") ? "right" : "forward";
+  return [`${band}.${direction}`];
+}
+function curateMeshyAnimation(raw) {
+  const inPlace = raw.tag === "InPlace";
+  const requirements = inferRequirements(raw.key, raw.subCategory);
+  const choreography = CHOREOGRAPHY_SUBCATEGORIES.has(raw.subCategory) || requirements.partner;
+  const loop = inPlace && LOOP_SUBCATEGORIES.has(raw.subCategory) && !NON_LOOP_ACTION.test(`${raw.key} ${raw.name}`);
+  const motionPolicy = loop ? "controller-loop" : choreography ? "choreography" : PLANAR_ACTION.test(`${raw.key} ${raw.name}`) ? "planar-root-action" : "anchored-action";
+  const base = {
+    actionId: raw.actionId,
+    key: raw.key,
+    name: raw.name,
+    category: raw.category,
+    subCategory: raw.subCategory,
+    previewUrl: raw.previewUrl,
+    rigType: raw.rigType,
+    inPlace,
+    isDefault: raw.isDefault,
+    isFree: raw.isFree,
+    createdAt: raw.createdAt,
+    aliases: [.../* @__PURE__ */ new Set([raw.key.replaceAll("_", " "), raw.name])],
+    gameplayTags: [.../* @__PURE__ */ new Set([...words(raw.category), ...words(raw.subCategory), ...inPlace ? ["in-place"] : [], ...requirements.props, ...requirements.environment])],
+    loop,
+    motionPolicy,
+    rootMotionValidated: false,
+    // A name that contains "walk" or "run" is not enough to make a safe
+    // controller loop. Only provider-declared InPlace loops (plus explicit
+    // measured overrides above) may populate automatic locomotion slots.
+    controllerSlots: loop ? inferSlots(raw.key) : [],
+    requirements,
+    reviewStatus: "metadata-reviewed"
+  };
+  return { ...base, ...CURATED[raw.actionId], requirements };
+}
+
+// ../../packages/meshy-animation-catalog/src/index.ts
+function normalizedPackDefinition(definition) {
+  const key = definition.key.trim();
+  if (!key) throw new Error("Meshy controller-pack key cannot be empty");
+  if (!Number.isInteger(definition.version) || definition.version < 1) {
+    throw new Error("Meshy controller-pack version must be a positive integer");
+  }
+  const actionIds = [...definition.actionIds];
+  if (actionIds.some((actionId) => !Number.isInteger(actionId))) {
+    throw new Error("Meshy controller-pack action IDs must be integers");
+  }
+  if (new Set(actionIds).size !== actionIds.length) {
+    throw new Error("Meshy controller-pack action IDs must be unique");
+  }
+  const allowed = new Set(actionIds);
+  const bindings = {};
+  for (const [slot, binding] of Object.entries(definition.bindings).sort(([left], [right]) => left.localeCompare(right))) {
+    if (!slot.trim()) throw new Error("Meshy controller-pack slots cannot be empty");
+    if (!allowed.has(binding.actionId)) {
+      throw new Error(`Meshy controller-pack slot ${slot} refers to action ${binding.actionId} outside its action set`);
+    }
+    if (binding.mode !== "loop" && binding.mode !== "one-shot" && binding.mode !== "pose") {
+      throw new Error(`Meshy controller-pack slot ${slot} has an invalid playback mode`);
+    }
+    if (binding.phase !== void 0 && (!Number.isFinite(binding.phase) || binding.phase < 0 || binding.phase > 1)) {
+      throw new Error(`Meshy controller-pack slot ${slot} has an invalid normalized phase`);
+    }
+    bindings[slot] = {
+      actionId: binding.actionId,
+      mode: binding.mode,
+      ...binding.phase === void 0 ? {} : { phase: binding.phase }
+    };
+  }
+  return { key, version: definition.version, actionIds, bindings };
+}
+function packFingerprint(definition) {
+  return createHash("sha256").update(JSON.stringify(definition)).digest("hex");
+}
+function createMeshyControllerPackSnapshot(definition) {
+  const normalized = normalizedPackDefinition(definition);
+  const actionIds = Object.freeze([...normalized.actionIds]);
+  const bindings = Object.freeze(Object.fromEntries(
+    Object.entries(normalized.bindings).map(([slot, binding]) => [slot, Object.freeze({ ...binding })])
+  ));
+  return Object.freeze({
+    ...normalized,
+    actionIds,
+    bindings,
+    fingerprint: packFingerprint(normalized)
+  });
+}
+var NEUTRAL_CONTROLLER_BINDINGS = {
+  "idle.default": { actionId: 243, mode: "loop" },
+  "walk.forward": { actionId: 613, mode: "loop" },
+  "run.forward": { actionId: 657, mode: "loop" },
+  "crouch.forward": { actionId: 616, mode: "loop" },
+  // The reviewed opening frame is a stable lowered stance; the loader samples
+  // it into a separate static clip so crouch movement can keep the full loop.
+  "crouch.idle": { actionId: 616, mode: "pose", phase: 0 },
+  "jump.full": { actionId: 466, mode: "one-shot" }
+};
+var MESHY_CONTROLLER_PACK = createMeshyControllerPackSnapshot({
+  key: "neutral-v3",
+  version: 3,
+  actionIds: [243, 613, 657, 616, 466],
+  bindings: NEUTRAL_CONTROLLER_BINDINGS
+});
+var MESHY_CONTROLLER_PACK_KEY = MESHY_CONTROLLER_PACK.key;
+var MESHY_CONTROLLER_PACK_VERSION = MESHY_CONTROLLER_PACK.version;
+var MESHY_CONTROLLER_PACK_FINGERPRINT = MESHY_CONTROLLER_PACK.fingerprint;
+var MESHY_CONTROLLER_CORE_ACTION_IDS = MESHY_CONTROLLER_PACK.actionIds;
+var MESHY_CONTROLLER_BINDINGS = MESHY_CONTROLLER_PACK.bindings;
+var SYNONYMS = {
+  attack: ["fight", "punch", "kick", "weapon", "combat"],
+  combat: ["fight", "attack", "punch", "weapon"],
+  crouch: ["sneak", "stealth"],
+  die: ["death", "dying", "fall"],
+  emote: ["gesture", "acting", "dance"],
+  gun: ["rifle", "pistol", "shoot", "firearm"],
+  idle: ["stand", "breathing"],
+  jump: ["leap", "vault"],
+  run: ["running", "jog", "sprint", "charge"],
+  sit: ["sitting", "chair", "seat"],
+  skate: ["skateboard", "skating", "board"],
+  sword: ["blade", "weapon", "slash"],
+  walk: ["walking", "stride", "stroll"],
+  wave: ["hello", "greeting", "gesture"]
+};
+var STOP_WORDS = /* @__PURE__ */ new Set(["a", "an", "and", "for", "of", "the", "to", "with"]);
+function tokens(value) {
+  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(/\s+/).filter((token) => token && !STOP_WORDS.has(token));
+}
+function tokenGroup(token) {
+  const group = /* @__PURE__ */ new Set([token, ...SYNONYMS[token] ?? []]);
+  for (const [canonical, synonyms] of Object.entries(SYNONYMS)) {
+    if (synonyms.includes(token)) {
+      group.add(canonical);
+      for (const synonym of synonyms) group.add(synonym);
+    }
+  }
+  return group;
+}
+var MESHY_ANIMATIONS = MESHY_ANIMATION_CATALOG.map(curateMeshyAnimation);
+var MESHY_ANIMATIONS_BY_ID = new Map(MESHY_ANIMATIONS.map((entry) => [entry.actionId, entry]));
+var MESHY_ANIMATIONS_BY_KEY = new Map(MESHY_ANIMATIONS.map((entry) => [entry.key.toLowerCase(), entry]));
+function animationById(actionId) {
+  return MESHY_ANIMATIONS_BY_ID.get(actionId);
+}
+function searchMeshyAnimations(query, options = {}) {
+  const rawQuery = query.trim().toLowerCase();
+  const queryTokens = tokens(query);
+  const groups = queryTokens.map(tokenGroup);
+  const expanded = new Set(groups.flatMap((group) => [...group]));
+  const results = [];
+  for (const entry of MESHY_ANIMATIONS) {
+    if (options.category && entry.category.toLowerCase() !== options.category.toLowerCase()) continue;
+    if (options.inPlace !== void 0 && entry.inPlace !== options.inPlace) continue;
+    const matched = [];
+    let score = 0;
+    if (String(entry.actionId) === rawQuery) {
+      score += 1e5;
+      matched.push("action id");
+    }
+    if (entry.key.toLowerCase() === rawQuery) {
+      score += 8e4;
+      matched.push("stable key");
+    }
+    if (entry.name.toLowerCase() === rawQuery) {
+      score += 6e4;
+      matched.push("exact name");
+    }
+    const haystack = new Set(tokens([
+      entry.key,
+      entry.name,
+      entry.category,
+      entry.subCategory,
+      ...entry.aliases,
+      ...entry.gameplayTags
+    ].join(" ")));
+    let coveredGroups = 0;
+    for (let index = 0; index < groups.length; index++) {
+      const hits = [...groups[index]].filter((token) => haystack.has(token));
+      if (hits.length === 0) continue;
+      coveredGroups++;
+      const original = queryTokens[index];
+      const best = hits.includes(original) ? original : hits[0];
+      score += best === original ? 400 : 140;
+      matched.push(best);
+    }
+    if (entry.inPlace && (expanded.has("walk") || expanded.has("run"))) score += 35;
+    const exact = score >= 6e4;
+    if (score > 0 && (exact || coveredGroups === groups.length)) {
+      results.push({ entry, score, matched: [...new Set(matched)] });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name) || a.entry.actionId - b.entry.actionId).slice(0, options.limit ?? 20);
+}
+
+// src/lib/anims.ts
+import fs11 from "fs/promises";
+import path12 from "path";
+var ANIMS_DEST = path12.join("public", "assets", "anims");
+var HIDDEN_TAG = "reference";
+async function runAnims(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const root = opts.cwd ?? process.cwd();
+  const selectors = opts.selectors ?? [];
+  log.plain(c.bold("genex controller anims"));
+  log.plain("");
+  const { manifest, source } = await loadManifest(opts.animsBase);
+  if (source === "snapshot") {
+    log.dim("  (offline or CDN unreachable \u2014 using the bundled catalog snapshot)");
+  }
+  if (opts.list) {
+    printCatalog(log, manifest, selectors);
+    return;
+  }
+  const controllerMarker = path12.join(root, "src", "controllers", "character");
+  if (!await exists2(controllerMarker)) {
+    log.error(
+      `No character controller in this game (missing ${c.cyan("src/controllers/character/")}).`
+    );
+    log.plain(`  Run ${c.cyan("genex controller character")} first, then re-run this command.`);
+    process.exitCode = 1;
+    return;
+  }
+  const destDir = path12.join(root, ANIMS_DEST);
+  const gameManifestPath = path12.join(destDir, "manifest.json");
+  if (opts.reset) {
+    await fs11.rm(destDir, { recursive: true, force: true });
+    log.step(`Cleared ${c.cyan(ANIMS_DEST + path12.sep)} (--reset)`);
+  }
+  if (selectors.length === 0) {
+    const installed = await readGameManifest(gameManifestPath);
+    if (installed === null || installed.clips.length === 0) {
+      log.plain("  No animation packs installed yet.");
+    } else {
+      log.plain(`  Installed (${installed.clips.length} clips): ${installed.clips.join(", ")}`);
+    }
+    log.plain("");
+    log.plain(
+      `  Install with ${c.cyan("genex controller anims <tag|clip \u2026>")}; browse with ${c.cyan(
+        "genex controller anims --list"
+      )}.`
+    );
+    return;
+  }
+  let resolved;
+  try {
+    resolved = resolveSelectors(manifest, selectors);
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  const coreNames = new Set(manifest.core);
+  const byName = /* @__PURE__ */ new Map();
+  let bundledSkips = 0;
+  for (const entries of resolved.values()) {
+    for (const entry of entries) {
+      if (coreNames.has(entry.name)) {
+        bundledSkips++;
+        continue;
+      }
+      byName.set(entry.name, entry);
+    }
+  }
+  const wanted = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  const cacheDir = path12.join(
+    opts.cacheDir ?? getAnimsCacheDir(),
+    `${manifest.library}-v${manifest.version}`
+  );
+  await fs11.mkdir(cacheDir, { recursive: true });
+  await fs11.mkdir(destDir, { recursive: true });
+  const base = getAnimsBase(opts.animsBase);
+  let installedCount = 0;
+  let presentCount = 0;
+  let addedBytes = 0;
+  const failures = [];
+  for (const entry of wanted) {
+    const dest = path12.join(destDir, entry.file);
+    if (await hasSize(dest, entry.bytes)) {
+      presentCount++;
+      continue;
+    }
+    try {
+      const cached = path12.join(cacheDir, entry.file);
+      if (!await hasSize(cached, entry.bytes)) {
+        const res = await fetch(base + entry.file);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        await fs11.writeFile(cached, buf);
+      }
+      await fs11.copyFile(cached, dest);
+      installedCount++;
+      addedBytes += entry.bytes;
+      log.dim(`  ${path12.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
+    } catch (err) {
+      failures.push(`${entry.name} (${err instanceof Error ? err.message : String(err)})`);
+    }
+  }
+  const previous = await readGameManifest(gameManifestPath);
+  const union = new Set(previous?.clips ?? []);
+  for (const entry of wanted) {
+    if (!failures.some((f) => f.startsWith(`${entry.name} (`))) union.add(entry.name);
+  }
+  const gameManifest = {
+    schema: 1,
+    library: manifest.library,
+    version: manifest.version,
+    clips: [...union].sort((a, b) => a.localeCompare(b))
+  };
+  await fs11.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
+  log.plain("");
+  const parts = [`${installedCount} clip${installedCount === 1 ? "" : "s"} installed`];
+  if (presentCount > 0) parts.push(`${presentCount} already present`);
+  if (bundledSkips > 0) parts.push(`${bundledSkips} already bundled in animation-library.glb`);
+  log.success(
+    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path12.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
+  );
+  for (const [selector, entries] of resolved) {
+    const names = entries.filter((e) => !coreNames.has(e.name)).map((e) => e.name);
+    if (names.length > 0) log.dim(`  ${selector}: ${names.join(", ")}`);
+  }
+  log.info(
+    `Wiring: load the ${c.cyan("genex-threejs-character-controller")} skill \u2192 "Animation packs" (loadCharacterClips picks these up automatically).`
+  );
+  if (failures.length > 0) {
+    log.plain("");
+    log.error(
+      `${failures.length} clip${failures.length === 1 ? "" : "s"} failed to download: ${failures.join(", ")}`
+    );
+    log.plain(
+      "  Each clip needs the network once per machine \u2014 check your connection and re-run the same command (already-installed clips are skipped)."
+    );
+    process.exitCode = 1;
+  }
+}
+async function loadManifest(baseOverride) {
+  const base = getAnimsBase(baseOverride);
+  try {
+    const res = await fetch(base + "manifest.json", { signal: AbortSignal.timeout(5e3) });
+    if (res.ok) {
+      const manifest2 = await res.json();
+      if (manifest2.schema === 1 && Array.isArray(manifest2.clips)) {
+        return { manifest: manifest2, source: "cdn" };
+      }
+    }
+  } catch {
+  }
+  const snapshotPath = path12.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
+  const manifest = JSON.parse(await fs11.readFile(snapshotPath, "utf8"));
+  return { manifest, source: "snapshot" };
+}
+function resolveSelectors(manifest, selectors) {
+  const byName = new Map(manifest.clips.map((entry) => [entry.name, entry]));
+  const byLowerName = new Map(manifest.clips.map((entry) => [entry.name.toLowerCase(), entry]));
+  const tags = /* @__PURE__ */ new Map();
+  for (const entry of manifest.clips) {
+    for (const tag of entry.tags) {
+      const list = tags.get(tag) ?? [];
+      list.push(entry);
+      tags.set(tag, list);
+    }
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const selector of selectors) {
+    const exact = byName.get(selector) ?? byLowerName.get(selector.toLowerCase());
+    if (exact) {
+      out.set(selector, [exact]);
+      continue;
+    }
+    const tagHit = tags.get(selector) ?? tags.get(selector.toLowerCase());
+    if (tagHit) {
+      out.set(selector, tagHit);
+      continue;
+    }
+    const candidates = [...tags.keys(), ...byName.keys()];
+    const close = suggest(selector, candidates);
+    throw new Error(
+      `unknown clip/tag "${selector}"${close.length > 0 ? ` \u2014 closest: ${close.join(", ")}` : ""}. Run ${c.cyan(
+        "genex controller anims --list"
+      )} for the catalog.`
+    );
+  }
+  return out;
+}
+function suggest(input, candidates) {
+  const lower = input.toLowerCase();
+  const scored = [];
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+    if (candidateLower.includes(lower) || lower.includes(candidateLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+    const distance = levenshtein(lower, candidateLower, 2);
+    if (distance <= 2) scored.push({ name: candidate, score: distance });
+  }
+  scored.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+  return scored.slice(0, 4).map((s) => s.name);
+}
+function levenshtein(a, b, max) {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > max) return max + 1;
+    prev = curr;
+  }
+  return prev[b.length];
+}
+function printCatalog(log, manifest, selectors) {
+  const coreNames = new Set(manifest.core);
+  if (selectors.length > 0) {
+    let resolved;
+    try {
+      resolved = resolveSelectors(manifest, selectors);
+    } catch (err) {
+      log.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+    for (const [selector, entries] of resolved) {
+      log.plain(c.bold(selector));
+      for (const entry of entries) {
+        const bundled = coreNames.has(entry.name) ? " (bundled)" : "";
+        log.plain(
+          `  ${entry.name.padEnd(26)} ${entry.duration.toFixed(1)}s  ${formatMb(entry.bytes)}${bundled}  ${c.dim(entry.desc)}`
+        );
+      }
+    }
+    return;
+  }
+  const tags = /* @__PURE__ */ new Map();
+  for (const entry of manifest.clips) {
+    for (const tag of entry.tags) {
+      if (tag === HIDDEN_TAG) continue;
+      const list = tags.get(tag) ?? [];
+      list.push(entry);
+      tags.set(tag, list);
+    }
+  }
+  log.plain(
+    `${c.bold(`Animation packs`)} (${manifest.library} v${manifest.version}, ${manifest.clips.length} clips)`
+  );
+  log.plain(
+    `  Install: ${c.cyan("genex controller anims <tag|clip \u2026>")}   Details: ${c.cyan(
+      "genex controller anims --list <tag>"
+    )}`
+  );
+  log.plain("");
+  for (const [tag, entries] of [...tags.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const bytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    const suffix = tag === "core" ? " \u2014 bundled in animation-library.glb" : ` (${formatMb(bytes)})`;
+    log.plain(`  ${c.bold(tag.padEnd(18))} ${entries.map((e) => e.name).join(", ")}${suffix}`);
   }
-};
-var LOOP_SUBCATEGORIES = /* @__PURE__ */ new Set(["Idle", "Walking", "Running", "CrouchWalking", "Swimming"]);
-var CHOREOGRAPHY_SUBCATEGORIES = /* @__PURE__ */ new Set([
-  "Climbing",
-  "HangingfromLedge",
-  "VaultingOverObstacle",
-  "Interacting",
-  "PickingUpItem",
-  "Pushing",
-  "Sleeping"
-]);
-var PLANAR_ACTION = /(?:roll|dodge|lunge|charge|step[_ -](?:back|forward)|slide)/i;
-var NON_LOOP_ACTION = /(?:transition|start|stop|turn)/i;
-function words(value) {
-  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
 }
-function inferRequirements(key, subCategory) {
-  const lower = `${key} ${subCategory}`.toLowerCase().replace(/[^a-z0-9]+/g, " ");
-  const props = [
-    ["gun", /\b(?:gun|rifle|pistol)\b/],
-    ["sword", /\b(?:sword|blade)\b/],
-    ["bow", /\b(?:bow|arrow)\b/],
-    ["shield", /\bshield\b/],
-    ["chair", /\b(?:chair|sit|sitting)\b/],
-    ["ladder", /\bladder\b/],
-    ["rope", /\brope\b/]
-  ].filter(([, pattern]) => pattern.test(lower)).map(([name]) => name);
-  const environment = [
-    ["climbable", /\b(?:climb|climbing|ladder|ledge|wall|rope)\b/],
-    ["vault obstacle", /\b(?:vault|vaulting|obstacle)\b/],
-    ["water", /\b(?:swim|swimming)\b/],
-    ["seat", /\b(?:sit|sitting|chair)\b/]
-  ].filter(([, pattern]) => pattern.test(lower)).map(([name]) => name);
-  return { props, environment, partner: /\b(?:partner|carry person|hug|handshake)\b/.test(lower) };
+async function readGameManifest(file) {
+  try {
+    return JSON.parse(await fs11.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
 }
-function inferSlots(key) {
-  const lower = key.toLowerCase();
-  const band = lower.includes("crouch") ? "crouch" : lower.includes("run") || lower.includes("sprint") ? "run" : lower.includes("walk") ? "walk" : null;
-  if (!band) return [];
-  const direction = lower.includes("backleft") ? "back-left" : lower.includes("backright") ? "back-right" : lower.includes("backward") || lower.includes("_back") ? "backward" : lower.includes("left") ? "left" : lower.includes("right") ? "right" : "forward";
-  return [`${band}.${direction}`];
+async function hasSize(file, bytes) {
+  try {
+    return (await fs11.stat(file)).size === bytes;
+  } catch {
+    return false;
+  }
 }
-function curateMeshyAnimation(raw) {
-  const inPlace = raw.tag === "InPlace";
-  const requirements = inferRequirements(raw.key, raw.subCategory);
-  const choreography = CHOREOGRAPHY_SUBCATEGORIES.has(raw.subCategory) || requirements.partner;
-  const loop = inPlace && LOOP_SUBCATEGORIES.has(raw.subCategory) && !NON_LOOP_ACTION.test(`${raw.key} ${raw.name}`);
-  const motionPolicy = loop ? "controller-loop" : choreography ? "choreography" : PLANAR_ACTION.test(`${raw.key} ${raw.name}`) ? "planar-root-action" : "anchored-action";
-  const base = {
-    actionId: raw.actionId,
-    key: raw.key,
-    name: raw.name,
-    category: raw.category,
-    subCategory: raw.subCategory,
-    previewUrl: raw.previewUrl,
-    rigType: raw.rigType,
-    inPlace,
-    isDefault: raw.isDefault,
-    isFree: raw.isFree,
-    createdAt: raw.createdAt,
-    aliases: [.../* @__PURE__ */ new Set([raw.key.replaceAll("_", " "), raw.name])],
-    gameplayTags: [.../* @__PURE__ */ new Set([...words(raw.category), ...words(raw.subCategory), ...inPlace ? ["in-place"] : [], ...requirements.props, ...requirements.environment])],
-    loop,
-    motionPolicy,
-    rootMotionValidated: false,
-    // A name that contains "walk" or "run" is not enough to make a safe
-    // controller loop. Only provider-declared InPlace loops (plus explicit
-    // measured overrides above) may populate automatic locomotion slots.
-    controllerSlots: loop ? inferSlots(raw.key) : [],
-    requirements,
-    reviewStatus: "metadata-reviewed"
-  };
-  return { ...base, ...CURATED[raw.actionId], requirements };
+async function exists2(p) {
+  try {
+    await fs11.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatMb(bytes) {
+  return bytes >= 1e6 ? `${(bytes / 1e6).toFixed(1)} MB` : `${Math.round(bytes / 1e3)} KB`;
 }
 
-// ../../packages/meshy-animation-catalog/src/index.ts
-var SYNONYMS = {
-  attack: ["fight", "punch", "kick", "weapon", "combat"],
-  combat: ["fight", "attack", "punch", "weapon"],
-  crouch: ["sneak", "stealth"],
-  die: ["death", "dying", "fall"],
-  emote: ["gesture", "acting", "dance"],
-  gun: ["rifle", "pistol", "shoot", "firearm"],
-  idle: ["stand", "breathing"],
-  jump: ["leap", "vault"],
-  run: ["running", "jog", "sprint", "charge"],
-  sit: ["sitting", "chair", "seat"],
-  skate: ["skateboard", "skating", "board"],
-  sword: ["blade", "weapon", "slash"],
-  walk: ["walking", "stride", "stroll"],
-  wave: ["hello", "greeting", "gesture"]
+// src/commands/controller.ts
+var CONTROLLER_KINDS = [
+  "character",
+  "car",
+  "drone",
+  "touch",
+  "networked-physics"
+];
+var SHARED = [
+  "shared/math.ts",
+  "shared/physics-world.ts",
+  "shared/colliders.ts"
+];
+var TOUCH_KIT = [
+  "touch/touch-joystick.ts",
+  "touch/drag-zone.ts",
+  "touch/rotate-overlay.ts"
+];
+var INPUT_AND_CAMERA = [
+  "character/follow-camera.ts",
+  "character/keyboard-input.ts",
+  "character/touch-joystick.ts",
+  ...TOUCH_KIT
+];
+var NOTICE = "NOTICE.md";
+var CONTROLLER_FILE_SETS = {
+  character: {
+    code: [
+      ...SHARED,
+      "character/character-controller.ts",
+      "character/character-animations.ts",
+      "character/animation-packs.ts",
+      "character/motion-actions.ts",
+      "character/meshy/meshy-loader.ts",
+      "character/presets.ts",
+      // VRM avatar support (three-vrm): load + retarget the UAL clips + auto-fit
+      // the capsule + optional foot IK. Owner's avatar replaces the old mannequin.
+      "character/vrm/vrm-loader.ts",
+      "character/vrm/vrm-retarget.ts",
+      "character/vrm/capsule-fit.ts",
+      "character/vrm/foot-ik.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    // The player's VRM is written to public/assets/avatar.vrm at install time by
+    // installOwnerAvatar (owner's avatar, or the bundled default) — so it is NOT
+    // a static manifest asset. animation-library.glb (the 12-clip core) still is;
+    // extra clips arrive via `genex controller anims` into public/assets/anims/.
+    assets: ["assets/animation-library.glb"],
+    skill: "genex-threejs-character-controller",
+    sketch: [
+      `const physics = await PhysicsWorld.create();`,
+      `const { scene, vrm } = await loadVrm("./assets/avatar.vrm");`,
+      `const clips = await loadCharacterClips(vrm); // core library + every genex-controller-anims pack`,
+      `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...capsuleFromModel(scene), position: { x: 0, y: 2, z: 0 } });`,
+      `character.root.add(scene); const anims = new CharacterAnimations(scene, clips);`,
+      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); vrm.update(dt);`
+    ]
+  },
+  car: {
+    code: [
+      ...SHARED,
+      "vehicle/vehicle-controller.ts",
+      "vehicle/wheel.ts",
+      "vehicle/presets.ts",
+      "interact/enter-exit.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-vehicle-controllers",
+    sketch: [
+      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
+      `const car = new VehicleController({ world: physics.world, position, carConfig: vehiclePresets["arcade-kart"].carConfig }); // + chassis colliders + car.addWheel(...) per preset slot`,
+      `scene.add(car.chassisObject); physics.onBeforeStep(() => { car.setMovement(keyboard.getCarMovement()); car.update(); });`
+    ]
+  },
+  drone: {
+    code: [
+      ...SHARED,
+      "drone/drone-controller.ts",
+      "drone/presets.ts",
+      "interact/enter-exit.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-vehicle-controllers",
+    sketch: [
+      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
+      `const drone = new DroneController({ world: physics.world, body, chassis, propellers, config: dronePresets["camera-drone"].config });`,
+      `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
+    ]
+  },
+  touch: {
+    code: [...TOUCH_KIT, NOTICE],
+    assets: [],
+    skill: "genex-threejs-touch-controls",
+    sketch: [
+      `const joy = new TouchJoystick({ floating: true }); // safe-area-aware defaults; static circle without the flag`,
+      `const jump = new VirtualButton({ label: "Jump", onPress: () => player.jump() });`,
+      `const look = new DragZone(); // right half; per frame: const { dx, dy } = look.consumeDelta()`,
+      `[joy, jump, look].forEach((w) => w.setVisible(navigator.maxTouchPoints > 0));`
+    ]
+  },
+  "networked-physics": {
+    code: [
+      ...SHARED,
+      "network/pose.ts",
+      "network/networked-pushable.ts",
+      "network/networked-vehicle.ts",
+      "NETWORKING.md",
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-multiplayer",
+    sketch: [
+      `const box = new NetworkedPushable({ id: "box:1", room: () => room, body, object: mesh });`,
+      `physics.onBeforeStep(() => box.update()); physics.onAfterStep(() => box.publish());`,
+      `contacts.onChange((active) => box.setContact(active)); // retries held claims while contact persists`
+    ]
+  }
 };
-var STOP_WORDS = /* @__PURE__ */ new Set(["a", "an", "and", "for", "of", "the", "to", "with"]);
-function tokens(value) {
-  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(/\s+/).filter((token) => token && !STOP_WORDS.has(token));
-}
-function tokenGroup(token) {
-  const group = /* @__PURE__ */ new Set([token, ...SYNONYMS[token] ?? []]);
-  for (const [canonical, synonyms] of Object.entries(SYNONYMS)) {
-    if (synonyms.includes(token)) {
-      group.add(canonical);
-      for (const synonym of synonyms) group.add(synonym);
+var CODE_DEST = path13.join("src", "controllers");
+var ASSETS_DEST = path13.join("public", "assets");
+async function runController(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  if (opts.kind?.trim() === "anims") {
+    await runAnims(opts);
+    return;
+  }
+  const kind = opts.kind?.trim();
+  if (!kind || !CONTROLLER_KINDS.includes(kind)) {
+    log.error(
+      `Missing or unknown controller type${kind ? ` "${kind}"` : ""}. Usage: ${c.cyan(
+        "genex controller <character|car|drone|touch|networked-physics> [--force]"
+      )} or ${c.cyan("genex controller anims <tag|clip \u2026>")}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const srcDir = path13.join(getTemplatesDir(), "controllers");
+  const root = opts.cwd ?? process.cwd();
+  const set = CONTROLLER_FILE_SETS[kind];
+  log.plain(c.bold(`genex controller ${kind}`));
+  log.plain("");
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
+  const plan = [
+    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
+    ...set.assets.map((rel) => ({
+      from: rel,
+      rel: path13.join(ASSETS_DEST, path13.basename(rel))
+    }))
+  ];
+  let copied = 0;
+  let skipped = 0;
+  try {
+    for (const file of plan) {
+      const dest = path13.join(root, file.rel);
+      if (!opts.force && await exists3(dest)) {
+        skipped++;
+        log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
+        continue;
+      }
+      await fs12.mkdir(path13.dirname(dest), { recursive: true });
+      await fs12.copyFile(path13.join(srcDir, file.from), dest);
+      copied++;
+      log.dim(`  ${file.rel}`);
     }
+  } catch (err) {
+    log.error(`Copy failed: ${String(err)}`);
+    process.exitCode = 1;
+    return;
   }
-  return group;
-}
-var MESHY_ANIMATIONS = MESHY_ANIMATION_CATALOG.map(curateMeshyAnimation);
-var MESHY_ANIMATIONS_BY_ID = new Map(MESHY_ANIMATIONS.map((entry) => [entry.actionId, entry]));
-var MESHY_ANIMATIONS_BY_KEY = new Map(MESHY_ANIMATIONS.map((entry) => [entry.key.toLowerCase(), entry]));
-function animationById(actionId) {
-  return MESHY_ANIMATIONS_BY_ID.get(actionId);
-}
-function searchMeshyAnimations(query, options = {}) {
-  const rawQuery = query.trim().toLowerCase();
-  const queryTokens = tokens(query);
-  const groups = queryTokens.map(tokenGroup);
-  const expanded = new Set(groups.flatMap((group) => [...group]));
-  const results = [];
-  for (const entry of MESHY_ANIMATIONS) {
-    if (options.category && entry.category.toLowerCase() !== options.category.toLowerCase()) continue;
-    if (options.inPlace !== void 0 && entry.inPlace !== options.inPlace) continue;
-    const matched = [];
-    let score = 0;
-    if (String(entry.actionId) === rawQuery) {
-      score += 1e5;
-      matched.push("action id");
+  log.success(
+    `Controller files ready (${copied} copied${skipped > 0 ? `, ${skipped} skipped` : ""}).`
+  );
+  log.plain("");
+  if (kind === "character") {
+    if (opts.character) {
+      try {
+        const token = opts.token !== void 0 ? opts.token : await readUserToken();
+        if (!token) throw new Error("Not authorized. Run `genex init` before installing a Meshy character.");
+        await installMeshyCharacterManifest({
+          root,
+          characterId: opts.character,
+          apiUrl: getApiUrl(opts.apiUrl),
+          token,
+          log
+        });
+      } catch (error) {
+        log.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      const token = opts.token !== void 0 ? opts.token : await readUserToken();
+      await installOwnerAvatar({ root, srcDir, apiUrl: getApiUrl(opts.apiUrl), token, log });
     }
-    if (entry.key.toLowerCase() === rawQuery) {
-      score += 8e4;
-      matched.push("stable key");
+    log.plain("");
+  }
+  log.plain(c.bold("Next steps"));
+  if (kind !== "touch") {
+    log.plain(
+      `  1. ${c.cyan(
+        kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : kind === "networked-physics" ? "npm i @dimforge/rapier3d-compat @genex-ai/multiplayer" : "npm i @dimforge/rapier3d-compat"
+      )} (three is already in the scaffold).`
+    );
+  }
+  const stepOffset = kind === "touch" ? 0 : 1;
+  log.plain(
+    `  ${stepOffset + 1}. Load the ${c.cyan(set.skill)} skill for wiring, presets, and tuning.`
+  );
+  log.plain(
+    kind === "touch" ? `  ${stepOffset + 2}. Wiring sketch (create behind a touch check; read per frame):` : `  ${stepOffset + 2}. Wiring sketch (controllers update BEFORE the physics step):`
+  );
+  const sketch = kind === "character" && opts.character ? [
+    `const physics = await PhysicsWorld.create();`,
+    `const native = await loadMeshyCharacter("./assets/meshy-character.json");`,
+    `const fit = capsuleFromModel(native.scene); const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...fit, position: { x: 0, y: 2, z: 0 } });`,
+    `character.root.add(native.scene); const anims = new CharacterAnimations(native.scene, native.clips, { locomotionProfile: native.locomotionProfile });`,
+    `physics.onBeforeStep(() => character.update(dt, input)); // Rapier owns movement; then anims.update(character, dt)`
+  ] : set.sketch;
+  for (const line of sketch) {
+    log.dim(`       ${line}`);
+  }
+  await firstPreviewNudge(log);
+}
+async function installMeshyCharacterManifest(args) {
+  const response = await apiFetch(
+    `${args.apiUrl}/api/characters/${encodeURIComponent(args.characterId)}/manifest`,
+    { headers: { Authorization: `Bearer ${args.token}` } }
+  );
+  if (response.status === 404) throw new Error(`Meshy character ${args.characterId} was not found on this account.`);
+  if (!response.ok) {
+    let detail;
+    try {
+      const errorBody = await response.json();
+      if (typeof errorBody.message === "string" && errorBody.message.length > 0) detail = errorBody.message;
+      else if (typeof errorBody.error === "string" && errorBody.error.length > 0) detail = errorBody.error;
+    } catch {
     }
-    if (entry.name.toLowerCase() === rawQuery) {
-      score += 6e4;
-      matched.push("exact name");
+    throw new Error(detail ?? `Couldn't fetch the Meshy character manifest (HTTP ${response.status}).`);
+  }
+  const body = await response.json();
+  const manifest = body.manifest;
+  if (!manifest || manifest.schema !== 1 || manifest.rig !== "meshy-biped" || manifest.characterId !== args.characterId || typeof manifest.model?.url !== "string" || typeof manifest.model.skeletonSignature !== "string" || !Array.isArray(manifest.clips) || !manifest.locomotion?.slots) {
+    throw new Error("The API returned an invalid Meshy character manifest.");
+  }
+  assertCompleteMeshyControllerPack(manifest);
+  const destination = path13.join(args.root, ASSETS_DEST, "meshy-character.json");
+  await fs12.mkdir(path13.dirname(destination), { recursive: true });
+  await fs12.writeFile(
+    destination,
+    `${JSON.stringify(manifest, null, 2)}
+`
+  );
+  args.log.dim(`  public/assets/meshy-character.json (${args.characterId}, current revision)`);
+  const pack = manifest.controllerPack;
+  if (typeof pack?.key === "string" && typeof pack.version === "number") {
+    args.log.success(`Meshy controller pack ${pack.key} v${pack.version}`);
+  } else {
+    args.log.warn("Legacy Meshy manifest \u2014 regenerate the character for the immutable preview-reviewed neutral-v3 locomotion pack.");
+  }
+  const provenance = manifest.provenance;
+  if (provenance?.provider === "meshy" && typeof provenance.aiModel === "string") {
+    const apiVersion = typeof provenance.apiVersion === "string" && provenance.apiVersion.length > 0 ? `; API ${provenance.apiVersion}` : "";
+    args.log.success(`Meshy model: ${provenance.aiModel}${apiVersion}`);
+    if ((provenance.poseMode === "a-pose" || provenance.poseMode === "t-pose") && typeof provenance.shouldRemesh === "boolean" && typeof provenance.targetPolycount === "number") {
+      args.log.dim(
+        `  generation: ${provenance.poseMode}, remesh ${provenance.shouldRemesh ? "on" : "off"}, target ${provenance.targetPolycount} polygons`
+      );
     }
-    const haystack = new Set(tokens([
-      entry.key,
-      entry.name,
-      entry.category,
-      entry.subCategory,
-      ...entry.aliases,
-      ...entry.gameplayTags
-    ].join(" ")));
-    let coveredGroups = 0;
-    for (let index = 0; index < groups.length; index++) {
-      const hits = [...groups[index]].filter((token) => haystack.has(token));
-      if (hits.length === 0) continue;
-      coveredGroups++;
-      const original = queryTokens[index];
-      const best = hits.includes(original) ? original : hits[0];
-      score += best === original ? 400 : 140;
-      matched.push(best);
+  } else {
+    args.log.warn("Meshy model/version metadata is unavailable in this legacy manifest.");
+  }
+  const actionIds = (manifest.clips ?? []).map((clip) => clip.actionId).filter((actionId) => typeof actionId === "number");
+  args.log.dim(`  installed action ids: ${actionIds.length > 0 ? actionIds.join(", ") : "none"}`);
+  const bindings = manifest.locomotion?.bindings;
+  if (bindings) {
+    for (const [slot, binding] of Object.entries(bindings).sort(([a], [b]) => a.localeCompare(b))) {
+      if (typeof binding?.actionId === "number" && typeof binding.clip === "string" && typeof binding.mode === "string") {
+        const phase = typeof binding.phase === "number" ? ` @ phase ${binding.phase}` : "";
+        args.log.dim(`  ${slot} -> action ${binding.actionId} (${binding.clip}, ${binding.mode}${phase})`);
+      }
     }
-    if (entry.inPlace && (expanded.has("walk") || expanded.has("run"))) score += 35;
-    const exact = score >= 6e4;
-    if (score > 0 && (exact || coveredGroups === groups.length)) {
-      results.push({ entry, score, matched: [...new Set(matched)] });
+  }
+  const slots = Object.keys(bindings ?? manifest.locomotion?.slots ?? {}).sort();
+  args.log.dim(`  locomotion slots: ${slots.length > 0 ? slots.join(", ") : "none"}`);
+  const crouchCovered = slots.includes("crouch.idle") && slots.includes("crouch.forward");
+  if (crouchCovered) args.log.success("Visual crouch coverage: idle + move");
+  else args.log.warn("Visual crouch coverage is incomplete; physics crouch may fall back to a standing pose.");
+}
+var REQUIRED_MESHY_CONTROLLER_SLOTS = [
+  "idle.default",
+  "walk.forward",
+  "run.forward",
+  "crouch.forward",
+  "crouch.idle",
+  "jump.full"
+];
+function incompletePack(message) {
+  throw new Error(`Incomplete Meshy controller pack: ${message}`);
+}
+function assertCompleteMeshyControllerPack(manifest) {
+  const pack = manifest.controllerPack;
+  if (pack === void 0) return;
+  if (typeof pack.key !== "string" || pack.key.length === 0 || typeof pack.version !== "number" || !Number.isInteger(pack.version)) {
+    incompletePack("invalid key or version.");
+  }
+  if (typeof pack.fingerprint !== "string" || pack.fingerprint.length === 0) {
+    incompletePack(`${pack.key} v${pack.version} has no immutable fingerprint.`);
+  }
+  if (!Array.isArray(pack.actionIds) || pack.actionIds.length === 0 || pack.actionIds.some((actionId) => typeof actionId !== "number" || !Number.isInteger(actionId))) {
+    incompletePack(`${pack.key} v${pack.version} has no valid action snapshot.`);
+  }
+  const actionIds = pack.actionIds;
+  const packActionIds = new Set(actionIds);
+  if (packActionIds.size !== actionIds.length) {
+    incompletePack(`${pack.key} v${pack.version} repeats an action ID.`);
+  }
+  const bindings = manifest.locomotion?.bindings;
+  if (!bindings) incompletePack(`${pack.key} v${pack.version} has no authoritative locomotion bindings.`);
+  const missingSlots = REQUIRED_MESHY_CONTROLLER_SLOTS.filter((slot) => bindings[slot] === void 0);
+  if (missingSlots.length > 0) {
+    incompletePack(`${pack.key} v${pack.version} is missing ${missingSlots.join(", ")}.`);
+  }
+  const clips = manifest.clips ?? [];
+  const boundActionIds = /* @__PURE__ */ new Set();
+  const snapshotBindings = {};
+  for (const [slot, binding] of Object.entries(bindings)) {
+    if (typeof binding.actionId !== "number" || !Number.isInteger(binding.actionId) || typeof binding.clip !== "string" || binding.clip.length === 0 || binding.mode !== "loop" && binding.mode !== "one-shot" && binding.mode !== "pose") {
+      incompletePack(`${pack.key} v${pack.version} has an invalid ${slot} binding.`);
+    }
+    if (binding.phase !== void 0 && (typeof binding.phase !== "number" || !Number.isFinite(binding.phase) || binding.phase < 0 || binding.phase > 1)) {
+      incompletePack(`${pack.key} v${pack.version} has an invalid ${slot} phase.`);
+    }
+    const actionId = binding.actionId;
+    boundActionIds.add(actionId);
+    if (!packActionIds.has(actionId)) {
+      incompletePack(`${slot} points at action ${actionId}, which is outside the stored pack snapshot.`);
+    }
+    const clip = clips.find((entry) => entry.actionId === actionId);
+    if (!clip || clip.key !== binding.clip) {
+      incompletePack(`${slot} expects action ${actionId} clip ${binding.clip}, but that exact clip is not installed.`);
+    }
+    snapshotBindings[slot] = {
+      actionId,
+      mode: binding.mode,
+      ...binding.phase === void 0 ? {} : { phase: binding.phase }
+    };
+  }
+  const unboundActionIds = actionIds.filter((actionId) => !boundActionIds.has(actionId));
+  if (unboundActionIds.length > 0) {
+    incompletePack(`${pack.key} v${pack.version} action snapshot contains unbound actions ${unboundActionIds.join(", ")}.`);
+  }
+  let computedFingerprint;
+  try {
+    computedFingerprint = createMeshyControllerPackSnapshot({
+      key: pack.key,
+      version: pack.version,
+      actionIds,
+      bindings: snapshotBindings
+    }).fingerprint;
+  } catch (error) {
+    incompletePack(error instanceof Error ? error.message : "the immutable snapshot is invalid.");
+  }
+  if (computedFingerprint !== pack.fingerprint) {
+    incompletePack(`${pack.key} v${pack.version} fingerprint does not match its action bindings.`);
+  }
+}
+async function installOwnerAvatar(args) {
+  const { root, srcDir, apiUrl, token, log } = args;
+  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs12.mkdir(path13.dirname(dest), { recursive: true });
+  if (token) {
+    try {
+      const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const me = await res.json();
+        if (me.vrmUrl) {
+          const vrmRes = await fetch(me.vrmUrl);
+          if (vrmRes.ok) {
+            const buf = Buffer.from(await vrmRes.arrayBuffer());
+            await fs12.writeFile(dest, buf);
+            log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
+            return;
+          }
+        }
+      }
+      log.dim("  couldn't fetch your avatar; using the bundled default.");
+    } catch {
+      log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  return results.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name) || a.entry.actionId - b.entry.actionId).slice(0, options.limit ?? 20);
+  await fs12.copyFile(path13.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  log.dim(
+    token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
+  );
+}
+async function exists3(p) {
+  try {
+    await fs12.access(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 // src/commands/character.ts
@@ -12487,8 +12670,10 @@ async function runCharacter(opts) {
   log.plain(c.bold("Character quote"));
   log.plain(`  ${price.credits} Genex credits = base ${price.baseCredits} + actions ${price.animationCredits}`);
   if (price.controllerPackKey) {
+    const version = price.controllerPackVersion === void 0 ? "" : ` v${price.controllerPackVersion}`;
+    const fingerprint = price.controllerPackFingerprint ? ` \xB7 fingerprint ${price.controllerPackFingerprint}` : "";
     log.plain(
-      `  controller pack ${c.cyan(price.controllerPackKey)} \xB7 provider actions ${(price.controllerActionIds ?? []).join(", ")}`
+      `  controller pack ${c.cyan(`${price.controllerPackKey}${version}`)}${fingerprint} \xB7 provider actions ${(price.controllerActionIds ?? []).join(", ")}`
     );
   }
   log.dim(`  ${price.actionsGenerated} Meshy animation task${price.actionsGenerated === 1 ? "" : "s"} in this request.`);