WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

Galvanorm Next.js - A corporate website for Galvanorm, featuring an interactive 3D catalog viewer. Built with Next.js 14 (App Router), React 18, TypeScript, and Three.js/React Three Fiber for 3D rendering.

Common Commands

Development

npm run dev          # Start development server on http://localhost:3000
npm run build        # Build production bundle
npm run start        # Start production server
npm run lint         # Run ESLint

Installation

npm install          # Install all dependencies (required after cloning)

Architecture Overview

Tech Stack

• Framework: Next.js 14 with App Router
• Language: TypeScript (strict mode enabled)
• 3D Graphics: Three.js via @react-three/fiber and @react-three/drei
• State Management: Jotai (atomic state management)
• Animations: GSAP, Swiper
• Styling: CSS Modules + Global CSS

Application Structure

App Router Layout (app/)

• layout.tsx - Root layout with metadata, CSS/JS includes, Turkish locale
• page.tsx - Main page composing all sections
• Uses Next.js Script component for legacy JS files loaded in specific order

Component Architecture (components/)

Single-page application with section-based components:

• Header.tsx - Navigation header
• HeroSection.tsx - Hero/landing section
• AboutSection.tsx - Company overview
• ServicesSection.tsx - Services offered
• ProjectsSection.tsx - Project showcase
• StatsSection.tsx - Statistics/metrics
• TestimonialsSection.tsx - Customer testimonials
• CatalogSection.tsx - 3D interactive catalog viewer (see below)
• GlobalMapSection.tsx - Geographic presence
• ClientsSection.tsx - Client logos
• FooterSection.tsx - Footer with contact info
• Preloader.tsx, MobileMenu.tsx, OffcanvasMenu.tsx - UI utilities

3D Catalog System (components/Book3D/)

The interactive 3D book/catalog is the core feature of this project. It allows users to view a PDF catalog as a 3D flippable book.

Key Files:

• index.tsx - Main component with:

  • Lazy loading via Intersection Observer
  • Dual rendering modes (embedded view + fullscreen modal)
  • Keyboard shortcuts (Arrow keys for navigation, Escape to close)
  • Sound effects support (optional /audios/page-flip.mp3)
  • Portal-based fullscreen overlay using createPortal

• UI.tsx - State management and configuration:

  • PICTURES_COUNT constant - SET THIS to match your PDF page count
  • Jotai atoms: pageAtom, zoomedAtom, fullscreenAtom
  • Page array generation (front/back pairs)
  • Navigation controls (only shown in fullscreen mode)

• Experience.tsx - Three.js scene setup:

  • Lighting configuration (directional + ambient + environment)
  • OrbitControls with zoom/pan/rotate
  • Float animation wrapper
  • Shadow mapping (2048x2048 resolution)

• Book.tsx - 3D book mesh implementation:

  • Skinned mesh with bone-based page curling animation
  • Dynamic texture loading with format fallback (jpg/png/webp)
  • Page interaction detection
  • Emissive hover effects
  • PBR materials with optional roughness maps

3D Catalog Workflow:

1. PDF pages must be converted to images (JPG recommended)
2. Place in public/textures/:
   • book-cover.jpg - Front cover
   • book-back.jpg - Back cover
   • 1.jpg, 2.jpg, 3.jpg, ... - Interior pages
3. Update PICTURES_COUNT in components/Book3D/UI.tsx
4. Optional: Add book-cover-roughness.jpg for realistic cover material

Texture Loading Logic:

• Attempts multiple image formats automatically (png, jpg, jpeg, webp)
• Special handling for cover/back vs interior pages
• Anisotropic filtering (16x) for high-quality rendering
• sRGB color space for accurate color reproduction

Dynamic Imports & SSR

The 3D Book component uses dynamic import with ssr: false to prevent server-side rendering issues with Three.js:

const Book3D = dynamic(() => import('./Book3D').then(mod => ({ default: mod.Book3D })), {
  ssr: false,
  loading: () => <LoadingComponent />
});

Why: Three.js and WebGL require browser APIs not available during SSR. This pattern is critical for all Three.js components.

Path Aliases

