@liveroom-tech/react-immersive 2.0.0 → 2.1.1

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 };