@preference-sl/pref-viewer 2.17.0-beta.0 → 2.17.0-beta.2

package/src/pref-viewer.js

@@ -1,6 +1,6 @@
 import PrefViewerTask from "./pref-viewer-task.js";
 import { PREF_VIEWER_STYLES_STORAGE_KEY, PrefViewerStyles, PrefViewerStyleVariables } from "./styles.js";
-import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./localization/i18n.js";
+import I18n from "./localization/i18n.js";
 
 /**
  * PrefViewer - Custom Web Component for immersive 2D/3D product visualization with localization, persistence, and download tooling.
@@ -26,7 +26,7 @@ import { DEFAULT_LOCALE, resolveLocale, setLocale, SUPPORTED_LOCALES } from "./l
  *  - config: Configuration descriptor with assets, culture/styles and optional boolean showRenderMenu/showViewCube flags.
  *  - model / scene / materials / drawing: Independent asset entry points (URLs, Base64, indexed data) for each subsystem.
  *  - options: JSON describing render toggles (AA, SSAO, IBL, shadows), animation menu, highlight, lighting, and misc viewer knobs.
- *  - culture: Locale identifier (RFC-5646 style) that resolves against `SUPPORTED_LOCALES` before applying.
+ *  - culture: Locale identifier (RFC-5646 style) that resolves against `I18n.SUPPORTED_LOCALES` before applying.
  *  - mode: Switches between `2d` and `3d`, automatically hiding/showing the relevant subcomponents and menu states.
  *  - show-model / show-scene: Boolean flags to toggle visibility without reloading the underlying resources.
  *  - show-render-menu: Boolean flag to show or hide the render-settings menu (default: true).
@@ -95,8 +95,8 @@ export default class PrefViewer extends HTMLElement {
 
     // Localization/culture management
     #CULTURE_STORAGE_KEY = "pref-viewer/culture";
-    #cultureInitial = DEFAULT_LOCALE;
-    #cultureList = SUPPORTED_LOCALES;
+    #cultureInitial = I18n.DEFAULT_LOCALE;
+    #cultureList = I18n.SUPPORTED_LOCALES;
     #culture = "";
     #cultureSuppressAttribute = false;
 
@@ -117,6 +117,7 @@ export default class PrefViewer extends HTMLElement {
     #handlers = {
         on2DZoomChanged: null,
         on2DElementClick: null,
+        on3DElementClick: null,
         onMenuApply: null,
         onViewerHoverStart: null,
         onViewerHoverEnd: null,
@@ -135,9 +136,9 @@ export default class PrefViewer extends HTMLElement {
         this.attachShadow({ mode: "open" });
         const storedCulture = this.#cultureReadPersisted();
         if (storedCulture) {
-            this.#culture = resolveLocale(storedCulture);
+            this.#culture = I18n.resolveLocale(storedCulture);
         } else {
-            this.#culture = setLocale(this.#cultureInitial);
+            this.#culture = I18n.setLocale(this.#cultureInitial);
         }
 
         this.#applyStyles(this.#stylesReadPersisted(), { persist: false, applyCssVariables: false });
@@ -281,6 +282,7 @@ export default class PrefViewer extends HTMLElement {
             this.#component2D.remove();
         }
         if (this.#component3D) {
+            this.#component3D.removeEventListener("pref-viewer-3d-element-click", this.#handlers.on3DElementClick);
             this.#component3D.removeEventListener("pref-viewer-3d-loaded", this.#handlers.on3DSceneLoaded);
             this.#component3D.removeEventListener("pref-viewer-3d-error", this.#handlers.on3DSceneError);
             this.#component3D.removeEventListener("view-cube-layout", this.#handlers.onViewCubeLayout);
@@ -355,6 +357,7 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     #createComponent3D() {
+        this.#handlers.on3DElementClick = this.#on3DElementClick.bind(this);
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
         this.#component3D.setAttribute("show-view-cube", this.getAttribute("show-view-cube") === "false" ? "false" : "true");
@@ -375,6 +378,7 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.on3DSceneError = () => {
             this.#menu3D?.setApplying(false, true);
         };
+        this.#component3D.addEventListener("pref-viewer-3d-element-click", this.#handlers.on3DElementClick);
         this.#component3D.addEventListener("pref-viewer-3d-loaded", this.#handlers.on3DSceneLoaded);
         this.#component3D.addEventListener("pref-viewer-3d-error", this.#handlers.on3DSceneError);
         this.#wrapper.appendChild(this.#component3D);
@@ -668,14 +672,14 @@ export default class PrefViewer extends HTMLElement {
             return changed;
         }
         const { reflectAttribute = false } = options;
-        const resolved = resolveLocale(cultureId);
+        const resolved = I18n.resolveLocale(cultureId);
         changed = resolved !== this.#culture;
         if (reflectAttribute) {
             this.#cultureReflectAttribute(resolved);
         }
         if (changed) {
             this.#culture = resolved;
-            setLocale(resolved);
+            I18n.setLocale(resolved);
             this.#menu3D?.setCulture?.(resolved);
             this.#component3D?.refreshViewCube?.();
             this.#culturePersist(resolved);
@@ -782,6 +786,7 @@ export default class PrefViewer extends HTMLElement {
 
         this.removeAttribute("loading-3d");
         this.setAttribute("loaded-3d", "");
+        this.#applySelectionStateTo3D();
 
         this.#dispatchPrefViewerEvent("pref-viewer-3d-loaded", detail ?? {});
         this.#dispatchPrefViewerEvent("scene-loaded", detail ?? {}); // Legacy event for backward compatibility
@@ -893,12 +898,23 @@ export default class PrefViewer extends HTMLElement {
         this.notifyElementClick(event.detail?.ids ?? []);
     }
 
+    /**
+     * Forwards semantic click ids from the encapsulated 3D component through the root event contract.
+     * @private
+     * @param {CustomEvent<{ids: string[]}>} event - Internal 3D model click event.
+     * @returns {void}
+     */
+    #on3DElementClick(event) {
+        event.stopPropagation();
+        this.notifyElementClick(event.detail?.ids ?? []);
+    }
+
     /**
      * Handles the custom "pref-viewer-3d-render-settings-change-requested" event emitted by the menu component.
      * Forwards the requested settings to the render-application pipeline.
      * @private
      * @param {CustomEvent} event - Menu event containing the `settings` payload.
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #onMenuApply(event) {
         event.stopPropagation();
@@ -966,7 +982,7 @@ export default class PrefViewer extends HTMLElement {
      * Processes the next task when finished.
      * @private
      * @param {object} drawing - The drawing object to process.
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #processDrawing(drawing) {
         if (!this.#component2D) {
@@ -1028,7 +1044,7 @@ export default class PrefViewer extends HTMLElement {
      * Dispatches loading events and processes the next task.
      * @private
      * @param {object} options - The options object to process.
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async #processOptions(options) {
         if (!this.#component3D) {
@@ -1129,7 +1145,7 @@ export default class PrefViewer extends HTMLElement {
      * Non-string and empty-string results are filtered out.
      * @private
      * @param {Array<string|{id?: string, Id?: string}>} value - Array of id-like items to normalize.
-     * @returns {string[]} Deduplicated, non-empty string ids.
+     * @returns {string[]} Non-empty string ids, preserving input order and duplicate occurrences.
      */
     #normalizeIdList(value) {
         if (!Array.isArray(value)) {
@@ -1180,11 +1196,31 @@ export default class PrefViewer extends HTMLElement {
         this.#dispatchPrefViewerEvent("pref-viewer-selection-state-changed", this.getSelectionState());
     }
 
-    /** Apply the current semantic snapshot to the 2D renderer when available. */
+    /** Apply the current semantic snapshot to the 2D renderer when available. * @returns {void}
+     */
     #applySelectionStateTo2D() {
         this.#component2D?.applySelectionState?.(this.getSelectionState());
     }
 
