@liveroom-tech/react-immersive 1.1.6 → 1.1.7

package/README.md

@@ -701,6 +701,8 @@ type Props = {
   measurementUnit?: string;
   enableXR?: boolean;
   usdzUrl?: string;
+  arScaleMode?: "normalized" | "real-world";
+  mobileHandoffUrl?: string;
   showAnnotationNavigation?: boolean;
 };
 ```
@@ -1448,7 +1450,11 @@ Default: disabled.
 
 Optional boolean that enables XR entry points. On WebXR-capable browsers, the viewer shows a **"View in your space"** (AR) and/or **"Enter VR"** button once `navigator.xr.isSessionSupported(...)` resolves `true` for that mode. On iPhone/iPad, WebXR AR is not available, but if you also pass [`usdzUrl`](#usdzUrl), the viewer shows a **"View in AR"** button that launches Apple Quick Look instead.
 
-On entering a session the model is normalized (scaled to ~1 m on its longest axis) and rested on the floor a short distance in front of the viewer, so large/real-scale scenes are framed instead of engulfing the viewer.
+On entering a session the model is rested on the floor a short distance in front
+of the viewer. By default it is normalized to ~1 m on its longest axis so
+arbitrary uploads and room scenes are framed safely. Set
+[`arScaleMode`](#arscalemode) to `"real-world"` for product AR, which preserves
+the GLB's authored metre scale.
 
 **AR placement gestures** — inside an AR session the viewer now uses an explicit placement flow:
 
@@ -1485,6 +1491,21 @@ Notes:
 - Android / WebXR-capable devices ignore this and continue using the normal WebXR AR flow
 - if `usdzUrl` is omitted, Apple handheld devices simply won't get an AR button
 
+### `arScaleMode`
+
+Controls the initial model size inside WebXR AR and VR sessions.
+
+```ts
+arScaleMode?: "normalized" | "real-world";
+```
+
+- `"normalized"` (default) fits the longest model dimension to approximately
+  1 metre. Use this for arbitrary uploads and room-scale scenes.
+- `"real-world"` preserves the GLB's authored scale. glTF units are metres, so
+  use this for product models exported at their real dimensions.
+
+Users can still pinch to resize after placement in either mode.
+
 ### `showAnnotationNavigation`
 
 Optional boolean that shows the "Guided Tour" control cluster when the model has at least one annotation: a single "Guided Tour" button that, once started, becomes Previous/Stop/Next controls for stepping through annotations in order.

package/dist/index.d.mts

@@ -344,6 +344,8 @@ declare function Viewer({ children, camera, backgroundColor, shadows, sceneConfi
 
 type PerformanceProfile = "auto" | "high" | "low";
 
+type XRScaleMode = "normalized" | "real-world";
+
 type CinematicWaypoint = {
     position: [number, number, number];
     target: [number, number, number];
@@ -604,10 +606,11 @@ type ModelViewerProps = {
     measurementUnit?: string;
     enableXR?: boolean;
     usdzUrl?: string;
+    arScaleMode?: XRScaleMode;
     mobileHandoffUrl?: string;
     showAnnotationNavigation?: boolean;
 };
-declare function ModelViewer({ modelUrl, licenseKey, objectBindings, selectedObject, panelHoveredObject, onObjectBindingsChange, onObjectSelect, onObjectHover, onModelLoaded, onLoadError, onAction, onHiddenObjectsChange, onCameraChange, onViewerReady, onTextureUpload, onAnimationsReady, onAnnotationsChange, activeAnnotation: controlledActiveAnnotation, onActiveAnnotationChange, lights, camera, backgroundColor, shadows, showObjectBindingDataPanel, customObjectBindingDataPanel, customSceneObjectsPanel, showSceneObjectsPanel, showDownloadButton, downloadFilename, showResetButton, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, mobileHandoffUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
+declare function ModelViewer({ modelUrl, licenseKey, objectBindings, selectedObject, panelHoveredObject, onObjectBindingsChange, onObjectSelect, onObjectHover, onModelLoaded, onLoadError, onAction, onHiddenObjectsChange, onCameraChange, onViewerReady, onTextureUpload, onAnimationsReady, onAnnotationsChange, activeAnnotation: controlledActiveAnnotation, onActiveAnnotationChange, lights, camera, backgroundColor, shadows, showObjectBindingDataPanel, customObjectBindingDataPanel, customSceneObjectsPanel, showSceneObjectsPanel, showDownloadButton, downloadFilename, showResetButton, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, arScaleMode, mobileHandoffUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -712,4 +715,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 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 ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, 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 ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.d.ts

@@ -344,6 +344,8 @@ declare function Viewer({ children, camera, backgroundColor, shadows, sceneConfi
 
 type PerformanceProfile = "auto" | "high" | "low";
 
+type XRScaleMode = "normalized" | "real-world";
+
 type CinematicWaypoint = {
     position: [number, number, number];
     target: [number, number, number];
@@ -604,10 +606,11 @@ type ModelViewerProps = {
     measurementUnit?: string;
     enableXR?: boolean;
     usdzUrl?: string;
+    arScaleMode?: XRScaleMode;
     mobileHandoffUrl?: string;
     showAnnotationNavigation?: boolean;
 };
-declare function ModelViewer({ modelUrl, licenseKey, objectBindings, selectedObject, panelHoveredObject, onObjectBindingsChange, onObjectSelect, onObjectHover, onModelLoaded, onLoadError, onAction, onHiddenObjectsChange, onCameraChange, onViewerReady, onTextureUpload, onAnimationsReady, onAnnotationsChange, activeAnnotation: controlledActiveAnnotation, onActiveAnnotationChange, lights, camera, backgroundColor, shadows, showObjectBindingDataPanel, customObjectBindingDataPanel, customSceneObjectsPanel, showSceneObjectsPanel, showDownloadButton, downloadFilename, showResetButton, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, mobileHandoffUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
+declare function ModelViewer({ modelUrl, licenseKey, objectBindings, selectedObject, panelHoveredObject, onObjectBindingsChange, onObjectSelect, onObjectHover, onModelLoaded, onLoadError, onAction, onHiddenObjectsChange, onCameraChange, onViewerReady, onTextureUpload, onAnimationsReady, onAnnotationsChange, activeAnnotation: controlledActiveAnnotation, onActiveAnnotationChange, lights, camera, backgroundColor, shadows, showObjectBindingDataPanel, customObjectBindingDataPanel, customSceneObjectsPanel, showSceneObjectsPanel, showDownloadButton, downloadFilename, showResetButton, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, arScaleMode, mobileHandoffUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -712,4 +715,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 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 ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, 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 ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.js

@@ -3631,12 +3631,15 @@ var TARGET_SIZE = 1;
 var FORWARD_DISTANCE = 1;
 var MIN_USER_SCALE = 0.1;
 var MAX_USER_SCALE = 10;
-function computeNormalization(box) {
+function computeNormalization(box, scaleMode) {
   const [sx, sy, sz] = box.size;
   const cx = (box.min[0] + box.max[0]) / 2;
   const cz = (box.min[2] + box.max[2]) / 2;
   const maxDim = Math.max(sx, sy, sz) || 1;
-  return { scale: TARGET_SIZE / maxDim, offset: [-cx, -box.min[1], -cz] };
+  return {
+    scale: scaleMode === "real-world" ? 1 : TARGET_SIZE / maxDim,
+    offset: [-cx, -box.min[1], -cz]
+  };
 }
 function touchDistance(touches) {
   const dx = touches[0].clientX - touches[1].clientX;
@@ -3649,15 +3652,15 @@ function touchAngle(touches) {
   return Math.atan2(dy, dx);
 }
 var XRModelPresenter = (0, import_react14.forwardRef)(
-  function XRModelPresenter2({ box, children, onARStateChange }, ref) {
+  function XRModelPresenter2({ box, scaleMode, children, onARStateChange }, ref) {
     const placementRef = (0, import_react14.useRef)(null);
     const scaleRef = (0, import_react14.useRef)(null);
     const reticleRef = (0, import_react14.useRef)(null);
     const inSession = (0, import_xr3.useXR)((state) => state.session != null);
     const isAR = (0, import_xr3.useXR)((state) => state.mode === "immersive-ar");
     const normalization = (0, import_react14.useMemo)(
-      () => box ? computeNormalization(box) : null,
-      [box]
+      () => box ? computeNormalization(box, scaleMode) : null,
+      [box, scaleMode]
     );
     const placedPosition = (0, import_react14.useRef)(new import_three16.Vector3(0, 0, -FORWARD_DISTANCE));
     const userScale = (0, import_react14.useRef)(1);
@@ -5221,6 +5224,7 @@ function ModelViewer({
   measurementUnit = "m",
   enableXR = false,
   usdzUrl,
+  arScaleMode = "normalized",
   mobileHandoffUrl,
   showAnnotationNavigation = true
 }) {
@@ -6784,6 +6788,7 @@ function ModelViewer({
                           {
                             ref: xrPresenterRef,
                             box: measureBox,
+                            scaleMode: arScaleMode,
                             onARStateChange: handleARStateChange,
                             children: modelContent
                           }

package/dist/index.mjs

@@ -3672,12 +3672,15 @@ var TARGET_SIZE = 1;
 var FORWARD_DISTANCE = 1;
 var MIN_USER_SCALE = 0.1;
 var MAX_USER_SCALE = 10;
-function computeNormalization(box) {
+function computeNormalization(box, scaleMode) {
   const [sx, sy, sz] = box.size;
   const cx = (box.min[0] + box.max[0]) / 2;
   const cz = (box.min[2] + box.max[2]) / 2;
   const maxDim = Math.max(sx, sy, sz) || 1;
-  return { scale: TARGET_SIZE / maxDim, offset: [-cx, -box.min[1], -cz] };
+  return {
+    scale: scaleMode === "real-world" ? 1 : TARGET_SIZE / maxDim,
+    offset: [-cx, -box.min[1], -cz]
+  };
 }
 function touchDistance(touches) {
   const dx = touches[0].clientX - touches[1].clientX;
@@ -3690,15 +3693,15 @@ function touchAngle(touches) {
   return Math.atan2(dy, dx);
 }
 var XRModelPresenter = forwardRef2(
-  function XRModelPresenter2({ box, children, onARStateChange }, ref) {
+  function XRModelPresenter2({ box, scaleMode, children, onARStateChange }, ref) {
     const placementRef = useRef7(null);
     const scaleRef = useRef7(null);
     const reticleRef = useRef7(null);
     const inSession = useXR2((state) => state.session != null);
     const isAR = useXR2((state) => state.mode === "immersive-ar");
     const normalization = useMemo10(
-      () => box ? computeNormalization(box) : null,
-      [box]
+      () => box ? computeNormalization(box, scaleMode) : null,
+      [box, scaleMode]
     );
     const placedPosition = useRef7(new Vector35(0, 0, -FORWARD_DISTANCE));
     const userScale = useRef7(1);
@@ -5287,6 +5290,7 @@ function ModelViewer({
   measurementUnit = "m",
   enableXR = false,
   usdzUrl,
+  arScaleMode = "normalized",
   mobileHandoffUrl,
   showAnnotationNavigation = true
 }) {
@@ -6850,6 +6854,7 @@ function ModelViewer({
                           {
                             ref: xrPresenterRef,
                             box: measureBox,
+                            scaleMode: arScaleMode,
                             onARStateChange: handleARStateChange,
                             children: modelContent
                           }

package/package.json

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