storysplat-viewer 2.9.47 → 2.9.48

package/README.md

@@ -29,6 +29,9 @@ A powerful npm package for embedding and interacting with 3D Gaussian Splatting
 - [Post-Processing](#post-processing)
 - [Custom Menu Links](#custom-menu-links)
 - [Entity Animations](#entity-animations)
+- [Guided Narration](#guided-narration)
+- [Custom Scripts](#custom-scripts)
+- [8th Wall AR](#8th-wall-ar)
 - [React Integration](#react-integration)
 - [Native App Integration](#native-app-integration)
 - [Analytics & Tracking](#analytics--tracking)
@@ -599,7 +602,7 @@ viewer.getFrameProgress();             // Get current progress
 ### 4DGS Events
 
 ```javascript
-viewer.on('frameChange', ({ frame, total }) => {
+viewer.on('frameChange', (frame, total) => {
   console.log(`Frame ${frame} of ${total}`);
 });
 
@@ -800,8 +803,8 @@ viewer.on('loaded', () => {
 });
 
 // Loading progress
-viewer.on('progress', ({ loaded, total, percent }) => {
-  console.log(`Loading: ${percent}%`);
+viewer.on('progress', ({ progress, text }) => {
+  console.log(`Loading ${Math.round(progress * 100)}%: ${text}`);
 });
 
 // Waypoint changed
@@ -839,7 +842,7 @@ viewer.on('splatChange', ({ url, isOriginal }) => {
 });
 
 // 4DGS frame sequence
-viewer.on('frameChange', ({ frame, total }) => {
+viewer.on('frameChange', (frame, total) => {
   console.log(`Frame ${frame} of ${total}`);
 });
 viewer.on('frameComplete', () => {
@@ -847,8 +850,8 @@ viewer.on('frameComplete', () => {
 });
 
 // Portal activated
-viewer.on('portalActivated', ({ sceneId }) => {
-  console.log(`Navigating to scene: ${sceneId}`);
+viewer.on('portalActivated', ({ targetSceneId }) => {
+  console.log(`Navigating to scene: ${targetSceneId}`);
 });
 
 // Errors and warnings
@@ -865,9 +868,9 @@ viewer.on('warning', ({ type, message }) => {
 | Event | Data | Description |
 |-------|------|-------------|
 | `ready` | — | Viewer initialized |
-| `loaded` | — | Scene fully loaded |
-| `progress` | `{ loaded, total, percent }` | Loading progress |
-| `waypointChange` | `{ index, waypoint }` | Waypoint changed |
+| `loaded` | `{ bandwidthUsed, isStorySplatHosted }` | Scene fully loaded |
+| `progress` | `{ progress, text }` | Loading progress |
+| `waypointChange` | `{ index, waypoint, prevIndex, cameraMode }` | Waypoint changed |
 | `playbackStart` | — | Auto-play started |
 | `playbackStop` | — | Auto-play paused/stopped |
 | `playbackComplete` | — | Tour reached the end |
@@ -877,12 +880,11 @@ viewer.on('warning', ({ type, message }) => {
 | `xrStart` | `{ type }` | Entered VR/AR |
 | `xrEnd` | — | Exited VR/AR |
 | `splatChange` | `{ url, isOriginal }` | Splat file swapped |
-| `frameChange` | `{ frame, total }` | 4DGS frame changed |
+| `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 |
+| `portalClick` | `{ portal }` | Portal clicked in editor mode |
+| `panoramaModeChange` | `{ enabled }` | 360 panorama portal mode changed |
 | `error` | `Error` | Viewer error |
 | `warning` | `{ type, message }` | Non-fatal warning |
 
@@ -963,9 +965,8 @@ The `targetSceneId` is just a string you define — it doesn't need to exist on
 | 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 }` |
+| `portalClick` | Portal clicked in editor mode | `{ portal }` |
+| `panoramaModeChange` | 360 panorama portal mode changed | `{ enabled }` |
 
 ## Audio Emitters
 
@@ -1247,6 +1248,113 @@ Keyframe-based animation system for any scene entity (hotspots, portals, lights,
 | Scale | `scale.x`, `scale.y`, `scale.z` |
 | Particles | `rate`, `lifetime`, `speed`, `scale`, `gravity`, `opacity`, `rotationSpeed` |
 
+## Guided Narration
+
+Add a continuous voiceover that synchronizes with the camera tour. The camera speed adjusts automatically per segment to match the narration timing.
+
+### Scene Data
+
+```json
+{
+  "narrationTrack": {
+    "enabled": true,
+    "audioUrl": "https://example.com/narration.mp3",
+    "duration": 120,
+    "volume": 0.8,
+    "segments": [
+      {
+        "id": "intro",
+        "audioStart": 0,
+        "audioEnd": 15,
+        "progressStart": 0,
+        "progressEnd": 25
+      },
+      {
+        "id": "gallery",
+        "audioStart": 15,
+        "audioEnd": 45,
+        "progressStart": 25,
+        "progressEnd": 60
+      }
+    ]
+  }
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Master toggle for narration |
+| `audioUrl` | `string` | URL to the narration audio file (MP3, WAV, OGG) |
+| `duration` | `number` | Total audio duration in seconds |
+| `volume` | `number` | Playback volume (0–1) |
+| `segments` | `array` | Maps audio time ranges to tour progress ranges |
+| `segments[].id` | `string` | Stable segment identifier |
+| `segments[].audioStart` / `audioEnd` | `number` | Time range in the audio file (seconds) |
+| `segments[].progressStart` / `progressEnd` | `number` | Corresponding tour progress range (0–100) |
+
+The viewer derives camera progress from the active audio segment and only seeks the audio when drift exceeds 0.5 seconds. Narration pauses when the viewer switches to Explore or Walk mode and resumes when returning to Tour mode.
+
+## Custom Scripts
+
+Execute custom JavaScript in the viewer sandbox for advanced behaviors. Scripts have access to the viewer API but run in a restricted environment with no network, DOM, or storage access.
+
+### Scene Data
+
+```json
+{
+  "customScript": "viewer.on('waypointChange', ({ index }) => {\n  console.log('Arrived at waypoint', index);\n});"
+}
+```
+
+### Available Globals
+
+| Global | Description |
+|--------|-------------|
+| `viewer` | The main viewer API (navigation, camera, audio, hotspots, splats, 4DGS) |
+| `canvas` | Read-only access to the rendering canvas (dimensions and pointer events) |
+| `getScrollPercentage()` | Returns current scroll progress (0–1) |
+| `getCurrentWaypointIndex()` | Returns the current waypoint index |
+| `registerUpdate(fn)` | Register a function that runs every frame |
+| `registerCleanup(fn)` | Register a function that runs on disposal |
+| `console` | Standard log, warn, error, info, debug |
+| `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` | Timer functions |
+| `requestAnimationFrame`, `cancelAnimationFrame` | Animation frame functions |
+| `queueMicrotask` | Microtask scheduling |
+
+Scripts are limited to 200,000 characters. The `registerUpdate` callback count is capped at 200.
+
+### Blocked (Security)
+
+No `fetch`, `XMLHttpRequest`, `WebSocket`, `localStorage`, `document`, `window`, `eval`, `Function`, `Worker`, or dynamic `import()`.
+
+## 8th Wall AR
+
+For AR experiences on iOS devices (which lack native WebXR), the viewer supports 8th Wall (XR8) as an alternative AR runtime.
+
+```typescript
+import { loadXR8, isXR8Available, isNativeWebXRAvailable, ARPlacement } from 'storysplat-viewer';
+
+// Check available AR runtimes
+if (await isNativeWebXRAvailable()) {
+  // Use native WebXR (Android Chrome, Quest, etc.)
+} else {
+  // Load 8th Wall (iOS Safari, etc.)
+  await loadXR8();
+  if (isXR8Available()) {
+    // XR8 is ready
+  }
+}
+```
+
+| Export | Description |
+|--------|-------------|
+| `loadXR8()` | Loads the 8th Wall XR8 runtime. Returns a Promise. |
+| `isXR8Available()` | Checks synchronously whether 8th Wall is already loaded. |
+| `isNativeWebXRAvailable()` | Checks asynchronously whether the browser supports native WebXR AR. |
+| `ARPlacement` | AR placement controller for positioning scenes in real-world space. |
+
+The bundled 8th Wall engine is self-hosted and does not require an API key. Use `eighthWallBaseUrl` or a `data-8thwall-base` attribute to point at custom engine files, and keep `scale: 'absolute'` for ground detection.
+
 ## React Integration
 
 ```jsx
@@ -1456,9 +1564,25 @@ This data appears in your StorySplat admin dashboard.
 | `createViewer` (self-hosted scenes) | No | No |
 | iframe embed | Yes | Yes |
 
+### Manual Analytics Setup
+
+If you use `createViewer` (self-hosted) but still want StorySplat analytics, use `setupAnalyticsTracking`:
+
+```typescript
+import { createViewer, setupAnalyticsTracking } from 'storysplat-viewer';
+
+const viewer = createViewer(container, sceneData);
+const tracker = setupAnalyticsTracking(viewer, 'https://discover.storysplat.com', 'SCENE_ID', 'OWNER_UID');
+
+// Clean up when done
+tracker.destroy();
+```
+
+This enables view counting, bandwidth tracking, and session recording for self-hosted scenes.
+
 ### 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.
+Tracking only occurs for scenes loaded via `createViewerFromSceneId` (or when `setupAnalyticsTracking` is explicitly called). If you use `createViewer` without manual tracking setup, no data is sent to StorySplat servers.
 
 ### Comparison: Scene ID vs JSON File
 
@@ -1555,6 +1679,18 @@ import type {
   RevealPresetConfig,
 } from 'storysplat-viewer';
 
+// Analytics
+import { setupAnalyticsTracking } from 'storysplat-viewer';
+
+// Custom Scripts
+import { CustomScriptSystem, setupCustomScript } from 'storysplat-viewer';
+
+// 8th Wall AR
+import { loadXR8, isXR8Available, isNativeWebXRAvailable, ARPlacement } from 'storysplat-viewer';
+
+// 4DGS
+import { FrameSequencePlayer } from 'storysplat-viewer';
+
 // Utilities
 import {
   DEFAULT_BUTTON_LABELS,