@buildcores/render-client 1.4.0 → 1.5.0

package/dist/index.js

@@ -142,6 +142,57 @@ function useBouncePatternProgress(enabled = true) {
     return { value, isBouncing };
 }
 
+/**
+ * Hook for continuous 360° spin animation with smooth interpolation support.
+ *
+ * @param enabled - Whether the animation is enabled
+ * @param duration - Duration in ms for one full rotation (default: 10000ms = 10 seconds)
+ * @param totalFrames - Total number of frames in the sprite (default: 72)
+ * @returns Object with current frame, next frame, and blend factor for smooth interpolation
+ */
+function useContinuousSpin(enabled = true, duration = 10000, totalFrames = 72) {
+    const [result, setResult] = react.useState({
+        frame: 0,
+        nextFrame: 1,
+        blend: 0
+    });
+    const startTime = react.useRef(null);
+    // Use refs to avoid stale closures in useAnimationFrame
+    const totalFramesRef = react.useRef(totalFrames);
+    const durationRef = react.useRef(duration);
+    // Keep refs in sync with props
+    react.useEffect(() => {
+        totalFramesRef.current = totalFrames;
+    }, [totalFrames]);
+    react.useEffect(() => {
+        durationRef.current = duration;
+    }, [duration]);
+    framerMotion.useAnimationFrame((time) => {
+        if (!enabled) {
+            if (startTime.current !== null) {
+                startTime.current = null;
+            }
+            return;
+        }
+        if (startTime.current === null) {
+            startTime.current = time;
+        }
+        const elapsed = time - startTime.current;
+        const currentDuration = durationRef.current;
+        const currentTotalFrames = totalFramesRef.current;
+        // Calculate progress through the full rotation (0 to 1)
+        const progress = (elapsed % currentDuration) / currentDuration;
+        // Convert to fractional frame position
+        const exactFrame = progress * currentTotalFrames;
+        const currentFrame = Math.floor(exactFrame) % currentTotalFrames;
+        const nextFrame = (currentFrame + 1) % currentTotalFrames;
+        // Blend is the fractional part - how far between current and next frame
+        const blend = exactFrame - Math.floor(exactFrame);
+        setResult({ frame: currentFrame, nextFrame, blend });
+    });
+    return result;
+}
+
 // API Configuration
 const API_BASE_URL = "https://www.renderapi.buildcores.com";
 // API Endpoints
@@ -217,6 +268,8 @@ const createRenderBuildJob = async (request, config) => {
         ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
         ...(request.cameraOffsetX !== undefined ? { cameraOffsetX: request.cameraOffsetX } : {}),
         ...(request.gridSettings ? { gridSettings: request.gridSettings } : {}),
+        // Include frame quality for sprite rendering
+        ...(request.frameQuality ? { frameQuality: request.frameQuality } : {}),
     };
     const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD, config), {
         method: "POST",
@@ -412,6 +465,7 @@ const createRenderByShareCodeJob = async (shareCode, config, options) => {
         ...(options?.showGrid !== undefined ? { showGrid: options.showGrid } : {}),
         ...(options?.cameraOffsetX !== undefined ? { cameraOffsetX: options.cameraOffsetX } : {}),
         ...(options?.gridSettings ? { gridSettings: options.gridSettings } : {}),
+        ...(options?.frameQuality ? { frameQuality: options.frameQuality } : {}),
     };
     const response = await fetch(url, {
         method: "POST",
@@ -639,28 +693,41 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                     profile: currentInput.profile,
                     showGrid: currentInput.showGrid,
                     cameraOffsetX: currentInput.cameraOffsetX,
-                    gridSettings: currentInput.gridSettings
+                    gridSettings: currentInput.gridSettings,
+                    frameQuality: currentInput.frameQuality
                 });
+                // Set metadata BEFORE sprite URL to avoid race condition
+                // (image load starts immediately when spriteSrc changes)
+                const rows = currentInput.frameQuality === 'high' ? 12 : 6;
+                setSpriteMetadata({ cols: 12, rows, totalFrames: 12 * rows });
                 setSpriteSrc((prevSrc) => {
                     if (prevSrc && prevSrc.startsWith("blob:")) {
                         URL.revokeObjectURL(prevSrc);
                     }
                     return spriteUrl;
                 });
-                setSpriteMetadata({ cols: 12, rows: 6, totalFrames: 72 });
                 return;
             }
             // Handle parts-based rendering (creates new build)
             const currentParts = currentInput.parts;
             const mode = options?.mode ?? "async";
