@liveroom-tech/react-immersive 2.0.0 → 2.1.0

package/README.md

@@ -12,10 +12,12 @@ import {
   material,
   ModelViewer,
   patchBindings,
+  patchSceneConfig,
   SimpleModelViewer,
   useObjectBinding,
   useObjectBindingIds,
   useObjectBindings,
+  useSceneConfig,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
@@ -27,7 +29,7 @@ import {
 } from "@liveroom-tech/react-immersive";
 ```
 
-It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `SceneConfig`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
+It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `SceneConfig`, `SceneConfigPatch`, `SceneConfigController`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
 
 `ModelViewer` provides:
 
@@ -334,7 +336,7 @@ If you want one state owner for binding patches, materials, and visibility, use
 const {
   objectBindings,
   setObjectBindings,
-  patch,
+  updateObjectBindings,
   setMaterial,
   setBaseColor,
   resetMaterial,
@@ -356,7 +358,7 @@ const {
 />;
 ```
 
-`useObjectBindings` owns the state used by the viewer. Every setter uses a functional update, so consecutive material, visibility, and general patch calls in the same tick compose instead of overwriting each other.
+`useObjectBindings` owns the state used by the viewer. Every setter uses a functional update, so consecutive material, visibility, and general binding updates in the same tick compose instead of overwriting each other.
 
 Object identifiers accepted by its methods can be:
 
@@ -367,7 +369,7 @@ Object identifiers accepted by its methods can be:
 The hook returns:
 
 - `objectBindings` and `setObjectBindings`
-- `patch` for any binding field or atomic edit batch
+- `updateObjectBindings` for any binding field or atomic edit batch
 - `setMaterial`, `setBaseColor`, `resetMaterial`, and `getMaterial`
 - `hiddenObjects`: a derived map of hidden binding keys
 - `hiddenObjectIds`: the currently hidden binding IDs
@@ -375,6 +377,37 @@ The hook returns:
 - `isObjectHidden`
 - `clearHiddenObjects`
 
+For scene-wide state, use `useSceneConfig`:
+
+```tsx
+const {
+  sceneConfig,
+  setSceneConfig,
+  updateSceneConfig,
+  resetSceneConfig,
+} = useSceneConfig(initialSceneConfig);
+
+const enableUvChecker = () =>
+  updateSceneConfig({
+    model: { renderer: "uv-checker" },
+    lighting: { ambient: { intensity: 0.5 } },
+  });
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  sceneConfig={sceneConfig}
+/>;
+
+<button onClick={enableUvChecker}>Show UV checker</button>;
+```
+
+Nested objects merge recursively, while arrays and tuples are replaced. Every
+update uses a functional state updater, so consecutive calls compose. Use the
+pure `patchSceneConfig(sceneConfig, patch)` utility when a store or parent owns
+the scene state.
+
 If you want to keep hover state in sync with the viewer, the library also exports:
 
 ```tsx

package/dist/index.d.mts

@@ -664,9 +664,10 @@ declare function useObjectBinding(objectBindings: Record<string, ObjectBinding>,
 
 declare function useObjectBindingIds(objectBindings: Record<string, ObjectBinding>): string[];
 
-type DeepPartial<T> = T extends (infer _U)[] ? T : T extends object ? {
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
+
 type ObjectBindingPatch = DeepPartial<ObjectBinding>;
 type BindingEdit = {
     ids: string | string[];
@@ -689,7 +690,7 @@ type HiddenObjectsState = Record<string, boolean>;
 type ObjectBindingsController = {
     objectBindings: Record<string, ObjectBinding>;
     setObjectBindings: React.Dispatch<React.SetStateAction<Record<string, ObjectBinding>>>;
-    patch: {
+    updateObjectBindings: {
         (objectId: string | string[], patch: ObjectBindingPatch): void;
         (edits: BindingEdit[]): void;
     };
@@ -714,6 +715,26 @@ type ObjectBindingsController = {
  */
 declare function useObjectBindings(initialBindings: Record<string, ObjectBinding> | (() => Record<string, ObjectBinding>)): ObjectBindingsController;
 
+type SceneConfigPatch = DeepPartial<SceneConfig>;
+/**
+ * Applies a nested scene-config patch without mutating either input. Objects
+ * are merged recursively, while arrays and tuples are replaced wholesale.
+ */
+declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+
+type SceneConfigUpdate = SceneConfigPatch | ((current: SceneConfig) => SceneConfigPatch);
+type SceneConfigController = {
+    sceneConfig: SceneConfig;
+    setSceneConfig: React.Dispatch<React.SetStateAction<SceneConfig>>;
+    updateSceneConfig: (update: SceneConfigUpdate) => void;
+    resetSceneConfig: () => void;
+};
+/**
+ * Owns scene-config state and applies nested patches through functional React
+ * updates, so consecutive calls in the same tick compose safely.
+ */
+declare function useSceneConfig(initialSceneConfig: SceneConfig | (() => SceneConfig)): SceneConfigController;
+
 type ViewerHoverProps = {
     hoveredObjectBinding: ObjectBinding | null;
     handleHoveredObject: (binding: ObjectBinding | null) => void;
@@ -766,4 +787,4 @@ type ShareableViewerStateProps = {
 };
 declare function useShareableViewerState({ cameraState, setCameraState, objectBindings, onObjectBindingsChange, selectedObjectBinding, setSelectedObjectBinding, paramKey, debounceMs, autoSync, }: UseShareableViewerStateOptions): ShareableViewerStateProps;
 
-export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, useObjectBinding, useObjectBindingIds, useObjectBindings, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, patchSceneConfig, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.d.ts

@@ -664,9 +664,10 @@ declare function useObjectBinding(objectBindings: Record<string, ObjectBinding>,
 
 declare function useObjectBindingIds(objectBindings: Record<string, ObjectBinding>): string[];
 
-type DeepPartial<T> = T extends (infer _U)[] ? T : T extends object ? {
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
+
 type ObjectBindingPatch = DeepPartial<ObjectBinding>;
 type BindingEdit = {
     ids: string | string[];
@@ -689,7 +690,7 @@ type HiddenObjectsState = Record<string, boolean>;
 type ObjectBindingsController = {
     objectBindings: Record<string, ObjectBinding>;
     setObjectBindings: React.Dispatch<React.SetStateAction<Record<string, ObjectBinding>>>;
-    patch: {
+    updateObjectBindings: {
         (objectId: string | string[], patch: ObjectBindingPatch): void;
         (edits: BindingEdit[]): void;
     };
@@ -714,6 +715,26 @@ type ObjectBindingsController = {
  */
 declare function useObjectBindings(initialBindings: Record<string, ObjectBinding> | (() => Record<string, ObjectBinding>)): ObjectBindingsController;
 
+type SceneConfigPatch = DeepPartial<SceneConfig>;
+/**
+ * Applies a nested scene-config patch without mutating either input. Objects
+ * are merged recursively, while arrays and tuples are replaced wholesale.
+ */
+declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+
+type SceneConfigUpdate = SceneConfigPatch | ((current: SceneConfig) => SceneConfigPatch);
+type SceneConfigController = {
+    sceneConfig: SceneConfig;
+    setSceneConfig: React.Dispatch<React.SetStateAction<SceneConfig>>;
+    updateSceneConfig: (update: SceneConfigUpdate) => void;
+    resetSceneConfig: () => void;
+};
+/**
+ * Owns scene-config state and applies nested patches through functional React
+ * updates, so consecutive calls in the same tick compose safely.
+ */
+declare function useSceneConfig(initialSceneConfig: SceneConfig | (() => SceneConfig)): SceneConfigController;
+
 type ViewerHoverProps = {
     hoveredObjectBinding: ObjectBinding | null;
     handleHoveredObject: (binding: ObjectBinding | null) => void;
@@ -766,4 +787,4 @@ type ShareableViewerStateProps = {
 };
 declare function useShareableViewerState({ cameraState, setCameraState, objectBindings, onObjectBindingsChange, selectedObjectBinding, setSelectedObjectBinding, paramKey, debounceMs, autoSync, }: UseShareableViewerStateOptions): ShareableViewerStateProps;
 
-export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, useObjectBinding, useObjectBindingIds, useObjectBindings, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, patchSceneConfig, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.js

@@ -54,9 +54,11 @@ __export(index_exports, {
   SimpleModelViewer: () => SimpleModelViewer,
   material: () => material,
   patchBindings: () => patchBindings,
+  patchSceneConfig: () => patchSceneConfig,
   useObjectBinding: () => useObjectBinding,
   useObjectBindingIds: () => useObjectBindingIds,
   useObjectBindings: () => useObjectBindings,
+  useSceneConfig: () => useSceneConfig,
   useShareableViewerState: () => useShareableViewerState,
   useViewerActions: () => useViewerActions,
   useViewerAnimations: () => useViewerAnimations,
@@ -17596,15 +17598,12 @@ function useObjectBindingIds(objectBindings) {
 // src/hooks/useObjectBindings.ts
 var import_react44 = require("react");
 
-// src/utils/patchBindings.ts
+// src/utils/deepMerge.ts
 function isPlainObject2(value) {
   if (typeof value !== "object" || value === null) return false;
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function isBindingEditArray(value) {
-  return Array.isArray(value) && value.length > 0 && typeof value[0] !== "string";
-}
 function deepMerge(base, patch) {
   if (!isPlainObject2(patch)) return patch;
   const target = isPlainObject2(base) ? { ...base } : {};
@@ -17614,6 +17613,11 @@ function deepMerge(base, patch) {
   }
   return target;
 }
+
+// src/utils/patchBindings.ts
+function isBindingEditArray(value) {
+  return Array.isArray(value) && value.length > 0 && typeof value[0] !== "string";
+}
 function patchBindings(bindings, objectIdOrEdits, patch) {
   const edits = isBindingEditArray(objectIdOrEdits) ? objectIdOrEdits : [{ ids: objectIdOrEdits, patch: patch ?? {} }];
   let next = bindings;
@@ -17643,7 +17647,7 @@ function getHiddenObjects(objectBindings) {
 }
 function useObjectBindings(initialBindings) {
   const [objectBindings, setObjectBindings] = (0, import_react44.useState)(initialBindings);
-  const patch = (0, import_react44.useCallback)(
+  const updateObjectBindings = (0, import_react44.useCallback)(
     (objectIdOrEdits, patchValue) => {
       setObjectBindings(
         (current) => patchValue === void 0 ? patchBindings(current, objectIdOrEdits) : patchBindings(
@@ -17656,16 +17660,16 @@ function useObjectBindings(initialBindings) {
     []
   );
   const setMaterial = (0, import_react44.useCallback)(
-    (objectId, value) => patch(objectId, material(value)),
-    [patch]
+    (objectId, value) => updateObjectBindings(objectId, material(value)),
+    [updateObjectBindings]
   );
   const setBaseColor = (0, import_react44.useCallback)(
     (objectId, color) => setMaterial(objectId, { baseColor: color }),
     [setMaterial]
   );
   const resetMaterial = (0, import_react44.useCallback)(
-    (objectId) => patch(objectId, { style: { material: void 0 } }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { style: { material: void 0 } }),
+    [updateObjectBindings]
   );
   const getMaterial = (0, import_react44.useCallback)(
     (objectId) => {
@@ -17675,12 +17679,12 @@ function useObjectBindings(initialBindings) {
     [objectBindings]
   );
   const hideObject = (0, import_react44.useCallback)(
-    (objectId) => patch(objectId, { visible: false }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { visible: false }),
+    [updateObjectBindings]
   );
   const showObject = (0, import_react44.useCallback)(
-    (objectId) => patch(objectId, { visible: true }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { visible: true }),
+    [updateObjectBindings]
   );
   const toggleObjectVisibility = (0, import_react44.useCallback)(
     (objectId) => {
@@ -17726,7 +17730,7 @@ function useObjectBindings(initialBindings) {
   return {
     objectBindings,
     setObjectBindings,
-    patch,
+    updateObjectBindings,
     setMaterial,
     setBaseColor,
     resetMaterial,
@@ -17741,11 +17745,45 @@ function useObjectBindings(initialBindings) {
   };
 }
 
-// src/hooks/useViewerHover.ts
+// src/hooks/useSceneConfig.ts
 var import_react45 = require("react");
+
+// src/utils/patchSceneConfig.ts
+function patchSceneConfig(sceneConfig, patch) {
+  return deepMerge(sceneConfig, patch);
+}
+
+// src/hooks/useSceneConfig.ts
+function useSceneConfig(initialSceneConfig) {
+  const initialSceneConfigRef = (0, import_react45.useRef)(null);
+  const [sceneConfig, setSceneConfig] = (0, import_react45.useState)(() => {
+    const initial = typeof initialSceneConfig === "function" ? initialSceneConfig() : initialSceneConfig;
+    initialSceneConfigRef.current = initial;
+    return initial;
+  });
+  const updateSceneConfig = (0, import_react45.useCallback)((update) => {
+    setSceneConfig((current) => {
+      const patch = typeof update === "function" ? update(current) : update;
+      return patchSceneConfig(current, patch);
+    });
+  }, []);
+  const resetSceneConfig = (0, import_react45.useCallback)(() => {
+    const initial = initialSceneConfigRef.current;
+    if (initial) setSceneConfig(initial);
+  }, []);
+  return {
+    sceneConfig,
+    setSceneConfig,
+    updateSceneConfig,
+    resetSceneConfig
+  };
+}
+
+// src/hooks/useViewerHover.ts
+var import_react46 = require("react");
 function useViewerHover() {
-  const [hoveredObjectBinding, setHoveredObjectBinding] = (0, import_react45.useState)(null);
-  const handleHoveredObject = (0, import_react45.useCallback)(
+  const [hoveredObjectBinding, setHoveredObjectBinding] = (0, import_react46.useState)(null);
+  const handleHoveredObject = (0, import_react46.useCallback)(
     (binding) => {
       setHoveredObjectBinding(binding);
     },
@@ -17758,18 +17796,18 @@ function useViewerHover() {
 }
 
 // src/hooks/useViewerModel.ts
-var import_react46 = require("react");
+var import_react47 = require("react");
 var import_three22 = require("three");
 function toTuple2(vector) {
   return [vector.x, vector.y, vector.z];
 }
 function useViewerModel() {
-  const [isLoading, setIsLoading] = (0, import_react46.useState)(true);
-  const [isReady, setIsReady] = (0, import_react46.useState)(false);
-  const [error, setError] = (0, import_react46.useState)(null);
-  const [bounds, setBounds] = (0, import_react46.useState)(null);
-  const [objectCount, setObjectCount] = (0, import_react46.useState)(0);
-  const handleModelLoaded = (0, import_react46.useCallback)((scene) => {
+  const [isLoading, setIsLoading] = (0, import_react47.useState)(true);
+  const [isReady, setIsReady] = (0, import_react47.useState)(false);
+  const [error, setError] = (0, import_react47.useState)(null);
+  const [bounds, setBounds] = (0, import_react47.useState)(null);
+  const [objectCount, setObjectCount] = (0, import_react47.useState)(0);
+  const handleModelLoaded = (0, import_react47.useCallback)((scene) => {
     const box = new import_three22.Box3().setFromObject(scene);
     const min = box.min.clone();
     const max = box.max.clone();
@@ -17794,14 +17832,14 @@ function useViewerModel() {
     setIsLoading(false);
     setIsReady(true);
   }, []);
-  const handleLoadError = (0, import_react46.useCallback)((nextError) => {
+  const handleLoadError = (0, import_react47.useCallback)((nextError) => {
     setError(nextError);
     setBounds(null);
     setObjectCount(0);
     setIsLoading(false);
     setIsReady(false);
   }, []);
-  const resetModelState = (0, import_react46.useCallback)(() => {
+  const resetModelState = (0, import_react47.useCallback)(() => {
     setIsLoading(true);
     setIsReady(false);
     setError(null);
@@ -17821,10 +17859,10 @@ function useViewerModel() {
 }
 
 // src/hooks/useViewerActions.ts
-var import_react47 = require("react");
+var import_react48 = require("react");
 function useViewerActions(objectBindings, options = {}) {
   const { onAction, onObjectBindingsChange } = options;
-  const getActionsForObject = (0, import_react47.useCallback)(
+  const getActionsForObject = (0, import_react48.useCallback)(
     (objectId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
       if (!bindingKey) {
@@ -17834,7 +17872,7 @@ function useViewerActions(objectBindings, options = {}) {
     },
     [objectBindings]
   );
-  const runAction = (0, import_react47.useCallback)(
+  const runAction = (0, import_react48.useCallback)(
     (objectId, actionId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
       if (!bindingKey) {
@@ -17876,7 +17914,7 @@ function useViewerActions(objectBindings, options = {}) {
 }
 
 // src/hooks/useShareableViewerState.ts
-var import_react48 = require("react");
+var import_react49 = require("react");
 function serializeState(cameraState, objectBindings, selectedObjectBinding) {
   const hidden = Object.values(objectBindings).filter((binding) => binding.visible === false).map((binding) => binding.id);
   return {
@@ -17896,8 +17934,8 @@ function useShareableViewerState({
   debounceMs = 400,
   autoSync = true
 }) {
-  const lastWrittenRawRef = (0, import_react48.useRef)(null);
-  const buildHash = (0, import_react48.useCallback)(() => {
+  const lastWrittenRawRef = (0, import_react49.useRef)(null);
+  const buildHash = (0, import_react49.useCallback)(() => {
     const state = serializeState(
       cameraState,
       objectBindings,
@@ -17905,12 +17943,12 @@ function useShareableViewerState({
     );
     return `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
   }, [cameraState, objectBindings, selectedObjectBinding, paramKey]);