TypeScript configured with @/* mapping to project root:

import Component from '@/components/Component'

Asset Organization

• /public/textures/ - 3D book page images
• /public/images/ - General website images
• /public/css/ - Legacy CSS files (loaded in specific order via layout.tsx)
• /public/js/ - Legacy JavaScript files (loaded via Next.js Script component)
• /public/audios/ - Optional sound effects

Important Development Notes

3D Catalog Page Count Configuration

Before running the project, you MUST:

1. Add PDF page images to public/textures/
2. Set PICTURES_COUNT in components/Book3D/UI.tsx to match your actual page count

Default is 10 pages. If you have 20 pages, change:

const PICTURES_COUNT = 20; // Your actual page count

Adding New 3D Components

When adding any Three.js/React Three Fiber components:

1. Use 'use client' directive at the top of the file
2. Import dynamically with ssr: false when used in pages
3. Wrap in <Suspense> with appropriate fallback
4. Consider Intersection Observer for lazy loading

Script Load Order

The project loads many legacy JS files in a specific order (see app/layout.tsx). Do NOT reorder these scripts without testing thoroughly, as they may have dependencies on each other.

TypeScript Configuration

• Strict mode enabled - All code must pass strict TypeScript checks
• Path aliases: Use @/ for imports from project root
• Module resolution: bundler (for Next.js App Router compatibility)

CSS Architecture

The project uses a hybrid CSS approach:

1. Legacy global CSS files (loaded in specific order)
2. CSS Modules for component-specific styles
3. Inline styles for dynamic 3D UI elements

Do not convert legacy CSS to CSS Modules without careful testing.

State Management

• Jotai is used for 3D book state (page number, zoom state, fullscreen mode)
• Each atom is exported from components/Book3D/UI.tsx
• Use useAtom hook to read/write atom values

Image Optimization Guidelines

For optimal 3D catalog performance:

• Format: JPG (PNG for transparency needs)
• Resolution: 2048x2732px (4:3 aspect ratio)
• File Size: Max 500KB per image
• DPI: 150-300
• Color Profile: sRGB
• Compression: 80-90% quality

Tools: iLovePDF, TinyPNG, Squoosh.app

Project-Specific Files

• 3D-BOOK-INTEGRATION.md - Detailed 3D catalog implementation guide with troubleshooting
• QUICK-START.md - Quick setup guide (Turkish)
• README.md - Standard Next.js boilerplate

Build & Deployment

Standard Next.js deployment:

1. npm run build - Creates optimized production build
2. npm run start - Runs production server
3. Or deploy to Vercel/similar platforms

Important: Ensure public/textures/ is included in deployment and contains all required book page images.

Browser Support

• Modern browsers with WebGL 2.0 support required for 3D features
• Responsive design supports mobile and desktop
• Touch gestures supported for mobile 3D interaction (rotate, zoom, pan)

Known Patterns

Client-Side Only Features

Components using browser APIs (window, document) should:

1. Use 'use client' directive
2. Check typeof window !== "undefined" before accessing window
3. Use useEffect for initialization that requires browser APIs
4. Use suppressHydrationWarning on body tag (already configured)

Fullscreen Modal Pattern

The 3D catalog uses React portals to render fullscreen overlays outside the normal component tree. This pattern allows the book to escape any parent container constraints.

Lazy Loading Pattern

The 3D book uses Intersection Observer to delay 3D rendering until the user scrolls to the catalog section, improving initial page load performance.

Troubleshooting

"Module not found: @react-three/fiber"

Run npm install - dependencies may not be installed

Textures not loading

1. Verify files exist in public/textures/
2. Check file names match exactly (case-sensitive)
3. Check file extensions are lowercase
4. View browser console for 404 errors

3D Book not rendering

1. Check browser has WebGL support
2. Verify dynamic import with ssr: false is used
3. Check console for Three.js errors
4. Ensure textures are present before rendering

Wrong page count

Update PICTURES_COUNT in components/Book3D/UI.tsx to match actual number of PDF pages

Performance issues

1. Optimize texture file sizes (use TinyPNG/Squoosh)
2. Reduce texture resolution if needed
3. Use JPG instead of PNG where possible
4. Check that lazy loading via Intersection Observer is working