storysplat-viewer 2.9.13 → 2.9.15

package/README.md

@@ -1,6 +1,6 @@
 # StorySplat Viewer
 
-A powerful npm package for embedding and interacting with 3D Gaussian Splatting scenes in web applications. StorySplat Viewer provides a complete solution for displaying, navigating, and interacting with .splat, .ply, and .sog files with built-in support for waypoints, hotspots, and multiple camera modes.
+A powerful npm package for embedding and interacting with 3D Gaussian Splatting scenes in web applications. StorySplat Viewer provides a complete solution for displaying, navigating, and interacting with .splat, .ply, and .sog files with built-in support for waypoints, hotspots, portals, audio, particles, LOD streaming, 4DGS frame sequences, and multiple camera modes.
 
 ## Table of Contents
 
@@ -13,13 +13,25 @@ A powerful npm package for embedding and interacting with 3D Gaussian Splatting
 - [API Reference](#api-reference)
 - [Controlling the Viewer](#controlling-the-viewer)
 - [Configuration Options](#configuration-options)
+- [Scene Data Format](#scene-data-format)
+- [LOD Streaming](#lod-streaming)
+- [4DGS Frame Sequences](#4dgs-frame-sequences)
 - [Viewer Theme Customization](#viewer-theme-customization)
 - [Splat Relighting](#splat-relighting)
 - [Internationalization (i18n)](#internationalization-i18n)
 - [Events](#events)
+- [Portals (Scene-to-Scene Navigation)](#portals-scene-to-scene-navigation)
+- [Audio Emitters](#audio-emitters)
+- [HTML Meshes](#html-meshes)
+- [Voxel Collision](#voxel-collision)
 - [React Integration](#react-integration)
+- [Native App Integration](#native-app-integration)
 - [Analytics & Tracking](#analytics--tracking)
+- [Standalone HTML Generation](#standalone-html-generation)
+- [Error Handling](#error-handling)
+- [Exports](#exports)
 - [Troubleshooting](#troubleshooting)
+- [Support](#support)
 
 ## Installation
 
@@ -114,31 +126,6 @@ const viewer = createViewer(
 
 > **Note:** When using `createViewer` with self-hosted scenes, views and bandwidth are not tracked. Use `createViewerFromSceneId` for StorySplat-hosted scenes to get analytics.
 
-### Scene Data Format
-
-When using `createViewer()` with self-hosted JSON, the scene data should match the format exported by the StorySplat editor. Key fields:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `loadedModelUrl` | `string` | URL to the .splat, .ply, or .ksplat file |
-| `waypoints` | `array` | Camera path waypoints |
-| `hotspots` | `array` | Interactive hotspot markers |
-| `portals` | `array` | Scene-to-scene navigation portals |
-| `activeSkyboxUrl` | `string` | URL to the skybox HDR/image file |
-| `skyboxRotation` | `number` | Skybox rotation offset |
-| `lights` | `array` | Scene lighting configuration |
-| `particleSystems` | `array` | Particle effect systems |
-| `customMeshes` | `array` | Imported 3D models |
-| `uiColor` | `string` | Accent color for UI controls |
-| `uiOptions` | `object` | UI visibility toggles and button labels |
-| `uiOptions.viewerTheme` | `ViewerTheme` | Custom viewer theme overrides (colors, fonts, radii) |
-| `defaultCameraMode` | `string` | Initial camera mode: `'tour'`, `'explore'`, or `'walk'` |
-| `revealStyle` | `string` | Reveal animation style: `'bloom'` or `'radial'` |
-| `doubleTapMoveSpeed` | `number` | Auto-forward speed on double-tap in explore mode (default: 1.0) |
-| `splatRelighting` | `object` | Splat relighting config (enabled, ambientColor, ambientIntensity, allowViewerToggle, viewerDefaultOn) |
-
-The viewer's transform layer normalizes all field variations automatically, so JSON exported from any version of the editor will work.
-
 ## API Reference
 
 ### createViewerFromSceneId
@@ -230,7 +217,7 @@ interface ViewerInstance {
   getWaypointCount: () => number;
 
   // Camera
-  setCameraMode: (mode: 'tour' | 'explore') => void;
+  setCameraMode: (mode: 'tour' | 'explore' | 'walk') => void;
   getCameraMode: () => string;
   setExploreMode: (mode: 'orbit' | 'fly') => void;
   setPosition: (x: number, y: number, z: number) => void;
@@ -253,6 +240,16 @@ interface ViewerInstance {
   isShowingOriginalSplat: () => boolean;
   getAdditionalSplats: () => Array<{ url: string; name?: string; waypointIndex: number; percentage: number }>;
 
+  // 4DGS Frame Sequence (only when frameSequence is configured)
+  isFrameSequencePlaying: () => boolean;
+  setFrame: (index: number) => void;
+  getCurrentFrame: () => number;
+  getTotalFrames: () => number;
+  setFps: (fps: number) => void;
+  getFps: () => number;
+  getFrameProgress: () => number;
+  setFrameProgress: (progress: number) => void;
+
   // Audio
   muteAll: () => void;
   unmuteAll: () => void;
@@ -279,6 +276,112 @@ interface ViewerInstance {
 }
 ```
 
+## Controlling the Viewer
+
+The viewer instance provides methods to control playback, navigation, and camera programmatically. This is useful for building custom UI controls outside the viewer.
+
+### External Control Example
+
+```html
+<div id="viewer" style="width: 100%; height: 500px;"></div>
+
+<div id="controls">
+  <button id="prev">Previous</button>
+  <button id="play">Play</button>
+  <button id="pause">Pause</button>
+  <button id="next">Next</button>
+  <span id="waypoint-info"></span>
+</div>
+
+<script type="module">
+import { createViewerFromSceneId } from 'storysplat-viewer';
+
+const viewer = await createViewerFromSceneId(
+  document.getElementById('viewer'),
+  'YOUR_SCENE_ID'
+);
+
+// Navigation
+document.getElementById('prev').onclick = () => viewer.prevWaypoint();
+document.getElementById('next').onclick = () => viewer.nextWaypoint();
+
+// Playback
+document.getElementById('play').onclick = () => viewer.play();
+document.getElementById('pause').onclick = () => viewer.pause();
+
+// Update waypoint display
+viewer.on('waypointChange', ({ index }) => {
+  const total = viewer.getWaypointCount();
+  document.getElementById('waypoint-info').textContent =
+    `Waypoint ${index + 1} of ${total}`;
+});
+
+// Jump to specific waypoint
+function goToWaypoint(index) {
+  viewer.goToWaypoint(index);
+}
+</script>
+```
+
+### Available Control Methods
+
+| Method | Description |
+|--------|-------------|
+| **Navigation** | |
+| `viewer.goToWaypoint(index)` | Jump to specific waypoint (0-indexed) |
+| `viewer.nextWaypoint()` | Go to next waypoint |
+| `viewer.prevWaypoint()` | Go to previous waypoint |
+| `viewer.getCurrentWaypointIndex()` | Get current waypoint index |
+| `viewer.getWaypointCount()` | Get total number of waypoints |
+| **Camera** | |
+| `viewer.setCameraMode(mode)` | Switch mode: `'tour'`, `'explore'`, or `'walk'` |
+| `viewer.getCameraMode()` | Get current camera mode |
+| `viewer.setExploreMode(mode)` | Switch explore sub-mode: `'orbit'` or `'fly'` |
+| `viewer.setPosition(x, y, z)` | Set camera position |
+| `viewer.setRotation(x, y, z)` | Set camera rotation (Euler angles) |
+| `viewer.getPosition()` | Get current camera position |
+| `viewer.getRotation()` | Get current camera rotation |
+| **Playback / Progress** | |
+| `viewer.play()` | Start auto-playing through waypoints |
+| `viewer.pause()` | Pause auto-play |
+| `viewer.stop()` | Stop and reset to first waypoint |
+| `viewer.isPlaying()` | Check if currently auto-playing |
+| `viewer.setProgress(progress)` | Set scroll progress (0-1) |
+| `viewer.getProgress()` | Get current scroll progress (0-1) |
+| **Splat Management** | |
+| `viewer.goToSplat(url)` | Swap to a different splat file at runtime |
+| `viewer.goToOriginalSplat()` | Switch back to the original splat |
+| `viewer.getCurrentSplatUrl()` | Get the currently loaded splat URL |
+| `viewer.isShowingOriginalSplat()` | Check if showing the original splat |
+| `viewer.getAdditionalSplats()` | Get the list of additional splat swap points |
+| **4DGS Frame Sequence** | |
+| `viewer.isFrameSequencePlaying()` | Check if frame sequence is playing |
+| `viewer.setFrame(index)` | Jump to specific frame |
+| `viewer.getCurrentFrame()` | Get current frame index |
+| `viewer.getTotalFrames()` | Get total frame count |
+| `viewer.setFps(fps)` | Set playback FPS |
+| `viewer.getFps()` | Get current FPS |
+| `viewer.getFrameProgress()` | Get frame progress (0-1) |
+| `viewer.setFrameProgress(progress)` | Set frame progress (0-1) |
+| **Audio** | |
+| `viewer.muteAll()` | Mute all audio |
+| `viewer.unmuteAll()` | Unmute all audio |
+| `viewer.isMuted()` | Check if audio is muted |
+| **Hotspots** | |
+| `viewer.getHotspots()` | Get all hotspot data (id, title, type, position) |
+| `viewer.triggerHotspot(id)` | Programmatically open a hotspot popup |
+| `viewer.closeHotspot()` | Close the currently open hotspot popup |
+| **Portals** | |
+| `viewer.navigateToScene(sceneId)` | Navigate to a linked scene via portal |
+| **Lifecycle** | |
+| `viewer.resize()` | Recalculate canvas size (call after container resize) |
+| `viewer.destroy()` | Clean up and remove viewer |
+| **UI** | |
+| `viewer.setButtonLabels(labels)` | Update UI text labels at runtime (see [i18n](#internationalization-i18n)) |
+| **Events** | |
+| `viewer.on(event, callback)` | Register event listener |
+| `viewer.off(event, callback)` | Remove event listener |
+
 ## Configuration Options
 
 ### ViewerOptions
@@ -304,6 +407,16 @@ interface ViewerOptions {
   lazyLoadThumbnail?: string;
   lazyLoadThumbnailType?: 'image' | 'video' | 'gif';  // Thumbnail media type
   lazyLoadButtonText?: string;
+
+  // Allow parent page CSS to affect the viewer
+  allowParentStyles?: boolean;  // Default: false
+
+  // Manual analytics (alternative to createViewerFromSceneId auto-tracking)
+  analytics?: {
+    sceneId: string;
+    ownerId: string;
+    baseUrl?: string;
+  };
 }
 ```
 
@@ -330,6 +443,166 @@ const viewer = createViewer(container, sceneData, {
 });
 ```
 
+## Scene Data Format
+
+When using `createViewer()` with self-hosted JSON, the scene data should match the format exported by the StorySplat editor. The viewer's transform layer normalizes all field variations automatically, so JSON exported from any version of the editor will work.
+
+### Core Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `loadedModelUrl` | `string` | URL to the .splat, .ply, or .ksplat file |
+| `sogModelUrl` / `sogUrl` | `string` | SOG compressed format URL (~95% smaller) |
+| `compressedPlyUrl` | `string` | Compressed PLY format URL (~50% smaller) |
+| `lodMetaUrl` | `string` | LOD streaming meta file URL (see [LOD Streaming](#lod-streaming)) |
+| `waypoints` | `array` | Camera path waypoints |
+| `hotspots` | `array` | Interactive hotspot markers |
+| `portals` | `array` | Scene-to-scene navigation portals |
+| `audioEmitters` | `array` | Spatial audio sources (see [Audio Emitters](#audio-emitters)) |
+| `htmlMeshes` | `array` | HTML-in-3D texture panels (see [HTML Meshes](#html-meshes)) |
+| `particleSystems` | `array` | Particle effect systems |
+| `customMeshes` | `array` | Imported 3D models (.glb/.gltf) |
+| `collisionMeshesData` | `array` | Primitive collision shapes |
+| `voxelCollisionUrl` | `string` | Voxel octree collision data URL (see [Voxel Collision](#voxel-collision)) |
+| `additionalSplats` | `array` | Splat swap points along the waypoint path |
+
+### Visual & Environment
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `activeSkyboxUrl` | `string` | URL to the skybox HDR/image file |
+| `skyboxRotation` | `number` | Skybox rotation offset in radians |
+| `lights` | `array` | Scene lighting configuration |
+| `backgroundColor` | `string` | Background color (hex) |
+| `splatRelighting` | `object` | Splat relighting config (see [Splat Relighting](#splat-relighting)) |
+
+### Camera & Navigation
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `defaultCameraMode` | `string` | Initial camera mode: `'tour'`, `'explore'`, or `'walk'` |
+| `orbitCameraSettings` | `object` | Initial orbit camera position + pivot: `{ cameraPosition: {x,y,z}, pivotPoint: {x,y,z} }` |
+| `doubleTapMoveSpeed` | `number` | Auto-forward speed on double-tap in explore mode (default: 1.0) |
+| `refocusTapMode` | `string` | Camera refocus trigger: `'single'` or `'double'` (default: `'single'`) |
+| `headBobEnabled` | `boolean` | Enable head bob in walk mode (default: true) |
+| `lodSettings` | `object` | LOD display settings (see [LOD Streaming](#lod-streaming)) |
+
+### UI & Appearance
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uiColor` | `string` | Accent color for UI controls |
+| `uiOptions` | `object` | UI visibility toggles and button labels |
+| `uiOptions.viewerTheme` | `ViewerTheme` | Custom viewer theme overrides (see [Theme Customization](#viewer-theme-customization)) |
+| `uiOptions.buttonLabels` | `ButtonLabels` | UI text overrides (see [i18n](#internationalization-i18n)) |
+| `revealStyle` | `string` | Reveal animation: `'bloom'` or `'radial'` |
+| `swapTransitionType` | `string` | Splat swap transition: `'scanline'` or `'dissolve'` (default: `'dissolve'`) |
+
+### Model URL Priority
+
+The viewer loads model files in this priority order:
+
+1. `lodMetaUrl` — LOD streaming (best quality, progressive loading)
+2. `sogModelUrl` / `sogUrl` — SOG compressed (~95% compression)
+3. `compressedPlyUrl` — Compressed PLY (~50% compression)
+4. `loadedModelUrl` — Original upload
+5. `splatUrl` — Legacy fallback
+
+## LOD Streaming
+
+LOD (Level-of-Detail) streaming progressively loads splat data in chunks, starting with low-detail and refining to full quality. This dramatically improves initial load times for large scenes.
+
+### How It Works
+
+The `lodMetaUrl` field points to a `lod-meta.json` file that references chunk files. Each chunk contains texture data (means, scales, quats, spherical harmonics) at different detail levels.
+
+### LOD Settings
+
+Configure LOD display behavior via `lodSettings` in scene data:
+
+```javascript
+const sceneData = {
+  lodMetaUrl: '/path/to/lod-meta.json',
+  lodSettings: {
+    preset: 'auto',  // 'auto' | 'desktop-max' | 'desktop' | 'mobile-max' | 'mobile' | 'custom'
+    // Custom overrides (only used when preset is 'custom'):
+    lodDistances: [10, 20, 40, 80, 160],  // 5 distance thresholds
+    lodRangeMin: 0,   // Min LOD range (0-5)
+    lodRangeMax: 5,   // Max LOD range (0-5)
+    // Per-device overrides when preset is 'auto':
+    mobilePreset: 'mobile',     // Preset for mobile devices
+    desktopPreset: 'desktop',   // Preset for desktop devices
+  }
+};
+```
+
+| Preset | Description |
+|--------|-------------|
+| `auto` | Automatically selects based on device type |
+| `desktop-max` | Maximum quality for desktop |
+| `desktop` | Balanced quality for desktop |
+| `mobile-max` | Maximum quality for mobile |
+| `mobile` | Balanced quality for mobile (recommended for mobile) |
+| `custom` | Use custom `lodDistances` and `lodRange` values |
+
+## 4DGS Frame Sequences
+
+4DGS (4D Gaussian Splatting) enables playback of frame-by-frame splat animations — like video but in 3D.
+
+### Configuration
+
+Add a `frameSequence` config to your scene data:
+
+```javascript
+const sceneData = {
+  loadedModelUrl: '/frames/frame_000.ply',  // First frame (also used as static fallback)
+  frameSequence: {
+    frameUrls: [
+      '/frames/frame_000.ply',
+      '/frames/frame_001.ply',
+      '/frames/frame_002.ply',
+      // ... up to N frames
+    ],
+    fps: 24,           // Playback FPS (default: 24)
+    loop: true,        // Loop playback (default: true)
+    preloadCount: 10,  // Frames to preload ahead (default: 10)
+    autoplay: true,    // Auto-play immediately (default: false)
+  }
+};
+```
+
+### Controlling Frame Playback
+
+```javascript
+const viewer = createViewer(container, sceneData);
+
+// Frame navigation
+viewer.setFrame(0);                    // Jump to first frame
+viewer.getCurrentFrame();              // Get current frame index
+viewer.getTotalFrames();               // Get total frame count
+viewer.isFrameSequencePlaying();       // Check if playing
+
+// Playback speed
+viewer.setFps(30);                     // Change FPS
+viewer.getFps();                       // Get current FPS
+
+// Progress (0-1)
+viewer.setFrameProgress(0.5);          // Jump to 50% through sequence
+viewer.getFrameProgress();             // Get current progress
+```
+
+### 4DGS Events
+
+```javascript
+viewer.on('frameChange', ({ frame, total }) => {
+  console.log(`Frame ${frame} of ${total}`);
+});
+
+viewer.on('frameComplete', () => {
+  console.log('Frame sequence finished (non-looping)');
+});
+```
+
 ## Viewer Theme Customization
 
 The viewer supports deep CSS customization via the `ViewerTheme` interface. You can override colors, font sizes, border radii, and more — either via scene data or programmatically.
@@ -362,8 +635,8 @@ const viewer = createViewer(container, sceneData);
 
 | Category | Properties |
 |----------|-----------|
-| **Colors** (19) | `buttonBg`, `buttonHoverBg`, `buttonTextColor`, `popupBg`, `popupTextColor`, `popupCloseBtnColor`, `popupLinkBtnColor`, `preloaderBg`, `preloaderTextColor`, `infoBannerBg`, `dropdownBg`, `watermarkBg`, `helpPanelBg`, `errorPopupBg`, `errorTitleColor`, `lazyLoadBg`, `joystickBaseColor`, `joystickThumbColor`, `portalPopupBg` |
-| **Typography** (8) | `fontFamily`, `buttonFontSize`, `popupTitleFontSize`, `popupContentFontSize`, `infoBannerTitleFontSize`, `infoBannerContentFontSize`, `progressFontSize`, `modeBtnFontSize`, `watermarkFontSize` |
+| **Colors** (20) | `globalTextColor`, `buttonBg`, `buttonHoverBg`, `buttonTextColor`, `popupBg`, `popupTextColor`, `popupCloseBtnColor`, `popupLinkBtnColor`, `preloaderBg`, `preloaderTextColor`, `infoBannerBg`, `dropdownBg`, `watermarkBg`, `helpPanelBg`, `errorPopupBg`, `errorTitleColor`, `lazyLoadBg`, `joystickBaseColor`, `joystickThumbColor`, `portalPopupBg` |
+| **Typography** (9) | `fontFamily`, `buttonFontSize`, `popupTitleFontSize`, `popupContentFontSize`, `infoBannerTitleFontSize`, `infoBannerContentFontSize`, `progressFontSize`, `modeBtnFontSize`, `watermarkFontSize` |
 | **Border Radii** (6) | `buttonBorderRadius`, `popupBorderRadius`, `dropdownBorderRadius`, `helpPanelBorderRadius`, `errorPopupBorderRadius`, `lazyLoadBtnBorderRadius` |
 | **Other** (3) | `dropdownBlur`, `progressBarHeight`, `preloaderBarHeight` |
 
@@ -398,6 +671,10 @@ const sceneData = {
     ambientIntensity: 0.8,        // 0-1, ambient fill strength
     allowViewerToggle: true,      // Show toggle button in viewer UI
     viewerDefaultOn: false,       // Start with relighting off for end users
+    shadowsEnabled: false,        // Enable shadow casting
+    shadowIntensity: 0.5,         // Shadow strength (0-1)
+    shadowGroundY: 0,             // Ground plane Y position for shadows
+    shadowPlaneScale: 10,         // Shadow receiving plane size
   }
 };
 ```
@@ -542,6 +819,11 @@ viewer.on('progressUpdate', ({ progress, index }) => {
   console.log(`Progress: ${(progress * 100).toFixed(0)}%, waypoint ${index}`);
 });
 
+// Hotspot clicked
+viewer.on('hotspotClick', ({ hotspot }) => {
+  console.log(`Hotspot clicked: ${hotspot.id} - ${hotspot.title}`);
+});
+
 // XR sessions
 viewer.on('xrStart', ({ type }) => console.log(`Entered ${type}`));
 viewer.on('xrEnd', () => console.log('Exited XR'));
@@ -551,6 +833,14 @@ viewer.on('splatChange', ({ url, isOriginal }) => {
   console.log(`Splat changed: ${url} (original: ${isOriginal})`);
 });
 
+// 4DGS frame sequence
+viewer.on('frameChange', ({ frame, total }) => {
+  console.log(`Frame ${frame} of ${total}`);
+});
+viewer.on('frameComplete', () => {
+  console.log('Frame sequence complete');
+});
+
 // Portal activated
 viewer.on('portalActivated', ({ sceneId }) => {
   console.log(`Navigating to scene: ${sceneId}`);
@@ -565,260 +855,256 @@ viewer.on('warning', ({ type, message }) => {
 });
 ```
 
-## React Integration
+### All Events Reference
 
-```jsx
-import { useEffect, useRef } from 'react';
-import { createViewerFromSceneId } from 'storysplat-viewer';
+| Event | Data | Description |
+|-------|------|-------------|
+| `ready` | — | Viewer initialized |
+| `loaded` | — | Scene fully loaded |
+| `progress` | `{ loaded, total, percent }` | Loading progress |
+| `waypointChange` | `{ index, waypoint }` | Waypoint changed |
+| `playbackStart` | — | Auto-play started |
+| `playbackStop` | — | Auto-play paused/stopped |
+| `playbackComplete` | — | Tour reached the end |
+| `modeChange` | `{ mode }` | Camera mode changed |
+| `progressUpdate` | `{ progress, index }` | Scroll progress updated |
+| `hotspotClick` | `{ hotspot }` | Hotspot clicked |
+| `xrStart` | `{ type }` | Entered VR/AR |
+| `xrEnd` | — | Exited VR/AR |
+| `splatChange` | `{ url, isOriginal }` | Splat file swapped |
+| `frameChange` | `{ frame, total }` | 4DGS frame changed |
+| `frameComplete` | — | 4DGS sequence finished |
+| `portalActivated` | `{ portalId, targetSceneId, targetSceneName }` | Portal triggered |
+| `portalNavigationStart` | `{ targetSceneId }` | Portal navigation beginning |
+| `portalNavigationComplete` | `{ sceneId }` | Portal navigation complete |
+| `portalNavigationError` | `{ error, targetSceneId }` | Portal navigation failed |
+| `error` | `Error` | Viewer error |
+| `warning` | `{ type, message }` | Non-fatal warning |
 
-function StorySplatViewer({ sceneId }) {
-  const containerRef = useRef(null);
-  const viewerRef = useRef(null);
+## Portals (Scene-to-Scene Navigation)
 
-  useEffect(() => {
-    let mounted = true;
+Portals allow users to navigate between multiple 3D scenes by clicking or walking near portal markers.
 
-    async function initViewer() {
-      if (!containerRef.current) return;
+### How Portals Work
 
-      try {
-        const viewer = await createViewerFromSceneId(
-          containerRef.current,
-          sceneId
-        );
+Portals are configured in the scene JSON with a `targetSceneId`:
 
-        if (mounted) {
-          viewerRef.current = viewer;
-        } else {
-          viewer.destroy();
-        }
-      } catch (error) {
-        console.error('Failed to create viewer:', error);
-      }
+```json
+{
+  "portals": [
+    {
+      "id": "portal-1",
+      "targetSceneId": "abc123xyz",
+      "targetSceneName": "Campervan Interior",
+      "targetSceneThumbnail": "https://example.com/thumb.jpg",
+      "position": { "x": 2, "y": 0, "z": -3 },
+      "type": "sphere",
+      "activationMode": "click",
+      "confirmNavigation": true,
+      "menuOnly": false,
+      "menuPath": "Building A/Floor 1"
     }
+  ]
+}
+```
 
-    initViewer();
+### Portal Fields
 
-    return () => {
-      mounted = false;
-      viewerRef.current?.destroy();
-    };
-  }, [sceneId]);
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique portal identifier |
+| `targetSceneId` | `string` | Scene ID to navigate to |
+| `targetSceneName` | `string` | Display name for the target scene |
+| `targetSceneThumbnail` | `string` | Thumbnail URL for portal preview |
+| `position` | `{x, y, z}` | 3D position of the portal marker |
+| `type` | `string` | Portal mesh shape (`'sphere'`, `'cube'`, etc.) |
+| `activationMode` | `string` | `'click'` or `'proximity'` |
+| `confirmNavigation` | `boolean` | Show confirmation dialog before navigating |
+| `menuOnly` | `boolean` | If true, portal appears only in the scene menu, not as a 3D mesh |
+| `menuPath` | `string` | Folder path for menu organization (e.g., `"Building A/Floor 1"`) |
 
-  return (
-    <div
-      ref={containerRef}
-      style={{ width: '100%', height: '500px' }}
-    />
-  );
-}
+### Self-Hosted Portal Navigation
 
-export default StorySplatViewer;
-```
+By default, portals use StorySplat scene IDs and fetch from `discover.storysplat.com`. For fully self-hosted portals, intercept the `portalActivated` event:
 
-## Error Handling
+```javascript
+import { createViewer } from 'storysplat-viewer';
 
-The package exports error classes for specific error handling:
+const SCENES = {
+  'campervan': '/scenes/campervan/scene.json',
+  'cabin': '/scenes/cabin/scene.json',
+};
 
-```javascript
-import {
-  createViewerFromSceneId,
-  SceneNotFoundError,
-  SceneApiError
-} from 'storysplat-viewer';
+let currentViewer = null;
 
-try {
-  const viewer = await createViewerFromSceneId(container, sceneId);
-} catch (error) {
-  if (error instanceof SceneNotFoundError) {
-    console.error('Scene not found or not public');
-  } else if (error instanceof SceneApiError) {
-    console.error(`API error (${error.statusCode}): ${error.message}`);
-  } else {
-    console.error('Unknown error:', error);
-  }
-}
-```
+async function loadScene(sceneId) {
+  if (currentViewer) currentViewer.destroy();
 
-## Controlling the Viewer
+  const sceneData = await fetch(SCENES[sceneId]).then(r => r.json());
+  currentViewer = await createViewer(container, sceneData);
 
-The viewer instance provides methods to control playback, navigation, and camera programmatically. This is useful for building custom UI controls outside the viewer.
+  currentViewer.on('portalActivated', (data) => {
+    loadScene(data.targetSceneId);
+  });
+}
 
-### External Control Example
+loadScene('campervan');
+```
 
-```html
-<div id="viewer" style="width: 100%; height: 500px;"></div>
+The `targetSceneId` is just a string you define — it doesn't need to exist on StorySplat. Map it to your own file paths.
 
-<div id="controls">
-  <button id="prev">Previous</button>
-  <button id="play">Play</button>
-  <button id="pause">Pause</button>
-  <button id="next">Next</button>
-  <span id="waypoint-info"></span>
-</div>
+### Portal Events
 
-<script type="module">
-import { createViewerFromSceneId } from 'storysplat-viewer';
+| Event | Description | Data |
+|-------|-------------|------|
+| `portalActivated` | Portal clicked or proximity triggered | `{ portalId, targetSceneId, targetSceneName }` |
+| `portalNavigationStart` | Navigation beginning | `{ targetSceneId }` |
+| `portalNavigationComplete` | New scene loaded | `{ sceneId }` |
+| `portalNavigationError` | Navigation failed | `{ error, targetSceneId }` |
 
-const viewer = await createViewerFromSceneId(
-  document.getElementById('viewer'),
-  'YOUR_SCENE_ID'
-);
+## Audio Emitters
 
-// Navigation
-document.getElementById('prev').onclick = () => viewer.prevWaypoint();
-document.getElementById('next').onclick = () => viewer.nextWaypoint();
+Audio emitters are standalone spatial audio sources positioned in 3D space. They support distance-based attenuation and spatialization.
 
-// Playback
-document.getElementById('play').onclick = () => viewer.play();
-document.getElementById('pause').onclick = () => viewer.pause();
-
-// Update waypoint display
-viewer.on('waypointChange', ({ index }) => {
-  const total = viewer.getWaypointCount();
-  document.getElementById('waypoint-info').textContent =
-    `Waypoint ${index + 1} of ${total}`;
-});
-
-// Jump to specific waypoint
-function goToWaypoint(index) {
-  viewer.goToWaypoint(index);
+```json
+{
+  "audioEmitters": [
+    {
+      "id": "birds",
+      "name": "Bird Sounds",
+      "url": "https://example.com/birds.mp3",
+      "position": { "x": 5, "y": 2, "z": -3 },
+      "volume": 0.8,
+      "loop": true,
+      "autoplay": true,
+      "spatialSound": true,
+      "distanceModel": "inverse",
+      "maxDistance": 50,
+      "refDistance": 1,
+      "rolloffFactor": 1,
+      "enabled": true
+    }
+  ]
 }
-</script>
 ```
 
-### Available Control Methods
-
-| Method | Description |
-|--------|-------------|
-| **Navigation** | |
-| `viewer.goToWaypoint(index)` | Jump to specific waypoint (0-indexed) |
-| `viewer.nextWaypoint()` | Go to next waypoint |
-| `viewer.prevWaypoint()` | Go to previous waypoint |
-| `viewer.getCurrentWaypointIndex()` | Get current waypoint index |
-| `viewer.getWaypointCount()` | Get total number of waypoints |
-| **Camera** | |
-| `viewer.setCameraMode(mode)` | Switch mode: `'tour'` or `'explore'` |
-| `viewer.getCameraMode()` | Get current camera mode |
-| `viewer.setExploreMode(mode)` | Switch explore sub-mode: `'orbit'` or `'fly'` |
-| `viewer.setPosition(x, y, z)` | Set camera position |
-| `viewer.setRotation(x, y, z)` | Set camera rotation (Euler angles) |
-| `viewer.getPosition()` | Get current camera position |
-| `viewer.getRotation()` | Get current camera rotation |
-| **Playback / Progress** | |
-| `viewer.play()` | Start auto-playing through waypoints |
-| `viewer.pause()` | Pause auto-play |
-| `viewer.stop()` | Stop and reset to first waypoint |
-| `viewer.isPlaying()` | Check if currently auto-playing |
-| `viewer.setProgress(progress)` | Set scroll progress (0-1) |
-| `viewer.getProgress()` | Get current scroll progress (0-1) |
-| **Splat Management** | |
-| `viewer.goToSplat(url)` | Swap to a different splat file at runtime |
-| `viewer.goToOriginalSplat()` | Switch back to the original splat |
-| `viewer.getCurrentSplatUrl()` | Get the currently loaded splat URL |
-| `viewer.isShowingOriginalSplat()` | Check if showing the original splat |
-| `viewer.getAdditionalSplats()` | Get the list of additional splat swap points |
-| **Audio** | |
-| `viewer.muteAll()` | Mute all audio |
-| `viewer.unmuteAll()` | Unmute all audio |
-| `viewer.isMuted()` | Check if audio is muted |
-| **Hotspots** | |
-| `viewer.getHotspots()` | Get all hotspot data (id, title, type, position) |
-| `viewer.triggerHotspot(id)` | Programmatically open a hotspot popup |
-| `viewer.closeHotspot()` | Close the currently open hotspot popup |
-| **Portals** | |
-| `viewer.navigateToScene(sceneId)` | Navigate to a linked scene via portal |
-| **Lifecycle** | |
-| `viewer.resize()` | Recalculate canvas size (call after container resize) |
-| `viewer.destroy()` | Clean up and remove viewer |
-| **UI** | |
-| `viewer.setButtonLabels(labels)` | Update UI text labels at runtime (see [i18n](#internationalization-i18n)) |
-
-## Analytics & Tracking
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | `string` | — | Unique identifier |
+| `name` | `string` | — | Display name |
+| `url` | `string` | — | Audio file URL |
+| `position` | `{x, y, z}` | `{0,0,0}` | 3D position |
+| `volume` | `number` | `1` | Volume (0-1) |
+| `loop` | `boolean` | `false` | Loop playback |
+| `autoplay` | `boolean` | `false` | Play automatically on load |
+| `spatialSound` | `boolean` | `true` | Enable 3D spatial audio |
+| `distanceModel` | `string` | `'inverse'` | `'inverse'`, `'linear'`, or `'exponential'` |
+| `maxDistance` | `number` | `100` | Maximum hearing distance |
+| `refDistance` | `number` | `1` | Distance at which volume is 100% |
+| `rolloffFactor` | `number` | `1` | How quickly volume decreases with distance |
+| `enabled` | `boolean` | `true` | Whether this emitter is active |
+
+## HTML Meshes
+
+HTML Meshes render HTML content as textures on 3D planes in the scene. They support text, images, iframes, CSS styling, and interactive elements.
 
-When using `createViewerFromSceneId`, the viewer automatically tracks:
-
-- **Views**: Each time a scene is loaded
-- **Bandwidth**: Data transferred when loading StorySplat-hosted files
-
-This data appears in your StorySplat admin dashboard.
-
-### What Gets Tracked
-
-| Scenario | Views | Bandwidth |
-|----------|-------|-----------|
-| `createViewerFromSceneId` with StorySplat-hosted files | Yes | Yes |
-| `createViewerFromSceneId` with self-hosted splat files | Yes | No |
-| `createViewer` (self-hosted scenes) | No | No |
-| iframe embed | Yes | Yes |
-
-### Privacy Note
-
-Tracking only occurs for scenes loaded via `createViewerFromSceneId`. If you use `createViewer` with your own scene data, no data is sent to StorySplat servers.
-
-## Comparison: Scene ID vs JSON File
+```json
+{
+  "htmlMeshes": [
+    {
+      "id": "info-panel",
+      "name": "Info Panel",
+      "htmlContent": "<h2>Welcome</h2><p>This is a 3D info panel</p>",
+      "position": { "x": 0, "y": 2, "z": -5 },
+      "rotation": { "x": 0, "y": 0, "z": 0 },
+      "scale": { "x": 2, "y": 1.5, "z": 1 },
+      "width": 512,
+      "height": 384,
+      "billboard": false,
+      "cssStyles": "background: rgba(0,0,0,0.8); color: white; padding: 20px; font-family: sans-serif;",
+      "visible": true
+    }
+  ]
+}
+```
 
-| Approach | Best For | Pros | Cons |
-|----------|----------|------|------|
-| **Scene ID** | Live content, CMS | Always latest, automatic tracking, no redeploy | Needs internet, API dependency |
-| **JSON File** | Self-hosted, offline | Full control, git-tracked, no external dependencies | Manual updates, no analytics |
+| Field | Type | Description |
+|-------|------|-------------|
+| `htmlContent` | `string` | HTML to render as texture |
+| `position` / `rotation` / `scale` | `{x,y,z}` | 3D transform |
+| `width` / `height` | `number` | Texture resolution in pixels |
+| `billboard` | `boolean` | Always face the camera |
+| `cssStyles` | `string` | CSS to apply to the HTML content |
+| `visible` | `boolean` | Whether the mesh is visible |
 
-## Troubleshooting
+## Voxel Collision
 
-### Container Needs Dimensions
+Voxel collision provides high-fidelity collision detection derived directly from splat geometry. Instead of placing primitive collision shapes manually, the system voxelizes the splat into an octree structure for accurate ground detection and movement blocking in walk mode.
 
-The container element must have explicit dimensions:
+### Scene Data
 
-```css
-#viewer {
-  width: 100%;
-  height: 500px; /* Must have explicit height */
+```json
+{
+  "voxelCollisionUrl": "https://example.com/scene.voxel.json"
 }
 ```
 
-### CORS Issues
+The voxel collision system requires two co-located files:
+- `.voxel.json` — Metadata (bounds, resolution, leaf count)
+- `.voxel.bin` — Binary octree data (nodes + leaf data)
 
-If loading splats from a different domain, ensure the server has proper CORS headers or use a proxy.
+Both primitive collision meshes and voxel collision coexist — primitives are checked first, then the octree.
 
-### Memory Cleanup
+## React Integration
 
-Always destroy the viewer when unmounting:
+```jsx
+import { useEffect, useRef } from 'react';
+import { createViewerFromSceneId } from 'storysplat-viewer';
 
-```javascript
-// Vanilla JS
-window.addEventListener('beforeunload', () => {
-  viewer.destroy();
-});
+function StorySplatViewer({ sceneId }) {
+  const containerRef = useRef(null);
+  const viewerRef = useRef(null);
 
-// React useEffect cleanup
-return () => {
-  viewer?.destroy();
-};
-```
+  useEffect(() => {
+    let mounted = true;
 
-### Build Target Must Be ES2016+
+    async function initViewer() {
+      if (!containerRef.current) return;
 
-If you bundle `storysplat-viewer` with Vite, esbuild, or another bundler, your build target **must be `es2016` or higher** (we recommend `es2020`).
+      try {
+        const viewer = await createViewerFromSceneId(
+          containerRef.current,
+          sceneId
+        );
 
-PlayCanvas (the 3D engine) serializes its gsplat sort worker via `Function.toString()` into a blob URL. If your bundler targets `es2015`, it will extract the `**` (exponentiation) operator into a module-scoped helper function. That helper doesn't exist inside the worker's isolated scope, causing a `ReferenceError` at runtime (e.g., `ss is not defined`).
+        if (mounted) {
+          viewerRef.current = viewer;
+        } else {
+          viewer.destroy();
+        }
+      } catch (error) {
+        console.error('Failed to create viewer:', error);
+      }
+    }
 
-```js
-// vite.config.ts
-export default {
-  build: {
-    target: 'es2020', // Must be es2016+ (NOT es2015)
-  }
-};
-```
+    initViewer();
 
-This only affects production builds — development servers typically don't minify and won't trigger the issue.
+    return () => {
+      mounted = false;
+      viewerRef.current?.destroy();
+    };
+  }, [sceneId]);
 
-### Browser Compatibility
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', height: '500px' }}
+    />
+  );
+}
 
-StorySplat Viewer requires:
-- WebGL 2.0 support
-- Modern JavaScript (ES2016+)
-- Recommended browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
+export default StorySplatViewer;
+```
 
 ## Native App Integration
 
@@ -932,39 +1218,64 @@ For simple web integration, use an iframe:
 </iframe>
 ```
 
-### Self-Hosting
+### CDN Options
 
-To self-host the viewer bundle instead of using a CDN:
+The viewer is available on multiple CDNs. **We recommend the bundled build for simplicity** — it includes PlayCanvas, so you only need one script:
+
+```html
+<!-- RECOMMENDED: Bundled build (includes PlayCanvas - single script!) -->
+<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.bundled.umd.js"></script>
+
+<!-- Alternative: Separate scripts (if you need a specific PlayCanvas version) -->
+<script src="https://cdn.jsdelivr.net/npm/playcanvas@2.14.3/build/playcanvas.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.umd.js"></script>
+
+<!-- unpkg alternative -->
+<script src="https://unpkg.com/storysplat-viewer@2/dist/storysplat-viewer.bundled.umd.js"></script>
+```
+
+### Self-Hosting the Bundle
 
-1. Download the UMD bundle from npm:
 ```bash
 npm pack storysplat-viewer
 # Extract storysplat-viewer-x.x.x.tgz
-# Copy dist/storysplat-viewer.umd.js to your server
+# Copy dist/storysplat-viewer.bundled.umd.js to your server
 ```
 
-2. Reference your self-hosted bundle:
 ```html
-<script src="/path/to/storysplat-viewer.umd.js"></script>
+<script src="/path/to/storysplat-viewer.bundled.umd.js"></script>
 ```
 
-### CDN Alternatives
+## Analytics & Tracking
 
-The viewer is available on multiple CDNs. **We recommend the bundled build for simplicity** - it includes PlayCanvas, so you only need one script:
+When using `createViewerFromSceneId`, the viewer automatically tracks:
 
-```html
-<!-- RECOMMENDED: Bundled build (includes PlayCanvas - single script!) -->
-<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.bundled.umd.js"></script>
+- **Views**: Each time a scene is loaded
+- **Bandwidth**: Data transferred when loading StorySplat-hosted files
 
-<!-- Alternative: Separate scripts (if you need a specific PlayCanvas version) -->
-<script src="https://cdn.jsdelivr.net/npm/playcanvas@2.14.3/build/playcanvas.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.umd.js"></script>
+This data appears in your StorySplat admin dashboard.
 
-<!-- unpkg alternative -->
-<script src="https://unpkg.com/storysplat-viewer@2/dist/storysplat-viewer.bundled.umd.js"></script>
-```
+### What Gets Tracked
+
+| Scenario | Views | Bandwidth |
+|----------|-------|-----------|
+| `createViewerFromSceneId` with StorySplat-hosted files | Yes | Yes |
+| `createViewerFromSceneId` with self-hosted splat files | Yes | No |
+| `createViewer` (self-hosted scenes) | No | No |
+| iframe embed | Yes | Yes |
+
+### Privacy Note
+
+Tracking only occurs for scenes loaded via `createViewerFromSceneId`. If you use `createViewer` with your own scene data, no data is sent to StorySplat servers.
 
-### Standalone HTML Generation
+### Comparison: Scene ID vs JSON File
+
+| Approach | Best For | Pros | Cons |
+|----------|----------|------|------|
+| **Scene ID** | Live content, CMS | Always latest, automatic tracking, no redeploy | Needs internet, API dependency |
+| **JSON File** | Self-hosted, offline | Full control, git-tracked, no external dependencies | Manual updates, no analytics |
+
+## Standalone HTML Generation
 
 Generate standalone HTML files programmatically:
 
@@ -988,7 +1299,7 @@ import fs from 'fs';
 fs.writeFileSync('scene.html', html);
 ```
 
-#### GenerateHTMLOptions
+### GenerateHTMLOptions
 
 ```typescript
 interface GenerateHTMLOptions {
@@ -1003,208 +1314,32 @@ interface GenerateHTMLOptions {
 }
 ```
 
-## Portals (Scene-to-Scene Navigation)
-
-Portals allow users to navigate between multiple 3D scenes by clicking or walking near portal markers.
-
-### How Portals Work
-
-Portals are configured in the scene JSON with a `targetSceneId`:
-
-```json
-{
-  "portals": [
-    {
-      "id": "portal-1",
-      "targetSceneId": "abc123xyz",
-      "targetSceneName": "Campervan Interior",
-      "position": { "x": 2, "y": 0, "z": -3 },
-      "type": "sphere",
-      "activationMode": "click"
-    }
-  ]
-}
-```
-
-### Portal Paths for Self-Hosted Scenes
-
-**Important:** By default, portals use StorySplat scene IDs and fetch from `discover.storysplat.com`. For fully self-hosted portals, you need to intercept the `portalActivated` event and implement custom navigation.
-
-#### Self-Hosted Portal Example
-
-```javascript
-import { createViewer } from 'storysplat-viewer';
-
-// Your self-hosted scene folder structure:
-// /scenes/
-//   ├── scene_campervan/
-//   │   └── scene.json
-//   ├── scene_cabin/
-//   │   └── scene.json
-//   └── scene_garden/
-//       └── scene.json
-
-// Load initial scene
-const initialScene = await fetch('/scenes/scene_campervan/scene.json').then(r => r.json());
-let viewer = await createViewer(container, initialScene);
-
-// Handle portal navigation with custom paths
-viewer.on('portalActivated', async (data) => {
-  console.log('Portal clicked:', data.targetSceneId);
-
-  // Map scene IDs to your folder paths
-  const scenePaths = {
-    'cabin-scene-id': '/scenes/scene_cabin/scene.json',
-    'garden-scene-id': '/scenes/scene_garden/scene.json',
-    // Or use the scene ID directly as folder name:
-    // [data.targetSceneId]: `/scenes/${data.targetSceneId}/scene.json`
-  };
-
-  const scenePath = scenePaths[data.targetSceneId];
-  if (!scenePath) {
-    console.error('Unknown scene:', data.targetSceneId);
-    return;
-  }
-
-  // Fetch from YOUR server
-  const newSceneData = await fetch(scenePath).then(r => r.json());
-
-  // Dispose old viewer and create new one
-  viewer.destroy();
-  viewer = await createViewer(container, newSceneData);
-
-  // Re-attach portal handler for the new scene
-  viewer.on('portalActivated', arguments.callee);
-});
-```
-
-#### Using Relative Paths
-
-If you want to use the `targetSceneId` directly as a folder name:
-
-```javascript
-viewer.on('portalActivated', async (data) => {
-  // targetSceneId becomes the folder name
-  const scenePath = `/scenes/${data.targetSceneId}/scene.json`;
-
-  const newSceneData = await fetch(scenePath).then(r => r.json());
-  viewer.destroy();
-  viewer = await createViewer(container, newSceneData);
-});
-```
-
-Then structure your folders to match:
-```
-/scenes/
-  ├── campervan/        ← targetSceneId: "campervan"
-  │   └── scene.json
-  ├── cabin/            ← targetSceneId: "cabin"
-  │   └── scene.json
-```
-
-#### Fully Self-Hosted (No StorySplat at All)
-
-If both scenes are created locally and **never uploaded to StorySplat**, you have full control over the `targetSceneId` values. They don't need to be real StorySplat IDs—use any string identifier you want:
-
-**Step 1: Edit your scene.json files to add portals with custom IDs**
-
-```json
-// scenes/campervan/scene.json
-{
-  "name": "Campervan Tour",
-  "portals": [
-    {
-      "id": "portal-1",
-      "targetSceneId": "cabin",
-      "targetSceneName": "Mountain Cabin",
-      "position": { "x": 2, "y": 0, "z": -3 },
-      "type": "sphere",
-      "activationMode": "click"
-    }
-  ]
-}
-```
-
-```json
-// scenes/cabin/scene.json
-{
-  "name": "Mountain Cabin",
-  "portals": [
-    {
-      "id": "portal-back",
-      "targetSceneId": "campervan",
-      "targetSceneName": "Back to Campervan",
-      "position": { "x": -1, "y": 0, "z": 2 },
-      "type": "sphere",
-      "activationMode": "click"
-    }
-  ]
-}
-```
+## Error Handling
 
-**Step 2: Complete self-hosted viewer code**
+The package exports error classes for specific error handling:
 
 ```javascript
-import { createViewer } from 'storysplat-viewer';
-
-const container = document.getElementById('viewer');
-
-// Map your scene identifiers to file paths
-const SCENES = {
-  'campervan': '/scenes/campervan/scene.json',
-  'cabin': '/scenes/cabin/scene.json',
-  'garden': '/scenes/garden/scene.json'
-};
-
-let currentViewer = null;
+import {
+  createViewerFromSceneId,
+  SceneNotFoundError,
+  SceneApiError
+} from 'storysplat-viewer';
 
-async function loadScene(sceneId) {
-  // Cleanup previous viewer
-  if (currentViewer) {
-    currentViewer.destroy();
+try {
+  const viewer = await createViewerFromSceneId(container, sceneId);
+} catch (error) {
+  if (error instanceof SceneNotFoundError) {
+    console.error('Scene not found or not public');
+  } else if (error instanceof SceneApiError) {
+    console.error(`API error (${error.statusCode}): ${error.message}`);
+  } else {
+    console.error('Unknown error:', error);
   }
-
-  // Fetch scene from YOUR server
-  const sceneData = await fetch(SCENES[sceneId]).then(r => r.json());
-
-  // Create viewer
-  currentViewer = await createViewer(container, sceneData);
-
-  // Handle portal clicks - loads target scene from your server
-  currentViewer.on('portalActivated', (data) => {
-    loadScene(data.targetSceneId);
-  });
 }
-
-// Start with initial scene
-loadScene('campervan');
 ```
 
-**Key point:** The `targetSceneId` is just a string you define. It doesn't need to exist on StorySplat—you map it to your own file paths.
-
-#### Portal Events
-
-| Event | Description | Data |
-|-------|-------------|------|
-| `portalActivated` | Portal clicked or proximity triggered | `{ portalId, targetSceneId, targetSceneName }` |
-| `portalNavigationStart` | Navigation beginning | `{ targetSceneId }` |
-| `portalNavigationComplete` | New scene loaded | `{ sceneId }` |
-| `portalNavigationError` | Navigation failed | `{ error, targetSceneId }` |
-
-### Q: Where does the viewer look for scene files?
-
-**A: It depends on how you load scenes:**
-
-- **`createViewerFromSceneId()`** - Fetches from `discover.storysplat.com/api/scene/{id}`
-- **`createViewer(sceneData)`** - Uses the data object you pass in directly (no fetch)
-- **Splat file URLs in scene JSON** - Can be absolute URLs or relative to your page
-
-The viewer itself has no "base path" concept - splat file paths in your scene JSON should be absolute URLs or relative to your HTML page, not to the viewer JS file.
-
 ## Exports
 
-The package exports the following types and utilities:
-
 ```typescript
 // Core viewer functions
 import {
@@ -1238,13 +1373,71 @@ import {
   getGsplatRelightingClass,
   SceneNotFoundError,
   SceneApiError,
+  BUILD_VERSION,
 } from 'storysplat-viewer';
 ```
 
+## Troubleshooting
+
+### Container Needs Dimensions
+
+The container element must have explicit dimensions:
+
+```css
+#viewer {
+  width: 100%;
+  height: 500px; /* Must have explicit height */
+}
+```
+
+### CORS Issues
+
+If loading splats from a different domain, ensure the server has proper CORS headers or use a proxy.
+
+### Memory Cleanup
+
+Always destroy the viewer when unmounting:
+
+```javascript
+// Vanilla JS
+window.addEventListener('beforeunload', () => {
+  viewer.destroy();
+});
+
+// React useEffect cleanup
+return () => {
+  viewer?.destroy();
+};
+```
+
+### Build Target Must Be ES2016+
+
+If you bundle `storysplat-viewer` with Vite, esbuild, or another bundler, your build target **must be `es2016` or higher** (we recommend `es2020`).
+
+PlayCanvas (the 3D engine) serializes its gsplat sort worker via `Function.toString()` into a blob URL. If your bundler targets `es2015`, it will extract the `**` (exponentiation) operator into a module-scoped helper function. That helper doesn't exist inside the worker's isolated scope, causing a `ReferenceError` at runtime (e.g., `ss is not defined`).
+
+```js
+// vite.config.ts
+export default {
+  build: {
+    target: 'es2020', // Must be es2016+ (NOT es2015)
+  }
+};
+```
+
+This only affects production builds — development servers typically don't minify and won't trigger the issue.
+
+### Browser Compatibility
+
+StorySplat Viewer requires:
+- WebGL 2.0 support
+- Modern JavaScript (ES2016+)
+- Recommended browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
+
 ## Support
 
 - GitHub Issues: [github.com/SonnyC56/storysplat-viewer/issues](https://github.com/SonnyC56/storysplat-viewer/issues)
-- Documentation: [docs.storysplat.com](https://docs.storysplat.com)
+- Documentation: [discover.storysplat.com/docs](https://discover.storysplat.com/docs)
 
 ## License