@buildcores/render-client 1.0.8 → 1.0.10

package/dist/api.d.ts

@@ -27,6 +27,8 @@ export interface RenderJobStatusResponse {
     job_id: string;
     status: "queued" | "processing" | "completed" | "error";
     url?: string | null;
+    video_url?: string | null;
+    sprite_url?: string | null;
     error?: string | null;
     end_time?: string | null;
 }

package/dist/hooks/useSpriteRender.d.ts

@@ -9,4 +9,12 @@ export interface UseSpriteRenderReturn {
         totalFrames: number;
     } | null;
 }
-export declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void) => UseSpriteRenderReturn;
+export interface UseSpriteRenderOptions {
+    /**
+     * Choose which backend flow to use
+     * - 'async' (default): uses /render-build and polls /render-build/{jobId} with format 'sprite'
+     * - 'experimental': uses /render-build-experimental and returns Blob
+     */
+    mode?: "async" | "experimental";
+}
+export declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;

package/dist/index.d.ts

@@ -45,24 +45,12 @@ interface BuildRenderVideoProps {
      */
     parts: RenderBuildRequest;
     /**
-     * Video size in pixels (width and height will be the same).
-     *
-     * This determines the resolution of the rendered 3D video. Higher values
-     * provide better quality but may impact performance.
-     *
-     * @example
-     * ```tsx
-     * <BuildRender parts={parts} size={300} />  // 300x300px
-     * <BuildRender parts={parts} size={500} />  // 500x500px
-     * <BuildRender parts={parts} size={800} />  // 800x800px - high quality
-     * ```
-     *
-     * Recommended sizes:
-     * - 300px: Good for thumbnails or small previews
-     * - 500px: Standard size for most use cases
-     * - 800px+: High quality for detailed viewing
+     * Width and height in pixels. If only `size` is provided, both width and height use it.
+     * If `width`/`height` are provided, they override `size` individually.
      */
-    size: number;
+    width?: number;
+    height?: number;
+    size?: number;
     /**
      * API configuration for environment and authentication.
      * This is required to make API calls to the BuildCores rendering service.
@@ -159,19 +147,12 @@ interface BuildRenderProps {
      */
     parts: RenderBuildRequest;
     /**
-     * Sprite size in pixels (width and height will be the same).
-     *
-     * This determines the display size of the rendered 3D sprite. The sprite sheet
-     * itself is rendered at a fixed resolution, but this controls the display size.
-     *
-     * @example
-     * ```tsx
-     * <SpriteRender parts={parts} size={300} />  // 300x300px
-     * <SpriteRender parts={parts} size={500} />  // 500x500px
-     * <SpriteRender parts={parts} size={800} />  // 800x800px - larger display
-     * ```
+     * Width and height in pixels. If only `size` is provided, both width and height use it.
+     * If `width`/`height` are provided, they override `size` individually.
      */
-    size: number;
+    width?: number;
+    height?: number;
+    size?: number;
     /**
      * API configuration for environment and authentication.
      * This is required to make API calls to the BuildCores rendering service.
@@ -475,7 +456,15 @@ interface UseSpriteRenderReturn {
         totalFrames: number;
     } | null;
 }
-declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void) => UseSpriteRenderReturn;
+interface UseSpriteRenderOptions {
+    /**
+     * Choose which backend flow to use
+     * - 'async' (default): uses /render-build and polls /render-build/{jobId} with format 'sprite'
+     * - 'experimental': uses /render-build-experimental and returns Blob
+     */
+    mode?: "async" | "experimental";
+}
+declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;
 
 interface DragIconProps {
     width?: number;
@@ -557,4 +546,4 @@ declare const renderSpriteExperimental: (request: RenderBuildRequest, config: Ap
 declare const getAvailableParts: (config: ApiConfig) => Promise<AvailablePartsResponse>;
 
 export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, getAvailableParts, renderBuildExperimental, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
-export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, PartDetails, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderSpriteResponse, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderReturn };
+export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, PartDetails, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderSpriteResponse, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderOptions, UseSpriteRenderReturn };

package/dist/index.esm.js

