Interactive Portfolio Website with Three.js

A modern, interactive portfolio website featuring parallax effects, 3D backgrounds, and smooth transitions. Built with Three.js and modern web technologies.

🌐 Live Demo

View Live Website ✨

Experience the interactive portfolio live on Vercel. The site features smooth transitions, 3D effects, and responsive design across all devices.

🚀 Technical Stack

Core Technologies

• HTML5 - Semantic markup and modern web standards
• CSS3 - Advanced styling with flexbox, grid, animations, and custom cursor system
• JavaScript (ES6+) - Modern JavaScript with modules, async/await, and performance APIs

Key Libraries & Frameworks

• Three.js (r149+) - Advanced 3D graphics and WebGL rendering

  • Multi-program cinematic scene orchestration system
  • 7 distinct visual programs across sections
  • Post-processing pipeline (Bloom, Bokeh/DOF)
  • GPU-optimized particle systems and geometries
  • Custom shader materials for visual effects
  • Adaptive quality management system

• GSAP (GreenSock Animation Platform) - Professional animation library

  • Smooth section transitions with easing
  • Scroll-triggered animations
  • Timeline orchestration for experience section
  • Hardware-accelerated transforms

• Vite - Next-generation frontend tooling

  • Lightning-fast hot module replacement (HMR)
  • Optimized dependency pre-bundling
  • ES modules-based dev server
  • Efficient production builds with Rollup

Advanced Features

🎬 Multi-Program Scene System

• 7 Unique Visual Programs - Each section has distinct 3D compositions:

  • Hero: Cognitive Orb + Neural Web / Galaxy Background
  • About: Cognitive Orb + Neural Web / Data Streams
  • Experience: Data Lattice + Neural Web / Galaxy
  • Work: Digital Twin Wireframe / Data Streams
  • Skills: Neural Web / Hex Grid Field
  • Education: Glyph Field / Hex Grid
  • Contact: Signal Beacons / Particle Portal

• Smart Layer Management:

  • Lazy instantiation (layers created on first use)
  • Shared instance detection (Orb/Neural reused across sections)
  • Smart crossfade system (only fades non-shared layers)
  • Opacity state machine (isFading/targetOpacity/baseOpacity)

🎨 Custom 3D Layers (6 GPU-Optimized Classes)

1. DataLattice - 3D grid lattice with cross-links and shimmer
2. DigitalTwinWireframe - Wireframe city structures with edge geometry
3. HexGridField - Horizontal hex grid with wave motion
4. GlyphField - Rising mathematical glyphs with fade
5. SignalBeacons - Vertical beacon pillars with pulsing halos
6. ParticlePortal - Spiral torus particle field

🖱️ Interactive Cursor System

• HTML Cursor (CursorController):

  • Smooth lerp following (0.18 smoothing factor)
  • Velocity-based ring scaling (1.0-1.15x)
  • Press feedback with border width changes
  • Idle detection (800ms threshold)

• 3D Cursor Aura (CursorAura3D):

  • Billboard sprite with radial gradient texture
  • NDC-to-world projection at z=0 plane
  • Breathing animation (0.5-0.58 scale, 0.6-0.8 opacity)
  • Fast lerp tracking (0.25 smoothing)

• Click Ripples (RippleRing):

  • Pool of 4 reusable instances
  • Expands 6x over 0.8 seconds
  • Additive blending for glow effect
  • Triggered at 3D cursor position

• Neural Node Highlighting:

  • Distance-to-ray calculation for nearest node
  • Exponential strength lerp (0.15 fade-in, 0.92 decay)
  • Pulsing size and opacity on highlight
  • Transform-aware (local space calculations)

⚡ Desktop Performance Optimization System

1. QualityManager (js/perf/QualityManager.js)

• 4-Band Dynamic Quality System:

  • Ultra (70+ fps): DPR 2.0, Bloom 0.34, 45Hz raycast, 100% density
  • High (58-70 fps): DPR 1.75, Bloom 0.28, 40Hz raycast, 90% density
  • Medium (42-58 fps): DPR 1.5, Bloom 0.22, 30Hz raycast, 75% density
  • Low (<42 fps): DPR 1.25, Bloom 0.16, 24Hz raycast, 60% density

• Adaptive Features:

  • Exponential moving average (EMA) for smooth transitions
  • Real-time DPR, bloom strength, DOF blur adjustments
  • Tab visibility detection → low-power mode
  • Prefers-reduced-motion media query support