+            const frameQuality = currentInput.frameQuality;
+            const rows = frameQuality === 'high' ? 12 : 6;
             if (mode === "experimental") {
                 const response = await renderSpriteExperimental({
                     ...currentParts,
                     showGrid: currentInput.showGrid,
                     cameraOffsetX: currentInput.cameraOffsetX,
                     gridSettings: currentInput.gridSettings,
+                    frameQuality,
                 }, apiConfig);
                 const objectUrl = URL.createObjectURL(response.sprite);
+                // Set sprite metadata BEFORE sprite URL to avoid race condition
+                setSpriteMetadata({
+                    cols: response.metadata?.cols || 12,
+                    rows: response.metadata?.rows || rows,
+                    totalFrames: response.metadata?.totalFrames || 12 * rows,
+                });
                 // Clean up previous sprite URL before setting new one
                 setSpriteSrc((prevSrc) => {
                     if (prevSrc && prevSrc.startsWith("blob:")) {
@@ -668,12 +735,6 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                     }
                     return objectUrl;
                 });
-                // Set sprite metadata
-                setSpriteMetadata({
-                    cols: response.metadata?.cols || 12,
-                    rows: response.metadata?.rows || 6,
-                    totalFrames: response.metadata?.totalFrames || 72,
-                });
             }
             else {
                 // Async job-based flow: request sprite format and use returned URL
@@ -683,15 +744,16 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                     showGrid: currentInput.showGrid,
                     cameraOffsetX: currentInput.cameraOffsetX,
                     gridSettings: currentInput.gridSettings,
+                    frameQuality,
                 }, apiConfig);
+                // Set metadata BEFORE sprite URL to avoid race condition
+                setSpriteMetadata({ cols: 12, rows, totalFrames: 12 * rows });
                 setSpriteSrc((prevSrc) => {
                     if (prevSrc && prevSrc.startsWith("blob:")) {
                         URL.revokeObjectURL(prevSrc);
                     }
                     return spriteUrl;
                 });
-                // No metadata from async endpoint; keep defaults
-                setSpriteMetadata({ cols: 12, rows: 6, totalFrames: 72 });
             }
         }
         catch (error) {
@@ -714,6 +776,7 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                 a.profile === b.profile &&
                 a.showGrid === b.showGrid &&
                 a.cameraOffsetX === b.cameraOffsetX &&
+                a.frameQuality === b.frameQuality &&
                 gridSettingsEqual;
         }
         if (a.type === 'parts' && b.type === 'parts') {
@@ -722,6 +785,7 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
             return arePartsEqual(a.parts, b.parts) &&
                 a.showGrid === b.showGrid &&
                 a.cameraOffsetX === b.cameraOffsetX &&
+                a.frameQuality === b.frameQuality &&
                 gridSettingsEqual;
         }
         return false;
@@ -897,7 +961,7 @@ const useZoomPan = ({ displayWidth, displayHeight, minScale = 1, maxScale = 4, }
     };
 };
 
-const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, cameraOffsetX, gridSettings, }) => {
+const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, cameraOffsetX, gridSettings, animationMode = 'bounce', spinDuration = 10000, interactive = true, frameQuality, }) => {
     const canvasRef = react.useRef(null);
     const containerRef = react.useRef(null);
     const [img, setImg] = react.useState(null);
@@ -915,6 +979,7 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
                 showGrid,
                 cameraOffsetX,
                 gridSettings,
+                frameQuality,
             };
         }
         return {
@@ -923,12 +988,15 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             showGrid,
             cameraOffsetX,
             gridSettings,
+            frameQuality,
         };
-    }, [shareCode, parts, showGrid, cameraOffsetX, gridSettings]);
+    }, [shareCode, parts, showGrid, cameraOffsetX, gridSettings, frameQuality]);
     // Use custom hook for sprite rendering
     const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(renderInput, apiConfig, undefined, useSpriteRenderOptions);
-    const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed);
     const total = spriteMetadata ? spriteMetadata.totalFrames : 72;
+    // Animation hooks - only one will be active based on animationMode
+    const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed && animationMode === 'bounce');
+    const spinResult = useContinuousSpin(bouncingAllowed && animationMode === 'spin360', spinDuration, total);
     const cols = spriteMetadata ? spriteMetadata.cols : 12;
     const rows = spriteMetadata ? spriteMetadata.rows : 6;
     const frameRef = react.useRef(0);
@@ -936,9 +1004,13 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
         displayWidth: displayW,
         displayHeight: displayH,
     });
-    // Image/frame sizes
+    // Image/frame sizes - only calculate if image dimensions match expected metadata
+    // This prevents using stale image with new metadata during transitions
     const frameW = img ? img.width / cols : 0;
     const frameH = img ? img.height / rows : 0;