@@ -415,7 +415,10 @@ const renderBuild = async (request, config, options) => {
     for (;;) {
         const status = await getRenderBuildStatus(job_id, config);
         if (status.status === "completed") {
-            const finalUrl = status.url ?? undefined;
+            const requestedFormat = request.format ?? "video";
+            const finalUrl = (requestedFormat === "sprite"
+                ? status.sprite_url || status.url || undefined
+                : status.video_url || status.url || undefined);
             if (!finalUrl) {
                 throw new Error("Render job completed but no URL returned");
             }
@@ -597,7 +600,7 @@ const useBuildRender = (parts, apiConfig, onLoadStart, options) => {
     };
 };
 
-const useSpriteRender = (parts, apiConfig, onLoadStart) => {
+const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
     const [spriteSrc, setSpriteSrc] = useState(null);
     const [isRenderingSprite, setIsRenderingSprite] = useState(false);
     const [renderError, setRenderError] = useState(null);
@@ -608,21 +611,36 @@ const useSpriteRender = (parts, apiConfig, onLoadStart) => {
             setIsRenderingSprite(true);
             setRenderError(null);
             onLoadStart?.();
-            const response = await renderSpriteExperimental(currentParts, apiConfig);
-            const objectUrl = URL.createObjectURL(response.sprite);
-            // Clean up previous sprite URL before setting new one
-            setSpriteSrc((prevSrc) => {
-                if (prevSrc) {
-                    URL.revokeObjectURL(prevSrc);
-                }
-                return objectUrl;
-            });
-            // Set sprite metadata
-            setSpriteMetadata({
-                cols: response.metadata?.cols || 12,
-                rows: response.metadata?.rows || 6,
-                totalFrames: response.metadata?.totalFrames || 72,
-            });
+            const mode = options?.mode ?? "async";
+            if (mode === "experimental") {
+                const response = await renderSpriteExperimental(currentParts, apiConfig);
+                const objectUrl = URL.createObjectURL(response.sprite);
+                // Clean up previous sprite URL before setting new one
+                setSpriteSrc((prevSrc) => {
+                    if (prevSrc && prevSrc.startsWith("blob:")) {
+                        URL.revokeObjectURL(prevSrc);
+                    }
+                    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
+                const { videoUrl: spriteUrl } = await renderBuild({ ...currentParts, format: "sprite" }, apiConfig);
+                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) {
             setRenderError(error instanceof Error ? error.message : "Failed to render sprite");
@@ -630,7 +648,7 @@ const useSpriteRender = (parts, apiConfig, onLoadStart) => {
         finally {
             setIsRenderingSprite(false);
         }
-    }, [apiConfig, onLoadStart]);
+    }, [apiConfig, onLoadStart, options?.mode]);
     // Effect to call API when parts content changes (using custom equality check)
     useEffect(() => {
         const shouldFetch = previousPartsRef.current === null ||
@@ -643,7 +661,7 @@ const useSpriteRender = (parts, apiConfig, onLoadStart) => {
     // Cleanup effect for component unmount
     useEffect(() => {
         return () => {
-            if (spriteSrc) {
+            if (spriteSrc && spriteSrc.startsWith("blob:")) {
                 URL.revokeObjectURL(spriteSrc);
             }
         };
@@ -711,11 +729,13 @@ const InstructionTooltip = ({ isVisible, progressValue, instructionIcon, }) => {
             } })) }));
 };
 
-const BuildRender = ({ parts, size, apiConfig, mouseSensitivity = 0.2, touchSensitivity = 0.2, }) => {
+const BuildRender = ({ parts, width, height, size, apiConfig, mouseSensitivity = 0.2, touchSensitivity = 0.2, }) => {
     const canvasRef = useRef(null);
     const [img, setImg] = useState(null);
     const [isLoading, setIsLoading] = useState(true);
     const [bouncingAllowed, setBouncingAllowed] = useState(false);
+    const displayW = width ?? size ?? 300;
+    const displayH = height ?? size ?? 300;
     // Use custom hook for sprite rendering
     const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(parts, apiConfig);
     const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed);
@@ -761,8 +781,8 @@ const BuildRender = ({ parts, size, apiConfig, mouseSensitivity = 0.2, touchSens
             return;
         // Backing store sized for HiDPI; CSS size stays `size`
         const dpr = Math.max(1, window.devicePixelRatio || 1);
-        const targetW = Math.round(size * dpr);
-        const targetH = Math.round(size * dpr);
+        const targetW = Math.round(displayW * dpr);
+        const targetH = Math.round(displayH * dpr);
         if (cnv.width !== targetW || cnv.height !== targetH) {
             cnv.width = targetW;
             cnv.height = targetH;
@@ -782,7 +802,7 @@ const BuildRender = ({ parts, size, apiConfig, mouseSensitivity = 0.2, touchSens
         ctx.imageSmoothingEnabled = true;
         ctx.imageSmoothingQuality = "high";
         ctx.drawImage(img, sx, sy, sw, sh, 0, 0, targetW, targetH);
-    }, [img, frameW, frameH, size, cols, total]);
+    }, [img, frameW, frameH, displayW, displayH, cols, total]);
     const { isDragging, handleMouseDown, handleTouchStart, hasDragged } = useSpriteScrubbing(canvasRef, total, {
         mouseSensitivity,
         touchSensitivity,
@@ -812,19 +832,19 @@ const BuildRender = ({ parts, size, apiConfig, mouseSensitivity = 0.2, touchSens
     }, [img, isLoading, draw]);
     return (jsxs("div", { style: {
             position: "relative",
-            width: size,
-            height: size,
+            width: displayW,
+            height: displayH,
             backgroundColor: "black",
         }, children: [img && (jsx("canvas", { ref: canvasRef, onMouseDown: handleMouseDown, onTouchStart: handleTouchStart, style: {
-                    width: size,
-                    height: size,
+                    width: displayW,
+                    height: displayH,
                     cursor: isDragging ? "grabbing" : "grab",
                     touchAction: "none", // Prevents default touch behaviors like scrolling
                     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: size }), jsx(InstructionTooltip, { isVisible: !isLoading &&
+                }, 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 &&
                     !isRenderingSprite &&
                     !renderError &&
                     isBouncing &&
@@ -924,10 +944,12 @@ const useVideoScrubbing = (videoRef, options = {}) => {
     };
 };
 
-const BuildRenderVideo = ({ parts, size, apiConfig, mouseSensitivity = 0.01, touchSensitivity = 0.01, }) => {
+const BuildRenderVideo = ({ parts, width, height, size, apiConfig, mouseSensitivity = 0.01, touchSensitivity = 0.01, }) => {
     const videoRef = useRef(null);
     const [isLoading, setIsLoading] = useState(true);
     const [bouncingAllowed, setBouncingAllowed] = useState(false);
+    const displayW = width ?? size ?? 300;
+    const displayH = height ?? size ?? 300;
     // Use custom hook for build rendering
     const { videoSrc, isRenderingBuild, renderError } = useBuildRender(parts, apiConfig);
     const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed);
@@ -957,7 +979,7 @@ const BuildRenderVideo = ({ parts, size, apiConfig, mouseSensitivity = 0.01, tou
             videoRef.current.currentTime = time;
         }
     }, [progressValue, hasDragged]);
-    return (jsxs("div", { style: { position: "relative", width: size, height: size }, children: [videoSrc && (jsx("video", { ref: videoRef, src: videoSrc, width: size, height: size, autoPlay: true, preload: "metadata", muted: true, playsInline: true, controls: false, disablePictureInPicture: true, controlsList: "nodownload nofullscreen noremoteplayback", ...{ "x-webkit-airplay": "deny" }, onMouseDown: handleMouseDown, onTouchStart: handleTouchStart, onLoadStart: handleLoadStartInternal, onCanPlay: handleCanPlayInternal, onLoadedData: () => {
+    return (jsxs("div", { style: { position: "relative", width: displayW, height: displayH }, children: [videoSrc && (jsx("video", { ref: videoRef, src: videoSrc, width: displayW, height: displayH, autoPlay: true, preload: "metadata", muted: true, playsInline: true, controls: false, disablePictureInPicture: true, controlsList: "nodownload nofullscreen noremoteplayback", ...{ "x-webkit-airplay": "deny" }, onMouseDown: handleMouseDown, onTouchStart: handleTouchStart, onLoadStart: handleLoadStartInternal, onCanPlay: handleCanPlayInternal, onLoadedData: () => {
                     if (videoRef.current) {
                         videoRef.current.pause();
                     }
@@ -975,7 +997,7 @@ const BuildRenderVideo = ({ parts, size, apiConfig, mouseSensitivity = 0.01, tou
                     WebkitTouchCallout: "none",
                     WebkitUserSelect: "none",
                     userSelect: "none",
-                }, children: "Your browser does not support the video tag." }, videoSrc)), jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingBuild || !!renderError, renderError: renderError || undefined, size: size }), jsx(InstructionTooltip, { isVisible: !isLoading &&
+                }, children: "Your browser does not support the video tag." }, videoSrc)), jsx(LoadingErrorOverlay, { isVisible: isLoading || isRenderingBuild || !!renderError, renderError: renderError || undefined, size: Math.min(displayW, displayH) }), jsx(InstructionTooltip, { isVisible: !isLoading &&
                     !isRenderingBuild &&
                     !renderError &&
                     isBouncing &&