@buildcores/render-client 1.2.0 → 1.4.0

package/dist/index.js

@@ -149,6 +149,9 @@ const API_ENDPOINTS = {
     RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental",
     RENDER_BUILD: "/render-build",
     AVAILABLE_PARTS: "/available-parts",
+    BUILD: "/build",
+    PARTS: "/parts",
+    RENDER_BY_SHARE_CODE: "/render-by-share-code",
 };
 // API URL helpers
 const buildApiUrl = (endpoint, config) => {
@@ -179,6 +182,8 @@ const renderBuildExperimental = async (request, config) => {
         // Include width and height if provided
         ...(request.width !== undefined ? { width: request.width } : {}),
         ...(request.height !== undefined ? { height: request.height } : {}),
+        // Include profile if provided
+        ...(request.profile ? { profile: request.profile } : {}),
     };
     const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
         method: "POST",
@@ -206,6 +211,12 @@ const createRenderBuildJob = async (request, config) => {
         // Include width and height if provided
         ...(request.width !== undefined ? { width: request.width } : {}),
         ...(request.height !== undefined ? { height: request.height } : {}),
+        // Include profile if provided
+        ...(request.profile ? { profile: request.profile } : {}),
+        // Include composition settings
+        ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
+        ...(request.cameraOffsetX !== undefined ? { cameraOffsetX: request.cameraOffsetX } : {}),
+        ...(request.gridSettings ? { gridSettings: request.gridSettings } : {}),
     };
     const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD, config), {
         method: "POST",
@@ -269,6 +280,8 @@ const renderSpriteExperimental = async (request, config) => {
         // Include width and height if provided
         ...(request.width !== undefined ? { width: request.width } : {}),
         ...(request.height !== undefined ? { height: request.height } : {}),
+        // Include profile if provided
+        ...(request.profile ? { profile: request.profile } : {}),
     };
     const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
         method: "POST",
@@ -309,6 +322,169 @@ const getAvailableParts = async (category, config, options) => {
     }
     return (await response.json());
 };