+    // Track expected rows to detect stale images
+    const expectedRowsRef = react.useRef(rows);
+    expectedRowsRef.current = rows;
     // ---- Load sprite image ----
     react.useEffect(() => {
         if (!spriteSrc) {
@@ -946,12 +1018,18 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             setIsLoading(true);
             return;
         }
+        // Clear current image immediately when source changes to prevent 
+        // using old image with new metadata
+        setImg(null);
         setIsLoading(true);
+        setBouncingAllowed(false);
         const i = new Image();
         i.decoding = "async";
         i.loading = "eager";
         i.src = spriteSrc;
         i.onload = () => {
+            // Only set the image if rows haven't changed since we started loading
+            // This prevents race conditions where metadata updates mid-load
             setImg(i);
             setIsLoading(false);
             // Start bouncing animation after delay
@@ -963,9 +1041,16 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             setImg(null);
             setIsLoading(false);
         };
-    }, [spriteSrc]);
-    // ---- Drawing function ----
-    const draw = react.useCallback((frameIndex) => {
+        // Cleanup: if this effect re-runs (due to spriteSrc or rows change), 
+        // the new effect will clear the image
+        return () => {
+            // Abort loading if component updates before load completes
+            i.onload = null;
+            i.onerror = null;
+        };
+    }, [spriteSrc, rows]);
+    // ---- Drawing function with optional cross-fade interpolation ----
+    const draw = react.useCallback((frameIndex, nextFrameIndex, blend) => {
         const cnv = canvasRef.current;
         if (!cnv || !img || !frameW || !frameH)
             return;
@@ -980,26 +1065,54 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             cnv.width = targetW;
             cnv.height = targetH;
         }
-        // Snap to integer frame (never between tiles)
-        let n = Math.round(frameIndex) % total;
-        if (n < 0)
-            n += total;
-        const r = Math.floor(n / cols);
-        const c = n % cols;
-        // Use integer source rects to avoid sampling bleed across tiles
-        const sx = Math.round(c * frameW);
-        const sy = Math.round(r * frameH);
+        // Calculate destination dimensions (letterboxing)
         const sw = Math.round(frameW);
         const sh = Math.round(frameH);
+        const frameAspect = sw / sh;
+        const canvasAspect = targetW / targetH;
+        let drawW, drawH;
+        if (frameAspect > canvasAspect) {
+            drawW = targetW;
+            drawH = targetW / frameAspect;
+        }
+        else {
+            drawH = targetH;
+            drawW = targetH * frameAspect;
+        }
+        // Apply zoom scale
+        drawW *= scale;
+        drawH *= scale;
+        // Center in canvas
+        const drawX = (targetW - drawW) / 2;
+        const drawY = (targetH - drawH) / 2;
         ctx.clearRect(0, 0, targetW, targetH);
         ctx.imageSmoothingEnabled = true;
         ctx.imageSmoothingQuality = "high";
-        const scaledW = targetW * scale;
-        const scaledH = targetH * scale;
-        const offsetX = -((scaledW - targetW) / 2);
-        const offsetY = -((scaledH - targetH) / 2);
-        ctx.drawImage(img, sx, sy, sw, sh, offsetX, offsetY, scaledW, scaledH);
-    }, [img, frameW, frameH, displayW, displayH, cols, total, scale]);
+        // Helper to draw a specific frame
+        const drawFrame = (frameIdx, opacity) => {
+            let n = Math.round(frameIdx) % total;
+            if (n < 0)
+                n += total;
+            const r = Math.floor(n / cols);
+            const c = n % cols;
+            const sx = Math.round(c * frameW);
+            const sy = Math.round(r * frameH);
+            ctx.globalAlpha = opacity;
+            ctx.drawImage(img, sx, sy, sw, sh, drawX, drawY, drawW, drawH);
+        };
+        // Cross-fade interpolation for smooth animation
+        if (nextFrameIndex !== undefined && blend !== undefined && blend > 0.01) {
+            // Draw current frame at full opacity first
+            drawFrame(frameIndex, 1);
+            // Then overlay next frame with blend opacity for smooth transition
+            drawFrame(nextFrameIndex, blend);
+            ctx.globalAlpha = 1; // Reset
+        }
+        else {
+            // Single frame draw (no interpolation)
+            drawFrame(frameIndex, 1);
+        }
+    }, [img, frameW, frameH, displayW, displayH, cols, rows, total, scale]);
     const { isDragging, handleMouseDown, handleTouchStart, hasDragged } = useSpriteScrubbing(canvasRef, total, {
         mouseSensitivity,
         touchSensitivity,
@@ -1012,23 +1125,30 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
         setIsLoading(true);
         setBouncingAllowed(false);
     }, []);
