@preference-sl/pref-viewer 2.16.0-beta.1 → 2.16.0-beta.11

package/LICENSE.md

@@ -0,0 +1,13 @@
+# Proprietary License
+
+Copyright © 2026 Preference S.L.
+All rights reserved.
+
+This software and its associated documentation are proprietary to Preference S.L.
+The package is made available to authorized customers and partners only for use under the applicable commercial agreement, subscription, order form, statement of work, or other written agreement with Preference S.L.
+
+Unless expressly permitted by Preference S.L. in writing, you may not copy, modify, sublicense, redistribute, resell, publish, reverse engineer, or make this software available to third parties.
+
+No open-source license is granted by this package. In particular, publication to npm does not grant permission to use the software outside the rights expressly provided by Preference S.L.
+
+For licensing questions, contact Preference S.L.

package/README.md

@@ -0,0 +1,486 @@
+# @preference-sl/pref-viewer
+
+`@preference-sl/pref-viewer` is a framework-agnostic Web Component for embedding an interactive 2D/3D product viewer in web applications. It renders glTF/GLB models with Babylon.js, supports SVG drawings, localized UI controls, runtime render settings, asset caching, and export flows for GLB, glTF ZIP, and USDZ.
+
+## Features
+
+- Native custom elements: `<pref-viewer>`, `<pref-viewer-2d>`, `<pref-viewer-3d>`, `<pref-viewer-dialog>`, and `<pref-viewer-menu-3d>`.
+- Babylon.js-based 3D visualization for glTF and GLB assets.
+- 2D SVG drawing support with pan and zoom controls.
+- Unified `<pref-viewer>` wrapper that coordinates 2D, 3D, menu, dialog, localization, and loading lifecycle.
+- Sequential task queue for deterministic config, model, scene, materials, drawing, options, and culture updates.
+- Direct URL, base64/data URI, and IndexedDB-backed asset loading.
+- File cache validation using size and timestamp metadata.
+- Runtime render settings for anti-aliasing, ambient occlusion, IBL, shadows, lighting time of day, and hover highlight.
+- Localized UI copy for `en-EN` and `es-ES`.
+- Export helpers for model, scene, or combined model + scene downloads.
+- Type declarations for TypeScript and JSX usage.
+
+## Installation
+
+```bash
+npm install @preference-sl/pref-viewer
+```
+
+## Basic usage
+
+Import the package once in your application entry point. The import registers the custom elements globally.
+
+```js
+import "@preference-sl/pref-viewer";
+```
+
+Then use the element in HTML:
+
+```html
+<pref-viewer
+  style="display: block; width: 100%; height: 600px;"
+  mode="3d"
+  culture="en-EN"
+  config='{
+    "model": {
+      "storage": {
+        "url": "https://example.com/assets/model.glb"
+      },
+      "visible": true
+    },
+    "scene": {
+      "storage": {
+        "url": "https://example.com/assets/scene.gltf"
+      },
+      "visible": true
+    }
+  }'
+></pref-viewer>
+```
+
+## JavaScript API usage
+
+You can configure the viewer declaratively with attributes or imperatively with JavaScript. Prefer the JavaScript API when passing large objects, dynamic values, or user-driven updates.
+
+```js
+const viewer = document.querySelector("pref-viewer");
+
+viewer.loadConfig({
+  model: {
+    storage: {
+      url: "https://example.com/assets/model.glb",
+    },
+    visible: true,
+  },
+  scene: {
+    storage: {
+      url: "https://example.com/assets/scene.gltf",
+    },
+    visible: true,
+  },
+  culture: "en-EN",
+});
+
+viewer.setOptions({
+  camera: "MainCamera",
+  ibl: {
+    url: "https://example.com/assets/environment.hdr",
+    intensity: 1,
+    shadows: true,
+  },
+  lighting: {
+    timeOfDay: 0.5,
+  },
+});
+```
+
+## Configuration model
+
+The main `config` payload can include model, scene, materials, drawing, options, and culture data.
+
+```js
+viewer.loadConfig({
+  model: {
+    storage: {
+      url: "https://example.com/model.glb",
+    },
+    visible: true,
+  },
+  scene: {
+    storage: {
+      url: "https://example.com/scene.gltf",
+    },
+    visible: true,
+  },
+  materials: {
+    storage: {
+      url: "https://example.com/materials.glb",
+    },
+  },
+  drawing: {
+    storage: {
+      url: "https://example.com/drawing.svg",
+    },
+  },
+  options: {
+    camera: "MainCamera",
+    ibl: {
+      url: "https://example.com/environment.hdr",
+      intensity: 1,
+      shadows: true,
+    },
+    render: {
+      ambientOcclusionEnabled: true,
+      antiAliasingEnabled: true,
+      iblEnabled: true,
+      shadowsEnabled: false,
+      showAnimationMenu: true,
+      showLightingTimeOfDay: true,
+      lightingTimeOfDay: 0.5,
+      highlightEnabled: true,
+      highlightColor: "#ff6700",
+    },
+  },
+  styles: {
+    colorPrimary: "#ff6700",
+  },
+  culture: "en-EN",
+  forceReload: false,
+});
+```
+
+## Asset storage descriptors
+
+Storage descriptors are passed through `model.storage`, `scene.storage`, `materials.storage`, or `drawing.storage`.
+
+### Remote URL
+
+```js
+{
+  storage: {
+    url: "https://example.com/assets/model.glb"
+  }
+}
+```
+
+### IndexedDB-backed asset
+
+```js
+{
+  storage: {
+    db: "PrefConfiguratorDB",
+    table: "gltfModels",
+    id: "product-model-id",
+    url: "https://example.com/assets/fallback-model.glb"
+  }
+}
+```
+
+### Base64 or data URI
+
+```js
+{
+  storage: {
+    url: "data:model/gltf-binary;base64,BASE64_CONTENT"
+  }
+}
+```
+
+## Attributes
+
+`<pref-viewer>` observes the following attributes directly. When they change, the host component queues the corresponding load/configuration action or updates its own UI state.
+
+| Attribute | Description |
+| --- | --- |
+| `config` | JSON string with the full viewer configuration. Forwards to `loadConfig(value)`. |
+| `model` | JSON string with a model payload. Forwards to `loadModel(value)`. |
+| `scene` | JSON string with a scene/environment payload. Forwards to `loadScene(value)`. |
+| `materials` | JSON string with a materials payload. Forwards to `loadMaterials(value)`. |
+| `drawing` | JSON string with a 2D drawing payload. Forwards to `loadDrawing(value)`. |
+| `options` | JSON string with viewer options. Forwards to `setOptions(value)`. Use this for runtime render changes such as highlight, animation menu, IBL, shadows, and lighting time of day. |
+| `culture` | UI locale. Supported values: `en-EN`, `es-ES`. Persists the resolved locale in `localStorage`. |
+| `mode` | Viewer mode: `3d` or `2d`. Defaults to `3d`. |
+| `show-model` | Shows or hides the current 3D model. Use `true` or `false`. |
+| `show-scene` | Shows or hides the current 3D scene/environment. Use `true` or `false`. |
+| `show-render-menu` | Shows or hides the floating 3D render settings menu. Defaults to visible. |
+| `styles` | JSON string with supported style overrides. Currently supports `colorPrimary`, applies it as `--pref-viewer-color-primary`, updates `PrefViewerStyleVariables.colorPrimary`, and persists it in `localStorage`. |
+
+## Public methods
+
+### Loading and configuration
+
+| Method | Description |
+| --- | --- |
+| `loadConfig(config)` | Queues a full configuration update. Accepts an object or JSON string with model, scene, materials, drawing, options, culture, styles, and visibility descriptors. |
+| `loadModel(model)` | Queues a model update. |
+| `loadScene(scene)` | Queues a scene/environment update. |
+| `loadMaterials(materials)` | Queues a materials update. |
+| `loadDrawing(drawing)` | Queues a 2D drawing update. |
+| `setOptions(options)` | Queues camera, material, IBL, lighting, animation-menu, highlight, and render option updates. |
+| `setStyles(styles)` | Queues supported runtime style overrides. Currently supports `{ colorPrimary }`, persists it in `localStorage`, updates `PrefViewerStyleVariables.colorPrimary`, and applies `--pref-viewer-color-primary`. |
+| `setIBL(ibl)` | Convenience wrapper for `setOptions({ ibl })`. |
+| `setCulture(culture)` | Changes the active UI locale and persists it in `localStorage`. |
+| `setMode(mode)` | Switches between `2d` and `3d`. |
+| `getDebugInfo()` | Returns a 3D runtime diagnostic snapshot when the internal 3D component and controller are available. |
+
+### Visibility and navigation
+
+| Method | Description |
+| --- | --- |
+| `showModel()` / `hideModel()` | Shows or hides the loaded model. |
+| `showScene()` / `hideScene()` | Shows or hides the loaded scene/environment. |
+| `syncVisibility(name, isVisible)` | Synchronizes `model` or `scene` visibility with the corresponding reflected attribute. |
+| `zoomCenter()` | Centers the 2D drawing view. |
+| `zoomExtentsAll()` | Fits all 2D drawing content in view. |
+| `zoomIn()` / `zoomOut()` | Controls 2D drawing zoom. |
+| `focusModel()` | Moves focus to the current model interaction target when available. |
+
+### Semantic selection and turnable state
+
+| Method | Description |
+| --- | --- |
+| `setSelectableElements(elements)` | Defines which host element ids are selectable. Accepts strings or objects with `id`/`Id`. |
+| `setSelectedElements(elements)` | Defines selected elements. Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
+| `applySelectionState(state)` | Applies selectable and selected state in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`. |
+| `clearSelectedElements()` | Clears selected elements while preserving the selectable set. |
+| `clearSelectableElements()` | Clears selectable elements while preserving the selected set. |
+| `clearSelectionState()` | Clears all semantic selection state. |
+| `getSelectionState()` | Returns `{ selectableIds, selectedIds, selectedItems }`. |
+| `notifyElementClick(element)` | Emits `pref-viewer-element-click` from a host-forwarded element id or detail object. |
+| `startTurnable(options)` | Starts semantic turnable state and emits `pref-viewer-3d-turnable-changed`. |
+| `stopTurnable()` | Stops semantic turnable state. |
+| `toggleTurnable(options)` | Toggles semantic turnable state. |
+| `getTurnableState()` | Returns `{ running, speed, direction }`. |
+
+### Animation controls
+
+| Method | Description |
+| --- | --- |
+| `getAnimations()` | Returns available model animations with state, progress, loop, and affected node ids. |
+| `playAnimation(name, action)` | Controls a named animation. Supported actions are delegated to `BabylonJSAnimationController`. |
+| `setAnimationProgress(name, progress)` | Sets animation progress from `0` to `1`. |
+| `setAnimationLoop(name, loop)` | Enables or disables looping for a named animation. |
+
+### Dialogs and downloads
+
+| Method | Description |
+| --- | --- |
+| `openDialog(title, content, footer)` | Opens a viewer dialog. |
+| `closeDialog()` | Closes the active viewer dialog. |
+| `downloadModelGLB()` / `downloadModelGLTF()` / `downloadModelUSDZ()` | Exports the current model. |
+| `downloadSceneGLB()` / `downloadSceneGLTF()` / `downloadSceneUSDZ()` | Exports the current scene/environment. |
+| `downloadModelAndSceneGLB()` / `downloadModelAndSceneGLTF()` / `downloadModelAndSceneUSDZ()` | Exports the combined model and scene. |
+
+## Public properties
+
+### Setters
+
+These setters are convenience bridges for framework bindings and property-based integration.
+
+| Property | Description |
+| --- | --- |
+| `config` | Forwards to `loadConfig(value)`. |
+| `model` | Forwards to `loadModel(value)`. |
+| `scene` | Forwards to `loadScene(value)`. |
+| `materials` | Forwards to `loadMaterials(value)`. |
+| `drawing` | Forwards to `loadDrawing(value)`. |
+| `options` | Forwards to `setOptions(value)`. |
+| `styles` | Forwards to `setStyles(value)`. |
+| `culture` | Forwards to `setCulture(value)`. |
+| `mode` | Forwards to `setMode(value)`. |
+
+### Getters
+
+| Property | Description |
+| --- | --- |
+| `culture` | Current resolved locale. |
+| `isInitialized` | Whether the root viewer has completed initialization. |
+| `isLoaded` | Whether the root viewer considers the current load complete. |
+| `isLoading` | Whether a load operation is currently in progress. |
+| `isMode2D` | `true` when the current mode is `2d`. |
+| `isMode3D` | `true` when the current mode is `3d`. |
+
+## Events
+
+The component emits custom events so host applications can integrate loading indicators, error states, and viewer controls. Public event payloads do not include `source`. Only root-level events without an explicit 2D/3D scope include `detail.mode`, and that value is always the current `<pref-viewer>` mode (`"2d"` or `"3d"`).
+
+### General Events
+
+| Event | Emitted by | Legacy alias | Description |
+| --- | --- | --- | --- |
+| `pref-viewer-initialized` | `<pref-viewer>` | None | The root component has been mounted and initialized. |
+| `pref-viewer-loading` | `<pref-viewer>` | None | A 2D or 3D load operation has started. Includes `detail.mode` with the current root mode. |
+| `pref-viewer-loaded` | `<pref-viewer>` | None | A 2D or 3D load operation completed. Includes `detail.mode` with the current root mode. |
+| `pref-viewer-error` | `<pref-viewer>` | None | A 2D or 3D operation failed. Includes `detail.mode` with the current root mode. |
+| `pref-viewer-selection-state-changed` | `<pref-viewer>` | None | The semantic selection state changed. |
+| `pref-viewer-element-click` | `<pref-viewer>` | None | A selectable element was clicked or forwarded by the host integration. |
+
+### 3D Events
+
+| Event | Emitted by | Legacy alias | Description |
+| --- | --- | --- | --- |
+| `pref-viewer-3d-loading` | `<pref-viewer>`, `<pref-viewer-3d>` | `scene-loading` | A 3D scene/model/material/options operation has started. |
+| `pref-viewer-3d-loaded` | `<pref-viewer>`, `<pref-viewer-3d>` | `scene-loaded` | A 3D scene/model/material/options operation completed. Includes operation details when available. |
+| `pref-viewer-3d-error` | `<pref-viewer>` | `scene-error` | A 3D operation failed. |
+| `pref-viewer-3d-options-applying` | `<pref-viewer-3d>` | `scene-setting-options` | 3D viewer options are being applied. |
+| `pref-viewer-3d-options-applied` | `<pref-viewer-3d>` | `scene-set-options` | 3D viewer options were applied. |
+| `pref-viewer-3d-render-settings-change-requested` | `<pref-viewer-menu-3d>` | None | The 3D settings menu requested render-setting changes. |
+| `pref-viewer-3d-animation-changed` | Opening animation controller | None | A model animation state changed. |
+| `pref-viewer-3d-turnable-changed` | `<pref-viewer>` | None | The semantic turnable state changed. |
+
+### 2D Events
+
+| Event | Emitted by | Legacy alias | Description |
+| --- | --- | --- | --- |
+| `pref-viewer-2d-loading` | `<pref-viewer>`, `<pref-viewer-2d>` | `drawing-loading` | A 2D drawing load started. |
+| `pref-viewer-2d-loaded` | `<pref-viewer>`, `<pref-viewer-2d>` | `drawing-loaded` | A 2D drawing load completed. |
+| `pref-viewer-2d-error` | `<pref-viewer>`, `<pref-viewer-2d>` | `drawing-error` | A 2D drawing operation failed. |
+| `pref-viewer-2d-viewport-changed` | `<pref-viewer>`, `<pref-viewer-2d>` | None | The 2D drawing pan/zoom viewport changed. |
+
+### Internal Listeners
+
+`<pref-viewer>` listens to `pref-viewer-2d-viewport-changed` from `<pref-viewer-2d>`, `pref-viewer-3d-loaded` and `pref-viewer-3d-error` from `<pref-viewer-3d>`, and `pref-viewer-3d-render-settings-change-requested` from `<pref-viewer-menu-3d>`. `BabylonJSController` listens to `pref-viewer-3d-animation-changed` from the nearest `<pref-viewer-3d>` host.
+
+Example:
+
+```js
+const viewer = document.querySelector("pref-viewer");
+
+viewer.addEventListener("pref-viewer-3d-loaded", (event) => {
+  console.log("Viewer 3D loaded", event.detail);
+});
+
+viewer.addEventListener("pref-viewer-3d-error", (event) => {
+  console.error("Viewer 3D failed", event.detail);
+});
+```
+
+## Render settings
+
+Render settings can be passed through `setOptions`, `loadConfig({ options: { render } })`, property setters, or the built-in 3D menu.
+
+```js
+viewer.setOptions({
+  render: {
+    antiAliasingEnabled: true,
+    ambientOcclusionEnabled: true,
+    iblEnabled: true,
+    shadowsEnabled: false,
+    showAnimationMenu: true,
+    highlightEnabled: true,
+    highlightColor: "#ff6700",
+    showLightingTimeOfDay: true,
+    lightingTimeOfDay: 0.5,
+  },
+});
+```
+
+| Setting | Type | Behavior |
+| --- | --- | --- |
+| `antiAliasingEnabled` | `boolean` | Enables/disables antialiasing. Changes are persisted and can trigger a render-settings reload. |
+| `ambientOcclusionEnabled` | `boolean` | Enables/disables SSAO. Changes are persisted and can trigger a render-settings reload. |
+| `iblEnabled` | `boolean` | Enables/disables image-based lighting. Changes are persisted and can trigger a render-settings reload. |
+| `shadowsEnabled` | `boolean` | Enables/disables shadows. Changes are persisted and can trigger a render-settings reload. |
+| `showAnimationMenu` | `boolean`/`"false"` | Enables the animation control menu when model animations are available. Applies immediately, persists, and refreshes menu availability. |
+| `highlightEnabled` | `boolean`/`"false"` | Enables/disables hover highlight for animation openings. Applies immediately and persists. |
+| `highlightColor` | `string` | Hex color used by hover highlight. Applies immediately and persists. |
+| `showLightingTimeOfDay` | `boolean`/`"false"` | Shows or hides the time-of-day slider. When set to `false` without an explicit `lightingTimeOfDay`, the viewer resets `lightingTimeOfDay` to the default `0.5`. |
+| `lightingTimeOfDay` | `number` | Normalized time of day from `0` to `1`; `0.5` is the default noon/day value. Applies immediately and persists unless `persist: false` is used by transient playback. |
+
+Render settings are persisted in `localStorage` under the `pref-viewer/render-settings` key when changed through the runtime settings flow. The menu is always synchronized from the effective controller settings after changes from the menu, `setOptions`, or `loadConfig`.
+
+## Runtime styles
+
+Runtime styles can be passed through the `styles` attribute, the `styles` property setter, `setStyles(styles)`, or `loadConfig({ styles })`.
+
+```html
+<pref-viewer styles='{"colorPrimary":"#0055cc"}'></pref-viewer>
+```
+
+```js
+viewer.setStyles({
+  colorPrimary: "#0055cc",
+});
+```
+
+Only `colorPrimary` is currently supported. The value updates `PrefViewerStyleVariables.colorPrimary`, is exposed on the host as `--pref-viewer-color-primary`, and is persisted in `localStorage` under `pref-viewer/styles`. Persisted styles are restored when a new `<pref-viewer>` instance is created and connected.
+
+## Localization
+
+The default locale is `en-EN`. The viewer currently includes translations for:
+
+- `en-EN`
+- `es-ES`
+
+```html
+<pref-viewer culture="es-ES"></pref-viewer>
+```
+
+```js
+viewer.setCulture("en-EN");
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Start the local playground:
+
+```bash
+npm start
+```
+
+The playground is available from `playground/index.html` and serves the project through `http-server` after bundling the local source.
+
+## Package scripts
+
+| Script | Description |
+| --- | --- |
+| `npm run build` | Bundles `src/index.js` into `dist/bundle.js` with esbuild. This is the standard ESM playground/runtime build. |
+| `npm run build:prefweb` | Creates a production webpack UMD build for PrefWeb consumption. It limits output to a single chunk and emits `dist/bundle-umd.js`. |
+| `npm run build:prefweb:dev` | Creates a development webpack UMD build with external source maps for PrefWeb/browser debugging. Source map module names point back to project source paths. |
+| `npm start` | Builds the standard bundle and starts a local HTTP server on port `8080`. |
+| `npm test` | Runs the Vitest test suite. |
+| `npm run release` | Creates a standard-version release. |
+| `npm run release:beta` | Creates a beta prerelease with standard-version. |
+
+## TypeScript and JSX
+
+The package ships `index.d.ts`, including JSX support for `<pref-viewer>`.
+
+```tsx
+export function ProductViewer() {
+  return (
+    <pref-viewer
+      model={JSON.stringify({
+        storage: {
+          url: "https://example.com/assets/model.glb",
+        },
+      })}
+    />
+  );
+}
+```
+
+## Notes for integrators
+
+- The component is a Web Component, so it can be used from plain HTML, React, Vue, Angular, or any framework that supports custom elements.
+- Give the element an explicit width and height. Babylon.js needs a measurable canvas container.
+- Use object-based JavaScript APIs for complex payloads. Attributes must be valid JSON strings.
+- Remote assets must be reachable by the browser and must satisfy the expected CORS policy.
+- glTF files with external resources are resolved and cached by the viewer when possible.
+- Avoid repeatedly replacing large assets if only visibility, camera, lighting, render, or material options changed.
+- Use `pref-viewer-initialized` only as a component-readiness signal. If a host generates model data asynchronously, wait for the host data-ready signal before calling `loadConfig()`.
+- For PrefWeb integration, consume the webpack UMD build (`bundle-umd.js`) and prefer development UMD builds while debugging source maps.
+
+## License
+
+Proprietary. Copyright (c) 2026 Preference S.L. All rights reserved.
+
+This package is published for authorized Preference S.L. customers and partners. Use, distribution, and access are governed by the applicable commercial agreement with Preference S.L. See [LICENSE.md](./LICENSE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.16.0-beta.1",
+    "version": "2.16.0-beta.11",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -19,7 +19,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "license": "MIT",
+    "license": "SEE LICENSE IN LICENSE.md",
     "type": "module",
     "main": "src/index.js",
     "types": "index.d.ts",
@@ -35,11 +35,11 @@
         "index.d.ts"
     ],
     "dependencies": {
-        "@babylonjs/core": "^8.50.5",
-        "@babylonjs/loaders": "^8.50.5",
-        "@babylonjs/serializers": "^8.50.5",
-        "@panzoom/panzoom": "^4.6.0",
-        "babylonjs-gltf2interface": "^8.50.5",
+        "@babylonjs/core": "^9.11.0",
+        "@babylonjs/loaders": "^9.11.0",
+        "@babylonjs/serializers": "^9.11.0",
+        "@panzoom/panzoom": "^4.6.2",
+        "babylonjs-gltf2interface": "^9.11.0",
         "buffer": "^6.0.3",
         "idb": "^8.0.3",
         "is-svg": "^6.1.0",

package/src/babylonjs-animation-opening.js

@@ -8,7 +8,7 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - Tracks animation state (paused, closed, opened, opening, closing).
  *  - Synchronizes animation progress and UI controls.
  *  - Handles loop mode and progress threshold logic.
- *  - Dispatches `prefviewer-animation-update` events with animation state snapshots.
+ *  - Dispatches `pref-viewer-3d-animation-changed` events with animation state snapshots.
  *  - Provides methods for play, pause, go to opened/closed, and progress control.
  *  - Manages the animation control menu (OpeningAnimationMenu) and its callbacks.
  *
@@ -20,12 +20,17 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - pause(): Pauses the current animation.
  *  - goToOpened(): Moves animation to the fully opened state.
  *  - goToClosed(): Moves animation to the fully closed state.
+ *  - setProgress(progress): Seeks the animation to a normalized position (0–1), snapping to ends when within the threshold.
+ *  - setLoop(loop): Enables or disables loop mode and syncs the control menu if visible.
  *  - showControls(canvas, openingAnimations): Displays the animation control menu and sets up callbacks.
  *  - hideControls(): Hides the animation control menu.
  *  - isControlsVisible(): Returns true if the control menu is visible for this animation.
  *
  * Public Properties:
- *  - state: Returns the current animation state.
+ *  - state: Returns the current animation state (one of OpeningAnimation.states).
+ *  - progress: Returns the normalized progress (0–1) derived from the current frame position.
+ *  - loop: Returns whether loop mode is currently enabled.
+ *  - nodes: Returns a copy of the node ID array affected by this animation.
  *
  * Private Methods:
  *  - #getNodesFromAnimationGroups(): Collects node IDs affected by the animation groups.
@@ -39,7 +44,7 @@ import OpeningAnimationMenu from "./babylonjs-animation-opening-menu.js";
  *  - #getProgress(): Calculates progress (0-1) from current frame.
  *  - #getPrefViewer3DComponent(): Resolves and caches the nearest `pref-viewer-3d` host element.
  *  - #checkProgress(progress): Applies threshold logic to progress.
- *  - #notifyStateChange(): Emits `prefviewer-animation-update` with state/progress/loop metadata.
+ *  - #notifyStateChange(): Emits `pref-viewer-3d-animation-changed` with state/progress/loop metadata.
  *  - #updateControlsSlider(): Updates the slider in the control menu.
  *  - #updateControls(): Emits state updates and syncs controls when the menu is visible.
  */
@@ -315,7 +320,7 @@ export default class OpeningAnimation {
     }
 
     /**
-     * Dispatches a `prefviewer-animation-update` CustomEvent from the nearest `pref-viewer-3d` host.
+     * Dispatches a `pref-viewer-3d-animation-changed` CustomEvent from the nearest `pref-viewer-3d` host.
      * The event bubbles and crosses shadow DOM boundaries, exposing the current animation snapshot
      * (`name`, `state`, `progress`, and `loop`) in `event.detail`.
      * @private
@@ -329,6 +334,7 @@ export default class OpeningAnimation {
 
         const customEventOptions = {
             bubbles: true,
+            cancelable: false,
             composed: true,
             detail: {
                 name: this.name,
@@ -337,7 +343,7 @@ export default class OpeningAnimation {
                 loop: this.#loop,
             },
         };
-        this.#prefViewer3D.dispatchEvent(new CustomEvent("prefviewer-animation-changed", customEventOptions));
+        this.#prefViewer3D.dispatchEvent(new CustomEvent("pref-viewer-3d-animation-changed", customEventOptions));
         return true;
     }