🪐 3D Models Showcase SPA

A premium, interactive Single Page Application (SPA) designed to showcase 3D models with keyframe animations, built using React 18, TypeScript, Vite 5, and Tailwind CSS v3, with 3D rendering powered by Three.js, React Three Fiber (R3F), and @react-three/drei.

---

✨ Key Features

• Premium Glassmorphic HUD Panels: Beautiful floating controls overlay utilizing modern backdrop blur and drop-shadow styling parameters.
• Fully Interactive 3D Viewport: OrbitControls-driven camera navigation (pan, zoom, orbit) with soft ContactShadows and a custom grid helper floor.
• Complex Animation Controls: Dynamic discovery of embedded model animations with support for play, pause, time-scaling (speeds at 0.5x, 1.0x, 2.0x), and track resetting.
• Dynamic Catalog & Search: Instant filterable search interface supporting fast metadata lookups and seamless selection transitions.
• WebGL Error Boundaries: Resilient catching of context loss and malformed asset load exceptions with a sleek reset dashboard.
• Optimized Testing Suite: Lightweight mock environment powered by Vitest, bypassing heavy 3D loading to prevent memory limits and finish execution in under 1 second.

---

🛠️ Technology Stack

• Core: React 18.3.1 (compatible with R3F peer dependencies) & TypeScript
• Bundler & Dev Server: Vite 5.x
• 3D Engine: Three.js (v0.160)
• 3D React Layer: @react-three/fiber (v8.x) & @react-three/drei (v9.x)
• Styling: Tailwind CSS (v3.x) & PostCSS
• Icons: lucide-react
• Test Runner: Vitest (v1.3.1) & React Testing Library

---

🚀 Getting Started

📋 Prerequisites

• Node.js v18.x or v20.x+
• npm v9.x+

🔧 Installation

Install the project dependencies using legacy peer resolution to handle React 18 / ESLint configurations:

npm install --legacy-peer-deps

💻 Local Development

Launch the local Vite development server:

npm run dev

Open http://localhost:5173 in your browser to view the application.

🧪 Run Tests

Execute the Vitest suite:

npm run test

📦 Production Build

Compile and optimize assets for deployment:

npm run build

Vite will compile files into the dist/ directory.

---

📂 Project Directory Map

├── public/
│   ├── models/                # *.glb or *.gltf 3D assets
│   ├── thumbnails/            # Thumbnail preview images
│   └── models-metadata.json   # Model inventory database
├── src/
│   ├── components/
│   │   ├── ControlPanel.tsx   # Controls active animation speed, pause/play
│   │   ├── ErrorBoundary.tsx  # Resilient fallback handler for WebGL/load fails
│   │   ├── ModelList.tsx      # Sidebar search & model cards list
│   │   ├── ModelRenderer.tsx  # Renders the GLTF scene and useAnimations mixers
│   │   └── Stage3D.tsx        # Canvas setup, lights, shadows, and neon grid
│   ├── App.tsx                # Main container coordinating viewport states
│   ├── index.css              # Tailwind entry, custom scrollbars, animations
│   └── main.tsx               # DOM entrypoint mounting App

---

⚙️ Extending the Showcase Inventory

You can easily add your own models to the showcase catalog by following these steps:

1. Copy your .gltf or .glb file to the public/models/ folder.
2. Put a preview image for your model in public/thumbnails/.
3. Append a new model object to public/models-metadata.json conforming to this schema:

  {
    "id": "unique-model-id",
    "title": "Model Display Title",
    "description": "A detailed description explaining features and visual assets.",
    "modelUrl": "/models/your-model.gltf",
    "thumbnailUrl": "/thumbnails/your-thumbnail.png",
    "scale": 1.0,
    "position": [0, 0, 0],
    "animations": ["Idle", "Run"]
  }

• scale: Number adjustment to uniform scale the model.
• position: An array [X, Y, Z] specifying offsets to center the model on the grid.
• animations: An array of string keys representing keyframe animation names present inside the GLTF clip timeline.