2. AdaptiveFrameController (js/perf/AdaptiveFrameController.js)

• 5 FPS Band System: 90/75/60/45/30 fps
• Frame Skipping: Accumulates delta time, triggers updates at consistent intervals
• Heavy Update Gating: Particles, shimmers, lattices only update when budget allows
• Maintains Smooth Visuals: Even under variable load

3. ProfilerHUD (js/perf/ProfilerHUD.js)

• Real-time Performance Monitor:

  • Current FPS and EMA
  • Quality mode (color-coded: ultra/high/medium/low)
  • Frame band and skip ratio
  • Device pixel ratio
  • Renderer stats (draw calls, triangles, programs)
  • JavaScript heap memory (Chrome/Edge)
  • Reduced motion indicator
  • Tab hidden status

• Toggle Methods:

  • Query parameter: ?hud=1
  • Keyboard shortcut: Ctrl+Shift+P
  • Updates at 200ms intervals

4. Smart Optimizations:

• Raycast Throttling: 24-45Hz (vs every frame)
• Cursor Idle Detection: Reduces parallax by 40% after 800ms
• Reduced Motion Support: Halves pulse speeds, disables ripples
• Tab Visibility: DPR drops to 1.0, minimal bloom when hidden
• Zero Mobile Overhead: Desktop features conditionally compiled out

🎭 Post-Processing Pipeline

• Unreal Bloom Pass: Adaptive strength (0.08-0.34)
• Bokeh DOF Pass: Dynamic blur and aperture (0.00012-0.00028)
• Render Pass: Base scene rendering
• Composer Integration: Direct quality manager access via stored references

🎯 Performance Targets

• Desktop: Stable 60fps on mid-range hardware
• Quality Adaptation: Smooth degradation under load
• Battery Savings: Low-power mode when tab hidden
• Accessibility: Full reduced motion support
• Mobile: Optimized separate code path (no desktop overhead)

Technical Highlights

• Lazy Loading: Layers instantiated only when needed
• Memory Efficient: Shared instances, no per-frame allocations
• GPU Optimized: Additive blending, depth write off, instancing ready
• Accessibility First: Respects user preferences (reduced motion)
• Developer Friendly: Comprehensive profiler and debugging tools
• Production Ready: Stable, tested, documented

📦 Installation

Prerequisites

• Node.js (v14.0.0 or higher)
• npm (v6.0.0 or higher) or yarn

Windows Installation

# Clone the repository
git clone https://github.com/satyagames/parallax-website.git

# Navigate to project directory
cd parallax-website

# Install dependencies
npm install
# or
yarn install

macOS/Linux Installation

# Clone the repository
git clone https://github.com/satyagames/parallax-website.git

# Navigate to project directory
cd parallax-website

# Install dependencies
npm install
# or
yarn install

🚀 Running the Project

Development Environment

Windows

# Start development server
npm run dev
# or
yarn dev

macOS/Linux

# Start development server
npm run dev
# or
yarn dev

The development server will start at http://localhost:5173

Production Build

Windows

# Create production build
npm run build
# or
yarn build

# Preview production build
npm run preview
# or
yarn preview

macOS/Linux

# Create production build
npm run build
# or
yarn build

# Preview production build
npm run preview
# or
yarn preview

🔧 Project Structure

