@liveroom-tech/react-immersive 5.0.2 → 5.1.0

package/dist/{ModelViewer-DOexHkJC.d.ts → ModelViewer-Bj-KjiDL.d.mts}

@@ -1,9 +1,52 @@
 import { ReactNode } from 'react';
-import { g as ObjectBinding, a1 as ViewerCameraState, y as SceneAnnotationMarker, f as ObjectActionEvent, a2 as ViewerObjectInfo, w as ObjectPointerEvent, a0 as ViewerCameraConfig, J as SceneConfig } from './objectCatalog-5W8n5xNQ.js';
-import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-CEmmvVCH.js';
+import { r as ObjectBindingDecal, Q as ObjectSurfacePoint, o as ObjectBinding, al as ViewerCameraState, U as SceneAnnotationMarker, n as ObjectActionEvent, an as ViewerObjectInfo, P as ObjectPointerEvent, e as AnimationControls, ak as ViewerCameraConfig, Z as SceneConfig, am as ViewerIsolation } from './objectCatalog-BIeXURoq.mjs';
+import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-DnkmTGMd.mjs';
 import { CameraControls } from '@react-three/drei';
 import { Object3D } from 'three';
 
+/** Engagement from deliberate viewer interactions, with model/session context. */
+type ViewerEngagementEvent = {
+    /** Ephemeral identifier for this viewer/model session; no persistent storage. */
+    sessionId: string;
+    /** ISO timestamp of the event. */
+    timestamp: string;
+    /** Milliseconds since tracking started for this model. */
+    elapsedMs: number;
+    modelUrl: string;
+    tilesetUrl: string | null;
+} & ({
+    type: "part-viewed";
+    objectId: string;
+    objectKey: string;
+    label?: string;
+    source: "canvas" | "panel";
+} | {
+    type: "variant-chosen";
+    variant: string | null;
+    previousVariant: string | null;
+} | {
+    type: "ar-started";
+} | {
+    type: "ar-ended";
+    durationMs: number;
+    reason: "session-ended" | "interrupted";
+} | {
+    type: "ar-launch-requested";
+    channel: "quick-look" | "mobile-handoff";
+} | {
+    type: "tour-started";
+    annotationCount: number;
+} | {
+    type: "tour-completed";
+    annotationCount: number;
+    durationMs: number;
+} | {
+    type: "tour-stopped";
+    annotationCount: number;
+    durationMs: number;
+    reason: "stopped" | "restarted" | "annotations-changed" | "interrupted";
+});
+
 type CameraLimits = {
     /** Closest the camera can get to its target, in scene units. Default 0. */
     minDistance?: number;
@@ -49,6 +92,8 @@ type ModelViewerUiOptions = {
     download?: boolean | string;
     /** The reset-view button. Default `true`. */
     reset?: boolean;
+    /** The viewer fullscreen toggle in the action bar. Default `false`. */
+    fullscreen?: boolean;
     /** The loading overlay and load-error message. Default `true`. */
     loadingOverlay?: boolean;
     /** The axis gizmo in the top-right corner. Default `false`. */
@@ -64,6 +109,8 @@ type ModelViewerUiOptions = {
     annotationOnHover?: boolean;
     /** Highlight objects under the pointer. Default `true`. */
     highlightOnHover?: boolean;
+    /** Buttons for the model's glTF material variants, when it has more than one. Default `true`. */
+    materialVariants?: boolean;
 };
 /**
  * Takes over parts of texture positioning (`texturePositioning`). Fields left
@@ -92,6 +139,10 @@ type ModelViewerToolsOptions = {
     uvChecker?: boolean;
     /** The exploded-view slider. Default `false`. */
     explode?: boolean;
+    /** The section-cut tool, to cut the model open along an axis. Default `false`. */
+    section?: boolean;
+    /** Isolate buttons in the scene objects panel, and a "Show all" pill. Default `false`. */
+    isolate?: boolean;
     /** Texture offset, rotation and Move/Zoom for textured objects. Default `false`. */
     texturePositioning?: boolean | TexturePositioningControls;
 };
@@ -168,6 +219,13 @@ type GroupedModelViewerProps = {
 /** What each preset sets. Props that aren't listed keep their defaults. */
 declare const MODEL_VIEWER_PRESETS: Readonly<Record<ModelViewerPreset, Readonly<Partial<ModelViewerProps>>>>;
 
+type DecalMoveTarget = {
+    objectId: string;
+    decal: ObjectBindingDecal;
+    onCommit: (surface: ObjectSurfacePoint) => void;
+    onCancel: () => void;
+};
+
 type CameraControllerType = "orbit" | "pointerLock";
 
 type CinematicWaypoint = {
@@ -195,6 +253,21 @@ type CaptureImageOptions = {
     transparent?: boolean;
 };
 
+type CaptureVideoOptions = {
+    /** Defaults to cinematic when a path is enabled, otherwise turntable. */
+    mode?: "cinematic" | "turntable";
+    /** Auto prefers WebM, then MP4. Explicit formats reject if unsupported. */
+    format?: "auto" | "webm" | "mp4";
+    /** Seconds per pass, in (0, 300]. Defaults to path timing or a 24s orbit. */
+    duration?: number;
+    /** Capture frame rate, from 1 to 60. Default 30. */
+    fps?: number;
+    /** Encoder target bitrate in bits per second. Default 8,000,000. */
+    videoBitsPerSecond?: number;
+    /** Aborting discards the recording and restores the viewer. */
+    signal?: AbortSignal;
+};
+
 type ViewerCameraPreset = {
     position: [number, number, number];
     target: [number, number, number];
@@ -221,6 +294,8 @@ type ViewerReadyState = {
     objectBindings: Record<string, ObjectBinding>;
     homeCameraState: HomeCameraState | null;
     captureImage: (options?: CaptureImageOptions) => Promise<string>;
+    /** Records one cinematic pass or turntable revolution as a video Blob. */
+    captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
     invalidate: () => void;
     /**
      * The live three.js scene, camera-controls instance, and model nodes, for
@@ -257,45 +332,6 @@ type ViewerCameraProps = {
 };
 declare function useViewerCamera(options?: UseViewerCameraOptions): ViewerCameraProps;
 
-type AnimationClipInfo = {
-    sourceName: string;
-    duration: number;
-};
-type AnimationPlaybackState = {
-    currentClip: string | null;
-    isPlaying: boolean;
-    speed: number;
-    time: number;
-    duration: number;
-};
-type AnimationControls = {
-    clips: string[];
-    clipDetails?: AnimationClipInfo[];
-    play: (clipName: string) => void;
-    pause: () => void;
-    stop: () => void;
-    setSpeed: (speed: number) => void;
-    seek?: (time: number) => void;
-    getState?: () => AnimationPlaybackState;
-    subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
-};
-type ViewerAnimationsProps = {
-    clips: string[];
-    clipDetails: AnimationClipInfo[];
-    currentClip: string | null;
-    isPlaying: boolean;
-    speed: number;
-    time: number;
-    duration: number;
-    play: (clipName: string) => void;
-    pause: () => void;
-    stop: () => void;
-    setSpeed: (speed: number) => void;
-    seek: (time: number) => void;
-    handleAnimationsReady: (controls: AnimationControls) => void;
-};
-declare function useViewerAnimations(): ViewerAnimationsProps;
-
 type ObjectTransformSpace = "local" | "world";
 
 type AnnotationMarker = SceneAnnotationMarker & {
@@ -354,6 +390,8 @@ type ModelViewerProps = GroupedModelViewerProps & {
      * open your own menu at `clientX`/`clientY`. A right-drag still pans.
      */
     onObjectContextMenu?: (event: ObjectPointerEvent) => void;
+    /** Editor preview: grab this decal and drag it over its object's surface. */
+    decalMove?: DecalMoveTarget | null;
     /** The model finished loading: its bounds and mesh count. */
     onModelLoaded?: (model: ViewerModelInfo) => void;
     onLoadError?: (error: unknown) => void;
@@ -362,6 +400,10 @@ type ModelViewerProps = GroupedModelViewerProps & {
     cameraControllerType?: CameraControllerType;
     onAction?: (event: ObjectActionEvent) => void;
     onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
+    /** Opt-in interaction analytics; no telemetry is sent by the viewer. */
+    onEngagement?: (event: ViewerEngagementEvent) => void | Promise<void>;
+    /** Log engagement events in the developer console. Default `false`. */
+    debugEngagement?: boolean;
     /** The camera moved. Fires often while the user orbits, pans or zooms. */
     onCameraChange?: (state: ViewerCameraState) => void;
     onViewerReady?: (viewer: ViewerReadyState) => void;
@@ -381,6 +423,8 @@ type ModelViewerProps = GroupedModelViewerProps & {
     showDownloadButton?: boolean;
     downloadFilename?: string;
     showResetButton?: boolean;
+    /** Fullscreen action button; grouped form: `ui.fullscreen`. Default `false`. */
+    showFullscreenButton?: boolean;
     showLoadingOverlay?: boolean;
     showMouseController?: boolean;
     mouseControllerPosition?: MouseControllerPosition;
@@ -409,6 +453,11 @@ type ModelViewerProps = GroupedModelViewerProps & {
     showMeasureTools?: boolean;
     showUvCheckerButton?: boolean;
     showExplodeControls?: boolean;
+    isolation?: ViewerIsolation | null;
+    onIsolationChange?: (isolation: ViewerIsolation | null) => void;
+    showIsolateControls?: boolean;
+    showSectionTools?: boolean;
+    showMaterialVariants?: boolean;
     cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
     enableXR?: boolean;
@@ -445,4 +494,4 @@ type ModelViewerProps = GroupedModelViewerProps & {
     texturePositioning?: boolean | TexturePositioningControls;
 };
 
-export { type AnimationClipInfo as A, type CameraControllerType as C, type GroupedModelViewerProps as G, type HomeCameraState as H, MODEL_VIEWER_PRESETS as M, type ObjectTransformSpace as O, type PerformanceProfile as P, type TexturePositioningControls as T, type UseViewerCameraOptions as U, type ViewerAnimationsProps as V, type XRScaleMode as X, type AnimationControls as a, type AnimationPlaybackState as b, type AnnotationMarker as c, type CameraLimits as d, type CaptureImageOptions as e, type CinematicConfig as f, type CinematicWaypoint as g, type CustomObjectBindingDataPanelProps as h, type CustomSceneObjectsPanelProps as i, type ModelViewerControlsOptions as j, type ModelViewerDecoderOptions as k, type ModelViewerPerfOptions as l, type ModelViewerPreset as m, type ModelViewerProps as n, type ModelViewerTilesOptions as o, type ModelViewerToolsOptions as p, type ModelViewerUiOptions as q, type ModelViewerXrOptions as r, type MouseControllerPosition as s, type ViewerCameraPreset as t, type ViewerCameraProps as u, type ViewerReadyState as v, useViewerAnimations as w, useViewerCamera as x };
+export { type AnnotationMarker as A, type CameraControllerType as C, type DecalMoveTarget as D, type GroupedModelViewerProps as G, type HomeCameraState as H, MODEL_VIEWER_PRESETS as M, type ObjectTransformSpace as O, type PerformanceProfile as P, type TexturePositioningControls as T, type UseViewerCameraOptions as U, type ViewerCameraPreset as V, type XRScaleMode as X, type CameraLimits as a, type CaptureImageOptions as b, type CaptureVideoOptions as c, type CinematicConfig as d, type CinematicWaypoint as e, type CustomObjectBindingDataPanelProps as f, type CustomSceneObjectsPanelProps as g, type ModelViewerControlsOptions as h, type ModelViewerDecoderOptions as i, type ModelViewerPerfOptions as j, type ModelViewerPreset as k, type ModelViewerProps as l, type ModelViewerTilesOptions as m, type ModelViewerToolsOptions as n, type ModelViewerUiOptions as o, type ModelViewerXrOptions as p, type MouseControllerPosition as q, type ViewerCameraProps as r, type ViewerEngagementEvent as s, type ViewerReadyState as t, useViewerCamera as u };

package/dist/{ModelViewer-CbbJT85n.d.mts → ModelViewer-BkQ73y6N.d.ts}

@@ -1,9 +1,52 @@
 import { ReactNode } from 'react';
-import { g as ObjectBinding, a1 as ViewerCameraState, y as SceneAnnotationMarker, f as ObjectActionEvent, a2 as ViewerObjectInfo, w as ObjectPointerEvent, a0 as ViewerCameraConfig, J as SceneConfig } from './objectCatalog-5W8n5xNQ.mjs';
-import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-CEmmvVCH.mjs';
+import { r as ObjectBindingDecal, Q as ObjectSurfacePoint, o as ObjectBinding, al as ViewerCameraState, U as SceneAnnotationMarker, n as ObjectActionEvent, an as ViewerObjectInfo, P as ObjectPointerEvent, e as AnimationControls, ak as ViewerCameraConfig, Z as SceneConfig, am as ViewerIsolation } from './objectCatalog-BIeXURoq.js';
+import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-DnkmTGMd.js';
 import { CameraControls } from '@react-three/drei';
 import { Object3D } from 'three';
 
+/** Engagement from deliberate viewer interactions, with model/session context. */
+type ViewerEngagementEvent = {
+    /** Ephemeral identifier for this viewer/model session; no persistent storage. */
+    sessionId: string;
+    /** ISO timestamp of the event. */
+    timestamp: string;
+    /** Milliseconds since tracking started for this model. */
+    elapsedMs: number;
+    modelUrl: string;
+    tilesetUrl: string | null;
+} & ({
+    type: "part-viewed";
+    objectId: string;
+    objectKey: string;
+    label?: string;
+    source: "canvas" | "panel";
+} | {
+    type: "variant-chosen";
+    variant: string | null;
+    previousVariant: string | null;
+} | {
+    type: "ar-started";
+} | {
+    type: "ar-ended";
+    durationMs: number;
+    reason: "session-ended" | "interrupted";
+} | {
+    type: "ar-launch-requested";
+    channel: "quick-look" | "mobile-handoff";
+} | {
+    type: "tour-started";
+    annotationCount: number;
+} | {
+    type: "tour-completed";
+    annotationCount: number;
+    durationMs: number;
+} | {
+    type: "tour-stopped";
+    annotationCount: number;
+    durationMs: number;
+    reason: "stopped" | "restarted" | "annotations-changed" | "interrupted";
+});
+
 type CameraLimits = {
     /** Closest the camera can get to its target, in scene units. Default 0. */
     minDistance?: number;
@@ -49,6 +92,8 @@ type ModelViewerUiOptions = {
     download?: boolean | string;
     /** The reset-view button. Default `true`. */
     reset?: boolean;
+    /** The viewer fullscreen toggle in the action bar. Default `false`. */
+    fullscreen?: boolean;
     /** The loading overlay and load-error message. Default `true`. */
     loadingOverlay?: boolean;
     /** The axis gizmo in the top-right corner. Default `false`. */
@@ -64,6 +109,8 @@ type ModelViewerUiOptions = {
     annotationOnHover?: boolean;
     /** Highlight objects under the pointer. Default `true`. */
     highlightOnHover?: boolean;
+    /** Buttons for the model's glTF material variants, when it has more than one. Default `true`. */
+    materialVariants?: boolean;
 };
 /**
  * Takes over parts of texture positioning (`texturePositioning`). Fields left
@@ -92,6 +139,10 @@ type ModelViewerToolsOptions = {
     uvChecker?: boolean;
     /** The exploded-view slider. Default `false`. */
     explode?: boolean;
+    /** The section-cut tool, to cut the model open along an axis. Default `false`. */
+    section?: boolean;
+    /** Isolate buttons in the scene objects panel, and a "Show all" pill. Default `false`. */
+    isolate?: boolean;
     /** Texture offset, rotation and Move/Zoom for textured objects. Default `false`. */
     texturePositioning?: boolean | TexturePositioningControls;
 };
@@ -168,6 +219,13 @@ type GroupedModelViewerProps = {
 /** What each preset sets. Props that aren't listed keep their defaults. */
 declare const MODEL_VIEWER_PRESETS: Readonly<Record<ModelViewerPreset, Readonly<Partial<ModelViewerProps>>>>;
 
+type DecalMoveTarget = {
+    objectId: string;
+    decal: ObjectBindingDecal;
+    onCommit: (surface: ObjectSurfacePoint) => void;
+    onCancel: () => void;
+};
+
 type CameraControllerType = "orbit" | "pointerLock";
 
 type CinematicWaypoint = {
@@ -195,6 +253,21 @@ type CaptureImageOptions = {
     transparent?: boolean;
 };
 
+type CaptureVideoOptions = {
+    /** Defaults to cinematic when a path is enabled, otherwise turntable. */
+    mode?: "cinematic" | "turntable";
+    /** Auto prefers WebM, then MP4. Explicit formats reject if unsupported. */
+    format?: "auto" | "webm" | "mp4";
+    /** Seconds per pass, in (0, 300]. Defaults to path timing or a 24s orbit. */
+    duration?: number;
+    /** Capture frame rate, from 1 to 60. Default 30. */
+    fps?: number;
+    /** Encoder target bitrate in bits per second. Default 8,000,000. */
+    videoBitsPerSecond?: number;
+    /** Aborting discards the recording and restores the viewer. */
+    signal?: AbortSignal;
+};
+
 type ViewerCameraPreset = {
     position: [number, number, number];
     target: [number, number, number];
@@ -221,6 +294,8 @@ type ViewerReadyState = {
     objectBindings: Record<string, ObjectBinding>;
     homeCameraState: HomeCameraState | null;
     captureImage: (options?: CaptureImageOptions) => Promise<string>;
+    /** Records one cinematic pass or turntable revolution as a video Blob. */
+    captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
     invalidate: () => void;
     /**
      * The live three.js scene, camera-controls instance, and model nodes, for
@@ -257,45 +332,6 @@ type ViewerCameraProps = {
 };
 declare function useViewerCamera(options?: UseViewerCameraOptions): ViewerCameraProps;
 
-type AnimationClipInfo = {
-    sourceName: string;
-    duration: number;
-};
-type AnimationPlaybackState = {
-    currentClip: string | null;
-    isPlaying: boolean;
-    speed: number;
-    time: number;
-    duration: number;
-};
-type AnimationControls = {
-    clips: string[];
-    clipDetails?: AnimationClipInfo[];
-    play: (clipName: string) => void;
-    pause: () => void;
-    stop: () => void;
-    setSpeed: (speed: number) => void;
-    seek?: (time: number) => void;
-    getState?: () => AnimationPlaybackState;
-    subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
-};
-type ViewerAnimationsProps = {
-    clips: string[];
-    clipDetails: AnimationClipInfo[];
-    currentClip: string | null;
-    isPlaying: boolean;
-    speed: number;
-    time: number;
-    duration: number;
-    play: (clipName: string) => void;
-    pause: () => void;
-    stop: () => void;
-    setSpeed: (speed: number) => void;
-    seek: (time: number) => void;
-    handleAnimationsReady: (controls: AnimationControls) => void;
-};
-declare function useViewerAnimations(): ViewerAnimationsProps;
-
 type ObjectTransformSpace = "local" | "world";
 
 type AnnotationMarker = SceneAnnotationMarker & {
@@ -354,6 +390,8 @@ type ModelViewerProps = GroupedModelViewerProps & {
      * open your own menu at `clientX`/`clientY`. A right-drag still pans.
      */
     onObjectContextMenu?: (event: ObjectPointerEvent) => void;
+    /** Editor preview: grab this decal and drag it over its object's surface. */
+    decalMove?: DecalMoveTarget | null;
     /** The model finished loading: its bounds and mesh count. */
     onModelLoaded?: (model: ViewerModelInfo) => void;
     onLoadError?: (error: unknown) => void;
@@ -362,6 +400,10 @@ type ModelViewerProps = GroupedModelViewerProps & {
     cameraControllerType?: CameraControllerType;
     onAction?: (event: ObjectActionEvent) => void;
     onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
+    /** Opt-in interaction analytics; no telemetry is sent by the viewer. */
+    onEngagement?: (event: ViewerEngagementEvent) => void | Promise<void>;
+    /** Log engagement events in the developer console. Default `false`. */
+    debugEngagement?: boolean;
     /** The camera moved. Fires often while the user orbits, pans or zooms. */
     onCameraChange?: (state: ViewerCameraState) => void;
     onViewerReady?: (viewer: ViewerReadyState) => void;
@@ -381,6 +423,8 @@ type ModelViewerProps = GroupedModelViewerProps & {
     showDownloadButton?: boolean;
     downloadFilename?: string;
     showResetButton?: boolean;
+    /** Fullscreen action button; grouped form: `ui.fullscreen`. Default `false`. */
+    showFullscreenButton?: boolean;
     showLoadingOverlay?: boolean;
     showMouseController?: boolean;
     mouseControllerPosition?: MouseControllerPosition;
@@ -409,6 +453,11 @@ type ModelViewerProps = GroupedModelViewerProps & {
     showMeasureTools?: boolean;
     showUvCheckerButton?: boolean;
     showExplodeControls?: boolean;
+    isolation?: ViewerIsolation | null;
+    onIsolationChange?: (isolation: ViewerIsolation | null) => void;
+    showIsolateControls?: boolean;
+    showSectionTools?: boolean;
+    showMaterialVariants?: boolean;
     cinematic?: boolean | CinematicConfig;
     measurementUnit?: string;
     enableXR?: boolean;
@@ -445,4 +494,4 @@ type ModelViewerProps = GroupedModelViewerProps & {
     texturePositioning?: boolean | TexturePositioningControls;
 };
 
-export { type AnimationClipInfo as A, type CameraControllerType as C, type GroupedModelViewerProps as G, type HomeCameraState as H, MODEL_VIEWER_PRESETS as M, type ObjectTransformSpace as O, type PerformanceProfile as P, type TexturePositioningControls as T, type UseViewerCameraOptions as U, type ViewerAnimationsProps as V, type XRScaleMode as X, type AnimationControls as a, type AnimationPlaybackState as b, type AnnotationMarker as c, type CameraLimits as d, type CaptureImageOptions as e, type CinematicConfig as f, type CinematicWaypoint as g, type CustomObjectBindingDataPanelProps as h, type CustomSceneObjectsPanelProps as i, type ModelViewerControlsOptions as j, type ModelViewerDecoderOptions as k, type ModelViewerPerfOptions as l, type ModelViewerPreset as m, type ModelViewerProps as n, type ModelViewerTilesOptions as o, type ModelViewerToolsOptions as p, type ModelViewerUiOptions as q, type ModelViewerXrOptions as r, type MouseControllerPosition as s, type ViewerCameraPreset as t, type ViewerCameraProps as u, type ViewerReadyState as v, useViewerAnimations as w, useViewerCamera as x };
+export { type AnnotationMarker as A, type CameraControllerType as C, type DecalMoveTarget as D, type GroupedModelViewerProps as G, type HomeCameraState as H, MODEL_VIEWER_PRESETS as M, type ObjectTransformSpace as O, type PerformanceProfile as P, type TexturePositioningControls as T, type UseViewerCameraOptions as U, type ViewerCameraPreset as V, type XRScaleMode as X, type CameraLimits as a, type CaptureImageOptions as b, type CaptureVideoOptions as c, type CinematicConfig as d, type CinematicWaypoint as e, type CustomObjectBindingDataPanelProps as f, type CustomSceneObjectsPanelProps as g, type ModelViewerControlsOptions as h, type ModelViewerDecoderOptions as i, type ModelViewerPerfOptions as j, type ModelViewerPreset as k, type ModelViewerProps as l, type ModelViewerTilesOptions as m, type ModelViewerToolsOptions as n, type ModelViewerUiOptions as o, type ModelViewerXrOptions as p, type MouseControllerPosition as q, type ViewerCameraProps as r, type ViewerEngagementEvent as s, type ViewerReadyState as t, useViewerCamera as u };