@heliguy-xyz/splat-viewer 1.0.0-rc.25 → 1.0.0-rc.26

package/README.md

@@ -24,6 +24,7 @@ external dependencies.
 - 🔄 **Transform System**: Programmatically position, rotate, and scale models
 - 🎥 **Fly Camera Mode**: First-person WASD + mouse-look navigation with configurable controls
 - 🎨 **Scene Configuration**: Adjust FOV and background color with smooth animations
+- 👁️ **Preview Mode**: Disable camera controls for product previews with programmatic rotation
 - 📡 **Comprehensive Events**: React to model lifecycle, transforms, camera changes, and more
 - 📘 **TypeScript Support**: Full type definitions for all APIs
 
@@ -161,6 +162,7 @@ declare namespace JSX {
         height?: string
         'auto-focus'?: boolean
         'enable-stats'?: boolean
+        'preview-mode'?: boolean
       },
       HTMLElement
     >
@@ -220,6 +222,7 @@ onMounted(() => {
 - `auto-focus` - Auto-focus on load (default: true)
 - `enable-stats` - Show performance stats (default: false)
 - `max-splats` - Maximum splat count (default: 2000000)
+- `preview-mode` - Disable camera controls for preview use (default: false)
 
 #### Camera Controls
 
@@ -235,6 +238,42 @@ onMounted(() => {
 - `navigation-cube-size` - Cube size in pixels (default: 120)
 - `navigation-cube-transition` - Camera transition duration in ms (default: 800)
 
+### Preview Mode
+
+Preview mode disables all camera controls (mouse/touch interactions) while maintaining programmatic rotation capabilities. This is ideal for:
+
+- Product configurators with UI-controlled rotation
+- Model previews with custom control interfaces
+- Embedded viewers where you want to control all interactions
+
+**Usage:**
+
+```html
+<splat-viewer src="model.splat" preview-mode></splat-viewer>
+```
+
+**Features in Preview Mode:**
+- ✅ Camera controls are completely disabled
+- ✅ Model is automatically centered and framed on load
+- ✅ Programmatic rotation via `setModelRotation()` API still works
+- ✅ All other APIs remain functional (visibility, transforms, etc.)
+
+**Example with Rotation Controls:**
+
+```javascript
+const viewer = document.getElementById('viewer');
+
+viewer.addEventListener('loaded', () => {
+  const models = viewer.getModels();
+  const modelId = models[0].id;
+
+  // Programmatically set rotation
+  viewer.setModelRotation(modelId, { x: 0, y: 45, z: 0 });
+});
+```
+
+See `examples/preview-mode.html` for a complete working example.
+
 ### Events
 
 #### Core Events