@buildcores/render-client 1.6.0 → 1.7.0

package/README.md

@@ -45,6 +45,33 @@ function App() {
 }
 ```
 
+## 🔐 Authentication Modes
+
+`@buildcores/render-client` supports two auth modes:
+
+- `legacy` (backward-compatible): sends a long-lived API key from `apiConfig.authToken`.
+- `session` (recommended): fetches short-lived delegated tokens from your backend via `apiConfig.getRenderSessionToken`.
+
+```tsx
+const apiConfig = {
+  environment: "prod",
+  authMode: "session",
+  getRenderSessionToken: async () => {
+    // Your backend endpoint should broker BuildCores /auth/render-session
+    const res = await fetch("/buildcores/session", { method: "POST" });
+    if (!res.ok) throw new Error("Failed to mint BuildCores session");
+    const data = await res.json();
+    return {
+      token: data.session_token,
+      expiresAt: data.expires_at,
+    };
+  },
+};
+```
+
+Legacy browser API key flow is deprecated and should only be used for temporary compatibility.
+`/render-build-experimental` behavior is unchanged.
+
 ## 🔧 API Reference
 
 ### `BuildRender` Component
@@ -72,6 +99,11 @@ interface RenderBuildRequest {
   format?: "video" | "sprite";
   width?: number;  // Optional: Canvas pixel width (256-2000)
   height?: number; // Optional: Canvas pixel height (256-2000)
+  scene?: "sunset" | "dawn" | "night" | "warehouse" | "forest" | "apartment" | "studio" | "studio_v2" | "city" | "park" | "lobby";
+  showBackground?: boolean;
+  showGrid?: boolean;
+  winterMode?: boolean; // mutually exclusive with springMode
+  springMode?: boolean; // mutually exclusive with winterMode
 }
 
 // Available part categories
@@ -91,6 +123,8 @@ enum PartCategory {
 
 **Resolution Control**: You can specify custom `width` and `height` (both must be provided together, 256-2000 pixels) for higher or lower quality renders. If not specified, the default resolution is used.
 
+**Environment Controls**: You can configure `scene`, `showBackground`, `showGrid`, and seasonal toggles (`winterMode` / `springMode`) for async render endpoints.
+
 #### Examples
 
 **Complete Build (All Components)**

package/dist/api.d.ts

@@ -32,6 +32,7 @@ export interface RenderJobStatusResponse {
     url?: string | null;
     video_url?: string | null;
     sprite_url?: string | null;
+    screenshot_url?: string | null;
     error?: string | null;
     end_time?: string | null;
 }
@@ -71,7 +72,7 @@ export interface RenderAPIService {
     getAvailableParts(category: PartCategory, config: ApiConfig, options?: GetAvailablePartsOptions): Promise<AvailablePartsResponse>;
 }
 export declare const buildApiUrl: (endpoint: string, config: ApiConfig) => string;
-export declare const buildHeaders: (config: ApiConfig) => Record<string, string>;
+export declare const buildHeaders: (config: ApiConfig, authTokenOverride?: string) => Record<string, string>;
 export declare const renderBuildExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderBuildResponse>;
 export declare const createRenderBuildJob: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderJobCreateResponse>;
 export declare const getRenderBuildStatus: (jobId: string, config: ApiConfig) => Promise<RenderJobStatusResponse>;

package/dist/hooks/useSpriteRender.d.ts

@@ -34,6 +34,10 @@ export type SpriteRenderInput = {
     type: 'parts';
     parts: RenderBuildRequest;
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
     cameraZoom?: number;
     gridSettings?: RenderGridSettings;
@@ -43,6 +47,10 @@ export type SpriteRenderInput = {
     shareCode: string;
     profile?: 'cinematic' | 'flat' | 'fast';
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
     cameraZoom?: number;
     gridSettings?: RenderGridSettings;

package/dist/index.d.ts

@@ -229,6 +229,24 @@ interface BuildRenderProps {
      * Works for both parts and shareCode rendering.
      */
     showGrid?: boolean;
+    /**
+     * Environment scene preset for rendering.
+     */
+    scene?: RenderScene;
+    /**
+     * Whether to show the environment background.
+     */
+    showBackground?: boolean;
+    /**
+     * Enable winter mode effects.
+     * Mutually exclusive with springMode.
+     */
+    winterMode?: boolean;
+    /**
+     * Enable spring mode effects.
+     * Mutually exclusive with winterMode.
+     */
+    springMode?: boolean;
     /**
      * Camera offset X for composition.
      * Positive values shift the build to the right, leaving room for text overlay on the left.
@@ -386,6 +404,22 @@ interface ApiConfig {
      * ```
      */
     authToken?: string;
