@genex-ai/cli-demo 0.38.0 → 0.40.0

package/README.md

@@ -15,7 +15,7 @@ genex sfx "<prompt>"       # generate a sound fx  → prints an asset URL
 genex texture "<prompt>"   # generate a texture   → prints an asset URL
 genex image "<prompt>"     # generate an image    → prints an asset URL
 genex video "<prompt>"     # generate a video     → prints an asset URL
-genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
+genex controller <type>    # character|car|drone|networked-physics → src/controllers/
 genex controller anims <sel…>  # download extra character animation clips (by tag or name) → public/assets/anims/
 ```
 
@@ -184,6 +184,27 @@ GENEX_BROWSER="open -a Safari" genex init
 GENEX_BROWSER="'/Applications/My Browser.app/Contents/MacOS/My Browser'" genex init
 ```
 
+## Crash reporting
+
+When a command hits an **unexpected** error, the CLI reports the crash to Sentry
+so we can fix it. Expected failures (missing token, a rejected API request, bad
+input) are just printed — they're not sent. Before anything leaves your machine
+it's scrubbed: your `GENEX_TOKEN` and any credentials, credential-bearing URLs
+(e.g. the per-push git URL), your home-directory paths and hostname, and
+stack-frame locals are all stripped ([`src/lib/sentry-scrub.ts`](src/lib/sentry-scrub.ts)).
+No IP address or account identity is attached. Only the crash, the command name,
+and your CLI/Node/OS versions are sent.
+
+Opt out any time:
+
+```bash
+export GENEX_TELEMETRY=0     # our switch (on by default)
+export DO_NOT_TRACK=1        # the cross-tool standard — any value disables it
+```
+
+Reporting is also off whenever no DSN is baked into the build (the default in
+local/source runs), so nothing is sent during development.
+
 ## How authorization works
 
 The CLI uses a loopback-redirect flow (the same pattern as `gh auth login` and

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-// src/commands/init.ts
-import path8 from "path";
+// src/instrument.ts
+import * as Sentry from "@sentry/node";
 
 // src/config.ts
 import fs from "fs";
@@ -89,6 +89,107 @@ function isDir(p) {
   }
 }
 
