@buildcores/render-client 1.4.0 → 1.5.0

package/dist/hooks/useContinuousSpin.d.ts

@@ -0,0 +1,17 @@
+export interface ContinuousSpinResult {
+    /** Current frame index (integer part) */
+    frame: number;
+    /** Next frame index for interpolation */
+    nextFrame: number;
+    /** Blend factor between frames (0-1), used for cross-fade interpolation */
+    blend: number;
+}
+/**
+ * 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
+ */
+export declare function useContinuousSpin(enabled?: boolean, duration?: number, totalFrames?: number): ContinuousSpinResult;

package/dist/hooks/useSpriteRender.d.ts

@@ -36,6 +36,7 @@ export type SpriteRenderInput = {
     showGrid?: boolean;
     cameraOffsetX?: number;
     gridSettings?: RenderGridSettings;
+    frameQuality?: 'standard' | 'high';
 } | {
     type: 'shareCode';
     shareCode: string;
@@ -43,5 +44,6 @@ export type SpriteRenderInput = {
     showGrid?: boolean;
     cameraOffsetX?: number;
     gridSettings?: RenderGridSettings;
+    frameQuality?: 'standard' | 'high';
 };
 export declare const useSpriteRender: (input: RenderBuildRequest | SpriteRenderInput, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;

package/dist/index.d.ts

@@ -240,6 +240,81 @@ interface BuildRenderProps {
      * Works for both parts and shareCode rendering.
      */
     gridSettings?: GridSettings;
+    /**
+     * Animation mode for the auto-rotation.
+     *
+     * - **bounce**: (default) Quick back-and-forth partial rotation with pauses
+     * - **spin360**: Slow continuous 360° rotation
+     *
+     * @example
+     * ```tsx
+     * // Continuous slow spin (good for showcases)
+     * <BuildRender
+     *   shareCode="abc123"
+     *   animationMode="spin360"
+     *   spinDuration={12000}  // 12 seconds per full rotation
+     * />
+     * ```
+     *
+     * @default "bounce"
+     */
+    animationMode?: 'bounce' | 'spin360';
+    /**
+     * Duration in milliseconds for one full 360° rotation.
+     * Only applies when `animationMode` is "spin360".
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   shareCode="abc123"
+     *   animationMode="spin360"
+     *   spinDuration={15000}  // 15 seconds per rotation
+     * />
+     * ```
+     *
+     * @default 10000 (10 seconds)
+     */
+    spinDuration?: number;
+    /**
+     * Whether to enable user interaction (drag to rotate, scroll to zoom).
+     *
+     * When set to `false`:
+     * - Drag-to-rotate is disabled
+     * - Scroll-to-zoom is disabled
+     * - Cursor shows as "pointer" instead of "grab"
+     * - Click events pass through (useful for wrapping in a link)
+     *
+     * @example
+     * ```tsx
+     * // Non-interactive showcase with link
+     * <a href="https://buildcores.com/build/abc123">
+     *   <BuildRender
+     *     shareCode="abc123"
+     *     animationMode="spin360"
+     *     interactive={false}
+     *   />
+     * </a>
+     * ```
+     *
+     * @default true
+     */
+    interactive?: boolean;
+    /**
+     * Frame quality for sprite renders.
+     * - **standard**: 72 frames (default) - good balance of quality and file size
+     * - **high**: 144 frames - smoother animation, larger file size (~2x file size)
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   shareCode="abc123"
+     *   frameQuality="high"  // 144 frames for smoother rotation
+     * />
+     * ```
+     *
+     * @default "standard"
+     */
+    frameQuality?: 'standard' | 'high';
 }
 /**
  * API configuration for environment and authentication
@@ -448,6 +523,14 @@ interface RenderBuildRequest {
      * Only applies when showGrid is true.
      */
     gridSettings?: GridSettings;
+    /**
+     * Frame quality for sprite renders.
+     * - **standard**: 72 frames (default) - good balance of quality and file size
+     * - **high**: 144 frames - smoother animation, larger file size
+     *
+     * @default "standard"
+     */
+    frameQuality?: 'standard' | 'high';
 }
 /**
  * Response structure containing all available parts for each category.
@@ -640,6 +723,8 @@ interface RenderByShareCodeOptions {
     cameraOffsetX?: number;
     /** Grid appearance settings (for thicker/more visible grid in renders) */
     gridSettings?: GridSettings;
+    /** Frame quality - 'standard' (72 frames) or 'high' (144 frames for smoother animation) */
+    frameQuality?: 'standard' | 'high';
     /** Polling interval in milliseconds (default: 1500) */
     pollIntervalMs?: number;
     /** Timeout in milliseconds (default: 120000 = 2 minutes) */
@@ -708,6 +793,24 @@ declare function useBouncePatternProgress(enabled?: boolean): {
     isBouncing: boolean;
 };
 
+interface ContinuousSpinResult {
+    /** Current frame index (integer part) */
+    frame: number;
+    /** Next frame index for interpolation */
+    nextFrame: number;
+    /** Blend factor between frames (0-1), used for cross-fade interpolation */
+    blend: number;
+}
+/**
+ * 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
+ */
+declare function useContinuousSpin(enabled?: boolean, duration?: number, totalFrames?: number): ContinuousSpinResult;
+
 /**
  * Compares two RenderBuildRequest objects for equality by checking if the same IDs
  * are present in each category array, regardless of order.
@@ -765,6 +868,7 @@ type SpriteRenderInput = {
     showGrid?: boolean;
     cameraOffsetX?: number;
     gridSettings?: RenderGridSettings;
+    frameQuality?: 'standard' | 'high';
 } | {
     type: 'shareCode';
     shareCode: string;
@@ -772,6 +876,7 @@ type SpriteRenderInput = {
     showGrid?: boolean;
     cameraOffsetX?: number;
     gridSettings?: RenderGridSettings;
+    frameQuality?: 'standard' | 'high';
 };
 declare const useSpriteRender: (input: RenderBuildRequest | SpriteRenderInput, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;
 
@@ -939,5 +1044,5 @@ declare const createRenderByShareCodeJob: (shareCode: string, config: ApiConfig,
  */
 declare const renderByShareCode: (shareCode: string, config: ApiConfig, options?: RenderByShareCodeOptions) => Promise<RenderByShareCodeResponse>;
 
-export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, createRenderByShareCodeJob, getAvailableParts, getBuildByShareCode, getPartsByIds, renderBuildExperimental, renderByShareCode, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
+export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, createRenderByShareCodeJob, getAvailableParts, getBuildByShareCode, getPartsByIds, renderBuildExperimental, renderByShareCode, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useContinuousSpin, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
 export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, BuildResponse, GetAvailablePartsOptions, GridSettings, PartDetails, PartDetailsWithCategory, PartsResponse, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderByShareCodeJobResponse, RenderByShareCodeOptions, RenderByShareCodeResponse, RenderSpriteResponse, SpriteRenderInput, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderOptions, UseSpriteRenderReturn };

