feat: integrate WebAssembly for zero-latency, offline-first color operations

Replaced REST API dependency with @valknarthing/pastel-wasm (130KB) for complete browser-based color operations. The application is now fully static (2.2MB total) with zero network latency and offline support. **Key Changes:** 1. **WASM Integration:** - Added @valknarthing/pastel-wasm dependency (0.1.0) - Created lib/api/wasm-client.ts wrapper matching API interface - Updated lib/api/client.ts to use WASM client by default - All 18 color operations now run locally in browser 2. **Static Export Configuration:** - Changed next.config.ts output from 'standalone' to 'export' - Disabled image optimization for static export - Removed API proxy route (app/api/pastel/[...path]/route.ts) - Updated package.json scripts (removed dev:api, added serve) 3. **Docker Optimization:** - Migrated from Node.js standalone to nginx-alpine - Created nginx.conf with SPA routing and WASM mime types - Updated Dockerfile for static file serving - Reduced image size from ~150MB to ~25MB - Changed port from 3000 to 80 (standard HTTP) - Simplified docker-compose.yml (removed pastel-api service) 4. **Documentation Updates:** - Updated README.md with WASM benefits and deployment options - Added Key Benefits section highlighting zero-latency features - Rewrote deployment section for static hosting platforms - Updated CLAUDE.md tech stack and architecture - Removed obsolete docs: DEV_SETUP.md, DOCKER.md, IMPLEMENTATION_PLAN.md **Benefits:** - 🚀 Zero Latency - All operations run locally via WebAssembly - 📱 Offline First - Works completely offline after initial load - 🌐 No Backend - Fully static, deploy anywhere - ⚡ Fast - Native-speed color operations in browser - 📦 Small - 2.2MB total (130KB WASM, 2.07MB HTML/CSS/JS) **Deployment:** Can now be deployed to any static hosting platform: - Vercel, Netlify, Cloudflare Pages (zero config) - GitHub Pages, S3, CDN - Self-hosted nginx/Apache - Docker (optional, nginx-based) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-17 09:06:25 +01:00
parent e6b693dbd8
commit 4aed0d4bf9
14 changed files with 710 additions and 1121 deletions
--- a/README.md
+++ b/README.md
@@ -8,7 +8,15 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