-  const getShareUrl = (0, import_react48.useCallback)(() => {
+  const getShareUrl = (0, import_react49.useCallback)(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     return url.toString();
   }, [buildHash]);
-  const syncUrl = (0, import_react48.useCallback)(() => {
+  const syncUrl = (0, import_react49.useCallback)(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     window.history.replaceState(null, "", url.toString());
@@ -17918,7 +17956,7 @@ function useShareableViewerState({
       paramKey
     );
   }, [buildHash, paramKey]);
-  const latestStateRef = (0, import_react48.useRef)({
+  const latestStateRef = (0, import_react49.useRef)({
     cameraState,
     objectBindings,
     selectedObjectBinding
@@ -17928,9 +17966,9 @@ function useShareableViewerState({
     objectBindings,
     selectedObjectBinding
   };
-  const [restoreAttempted, setRestoreAttempted] = (0, import_react48.useState)(false);
-  const lastSyncedHashRef = (0, import_react48.useRef)(null);
-  (0, import_react48.useEffect)(() => {
+  const [restoreAttempted, setRestoreAttempted] = (0, import_react49.useState)(false);
+  const lastSyncedHashRef = (0, import_react49.useRef)(null);
+  (0, import_react49.useEffect)(() => {
     if (!autoSync || !restoreAttempted) return;
     const tick = () => {
       const current = latestStateRef.current;
@@ -17952,9 +17990,9 @@ function useShareableViewerState({
     const id = window.setInterval(tick, debounceMs);
     return () => window.clearInterval(id);
   }, [autoSync, restoreAttempted, debounceMs, paramKey]);
-  const lastRestoredRawRef = (0, import_react48.useRef)(null);
-  const restoringRawRef = (0, import_react48.useRef)(null);
-  const restoreFromUrl = (0, import_react48.useCallback)(async () => {
+  const lastRestoredRawRef = (0, import_react49.useRef)(null);
+  const restoringRawRef = (0, import_react49.useRef)(null);
+  const restoreFromUrl = (0, import_react49.useCallback)(async () => {
     setRestoreAttempted(true);
     const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : window.location.hash;
     const raw = new URLSearchParams(rawHash).get(paramKey);
@@ -18007,7 +18045,7 @@ function useShareableViewerState({
     setCameraState,
     setSelectedObjectBinding
   ]);
-  (0, import_react48.useEffect)(() => {
+  (0, import_react49.useEffect)(() => {
     const handleHashChange = () => {
       void restoreFromUrl();
     };
@@ -18027,9 +18065,11 @@ function useShareableViewerState({
   SimpleModelViewer,
   material,
   patchBindings,
+  patchSceneConfig,
   useObjectBinding,
   useObjectBindingIds,
   useObjectBindings,
+  useSceneConfig,
   useShareableViewerState,
   useViewerActions,
   useViewerAnimations,

package/dist/index.mjs

@@ -17697,15 +17697,12 @@ function useObjectBindingIds(objectBindings) {
 // src/hooks/useObjectBindings.ts
 import { useCallback as useCallback12, useMemo as useMemo20, useState as useState28 } from "react";
 
-// src/utils/patchBindings.ts
+// src/utils/deepMerge.ts
 function isPlainObject2(value) {
   if (typeof value !== "object" || value === null) return false;
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function isBindingEditArray(value) {
-  return Array.isArray(value) && value.length > 0 && typeof value[0] !== "string";
-}
 function deepMerge(base, patch) {
   if (!isPlainObject2(patch)) return patch;
   const target = isPlainObject2(base) ? { ...base } : {};
@@ -17715,6 +17712,11 @@ function deepMerge(base, patch) {
   }
   return target;
 }
+
+// src/utils/patchBindings.ts
+function isBindingEditArray(value) {
+  return Array.isArray(value) && value.length > 0 && typeof value[0] !== "string";
+}
 function patchBindings(bindings, objectIdOrEdits, patch) {
   const edits = isBindingEditArray(objectIdOrEdits) ? objectIdOrEdits : [{ ids: objectIdOrEdits, patch: patch ?? {} }];
   let next = bindings;
@@ -17744,7 +17746,7 @@ function getHiddenObjects(objectBindings) {
 }
 function useObjectBindings(initialBindings) {
   const [objectBindings, setObjectBindings] = useState28(initialBindings);
-  const patch = useCallback12(
+  const updateObjectBindings = useCallback12(
     (objectIdOrEdits, patchValue) => {
       setObjectBindings(
         (current) => patchValue === void 0 ? patchBindings(current, objectIdOrEdits) : patchBindings(
@@ -17757,16 +17759,16 @@ function useObjectBindings(initialBindings) {
     []
   );
   const setMaterial = useCallback12(
-    (objectId, value) => patch(objectId, material(value)),
-    [patch]
+    (objectId, value) => updateObjectBindings(objectId, material(value)),
+    [updateObjectBindings]
   );
   const setBaseColor = useCallback12(
     (objectId, color) => setMaterial(objectId, { baseColor: color }),
     [setMaterial]
   );
   const resetMaterial = useCallback12(
-    (objectId) => patch(objectId, { style: { material: void 0 } }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { style: { material: void 0 } }),
+    [updateObjectBindings]
   );
   const getMaterial = useCallback12(
     (objectId) => {
@@ -17776,12 +17778,12 @@ function useObjectBindings(initialBindings) {
     [objectBindings]
   );
   const hideObject = useCallback12(
-    (objectId) => patch(objectId, { visible: false }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { visible: false }),
+    [updateObjectBindings]
   );
   const showObject = useCallback12(
-    (objectId) => patch(objectId, { visible: true }),
-    [patch]
+    (objectId) => updateObjectBindings(objectId, { visible: true }),
+    [updateObjectBindings]
   );
   const toggleObjectVisibility = useCallback12(
     (objectId) => {
@@ -17827,7 +17829,7 @@ function useObjectBindings(initialBindings) {
   return {
     objectBindings,
     setObjectBindings,
-    patch,
+    updateObjectBindings,
     setMaterial,
     setBaseColor,
     resetMaterial,
@@ -17842,11 +17844,45 @@ function useObjectBindings(initialBindings) {
   };
 }
 
+// src/hooks/useSceneConfig.ts
+import { useCallback as useCallback13, useRef as useRef20, useState as useState29 } from "react";
+
+// src/utils/patchSceneConfig.ts
+function patchSceneConfig(sceneConfig, patch) {
+  return deepMerge(sceneConfig, patch);
+}
+
+// src/hooks/useSceneConfig.ts
+function useSceneConfig(initialSceneConfig) {
+  const initialSceneConfigRef = useRef20(null);
+  const [sceneConfig, setSceneConfig] = useState29(() => {
+    const initial = typeof initialSceneConfig === "function" ? initialSceneConfig() : initialSceneConfig;
+    initialSceneConfigRef.current = initial;
+    return initial;
+  });
+  const updateSceneConfig = useCallback13((update) => {
+    setSceneConfig((current) => {
+      const patch = typeof update === "function" ? update(current) : update;
+      return patchSceneConfig(current, patch);
+    });
+  }, []);
+  const resetSceneConfig = useCallback13(() => {
+    const initial = initialSceneConfigRef.current;
+    if (initial) setSceneConfig(initial);
+  }, []);
+  return {
+    sceneConfig,
+    setSceneConfig,
+    updateSceneConfig,
+    resetSceneConfig
+  };
+}
+
 // src/hooks/useViewerHover.ts
-import { useCallback as useCallback13, useState as useState29 } from "react";
+import { useCallback as useCallback14, useState as useState30 } from "react";
 function useViewerHover() {
-  const [hoveredObjectBinding, setHoveredObjectBinding] = useState29(null);
-  const handleHoveredObject = useCallback13(
+  const [hoveredObjectBinding, setHoveredObjectBinding] = useState30(null);
+  const handleHoveredObject = useCallback14(
     (binding) => {
       setHoveredObjectBinding(binding);
     },
@@ -17859,18 +17895,18 @@ function useViewerHover() {
 }
 
 // src/hooks/useViewerModel.ts
-import { useCallback as useCallback14, useState as useState30 } from "react";
+import { useCallback as useCallback15, useState as useState31 } from "react";
 import { Box3 as Box36, Vector3 as Vector310 } from "three";
 function toTuple2(vector) {
   return [vector.x, vector.y, vector.z];
 }
 function useViewerModel() {
-  const [isLoading, setIsLoading] = useState30(true);
-  const [isReady, setIsReady] = useState30(false);
-  const [error, setError] = useState30(null);
-  const [bounds, setBounds] = useState30(null);
-  const [objectCount, setObjectCount] = useState30(0);
-  const handleModelLoaded = useCallback14((scene) => {
+  const [isLoading, setIsLoading] = useState31(true);
+  const [isReady, setIsReady] = useState31(false);
+  const [error, setError] = useState31(null);
+  const [bounds, setBounds] = useState31(null);
+  const [objectCount, setObjectCount] = useState31(0);
+  const handleModelLoaded = useCallback15((scene) => {
     const box = new Box36().setFromObject(scene);
     const min = box.min.clone();
     const max = box.max.clone();
@@ -17895,14 +17931,14 @@ function useViewerModel() {
     setIsLoading(false);
     setIsReady(true);
   }, []);
-  const handleLoadError = useCallback14((nextError) => {
+  const handleLoadError = useCallback15((nextError) => {
     setError(nextError);
     setBounds(null);
     setObjectCount(0);
     setIsLoading(false);
     setIsReady(false);
   }, []);
-  const resetModelState = useCallback14(() => {
+  const resetModelState = useCallback15(() => {
     setIsLoading(true);
     setIsReady(false);
     setError(null);
@@ -17922,10 +17958,10 @@ function useViewerModel() {
 }
 
 // src/hooks/useViewerActions.ts
-import { useCallback as useCallback15 } from "react";
+import { useCallback as useCallback16 } from "react";
 function useViewerActions(objectBindings, options = {}) {
   const { onAction, onObjectBindingsChange } = options;
-  const getActionsForObject = useCallback15(
+  const getActionsForObject = useCallback16(
     (objectId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
       if (!bindingKey) {
@@ -17935,7 +17971,7 @@ function useViewerActions(objectBindings, options = {}) {
     },
     [objectBindings]
   );
-  const runAction = useCallback15(
+  const runAction = useCallback16(
     (objectId, actionId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
       if (!bindingKey) {
@@ -17977,7 +18013,7 @@ function useViewerActions(objectBindings, options = {}) {
 }
 
 // src/hooks/useShareableViewerState.ts
-import { useCallback as useCallback16, useEffect as useEffect22, useRef as useRef20, useState as useState31 } from "react";
+import { useCallback as useCallback17, useEffect as useEffect22, useRef as useRef21, useState as useState32 } from "react";
 function serializeState(cameraState, objectBindings, selectedObjectBinding) {
   const hidden = Object.values(objectBindings).filter((binding) => binding.visible === false).map((binding) => binding.id);
   return {
@@ -17997,8 +18033,8 @@ function useShareableViewerState({
   debounceMs = 400,
   autoSync = true
 }) {
-  const lastWrittenRawRef = useRef20(null);
-  const buildHash = useCallback16(() => {
+  const lastWrittenRawRef = useRef21(null);
+  const buildHash = useCallback17(() => {
     const state = serializeState(
       cameraState,
       objectBindings,
@@ -18006,12 +18042,12 @@ function useShareableViewerState({
     );
     return `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
   }, [cameraState, objectBindings, selectedObjectBinding, paramKey]);
-  const getShareUrl = useCallback16(() => {
+  const getShareUrl = useCallback17(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     return url.toString();
   }, [buildHash]);
-  const syncUrl = useCallback16(() => {
+  const syncUrl = useCallback17(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     window.history.replaceState(null, "", url.toString());
@@ -18019,7 +18055,7 @@ function useShareableViewerState({
       paramKey
     );
   }, [buildHash, paramKey]);
-  const latestStateRef = useRef20({
+  const latestStateRef = useRef21({
     cameraState,
     objectBindings,
     selectedObjectBinding
@@ -18029,8 +18065,8 @@ function useShareableViewerState({
     objectBindings,
     selectedObjectBinding
   };
-  const [restoreAttempted, setRestoreAttempted] = useState31(false);
-  const lastSyncedHashRef = useRef20(null);
+  const [restoreAttempted, setRestoreAttempted] = useState32(false);
+  const lastSyncedHashRef = useRef21(null);
   useEffect22(() => {
     if (!autoSync || !restoreAttempted) return;
     const tick = () => {
@@ -18053,9 +18089,9 @@ function useShareableViewerState({
     const id = window.setInterval(tick, debounceMs);
     return () => window.clearInterval(id);
   }, [autoSync, restoreAttempted, debounceMs, paramKey]);
-  const lastRestoredRawRef = useRef20(null);
-  const restoringRawRef = useRef20(null);
-  const restoreFromUrl = useCallback16(async () => {
+  const lastRestoredRawRef = useRef21(null);
+  const restoringRawRef = useRef21(null);
+  const restoreFromUrl = useCallback17(async () => {
     setRestoreAttempted(true);
     const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : window.location.hash;
     const raw = new URLSearchParams(rawHash).get(paramKey);
@@ -18127,9 +18163,11 @@ export {
   SimpleModelViewer,
   material,
   patchBindings,
+  patchSceneConfig,
   useObjectBinding,
   useObjectBindingIds,
   useObjectBindings,
+  useSceneConfig,
   useShareableViewerState,
   useViewerActions,
   useViewerAnimations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveroom-tech/react-immersive",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",