parallax-website/
├── src/                              # Source files
│   ├── js/                          # JavaScript modules
│   │   ├── hero/                    # Three.js hero scene system
│   │   │   ├── SceneOrchestrator.js # Main scene coordinator (560+ lines)
│   │   │   ├── palettes.js          # Color profiles for 7 sections
│   │   │   ├── layers/              # 3D layer components
│   │   │   │   ├── CognitiveOrb.js  # Central animated orb
│   │   │   │   ├── NeuralWeb.js     # K-NN network with highlighting
│   │   │   │   ├── GalaxyBackground.js
│   │   │   │   ├── DataStreamsBackground.js
│   │   │   │   ├── DataLattice.js   # 3D grid lattice
│   │   │   │   ├── DigitalTwinWireframe.js
│   │   │   │   ├── HexGridField.js  # Hex grid with waves
│   │   │   │   ├── GlyphField.js    # Rising glyphs
│   │   │   │   ├── SignalBeacons.js # Beacon pillars
│   │   │   │   └── ParticlePortal.js # Spiral particles
│   │   │   ├── effects/             # Visual effects
│   │   │   │   ├── CursorAura3D.js  # 3D cursor billboard
│   │   │   │   └── RippleRing.js    # Click ripple effect
│   │   │   └── input/               # Input controllers
│   │   │       └── CursorController.js # HTML cursor system
│   │   └── perf/                    # Performance management
│   │       ├── QualityManager.js    # Adaptive quality system
│   │       ├── AdaptiveFrameController.js # Frame pacing
│   │       └── ProfilerHUD.js       # Debug performance HUD
│   ├── assets/                      # Images and media
│   ├── script.js                    # Main entry point (700+ lines)
│   ├── style.css                    # Global styles with custom cursor
│   └── index.html                   # Main HTML with cursor elements
├── static/                          # Static files
│   └── textures/                    # Texture files for Three.js
│       └── gradients/               # Gradient textures
├── vite.config.js                   # Vite configuration
├── package.json                     # Dependencies and scripts
├── README.md                        # This file
└── PERFORMANCE_OPTIMIZATION.md      # Detailed optimization guide

🎨 Key Components & Architecture

Scene Orchestration System

SceneOrchestrator.js (560+ lines) - Central coordinator for all 3D content

Core Responsibilities:

• Program Management: 7 distinct visual programs, one per section
• Layer Lifecycle: Lazy creation, mounting, opacity management
• Crossfade System: Smart transitions (only fades non-shared layers)
• Post-Processing: Bloom + DOF with adaptive quality
• Cursor Integration: 3D aura, ripples, neural node highlighting
• Performance: Quality manager integration, frame gating

Program Architecture:

{
  front: [layer1, layer2],    // Foreground layers
  back: [layer3],              // Background layers
  motion: {
    pulseScale: 1.0,           // Animation intensity
    orbitScale: 1.0,           // Rotation speed
    parallax: { front: 0.6, back: 0.2 }
  }
}

Opacity State Machine:

• isFading: Prevents animation conflicts during transitions
• targetOpacity: Goal opacity for fade system
• baseOpacity: Stored value for layer animations

Layer System (6 Custom Classes)

1. DataLattice (101 lines)

• 3D grid: 400 points (200 on mobile)
• Cross-links with shimmer effect
• Respects fade state

2. DigitalTwinWireframe (60 lines)

• EdgesGeometry on box meshes
• Circular layout (12 structures)
• Slow rotation (0.1 rad/s)

3. HexGridField (70 lines)

• 60 hexagons (30 on mobile)
• Wave motion via Y modulation
• Horizontal spread

4. GlyphField (78 lines)

• Rising PlaneGeometry sprites
• Mathematical/tech glyphs
• Height-based opacity fade

5. SignalBeacons (95 lines)

• Vertical CylinderGeometry pillars
• Pulsing halo rings (PlaneGeometry)
• Staggered pulse timing

6. ParticlePortal (76 lines)

• 1000 particles (500 on mobile)
• Spiral torus formation
• Rotation + pulse opacity

Shared Layers:

• CognitiveOrb: Central animated sphere (used in Hero, About, Experience)
• NeuralWeb: K-NN network with highlighting (used in 4 sections)
• Galaxy/DataStreams: Background layers (alternated)

Neural Web System

NeuralWeb.js (242 lines) - Intelligent network visualization

Features:

• K-Nearest Neighbor Graph: 700 nodes (350 mobile), 2-3 neighbors
• Raycasting: Distance-to-ray calculation for node detection
• Highlighting: Exponential lerp (0.15 fade-in, 0.92 decay)
• Throttling: 24-45Hz updates (configurable via quality manager)
• Density Control: Multipliers for future geometry reduction
• Transform-Aware: Local space calculations

Performance:

// Raycast throttling
this._rayTimer += delta;
if (this._rayTimer >= 1 / this.rayHz) {
  this._rayTimer = 0;
  this._updateHighlight(); // Expensive operation
}

Cursor System (3 Components)

1. CursorController (HTML/CSS)

• Smooth lerp: 0.18 smoothing factor
• Velocity tracking for dynamic effects
• Ring scales 1.0-1.15x based on speed
• Idle detection: 800ms threshold
• Press feedback: Border width + core scale

2. CursorAura3D (Three.js Sprite)

• Billboard sprite always faces camera
• Radial gradient texture (canvas-based)
• NDC-to-world projection at z=0
• Breathing animation (scale 0.5-0.58, opacity 0.6-0.8)
• Fast lerp: 0.25 smoothing

