@liveroom-tech/react-immersive 1.3.4 → 1.4.0

package/README.md

@@ -41,10 +41,13 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActio
 - optional custom right scene objects panel through `customSceneObjectsPanel`
 - optional hiding of either built-in panel through `showObjectBindingDataPanel` and `showSceneObjectsPanel`
 - optional model export button through `showDownloadButton` and `downloadFilename`, plus an independent `showResetButton` toggle for the rest of that action bar
+- an optional UV Checker toolbar button through `showUvCheckerButton`, for inspecting UV scale, stretching, seams, orientation, and missing UV0 coordinates directly in `ModelViewer`
 - click-to-measure distance tool and a bounding-box dimensions overlay through `showMeasureTools` and `measurementUnit`
 - an exploded-view slider that slides each bound part outward from the model center to reveal interior/assembly structure through `showExplodeControls`
 - a cinematic auto-camera that glides the camera along authored waypoints (or a zero-config showcase orbit), like a film, through `cinematic` — with a play/pause control that yields the moment you touch the camera
 - a guided-tour control cluster (Previous/Stop/Next) for stepping through annotations, toggleable via `showAnnotationNavigation`
+- optional annotation detail popups on marker hover via `showAnnotationOnHover`
+- PBR, Matcap, and UV Checker renderer modes, with the checker exposing UV stretching, seams, rotation, and missing UV0 data directly on the model
 - a `sceneConfig` prop accepting the same scene-wide config (lighting, environment, background, post-processing, animations, annotations) authored by `BindingBuilder`'s Scene tab
 - render-loop and perf tuning through `renderMode`, `maxDpr`, `performanceProfile`, and compressed-asset decoder options (`dracoDecoderPath`, `ktx2TranscoderPath`, `meshopt`)
 - WebXR "View in your space" (AR) and "Enter VR" through `enableXR`, with tap-to-place, pinch-to-resize, and twist-to-rotate AR placement gestures
