@liveroom-tech/react-immersive 1.0.3 → 1.1.0

package/README.md

@@ -25,7 +25,7 @@ import {
 } from "@liveroom-tech/react-immersive";
 ```
 
-It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActionEvent`, `SceneConfig`, `AnimationControls`, and related shapes used throughout this document.
+It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActionEvent`, `SceneConfig`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
 
 `ModelViewer` provides:
 
@@ -42,6 +42,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActio
 - optional hiding of either built-in panel through `showObjectBindingDataPanel` and `showSceneObjectsPanel`
 - optional model export button through `showDownloadButton` and `downloadFilename`, plus independent `showResetButton` / `showDownloadButtons` toggles for the rest of that action bar
 - 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`
 - 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`)
@@ -71,7 +73,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActio
 - editable binding fields for identity, basics, style, actions, metrics, metadata, and saved camera state
 - a one-click material preset gallery (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.)
 - undo/redo for both the Object tab's bindings and the Scene tab's config, independently, with `Cmd/Ctrl+Z` / `Cmd/Ctrl+Shift+Z` shortcuts
-- a Scene tab for the same `sceneConfig` shape `ModelViewer` accepts (lighting, environment, background, post-processing, animations, annotations)
+- a Scene tab for the same `sceneConfig` shape `ModelViewer` accepts (lighting, environment, background, post-processing, animations, annotations, and cinematic camera paths)
+- a Cinematic sub-tab for authoring a camera path visually — frame the model, capture the current view as a waypoint, reorder/preview/delete waypoints, and toggle loop/auto-play; stored on `sceneConfig.cinematic` and replayed by `ModelViewer`'s `cinematic` prop
 - import a previously exported `objectBindings.json` or `sceneConfig.json` and merge it back onto the current model/config
 - live preview using `ModelViewer`
 - export as JSON or TypeScript — bundled into a `.zip` with a `materials/` folder automatically when any texture field was filled by file upload, otherwise a plain file
@@ -694,6 +697,8 @@ type Props = {
   ktx2TranscoderPath?: string | false;
   meshopt?: boolean;
   showMeasureTools?: boolean;
+  showExplodeControls?: boolean;
+  cinematic?: boolean | CinematicConfig;
   measurementUnit?: string;
   enableXR?: boolean;
   usdzUrl?: string;
@@ -1390,6 +1395,66 @@ Default:
 "m";
 ```
 
+### `showExplodeControls`
+
+Optional boolean that shows an exploded-view slider over the canvas. It slides each bound part outward from the model center to reveal interior/assembly structure, then back to reassemble. Best suited to static product/CAD models — the offset writes node positions each frame, so it conflicts with a playing skeletal animation.
+
+Default:
+
+```ts
+false;
+```
+
+### `cinematic`
+
+Optional cinematic auto-camera. The camera glides along a path on its own, like a film — ideal for showing off a gallery, apartment, or product with no user interaction. Renders a play/pause button over the canvas; grabbing the camera (or selecting a part) pauses it.
+
+```ts
+cinematic?: boolean | CinematicConfig;
+
+type CinematicConfig = {
+  waypoints?: CinematicWaypoint[]; // camera keyframes to glide through
+  duration?: number; // seconds for one full pass (auto-scales when omitted)
+  loop?: boolean; // default true
+  autoPlay?: boolean; // start once the model has loaded and framed (default false)
+};
+
+type CinematicWaypoint = {
+  position: [number, number, number];
+  target: [number, number, number]; // world-space look-at point
+};
+```
+
+- Boolean `true` (or an object with fewer than two waypoints) gives a zero-config **showcase orbit** around the model's bounding sphere.
+- Two or more `waypoints` author a **walkthrough**: the camera follows a smooth Catmull-Rom spline through them at a constant on-screen speed, looping seamlessly.
+- Waypoints are easiest to capture visually in `BindingBuilder`'s **Cinematic** tab, which stores them on `sceneConfig.cinematic`.
+
+A path can also come from `sceneConfig.cinematic`. The `cinematic` prop overrides it: a boolean toggles the feature (`true` keeps any authored waypoints, `false` forces it off), and an object overrides field-by-field — so you can keep the authored waypoints while overriding, say, `autoPlay` or `loop`.
+
+```tsx
+// Zero-config showcase orbit
+<ModelViewer cinematic ... />
+
+// Authored walkthrough
+<ModelViewer
+  cinematic={{
+    waypoints: [
+      { position: [4, 2, 6], target: [0, 1, 0] },
+      { position: [-3, 2, 4], target: [0, 1, 0] },
+      { position: [-5, 2, -2], target: [0, 1, 0] },
+    ],
+    loop: true,
+    autoPlay: true,
+  }}
+  ...
+/>
+
+// Keep the BindingBuilder-authored path, just autoplay it
+<ModelViewer sceneConfig={sceneConfig} cinematic={{ autoPlay: true }} ... />
+```
+
+Default: disabled.
+
 ### `enableXR`
 
 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.