+// src/lib/sentry-scrub.ts
+import os2 from "os";
+var BEARER = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+var URL_CRED = /(https?:\/\/)[^/@\s:]+(?::[^/@\s]*)?@/gi;
+var TOKENISH_KV = /((?:token|secret|password|api[_-]?key|authorization)=)[^&#\s"']+/gi;
+var SENSITIVE_KEY = /token|secret|password|api[_-]?key|authorization|bearer/i;
+function scrubString(s) {
+  return s.replace(URL_CRED, "$1[redacted]@").replace(BEARER, "Bearer [redacted]").replace(TOKENISH_KV, "$1[redacted]");
+}
+function redactHome(s, home = os2.homedir()) {
+  if (!home) return s;
+  return s.split(home).join("~");
+}
+var clean = (s) => redactHome(scrubString(s));
+function scrubEvent(event) {
+  delete event.user;
+  delete event.server_name;
+  if (typeof event.message === "string") event.message = clean(event.message);
+  for (const ex of event.exception?.values ?? []) {
+    if (typeof ex.value === "string") ex.value = clean(ex.value);
+    for (const f of ex.stacktrace?.frames ?? []) {
+      if (typeof f.filename === "string") f.filename = redactHome(f.filename);
+      if (typeof f.abs_path === "string") f.abs_path = redactHome(f.abs_path);
+      delete f.vars;
+    }
+  }
+  if (event.request && typeof event.request.url === "string") {
+    event.request.url = clean(event.request.url);
+  }
+  for (const b of event.breadcrumbs ?? []) {
+    if (typeof b.message === "string") b.message = clean(b.message);
+    const d = b.data;
+    if (d) {
+      for (const k of Object.keys(d)) {
+        if (typeof d[k] === "string") d[k] = clean(d[k]);
+      }
+    }
+  }
+  for (const bag of [event.extra, event.tags]) {
+    if (!bag) continue;
+    for (const k of Object.keys(bag)) {
+      if (SENSITIVE_KEY.test(k)) bag[k] = "[Filtered]";
+      else if (typeof bag[k] === "string") bag[k] = clean(bag[k]);
+    }
+  }
+  return event;
+}
+
+// src/instrument.ts
+var GENEX_CLI_DSN = "https://43efc6f7d16c3e67cad6c60fa8175c20@o4511115493900288.ingest.us.sentry.io/4511706579599360";
+function bakedDsn() {
+  return import.meta.url.includes("/dist/") ? GENEX_CLI_DSN : "";
+}
+function resolveDsn() {
+  return (process.env.GENEX_SENTRY_DSN || bakedDsn()).trim();
+}
+function isTruthy(v) {
+  return v !== void 0 && v.trim() !== "" && !/^(0|false|off|no)$/i.test(v.trim());
+}
+function telemetryDisabled() {
+  if (isTruthy(process.env.DO_NOT_TRACK)) return true;
+  if (process.env.GENEX_TELEMETRY !== void 0 && !isTruthy(process.env.GENEX_TELEMETRY)) return true;
+  if (isTruthy(process.env.GENEX_DISABLE_SENTRY)) return true;
+  return false;
+}
+var dsn = resolveDsn();
+var sentryEnabled = !!dsn && !telemetryDisabled();
+if (sentryEnabled) {
+  Sentry.init({
+    dsn,
+    // release aligns with the AG-757 `x-genex-cli-version` telemetry stream so
+    // the two correlate; environment is prod unless pointed at a non-default API.
+    release: `@genex-ai/cli-demo@${getCliVersion()}`,
+    environment: getApiUrl() === DEFAULT_API_URL ? "production" : "development",
+    // A short-lived CLI has no meaningful tracing workload — errors only.
+    tracesSampleRate: 0,
+    // No IP / user auto-collection (opposite of the server apps' `userInfo: true`).
+    dataCollection: { userInfo: false },
+    // Keep @sentry/node's default onUncaughtException + onUnhandledRejection
+    // integrations (auto-registered) — they catch the fire-and-forget async
+    // paths in lib/updates.ts / lib/deploy.ts that otherwise swallow errors.
+    beforeSend(event) {
+      scrubEvent(event);
+      return event;
+    }
+  });
+}
+async function flushSentry(timeoutMs = 2e3) {
+  if (!sentryEnabled) return;
+  try {
+    await Sentry.flush(timeoutMs);
+  } catch {
+  }
+}
+
+// src/index.ts
+import * as Sentry2 from "@sentry/node";
+
+// src/commands/init.ts
+import path8 from "path";
+
 // src/lib/copy-templates.ts
 import fs2 from "fs/promises";
 import path2 from "path";
@@ -604,10 +705,10 @@ var structuredPrinted = /* @__PURE__ */ new WeakSet();
 function printedStructuredError(res) {
   return structuredPrinted.has(res);
 }
-async function apiFetch(url, init = {}) {
-  const headers = new Headers(init.headers);
+async function apiFetch(url, init2 = {}) {
+  const headers = new Headers(init2.headers);
   if (!headers.has(CLI_VERSION_HEADER)) headers.set(CLI_VERSION_HEADER, getCliVersion());
-  const res = await fetch(url, { ...init, headers });
+  const res = await fetch(url, { ...init2, headers });
   if (res.status === 426) {
     try {
       const body = await res.clone().json();
@@ -1157,7 +1258,7 @@ async function listOwnSlugs(apiUrl, token, log) {
 import { spawn as spawn3 } from "child_process";
 import crypto3 from "crypto";
 import fs9 from "fs/promises";
-import os2 from "os";
+import os3 from "os";
 import path10 from "path";
 function run(cmd, args, env) {
   return new Promise((resolve) => {
@@ -1354,7 +1455,7 @@ async function pushWorktree(cwd, pushUrl, managed, log) {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const gitDir = await fs9.mkdtemp(path10.join(os2.tmpdir(), "genex-source-"));
+  const gitDir = await fs9.mkdtemp(path10.join(os3.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   const ident = {
     GIT_AUTHOR_NAME: "genex",
@@ -2264,7 +2365,12 @@ function formatMb(bytes) {
 }
 
 // src/commands/controller.ts
-var CONTROLLER_KINDS = ["character", "car", "drone"];
+var CONTROLLER_KINDS = [
+  "character",
+  "car",
+  "drone",
+  "networked-physics"
+];
 var SHARED = [
   "shared/math.ts",
   "shared/physics-world.ts",
@@ -2342,6 +2448,23 @@ var CONTROLLER_FILE_SETS = {
       `const drone = new DroneController({ world: physics.world, body, chassis, propellers, config: dronePresets["camera-drone"].config });`,
       `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
     ]
+  },
+  "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");
@@ -2356,7 +2479,7 @@ async function runController(opts) {
   if (!kind || !CONTROLLER_KINDS.includes(kind)) {
     log.error(
       `Missing or unknown controller type${kind ? ` "${kind}"` : ""}. Usage: ${c.cyan(
-        "genex controller <character|car|drone> [--force]"
+        "genex controller <character|car|drone|networked-physics> [--force]"
       )} or ${c.cyan("genex controller anims <tag|clip \u2026>")}`
     );
     process.exitCode = 1;
@@ -2407,7 +2530,7 @@ async function runController(opts) {
   log.plain(c.bold("Next steps"));
   log.plain(
     `  1. ${c.cyan(
-      kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : "npm i @dimforge/rapier3d-compat"
+      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).`
   );
   log.plain(`  2. Load the ${c.cyan(set.skill)} skill for wiring, presets, and tuning.`);
@@ -2540,7 +2663,8 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
-  genex controller <type> [--force]  Install a physics controller (character|car|drone)
+  genex controller <type> [--force]  Install a physics controller
+                                     (character|car|drone|networked-physics)
                                      into src/controllers (+ assets into public/assets).
   genex controller anims <sel \u2026>     Download extra character animation clips by tag or
                                      exact name (sword, stealth, Celebration, \u2026) into
@@ -2619,6 +2743,8 @@ ${c.bold("Environment")}
   GENEX_API_URL        Overrides the default API base URL.
   GENEX_COLYSEUS_URL   Overrides the default multiplayer URL.
   GENEX_BROWSER        Command used to open the browser (falls back to BROWSER).
+  GENEX_TELEMETRY      Set to 0 to disable anonymous crash reporting (Sentry).
+  DO_NOT_TRACK         Standard opt-out; any value disables crash reporting.
 
 ${c.bold("Examples")}
   genex init my-game
@@ -2637,6 +2763,7 @@ ${c.bold("Examples")}
   genex image "neon graffiti tag, spray-paint style" --transparent
   genex video "swirling neon plasma, seamless loop" --loop
   genex controller character
+  genex controller networked-physics
   genex explore "grass"
   genex explore
 `;
@@ -2854,6 +2981,17 @@ async function main() {
   const updateLog = createLogger({ quiet: parsed.options.quiet });
   if (parsed.command !== "init") await syncSkills(updateLog);
   const updateCheck = startUpdateCheck();
+  Sentry2.setTag("command", parsed.command);
+  Sentry2.setTag("cli.version", getCliVersion());
+  Sentry2.setTag("node.version", process.versions.node);
+  Sentry2.setTag("os.platform", process.platform);
+  Sentry2.setContext("runtime", {
+    cliVersion: getCliVersion(),
+    node: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    ci: !!process.env.CI
+  });
   try {
     if (GEN_KINDS.has(parsed.command)) {
       await runGenerate(parsed.command, {
@@ -2891,10 +3029,13 @@ async function main() {
     }
   } finally {
     await reportUpdateNudges(updateCheck, updateLog);
+    await flushSentry();
   }
 }
-main().catch((err) => {
+main().catch(async (err) => {
+  Sentry2.captureException(err);
   const log = createLogger();
   log.error(err instanceof Error ? err.message : String(err));
+  await flushSentry();
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -35,8 +35,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@sentry/node": "^10.63.0"
+  },
   "devDependencies": {
     "@dimforge/rapier3d-compat": "^0.19.3",
+    "@genex-ai/multiplayer": "workspace:*",
     "@pixiv/three-vrm": "^3.5.4",
     "@types/three": "^0.185.0",
     "three": "^0.185.1",

package/templates/controllers/NETWORKING.md

@@ -0,0 +1,29 @@
+# Networking these controllers
+
+These controllers simulate **your own player only** (self-authoritative, zero input
+latency). To show OTHER players' rigs in a multiplayer game, publish a small flat state on
+a fixed tick and play it back on a visual-only remote rig — never instantiate a controller
+or a Rapier body for a remote player.
+
+Install `genex controller networked-physics` for confirmed-authority Rapier pushable and vehicle
+state machines. They use one local fixed-step body: dynamic only for the confirmed owner and a
+kinematic proxy driven directly from the SDK-smoothed remote state otherwise. Do not add a second
+remote lerp or shadow physics simulation.
+
+Use ordinary `set` for continuous movement. Use `me.snap` / `objects.snap` only for a deliberate
+respawn, teleport, goal reset, or vehicle mode edge. Irreversible impulses, seats, reset feedback,
+release, and removal must wait for the confirmed object-control result. The networked helpers watch
+the relay-owned object `epoch` and direct-place Rapier followers on snaps, so a reset cannot create a
+synthetic kinematic sweep through bystanders.
+
+Vehicle seat rules the helper enforces: idle vehicles stay unowned, so a present owner IS the current
+driver — `NetworkedVehicle.enter()` refuses an owned vehicle unless the game passes
+`{ steal: true }`, and `onSeatLost` fires if the relay moves the seat without a clean `exit()`
+(steal, orphan repair, host reset). When a driver disconnects, the relay parks the orphaned vehicle
+on the host — the host should call `releaseOrphanIfHost()` (each vehicle, when it observes itself as
+a non-driving owner) to snap the pose clean and return the vehicle to the idle-unowned state.
+
+The complete recipe (what to publish per controller, remote playback, and genuine simultaneous
+contested physics via the host) lives in the multiplayer skill:
+`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
+any networking code.

package/templates/controllers/character/character-controller.ts

@@ -19,6 +19,14 @@ export type { ControllerUserData };
 
 const clamp = THREE.MathUtils.clamp;
 
+function finiteVec(v: { x: number; y: number; z: number }): boolean {
+  return Number.isFinite(v.x) && Number.isFinite(v.y) && Number.isFinite(v.z);
+}
+
+function finiteQuat(q: { x: number; y: number; z: number; w: number }): boolean {
+  return finiteVec(q) && Number.isFinite(q.w) && Math.hypot(q.x, q.y, q.z, q.w) > 1e-6;
+}
+
 /** Default platform mass-ratio falloff curve: flat 0 until half the character's
  *  mass, then rising to full inheritance at equal-or-heavier platforms. */
 const DEFAULT_CURVE_DATA: CurveData = {
@@ -72,6 +80,12 @@ type ResolvedMovementInput = {
 /** Crouch input interpretation — see {@link CharacterControllerOptions.crouchMode}. */
 export type CrouchMode = "toggle" | "hold";
 
+export interface CharacterRecoveryEvent {
+  reason: "non-finite" | "out-of-bounds";
+  position: { x: number; y: number; z: number };
+  linearVelocity: { x: number; y: number; z: number };
+}
+
 /**
  * Options for {@link CharacterController}. Every value has a tuned default —
  * start from a preset in `./presets.ts` and only override what feels wrong.
@@ -97,6 +111,20 @@ export interface CharacterControllerOptions {
   density?: number;
   /** Allow the body to sleep when at rest. Default `true`. */
   canSleep?: boolean;
+  /** Continuous collision detection for high-speed prop/vehicle impacts. Default `true`. */
+  ccd?: boolean;
+  /**
+   * Optional absolute body-speed ceiling in m/s. Set it comfortably above intended run/jump/fall
+   * speeds; it is a last-resort external-impulse guard, not locomotion tuning.
+   */
+  maxExternalLinearSpeed?: number;
+  /** Optional game-owned arena/bounds predicate. Non-finite poses are rejected regardless. */
+  isPoseAllowed?: (position: Readonly<{ x: number; y: number; z: number }>) => boolean;
+  /**
+   * Called after an unsafe pose was atomically restored to the constructor spawn. Pair this with
+   * `physics.snapBodyInterpolation(body)`, camera reset, and `room.me.snap(...)` when networked.
+   */
+  onRecovery?: (event: CharacterRecoveryEvent) => void;
   /** Initial gravity scale while airborne and not falling. Default `1`. */
   gravityScale?: number;
   /**
@@ -314,6 +342,11 @@ export class CharacterController {
   private readonly counterMoveImpFactor: number;
   private readonly initialGravityScale: number;
   private readonly massRatioFallOffCurve: CurveLUT;
+  private readonly maxExternalLinearSpeed: number | undefined;
+  private readonly isPoseAllowed: CharacterControllerOptions["isPoseAllowed"];
+  private readonly onRecovery: CharacterControllerOptions["onRecovery"];
+  private readonly recoveryPosition = new THREE.Vector3();
+  private readonly recoveryRotation = new THREE.Quaternion();
 
   // ── input state ──
   private readonly movementState: ResolvedMovementInput = {
@@ -531,6 +564,9 @@ export class CharacterController {
     this.applyCounterMoveImp = options.applyCounterMoveImp ?? true;
     this.counterMoveImpFactor = options.counterMoveImpFactor ?? 1;
     this.initialGravityScale = options.gravityScale ?? 1;
+    this.maxExternalLinearSpeed = options.maxExternalLinearSpeed;
+    this.isPoseAllowed = options.isPoseAllowed;
+    this.onRecovery = options.onRecovery;
 
     const curveData = options.massRatioFallOffCurveData ?? DEFAULT_CURVE_DATA;
     this.massRatioFallOffCurve = bakeCurveLUT(curveData.points, curveData.samples ?? 50);
@@ -547,7 +583,10 @@ export class CharacterController {
       .setCanSleep(options.canSleep ?? true)
       .setGravityScale(this.initialGravityScale);
     this._body = world.createRigidBody(bodyDesc);
+    this._body.enableCcd(options.ccd ?? true);
     this._body.userData = options.userData ?? {};
+    this.recoveryPosition.set(position.x, position.y, position.z);
+    this.recoveryRotation.copy(rotation);
 
     // Capsule args order matches the JSX args: (halfHeight, radius).
     const colliderDesc = RAPIER.ColliderDesc.capsule(capsuleHalfHeight, this.capsuleRadius)
@@ -838,6 +877,27 @@ export class CharacterController {
     this.lastInputDir.set(0, 0, 1).applyQuaternion(this.unparkQuat);
     this.parked = false;
     this._body.wakeUp();
+    // Camera/gameplay getters read these caches on the same exit frame, before
+    // the next controller update. Keep body, root, and cached truth aligned.
+    this.updateCharacterInfo();
+  }
+
+  /**
+   * Atomically restore the body, visual root, velocities, and controller pose cache. The caller owns
+   * camera/interpolation/network discontinuity state; use `onRecovery` to update those in this frame.
+   */
+  recover(position = this.recoveryPosition, rotation = this.recoveryRotation): void {
+    const p = finiteVec(position) ? position : this.recoveryPosition;
+    const q = finiteQuat(rotation) ? rotation : this.recoveryRotation;
+    this._body.setTranslation(p, false);
+    this._body.setRotation(q, false);
+    this._body.setLinvel(this.fixedZero, false);
+    this._body.setAngvel(this.fixedZero, false);
+    this.root.position.copy(p);
+    this.root.quaternion.copy(q);
+    this.lastInputDir.set(0, 0, 1).applyQuaternion(q);
+    this.updateCharacterInfo();
+    this._body.wakeUp();
   }
 
   /**
@@ -851,6 +911,7 @@ export class CharacterController {
     // Skip the whole controller loop when disabled or parked
     if (!this.enabled || this.parked) return;
     const characterBody = this._body;
+    if (this.recoverUnsafePose()) return;
     let isSleeping = characterBody.isSleeping();
 
     // Correct frame rate difference
@@ -1028,6 +1089,35 @@ export class CharacterController {
     this.currentAngVelOnUp.copy(this.currentAngVel).projectOnVector(this.characterYAxis);
   }
 
+  /** Recover before any impulses or publication can observe an unsafe pose. */
+  private recoverUnsafePose(): boolean {
+    const p = this._body.translation();
+    const q = this._body.rotation();
+    const v = this._body.linvel();
+    const av = this._body.angvel();
+    const finite = finiteVec(p) && finiteQuat(q) && finiteVec(v) && finiteVec(av);
+    const allowed = finite && (this.isPoseAllowed?.(p) ?? true);
+    if (!finite || !allowed) {
+      const event: CharacterRecoveryEvent = {
+        reason: finite ? "out-of-bounds" : "non-finite",
+        position: { x: p.x, y: p.y, z: p.z },
+        linearVelocity: { x: v.x, y: v.y, z: v.z },
+      };
+      this.recover();
+      this.onRecovery?.(event);
+      return true;
+    }
+    const max = this.maxExternalLinearSpeed;
+    if (max !== undefined && Number.isFinite(max) && max > 0) {
+      const speed = Math.hypot(v.x, v.y, v.z);
+      if (speed > max) {
+        const scale = max / speed;
+        this._body.setLinvel({ x: v.x * scale, y: v.y * scale, z: v.z * scale }, true);
+      }
+    }
+    return false;
+  }
+
   /**
    * Update gravity/upAxis direction and value (upstream l.499-513; the custom
    * gravity-field branch is dropped per the v1 port scope — world gravity may

package/templates/controllers/drone/drone-controller.ts

@@ -356,6 +356,9 @@ export class DroneController {
         this.addPropeller(propellerOptions);
       }
     }
+    // Cache the supplied body's real pose immediately. Without this, getters
+    // and the chassis can remain at zero until the first awake physics step.
+    this.updateVehicleInfo();
   }
 
   // ---- per-frame ----
@@ -595,6 +598,11 @@ export class DroneController {
 
   // ---- internals ----
 
+  /** Refresh cached pose/velocity/axes immediately after an external body placement. */
+  syncFromBody(): void {
+    this.updateVehicleInfo();
+  }
+
   /** Update vehicle collider pos/vel/quat/axis from the rigid body. */
   private updateVehicleInfo(): void {
     const translation = this.bodyRef.translation();

package/templates/controllers/interact/enter-exit.ts

@@ -68,6 +68,8 @@ export interface VehicleUnitLike extends FollowTargetLike {
   readonly bodyXAxis: THREE.Vector3;
   /** World-space body Z axis (live vector). */
   readonly bodyZAxis: THREE.Vector3;
+  /** Refresh cached pose/axes after an external body placement. */
+  syncFromBody(): void;
 }
 
 /**
@@ -479,10 +481,8 @@ export class EnterExitManager {
    * Port of the upstream `computeExitTransform` — exact math and order.
    * Writes `this.exitPos` / `this.exitRot`.
    *
-   * Faithful non-guard: if the vehicle is flipped so bodyZAxis is parallel
-   * to upAxis, projectOnPlane yields a near-zero vector and normalize()
-   * produces NaN — upstream does not guard this either (realistic trigger:
-   * exiting a nose-down drone along its up axis).
+   * A flipped/nose-down vehicle can make bodyZ parallel to up. Establish a
+   * finite fallback basis before normalizing so an exit can never create NaN.
    */
   private computeExitTransform(
     vehicle: VehicleUnitLike,
@@ -491,7 +491,16 @@ export class EnterExitManager {
   ): void {
     this.exitPos.copy(vehicle.currPos).addScaledVector(exitDirection, exitLength);
     const up = vehicle.upAxis;
-    this.exitZAxis.copy(vehicle.bodyZAxis).projectOnPlane(up).normalize();
+    this.exitZAxis.copy(vehicle.bodyZAxis).projectOnPlane(up);
+    if (this.exitZAxis.lengthSq() < 1e-6) {
+      this.exitZAxis.copy(vehicle.bodyXAxis).projectOnPlane(up);
+      if (this.exitZAxis.lengthSq() < 1e-6) {
+        if (Math.abs(up.y) < 0.9) this.exitZAxis.set(0, 1, 0);
+        else this.exitZAxis.set(1, 0, 0);
+        this.exitZAxis.projectOnPlane(up);
+      }
+    }
+    this.exitZAxis.normalize();
     // Cross order matters: X = up x Z. Swapping mirrors the spawn basis.
     this.exitXAxis.crossVectors(up, this.exitZAxis);
     // makeBasis takes COLUMN vectors X, Y, Z.