+    /**
+     * Auth mode for API requests.
+     * - legacy: Sends `authToken` directly as bearer token.
+     * - session: Uses `getRenderSessionToken` to fetch short-lived delegated tokens.
+     *
+     * @default "legacy"
+     */
+    authMode?: 'legacy' | 'session';
+    /**
+     * Session token supplier used when `authMode` is "session".
+     * Should call your backend endpoint that brokers BuildCores session tokens.
+     */
+    getRenderSessionToken?: () => Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
 }
 /**
  * Enum defining all available PC part categories that can be rendered.
@@ -552,6 +586,24 @@ interface RenderBuildRequest {
      * Defaults to true for cinematic profile, false otherwise.
      */
     showGrid?: boolean;
+    /**
+     * Environment scene preset.
+     */
+    scene?: RenderScene;
+    /**
+     * Whether to show the environment background.
+     */
+    showBackground?: boolean;
+    /**
+     * Enable winter mode effects.
+     * Mutually exclusive with springMode.
+     */
+    winterMode?: boolean;
+    /**
+     * Enable spring mode effects.
+     * Mutually exclusive with winterMode.
+     */
+    springMode?: boolean;
     /**
      * Horizontal offset for the camera view.
      * Positive values shift the build to the right, leaving room for text overlay on the left.
@@ -759,6 +811,10 @@ interface GridSettings {
     /** Render order for depth sorting (default: 0, use -1 to render before other objects) */
     renderOrder?: number;
 }
+/**
+ * Supported environment scene presets for render API endpoints.
+ */
+type RenderScene = "sunset" | "dawn" | "night" | "warehouse" | "forest" | "apartment" | "studio" | "studio_v2" | "city" | "park" | "lobby";
 /**
  * Options for rendering a build by share code
  */