-    // Auto-rotate when bouncing is allowed and not dragged
+    // Auto-rotate when animation is allowed and user hasn't manually dragged
     react.useEffect(() => {
-        if (hasDragged.current || !img)
+        if ((interactive && hasDragged.current) || !img)
             return;
-        // Calculate frame based on progress value (similar to video time calculation)
-        const frame = ((progressValue / 5) * total) % total;
-        frameRef.current = frame;
-        draw(frame);
-    }, [progressValue, hasDragged, img, total, draw]);
+        if (animationMode === 'spin360') {
+            // Continuous 360 spin with cross-fade interpolation for smoothness
+            frameRef.current = spinResult.frame;
+            draw(spinResult.frame, spinResult.nextFrame, spinResult.blend);
+        }
+        else {
+            // Bounce animation (no interpolation needed - it pauses between movements)
+            const frame = ((progressValue / 5) * total) % total;
+            frameRef.current = frame;
+            draw(frame);
+        }
+    }, [progressValue, spinResult, hasDragged, img, total, draw, animationMode, interactive]);
     // Reset zoom when sprite changes or container size updates
     react.useEffect(() => {
         resetZoom();
     }, [spriteSrc, displayW, displayH, resetZoom]);
-    // Add native wheel event listener to prevent scrolling AND handle zoom
+    // Add native wheel event listener to prevent scrolling AND handle zoom (only when interactive)
     react.useEffect(() => {
         const container = containerRef.current;
-        if (!container)
+        if (!container || !interactive)
             return;
         const handleNativeWheel = (event) => {
             event.preventDefault();
@@ -1056,7 +1176,7 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
         return () => {
             container.removeEventListener('wheel', handleNativeWheel);
         };
-    }, [handleZoomWheel, scale, displayH]);
+    }, [handleZoomWheel, scale, displayH, interactive]);
     // Initial draw once image is ready or zoom changes
     react.useEffect(() => {
         if (img && !isLoading) {
@@ -1080,16 +1200,19 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             height: displayH,
             backgroundColor: "black",
             overflow: "hidden",
-        }, children: [img && (jsxRuntime.jsx("canvas", { ref: canvasRef, onMouseDown: handleMouseDown, onTouchStart: handleCanvasTouchStart, style: {
+        }, children: [img && (jsxRuntime.jsx("canvas", { ref: canvasRef, onMouseDown: interactive ? handleMouseDown : undefined, onTouchStart: interactive ? handleCanvasTouchStart : undefined, style: {
                     width: displayW,
                     height: displayH,
-                    cursor: isDragging ? "grabbing" : "grab",
-                    touchAction: "none", // Prevents default touch behaviors like scrolling
+                    cursor: interactive ? (isDragging ? "grabbing" : "grab") : "pointer",
+                    touchAction: interactive ? "none" : "auto",
                     display: "block",
                     userSelect: "none",
                     WebkitUserSelect: "none",
                     WebkitTouchCallout: "none",
-                }, role: "img", "aria-label": "360\u00B0 viewer", onContextMenu: (e) => e.preventDefault() })), jsxRuntime.jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingSprite || !!renderError, renderError: renderError || undefined, size: Math.min(displayW, displayH) }), jsxRuntime.jsx(InstructionTooltip, { isVisible: !isLoading &&
+                    pointerEvents: interactive ? "auto" : "none", // Allow click-through when not interactive
+                }, role: "img", "aria-label": "360\u00B0 viewer", onContextMenu: interactive ? (e) => e.preventDefault() : undefined })), jsxRuntime.jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingSprite || !!renderError, renderError: renderError || undefined, size: Math.min(displayW, displayH) }), jsxRuntime.jsx(InstructionTooltip, { isVisible: interactive &&
+                    animationMode === 'bounce' &&
+                    !isLoading &&
                     !isRenderingSprite &&
                     !renderError &&
                     isBouncing &&
@@ -1270,6 +1393,7 @@ exports.renderByShareCode = renderByShareCode;
 exports.renderSpriteExperimental = renderSpriteExperimental;
 exports.useBouncePatternProgress = useBouncePatternProgress;
 exports.useBuildRender = useBuildRender;
+exports.useContinuousSpin = useContinuousSpin;
 exports.useSpriteRender = useSpriteRender;
 exports.useSpriteScrubbing = useSpriteScrubbing;
 exports.useVideoScrubbing = useVideoScrubbing;