@@ -696,6 +699,7 @@ type Props = {
   ktx2TranscoderPath?: string | false;
   meshopt?: boolean;
   showMeasureTools?: boolean;
+  showUvCheckerButton?: boolean;
   showExplodeControls?: boolean;
   cinematic?: boolean | CinematicConfig;
   measurementUnit?: string;
@@ -704,6 +708,7 @@ type Props = {
   arScaleMode?: "normalized" | "real-world";
   mobileHandoffUrl?: string;
   showAnnotationNavigation?: boolean;
+  showAnnotationOnHover?: boolean;
 };
 ```
 
@@ -1133,7 +1138,8 @@ true;
 
 ### `showDownloadButton`
 
-Optional boolean that enables the download split-button (export GLB / export PNG screenshot).
+Optional boolean that enables the download split-button (export GLB, export PNG
+screenshot, or export the model's UV layout).
 
 Default:
 
@@ -1141,6 +1147,12 @@ Default:
 true;
 ```
 
+UV export downloads an editable 2048×2048 SVG UV-island outline when the model
+uses one material. For multi-material models it downloads a ZIP containing one
+SVG texture template per material. Meshes without a `uv` attribute are omitted;
+when the model has no UV coordinates, the viewer reports that no layout is
+available.
+
 The bottom-right action bar renders when at least one of `showResetButton`, `showDownloadButton`, or (`showAnnotationNavigation` with annotations present) is `true`.
 
 ### `downloadFilename`
@@ -1249,6 +1261,22 @@ Optional scene-wide configuration object (`SceneConfig`) covering model, camera,
 
 `sceneConfig.animations` drives autoplay and per-clip playback settings, and `sceneConfig.annotations` seeds the annotation markers rendered on the model.
 
+`sceneConfig.model.renderer` accepts `"pbr"`, `"matcap"`, or `"uv-checker"`.
+UV Checker temporarily replaces every mesh material with an unlit numbered test
+chart without changing `objectBindings` or uploaded textures. Switching back
+restores the original material references. Meshes without UV0 coordinates appear
+magenta and trigger an explanatory notice.
+
+```tsx
+<ModelViewer
+  {...props}
+  sceneConfig={{
+    ...sceneConfig,
+    model: { ...sceneConfig.model, renderer: "uv-checker" },
+  }}
+/>
+```
+
 ### `disableZoom`
 
 Optional boolean. When `true`, the viewer never zooms the camera to an object on selection (selection still highlights and fires callbacks).
@@ -1366,6 +1394,20 @@ meshopt?: boolean;
 
 DRACO, Meshopt, and KTX2 decoding are enabled by default via hosted decoder/transcoder bundles, fetched lazily only when the model needs them. Pass a path to self-host the decoder/transcoder files, or `false` to disable that decoder.
 
+### `showUvCheckerButton`
+
+Optional boolean that shows a UV Checker toggle button over the canvas. Turning it on temporarily replaces the model's materials with the numbered diagnostic texture; turning it off restores the renderer configured by `sceneConfig`. Missing UV0 coordinates are shown in magenta.
+
+```tsx
+<ModelViewer showUvCheckerButton {...props} />
+```
+
+Default:
+
+```ts
+false;
+```
+
 ### `showMeasureTools`
 
 Optional boolean that shows a click-to-measure toolbar over the canvas: click two points on the model for a distance readout, plus a toggleable bounding-box dimensions overlay.
@@ -1516,6 +1558,23 @@ Default:
 true;
 ```
 
+### `showAnnotationOnHover`
+
+Optional boolean that temporarily opens an annotation's detail popup when the
+pointer hovers over its marker. Moving the pointer away closes the hover popup
+after a short grace period. Clicking a marker still locks its popup open until
+it is closed.
+
+Default:
+
+```ts
+false;
+```
+
+```tsx
+<ModelViewer {...props} showAnnotationOnHover />
+```
+
 ### Theming the scene objects / object binding panels
 
 The scene objects panel and object binding data panel read their colors,

package/dist/index.d.mts

@@ -26,10 +26,12 @@ type SceneLightingConfig = {
     };
     lights: SceneLight[];
 };
+declare const SCENE_MODEL_RENDERERS: readonly ["pbr", "matcap", "uv-checker"];
+type SceneModelRenderer = (typeof SCENE_MODEL_RENDERERS)[number];
 type SceneModelConfig = {
     rotation: [number, number, number];
     showAdvancedRotation: boolean;
-    renderer: "pbr" | "matcap";
+    renderer: SceneModelRenderer;
     shading: "lit" | "unlit" | "normals";
 };
 type SceneCameraConfig = {
@@ -610,6 +612,7 @@ type ModelViewerProps = {
     ktx2TranscoderPath?: string | false;
     meshopt?: boolean;
     showMeasureTools?: boolean;
+    showUvCheckerButton?: boolean;
     showExplodeControls?: boolean;
     cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
@@ -618,8 +621,9 @@ type ModelViewerProps = {
     arScaleMode?: XRScaleMode;
     mobileHandoffUrl?: string;
     showAnnotationNavigation?: boolean;
+    showAnnotationOnHover?: 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, arScaleMode, 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, showUvCheckerButton, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, arScaleMode, mobileHandoffUrl, showAnnotationNavigation, showAnnotationOnHover, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -724,4 +728,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, type XRScaleMode, 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, 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, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.d.ts

@@ -26,10 +26,12 @@ type SceneLightingConfig = {
     };
     lights: SceneLight[];
 };
+declare const SCENE_MODEL_RENDERERS: readonly ["pbr", "matcap", "uv-checker"];
+type SceneModelRenderer = (typeof SCENE_MODEL_RENDERERS)[number];
 type SceneModelConfig = {
     rotation: [number, number, number];
     showAdvancedRotation: boolean;
-    renderer: "pbr" | "matcap";
+    renderer: SceneModelRenderer;
     shading: "lit" | "unlit" | "normals";
 };
 type SceneCameraConfig = {
@@ -610,6 +612,7 @@ type ModelViewerProps = {
     ktx2TranscoderPath?: string | false;
     meshopt?: boolean;
     showMeasureTools?: boolean;
+    showUvCheckerButton?: boolean;
     showExplodeControls?: boolean;
     cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
@@ -618,8 +621,9 @@ type ModelViewerProps = {
     arScaleMode?: XRScaleMode;
     mobileHandoffUrl?: string;
     showAnnotationNavigation?: boolean;
+    showAnnotationOnHover?: 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, arScaleMode, 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, showUvCheckerButton, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, arScaleMode, mobileHandoffUrl, showAnnotationNavigation, showAnnotationOnHover, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -724,4 +728,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, type XRScaleMode, 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, 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, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };