@liveroom-tech/react-immersive 1.0.3 → 1.1.1

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
@@ -428,7 +431,7 @@ runAction("car-body", "toggle-visibility");
 Current note:
 
 - visibility-style actions (`toggle-visibility`) update binding data through `onObjectBindingsChange`
-- color/material actions still rely on `ModelViewer`'s built-in UI popovers, so `runAction` dispatches those events but does not open the internal color picker or texture upload popover by itself
+- color/material actions still rely on `ModelViewer`'s built-in UI, so `runAction` dispatches those events but does not open the built-in color picker or texture upload panel by itself
 
 ## `BindingBuilder`
 
@@ -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.
@@ -1662,7 +1727,7 @@ Notes:
 - each `style.material` group also accepts a texture-map slot (`metalnessMap`, `roughnessMap`, `normalMap`, `aoMap`, `clearcoatMap`, etc.); color maps are decoded as sRGB and data maps as linear automatically
 - `BindingBuilder` intentionally omits exact Sketchfab glossiness, cavity, and subsurface-scattering workflows; those require preprocessing or a different material pipeline
 - `cameraState` stores a saved camera view for the object; when both `position` and `target` are set, the viewer uses that view when the object is focused or selected instead of falling back to `fitToBox`
-- `metrics` and `metadata` are displayed in the side panel JSON preview
+- `metrics` and `metadata` are displayed in the side panel as nested key/value fields (objects expand into indented child labels)
 - `ObjectBindingType` is a large union covering vehicles, rooms, furniture, characters, weapons, environment, and more
 
 ## Supported Built-In Actions
@@ -1674,9 +1739,9 @@ Action handling is currently hardcoded in `ModelViewer`.
 - `toggle-visibility`
   Hides or shows the selected mesh by setting `binding.visible` and calling `onObjectBindingsChange`
 - `change-color`
-  Opens the color picker; the chosen hex is applied as a live preview while dragging and committed into `binding.style.material.baseColor` via `onObjectBindingsChange` when the picker closes
+  Opens the color picker inline beneath the action; the chosen hex is applied as a live preview while dragging and committed into `binding.style.material.baseColor` via `onObjectBindingsChange` when the picker closes
 - `change-material`
-  Opens the texture upload popup for JPG, PNG, and WebP files; if `onTextureUpload` is provided, the file is passed to it and the returned URL is stored in `binding.style.material.texture.path`; otherwise a session-scoped blob URL is used as the fallback
+  Opens the texture upload panel inline beneath the action for JPG, PNG, and WebP files; if `onTextureUpload` is provided, the file is passed to it and the returned URL is stored in `binding.style.material.texture.path`; otherwise a session-scoped blob URL is used as the fallback
 
 ## How Rendering Works
 
@@ -1709,10 +1774,10 @@ Pass `shadows={false}` to disable shadow rendering entirely, or pass a custom `l
 The current component includes its own UI shell:
 
 - a viewer layout that fills its parent container
-- a sliding left side panel about `280px` wide
+- a sliding left side panel about `280px` wide (collapses to half-width on narrow screens so the canvas keeps its other half)
 - a canvas area that fills the remaining width
-- a floating color picker popover
-- a floating texture upload popover
+- a color picker that expands inline beneath the **Change Color** action
+- a texture upload panel that expands inline beneath the **Change Material** action
 - a right scene objects panel with search and per-object visibility toggles
 
 Because of that, it works best when mounted in a container with an explicit height.

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