@preference-sl/pref-viewer 2.16.0-beta.9 → 2.16.1

package/README.md

@@ -126,13 +126,22 @@ viewer.loadConfig({
       shadows: true,
     },
     render: {
-      antiAliasingEnabled: true,
       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,
 });
 ```
 
@@ -175,23 +184,22 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 
 ## 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. |
-| `model` | JSON string with a model payload. |
-| `scene` | JSON string with a scene/environment payload. |
-| `materials` | JSON string with a materials payload. |
-| `drawing` | JSON string with a 2D drawing payload. |
-| `options` | JSON string with viewer options. |
-| `culture` | UI locale. Supported values: `en-EN`, `es-ES`. |
+| `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 model. Use `true` or `false`. |
-| `show-scene` | Shows or hides the current scene/environment. Use `true` or `false`. |
-| `show-menu` | Shows or hides the 3D render settings menu. Defaults to visible. |
-| `accent-color` | Forwarded to the 3D component and menu for theme/accent styling when supported by the internal UI. |
-| `show-animation-menu` | Enables or disables the animation menu when animations are available. |
-| `highlight-enabled` | Enables or disables hover highlight. |
-| `highlight-color` | CSS color used for hover highlight. Defaults to `#ff6700`. |
+| `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
 
@@ -199,22 +207,17 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 
 | Method | Description |
 | --- | --- |
-| `loadConfig(config)` | Queues a full configuration update. Accepts an object or JSON string. |
+| `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, or render option updates. |
-| `setCulture(culture)` | Changes the active UI locale. |
+| `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`. |
-
-### Parallel loading helpers
-
-| Method | Description |
-| --- | --- |
-| `loadModelParallel(model)` | Loads a model without waiting for the standard task queue. |
-| `loadSceneParallel(scene)` | Loads a scene/environment without waiting for the standard task queue. |
-| `loadMaterialsParallel(materials)` | Loads materials without waiting for the standard task queue. |
+| `getDebugInfo()` | Returns a 3D runtime diagnostic snapshot when the internal 3D component and controller are available. |
 
 ### Visibility and navigation
 
@@ -227,14 +230,34 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 | `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. |
-| `getDebugState()` | Returns a 3D runtime debug snapshot when the internal 3D component exposes one. |
+
+### Semantic selection and turnable state
+
+| Method | Description |
+| --- | --- |
+| `setSelectableElements(elements)` | Defines and renders selectable SVG ids in yellow (`#FFFF00`, opacity `0.5`). Accepts strings or objects with `id`/`Id`. |
+| `setSelectedElements(elements)` | Defines and renders selected highlights in red (`#FF0000`, opacity `0.5`). Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
+| `applySelectionState(state)` | Applies selectable and selected state to the semantic snapshot and 2D drawing in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`; state supplied before a drawing is reapplied after load. |
+| `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` with exactly `{ ids: string[] }` from a string, descriptor, collection, or `{ ids }` input. This replaces the provisional `detail.element` payload. |
+| `appendSvgNode(id, svgId, svg)` | Adds a host-owned SVG node to the interactive 2D drawing. The node's identified geometry participates in hit-testing and selection. Returns `false` for a duplicate `svgId` or absent node. |
+| `removeAppendedSvgNodes()` | Removes every SVG node previously added through `appendSvgNode` and reconciles the current visual selection layers. |
+| `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 }`. |
+
+Selection colors are rendered through disposable SVG clones; the loaded base SVG and shared definitions are not modified. Selectable clones are inserted before selected clones so red selection remains visible above yellow availability. Reapplying state is idempotent, and replacing the drawing removes dynamic nodes and prior visual layers before the current semantic snapshot is rendered again.
 
 ### Animation controls
 
 | Method | Description |
 | --- | --- |
-| `getAnimations()` | Returns available model animations. |
-| `playAnimation(name, action)` | Plays, pauses, stops, or otherwise controls a named animation. |
+| `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. |
 
@@ -262,10 +285,9 @@ These setters are convenience bridges for framework bindings and property-based
 | `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)`. |
-| `highlightEnabled` | Reflects to the `highlight-enabled` attribute. |
-| `highlightColor` | Reflects to the `highlight-color` attribute. |
 
 ### Getters
 
@@ -277,92 +299,65 @@ These setters are convenience bridges for framework bindings and property-based
 | `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.
+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"`).
 
-| Event | Description |
-| --- | --- |
-| `scene-loading` | A 3D scene/model/material operation has started. |
-| `scene-loaded` | A 3D scene/model/material operation completed. Includes operation details when available. |
-| `scene-error` | A scene operation failed. |
-| `scene-setting-options` | Viewer options are being applied. |
-| `scene-set-options` | Viewer options were applied. |
-| `model-loading` | A parallel model load started. |
-| `model-loaded` | A model container loaded successfully. In the parallel path, this means the independent model load completed. |
-| `model-error` | A parallel model load failed. |
-| `environment-loaded` | The environment/scene container loaded successfully. |
-| `materials-loading` | A parallel materials load started. |
-| `materials-loaded` | A parallel materials load completed. |
-| `materials-error` | A parallel materials load failed. |
-| `drawing-loading` | A 2D drawing load started. |
-| `drawing-loaded` | A 2D drawing load completed. |
-| `drawing-zoom-changed` | The 2D drawing zoom changed. |
-| `model-first-painted` | The first frame for a newly loaded model was painted. |
-| `prefviewer-animation-changed` | A model animation state changed. |
-| `pref-viewer-menu-3d-apply` | The 3D settings menu submitted render-setting changes. |
-| `scene-load-assets-complete` | Performance/progress event emitted after asset-container loading completes. |
-| `scene-load-merge-complete` | Performance/progress event emitted after loaded containers are merged into the scene. |
-| `scene-load-shaders-complete` | Performance/progress event emitted after render/shader work completes. |
-| `scene-load-container-complete` | Performance/progress event emitted after an independent container load completes. |
+### General Events
 
