storysplat-viewer 2.0.0 → 2.2.0

package/README.md

@@ -1,639 +1,427 @@
 # 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 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, and multiple camera modes.
 
 ## Table of Contents
 
-- [Overview](#overview)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Loading Scenes](#loading-scenes)
+  - [From Scene ID (Live-Linked)](#option-1-from-scene-id-live-linked)
+  - [From JSON File (Version-Controlled)](#option-2-from-json-file-version-controlled)
+  - [From URL](#option-3-from-url)
 - [API Reference](#api-reference)
 - [Configuration Options](#configuration-options)
-- [Examples](#examples)
-- [Events and Callbacks](#events-and-callbacks)
-- [Styling](#styling)
-- [Migration Guide](#migration-guide)
+- [Events](#events)
+- [React Integration](#react-integration)
 - [Troubleshooting](#troubleshooting)
 
-## Overview
-
-StorySplat Viewer is a TypeScript/JavaScript library that enables seamless integration of 3D Gaussian Splatting scenes into web applications. It provides:
-
-- 🎥 Multiple camera modes (orbit, free, first-person)
-- 🎯 Interactive hotspots with rich content
-- 🚶 Waypoint-based navigation system
-- 📱 Mobile-friendly touch controls
-- 🎨 Customizable UI and styling
-- 🔧 Comprehensive API for programmatic control
-- ⚡ Optimized performance with BabylonJS engine
-
 ## Installation
 
 ```bash
-npm install @storysplat/viewer
+npm install storysplat-viewer
 ```
 
 Or using yarn:
 
 ```bash
-yarn add @storysplat/viewer
+yarn add storysplat-viewer
 ```
 
 ## Quick Start
 
 ```javascript
-import { initializeViewer } from '@storysplat/viewer';
-import '@storysplat/viewer/dist/styles/viewer.css';
-
-// Initialize the viewer
-const viewerElement = document.getElementById('storysplat-viewer');
-const viewer = initializeViewer(viewerElement, {
-  splatUrl: 'https://example.com/scene.splat',
-  targetFps: 60,
-  fov: 60,
-  cameraMode: 'orbit'
-});
+import { createViewerFromSceneId } from 'storysplat-viewer';
+
+// Create a viewer from your StorySplat scene ID
+const viewer = await createViewerFromSceneId(
+  document.getElementById('viewer'),
+  'YOUR_SCENE_ID'
+);
 
-// Load additional splats
-await viewer.loadSplat('https://example.com/another.splat');
+// Control playback
+viewer.play();
+viewer.pause();
 
-// Switch camera mode
-viewer.setCameraMode('free');
+// Navigate between waypoints
+viewer.nextWaypoint();
+viewer.goToWaypoint(2);
+
+// Listen for events
+viewer.on('ready', () => console.log('Viewer ready!'));
 ```
 
-## API Reference
+## Loading Scenes
 
-### initializeViewer
+There are three ways to load scenes into the viewer:
 
-Creates and initializes a new StorySplat viewer instance.
+### Option 1: From Scene ID (Live-Linked)
 
-```typescript
-function initializeViewer(
-  element: HTMLElement,
-  data: StorySplatData,
-  options?: Partial<ViewerOptions>
-): ViewerInstance
+Best for: Live content that updates when you edit in the StorySplat editor.
+
+```javascript
+import { createViewerFromSceneId } from 'storysplat-viewer';
+
+// Scene ID from your StorySplat dashboard
+const viewer = await createViewerFromSceneId(
+  document.getElementById('viewer'),
+  'YOUR_SCENE_ID'
+);
 ```
 
-**Parameters:**
-- `element` (HTMLElement): The DOM element to render the viewer into
-- `data` (StorySplatData): Scene data including splat URL and configuration
-- `options` (Partial<ViewerOptions>): Optional viewer configuration
+The scene is fetched from the StorySplat API and always reflects your latest changes.
 
-**Returns:** ViewerInstance object for controlling the viewer
+**Getting your Scene ID:**
+1. Open your scene in the StorySplat editor
+2. Click "Upload" or "Update"
+3. Copy the Scene ID from the "Developer Export" section
 
-### ViewerInstance Interface
+### Option 2: From JSON File (Version-Controlled)
 
-The main interface for interacting with the viewer after initialization.
+Best for: Production apps where you want version control over scene data.
 
-```typescript
-interface ViewerInstance {
-  // Scene Management
-  loadSplat(url: string, options?: LoadOptions): Promise<void>;
-  clearScene(): void;
-  destroy(): void;
-  
-  // Camera Controls
-  setCameraMode(mode: 'orbit' | 'free' | 'firstPerson'): void;
-  getCameraMode(): string;
-  setCameraPosition(x: number, y: number, z: number): void;
-  getCameraPosition(): { x: number; y: number; z: number };
-  setCameraTarget(x: number, y: number, z: number): void;
-  getCameraTarget(): { x: number; y: number; z: number };
-  
-  // Navigation
-  navigateToWaypoint(waypointId: string): Promise<void>;
-  getWaypoints(): Waypoint[];
-  startWaypointTour(waypointIds?: string[]): void;
-  stopWaypointTour(): void;
-  
-  // Hotspots
-  getHotspots(): Hotspot[];
-  showHotspot(hotspotId: string): void;
-  hideHotspot(hotspotId: string): void;
-  updateHotspot(hotspotId: string, data: Partial<Hotspot>): void;
-  
-  // Rendering
-  setRenderingEnabled(enabled: boolean): void;
-  takeScreenshot(options?: ScreenshotOptions): Promise<Blob>;
-  
-  // Scene Properties
-  setBackgroundColor(color: string): void;
-  setSkybox(skyboxUrl: string): void;
-  setFog(enabled: boolean, density?: number): void;
-  
-  // Events
-  on(event: string, callback: Function): void;
-  off(event: string, callback: Function): void;
-}
+```javascript
+import { createViewer } from 'storysplat-viewer';
+import sceneConfig from './my-scene.json'; // Downloaded from editor
+
+const viewer = createViewer(
+  document.getElementById('viewer'),
+  sceneConfig
+);
 ```
 
-### Data Types
+**Downloading scene JSON:**
+1. Open your scene in the StorySplat editor
+2. Click "Export" or "Upload"
+3. In the "Developer Export" section, click "Download Scene JSON"
+4. Save the file in your project
 
-#### StorySplatData
+### Option 3: From URL
 
-```typescript
-interface StorySplatData {
-  splatUrl: string;
-  waypoints?: Waypoint[];
-  hotspots?: Hotspot[];
-  cameraSettings?: CameraSettings;
-  environmentSettings?: EnvironmentSettings;
-  meshes?: CustomMesh[];
-  particleSystems?: ParticleSystemConfig[];
-}
-```
+Load scene configuration from any URL:
 
-#### ViewerOptions
+```javascript
+import { createViewerFromUrl } from 'storysplat-viewer';
 
-```typescript
-interface ViewerOptions {
-  // Camera settings
-  cameraMode?: 'orbit' | 'free' | 'firstPerson';
-  fov?: number;
-  initialCameraPosition?: { x: number; y: number; z: number };
-  initialCameraTarget?: { x: number; y: number; z: number };
-  
-  // Rendering
-  targetFps?: number;
-  backgroundColor?: string;
-  skyboxUrl?: string;
-  
-  // UI Options
-  showToolbar?: boolean;
-  showMobileControls?: boolean;
-  showLoadingIndicator?: boolean;
-  watermarkText?: string;
-  
-  // Interaction
-  enableHotspots?: boolean;
-  enableWaypoints?: boolean;
-  enableCollisions?: boolean;
-  
-  // Callbacks
-  onReady?: () => void;
-  onError?: (error: Error) => void;
-  onProgress?: (progress: number) => void;
-  onHotspotClick?: (hotspot: Hotspot) => void;
-  onWaypointReached?: (waypoint: Waypoint) => void;
-}
+const viewer = await createViewerFromUrl(
+  document.getElementById('viewer'),
+  'https://example.com/my-scene.json'
+);
 ```
 
-#### Waypoint
+## API Reference
+
+### createViewerFromSceneId
+
+Create a viewer by fetching scene data from the StorySplat API.
 
 ```typescript
-interface Waypoint {
-  id: string;
-  name: string;
-  position: { x: number; y: number; z: number };
-  lookAt?: { x: number; y: number; z: number };
-  duration?: number; // Animation duration in ms
-  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
-}
+async function createViewerFromSceneId(
+  container: HTMLElement,
+  sceneId: string,
+  options?: ViewerFromSceneIdOptions
+): Promise<ViewerInstance>
 ```
 
-#### Hotspot
+**Parameters:**
+- `container` - HTML element to render the viewer into
+- `sceneId` - Your StorySplat scene ID
+- `options` - Optional viewer configuration
 
+**Options:**
 ```typescript
-interface Hotspot {
-  id: string;
-  position: { x: number; y: number; z: number };
-  type: 'info' | 'link' | 'media' | 'custom';
-  title?: string;
-  content?: string;
-  mediaUrl?: string;
-  linkUrl?: string;
-  icon?: string;
-  color?: string;
-  size?: number;
-  alwaysVisible?: boolean;
+interface ViewerFromSceneIdOptions {
+  // API configuration
+  baseUrl?: string;  // Default: 'https://discover.storysplat.com'
+  apiKey?: string;   // For private scenes (future feature)
+
+  // Viewer options
+  autoPlay?: boolean;
+  showUI?: boolean;
+  backgroundColor?: string;
+  revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
+  lazyLoad?: boolean;
+  lazyLoadThumbnail?: string;
+  lazyLoadButtonText?: string;
 }
 ```
 
-## Configuration Options
+### createViewer
 
-### Camera Settings
+Create a viewer from scene data object.
 
-```javascript
-const viewer = initializeViewer(element, {
-  splatUrl: 'scene.splat'
-}, {
-  cameraMode: 'orbit',        // 'orbit' | 'free' | 'firstPerson'
-  fov: 60,                    // Field of view in degrees
-  initialCameraPosition: { x: 0, y: 5, z: 10 },
-  initialCameraTarget: { x: 0, y: 0, z: 0 }
-});
+```typescript
+function createViewer(
+  container: HTMLElement,
+  scene: SceneData,
+  options?: ViewerOptions
+): ViewerInstance
 ```
 
-### Rendering Options
+### createViewerFromUrl
 
-```javascript
-const viewer = initializeViewer(element, data, {
-  targetFps: 60,              // Target frame rate
-  backgroundColor: '#000000',  // Background color
-  skyboxUrl: '/assets/skybox.dds',  // Optional skybox
-  showLoadingIndicator: true   // Show loading progress
-});
-```
+Create a viewer by fetching scene data from a URL.
 
-### UI Options
-
-```javascript
-const viewer = initializeViewer(element, data, {
-  showToolbar: true,          // Show control toolbar
-  showMobileControls: true,   // Auto-detect and show mobile controls
-  watermarkText: 'My Scene'   // Custom watermark
-});
+```typescript
+async function createViewerFromUrl(
+  container: HTMLElement,
+  url: string,
+  options?: ViewerOptions
+): Promise<ViewerInstance>
 ```
 
-## Examples
+### fetchSceneMeta
 
-### Basic Setup
+Fetch scene metadata without creating a viewer (useful for previews).
 
-```javascript
-import { initializeViewer } from '@storysplat/viewer';
-import '@storysplat/viewer/dist/styles/viewer.css';
-
-function setupViewer() {
-  const element = document.getElementById('storysplat-viewer');
-  
-  const viewer = initializeViewer(element, {
-    splatUrl: '/models/scene.splat'
-  }, {
-    onReady: () => console.log('Viewer ready!'),
-    onError: (error) => console.error('Viewer error:', error)
-  });
-  
-  return viewer;
-}
+```typescript
+async function fetchSceneMeta(
+  sceneId: string,
+  options?: { baseUrl?: string; apiKey?: string }
+): Promise<{
+  name: string;
+  description: string;
+  thumbnailUrl: string;
+  userName: string;
+  views: number;
+  tags: string[];
+  createdAt: string | null;
+}>
 ```
 
-### Camera Mode Switching
+### ViewerInstance
 
-```javascript
-// Create camera mode buttons
-const viewer = initializeViewer(element, { splatUrl: 'scene.splat' });
+The viewer instance returned by all create functions.
 
-document.getElementById('orbit-btn').onclick = () => {
-  viewer.setCameraMode('orbit');
-};
+```typescript
+interface ViewerInstance {
+  // PlayCanvas app reference
+  app: any;
+  canvas: HTMLCanvasElement;
 
-document.getElementById('free-btn').onclick = () => {
-  viewer.setCameraMode('free');
-};
+  // Navigation
+  goToWaypoint: (index: number) => void;
+  nextWaypoint: () => void;
+  prevWaypoint: () => void;
+  getCurrentWaypointIndex: () => number;
+  getWaypointCount: () => number;
+
+  // Camera
+  setPosition: (x: number, y: number, z: number) => void;
+  setRotation: (x: number, y: number, z: number) => void;
+  getPosition: () => { x: number; y: number; z: number };
+  getRotation: () => { x: number; y: number; z: number };
+
+  // Playback
+  play: () => void;
+  pause: () => void;
+  stop: () => void;
+  isPlaying: () => boolean;
+
+  // Lifecycle
+  destroy: () => void;
+  resize: () => void;
 
-document.getElementById('fps-btn').onclick = () => {
-  viewer.setCameraMode('firstPerson');
-};
+  // Events
+  on: (event: ViewerEvent, callback: (...args: any[]) => void) => void;
+  off: (event: ViewerEvent, callback: (...args: any[]) => void) => void;
+}
 ```
 
-### Waypoint Navigation
+## Configuration Options
 
-```javascript
-const viewer = initializeViewer(element, {
-  splatUrl: '/models/scene.splat',
-  waypoints: [
-    { id: 'entrance', name: 'Entrance', position: { x: 0, y: 0, z: 5 } },
-    { id: 'center', name: 'Center', position: { x: 0, y: 0, z: 0 } },
-    { id: 'exit', name: 'Exit', position: { x: 0, y: 0, z: -5 } }
-  ]
-});
+### ViewerOptions
 
-// Navigate to specific waypoint
-await viewer.navigateToWaypoint('center');
+```typescript
+interface ViewerOptions {
+  // Template style
+  template?: 'standard' | 'minimal' | 'pro';
 
-// Start automated tour
-viewer.startWaypointTour(['entrance', 'center', 'exit']);
-```
+  // Playback
+  autoPlay?: boolean;
 
-### Hotspot Interaction
+  // UI
+  showUI?: boolean;
+  backgroundColor?: string;
 
-```javascript
-const viewer = initializeViewer(element, {
-  splatUrl: 'scene.splat',
-  hotspots: [
-    {
-      id: 'info-1',
-      position: { x: 2, y: 1, z: 0 },
-      type: 'info',
-      title: 'Information',
-      content: 'This is an information hotspot'
-    }
-  ]
-}, {
-  onHotspotClick: (hotspot) => {
-    console.log('Hotspot clicked:', hotspot);
-    // Custom hotspot handling
-    if (hotspot.type === 'link') {
-      window.open(hotspot.linkUrl, '_blank');
-    }
-  }
-});
+  // Loading animation
+  revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
 
-// Add custom hotspot dynamically
-viewer.updateHotspot('custom-1', {
-  position: { x: -2, y: 1, z: 0 },
-  type: 'info',
-  title: 'Dynamic Hotspot',
-  content: 'Added at runtime',
-  color: '#ff0000'
-});
+  // Lazy loading
+  lazyLoad?: boolean;
+  lazyLoadThumbnail?: string;
+  lazyLoadButtonText?: string;
+}
 ```
 
-### Dynamic Splat Loading
+### Lazy Loading
+
+Show a thumbnail with a start button before loading the full viewer:
 
 ```javascript
-const viewer = initializeViewer(element, {
-  splatUrl: '/models/base.splat'
+const viewer = await createViewerFromSceneId(container, sceneId, {
+  lazyLoad: true,
+  lazyLoadThumbnail: '/preview.jpg',  // Optional custom thumbnail
+  lazyLoadButtonText: 'Start Tour'    // Default: "Start Experience"
 });
-
-// Load additional splats
-async function loadScenes() {
-  await viewer.loadSplat('/models/building.splat');
-  await viewer.loadSplat('/models/furniture.splat', {
-    position: { x: 0, y: 0, z: 0 },
-    scale: 1.5,
-    rotation: { x: 0, y: 90, z: 0 }
-  });
-}
-
-// Clear and load new scene
-async function switchScene() {
-  viewer.clearScene();
-  await viewer.loadSplat('/models/new-scene.splat');
-}
 ```
 
-### Custom UI Integration
+### Reveal Effects
+
+Control how the splat appears when loaded:
 
 ```javascript
-const viewer = initializeViewer(element, data, {
-  showToolbar: false  // Hide default toolbar
+const viewer = createViewer(container, sceneData, {
+  revealEffect: 'medium'  // 'fast' | 'medium' | 'slow' | 'none'
 });
-
-// Create custom controls
-const customUI = {
-  updateCameraInfo() {
-    const pos = viewer.getCameraPosition();
-    document.getElementById('camera-info').textContent = 
-      `Camera: ${pos.x.toFixed(2)}, ${pos.y.toFixed(2)}, ${pos.z.toFixed(2)}`;
-  },
-  
-  takePhoto() {
-    viewer.takeScreenshot({ width: 1920, height: 1080 })
-      .then(blob => {
-        const url = URL.createObjectURL(blob);
-        window.open(url, '_blank');
-      });
-  }
-};
-
-// Update camera info on render
-viewer.on('render', customUI.updateCameraInfo);
 ```
 
-## Events and Callbacks
-
-### Available Events
+## Events
 
 ```javascript
+// Viewer is ready
 viewer.on('ready', () => {
-  console.log('Viewer initialized and ready');
+  console.log('Viewer initialized');
 });
 
-viewer.on('loadStart', (url) => {
-  console.log('Started loading:', url);
+// Scene loaded
+viewer.on('loaded', () => {
+  console.log('Scene fully loaded');
 });
 
-viewer.on('loadProgress', (progress) => {
-  console.log('Loading progress:', progress + '%');
+// Loading progress
+viewer.on('progress', ({ loaded, total, percent }) => {
+  console.log(`Loading: ${percent}%`);
 });
 
-viewer.on('loadComplete', () => {
-  console.log('Loading complete');
+// Waypoint changed
+viewer.on('waypointChange', ({ index, waypoint }) => {
+  console.log(`Now at waypoint ${index}: ${waypoint.name}`);
 });
 
+// Playback state
+viewer.on('playbackStart', () => console.log('Playing'));
+viewer.on('playbackStop', () => console.log('Stopped'));
+
+// Errors
 viewer.on('error', (error) => {
   console.error('Viewer error:', error);
 });
-
-viewer.on('cameraMove', (position) => {
-  console.log('Camera moved to:', position);
-});
-
-viewer.on('hotspotClick', (hotspot) => {
-  console.log('Hotspot clicked:', hotspot);
-});
-
-viewer.on('waypointReached', (waypoint) => {
-  console.log('Reached waypoint:', waypoint);
-});
-
-viewer.on('render', (deltaTime) => {
-  // Called every frame
-});
 ```
 
-### Removing Event Listeners
+## React Integration
 
-```javascript
-const handler = (position) => console.log(position);
-viewer.on('cameraMove', handler);
-
-// Later...
-viewer.off('cameraMove', handler);
-```
+```jsx
+import { useEffect, useRef } from 'react';
+import { createViewerFromSceneId } from 'storysplat-viewer';
 
-## Styling
+function StorySplatViewer({ sceneId }) {
+  const containerRef = useRef(null);
+  const viewerRef = useRef(null);
 
-### CSS Variables
+  useEffect(() => {
+    let mounted = true;
 
-The viewer uses CSS variables for theming:
+    async function initViewer() {
+      if (!containerRef.current) return;
 
-```css
-#storysplat-viewer {
-  --storysplat-primary-color: #007bff;
-  --storysplat-background-color: #000000;
-  --storysplat-text-color: #ffffff;
-  --storysplat-toolbar-bg: rgba(0, 0, 0, 0.8);
-  --storysplat-button-hover: #0056b3;
-  --storysplat-hotspot-color: #ffc107;
-}
-```
+      try {
+        const viewer = await createViewerFromSceneId(
+          containerRef.current,
+          sceneId
+        );
 
-### Custom Styling
+        if (mounted) {
+          viewerRef.current = viewer;
+        } else {
+          viewer.destroy();
+        }
+      } catch (error) {
+        console.error('Failed to create viewer:', error);
+      }
+    }
 
-```css
-/* Override toolbar styles */
-.storysplat-toolbar {
-  background: linear-gradient(to bottom, rgba(0,0,0,0.9), rgba(0,0,0,0.7));
-  border-radius: 8px;
-  margin: 10px;
-}
+    initViewer();
 
-/* Custom hotspot appearance */
-.storysplat-hotspot {
-  animation: pulse 2s infinite;
-}
+    return () => {
+      mounted = false;
+      viewerRef.current?.destroy();
+    };
+  }, [sceneId]);
 
-@keyframes pulse {
-  0% { transform: scale(1); }
-  50% { transform: scale(1.1); }
-  100% { transform: scale(1); }
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', height: '500px' }}
+    />
+  );
 }
 
-/* Mobile controls */
-.storysplat-mobile-controls {
-  opacity: 0.8;
-}
+export default StorySplatViewer;
 ```
 
-### Required CSS
+## Error Handling
 
-Make sure to import the viewer CSS:
+The package exports error classes for specific error handling:
 
 ```javascript
-import '@storysplat/viewer/dist/styles/viewer.css';
+import {
+  createViewerFromSceneId,
+  SceneNotFoundError,
+  SceneApiError
+} from 'storysplat-viewer';
+
+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);
+  }
+}
 ```
 
-Or include it in your HTML:
+## Comparison: Scene ID vs JSON File
 
-```html
-<link rel="stylesheet" href="node_modules/@storysplat/viewer/dist/styles/viewer.css">
-```
-
-## Migration Guide
-
-### From Exported HTML to NPM Package
-
-If you're migrating from StorySplat's exported HTML files to the npm package:
-
-1. **Extract Scene Data**
-   ```javascript
-   // From your exported HTML's scene configuration
-   const sceneData = {
-     splatUrl: 'path/to/your.splat',
-     waypoints: [...],  // Copy waypoints array
-     hotspots: [...],   // Copy hotspots array
-     cameraSettings: {
-       position: { x: 0, y: 5, z: 10 },
-       target: { x: 0, y: 0, z: 0 }
-     }
-   };
-   ```
-
-2. **Initialize Viewer**
-   ```javascript
-   const element = document.getElementById('viewer-container');
-   const viewer = initializeViewer(element, sceneData, {
-     // Match your export settings
-     backgroundColor: '#000000',
-     targetFps: 60,
-     cameraMode: 'orbit'
-   });
-   ```
-
-3. **Update Event Handlers**
-   ```javascript
-   // Old: onclick handlers in HTML
-   // New: Event listeners
-   viewer.on('hotspotClick', handleHotspotClick);
-   viewer.on('waypointReached', handleWaypointReached);
-   ```
-
-4. **Handle Assets**
-   ```javascript
-   // Ensure all assets use absolute URLs or are properly bundled
-   const sceneData = {
-     splatUrl: '/assets/scene.splat',
-     skyboxUrl: '/assets/skybox.dds'
-   };
-   ```
+| Approach | Best For | Pros | Cons |
+|----------|----------|------|------|
+| **Scene ID** | Live content, CMS | Always latest, no redeploy | Needs internet, API dependency |
+| **JSON File** | Version control, offline | Full control, git-tracked | Manual updates needed |
 
 ## Troubleshooting
 
-### Common Issues
+### Container Needs Dimensions
 
-#### Viewer Not Rendering
+The container element must have explicit dimensions:
 
-```javascript
-// Check container exists and has dimensions
-const container = document.getElementById('storysplat-viewer');
-if (!container) {
-  console.error('Container element not found');
-}
-
-// Ensure container has explicit dimensions
-#storysplat-viewer {
+```css
+#viewer {
   width: 100%;
   height: 500px; /* Must have explicit height */
 }
 ```
 
-#### CORS Errors
-
-```javascript
-// For cross-origin splat files, ensure proper CORS headers
-// Or use a proxy:
-const viewer = initializeViewer(element, {
-  splatUrl: '/api/proxy?url=' + encodeURIComponent(splatUrl)
-});
-```
-
-#### Performance Issues
-
-```javascript
-// Reduce target FPS for better performance
-const viewer = initializeViewer(element, data, {
-  targetFps: 30,  // Lower FPS
-  // Disable expensive features
-  skyboxUrl: null,
-  showLoadingIndicator: false
-});
-
-// Optimize rendering
-viewer.setRenderingEnabled(false); // Pause when not visible
-```
-
-#### Mobile Touch Controls Not Working
+### CORS Issues
 
-```javascript
-// Ensure mobile controls are enabled
-const viewer = initializeViewer(element, data, {
-  showMobileControls: true,
-  // Force mobile controls for testing
-  forceMobileControls: true
-});
+If loading splats from a different domain, ensure the server has proper CORS headers or use a proxy.
 
-// Check viewport meta tag
-<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
-```
+### Memory Cleanup
 
-#### Memory Leaks
+Always destroy the viewer when unmounting:
 
 ```javascript
-// Always cleanup when done
+// Vanilla JS
 window.addEventListener('beforeunload', () => {
   viewer.destroy();
 });
 
-// In React/Vue/Angular components
-componentWillUnmount() {
-  if (this.viewer) {
-    this.viewer.destroy();
-  }
-}
-```
-
-### Debug Mode
-
-Enable debug logging:
-
-```javascript
-const viewer = initializeViewer(element, data, {
-  debug: true,  // Enable debug logging
-  onDebug: (message) => console.log('[Debug]', message)
-});
+// React useEffect cleanup
+return () => {
+  viewer?.destroy();
+};
 ```
 
 ### Browser Compatibility
@@ -641,19 +429,13 @@ const viewer = initializeViewer(element, data, {
 StorySplat Viewer requires:
 - WebGL 2.0 support
 - Modern JavaScript (ES2015+)
-- Recommended browsers:
-  - Chrome 80+
-  - Firefox 75+
-  - Safari 13+
-  - Edge 80+
+- Recommended browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
 
-### Support
+## Support
 
-For issues, feature requests, or questions:
-- GitHub Issues: [github.com/storysplat/viewer/issues](https://github.com/storysplat/viewer/issues)
+- GitHub Issues: [github.com/SonnyC56/storysplat-viewer/issues](https://github.com/SonnyC56/storysplat-viewer/issues)
 - Documentation: [docs.storysplat.com](https://docs.storysplat.com)
-- Discord: [discord.gg/storysplat](https://discord.gg/storysplat)
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT License - see LICENSE file for details