+// ============================================
+// Build and Parts API Functions
+// ============================================
+/**
+ * Fetch a build by its share code.
+ * Returns build metadata and parts organized by category.
+ *
+ * @param shareCode - The share code of the build to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with build details including parts
+ *
+ * @example
+ * ```tsx
+ * const build = await getBuildByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * console.log(build.name); // "My Gaming PC"
+ * console.log(build.parts.CPU); // ["7xjqsomhr"]
+ *
+ * // Use the parts directly with BuildRender
+ * <BuildRender parts={{ parts: build.parts }} size={500} apiConfig={config} />
+ * ```
+ */
+const getBuildByShareCode = async (shareCode, config) => {
+    const url = buildApiUrl(`${API_ENDPOINTS.BUILD}/${encodeURIComponent(shareCode)}`, config);
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(config),
+    });
+    if (response.status === 404) {
+        throw new Error("Build not found");
+    }
+    if (!response.ok) {
+        throw new Error(`Get build by share code failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+};
+/**
+ * Fetch part details by their BuildCores IDs.
+ *
+ * @param partIds - Array of BuildCores part IDs to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with part details
+ *
+ * @example
+ * ```tsx
+ * const response = await getPartsByIds(['7xjqsomhr', 'z7pyphm9k'], {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * response.parts.forEach(part => {
+ *   console.log(`${part.name} (${part.category})`);
+ * });
+ * ```
+ */
+const getPartsByIds = async (partIds, config) => {
+    const url = buildApiUrl(API_ENDPOINTS.PARTS, config);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify({ ids: partIds }),
+    });
+    if (!response.ok) {
+        throw new Error(`Get parts by IDs failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+};
+/**
+ * Create a render job for a build by its share code.
+ * Returns the job ID for polling status.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options (format, dimensions, profile)
+ * @returns Promise with job creation response
+ */
+const createRenderByShareCodeJob = async (shareCode, config, options) => {
+    const url = buildApiUrl(API_ENDPOINTS.RENDER_BY_SHARE_CODE, config);
+    const body = {
+        shareCode,
+        ...(options?.format ? { format: options.format } : {}),
+        ...(options?.width !== undefined ? { width: options.width } : {}),
+        ...(options?.height !== undefined ? { height: options.height } : {}),
+        ...(options?.profile ? { profile: options.profile } : {}),
+        ...(options?.showGrid !== undefined ? { showGrid: options.showGrid } : {}),
+        ...(options?.cameraOffsetX !== undefined ? { cameraOffsetX: options.cameraOffsetX } : {}),
+        ...(options?.gridSettings ? { gridSettings: options.gridSettings } : {}),
+    };
+    const response = await fetch(url, {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify(body),
+    });
+    if (response.status === 404) {
+        throw new Error("Build not found");
+    }
+    if (!response.ok) {
+        throw new Error(`Create render job failed: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data?.job_id) {
+        throw new Error("Create render job failed: missing job_id in response");
+    }
+    return data;
+};
+/**
+ * Render a build by its share code.
+ * This is a convenience function that creates a render job and polls until completion.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options including polling configuration
+ * @returns Promise with the final render URL
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - just pass share code
+ * const result = await renderByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ * console.log(result.videoUrl); // URL to rendered video
+ *
+ * // With custom options
+ * const result = await renderByShareCode('abc123xyz', config, {
+ *   format: 'sprite',
+ *   width: 1920,
+ *   height: 1080,
+ *   profile: 'cinematic',
+ *   timeoutMs: 180000 // 3 minute timeout
+ * });
+ * ```
+ */
+const renderByShareCode = async (shareCode, config, options) => {
+    const pollIntervalMs = options?.pollIntervalMs ?? 1500;
+    const timeoutMs = options?.timeoutMs ?? 120000; // 2 minutes default
+    const { job_id } = await createRenderByShareCodeJob(shareCode, config, options);
+    const start = Date.now();
+    // Poll until completed or error or timeout
+    for (;;) {
+        const status = await getRenderBuildStatus(job_id, config);
+        if (status.status === "completed") {
+            const requestedFormat = options?.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");
+            }
+            return { videoUrl: finalUrl };
+        }
+        if (status.status === "error") {
+            throw new Error(status.error || "Render job failed");
+        }
+        if (Date.now() - start > timeoutMs) {
+            throw new Error("Timed out waiting for render job to complete");
+        }
+        await sleep(pollIntervalMs);
+    }
+};
 
 /**
  * Enum defining all available PC part categories that can be rendered.
@@ -349,6 +525,8 @@ exports.PartCategory = void 0;
     PartCategory["PCCase"] = "PCCase";
     /** CPU Cooler - Air or liquid cooling for the processor */
     PartCategory["CPUCooler"] = "CPUCooler";
+    /** Case Fans - Additional cooling fans for the case */
+    PartCategory["CaseFan"] = "CaseFan";
 })(exports.PartCategory || (exports.PartCategory = {}));
 
 /**
@@ -441,20 +619,47 @@ const useBuildRender = (parts, apiConfig, onLoadStart, options) => {
     };
 };
 
-const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
+const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
     const [spriteSrc, setSpriteSrc] = react.useState(null);
     const [isRenderingSprite, setIsRenderingSprite] = react.useState(false);
     const [renderError, setRenderError] = react.useState(null);
     const [spriteMetadata, setSpriteMetadata] = react.useState(null);
-    const previousPartsRef = react.useRef(null);
-    const fetchRenderSprite = react.useCallback(async (currentParts) => {
+    const previousInputRef = react.useRef(null);
+    // Normalize input to SpriteRenderInput format
+    const normalizedInput = 'type' in input ? input : { type: 'parts', parts: input };
+    const fetchRenderSprite = react.useCallback(async (currentInput) => {
         try {
             setIsRenderingSprite(true);
             setRenderError(null);
             onLoadStart?.();
+            // Handle share code rendering - uses existing build with proper interactive state
+            if (currentInput.type === 'shareCode') {
+                const { videoUrl: spriteUrl } = await renderByShareCode(currentInput.shareCode, apiConfig, {
+                    format: 'sprite',
+                    profile: currentInput.profile,
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings
+                });
+                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";
             if (mode === "experimental") {
-                const response = await renderSpriteExperimental(currentParts, apiConfig);
+                const response = await renderSpriteExperimental({
+                    ...currentParts,
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings,
+                }, apiConfig);
                 const objectUrl = URL.createObjectURL(response.sprite);
                 // Clean up previous sprite URL before setting new one
                 setSpriteSrc((prevSrc) => {
@@ -472,7 +677,13 @@ const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
             }
             else {
                 // Async job-based flow: request sprite format and use returned URL
-                const { videoUrl: spriteUrl } = await renderBuild({ ...currentParts, format: "sprite" }, apiConfig);
+                const { videoUrl: spriteUrl } = await renderBuild({
+                    ...currentParts,
+                    format: "sprite",
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings,
+                }, apiConfig);
                 setSpriteSrc((prevSrc) => {
                     if (prevSrc && prevSrc.startsWith("blob:")) {
                         URL.revokeObjectURL(prevSrc);
@@ -490,15 +701,39 @@ const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
             setIsRenderingSprite(false);
         }
     }, [apiConfig, onLoadStart, options?.mode]);
-    // Effect to call API when parts content changes (using custom equality check)
+    // Check if inputs are equal
+    const areInputsEqual = (a, b) => {
+        if (!a)
+            return false;
+        if (a.type !== b.type)
+            return false;
+        if (a.type === 'shareCode' && b.type === 'shareCode') {
+            // Compare grid settings (shallow comparison of properties)
+            const gridSettingsEqual = JSON.stringify(a.gridSettings ?? {}) === JSON.stringify(b.gridSettings ?? {});
+            return a.shareCode === b.shareCode &&
+                a.profile === b.profile &&
+                a.showGrid === b.showGrid &&
+                a.cameraOffsetX === b.cameraOffsetX &&
+                gridSettingsEqual;
+        }
+        if (a.type === 'parts' && b.type === 'parts') {
+            // Compare grid settings (shallow comparison of properties)
+            const gridSettingsEqual = JSON.stringify(a.gridSettings ?? {}) === JSON.stringify(b.gridSettings ?? {});
+            return arePartsEqual(a.parts, b.parts) &&
+                a.showGrid === b.showGrid &&
+                a.cameraOffsetX === b.cameraOffsetX &&
+                gridSettingsEqual;
+        }
+        return false;
+    };
+    // Effect to call API when input changes
     react.useEffect(() => {
-        const shouldFetch = previousPartsRef.current === null ||
-            !arePartsEqual(previousPartsRef.current, parts);
+        const shouldFetch = !areInputsEqual(previousInputRef.current, normalizedInput);
         if (shouldFetch) {
-            previousPartsRef.current = parts;
-            fetchRenderSprite(parts);
+            previousInputRef.current = normalizedInput;
+            fetchRenderSprite(normalizedInput);
         }
-    }, [parts, fetchRenderSprite]);
+    }, [normalizedInput, fetchRenderSprite]);
     // Cleanup effect for component unmount
     react.useEffect(() => {
         return () => {
@@ -570,20 +805,137 @@ const InstructionTooltip = ({ isVisible, progressValue, instructionIcon, }) => {
             } })) }));
 };
 
-const BuildRender = ({ parts, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, }) => {
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const getTouchDistance = (touches) => {
+    const first = touches[0];
+    const second = touches[1];
+    if (!first || !second)
+        return 0;
+    return Math.hypot(second.clientX - first.clientX, second.clientY - first.clientY);
+};
+const useZoomPan = ({ displayWidth, displayHeight, minScale = 1, maxScale = 4, } = {}) => {
+    const [scale, setScale] = react.useState(1);
+    const [isPinching, setIsPinching] = react.useState(false);
+    const scaleRef = react.useRef(1);
+    const pinchDataRef = react.useRef({
+        initialDistance: 0,
+        initialScale: 1,
+    });
+    const setScaleSafe = react.useCallback((next) => {
+        const clamped = clamp(next, minScale, maxScale);
+        if (clamped === scaleRef.current)
+            return;
+        scaleRef.current = clamped;
+        setScale(clamped);
+    }, [minScale, maxScale]);
+    const handleWheel = react.useCallback((event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        const deltaY = event.deltaMode === 1
+            ? event.deltaY * 16
+            : event.deltaMode === 2
+                ? event.deltaY * (displayHeight ?? 300)
+                : event.deltaY;
+        const zoomFactor = Math.exp(-deltaY * 0.0015);
+        const nextScale = scaleRef.current * zoomFactor;
+        setScaleSafe(nextScale);
+    }, [setScaleSafe, displayHeight]);
+    const handleTouchStart = react.useCallback((event) => {
+        if (event.touches.length < 2) {
+            return false;
+        }
+        const distance = getTouchDistance(event.touches);
+        if (!distance) {
+            return false;
+        }
+        pinchDataRef.current = {
+            initialDistance: distance,
+            initialScale: scaleRef.current,
+        };
+        setIsPinching(true);
+        event.preventDefault();
+        return true;
+    }, []);
+    react.useEffect(() => {
+        if (!isPinching)
+            return;
+        const handleMove = (event) => {
+            if (event.touches.length < 2)
+                return;
+            const distance = getTouchDistance(event.touches);
+            if (!distance || pinchDataRef.current.initialDistance === 0)
+                return;
+            const scaleFactor = distance / pinchDataRef.current.initialDistance;
+            const nextScale = pinchDataRef.current.initialScale * scaleFactor;
+            setScaleSafe(nextScale);
+            event.preventDefault();
+        };
+        const handleEnd = (event) => {
+            if (event.touches.length < 2) {
+                setIsPinching(false);
+            }
+        };
+        window.addEventListener("touchmove", handleMove, { passive: false });
+        window.addEventListener("touchend", handleEnd);
+        window.addEventListener("touchcancel", handleEnd);
+        return () => {
+            window.removeEventListener("touchmove", handleMove);
+            window.removeEventListener("touchend", handleEnd);
+            window.removeEventListener("touchcancel", handleEnd);
+        };
+    }, [isPinching, setScaleSafe]);
+    const reset = react.useCallback(() => {
+        scaleRef.current = 1;
+        setScale(1);
+    }, []);
+    return {
+        scale,
+        isPinching,
+        handleWheel,
+        handleTouchStart,
+        reset,
+    };
+};
+
+const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, cameraOffsetX, gridSettings, }) => {
     const canvasRef = react.useRef(null);
+    const containerRef = react.useRef(null);
     const [img, setImg] = react.useState(null);
     const [isLoading, setIsLoading] = react.useState(true);
     const [bouncingAllowed, setBouncingAllowed] = react.useState(false);
     const displayW = width ?? size ?? 300;
     const displayH = height ?? size ?? 300;
+    // Build the render input - prefer shareCode if provided (preserves interactive state like case fan slots)
+    const renderInput = react.useMemo(() => {
+        if (shareCode) {
+            return {
+                type: 'shareCode',
+                shareCode,
+                profile: parts?.profile,
+                showGrid,
+                cameraOffsetX,
+                gridSettings,
+            };
+        }
+        return {
+            type: 'parts',
+            parts: parts,
+            showGrid,
+            cameraOffsetX,
+            gridSettings,
+        };
+    }, [shareCode, parts, showGrid, cameraOffsetX, gridSettings]);
     // Use custom hook for sprite rendering
-    const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(parts, apiConfig, undefined, useSpriteRenderOptions);
+    const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(renderInput, apiConfig, undefined, useSpriteRenderOptions);
     const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed);
     const total = spriteMetadata ? spriteMetadata.totalFrames : 72;
     const cols = spriteMetadata ? spriteMetadata.cols : 12;
     const rows = spriteMetadata ? spriteMetadata.rows : 6;
     const frameRef = react.useRef(0);
+    const { scale, handleWheel: handleZoomWheel, handleTouchStart: handleZoomTouchStart, reset: resetZoom, } = useZoomPan({
+        displayWidth: displayW,
+        displayHeight: displayH,
+    });
     // Image/frame sizes
     const frameW = img ? img.width / cols : 0;
     const frameH = img ? img.height / rows : 0;
@@ -642,8 +994,12 @@ const BuildRender = ({ parts, width, height, size, apiConfig, useSpriteRenderOpt
         ctx.clearRect(0, 0, targetW, targetH);
         ctx.imageSmoothingEnabled = true;
         ctx.imageSmoothingQuality = "high";
-        ctx.drawImage(img, sx, sy, sw, sh, 0, 0, targetW, targetH);
-    }, [img, frameW, frameH, displayW, displayH, cols, total]);
+        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]);
     const { isDragging, handleMouseDown, handleTouchStart, hasDragged } = useSpriteScrubbing(canvasRef, total, {
         mouseSensitivity,
         touchSensitivity,
@@ -665,18 +1021,66 @@ const BuildRender = ({ parts, width, height, size, apiConfig, useSpriteRenderOpt
         frameRef.current = frame;
         draw(frame);
     }, [progressValue, hasDragged, img, total, draw]);
-    // Initial draw once image is ready
+    // 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
+    react.useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const handleNativeWheel = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            // Manually trigger zoom since we're preventing the React event
+            event.deltaMode === 1
+                ? event.deltaY * 16
+                : event.deltaMode === 2
+                    ? event.deltaY * (displayH ?? 300)
+                    : event.deltaY;
+            // We need to call the zoom handler directly
+            // Create a synthetic React event-like object
+            const syntheticEvent = {
+                preventDefault: () => { },
+                stopPropagation: () => { },
+                deltaY: event.deltaY,
+                deltaMode: event.deltaMode,
+                currentTarget: container,
+            };
+            handleZoomWheel(syntheticEvent);
+            hasDragged.current = true;
+        };
+        // Add listener to container to catch all wheel events
+        container.addEventListener('wheel', handleNativeWheel, { passive: false });
+        return () => {
+            container.removeEventListener('wheel', handleNativeWheel);
+        };
+    }, [handleZoomWheel, scale, displayH]);
+    // Initial draw once image is ready or zoom changes
     react.useEffect(() => {
         if (img && !isLoading) {
             draw(frameRef.current);
         }
     }, [img, isLoading, draw]);
-    return (jsxRuntime.jsxs("div", { style: {
+    const handleCanvasTouchStart = react.useCallback((event) => {
+        if (handleZoomTouchStart(event)) {
+            hasDragged.current = true;
+            return;
+        }
+        handleTouchStart(event);
+    }, [handleZoomTouchStart, handleTouchStart, hasDragged]);
+    react.useCallback((event) => {
+        hasDragged.current = true;
+        handleZoomWheel(event);
+    }, [handleZoomWheel, hasDragged]);
+    return (jsxRuntime.jsxs("div", { ref: containerRef, style: {
             position: "relative",
             width: displayW,
             height: displayH,
             backgroundColor: "black",
-        }, children: [img && (jsxRuntime.jsx("canvas", { ref: canvasRef, onMouseDown: handleMouseDown, onTouchStart: handleTouchStart, style: {
+            overflow: "hidden",
+        }, children: [img && (jsxRuntime.jsx("canvas", { ref: canvasRef, onMouseDown: handleMouseDown, onTouchStart: handleCanvasTouchStart, style: {
                     width: displayW,
                     height: displayH,
                     cursor: isDragging ? "grabbing" : "grab",
@@ -857,8 +1261,12 @@ exports.buildApiUrl = buildApiUrl;
 exports.buildHeaders = buildHeaders;
 exports.calculateCircularFrame = calculateCircularFrame;
 exports.calculateCircularTime = calculateCircularTime;
+exports.createRenderByShareCodeJob = createRenderByShareCodeJob;
 exports.getAvailableParts = getAvailableParts;
+exports.getBuildByShareCode = getBuildByShareCode;
+exports.getPartsByIds = getPartsByIds;
 exports.renderBuildExperimental = renderBuildExperimental;
+exports.renderByShareCode = renderByShareCode;
 exports.renderSpriteExperimental = renderSpriteExperimental;
 exports.useBouncePatternProgress = useBouncePatternProgress;
 exports.useBuildRender = useBuildRender;