@buildcores/render-client 1.5.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,7 +34,12 @@ export type SpriteRenderInput = {
     type: 'parts';
     parts: RenderBuildRequest;
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
+    cameraZoom?: number;
     gridSettings?: RenderGridSettings;
     frameQuality?: 'standard' | 'high';
 } | {
@@ -42,7 +47,12 @@ 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;
     frameQuality?: 'standard' | 'high';
 };

package/dist/hooks/useZoomPan.d.ts

@@ -4,6 +4,7 @@ interface UseZoomOptions {
     displayHeight?: number;
     minScale?: number;
     maxScale?: number;
+    initialScale?: number;
 }
 interface UseZoomReturn {
     scale: number;
@@ -12,5 +13,5 @@ interface UseZoomReturn {
     handleTouchStart: (event: ReactTouchEvent<HTMLCanvasElement>) => boolean;
     reset: () => void;
 }
-export declare const useZoomPan: ({ displayWidth, displayHeight, minScale, maxScale, }?: UseZoomOptions) => UseZoomReturn;
+export declare const useZoomPan: ({ displayWidth, displayHeight, minScale, maxScale, initialScale, }?: UseZoomOptions) => UseZoomReturn;
 export {};

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.
@@ -315,6 +333,46 @@ interface BuildRenderProps {
      * @default "standard"
      */
     frameQuality?: 'standard' | 'high';
+    /**
+     * Initial zoom level for the build.
+     * Range: 0.5 (50%) to 2.5 (250%). Values less than 1 make the build appear smaller,
+     * values greater than 1 make it appear larger.
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   shareCode="abc123"
+     *   zoom={0.7}  // 70% size - build appears smaller
+     * />
+     *
+     * <BuildRender
+     *   shareCode="abc123"
+     *   zoom={1.5}  // 150% size - build appears larger
+     * />
+     * ```
+     *
+     * @default 1
+     */
+    zoom?: number;
+    /**
+     * Camera zoom level for server-side rendering.
+     * Values > 1 move the camera further away (build appears smaller in the sprite).
+     * Values < 1 move the camera closer (build appears larger in the sprite).
+     *
+     * Use this for higher quality scaled-down renders vs client-side zoom scaling.
+     * Range: 0.5 to 2.0
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   shareCode="abc123"
+     *   cameraZoom={1.3}  // Camera 30% further away - smaller build in sprite
+     * />
+     * ```
+     *
+     * @default 1
+     */
+    cameraZoom?: number;
 }
 /**
  * API configuration for environment and authentication
@@ -346,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.
@@ -512,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.
@@ -531,6 +623,15 @@ interface RenderBuildRequest {
      * @default "standard"
      */
     frameQuality?: 'standard' | 'high';
+    /**
+     * Camera zoom level for server-side rendering.
+     * Values > 1 move the camera further away (build appears smaller in the sprite).
+     * Values < 1 move the camera closer (build appears larger in the sprite).
+     * Range: 0.5 to 2.0
+     *
+     * @default 1
+     */
+    cameraZoom?: number;
 }
 /**
  * Response structure containing all available parts for each category.
@@ -674,6 +775,11 @@ interface BuildResponse {
     partDetails: {
         [K in PartCategory]?: PartDetailsWithCategory[];
     };
+    /**
+     * Whether the case in this build has an interactive 3D model available.
+     * If false, the build cannot be rendered in 3D.
+     */
+    hasInteractiveModel: boolean;
 }
 /**
  * Response from the get parts by IDs endpoint.
@@ -705,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
  */
@@ -717,14 +827,24 @@ 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) */
     gridSettings?: GridSettings;
     /** Frame quality - 'standard' (72 frames) or 'high' (144 frames for smoother animation) */
     frameQuality?: 'standard' | 'high';
+    /** Camera zoom level for rendering. Values > 1 move camera further (build appears smaller). Range: 0.5 to 2.0 */
+    cameraZoom?: number;
     /** Polling interval in milliseconds (default: 1500) */
     pollIntervalMs?: number;
     /** Timeout in milliseconds (default: 120000 = 2 minutes) */
@@ -866,7 +986,12 @@ type SpriteRenderInput = {
     type: 'parts';
     parts: RenderBuildRequest;
     showGrid?: boolean;
+    scene?: RenderBuildRequest["scene"];
+    showBackground?: boolean;
+    winterMode?: boolean;
+    springMode?: boolean;
     cameraOffsetX?: number;
+    cameraZoom?: number;
     gridSettings?: RenderGridSettings;
     frameQuality?: 'standard' | 'high';
 } | {
@@ -874,7 +999,12 @@ 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;
     frameQuality?: 'standard' | 'high';
 };
@@ -925,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")
@@ -957,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>;
@@ -1045,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 };