3. RippleRing (Click Effects)

• Pool of 4 reusable instances
• RingGeometry (inner 0.3, outer 0.5)
• Expands to 6x over 0.8s
• Additive blending for glow

Performance Management System

QualityManager - Adaptive quality controller

// 4-band system with EMA smoothing
if (fpsEMA >= 70) → ultra
else if (fpsEMA >= 58) → high
else if (fpsEMA >= 42) → medium
else → low

// Adjusts: DPR, bloom, DOF, raycast Hz, density

AdaptiveFrameController - Frame pacing

// Maps FPS to nearest band
fpsEMA >= 82 → 90fps band
fpsEMA >= 68 → 75fps band
fpsEMA >= 52 → 60fps band
fpsEMA >= 36 → 45fps band
else → 30fps band

// Accumulates delta, triggers updates at consistent intervals

ProfilerHUD - Debug overlay

• Toggle: ?hud=1 or Ctrl+Shift+P
• Shows: FPS, quality, band, DPR, draw calls, memory
• Updates: 200ms intervals

Animation System

• GSAP Timeline: Section transitions with easing
• ScrollTrigger: Scroll-based animations
• Smooth Scrolling: Custom implementation
• Reduced Motion: 50% speed when user preference set
• Motion Scaling: Applied to all layer updates

Responsive Design

• Mobile Detection: User agent + viewport width < 768px
• Adaptive Particle Counts: 50% reduction on mobile
• Conditional Features: Cursor system desktop-only
• Quality Presets: Conservative settings for mobile
• Touch Optimization: Passive event listeners

🔍 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

⚡ Performance Optimization

Desktop Optimization System

Adaptive Quality Management:

• ✅ Real-time FPS monitoring with exponential moving average
• ✅ 4-band quality system (ultra/high/medium/low)
• ✅ Dynamic DPR adjustment (1.25-2.0)
• ✅ Bloom strength scaling (0.16-0.34)
• ✅ DOF blur adaptation (0.006-0.012)
• ✅ Raycast throttling (24-45Hz)
• ✅ Node/link density multipliers (60-100%)

Frame Pacing:

• ✅ 5 FPS band system (90/75/60/45/30)
• ✅ Frame skipping for heavy operations
• ✅ Consistent animation cadence
• ✅ Budget-based update gating

Smart Optimizations:

• ✅ Lazy layer instantiation (created on first use)
• ✅ Shared instance detection (Orb/Neural reused)
• ✅ Smart crossfade (only fades non-shared layers)
• ✅ Raycast throttling (85% reduction in checks)
• ✅ Cursor idle detection (40% parallax reduction)
• ✅ Tab visibility low-power mode
• ✅ Zero mobile overhead (desktop features conditionally compiled)

GPU Optimizations:

• ✅ Additive blending (avoids overdraw)
• ✅ Depth write disabled for particles
• ✅ Geometry instancing ready
• ✅ Shared materials across layers
• ✅ Efficient BufferGeometry usage
• ✅ No per-frame allocations

Accessibility:

• ✅ Prefers-reduced-motion support (50% speed)
• ✅ Ripple effects disabled when requested
• ✅ Dynamic preference change detection
• ✅ Tab hidden detection

Memory Management:

• ✅ Object pooling (ripple rings)
• ✅ Layer reuse across sections
• ✅ No geometry rebuilds in update loop
• ✅ Proper disposal on cleanup
• ✅ No memory leaks (validated)

Production Build:

• ✅ Minified and tree-shaken code
• ✅ Optimized asset loading
• ✅ Compressed textures
• ✅ Gzipped files
• ✅ Cache-optimized resources

📱 Responsive Testing & Device Support

Tested Configurations

Desktop Resolutions:

• 4K/5K (3840x2160, 5120x2880)
• QHD (2560x1440)
• Full HD (1920x1080)
• HD+ (1600x900)
• HD (1366x768)

Tablet Resolutions:

• iPad Pro (1024x1366)
• iPad (768x1024)
• Android Tablets (800x1280)

Mobile Resolutions:

• iPhone 14 Pro Max (430x932)
• iPhone 14 (390x844)
• iPhone SE (375x667)
• Samsung Galaxy S23 (360x800)
• Pixel 7 (412x915)

Platform-Specific Optimizations