+    /**
+     * Applies the current semantic snapshot to the 3D renderer when available.
+     * @private
+     * @returns {void}
+     */
+    #applySelectionStateTo3D() {
+        this.#component3D?.applySelectionState?.(this.getSelectionState());
+    }
+
+    /**
+     * Synchronizes the current semantic selection snapshot with both renderers.
+     * @private
+     * @returns {void}
+     */
+    #applySelectionState() {
+        this.#applySelectionStateTo2D();
+        this.#applySelectionStateTo3D();
+    }
+
     /**
      * Dispatches a `pref-viewer-3d-turnable-changed` event carrying the current turnable snapshot.
      * Called after `startTurnable`, `stopTurnable`, or `toggleTurnable` mutates the internal state.
@@ -1505,7 +1541,7 @@ export default class PrefViewer extends HTMLElement {
      */
     setSelectableElements(elements = []) {
         this.#selectionState.selectableIds = this.#normalizeIdList(elements);
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1520,7 +1556,7 @@ export default class PrefViewer extends HTMLElement {
         const selectedItems = this.#normalizeSelectionItems(elements);
         this.#selectionState.selectedItems = selectedItems;
         this.#selectionState.selectedIds = selectedItems.map((item) => item.id);
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1536,7 +1572,7 @@ export default class PrefViewer extends HTMLElement {
         const selectedItems = this.#normalizeSelectionItems(state.selectedItems ?? state.selectedIds ?? state.selected ?? []);
         this.#selectionState.selectedItems = selectedItems;
         this.#selectionState.selectedIds = selectedItems.map((item) => item.id);
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1549,7 +1585,7 @@ export default class PrefViewer extends HTMLElement {
     clearSelectedElements() {
         this.#selectionState.selectedIds = [];
         this.#selectionState.selectedItems = [];
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1561,7 +1597,7 @@ export default class PrefViewer extends HTMLElement {
      */
     clearSelectableElements() {
         this.#selectionState.selectableIds = [];
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1577,7 +1613,7 @@ export default class PrefViewer extends HTMLElement {
             selectedIds: [],
             selectedItems: [],
         };
-        this.#applySelectionStateTo2D();
+        this.#applySelectionState();
         this.#emitSelectionStateChanged();
         return this.getSelectionState();
     }
@@ -1643,7 +1679,7 @@ export default class PrefViewer extends HTMLElement {
      * Remove every SVG node previously added through appendSvgNode.
      * @public
      * @returns {void}
-     * */
+     */
     removeAppendedSvgNodes() {
         this.#component2D?.removeAppendedSvgNodes?.();
     }

package/src/render-math.js

@@ -1,127 +1,140 @@
 /**
- * Pure math utilities used by the lighting cycle and hardware scaling logic.
- * No Babylon.js imports — safe to use in Node/SSR environments and in tests without mocks.
+ * Pure lighting and hardware-scaling calculations without Babylon.js dependencies.
+ * @class RenderMath
  */
-
-/**
- * Clamps a number to the [0, 1] range.
- * Returns 0.5 for non-finite inputs (NaN, ±Infinity) so callers get a safe mid-point fallback.
- * @param {number} value - The value to clamp.
- * @returns {number} A number in [0, 1].
- */
-export function clamp01(value) {
-    if (!Number.isFinite(value)) {
-        return 0.5;
+export default class RenderMath {
+    /**
+     * Clamps a number to the [0, 1] range.
+     * Returns 0.5 for non-finite inputs (NaN, ±Infinity) so callers get a safe mid-point fallback.
+     * @public
+     * @static
+     * @param {number} value - The value to clamp.
+     * @returns {number} A number in [0, 1].
+     */
+    static clamp01(value) {
+        if (!Number.isFinite(value)) {
+            return 0.5;
+        }
+        return Math.min(1, Math.max(0, value));
     }
-    return Math.min(1, Math.max(0, value));
-}
 
-/**
- * Linearly interpolates between two values.
- * The interpolation amount is clamped to [0, 1] before use.
- * @param {number} from - Start value (returned when amount ≤ 0).
- * @param {number} to - End value (returned when amount ≥ 1).
- * @param {number} amount - Blend factor in [0, 1].
- * @returns {number} Interpolated value between `from` and `to`.
- */
-export function lerp(from, to, amount) {
-    const t = clamp01(amount);
-    return from + (to - from) * t;
-}
+    /**
+     * Linearly interpolates between two values.
+     * The interpolation amount is clamped to [0, 1] before use.
+     * @public
+     * @static
+     * @param {number} from - Start value (returned when amount ≤ 0).
+     * @param {number} to - End value (returned when amount ≥ 1).
+     * @param {number} amount - Blend factor in [0, 1].
+     * @returns {number} Interpolated value between `from` and `to`.
+     */
+    static lerp(from, to, amount) {
+        const t = RenderMath.clamp01(amount);
+        return from + (to - from) * t;
+    }
 
-/**
- * Evaluates a bell-curve (half sine arc) over [0, 1].
- * Returns 0 at both endpoints and 1 at the midpoint (x = 0.5).
- * Used to model the intensity rise and fall of sunlight across the day.
- * @param {number} x - Input in [0, 1]; clamped internally.
- * @returns {number} Bell-curve output in [0, 1].
- */
-function bellCurve(x) {
-    const clamped = clamp01(x);
-    return Math.sin(clamped * Math.PI);
-}
+    /**
+     * Evaluates a bell-curve (half sine arc) over [0, 1].
+     * Returns 0 at both endpoints and 1 at the midpoint (x = 0.5).
+     * Used to model the intensity rise and fall of sunlight across the day.
+     * @private
+     * @static
+     * @param {number} x - Input in [0, 1]; clamped internally.
+     * @returns {number} Bell-curve output in [0, 1].
+     */
+    static #bellCurve(x) {
+        const clamped = RenderMath.clamp01(x);
+        return Math.sin(clamped * Math.PI);
+    }
 
-/**
- * Returns a unit vector for the given (x, y, z) direction.
- * Falls back to the original vector with length 1 when the input is the zero vector.
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @returns {{x: number, y: number, z: number}} Normalized direction vector.
- */
-function normalizeDirection(x, y, z) {
-    const length = Math.hypot(x, y, z) || 1;
-    return {
-        x: x / length,
-        y: y / length,
-        z: z / length,
-    };
-}
+    /**
+     * Returns a unit vector for the given (x, y, z) direction.
+     * Leaves the zero vector unchanged by using a divisor of 1 when its length is zero.
+     * @private
+     * @static
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {{x: number, y: number, z: number}} Normalized direction vector.
+     */
+    static #normalizeDirection(x, y, z) {
+        const length = Math.hypot(x, y, z) || 1;
+        return {
+            x: x / length,
+            y: y / length,
+            z: z / length,
+        };
+    }
 
-/**
- * Computes the Babylon.js `hardwareScalingLevel` needed to render at the requested base
- * resolution on a HiDPI display.
- *
- * Babylon's hardware scaling is the inverse of the device pixel ratio: a level of 0.5 on a
- * 2× display renders at native resolution. This helper applies the base scaling factor (which
- * may already downscale for performance on low-end hardware) on top of the device pixel ratio.
- *
- * Both inputs are validated and fall back to 1 when zero, negative, or non-finite.
- * @param {number} [baseScaling=1] - Desired base scaling level (1 = full resolution, >1 = downscaled).
- * @param {number} [pixelRatio=1] - Device pixel ratio (`window.devicePixelRatio`).
- * @returns {number} Hardware scaling level to pass to `engine.setHardwareScalingLevel()`.
- */
-export function getAdaptiveHardwareScalingLevel(baseScaling = 1, pixelRatio = 1) {
-    const safeBaseScaling = Number.isFinite(baseScaling) && baseScaling > 0 ? baseScaling : 1;
-    const safePixelRatio = Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1;
-    return safeBaseScaling / safePixelRatio;
-}
+    /**
+     * Computes the Babylon.js `hardwareScalingLevel` needed to render at the requested base
+     * resolution on a HiDPI display.
+     *
+     * Babylon's hardware scaling is the inverse of the device pixel ratio: a level of 0.5 on a
+     * 2× display renders at native resolution. This helper applies the base scaling factor (which
+     * may already downscale for performance on low-end hardware) on top of the device pixel ratio.
+     *
+     * Both inputs are validated and fall back to 1 when zero, negative, or non-finite.
+     * @public
+     * @static
+     * @param {number} [baseScaling=1] - Desired base scaling level (1 = full resolution, >1 = downscaled).
+     * @param {number} [pixelRatio=1] - Device pixel ratio (`window.devicePixelRatio`).
+     * @returns {number} Hardware scaling level to pass to `engine.setHardwareScalingLevel()`.
+     */
+    static getAdaptiveHardwareScalingLevel(baseScaling = 1, pixelRatio = 1) {
+        const safeBaseScaling = Number.isFinite(baseScaling) && baseScaling > 0 ? baseScaling : 1;
+        const safePixelRatio = Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1;
+        return safeBaseScaling / safePixelRatio;
+    }
 
-/**
- * Computes a lighting profile for a given time of day, used to drive the scene's directional
- * lights, environment intensity, and tonemapping curve.
- *
- * The model follows a simplified solar arc: sunrise at 06:15 and sunset at 20:15 (fractional
- * hours). Day factor peaks at solar noon and falls to zero outside daylight hours. Sun and moon
- * directions are antipodal unit vectors derived from the sun phase angle.
- * @param {number} [timeOfDay=0.5] - Normalized time in [0, 1] where 0 = midnight and 1 = next midnight.
- *   Values outside [0, 1] are clamped.
- * @returns {{
- *   timeOfDay: number,
- *   timeHours: number,
- *   sunPhase: number,
- *   solarAzimuth: number,
- *   solarElevation: number,
- *   dayFactor: number,
- *   nightFactor: number,
- *   sunDirection: {x: number, y: number, z: number},
- *   moonDirection: {x: number, y: number, z: number}
- * }} Lighting profile snapshot for the requested time.
- */
-export function getLightingCycleProfile(timeOfDay = 0.5) {
-    const normalizedTime = clamp01(timeOfDay);
-    const timeHours = normalizedTime * 24;
-    const sunriseHour = 6.25;
-    const sunsetHour = 20.25;
-    const daylightProgress = clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
-    const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(bellCurve(daylightProgress), 0.88) : 0;
-    const nightFactor = 1 - dayFactor;
-    const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
-    const solarAzimuth = lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
-    const solarElevation = lerp(-0.18, 1.18, solarArc);
-    const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
-    const sunDirection = normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
-    const moonDirection = normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
+    /**
+     * Computes a lighting profile for a given time of day, used to drive the scene's directional
+     * lights, environment intensity, and tonemapping curve.
+     *
+     * The model follows a simplified solar arc: sunrise at 06:15 and sunset at 20:15 (fractional
+     * hours). Day factor peaks at solar noon and falls to zero outside daylight hours. Sun and moon
+     * directions are antipodal unit vectors derived from the sun phase angle.
+     * @public
+     * @static
+     * @param {number} [timeOfDay=0.5] - Normalized time in [0, 1] where 0 = midnight and 1 = next midnight.
+     *   Values outside [0, 1] are clamped.
+     * @returns {{
+     *   timeOfDay: number,
+     *   timeHours: number,
+     *   sunPhase: number,
+     *   solarAzimuth: number,
+     *   solarElevation: number,
+     *   dayFactor: number,
+     *   nightFactor: number,
+     *   sunDirection: {x: number, y: number, z: number},
+     *   moonDirection: {x: number, y: number, z: number}
+     * }} Lighting profile snapshot for the requested time.
+     */
+    static getLightingCycleProfile(timeOfDay = 0.5) {
+        const normalizedTime = RenderMath.clamp01(timeOfDay);
+        const timeHours = normalizedTime * 24;
+        const sunriseHour = 6.25;
+        const sunsetHour = 20.25;
+        const daylightProgress = RenderMath.clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
+        const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(RenderMath.#bellCurve(daylightProgress), 0.88) : 0;
+        const nightFactor = 1 - dayFactor;
+        const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
+        const solarAzimuth = RenderMath.lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
+        const solarElevation = RenderMath.lerp(-0.18, 1.18, solarArc);
+        const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
+        const sunDirection = RenderMath.#normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
+        const moonDirection = RenderMath.#normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
 
-    return {
-        timeOfDay: normalizedTime,
-        timeHours,
-        sunPhase,
-        solarAzimuth,
-        solarElevation,
-        dayFactor,
-        nightFactor,
-        sunDirection,
-        moonDirection,
-    };
+        return {
+            timeOfDay: normalizedTime,
+            timeHours,
+            sunPhase,
+            solarAzimuth,
+            solarElevation,
+            dayFactor,
+            nightFactor,
+            sunDirection,
+            moonDirection,
+        };
+    }
 }

package/src/svg-resolver.js

@@ -15,7 +15,7 @@ import { initDb, loadModel } from "./gltf-storage.js";
  *  - Provides a unified API for consumers to obtain SVG content and metadata.
  *
  * Usage:
- *  - Instantiate with an initial SVG state object (required).
+ *  - Instantiate with an optional initial SVG state object.
  *      Example: const resolver = new SVGResolver({ value: "", size: 0, timeStamp: null, update: true });
  *  - Call getSVG(svgConfig) to resolve and update the SVG state.
  *      Example: await resolver.getSVG({ storage: { url: "data:image/svg+xml;base64,..." } });
@@ -78,7 +78,7 @@ export default class SVGResolver {
      * Parse an input that may be a plain SVG string or a data URI (possibly base64).
      * @private
      * @param {string} source - Data URI or raw string to decode/check.
-     * @returns {{value: string|null, size: number}} value when detected/decoded, and size (length of the text string).
+     * @returns {[string|null, number]} Decoded SVG text or null, followed by the source size used for cache comparison.
      */
     #parseSource(source) {
         let value = null;
@@ -210,14 +210,15 @@ export default class SVGResolver {
     /**
      * Resolve and prepare an SVG from multiple storage forms.
      * @public
-     * @param {object|string} svgConfig - Configuration object. Expected shape for storage:
+     * @param {object} svgConfig - Configuration object. Expected shape for storage:
      *   { storage: { url: "<url>" } } // remote URL or data URI (base64 or plain)
      *   { storage: { db: "<db>", table: "<table>", id: "<id>" } } // IndexedDB record
      * @param {object} [svg] - Optional external SVG state object to seed/update. If provided, the resolver
      *   updates this object in-place: { value: string, size: number, timeStamp: string|null, update: boolean }.
      * @returns {Promise<false|{value:string,size:number,timeStamp:string|null,update:boolean}>}
-     *   - Resolves to false when no update is required or on error.
+     *   - Resolves to false when no update is required or the source cannot be decoded/fetched.
      *   - Resolves to the internal SVG state object when an update was prepared.
+     * @throws {Error} Rejects on IndexedDB failures or an absent record in the requested database.
      * @description
      *  - Accepts SVG (base64 or plain string) from IndexedDB (storage.db/table/id), from a data URI (base64 or plain string) (storage.url),
      *    from a remote URL (storage.url) or from direct SVG string (storage.url).