2D/3D Canvas with Live Color Customization

Overview

Major feature release implementing the complete 2D/3D uniform builder canvas with live design preview, SVG color manipulation, and real-time 3D product visualization. Users can now select designs, customize colors, and see their changes instantly in both 2D and 3D views.

Features

2D Canvas with Fabric.js

• SVG Design Rendering - Loads design templates as SVG and renders them on a Fabric.js canvas
• Dynamic Color Manipulation - Change colors of specific SVG zones by element ID (primary, secondary, accent)
• High-Resolution Export - Maintains 2048x2048 backing store for UV texture mapping
• Color Zone Detection - Automatically detects available color zones from loaded SVG designs

3D Product Viewer

• Three.js Integration - Full 3D scene using React Three Fiber and Drei
• GLB Model Loading - Loads product 3D models from database
• Real-time Texture Updates - 2D canvas exports as texture to 3D model
• Camera Controls - Orbit controls with zoom, pan, and rotation
• Fabric Material System - PBR materials with normal, displacement, and gloss maps

Live Color Customization

• Color Picker Tabs - Three color selection modes:
  • Teamsport Colors - Team-specific color palettes
  • Default Colors - Standard color library
  • Custom Colors - Manual hex/RGB input
• Real-time Preview - Colors update instantly on both 2D and 3D views
• Color Palette Support - Fetches palettes with colors in a single optimized query

Design Management

• Design Fetching - Loads designs from database filtered by product
• Default Design Selection - Automatically selects default or first available design
• Design Preview Grid - Visual grid of available design templates
• SVG File Support - Designs stored as SVG URLs for dynamic rendering

Performance Optimizations

• Optimized Database Queries - Single query with relationship joins instead of N+1 pattern
• Deferred Canvas Operations - Uses requestIdleCallback for blocking toDataURL() calls
• Debounced Snapshots - 250ms debounce prevents rapid-fire texture captures
• Query Caching - 5-minute stale time prevents unnecessary refetching

Architecture

Component Structure

builder/
├── _components/
│   ├── canvas/
│   │   ├── 2d/           # Fabric.js canvas components
│   │   ├── 3d/           # Three.js scene components
│   │   └── *.tsx         # Canvas panel, toolbar, toggle
│   ├── layout/           # Builder layout components
│   ├── shared/           # Shared components (color picker)
│   └── steps/            # Step content components
└── _lib/
    ├── config/           # Step configuration
    ├── context/          # React context providers
    └── hooks/            # Custom hooks

Context Providers

• BuilderContext - Fullscreen mode, view mode (2D/3D), color zones
• BuilderDataContext - Form state with react-hook-form
• CanvasTextureContext - Texture sharing between 2D canvas and 3D scene
• CameraControlsContext - 3D camera control state

Key Hooks

• useFabricCanvas - Fabric.js canvas initialization and SVG loading
• useBuilderMaterials - Three.js material and texture management
• useDesignsForProduct - Design fetching by product slug
• useColorsForBuilder - Color and palette fetching

Technical Details

Dependencies Added

• fabric - Canvas manipulation library for 2D design editing
• three - 3D graphics library
• @react-three/fiber - React renderer for Three.js
• @react-three/drei - Useful helpers for React Three Fiber

Texture Pipeline

1. User selects/changes colors in step panel
2. Fabric.js canvas updates SVG fill colors
3. Canvas captures snapshot as PNG data URL (deferred)
4. Three.js texture updates in-place from snapshot
5. 3D model re-renders with new texture

Color Zone System

SVG designs use element IDs to define color zones:

• primary - Main body color
• secondary - Secondary panels
• accent - Accent details
• accent2 - Additional accent
• accent3 - Third accent color