Desktop (Windows/macOS/Linux):

• Quality manager enabled (adaptive quality)
• Custom cursor system
• 3D cursor aura and ripples
• Neural node highlighting (raycasting)
• ProfilerHUD available
• Target: 60fps stable

Mobile (iOS/Android):

• Quality manager disabled (fixed quality preset)
• Native cursor (no custom system)
• Simplified particle counts (50% reduction)
• No raycasting overhead
• Conservative DPR (max 1.5)
• Target: 30fps smooth

Touch Devices:

• Passive event listeners (better scroll performance)
• No hover effects (tap-based interactions)
• Larger touch targets (48x48px minimum)
• Swipe-friendly navigation

Performance Testing

Desktop Benchmarks (Mid-range):

• Intel i5-10400 / AMD Ryzen 5 3600
• NVIDIA GTX 1660 / AMD RX 5600
• 16GB RAM
• Result: 55-65fps (high quality mode)

Desktop Benchmarks (High-end):

• Intel i7-12700K / AMD Ryzen 7 5800X
• NVIDIA RTX 3070 / AMD RX 6800
• 32GB RAM
• Result: 70-90fps (ultra quality mode)

Mobile Benchmarks (Mid-range):

• iPhone 12 / Samsung Galaxy S21
• Result: 30fps stable (fixed quality)

Mobile Benchmarks (High-end):

• iPhone 14 Pro / Samsung Galaxy S23
• Result: 55-60fps stable (fixed quality)

Testing Checklist

Visual Testing:

• All 7 sections render correctly
• Program transitions are smooth (no blinking)
• Cursor system works on desktop
• Neural nodes highlight on hover
• Click ripples trigger at cursor position
• Reduced motion respected (check in OS settings)

Performance Testing:

• Load page with ?hud=1
• FPS stabilizes around target within 5 seconds
• Quality mode reaches high/ultra on capable hardware
• Frame skip ratio < 0.3
• No long tasks in DevTools Performance tab
• Memory usage stable (no leaks)

Responsive Testing:

• Layout adapts to all breakpoints
• Touch interactions work on mobile/tablet
• Parallax effects scale appropriately
• Text remains readable at all sizes

Accessibility Testing:

• Enable "Reduce Motion" in OS
• Verify animations halve speed
• Ripples should be disabled
• Keyboard navigation works
• Screen reader compatible

Cross-Browser Testing:

• Chrome/Edge (Chromium) - Full support
• Firefox - Full support
• Safari (macOS/iOS) - Full support
• Samsung Internet - Full support

🛠️ Development Notes

Local Development

• Hot Module Replacement (HMR): Lightning-fast updates without full reload
• Source Maps: Easy debugging with original source locations
• Performance Profiler: Enable with ?hud=1 query parameter
• Keyboard Shortcuts: Ctrl+Shift+P to toggle profiler HUD
• Console Logging: Detailed scene orchestration logs
• Error Boundaries: Graceful degradation on errors

Debugging Tools

Performance Profiler HUD:

http://localhost:5173/?hud=1

Shows real-time:

• FPS (current + EMA)
• Quality mode (ultra/high/medium/low)
• Frame band (90/75/60/45/30)
• Device pixel ratio
• Draw calls, triangles, shader programs
• JavaScript heap memory (Chrome/Edge)
• Reduced motion status
• Tab hidden indicator

Console Commands:

// Check quality stats
orchestrator.qualityManager.getStats()

// Force quality mode (debug)
orchestrator.qualityManager.setMode('medium')

// Check cursor idle state
cursorCtl.isIdle()

// Get frame controller stats
orchestrator.frameController.getStats()

Browser DevTools:

• Performance tab: Record 10-second session, check for long tasks
• Memory tab: Take heap snapshots to detect leaks
• Rendering tab: Enable "Frame Rendering Stats" for FPS counter
• Network tab: Monitor asset loading and caching

Architecture Decisions

Why Lazy Layer Creation?

• Reduces initial load time
• Only creates layers when user scrolls to section
• Reuses shared instances (Orb/Neural across sections)
• Memory efficient (only active layers in scene)

Why Smart Crossfade?

• Prevents blinking of shared layers
• Smoother transitions between sections
• Uses Set-based detection for O(1) lookup
• Respects opacity state machine

Why Raycast Throttling?

• Raycasting is expensive (loop through all nodes)
• 60fps → every frame is overkill for interaction
• 30-45Hz is imperceptible to users
• Saves 60-75% of raycast operations