package/dist/index.esm.js

@@ -140,6 +140,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] = useState({
+        frame: 0,
+        nextFrame: 1,
+        blend: 0
+    });
+    const startTime = useRef(null);
+    // Use refs to avoid stale closures in useAnimationFrame
+    const totalFramesRef = useRef(totalFrames);
+    const durationRef = useRef(duration);
+    // Keep refs in sync with props
+    useEffect(() => {
+        totalFramesRef.current = totalFrames;
+    }, [totalFrames]);
+    useEffect(() => {
+        durationRef.current = duration;
+    }, [duration]);
+    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
@@ -215,6 +266,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",
@@ -410,6 +463,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",
@@ -637,28 +691,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:")) {
@@ -666,12 +733,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
@@ -681,15 +742,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) {
@@ -712,6 +774,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') {
@@ -720,6 +783,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;
@@ -895,7 +959,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 = useRef(null);
     const containerRef = useRef(null);
     const [img, setImg] = useState(null);
@@ -913,6 +977,7 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
                 showGrid,
                 cameraOffsetX,
                 gridSettings,
+                frameQuality,
             };
         }
         return {
@@ -921,12 +986,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 = useRef(0);
@@ -934,9 +1002,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 = useRef(rows);
+    expectedRowsRef.current = rows;
     // ---- Load sprite image ----
     useEffect(() => {
         if (!spriteSrc) {
@@ -944,12 +1016,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
@@ -961,9 +1039,16 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             setImg(null);
             setIsLoading(false);
         };
-    }, [spriteSrc]);
-    // ---- Drawing function ----
-    const draw = 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 = useCallback((frameIndex, nextFrameIndex, blend) => {
         const cnv = canvasRef.current;
         if (!cnv || !img || !frameW || !frameH)
             return;
@@ -978,26 +1063,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,
@@ -1010,23 +1123,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
     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
     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)
     useEffect(() => {
         const container = containerRef.current;
-        if (!container)
+        if (!container || !interactive)
             return;
         const handleNativeWheel = (event) => {
             event.preventDefault();
@@ -1054,7 +1174,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
     useEffect(() => {
         if (img && !isLoading) {
@@ -1078,16 +1198,19 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
             height: displayH,
             backgroundColor: "black",
             overflow: "hidden",
-        }, children: [img && (jsx("canvas", { ref: canvasRef, onMouseDown: handleMouseDown, onTouchStart: handleCanvasTouchStart, style: {
+        }, children: [img && (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() })), jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingSprite || !!renderError, renderError: renderError || undefined, size: Math.min(displayW, displayH) }), 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 })), jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingSprite || !!renderError, renderError: renderError || undefined, size: Math.min(displayW, displayH) }), jsx(InstructionTooltip, { isVisible: interactive &&
+                    animationMode === 'bounce' &&
+                    !isLoading &&
                     !isRenderingSprite &&
                     !renderError &&
                     isBouncing &&
@@ -1247,5 +1370,5 @@ const BuildRenderVideo = ({ parts, width, height, size, apiConfig, useBuildRende
                     !hasDragged.current, progressValue: progressValue })] }));
 };
 
-export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, createRenderByShareCodeJob, getAvailableParts, getBuildByShareCode, getPartsByIds, renderBuildExperimental, renderByShareCode, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
+export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, createRenderByShareCodeJob, getAvailableParts, getBuildByShareCode, getPartsByIds, renderBuildExperimental, renderByShareCode, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useContinuousSpin, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
 //# sourceMappingURL=index.esm.js.map