Common failures and fixes. Draft pass — expand with real issues found during the dry-run (Phase 4) and on the day.

Setup / install

• Wrong Node version → fnm use 22 / nvm use 22; the repo has an .nvmrc.
• pnpm: command not found → corepack enable, reopen terminal (or use npm).
• Install hangs / slow on wifi → this is why we install at home; tether to a phone, or grab the local mirror / USB fallback.
• pnpm verify fails on deps → re-run pnpm install.

Runtime

• Black / blank canvas → enable browser hardware acceleration; update GPU drivers; try another browser.
• Nothing visible → no light in the scene, or the camera isn't pointed at the object.
• Low FPS → big/un-optimized model (mention draco/meshopt); too many objects; close other GPU-heavy tabs.
• Port already in use → Vite auto-bumps; use the URL it prints.

Git / checkpoints

• git switch refused (local changes) → pnpm step … stashes for you; or commit / git stash first.
• "Where did my code go?" → it's in a labeled stash: git stash list → git stash pop.
• Checkpoints not showing → make sure you git cloned (not degit); pnpm steps reads local + remote branches.

Per-demo gotchas

• models: assets must live in /public and be referenced by URL (not imported); use <Center> if scale/position is off.
• physics: the floor must be a fixed RigidBody; cap spawned bodies; turn on <Physics debug> to see colliders.
• mini: hover state belongs in component state, not the render loop; meshes need visible geometry to receive pointer events.

Still stuck?