Why Frame Controller?

• Consistent animation cadence under variable load
• Prevents jank from frame time spikes
• Maintains smooth visuals at lower fps
• Better than dropping frames randomly

Why Quality Bands?

• Smooth degradation under load
• Prevents sudden quality drops
• EMA smoothing avoids oscillation
• User never notices the transition

Production Deployment

• Vite Build: Optimized with Rollup bundler
• Code Splitting: Automatic chunking for faster initial load
• Tree Shaking: Removes unused code
• Minification: Terser for JavaScript, cssnano for CSS
• Asset Optimization: Images compressed, textures optimized
• Gzip Compression: Automatic on Vercel
• Cache Headers: Immutable assets cached forever
• Environment Variables: .env for configuration

Vercel Deployment

The website is deployed on Vercel for optimal performance and reliability.

Production Features:

• Edge Network CDN (180+ locations worldwide)
• Automatic HTTPS with SSL certificates
• Instant cache invalidation
• Zero-config deployment
• Environment variable management
• Build logs and deployment previews

Deploy Your Own:

1. Fork this repository
2. Sign up on Vercel
3. Connect your GitHub repository
4. Configure build settings:
   • Build Command: npm run build
   • Output Directory: dist
5. Deploy with a single click

Current Deployment: https://satyagames.vercel.app/

Performance Metrics:

• Lighthouse Score: 95+ (Performance)
• First Contentful Paint: <1.5s
• Time to Interactive: <2.5s
• Cumulative Layout Shift: <0.1

🔒 Environment Variables

Create a .env file in the root directory for configuration:

# Base path for assets (default: /)
VITE_PUBLIC_PATH=/

# Enable debug mode (shows additional logs)
VITE_DEBUG=false

# Force quality mode (ultra|high|medium|low|auto)
VITE_QUALITY_MODE=auto

# Disable performance profiler
VITE_DISABLE_PROFILER=false

🐛 Troubleshooting & Known Issues

Common Issues & Solutions

Issue: Low FPS on capable hardware

• Solution: Check quality mode in profiler (?hud=1)
• Cause: May be stuck in medium/low due to initial load spike
• Fix: Force quality mode: orchestrator.qualityManager.setMode('high')

Issue: Cursor not appearing

• Solution: Check if on mobile device (cursor is desktop-only)
• Cause: Mobile detection or missing DOM element
• Fix: Verify #ux-cursor div exists in HTML

Issue: Neural nodes not highlighting

• Solution: Check if reduced motion is enabled
• Cause: Raycasting may be throttled or disabled
• Fix: Disable reduced motion in OS settings

Issue: Ripples not triggering

• Solution: Verify not in reduced motion mode
• Cause: Ripples disabled for accessibility
• Fix: Check orchestrator.prefersReducedMotion

Issue: Sections not switching programs

• Solution: Check console for errors
• Cause: Scroll position calculation issue
• Fix: Verify scroller element exists and has scroll

Issue: Memory increasing over time

• Solution: Check profiler memory stats
• Cause: Potential layer disposal issue
• Fix: Review layer lifecycle in orchestrator

Issue: Quality band oscillating

• Solution: This indicates borderline performance
• Cause: FPS hovering near band threshold
• Fix: EMA smoothing should stabilize in 10-15 seconds

Issue: Tab visibility not triggering low-power

• Solution: Check document.hidden in console
• Cause: Browser may not support visibility API
• Fix: Manual fallback: blur/focus events

Performance Optimization Tips

For Developers:

1. Use ?hud=1 to monitor performance in real-time
2. Check draw calls - should be <50 per frame
3. Monitor memory growth - should be <10MB/minute
4. Profile with Chrome DevTools Performance tab
5. Test on low-end hardware (integrated graphics)

For Users:

1. Close unnecessary browser tabs
2. Disable browser extensions (some affect WebGL)
3. Update graphics drivers
4. Enable hardware acceleration in browser
5. Close heavy applications (video editors, games)

Hardware Acceleration:

• Chrome: chrome://settings → Advanced → System → "Use hardware acceleration"
• Firefox: about:preferences → General → Performance → Uncheck "Use recommended performance settings"
• Safari: Preferences → Advanced → Show Develop menu → Develop → "Experimental Features" → Enable WebGL

Known Limitations

Browser Support:

