WALL·E Gallery

Browse beautiful wallpapers from GitHub repositories with lightning-fast performance and elegant design

---

✨ Features

🎨 Multi-Source Support

• Multiple Engines - Browse wallpapers from any public GitHub repository
• 11 Built-in Collections - Pre-configured repositories with thousands of wallpapers
• Custom Engines - Add your own favorite wallpaper repositories
• Easy Switching - Seamlessly switch between different wallpaper sources

🖼️ Gallery Experience

• Masonry Layout - Beautiful, responsive grid that adapts to image sizes
• 3 Thumbnail Sizes - Choose between small, medium, or large grid views
• Category Navigation - Browse by organized categories
• Smart Sorting - Sort by name or file size, ascending or descending
• Powerful Search - Find wallpapers instantly by name or category
• Infinite Scroll - Smooth, lazy-loaded browsing experience

🚀 Performance

• Lightning Fast - 99.5% bandwidth reduction with optimized thumbnails
• Progressive Loading - Blur-to-sharp transitions for smooth experience
• Intelligent Caching - Per-engine data caching for instant switching
• Memory Efficient - 90% memory reduction vs loading full resolution

🎯 User Experience

• Fullscreen Preview - View and download wallpapers in full quality
• Dark/Light Mode - Toggle themes with persistent preference
• Persistent Settings - All preferences saved (theme, size, sort, engine)
• Responsive Design - Works beautifully on all devices
• Keyboard Shortcuts - ESC to close modal, intuitive navigation

🛠️ Tech Stack

Built with modern web technologies for optimal performance:

• React 19 - Latest React with concurrent features
• TypeScript - Full type safety throughout the codebase
• Vite - Lightning-fast build tool and dev server
• Tailwind CSS v3 - Utility-first styling with custom theme
• Lucide React - Beautiful, customizable icons
• GitHub API - Direct repository integration
• wsrv.nl - Image optimization proxy

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview

The app will be available at http://localhost:5173/

📁 Project Structure

wall-e-gallery/
├── src/
│ ├── components/ # React components
│ │ ├── Button.tsx
│ │ ├── Input.tsx
│ │ ├── Sidebar.tsx
│ │ ├── SearchBar.tsx
│ │ ├── MasonryGallery.tsx
│ │ ├── ImageModal.tsx
│ │ └── InfiniteScrollTrigger.tsx
│ ├── hooks/ # Custom React hooks
│ │ ├── useTheme.ts
│ │ └── useInfiniteScroll.ts
│ ├── lib/ # Utilities and services
│ │ ├── utils.ts
│ │ └── github-api.ts
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts
│ ├── App.tsx # Main app component
│ ├── main.tsx # App entry point
│ └── index.css # Global styles
├── public/ # Static assets
└── ...config files

🔧 How It Works

The app uses a sophisticated engine system to browse wallpapers from any GitHub repository:

1. Engine Selection - Choose from built-in engines or add custom repositories
2. Tree Fetching - GitHub API fetches the complete repository structure
3. Smart Caching - Per-engine caching minimizes API calls and enables instant switching
4. Image Optimization - Thumbnails generated on-the-fly via wsrv.nl proxy (10MB → 50KB)
5. Progressive Loading - Gallery shows thumbnails, full-res loads only in modal
6. Client-side Operations - All filtering, sorting, and searching happen instantly on cached data

API Endpoints

GitHub API:
https://api.github.com/repos/{owner}/{repo}/git/trees/{sha}?recursive=1
Raw Images:
https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}
Optimized Thumbnails:
https://wsrv.nl/?url={encoded-url}&w={width}&q={quality}&output=webp

⚡ Performance Optimizations

The app implements multiple performance strategies to handle large wallpaper collections efficiently:

Image Optimization

• Image Proxy Service - Uses wsrv.nl to generate optimized thumbnails (400px width, 80% quality, WebP format)
• Progressive Loading - Displays thumbnails first, then loads full resolution only in modal
• Blur-to-Sharp Transition - Smooth visual effect during image loading
• Lazy Loading - Browser-native lazy loading with Intersection Observer
• WebP Format - Automatic conversion to WebP for better compression (50-80% smaller)

Memory Management

• Thumbnail-only Gallery - Gallery shows only 400px thumbnails, not full 4K+ images
• On-demand Full Resolution - Full res images loaded only when viewing in modal
• Virtual Scrolling Ready - Component architecture supports virtual scrolling for thousands of images
• Intersection Observer - Efficient viewport detection with 200px root margin

Rendering Performance

• React.memo & useMemo - Optimized re-renders
• Infinite Scroll - Loads 20 images at a time instead of all at once
• CSS Columns - Hardware-accelerated masonry layout (no JS calculation)
• Debounced Search - Prevents excessive filtering operations

Network Optimization

• Repository Tree Caching - GitHub API response cached to minimize requests
• CDN Delivery - All images served through GitHub CDN and wsrv.nl proxy
• Parallel Loading - Multiple images load simultaneously
• Smart Preloading - Images preload just before entering viewport

📊 Performance Metrics

• Bandwidth Savings - 99.5% reduction (10MB → 50KB per image)
• Memory Usage - 90% reduction with thumbnail-only gallery
• Initial Load - ~200ms framework load
• First Paint - < 1 second with thumbnails

🌐 Browser Support

Works on all modern browsers supporting:

• ES2020+ JavaScript features
• CSS Grid and Flexbox
• Intersection Observer API
• WebP image format

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Setting up the development environment
• Code style guidelines
• Pull request process

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Icons by Lucide
• Image optimization by wsrv.nl

---

Built with ❤️ using React, TypeScript, and Tailwind CSS

⭐ Star this repo if you find it useful!