storysplat-viewer 2.7.18 → 2.9.0

package/README.md

@@ -13,6 +13,8 @@ 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)
+- [Viewer Theme Customization](#viewer-theme-customization)
+- [Splat Relighting](#splat-relighting)
 - [Internationalization (i18n)](#internationalization-i18n)
 - [Events](#events)
 - [React Integration](#react-integration)
@@ -129,7 +131,11 @@ When using `createViewer()` with self-hosted JSON, the scene data should match t
 | `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.
 
@@ -164,6 +170,7 @@ interface ViewerFromSceneIdOptions {
   showUI?: boolean;
   backgroundColor?: string;
   revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
+  revealStyle?: 'bloom' | 'radial';
   lazyLoad?: boolean;
   lazyLoadThumbnail?: string;
   lazyLoadButtonText?: string;
@@ -290,6 +297,7 @@ interface ViewerOptions {
 
   // Loading animation
   revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
+  revealStyle?: 'bloom' | 'radial';  // 'bloom' = burst with overshoot, 'radial' = classic dot wave
 
   // Lazy loading
   lazyLoad?: boolean;
@@ -317,10 +325,85 @@ Control how the splat appears when loaded:
 
 ```javascript
 const viewer = createViewer(container, sceneData, {
-  revealEffect: 'medium'  // 'fast' | 'medium' | 'slow' | 'none'
+  revealEffect: 'medium',  // 'fast' | 'medium' | 'slow' | 'none'
+  revealStyle: 'bloom'     // 'bloom' (burst with overshoot) | 'radial' (classic dot wave)
 });
 ```
 
+## 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.
+
+### Setting a Theme via Scene Data
+
+```javascript
+const sceneData = await fetch('/scene.json').then(r => r.json());
+
+sceneData.uiOptions = {
+  ...sceneData.uiOptions,
+  viewerTheme: {
+    buttonBg: 'rgba(20, 20, 40, 0.9)',
+    buttonTextColor: '#e0e0ff',
+    popupBg: 'rgba(10, 10, 30, 0.95)',
+    popupTextColor: '#ffffff',
+    preloaderBg: '#0a0a1e',
+    joystickBaseColor: 'rgba(100, 100, 255, 0.3)',
+    joystickThumbColor: 'rgba(150, 150, 255, 0.6)',
+    buttonBorderRadius: '12px',
+    buttonFontSize: '13px',
+    fontFamily: '"Inter", sans-serif',
+  }
+};
+
+const viewer = createViewer(container, sceneData);
+```
+
+### Available Theme Properties
+
+| 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` |
+| **Border Radii** (6) | `buttonBorderRadius`, `popupBorderRadius`, `dropdownBorderRadius`, `helpPanelBorderRadius`, `errorPopupBorderRadius`, `lazyLoadBtnBorderRadius` |
+| **Other** (3) | `dropdownBlur`, `progressBarHeight`, `preloaderBarHeight` |
+
+All properties are optional — unspecified values fall back to built-in defaults.
+
+### Generating Styles Programmatically
+
+```javascript
+import { generateViewerStyles } from 'storysplat-viewer';
+
+const css = generateViewerStyles({
+  buttonBg: 'rgba(0, 0, 0, 0.8)',
+  buttonTextColor: '#fff',
+});
+
+// Inject into your page
+const style = document.createElement('style');
+style.textContent = css;
+document.head.appendChild(style);
+```
+
+## Splat Relighting
+
+Scene lights can dynamically illuminate Gaussian Splats for dramatic lighting effects. Configure relighting in scene data:
+
+```javascript
+const sceneData = {
+  // ... other scene config ...
+  splatRelighting: {
+    enabled: true,
+    ambientColor: '#ffffff',      // Ambient light color for unlit areas
+    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
+  }
+};
+```
+
+When `allowViewerToggle` is `true`, end users see a toggle button in the viewer to switch relighting on/off.
+
 ## Internationalization (i18n)
 
 All user-facing UI text can be customized via `ButtonLabels`. This enables full translation or label renaming.
@@ -401,6 +484,22 @@ viewer.setButtonLabels({ next: 'Suivant', previous: 'Pr\u00e9c\u00e9dent' });
 | `helpTourDesc` | `"Follow predefined path"` | Help tour description |
 | `helpExploreDesc` | `"Free movement"` | Help explore description |
 | `helpWalkDesc` | `"First-person walking"` | Help walk description |
+| `helpTourControls` | `"Controls:"` | Help panel - tour controls heading |
+| `helpTourScroll` | `"Scroll to navigate"` | Help panel - tour scroll instruction |
+| `helpTourDrag` | `"Drag to look around"` | Help panel - tour drag instruction |
+| `helpExploreControls` | `"Controls:"` | Help panel - explore controls heading |
+| `helpExploreLMB` | `"Left click + drag to orbit"` | Help panel - explore LMB |
+| `helpExploreRMB` | `"Right click + drag to pan"` | Help panel - explore RMB |
+| `helpExploreWASD` | `"WASD to move"` | Help panel - explore WASD |
+| `helpExploreShift` | `"Shift to speed up"` | Help panel - explore shift |
+| `helpExploreScroll` | `"Scroll to zoom"` | Help panel - explore scroll |
+| `helpExploreDblClick` | `"Double-click to auto-move"` | Help panel - explore double-click |
+| `helpWalkControls` | `"Controls:"` | Help panel - walk controls heading |
+| `helpWalkClick` | `"Click to start"` | Help panel - walk click |
+| `helpWalkWASD` | `"WASD to walk"` | Help panel - walk WASD |
+| `helpWalkMouse` | `"Mouse to look"` | Help panel - walk mouse |
+| `helpWalkShift` | `"Shift to run"` | Help panel - walk shift |
+| `helpWalkSpace` | `"Space to jump"` | Help panel - walk space |
 | `errorWebGLTitle` | `"Unable to Initialize 3D Graphics"` | WebGL error heading |
 | `errorWebGLMessage` | `"Your browser or device..."` | WebGL error body |
 | `percentageFormat` | `"{n}%"` | Progress percentage format |
@@ -1085,6 +1184,46 @@ loadScene('campervan');
 
 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 {
+  createViewer,
+  createViewerFromSceneId,
+  createViewerFromUrl,
+  fetchSceneMeta,
+  generateHTML,
+  generateHTMLFromUrl,
+} from 'storysplat-viewer';
+
+// Types
+import type {
+  ViewerInstance,
+  ViewerOptions,
+  SceneData,
+  ButtonLabels,
+  ViewerTheme,
+  SplatRelightingConfig,
+  RevealPreset,
+  RevealPresetConfig,
+} from 'storysplat-viewer';
+
+// Utilities
+import {
+  DEFAULT_BUTTON_LABELS,
+  generateViewerStyles,
+  REVEAL_PRESETS,
+  getRevealPreset,
+  GsplatRelighting,
+  getGsplatRelightingClass,
+  SceneNotFoundError,
+  SceneApiError,
+} from 'storysplat-viewer';
+```
+
 ## Support
 
 - GitHub Issues: [github.com/SonnyC56/storysplat-viewer/issues](https://github.com/SonnyC56/storysplat-viewer/issues)