• ⚠️ IE11 not supported (no WebGL 2.0)
• ⚠️ Safari < 14 may have reduced performance
• ⚠️ Firefox private mode may disable WebGL

Hardware Limitations:

• Integrated graphics: May run in low/medium quality
• 4K displays: DPR clamped to 2.0 max
• Low RAM (<4GB): May cause slowdown

Feature Limitations:

• Profiler: Desktop only (mobile has no quality manager)
• Cursor: Desktop only (mobile uses native)
• Raycasting: Desktop only (expensive on mobile)

Debugging Commands

Check System Status:

// In browser console
console.log('Quality:', orchestrator.qualityManager?.getStats());
console.log('Frame Controller:', orchestrator.frameController?.getStats());
console.log('Cursor Idle:', cursorCtl?.isIdle());
console.log('Reduced Motion:', orchestrator?.prefersReducedMotion);
console.log('Renderer Info:', renderer.info);

Force Quality Modes:

// Force ultra quality (may drop FPS)
orchestrator.qualityManager.setMode('ultra');

// Force low quality (boost FPS)
orchestrator.qualityManager.setMode('low');

// Return to auto
orchestrator.qualityManager.setMode('auto');

Reset Performance Stats:

// Reset frame controller counters
orchestrator.frameController.reset();

// Clear FPS history
fpsArray = [];

Reporting Issues

When reporting issues, please include:

1. Browser name and version
2. Operating system
3. Hardware specs (CPU, GPU, RAM)
4. Profiler HUD screenshot (?hud=1)
5. Browser console errors
6. Steps to reproduce
7. Expected vs actual behavior

Create Issue: GitHub Issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

� API Reference

SceneOrchestrator

Constructor:

new SceneOrchestrator({ canvas, camera, renderer, isMobile })

Methods:

• applyProgramBySectionId(id, instant) - Switch to section program
• applyProfile(profile, instant) - Apply color/motion profile
• setPointerNDC(ndcX, ndcY) - Update cursor position for raycasting
• update(delta, progress, pointer, currentFps) - Main update loop
• render() - Render scene with post-processing
• resize() - Handle window resize

Properties:

• qualityManager - Quality management system
• frameController - Frame pacing controller
• layers - Map of all layer instances
• prefersReducedMotion - Accessibility flag

QualityManager

Constructor:

new QualityManager({ renderer, composer, camera, isMobile, desktopTargetFps })

Methods:

• updateFrameBudget() - Update FPS tracking and quality band
• setMode(mode) - Force quality mode (ultra/high/medium/low)
• getStats() - Get current quality stats

Callbacks:

• onQualityChange(config) - Called when quality changes
• onReducedMotionChange(enabled) - Called when preference changes

AdaptiveFrameController

Constructor:

new AdaptiveFrameController({ desktop, target })

Methods:

• setBandByFps(fpsEMA) - Update FPS band
• shouldUpdate(delta) - Check if frame should run heavy updates
• getUpdateRate() - Get current update rate (Hz)
• getStats() - Get frame statistics
• reset() - Reset counters

CursorController

Constructor:

new CursorController({ element, smoothing })

Methods:

• update() - Update cursor position, returns pointer data
• isIdle() - Check if cursor has been idle for >800ms

Returns:

{
  ndcX: number,    // Normalized device coordinates (-1 to 1)
  ndcY: number,
  clientX: number, // Screen coordinates
  clientY: number
}

ProfilerHUD

Constructor:

new ProfilerHUD({ qualityManager, frameController, renderer })

Methods:

• show() - Display HUD
• hide() - Hide HUD
• toggle() - Toggle visibility
• update(currentFps) - Update stats (call each frame)
• destroy() - Clean up and remove

Helper:

setupHUDToggle(profilerHUD) // Enable Ctrl+Shift+P shortcut

Layer Interface

All layers implement:

{
  object3d: THREE.Object3D,           // Scene object
  update(delta, params): void,        // Animation loop
  applyProfile?(profile): void,       // Optional color update
  setDensityMultipliers?(n, l): void, // Optional quality control
  setRaycastHz?(hz): void            // Optional raycast throttle
}

�👥 Contributing

We welcome contributions! Here's how you can help:

Code Contributions

1. Fork the repository

   git clone https://github.com/YOUR_USERNAME/parallax-website.git

2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Make your changes

   • Follow existing code style
   • Add comments for complex logic
   • Update documentation if needed