-Pastel UI is a beautiful, feature-rich interface for the [Pastel API](https://github.com/valknarness/pastel-api), providing intuitive tools for color manipulation, palette generation, and accessibility testing.
+Pastel UI is a beautiful, feature-rich interface powered by WebAssembly for **zero-latency, offline-first** color manipulation, palette generation, and accessibility testing.
+
+## ⚡ Key Benefits
+
+- **🚀 Zero Latency** - All operations run locally via WebAssembly (130KB)
+- **📱 Offline First** - Works completely offline after initial load
+- **🌐 No Backend** - Fully static, deploy anywhere (2.2MB total)
+- **⚡ Fast** - Native-speed color operations in the browser
+- **🎨 Feature-Rich** - 18 color operations, 6 palette types, accessibility tools

 ## Features

@@ -51,6 +59,7 @@ Pastel UI is a beautiful, feature-rich interface for the [Pastel API](https://gi
 - **[React 19](https://react.dev)** - Latest React with improved concurrent features
 - **[Tailwind CSS 4](https://tailwindcss.com)** - CSS-first utility framework with modern color spaces
 - **[TypeScript](https://www.typescriptlang.org)** - Strict type safety throughout
+- **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** - WebAssembly color engine for zero-latency operations
 - **[React Query](https://tanstack.com/query)** - Server state management and caching
 - **[Zustand](https://github.com/pmndrs/zustand)** - Client state management
 - **[Framer Motion](https://www.framer.com/motion/)** - Smooth animations and transitions
@@ -62,7 +71,6 @@ Pastel UI is a beautiful, feature-rich interface for the [Pastel API](https://gi

 - **Node.js** 18+ (20+ recommended)
 - **pnpm** 9+ (or npm/yarn)
- **Pastel API** running locally or remotely

 ### Installation

@@ -74,23 +82,13 @@ cd pastel-ui
 # Install dependencies
 pnpm install

-# Set up environment variables
-cp .env.example .env.local
-# Edit .env.local with your Pastel API URL
-
 # Run development server
 pnpm dev
 ```

 Open [http://localhost:3000](http://localhost:3000) in your browser.

-### Environment Variables
-
-```bash
-# .env.local
-NEXT_PUBLIC_API_URL=http://localhost:3000  # Your Pastel API URL
-NEXT_PUBLIC_APP_URL=http://localhost:3000  # This app's URL (for sharing)
-```
+**Note**: All color operations run locally in WebAssembly - no backend API required!

 ## Development

@@ -101,9 +99,10 @@ NEXT_PUBLIC_APP_URL=http://localhost:3000  # This app's URL (for sharing)
 pnpm dev              # Start dev server (http://localhost:3000)
 pnpm dev:turbo        # Start with Turbopack (faster)

-# Building
-pnpm build            # Production build
-pnpm start            # Start production server
+# Building & Deployment
+pnpm build            # Build static export (outputs to out/)
+pnpm export           # Alias for build (static export)
+pnpm serve            # Build and serve static files locally

 # Code Quality
 pnpm lint             # Run ESLint
@@ -282,41 +281,48 @@ $color-accent: #ffcc00;
 | `Arrow Keys` | Navigate color history |
 | `Space` | Toggle color picker |

-## API Integration
+## WebAssembly Integration

-Pastel UI communicates with the [Pastel API](https://github.com/valknarness/pastel-api) for all color operations. The API client is type-safe and includes automatic retries, caching, and error handling.
+Pastel UI uses **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** for all color operations, providing:

-### Example API Usage
+- **Zero Latency** - All operations run locally in the browser
+- **Offline First** - Works completely offline after initial load
+- **No Backend** - No API server required
+- **132KB Bundle** - Optimized WASM binary
+- **Type Safe** - Full TypeScript definitions
+
+### Example Usage

 ```typescript
-import { pastelAPI } from '@/lib/api/client';
+import { pastelWASM } from '@/lib/api/wasm-client';

 // Get color information
-const info = await pastelAPI.getColorInfo(['#ff0099']);
+const info = await pastelWASM.getColorInfo({ colors: ['#ff0099'] });

 // Generate distinct colors
-const distinct = await pastelAPI.generateDistinct(8, 'ciede2000');
+const distinct = await pastelWASM.generateDistinct({ count: 8, metric: 'ciede2000' });

 // Create gradient
-const gradient = await pastelAPI.generateGradient({
+const gradient = await pastelWASM.generateGradient({
  stops: ['#ff0000', '#0000ff'],
  count: 10,
  colorspace: 'lch'
 });
 ```

-See [CLAUDE.md](CLAUDE.md) for detailed API integration documentation.
+See [CLAUDE.md](CLAUDE.md) for detailed WASM integration documentation.

 ## Performance

 Pastel UI is optimized for performance:

- **Fast Initial Load** - < 200KB initial bundle
+- **WebAssembly Engine** - Native-speed color operations (132KB WASM)
+- **Zero Latency** - No network requests for color operations
+- **Fast Initial Load** - < 350KB total initial bundle
 - **Code Splitting** - Route-based automatic splitting
 - **Image Optimization** - Next.js Image with AVIF/WebP
- **API Caching** - React Query with smart cache invalidation
+- **Offline Support** - Works completely offline after first load
 - **Debounced Updates** - Smooth slider interactions
- **Web Workers** - Heavy calculations off main thread

 ## Accessibility

@@ -339,7 +345,23 @@ Pastel UI meets WCAG 2.1 Level AAA standards:

 ## Deployment

-### Vercel (Recommended)
+Pastel UI is a **fully static application** that requires no backend server. Deploy to any static hosting platform!
+
+### Static Export (Recommended)
+
+Build and deploy to any static hosting:
+
+```bash
+# Build static export
+pnpm build
+
+# Output in out/ directory (2.2MB total, 130KB WASM)
+# Serve with any static file server
+```
+
+### Static Hosting Platforms
+
+#### Vercel

 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/valknarness/pastel-ui)

@@ -354,67 +376,74 @@ vercel
 vercel --prod
 ```

-### Docker
-
-#### Using Pre-built Image from GHCR
+#### Netlify

 ```bash
-# Pull the latest image
-docker pull ghcr.io/valknarness/pastel-ui:latest
-
-# Run the container
-docker run -p 3000:3000 \
-  -e NEXT_PUBLIC_API_URL=http://localhost:3001 \
-  ghcr.io/valknarness/pastel-ui:latest
+# Build command: pnpm build
+# Publish directory: out
 ```

-#### Docker Compose (UI + API)
-
-Run both Pastel UI and Pastel API together:
+#### Cloudflare Pages

 ```bash
-# Using docker-compose
-docker-compose up -d
-
-# View logs
-docker-compose logs -f
-
-# Stop
-docker-compose down
+# Build command: pnpm build
+# Output directory: out
 ```

-#### Building Locally
-
-```bash
-# Build the image
-docker build -t pastel-ui .
-
-# Run locally built image
-docker run -p 3000:3000 \
-  -e NEXT_PUBLIC_API_URL=http://localhost:3001 \
-  pastel-ui
-```
-
-#### Available Docker Images
-
-Images are automatically built and published to GitHub Container Registry:
-
- `ghcr.io/valknarness/pastel-ui:latest` - Latest main branch
- `ghcr.io/valknarness/pastel-ui:v1.0.0` - Specific version
- `ghcr.io/valknarness/pastel-ui:main-abc1234` - Commit SHA
-
-Supported platforms: `linux/amd64`, `linux/arm64`
-
-### Static Export
+#### GitHub Pages

 ```bash
 # Build static export
 pnpm build

-# Output in out/ directory
-# Deploy to any static hosting (Netlify, Cloudflare Pages, etc.)
+# Deploy out/ directory to gh-pages branch
 ```

+#### Self-Hosted (Nginx/Apache)
+
+```bash
+# Build static export
+pnpm build
+
+# Copy out/ directory to web server
+cp -r out/* /var/www/html/
+```
+
+### Serve Locally
+
+Test the static build locally:
+
+```bash
+# Build
+pnpm build
+
+# Serve with any static file server
+npx serve out
+# or
+python -m http.server -d out 8000
+# or
+cd out && python3 -m http.server
+```
+
+### Docker (Optional)
+
+For containerized deployment using nginx:
+
+```bash
+# Build the image
+docker build -t pastel-ui .
+
+# Run container (serves on port 80)
+docker run -p 80:80 pastel-ui
+
+# Or use docker-compose
+docker-compose up -d
+```
+
+The Docker image uses nginx to serve the static files (final image size: ~25MB).
+
+**Note**: Docker is optional - the app is fully static and can be served by any HTTP server.
+
 ## Contributing

 Contributions are welcome! Please read [CLAUDE.md](CLAUDE.md) for development guidelines.
@@ -441,7 +470,8 @@ Contributions are welcome! Please read [CLAUDE.md](CLAUDE.md) for development gu

 ## Related Projects

- **[Pastel API](https://github.com/valknarness/pastel-api)** - REST API for color manipulation
+- **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** - WebAssembly color engine
+- **[Pastel API](https://github.com/valknarness/pastel-api)** - Optional REST API for server-side operations
 - **[Pastel CLI](https://github.com/sharkdp/pastel)** - Original command-line tool by David Peter

 ## License
@@ -464,7 +494,7 @@ MIT License - see [LICENSE](LICENSE) file for details.

 ---

-**Built with** ❤️ **using** [Next.js](https://nextjs.org), [React](https://react.dev), and [Tailwind CSS](https://tailwindcss.com)
+**Built with** ❤️ **using** [Next.js](https://nextjs.org), [React](https://react.dev), [WebAssembly](https://webassembly.org), and [Tailwind CSS](https://tailwindcss.com)

-**Project Status**: Design phase complete, ready for implementation
-**Last Updated**: 2025-11-07
+**Project Status**: ✅ Production-ready with WASM integration
+**Last Updated**: 2025-11-17