-Example:
+| 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 semantic SVG element was clicked or forwarded by the host. Geometry without its own id resolves the nearest id-bearing ancestor inside the drawing. `detail` is exactly `{ ids: string[] }`; clicks are emitted independently of the current selectable set. |
 
-```js
-const viewer = document.querySelector("pref-viewer");
-
-viewer.addEventListener("scene-loaded", (event) => {
-  console.log("Viewer scene loaded", event.detail);
-});
+### 3D Events
 
-viewer.addEventListener("scene-error", (event) => {
-  console.error("Viewer scene failed", event.detail);
-});
-```
+| 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. |
 
-## Progressive model loading / eager model path
+### 2D Events
 
-`loadModelParallel(model)` is the eager/progressive model-loading API. It bypasses the root task queue and asks the 3D controller to load the model container independently while the existing render loop keeps running.
+| 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. `detail` contains numeric `x`, `y`, `scale` and boolean `moved`, `scaled`, `maximized`, `minimized`; it does not contain `centered` or any private `desde2d`, `mode`, or `source` marker. |
 
-How it behaves:
+### Internal Listeners
 
-1. The model payload is parsed from an object or JSON string.
-2. `model-loading` is dispatched immediately from `<pref-viewer>`.
-3. The 3D component calls `loadModelIndependent(model)`.
-4. The Babylon controller uses `loadContainerIndependent("model", ...)`.
-5. If the model is not already claimed by a full scene load, it follows the optimistic `par` path: download/prepare the glTF container immediately, then merge it atomically.
-6. If a full scene load already claimed the model container, it follows the `claimed` path to avoid a double-load conflict while still letting the independent path own the replacement.
-7. The previous model is replaced without rebuilding camera-dependent effects during the merge (`releaseEffects: false`), reducing gray-frame/flicker risk.
-8. After merge, the controller requests a few render frames and waits for paint before dispatching `model-first-painted`.
-9. The returned detail includes `success`, `error`, `loadedContainers`, and `loadSessionId` when provided by the payload.
+`<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 loadSessionId = crypto.randomUUID();
+const viewer = document.querySelector("pref-viewer");
 
-viewer.addEventListener("model-first-painted", (event) => {
-  console.log("Model first painted", event.detail);
+viewer.addEventListener("pref-viewer-3d-loaded", (event) => {
+  console.log("Viewer 3D loaded", event.detail);
 });
 
-await viewer.loadModelParallel({
-  loadSessionId,
-  storage: {
-    url: "https://example.com/assets/model.glb",
-  },
-  visible: true,
+viewer.addEventListener("pref-viewer-3d-error", (event) => {
+  console.error("Viewer 3D failed", event.detail);
 });
 ```
 
-Important constraints:
-
-- The eager model path requires the internal Babylon scene to already exist. If there is no scene, the controller returns `success: false` with `No scene available`.
-- Only one independent model load can run at a time. A concurrent call returns `success: false` with `Already loading model independently`.
-- `model-loaded` means the model container load finished; `model-first-painted` is the stronger signal for UI handoff because it waits for the browser to paint after the atomic merge.
-- Use this path when the product model should appear as soon as possible while slower scene/environment/material work continues. Use `loadConfig()` when deterministic sequential loading is more important than progressive display.
 ## Render settings
 
-Render settings can be passed through `setOptions`, initial config, or the built-in 3D menu.
+Render settings can be passed through `setOptions`, `loadConfig({ options: { render } })`, property setters, or the built-in 3D menu.
 
 ```js
 viewer.setOptions({
@@ -371,14 +366,44 @@ viewer.setOptions({
     ambientOcclusionEnabled: true,
     iblEnabled: true,
     shadowsEnabled: false,
-    lightingTimeOfDay: 0.5,
+    showAnimationMenu: true,
     highlightEnabled: true,
     highlightColor: "#ff6700",
+    showLightingTimeOfDay: true,
+    lightingTimeOfDay: 0.5,
   },
 });
 ```
 
-Render settings are persisted in `localStorage` under the `pref-viewer/render-settings` key when changed through the runtime settings flow.
+| 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
 
@@ -421,10 +446,10 @@ The playground is available from `playground/index.html` and serves the project
 
 | Script | Description |
 | --- | --- |
-| `npm run build` | Bundles `src/index.js` into `dist/bundle.js` with esbuild. |
-| `npm run build:prefweb` | Creates a production webpack build. |
-| `npm run build:prefweb:dev` | Creates a development webpack build. |
-| `npm start` | Builds the bundle and starts a local HTTP server on port `8080`. |
+| `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. |
@@ -454,7 +479,9 @@ export function ProductViewer() {
 - 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, or material options changed.
+- 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