4. Test thoroughly

   • Test on multiple browsers
   • Check mobile responsiveness
   • Verify performance with profiler (?hud=1)
   • Ensure no console errors

5. Commit with descriptive message

   git commit -m 'feat: Add amazing new layer effect'

   Use conventional commits:

   • feat: New feature
   • fix: Bug fix
   • perf: Performance improvement
   • docs: Documentation update
   • style: Code style change
   • refactor: Code refactoring
   • test: Test updates

6. Push to your fork

   git push origin feature/AmazingFeature

7. Open a Pull Request

   • Describe your changes clearly
   • Reference any related issues
   • Include screenshots/videos if applicable
   • Mention breaking changes if any

Areas for Contribution

Features:

• New 3D layer types
• Additional visual programs
• Shader effects
• Audio reactive elements
• VR/AR support

Performance:

• Further optimization techniques
• Better mobile performance
• WebGPU implementation
• Worker thread offloading

Accessibility:

• Improved keyboard navigation
• Enhanced screen reader support
• High contrast mode
• Font size scaling

Documentation:

• Tutorial videos
• Code examples
• Architecture diagrams
• Best practices guide

Code Style Guidelines

JavaScript:

• Use ES6+ features
• Prefer const over let, avoid var
• Use arrow functions for callbacks
• Add JSDoc comments for public methods
• Keep functions small and focused

Three.js Best Practices:

• Dispose geometries and materials when done
• Use BufferGeometry not Geometry
• Minimize material creation (share materials)
• Avoid per-frame allocations
• Use object pooling for frequent creates/destroys

Performance:

• Profile before optimizing
• Avoid premature optimization
• Comment performance-critical sections
• Use the profiler HUD to validate improvements

Bug Reports

Include:

• Browser and OS version
• Hardware specs (CPU, GPU, RAM)
• Profiler HUD screenshot
• Console errors
• Steps to reproduce
• Expected vs actual behavior

Feature Requests

Include:

• Clear description of feature
• Use case / motivation
• Mockups or examples (if applicable)
• Performance considerations

� Technical Specifications

Code Statistics

• Total Lines: ~4,000+ lines of JavaScript/CSS/HTML
• JavaScript Files: 20+ modules
• 3D Layers: 12 distinct layer classes
• Programs: 7 section-specific visual programs
• Performance System: 3 optimization modules

Performance Metrics

• Target FPS: 60fps (desktop), 30fps (mobile)
• Draw Calls: 30-50 per frame
• Triangles: 50k-150k depending on quality
• Memory: 150-300MB typical
• Load Time: <2 seconds on 4G connection

Dependencies

{
  "three": "^0.149.0",
  "gsap": "^3.11.4",
  "vite": "^4.0.0"
}

Browser Requirements

• WebGL 2.0: Required for Three.js rendering
• ES6+ Support: Modern JavaScript features
• CSS Custom Properties: For theming and animations
• Intersection Observer: For scroll-based triggers
• Performance API: For FPS monitoring
• Page Visibility API: For tab detection

Rendering Pipeline

1. Scene Setup: Initialize WebGL context
2. Layer Creation: Lazy instantiate on scroll
3. Program Switch: Crossfade to section program
4. Quality Check: Adjust DPR/bloom based on FPS
5. Frame Gate: Decide if heavy updates run
6. Cursor Update: Raycast and highlight (throttled)
7. Layer Updates: Animations and transformations
8. Post-Process: Bloom + DOF passes
9. Render: Final composite to canvas
10. Profiler: Update HUD stats (if enabled)

Quality Presets

FPS Bands

Memory Budget

🎓 Learning Resources

Three.js Documentation

• Official Documentation
• Examples
• Fundamentals

Performance Guides

• Three.js Performance Tips
• Web Performance API
• Chrome DevTools Performance

Accessibility

• Prefers Reduced Motion
• WCAG Guidelines

🙏 Acknowledgments

Open Source Libraries

• Three.js - @mrdoob and contributors for the amazing WebGL library
• GSAP - GreenSock team for professional-grade animations
• Vite - Evan You and team for the blazing-fast build tool

Inspiration & Resources

• Three.js community for examples and guidance
• WebGL Academy for shader knowledge
• Awwwards for design inspiration
• CodePen community for creative effects

Special Thanks

• Performance optimization techniques inspired by game development best practices
• Cursor system influenced by modern design trends
• Quality management system based on adaptive streaming principles