@@ -771,8 +827,16 @@ interface RenderByShareCodeOptions {
     height?: number;
     /** Render quality profile */
     profile?: "cinematic" | "flat" | "fast";
+    /** Environment scene preset */
+    scene?: RenderScene;
+    /** Whether to show the environment background */
+    showBackground?: boolean;
     /** Show grid in render (default: true for cinematic profile) */
     showGrid?: boolean;
+    /** Enable winter mode effects (mutually exclusive with springMode) */
+    winterMode?: boolean;
+    /** Enable spring mode effects (mutually exclusive with winterMode) */
+    springMode?: boolean;
     /** Camera offset X for composition (positive = shift build right to leave room for text overlay) */
     cameraOffsetX?: number;
     /** Grid appearance settings (for thicker/more visible grid in renders) */
@@ -922,6 +986,10 @@ type SpriteRenderInput = {
     type: 'parts';
     parts: RenderBuildRequest;
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
     cameraZoom?: number;
     gridSettings?: RenderGridSettings;
@@ -931,6 +999,10 @@ type SpriteRenderInput = {
     shareCode: string;
     profile?: 'cinematic' | 'flat' | 'fast';
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
     cameraZoom?: number;
     gridSettings?: RenderGridSettings;
@@ -983,6 +1055,20 @@ interface RenderBuildResponse {
         format?: string;
     };
 }
+interface RenderJobCreateResponse {
+    job_id: string;
+    status: "queued" | "processing" | "completed" | "error";
+}
+interface RenderJobStatusResponse {
+    job_id: string;
+    status: "queued" | "processing" | "completed" | "error";
+    url?: string | null;
+    video_url?: string | null;
+    sprite_url?: string | null;
+    screenshot_url?: string | null;
+    error?: string | null;
+    end_time?: string | null;
+}
 interface RenderSpriteResponse {
     /**
      * The rendered sprite sheet as a Blob (when format is "sprite")
@@ -1015,7 +1101,7 @@ interface RenderAPIService {
     getAvailableParts(category: PartCategory, config: ApiConfig, options?: GetAvailablePartsOptions): Promise<AvailablePartsResponse>;
 }
 declare const buildApiUrl: (endpoint: string, config: ApiConfig) => string;
-declare const buildHeaders: (config: ApiConfig) => Record<string, string>;
+declare const buildHeaders: (config: ApiConfig, authTokenOverride?: string) => Record<string, string>;
 declare const renderBuildExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderBuildResponse>;
 declare const renderSpriteExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderSpriteResponse>;
 declare const getAvailableParts: (category: PartCategory, config: ApiConfig, options?: GetAvailablePartsOptions) => Promise<AvailablePartsResponse>;
@@ -1103,4 +1189,4 @@ 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, 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 };
+export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, BuildResponse, GetAvailablePartsOptions, GridSettings, PartDetails, PartDetailsWithCategory, PartsResponse, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderByShareCodeJobResponse, RenderByShareCodeOptions, RenderByShareCodeResponse, RenderJobCreateResponse, RenderJobStatusResponse, RenderScene, RenderSpriteResponse, SpriteRenderInput, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderOptions, UseSpriteRenderReturn };

package/dist/index.esm.js

@@ -211,17 +211,73 @@ const buildApiUrl = (endpoint, config) => {
     }
     return baseUrl;
 };
+const SESSION_TOKEN_REFRESH_WINDOW_MS = 15000;
+const sessionTokenCache = new WeakMap();
+const resolveAuthMode = (config) => config.authMode ?? (config.getRenderSessionToken ? "session" : "legacy");
+const isSessionAuthMode = (config) => resolveAuthMode(config) === "session";
+const parseExpiresAtMs = (expiresAt) => {
+    const parsed = Date.parse(expiresAt);
+    if (!Number.isFinite(parsed)) {
+        throw new Error("Invalid session token expiry (expiresAt)");
+    }
+    return parsed;
+};
+const resolveSessionToken = async (config, forceRefresh) => {
+    const supplier = config.getRenderSessionToken;
+    if (!supplier) {
+        throw new Error("authMode=session requires getRenderSessionToken");
+    }
+    const cached = sessionTokenCache.get(supplier);
+    const now = Date.now();
+    if (!forceRefresh &&
+        cached &&
+        cached.expiresAtMs - SESSION_TOKEN_REFRESH_WINDOW_MS > now) {
+        return cached.token;
+    }
+    const session = await supplier();
+    if (!session?.token || !session?.expiresAt) {
+        throw new Error("getRenderSessionToken must return { token, expiresAt }");
+    }
+    const expiresAtMs = parseExpiresAtMs(session.expiresAt);
+    sessionTokenCache.set(supplier, {
+        token: session.token,
+        expiresAtMs,
+    });
+    return session.token;
+};
+const resolveAuthToken = async (config, forceRefresh) => {
+    if (isSessionAuthMode(config)) {
+        return resolveSessionToken(config, forceRefresh);
+    }
+    return config.authToken;
+};
 // Helper to build request headers with auth token
-const buildHeaders = (config) => {
+const buildHeaders = (config, authTokenOverride) => {
     const headers = {
         "Content-Type": "application/json",
         accept: "application/json",
     };
-    if (config.authToken) {
-        headers["Authorization"] = `Bearer ${config.authToken}`;
+    const authToken = authTokenOverride ?? config.authToken;
+    if (authToken) {
+        headers["Authorization"] = `Bearer ${authToken}`;
     }
     return headers;
 };
+const fetchWithApiAuth = async (url, init, config) => {
+    const firstToken = await resolveAuthToken(config, false);
+    const firstResponse = await fetch(url, {
+        ...init,
+        headers: buildHeaders(config, firstToken),
+    });
+    if (!isSessionAuthMode(config) || firstResponse.status !== 401) {
+        return firstResponse;
+    }
+    const refreshedToken = await resolveAuthToken(config, true);
+    return fetch(url, {
+        ...init,
+        headers: buildHeaders(config, refreshedToken),
+    });
+};
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // API Implementation
 const renderBuildExperimental = async (request, config) => {
@@ -233,12 +289,16 @@ const renderBuildExperimental = async (request, config) => {
         ...(request.height !== undefined ? { height: request.height } : {}),
         // Include profile if provided
         ...(request.profile ? { profile: request.profile } : {}),
+        ...(request.scene ? { scene: request.scene } : {}),
+        ...(request.showBackground !== undefined ? { showBackground: request.showBackground } : {}),
+        ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
+        ...(request.winterMode !== undefined ? { winterMode: request.winterMode } : {}),
+        ...(request.springMode !== undefined ? { springMode: request.springMode } : {}),
     };
-    const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
+    const response = await fetchWithApiAuth(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
         method: "POST",
-        headers: buildHeaders(config),
         body: JSON.stringify(requestWithFormat),
-    });
+    }, config);
     if (!response.ok) {
         throw new Error(`Render build failed: ${response.status} ${response.statusText}`);
     }
@@ -262,8 +322,12 @@ const createRenderBuildJob = async (request, config) => {
         ...(request.height !== undefined ? { height: request.height } : {}),
         // Include profile if provided
         ...(request.profile ? { profile: request.profile } : {}),
+        ...(request.scene ? { scene: request.scene } : {}),
+        ...(request.showBackground !== undefined ? { showBackground: request.showBackground } : {}),
         // Include composition settings
         ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
+        ...(request.winterMode !== undefined ? { winterMode: request.winterMode } : {}),
+        ...(request.springMode !== undefined ? { springMode: request.springMode } : {}),
         ...(request.cameraOffsetX !== undefined ? { cameraOffsetX: request.cameraOffsetX } : {}),
         ...(request.gridSettings ? { gridSettings: request.gridSettings } : {}),
         // Include frame quality for sprite rendering
@@ -271,11 +335,10 @@ const createRenderBuildJob = async (request, config) => {
         // Include camera zoom for render-time scaling
         ...(request.cameraZoom !== undefined ? { cameraZoom: request.cameraZoom } : {}),
     };
-    const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD, config), {
+    const response = await fetchWithApiAuth(buildApiUrl(API_ENDPOINTS.RENDER_BUILD, config), {
         method: "POST",
-        headers: buildHeaders(config),
         body: JSON.stringify(body),
-    });
+    }, config);
     if (!response.ok) {
         throw new Error(`Create render job failed: ${response.status} ${response.statusText}`);
     }
@@ -287,10 +350,7 @@ const createRenderBuildJob = async (request, config) => {
 };
 const getRenderBuildStatus = async (jobId, config) => {
     const url = buildApiUrl(`${API_ENDPOINTS.RENDER_BUILD}/${encodeURIComponent(jobId)}`, config);
-    const response = await fetch(url, {
-        method: "GET",
-        headers: buildHeaders(config),
-    });
+    const response = await fetchWithApiAuth(url, { method: "GET" }, config);
     if (response.status === 404) {
         throw new Error("Render job not found");
     }
@@ -335,12 +395,16 @@ const renderSpriteExperimental = async (request, config) => {
         ...(request.height !== undefined ? { height: request.height } : {}),
         // Include profile if provided
         ...(request.profile ? { profile: request.profile } : {}),
+        ...(request.scene ? { scene: request.scene } : {}),
+        ...(request.showBackground !== undefined ? { showBackground: request.showBackground } : {}),
+        ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
+        ...(request.winterMode !== undefined ? { winterMode: request.winterMode } : {}),
+        ...(request.springMode !== undefined ? { springMode: request.springMode } : {}),
     };
-    const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
+    const response = await fetchWithApiAuth(buildApiUrl(API_ENDPOINTS.RENDER_BUILD_EXPERIMENTAL, config), {
         method: "POST",
-        headers: buildHeaders(config),
         body: JSON.stringify(requestWithFormat),
-    });
+    }, config);
     if (!response.ok) {
         throw new Error(`Render sprite failed: ${response.status} ${response.statusText}`);
     }
@@ -366,10 +430,7 @@ const getAvailableParts = async (category, config, options) => {
         params.set("skip", String(options.skip));
     const separator = base.includes("?") ? "&" : "?";
     const url = `${base}${separator}${params.toString()}`;
-    const response = await fetch(url, {
-        method: "GET",
-        headers: buildHeaders(config),
-    });
+    const response = await fetchWithApiAuth(url, { method: "GET" }, config);
     if (!response.ok) {
         throw new Error(`Get available parts failed: ${response.status} ${response.statusText}`);
     }
@@ -402,10 +463,7 @@ const getAvailableParts = async (category, config, options) => {
  */
 const getBuildByShareCode = async (shareCode, config) => {
     const url = buildApiUrl(`${API_ENDPOINTS.BUILD}/${encodeURIComponent(shareCode)}`, config);
-    const response = await fetch(url, {
-        method: "GET",
-        headers: buildHeaders(config),
-    });
+    const response = await fetchWithApiAuth(url, { method: "GET" }, config);
     if (response.status === 404) {
         throw new Error("Build not found");
     }
@@ -435,11 +493,10 @@ const getBuildByShareCode = async (shareCode, config) => {
  */
 const getPartsByIds = async (partIds, config) => {
     const url = buildApiUrl(API_ENDPOINTS.PARTS, config);
-    const response = await fetch(url, {
+    const response = await fetchWithApiAuth(url, {
         method: "POST",
-        headers: buildHeaders(config),
         body: JSON.stringify({ ids: partIds }),
-    });
+    }, config);
     if (!response.ok) {
         throw new Error(`Get parts by IDs failed: ${response.status} ${response.statusText}`);
     }
@@ -462,17 +519,20 @@ const createRenderByShareCodeJob = async (shareCode, config, options) => {
         ...(options?.width !== undefined ? { width: options.width } : {}),
         ...(options?.height !== undefined ? { height: options.height } : {}),
         ...(options?.profile ? { profile: options.profile } : {}),
+        ...(options?.scene ? { scene: options.scene } : {}),
+        ...(options?.showBackground !== undefined ? { showBackground: options.showBackground } : {}),
         ...(options?.showGrid !== undefined ? { showGrid: options.showGrid } : {}),
+        ...(options?.winterMode !== undefined ? { winterMode: options.winterMode } : {}),
+        ...(options?.springMode !== undefined ? { springMode: options.springMode } : {}),
         ...(options?.cameraOffsetX !== undefined ? { cameraOffsetX: options.cameraOffsetX } : {}),
         ...(options?.gridSettings ? { gridSettings: options.gridSettings } : {}),
         ...(options?.frameQuality ? { frameQuality: options.frameQuality } : {}),
         ...(options?.cameraZoom !== undefined ? { cameraZoom: options.cameraZoom } : {}),
     };
-    const response = await fetch(url, {
+    const response = await fetchWithApiAuth(url, {
         method: "POST",
-        headers: buildHeaders(config),
         body: JSON.stringify(body),
-    });
+    }, config);
     if (response.status === 404) {
         throw new Error("Build not found");
     }
@@ -681,7 +741,21 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
     const [spriteMetadata, setSpriteMetadata] = useState(null);
     const previousInputRef = useRef(null);
     // Normalize input to SpriteRenderInput format
-    const normalizedInput = 'type' in input ? input : { type: 'parts', parts: input };
+    const normalizedInput = 'type' in input
+        ? input
+        : {
+            type: 'parts',
+            parts: input,
+            showGrid: input.showGrid,
+            scene: input.scene,
+            showBackground: input.showBackground,
+            winterMode: input.winterMode,
+            springMode: input.springMode,
+            cameraOffsetX: input.cameraOffsetX,
+            cameraZoom: input.cameraZoom,
+            gridSettings: input.gridSettings,
+            frameQuality: input.frameQuality
+        };
     const fetchRenderSprite = useCallback(async (currentInput) => {
         try {
             setIsRenderingSprite(true);
@@ -693,6 +767,10 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                     format: 'sprite',
                     profile: currentInput.profile,
                     showGrid: currentInput.showGrid,
+                    scene: currentInput.scene,
+                    showBackground: currentInput.showBackground,
+                    winterMode: currentInput.winterMode,
+                    springMode: currentInput.springMode,
                     cameraOffsetX: currentInput.cameraOffsetX,
                     cameraZoom: currentInput.cameraZoom,
                     gridSettings: currentInput.gridSettings,
@@ -719,6 +797,10 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                 const response = await renderSpriteExperimental({
                     ...currentParts,
                     showGrid: currentInput.showGrid,
+                    scene: currentInput.scene,
+                    showBackground: currentInput.showBackground,
+                    winterMode: currentInput.winterMode,
+                    springMode: currentInput.springMode,
                     cameraOffsetX: currentInput.cameraOffsetX,
                     cameraZoom: currentInput.cameraZoom,
                     gridSettings: currentInput.gridSettings,
@@ -745,6 +827,10 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
                     ...currentParts,
                     format: "sprite",
                     showGrid: currentInput.showGrid,
+                    scene: currentInput.scene,
+                    showBackground: currentInput.showBackground,
+                    winterMode: currentInput.winterMode,
+                    springMode: currentInput.springMode,
                     cameraOffsetX: currentInput.cameraOffsetX,
                     cameraZoom: currentInput.cameraZoom,
                     gridSettings: currentInput.gridSettings,
@@ -779,6 +865,10 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
             return a.shareCode === b.shareCode &&
                 a.profile === b.profile &&
                 a.showGrid === b.showGrid &&
+                a.scene === b.scene &&
+                a.showBackground === b.showBackground &&
+                a.winterMode === b.winterMode &&
+                a.springMode === b.springMode &&
                 a.cameraOffsetX === b.cameraOffsetX &&
                 a.cameraZoom === b.cameraZoom &&
                 a.frameQuality === b.frameQuality &&
@@ -789,6 +879,10 @@ const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
             const gridSettingsEqual = JSON.stringify(a.gridSettings ?? {}) === JSON.stringify(b.gridSettings ?? {});
             return arePartsEqual(a.parts, b.parts) &&
                 a.showGrid === b.showGrid &&
+                a.scene === b.scene &&
+                a.showBackground === b.showBackground &&
+                a.winterMode === b.winterMode &&
+                a.springMode === b.springMode &&
                 a.cameraOffsetX === b.cameraOffsetX &&
                 a.cameraZoom === b.cameraZoom &&
                 a.frameQuality === b.frameQuality &&
@@ -967,7 +1061,7 @@ const useZoomPan = ({ displayWidth, displayHeight, minScale = 0.5, maxScale = 2.
     };
 };
 
-const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, cameraOffsetX, cameraZoom, gridSettings, animationMode = 'bounce', spinDuration = 10000, interactive = true, frameQuality, zoom = 1, }) => {
+const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, scene, showBackground, winterMode, springMode, cameraOffsetX, cameraZoom, gridSettings, animationMode = 'bounce', spinDuration = 10000, interactive = true, frameQuality, zoom = 1, }) => {
     const canvasRef = useRef(null);
     const containerRef = useRef(null);
     const [img, setImg] = useState(null);
@@ -977,28 +1071,45 @@ const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpri
     const displayH = height ?? size ?? 300;
     // Build the render input - prefer shareCode if provided (preserves interactive state like case fan slots)
     const renderInput = useMemo(() => {
+        const resolvedShowGrid = showGrid ?? parts?.showGrid;
+        const resolvedScene = scene ?? parts?.scene;
+        const resolvedShowBackground = showBackground ?? parts?.showBackground;
+        const resolvedWinterMode = winterMode ?? parts?.winterMode;
+        const resolvedSpringMode = springMode ?? parts?.springMode;
+        const resolvedCameraOffsetX = cameraOffsetX ?? parts?.cameraOffsetX;
+        const resolvedCameraZoom = cameraZoom ?? parts?.cameraZoom;
+        const resolvedGridSettings = gridSettings ?? parts?.gridSettings;
+        const resolvedFrameQuality = frameQuality ?? parts?.frameQuality;
         if (shareCode) {
             return {
                 type: 'shareCode',
                 shareCode,
                 profile: parts?.profile,
-                showGrid,
-                cameraOffsetX,
-                cameraZoom,
-                gridSettings,
-                frameQuality,
+                showGrid: resolvedShowGrid,
+                scene: resolvedScene,
+                showBackground: resolvedShowBackground,
+                winterMode: resolvedWinterMode,
+                springMode: resolvedSpringMode,
+                cameraOffsetX: resolvedCameraOffsetX,
+                cameraZoom: resolvedCameraZoom,
+                gridSettings: resolvedGridSettings,
+                frameQuality: resolvedFrameQuality,
             };
         }
         return {
             type: 'parts',
             parts: parts,
-            showGrid,
-            cameraOffsetX,
-            cameraZoom,
-            gridSettings,
-            frameQuality,
+            showGrid: resolvedShowGrid,
+            scene: resolvedScene,
+            showBackground: resolvedShowBackground,
+            winterMode: resolvedWinterMode,
+            springMode: resolvedSpringMode,
+            cameraOffsetX: resolvedCameraOffsetX,
+            cameraZoom: resolvedCameraZoom,
+            gridSettings: resolvedGridSettings,
+            frameQuality: resolvedFrameQuality,
         };
-    }, [shareCode, parts, showGrid, cameraOffsetX, cameraZoom, gridSettings, frameQuality]);
+    }, [shareCode, parts, showGrid, scene, showBackground, winterMode, springMode, cameraOffsetX, cameraZoom, gridSettings, frameQuality]);
     // Use custom hook for sprite rendering
     const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(renderInput, apiConfig, undefined, useSpriteRenderOptions);
     const total = spriteMetadata ? spriteMetadata.totalFrames : 72;