package/dist/index.d.mts

@@ -291,6 +291,17 @@ type SceneAnnotationMarker = {
     title: string;
     description: string;
 };
+type SceneCinematicWaypoint = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type SceneCinematicConfig = {
+    enabled: boolean;
+    waypoints: SceneCinematicWaypoint[];
+    duration?: number;
+    loop: boolean;
+    autoPlay: boolean;
+};
 type SceneConfig = {
     model: SceneModelConfig;
     camera: SceneCameraConfig;
@@ -303,6 +314,7 @@ type SceneConfig = {
     postProcessing: ScenePostProcessingConfig;
     animations: SceneAnimationConfig;
     annotations: SceneAnnotationMarker[];
+    cinematic?: SceneCinematicConfig;
 };
 
 type CanvasCamera = ComponentProps<typeof Canvas>["camera"];
@@ -332,6 +344,17 @@ declare function Viewer({ children, camera, backgroundColor, shadows, sceneConfi
 
 type PerformanceProfile = "auto" | "high" | "low";
 
+type CinematicWaypoint = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type CinematicConfig = {
+    waypoints?: CinematicWaypoint[];
+    duration?: number;
+    loop?: boolean;
+    autoPlay?: boolean;
+};
+
 type MouseControllerPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'center' | 'center-bottom' | 'center-top';
 
 type ObjectBindingAction = {
@@ -578,12 +601,13 @@ type ModelViewerProps = {
     meshopt?: boolean;
     showMeasureTools?: boolean;
     showExplodeControls?: boolean;
+    cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
     enableXR?: boolean;
     usdzUrl?: 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, showDownloadButtons, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, measurementUnit, enableXR, usdzUrl, 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, showDownloadButtons, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -688,4 +712,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 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 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, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.d.ts

@@ -291,6 +291,17 @@ type SceneAnnotationMarker = {
     title: string;
     description: string;
 };
+type SceneCinematicWaypoint = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type SceneCinematicConfig = {
+    enabled: boolean;
+    waypoints: SceneCinematicWaypoint[];
+    duration?: number;
+    loop: boolean;
+    autoPlay: boolean;
+};
 type SceneConfig = {
     model: SceneModelConfig;
     camera: SceneCameraConfig;
@@ -303,6 +314,7 @@ type SceneConfig = {
     postProcessing: ScenePostProcessingConfig;
     animations: SceneAnimationConfig;
     annotations: SceneAnnotationMarker[];
+    cinematic?: SceneCinematicConfig;
 };
 
 type CanvasCamera = ComponentProps<typeof Canvas>["camera"];
@@ -332,6 +344,17 @@ declare function Viewer({ children, camera, backgroundColor, shadows, sceneConfi
 
 type PerformanceProfile = "auto" | "high" | "low";
 
+type CinematicWaypoint = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type CinematicConfig = {
+    waypoints?: CinematicWaypoint[];
+    duration?: number;
+    loop?: boolean;
+    autoPlay?: boolean;
+};
+
 type MouseControllerPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'center' | 'center-bottom' | 'center-top';
 
 type ObjectBindingAction = {
@@ -578,12 +601,13 @@ type ModelViewerProps = {
     meshopt?: boolean;
     showMeasureTools?: boolean;
     showExplodeControls?: boolean;
+    cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
     enableXR?: boolean;
     usdzUrl?: 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, showDownloadButtons, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, measurementUnit, enableXR, usdzUrl, 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, showDownloadButtons, showLoadingOverlay, showMouseController, mouseControllerPosition, mouseControllerOpacity, moveSensitivity, zoomSensitivity, sceneConfig, disableZoom, zoomOnSelected, highlightOnHover, onAutoFit, refitOnResize, renderMode, maxDpr, performanceProfile, dracoDecoderPath, ktx2TranscoderPath, meshopt, showMeasureTools, showExplodeControls, cinematic, measurementUnit, enableXR, usdzUrl, showAnnotationNavigation, }: ModelViewerProps): react_jsx_runtime.JSX.Element;
 
 declare function BindingBuilder({ licenseKey }: {
     licenseKey: string;
@@ -688,4 +712,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 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 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, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };