@liveroom-tech/react-immersive 1.0.0 → 1.0.2

package/README.md

@@ -1018,6 +1018,8 @@ Example:
 />
 ```
 
+Passing an explicit `camera` counts as choosing the initial view yourself, so the mount-time auto-fit (see [`onAutoFit`](#onautofit)) is skipped automatically and your `position`/`fov` stick. Provide `onAutoFit` as well only if you want to run your _own_ fit-to-scene logic instead.
+
 ### `backgroundColor`
 
 Optional background color for the viewer canvas.
@@ -1273,7 +1275,7 @@ true;
 
 ### `onAutoFit`
 
-Optional async callback fired once the model has loaded and the scene is ready. When provided, the viewer calls it so consumers can run their own fit-to-scene behavior (e.g. an animated fit); if omitted, the viewer falls back to its internal `fitScene`.
+Optional async callback fired once the model has loaded and the scene is ready. When provided, the viewer calls it so consumers can run their own fit-to-scene behavior (e.g. an animated fit); if omitted, the viewer falls back to its internal `fitScene` — unless an explicit [`camera`](#camera) prop was given, in which case that position is treated as the chosen initial view and `fitScene` is skipped.
 
 Current callback shape:
 

package/dist/index.d.mts

@@ -669,4 +669,22 @@ type ViewerActionsProps = {
 };
 declare function useViewerActions(objectBindings: Record<string, ObjectBinding>, options?: ViewerActionsOptions): ViewerActionsProps;
 
-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, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+type UseShareableViewerStateOptions = {
+    cameraState: ViewerCameraState | null;
+    setCameraState: (state: ViewerCameraState, enableTransition?: boolean) => Promise<boolean>;
+    objectBindings: Record<string, ObjectBinding>;
+    onObjectBindingsChange: (next: Record<string, ObjectBinding>) => void;
+    selectedObjectBinding: ObjectBinding | null;
+    setSelectedObjectBinding: (binding: ObjectBinding | null) => void;
+    paramKey?: string;
+    debounceMs?: number;
+    autoSync?: boolean;
+};
+type ShareableViewerStateProps = {
+    getShareUrl: () => string;
+    syncUrl: () => void;
+    restoreFromUrl: () => Promise<boolean>;
+};
+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 };

package/dist/index.d.ts

@@ -669,4 +669,22 @@ type ViewerActionsProps = {
 };
 declare function useViewerActions(objectBindings: Record<string, ObjectBinding>, options?: ViewerActionsOptions): ViewerActionsProps;
 
-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, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+type UseShareableViewerStateOptions = {
+    cameraState: ViewerCameraState | null;
+    setCameraState: (state: ViewerCameraState, enableTransition?: boolean) => Promise<boolean>;
+    objectBindings: Record<string, ObjectBinding>;
+    onObjectBindingsChange: (next: Record<string, ObjectBinding>) => void;
+    selectedObjectBinding: ObjectBinding | null;
+    setSelectedObjectBinding: (binding: ObjectBinding | null) => void;
+    paramKey?: string;
+    debounceMs?: number;
+    autoSync?: boolean;
+};
+type ShareableViewerStateProps = {
+    getShareUrl: () => string;
+    syncUrl: () => void;
+    restoreFromUrl: () => Promise<boolean>;
+};
+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 };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
   useObjectBinding: () => useObjectBinding,
   useObjectBindingIds: () => useObjectBindingIds,
   useObjectVisibility: () => useObjectVisibility,
+  useShareableViewerState: () => useShareableViewerState,
   useViewerActions: () => useViewerActions,
   useViewerAnimations: () => useViewerAnimations,
   useViewerCamera: () => useViewerCamera,
@@ -5025,10 +5026,12 @@ function ModelViewer({
   const sceneRef = (0, import_react21.useRef)(null);
   const fitAttemptedRef = (0, import_react21.useRef)(false);
   const fitInFlightRef = (0, import_react21.useRef)(false);
+  const cameraProvidedRef = (0, import_react21.useRef)(Boolean(camera));
+  cameraProvidedRef.current = Boolean(camera);
   const initialCameraStateRef = (0, import_react21.useRef)(null);
   const [isAutoFraming, setIsAutoFraming] = (0, import_react21.useState)(Boolean(modelUrl));
   const [cameraPositioned, setCameraPositioned] = (0, import_react21.useState)(
-    !modelUrl || Boolean(onAutoFit)
+    !modelUrl || Boolean(onAutoFit) || Boolean(camera)
   );
   const [downloadMenuOpen, setDownloadMenuOpen] = (0, import_react21.useState)(false);
   const [modelLoaded, setModelLoaded] = (0, import_react21.useState)(false);
@@ -5846,7 +5849,7 @@ function ModelViewer({
       return;
     }
     setIsAutoFraming(true);
-    setCameraPositioned(Boolean(onAutoFit));
+    setCameraPositioned(Boolean(onAutoFit) || cameraProvidedRef.current);
     let cancelled = false;
     let timer = null;
     const scheduleCheck = (delay) => {
@@ -5870,7 +5873,7 @@ function ModelViewer({
         return;
       }
       fitInFlightRef.current = true;
-      const fitPromise = onAutoFit ? onAutoFit() : fitScene(true);
+      const fitPromise = onAutoFit ? onAutoFit() : cameraProvidedRef.current ? Promise.resolve(true) : fitScene(true);
       fitPromise.then((didFit) => {
         fitAttemptedRef.current = didFit !== false;
         if (fitAttemptedRef.current) {
@@ -15893,6 +15896,150 @@ function useViewerActions(objectBindings, options = {}) {
     runAction
   };
 }
+
+// src/hooks/useShareableViewerState.ts
+var import_react46 = require("react");
+function serializeState(cameraState, objectBindings, selectedObjectBinding) {
+  const hidden = Object.values(objectBindings).filter((binding) => binding.visible === false).map((binding) => binding.id);
+  return {
+    camera: cameraState ?? void 0,
+    hidden,
+    selected: selectedObjectBinding?.id ?? null
+  };
+}
+function useShareableViewerState({
+  cameraState,
+  setCameraState,
+  objectBindings,
+  onObjectBindingsChange,
+  selectedObjectBinding,
+  setSelectedObjectBinding,
+  paramKey = "view",
+  debounceMs = 400,
+  autoSync = true
+}) {
+  const lastWrittenRawRef = (0, import_react46.useRef)(null);
+  const buildHash = (0, import_react46.useCallback)(() => {
+    const state = serializeState(
+      cameraState,
+      objectBindings,
+      selectedObjectBinding
+    );
+    return `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
+  }, [cameraState, objectBindings, selectedObjectBinding, paramKey]);
+  const getShareUrl = (0, import_react46.useCallback)(() => {
+    const url = new URL(window.location.href);
+    url.hash = buildHash();
+    return url.toString();
+  }, [buildHash]);
+  const syncUrl = (0, import_react46.useCallback)(() => {
+    const url = new URL(window.location.href);
+    url.hash = buildHash();
+    window.history.replaceState(null, "", url.toString());
+    lastWrittenRawRef.current = new URLSearchParams(url.hash.slice(1)).get(
+      paramKey
+    );
+  }, [buildHash, paramKey]);
+  const latestStateRef = (0, import_react46.useRef)({
+    cameraState,
+    objectBindings,
+    selectedObjectBinding
+  });
+  latestStateRef.current = {
+    cameraState,
+    objectBindings,
+    selectedObjectBinding
+  };
+  const [restoreAttempted, setRestoreAttempted] = (0, import_react46.useState)(false);
+  const lastSyncedHashRef = (0, import_react46.useRef)(null);
+  (0, import_react46.useEffect)(() => {
+    if (!autoSync || !restoreAttempted) return;
+    const tick = () => {
+      const current = latestStateRef.current;
+      const state = serializeState(
+        current.cameraState,
+        current.objectBindings,
+        current.selectedObjectBinding
+      );
+      const hash = `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
+      if (hash === lastSyncedHashRef.current) return;
+      lastSyncedHashRef.current = hash;
+      const url = new URL(window.location.href);
+      url.hash = hash;
+      window.history.replaceState(null, "", url.toString());
+      lastWrittenRawRef.current = new URLSearchParams(url.hash.slice(1)).get(
+        paramKey
+      );
+    };
+    const id = window.setInterval(tick, debounceMs);
+    return () => window.clearInterval(id);
+  }, [autoSync, restoreAttempted, debounceMs, paramKey]);
+  const lastRestoredRawRef = (0, import_react46.useRef)(null);
+  const restoringRawRef = (0, import_react46.useRef)(null);
+  const restoreFromUrl = (0, import_react46.useCallback)(async () => {
+    setRestoreAttempted(true);
+    const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : window.location.hash;
+    const raw = new URLSearchParams(rawHash).get(paramKey);
+    if (!raw) {
+      lastRestoredRawRef.current = null;
+      return false;
+    }
+    if (raw === lastWrittenRawRef.current || raw === lastRestoredRawRef.current || raw === restoringRawRef.current) {
+      return false;
+    }
+    let state;
+    try {
+      state = JSON.parse(raw);
+    } catch {
+      return false;
+    }
+    restoringRawRef.current = raw;
+    try {
+      if (state.camera) {
+        await setCameraState(state.camera, false);
+      }
+      if (state.hidden) {
+        const hiddenIds = new Set(state.hidden);
+        onObjectBindingsChange(
+          Object.fromEntries(
+            Object.entries(objectBindings).map(([bindingKey, binding]) => [
+              bindingKey,
+              { ...binding, visible: !hiddenIds.has(binding.id) }
+            ])
+          )
+        );
+      }
+      if (state.selected !== void 0) {
+        const bindingKey = state.selected ? resolveBindingKey(objectBindings, state.selected) : null;
+        setSelectedObjectBinding(
+          bindingKey ? objectBindings[bindingKey] : null
+        );
+      }
+      lastRestoredRawRef.current = raw;
+      return true;
+    } finally {
+      if (restoringRawRef.current === raw) {
+        restoringRawRef.current = null;
+      }
+    }
+  }, [
+    objectBindings,
+    onObjectBindingsChange,
+    paramKey,
+    setCameraState,
+    setSelectedObjectBinding
+  ]);
+  (0, import_react46.useEffect)(() => {
+    const handleHashChange = () => {
+      void restoreFromUrl();
+    };
+    window.addEventListener("hashchange", handleHashChange);
+    return () => {
+      window.removeEventListener("hashchange", handleHashChange);
+    };
+  }, [restoreFromUrl]);
+  return { getShareUrl, syncUrl, restoreFromUrl };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BindingBuilder,
@@ -15903,6 +16050,7 @@ function useViewerActions(objectBindings, options = {}) {
   useObjectBinding,
   useObjectBindingIds,
   useObjectVisibility,
+  useShareableViewerState,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,

package/dist/index.mjs

@@ -5083,10 +5083,12 @@ function ModelViewer({
   const sceneRef = useRef9(null);
   const fitAttemptedRef = useRef9(false);
   const fitInFlightRef = useRef9(false);
+  const cameraProvidedRef = useRef9(Boolean(camera));
+  cameraProvidedRef.current = Boolean(camera);
   const initialCameraStateRef = useRef9(null);
   const [isAutoFraming, setIsAutoFraming] = useState10(Boolean(modelUrl));
   const [cameraPositioned, setCameraPositioned] = useState10(
-    !modelUrl || Boolean(onAutoFit)
+    !modelUrl || Boolean(onAutoFit) || Boolean(camera)
   );
   const [downloadMenuOpen, setDownloadMenuOpen] = useState10(false);
   const [modelLoaded, setModelLoaded] = useState10(false);
@@ -5904,7 +5906,7 @@ function ModelViewer({
       return;
     }
     setIsAutoFraming(true);
-    setCameraPositioned(Boolean(onAutoFit));
+    setCameraPositioned(Boolean(onAutoFit) || cameraProvidedRef.current);
     let cancelled = false;
     let timer = null;
     const scheduleCheck = (delay) => {
@@ -5928,7 +5930,7 @@ function ModelViewer({
         return;
       }
       fitInFlightRef.current = true;
-      const fitPromise = onAutoFit ? onAutoFit() : fitScene(true);
+      const fitPromise = onAutoFit ? onAutoFit() : cameraProvidedRef.current ? Promise.resolve(true) : fitScene(true);
       fitPromise.then((didFit) => {
         fitAttemptedRef.current = didFit !== false;
         if (fitAttemptedRef.current) {
@@ -15989,6 +15991,150 @@ function useViewerActions(objectBindings, options = {}) {
     runAction
   };
 }
+
+// src/hooks/useShareableViewerState.ts
+import { useCallback as useCallback15, useEffect as useEffect20, useRef as useRef18, useState as useState29 } from "react";
+function serializeState(cameraState, objectBindings, selectedObjectBinding) {
+  const hidden = Object.values(objectBindings).filter((binding) => binding.visible === false).map((binding) => binding.id);
+  return {
+    camera: cameraState ?? void 0,
+    hidden,
+    selected: selectedObjectBinding?.id ?? null
+  };
+}
+function useShareableViewerState({
+  cameraState,
+  setCameraState,
+  objectBindings,
+  onObjectBindingsChange,
+  selectedObjectBinding,
+  setSelectedObjectBinding,
+  paramKey = "view",
+  debounceMs = 400,
+  autoSync = true
+}) {
+  const lastWrittenRawRef = useRef18(null);
+  const buildHash = useCallback15(() => {
+    const state = serializeState(
+      cameraState,
+      objectBindings,
+      selectedObjectBinding
+    );
+    return `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
+  }, [cameraState, objectBindings, selectedObjectBinding, paramKey]);
+  const getShareUrl = useCallback15(() => {
+    const url = new URL(window.location.href);
+    url.hash = buildHash();
+    return url.toString();
+  }, [buildHash]);
+  const syncUrl = useCallback15(() => {
+    const url = new URL(window.location.href);
+    url.hash = buildHash();
+    window.history.replaceState(null, "", url.toString());
+    lastWrittenRawRef.current = new URLSearchParams(url.hash.slice(1)).get(
+      paramKey
+    );
+  }, [buildHash, paramKey]);
+  const latestStateRef = useRef18({
+    cameraState,
+    objectBindings,
+    selectedObjectBinding
+  });
+  latestStateRef.current = {
+    cameraState,
+    objectBindings,
+    selectedObjectBinding
+  };
+  const [restoreAttempted, setRestoreAttempted] = useState29(false);
+  const lastSyncedHashRef = useRef18(null);
+  useEffect20(() => {
+    if (!autoSync || !restoreAttempted) return;
+    const tick = () => {
+      const current = latestStateRef.current;
+      const state = serializeState(
+        current.cameraState,
+        current.objectBindings,
+        current.selectedObjectBinding
+      );
+      const hash = `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
+      if (hash === lastSyncedHashRef.current) return;
+      lastSyncedHashRef.current = hash;
+      const url = new URL(window.location.href);
+      url.hash = hash;
+      window.history.replaceState(null, "", url.toString());
+      lastWrittenRawRef.current = new URLSearchParams(url.hash.slice(1)).get(
+        paramKey
+      );
+    };
+    const id = window.setInterval(tick, debounceMs);
+    return () => window.clearInterval(id);
+  }, [autoSync, restoreAttempted, debounceMs, paramKey]);
+  const lastRestoredRawRef = useRef18(null);
+  const restoringRawRef = useRef18(null);
+  const restoreFromUrl = useCallback15(async () => {
+    setRestoreAttempted(true);
+    const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : window.location.hash;
+    const raw = new URLSearchParams(rawHash).get(paramKey);
+    if (!raw) {
+      lastRestoredRawRef.current = null;
+      return false;
+    }
+    if (raw === lastWrittenRawRef.current || raw === lastRestoredRawRef.current || raw === restoringRawRef.current) {
+      return false;
+    }
+    let state;
+    try {
+      state = JSON.parse(raw);
+    } catch {
+      return false;
+    }
+    restoringRawRef.current = raw;
+    try {
+      if (state.camera) {
+        await setCameraState(state.camera, false);
+      }
+      if (state.hidden) {
+        const hiddenIds = new Set(state.hidden);
+        onObjectBindingsChange(
+          Object.fromEntries(
+            Object.entries(objectBindings).map(([bindingKey, binding]) => [
+              bindingKey,
+              { ...binding, visible: !hiddenIds.has(binding.id) }
+            ])
+          )
+        );
+      }
+      if (state.selected !== void 0) {
+        const bindingKey = state.selected ? resolveBindingKey(objectBindings, state.selected) : null;
+        setSelectedObjectBinding(
+          bindingKey ? objectBindings[bindingKey] : null
+        );
+      }
+      lastRestoredRawRef.current = raw;
+      return true;
+    } finally {
+      if (restoringRawRef.current === raw) {
+        restoringRawRef.current = null;
+      }
+    }
+  }, [
+    objectBindings,
+    onObjectBindingsChange,
+    paramKey,
+    setCameraState,
+    setSelectedObjectBinding
+  ]);
+  useEffect20(() => {
+    const handleHashChange = () => {
+      void restoreFromUrl();
+    };
+    window.addEventListener("hashchange", handleHashChange);
+    return () => {
+      window.removeEventListener("hashchange", handleHashChange);
+    };
+  }, [restoreFromUrl]);
+  return { getShareUrl, syncUrl, restoreFromUrl };
+}
 export {
   BindingBuilder,
   MATERIAL_BLENDING_MODES,
@@ -15998,6 +16144,7 @@ export {
   useObjectBinding,
   useObjectBindingIds,
   useObjectVisibility,
+  useShareableViewerState,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveroom-tech/react-immersive",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -75,7 +75,7 @@
   "homepage": "https://react-immersive.liveroom.dev",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.liveroom.xyz/team_liveroom/react-immersive-docs.git"
+    "url": "https://github.com/liveroom-technologies/react-immersive-docs.git"
   },
   "bugs": {
     "url": "https://github.com/liveroom-technologies/react-immersive-docs/issues"