@preference-sl/pref-viewer 2.16.2 → 2.17.0-beta.1

package/src/file-storage.js

@@ -130,6 +130,12 @@ export default class FileStorage {
     #maxQuotaEvictionRetries = 5; // max retries after quota error
     #lastCleanupAt = 0; // timestamp of last automatic cleanup run
 
+    /**
+     * Configures the file-cache database and object store; opening is deferred until storage is used.
+     * @public
+     * @param {string} [dbName="FilesDB"] - IndexedDB cache database name.
+     * @param {string} [osName="FilesObjectStore"] - Object store for cached files.
+     */
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
         this.osName = osName; // object store name used for file cache
@@ -447,6 +453,7 @@ export default class FileStorage {
      * @private
      * @param {IDBDatabase} db IndexedDB database instance
      * @param {String} osName Object store name
+     * @returns {void}
      */
     #createObjectStore(db, osName) {
         if (!db.objectStoreNames.contains(osName)) {
@@ -466,6 +473,12 @@ export default class FileStorage {
         const self = this;
         try {
             return await openDB(this.dbName, this.#dbVersion, {
+                /**
+                 * Creates the configured cache object store during an IndexedDB schema upgrade.
+                 * @private
+                 * @param {IDBDatabase} db - Database being upgraded.
+                 * @returns {void}
+                 */
                 upgrade(db) {
                     self.#createObjectStore(db, self.osName);
                 },

package/src/gltf-storage.js

@@ -7,6 +7,12 @@ PC.db = PC.db ?? null;
 PC.dbName = PC.dbName ?? null;
 PC.storeName = PC.storeName ?? null;
 
+/**
+ * Returns the active IndexedDB connection, throwing if initDb has not initialized it.
+ * @private
+ * @returns {IDBDatabase}
+ * @throws {Error} If initDb has not established a database connection.
+ */
 function _getDbOrThrow() {
     const db = PC.db;
     if (!db) throw new Error("Database not initialized. Call initDb(...) first.");
@@ -14,6 +20,13 @@ function _getDbOrThrow() {
 }
 
 // --- internal helpers -------------------------------------------------------
+/**
+ * Opens database version 5 and creates the model store and expiration index during upgrade.
+ * @private
+ * @param {string} dbName - IndexedDB database name.
+ * @param {string} storeName - Object store name.
+ * @returns {Promise<IDBDatabase>}
+ */
 function _openEnsuringStore(dbName, storeName) {
     return new Promise((resolve, reject) => {
         const open = indexedDB.open(dbName, 5);
@@ -41,6 +54,12 @@ function _openEnsuringStore(dbName, storeName) {
     });
 }
 
+/**
+ * Identifies missing-store or closing-connection errors that allow one database reinitialization.
+ * @private
+ * @param {unknown} err - Error raised by an IndexedDB operation.
+ * @returns {boolean}
+ */
 function _isRecoverableDbError(err) {
     const msg = String(err?.message ?? err ?? "");
     if (!msg) return false;
@@ -50,6 +69,12 @@ function _isRecoverableDbError(err) {
         msg.includes("NotFoundError");
 }
 
+/**
+ * Executes a database operation and retries once after reopening a recoverable connection.
+ * @private
+ * @param {function(IDBDatabase): Promise<*>} work - Operation using the active database.
+ * @returns {Promise<*>}
+ */
 async function _withDbRetry(work) {
     try {
         return await work(_getDbOrThrow());
@@ -65,6 +90,13 @@ async function _withDbRetry(work) {
 // --- public API -------------------------------------------------------------
 
 // Inicializar IndexedDB y dejar el handle en PrefConfigurator.db (público)
+/**
+ * Opens the model database, replaces the previous connection and closes on version changes.
+ * @public
+ * @param {string} dbName - IndexedDB database name.
+ * @param {string} storeName - Object store to create on upgrade.
+ * @returns {Promise<void>}
+ */
 export async function initDb(dbName, storeName) {
     PC.dbName = dbName;
     PC.storeName = storeName;
@@ -83,6 +115,14 @@ export async function initDb(dbName, storeName) {
 }
 
 // Guardar modelo
+/**
+ * Parses a JSON model record and stores it with its base64 data length as the size.
+ * @public
+ * @param {string} modelDataStr - JSON record containing id, data and optional metadata or timestamps.
+ * @param {string} storeName - Object store receiving the record.
+ * @returns {Promise<void>}
+ * @throws {Error} Rejects when JSON parsing or the IndexedDB request fails.
+ */
 export async function saveModel(modelDataStr, storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         let modelData;
@@ -105,6 +145,13 @@ export async function saveModel(modelDataStr, storeName) {
 }
 
 // Cargar modelo
+/**
+ * Reads a complete model record by its IndexedDB key, returning null when absent.
+ * @public
+ * @param {IDBValidKey} modelId - Stored model key.
+ * @param {string} storeName - Object store containing the record.
+ * @returns {Promise<object|null>}
+ */
 export function loadModel(modelId, storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readonly");
@@ -117,6 +164,14 @@ export function loadModel(modelId, storeName) {
 }
 
 // Descargar archivo desde base64
+/**
+ * Triggers a browser download using a base64 data URI and removes the temporary link.
+ * @public
+ * @param {string} fileName - Suggested download filename.
+ * @param {string} bytesBase64 - Base64-encoded file contents.
+ * @param {string} mimeType - MIME type used in the data URI.
+ * @returns {void}
+ */
 export function downloadFileFromBytes(fileName, bytesBase64, mimeType) {
     const link = document.createElement("a");
     link.download = fileName;
@@ -127,6 +182,12 @@ export function downloadFileFromBytes(fileName, bytesBase64, mimeType) {
 }
 
 // Obtener todos los modelos (solo metadata)
+/**
+ * Returns JSON metadata for all models, excluding their stored data payloads.
+ * @public
+ * @param {string} storeName - Object store to read.
+ * @returns {Promise<string>}
+ */
 export async function getAllModels(storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readonly");
@@ -149,6 +210,13 @@ export async function getAllModels(storeName) {
 }
 
 // Eliminar modelo por id
+/**
+ * Deletes the record with the requested key.
+ * @public
+ * @param {IDBValidKey} modelId - Stored model key.
+ * @param {string} storeName - Object store to update.
+ * @returns {Promise<void>}
+ */
 export async function deleteModel(modelId, storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
@@ -161,6 +229,12 @@ export async function deleteModel(modelId, storeName) {
 }
 
 // Limpiar toda la store
+/**
+ * Deletes every model record in the requested object store.
+ * @public
+ * @param {string} storeName - Object store to clear.
+ * @returns {Promise<void>}
+ */
 export async function clearAll(storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
@@ -173,6 +247,12 @@ export async function clearAll(storeName) {
 }
 
 // Borrar modelos expirados usando el índice "expirationTimeStamp"
+/**
+ * Deletes records whose expirationTimeStamp is at or before the current time and waits for transaction completion.
+ * @public
+ * @param {string} storeName - Object store with an expirationTimeStamp index.
+ * @returns {Promise<void>}
+ */
 export async function cleanExpiredModels(storeName) {
     return _withDbRetry((db) => new Promise((resolve, reject) => {
         const tx = db.transaction([storeName], "readwrite");
@@ -198,6 +278,11 @@ export async function cleanExpiredModels(storeName) {
 }
 
 // Utilidades opcionales y visibles (por si las quieres usar en consola)
+/**
+ * Closes the active database connection and clears the shared handle.
+ * @public
+ * @returns {void}
+ */
 export function closeDb() {
     if (PC.db) {
         try { PC.db.close(); } catch { }
@@ -205,6 +290,12 @@ export function closeDb() {
     }
 }
 
+/**
+ * Closes the matching active connection and deletes the database, rejecting blocked or failed requests.
+ * @public
+ * @param {string} dbName - IndexedDB database to delete.
+ * @returns {Promise<void>}
+ */
 export function deleteDatabase(dbName) {
     return new Promise((resolve, reject) => {
         // Close current handle if points to this DB
@@ -220,6 +311,12 @@ export function deleteDatabase(dbName) {
 }
 
 // Attach a frozen, public API (no private state)
+/**
+ * Attaches the frozen storage API to the shared PrefConfigurator namespace.
+ * @private
+ * @param {typeof globalThis} global - Global object exposing the initialized namespace.
+ * @returns {void}
+ */
 (function attachPublicAPI(global) {
     const storage = {
         initDb,

package/src/localization/i18n.js

@@ -1,94 +1,167 @@
 import translations from "./translations.js";
 
-export const DEFAULT_LOCALE = "en-EN";
+/**
+ * Shared localization service with encapsulated locale and subscriber state.
+ * Static methods preserve the single locale shared by all viewer components.
+ * @class I18n
+ */
+export default class I18n {
+    static DEFAULT_LOCALE = "en-EN";
+    static SUPPORTED_LOCALES = Object.keys(translations);
+    static #listeners = new Set();
+    static #currentLocale = I18n.DEFAULT_LOCALE;
 
-export const SUPPORTED_LOCALES = Object.keys(translations);
-const listeners = new Set();
-let currentLocale = DEFAULT_LOCALE;
-
-const findLocaleKey = (localeId) => {
-    if (typeof localeId !== "string") {
-        return DEFAULT_LOCALE;
+    /**
+     * Matches a supported locale without case sensitivity and falls back to DEFAULT_LOCALE.
+     * @private
+     * @static
+     * @param {unknown} localeId - Requested locale identifier.
+     * @returns {string}
+     */
+    static #findLocaleKey(localeId) {
+        if (typeof localeId !== "string") {
+            return I18n.DEFAULT_LOCALE;
+        }
+        const normalized = localeId.trim().toLowerCase();
+        const match = I18n.SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === normalized);
+        return match ?? I18n.DEFAULT_LOCALE;
     }
-    const normalized = localeId.trim().toLowerCase();
-    const match = SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === normalized);
-    return match ?? DEFAULT_LOCALE;
-};
-
-const getBundle = (localeId = currentLocale) => {
-    const key = findLocaleKey(localeId);
-    return translations[key] ?? translations[DEFAULT_LOCALE];
-};
-
-const resolveValue = (bundle, parts) => parts.reduce((acc, part) => (
-    acc && Object.prototype.hasOwnProperty.call(acc, part) ? acc[part] : undefined
-), bundle);
 
-export const availableLocales = () => [...SUPPORTED_LOCALES];
+    /**
+     * Returns the requested translation bundle or the default bundle.
+     * @private
+     * @static
+     * @param {string} [localeId=currentLocale] - Locale to resolve.
+     * @returns {object}
+     */
+    static #getBundle(localeId = I18n.#currentLocale) {
+        const key = I18n.#findLocaleKey(localeId);
+        return translations[key] ?? translations[I18n.DEFAULT_LOCALE];
+    }
 
-export const getLocale = () => currentLocale;
+    /**
+     * Traverses own translation properties, returning undefined when a path is absent.
+     * @private
+     * @static
+     * @param {object} bundle - Translation bundle.
+     * @param {string[]} parts - Nested translation-key segments.
+     * @returns {*}
+     */
+    static #resolveValue(bundle, parts) {
+        return parts.reduce((acc, part) => (
+            acc && Object.prototype.hasOwnProperty.call(acc, part) ? acc[part] : undefined
+        ), bundle);
+    }
 
-export const resolveLocale = (localeId) => findLocaleKey(localeId);
+    /**
+     * Returns a copy of the supported locale identifiers.
+     * @public
+     * @static
+     * @returns {string[]}
+     */
+    static availableLocales() {
+        return [...I18n.SUPPORTED_LOCALES];
+    }
 
-export const setLocale = (localeId) => {
-    const resolved = findLocaleKey(localeId);
-    if (resolved === currentLocale) {
-        return currentLocale;
+    /**
+     * Returns the active shared locale.
+     * @public
+     * @static
+     * @returns {string}
+     */
+    static getLocale() {
+        return I18n.#currentLocale;
     }
-    currentLocale = resolved;
-    listeners.forEach((listener) => {
-        try {
-            listener(currentLocale);
-        } catch (error) {
-            console.warn("PrefViewer: i18n listener failed", error);
-        }
-    });
-    return currentLocale;
-};
 
-export const onLocaleChange = (listener) => {
-    if (typeof listener !== "function") {
-        return () => {};
+    /**
+     * Resolves a requested locale to a supported identifier or the default locale.
+     * @public
+     * @static
+     * @param {unknown} localeId - Requested locale.
+     * @returns {string}
+     */
+    static resolveLocale(localeId) {
+        return I18n.#findLocaleKey(localeId);
     }
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-};
 
-export const translate = (key, options = {}) => {
-    if (!key) {
-        return "";
+    /**
+     * Updates the shared locale and notifies subscribers only when it changes; subscriber errors are logged.
+     * @public
+     * @static
+     * @param {unknown} localeId - Requested locale.
+     * @returns {string}
+     */
+    static setLocale(localeId) {
+        const resolved = I18n.#findLocaleKey(localeId);
+        if (resolved === I18n.#currentLocale) {
+            return I18n.#currentLocale;
+        }
+        I18n.#currentLocale = resolved;
+        I18n.#listeners.forEach((listener) => {
+            try {
+                listener(I18n.#currentLocale);
+            } catch (error) {
+                console.warn("PrefViewer: i18n listener failed", error);
+            }
+        });
+        return I18n.#currentLocale;
     }
-    const { locale, fallback } = options;
-    const parts = Array.isArray(key) ? key : key.split(".");
-    const bundle = getBundle(locale);
-    let value = resolveValue(bundle, parts);
-    if (value !== undefined) {
-        return value;
+
+    /**
+     * Registers a locale-change subscriber and returns its unsubscribe function.
+     * @public
+     * @static
+     * @param {function(string): void} listener - Callback receiving the resolved locale.
+     * @returns {function(): void}
+     */
+    static onLocaleChange(listener) {
+        if (typeof listener !== "function") {
+            return () => {};
+        }
+        I18n.#listeners.add(listener);
+        return () => I18n.#listeners.delete(listener);
     }
-    if (bundle !== translations[DEFAULT_LOCALE]) {
-        value = resolveValue(translations[DEFAULT_LOCALE], parts);
+
+    /**
+     * Resolves a dotted or segmented key, then the default locale, then the supplied fallback or an empty string.
+     * @public
+     * @static
+     * @param {string|string[]} key - Translation key or nested path.
+     * @param {{locale?:string,fallback?:*}} [options={}] - Locale override and missing-key fallback.
+     * @returns {*}
+     */
+    static translate(key, options = {}) {
+        if (!key) {
+            return "";
+        }
+        const { locale, fallback } = options;
+        const parts = Array.isArray(key) ? key : key.split(".");
+        const bundle = I18n.#getBundle(locale);
+        let value = I18n.#resolveValue(bundle, parts);
         if (value !== undefined) {
             return value;
         }
+        if (bundle !== translations[I18n.DEFAULT_LOCALE]) {
+            value = I18n.#resolveValue(translations[I18n.DEFAULT_LOCALE], parts);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        return fallback ?? "";
     }
-    return fallback ?? "";
-};
 
-export const getNamespace = (namespace, options = {}) => {
-    if (!namespace) {
-        return getBundle(options.locale);
+    /**
+     * Returns an entire locale bundle or resolves a namespace through the translation fallback rules.
+     * @public
+     * @static
+     * @param {string} namespace - Nested namespace; an empty value returns the bundle.
+     * @param {{locale?:string,fallback?:*}} [options={}] - Locale override and fallback.
+     * @returns {*}
+     */
+    static getNamespace(namespace, options = {}) {
+        if (!namespace) {
+            return I18n.#getBundle(options.locale);
+        }
+        return I18n.translate(namespace, options);
     }
-    return translate(namespace, options);
-};
-
-export default {
-    availableLocales,
-    DEFAULT_LOCALE,
-    getLocale,
-    getNamespace,
-    onLocaleChange,
-    resolveLocale,
-    setLocale,
-    SUPPORTED_LOCALES,
-    translate,
-};
+}

package/src/localization/translations.js

@@ -1,6 +1,15 @@
 export const translations = {
     "en-EN": {
         prefViewer: {
+            viewCube: {
+                title: "View orientation",
+                front: "Inner",
+                back: "Outer",
+                top: "Top",
+                bottom: "Bottom",
+                left: "Left",
+                right: "Right"
+            },
             menu3d: {
                 title: "3D render settings",
                 subtitle: "Modify the visual effects.",
@@ -62,6 +71,15 @@ export const translations = {
     },
     "es-ES": {
         prefViewer: {
+            viewCube: {
+                title: "Orientación de vista",
+                front: "Interior",
+                back: "Exterior",
+                top: "Arriba",
+                bottom: "Abajo",
+                left: "Izquierda",
+                right: "Derecha"
+            },
             menu3d: {
                 title: "Ajustes de render 3D",
                 subtitle: "Modifica los efectos visuales.",

package/src/material-utils.js

@@ -1,72 +1,79 @@
 import { PBRMaterial } from "@babylonjs/core";
 
 /**
- * Utilities for classifying and tagging PBR materials by their transparency/transmission mode.
- * Used by BabylonJSController at load time and by pref-viewer-3d for render-order decisions.
+ * Classifies and tags materials for transmission and transparent render ordering.
+ * @class MaterialUtils
  */
+export default class MaterialUtils {
+    static #SIMPLIFIED_TRANSMISSION_KEY = "prefViewerSimplifiedTransmission";
 
-const PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY = "prefViewerSimplifiedTransmission";
+    /**
+     * Tags a PBR material as having been converted from physical KHR_materials_transmission to simple
+     * alpha blending. The tag is stored in `mat.metadata` under an internal key so that downstream
+     * render-order passes can still identify these materials as transparent candidates even after
+     * their `subSurface.isRefractionEnabled` flag has been cleared.
+     *
+     * Returns the same material instance (or the original value when `mat` is falsy) so calls can be
+     * chained.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").PBRMaterial|null|undefined} mat - Material to tag.
+     * @returns {import("@babylonjs/core").PBRMaterial|null|undefined} The same `mat` value that was passed in.
+     */
+    static markPrefViewerSimplifiedTransmissionMaterial(mat) {
+        if (!mat) {
+            return mat;
+        }
 
-/**
- * Tags a PBR material as having been converted from physical KHR_materials_transmission to simple
- * alpha blending. The tag is stored in `mat.metadata` under an internal key so that downstream
- * render-order passes can still identify these materials as transparent candidates even after
- * their `subSurface.isRefractionEnabled` flag has been cleared.
- *
- * Returns the same material instance (or the original value when `mat` is falsy) so calls can be
- * chained.
- * @param {import("@babylonjs/core").PBRMaterial|null|undefined} mat - Material to tag.
- * @returns {import("@babylonjs/core").PBRMaterial|null|undefined} The same `mat` value that was passed in.
- */
-export function markPrefViewerSimplifiedTransmissionMaterial(mat) {
-    if (!mat) {
+        mat.metadata = {
+            ...(mat.metadata ?? {}),
+            [MaterialUtils.#SIMPLIFIED_TRANSMISSION_KEY]: true,
+        };
         return mat;
     }
-            
-    mat.metadata = {
-        ...(mat.metadata ?? {}),
-        [PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY]: true,
-    };
-    return mat;
-}
 
-/**
- * Returns true when the material uses Babylon.js physical glass rendering — i.e. either
- * KHR_materials_transmission (refraction) or KHR_materials_translucency is active.
- *
- * This is intentionally narrower than `isPrefViewerTransparentRenderOrderMaterial`: it only
- * matches full physical transmission, not plain alpha blending or simplified environment glass.
- * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
- * @returns {boolean}
- */
-export function isPrefViewerPhysicalGlassMaterial(mat) {
-    return Boolean(mat?.subSurface?.isRefractionEnabled || mat?.subSurface?.isTranslucencyEnabled);
-}
-
-/**
- * Returns true when a material should be placed in the transparent rendering group (renderingGroupId=1).
- *
- * A material qualifies when any of the following is true:
- * - It is a physical glass material (KHR_materials_transmission / translucency).
- * - It has been tagged as simplified environment transmission via `markPrefViewerSimplifiedTransmissionMaterial`.
- * - Its effective alpha is below 1, its `transparencyMode` is alpha-blend or alpha-test-and-blend,
- *   or it self-reports as needing blending/testing through the Babylon.js material API.
- * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
- * @returns {boolean}
- */
-export function isPrefViewerTransparentRenderOrderMaterial(mat) {
-    if (!mat) {
-        return false;
+    /**
+     * Returns true when the material uses Babylon.js physical glass rendering — i.e. either
+     * KHR_materials_transmission (refraction) or KHR_materials_translucency is active.
+     *
+     * This is intentionally narrower than `isPrefViewerTransparentRenderOrderMaterial`: it only
+     * matches full physical transmission, not plain alpha blending or simplified environment glass.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
+     * @returns {boolean}
+     */
+    static isPrefViewerPhysicalGlassMaterial(mat) {
+        return Boolean(mat?.subSurface?.isRefractionEnabled || mat?.subSurface?.isTranslucencyEnabled);
     }
-    const isTransmissive = isPrefViewerPhysicalGlassMaterial(mat);
-    const isSimplifiedTransmission = mat.metadata?.[PREF_VIEWER_SIMPLIFIED_TRANSMISSION_METADATA_KEY] === true;
-    const alpha = typeof mat.alpha === "number" ? mat.alpha : 1;
-    const isAlphaBlended =
-        alpha < 1 ||
-        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHABLEND ||
-        mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHATESTANDBLEND ||
-        mat.needAlphaBlending?.() === true ||
-        mat.needAlphaTesting?.() === true;
 
-    return Boolean(isTransmissive || isSimplifiedTransmission || isAlphaBlended);
+    /**
+     * Returns true when a material should be placed in the transparent rendering group (renderingGroupId=1).
+     *
+     * A material qualifies when any of the following is true:
+     * - It is a physical glass material (KHR_materials_transmission / translucency).
+     * - It has been tagged as simplified environment transmission via `markPrefViewerSimplifiedTransmissionMaterial`.
+     * - Its effective alpha is below 1, its `transparencyMode` is alpha-blend or alpha-test-and-blend,
+     *   or it self-reports as needing blending/testing through the Babylon.js material API.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").Material|null|undefined} mat - Material to test.
+     * @returns {boolean}
+     */
+    static isPrefViewerTransparentRenderOrderMaterial(mat) {
+        if (!mat) {
+            return false;
+        }
+        const isTransmissive = MaterialUtils.isPrefViewerPhysicalGlassMaterial(mat);
+        const isSimplifiedTransmission = mat.metadata?.[MaterialUtils.#SIMPLIFIED_TRANSMISSION_KEY] === true;
+        const alpha = typeof mat.alpha === "number" ? mat.alpha : 1;
+        const isAlphaBlended =
+            alpha < 1 ||
+            mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHABLEND ||
+            mat.transparencyMode === PBRMaterial.PBRMATERIAL_ALPHATESTANDBLEND ||
+            mat.needAlphaBlending?.() === true ||
+            mat.needAlphaTesting?.() === true;
+
+        return Boolean(isTransmissive || isSimplifiedTransmission || isAlphaBlended);
+    }
 }

package/src/panzoom-controller.js

@@ -105,6 +105,14 @@ export default class PanzoomController {
         wheel: null,
     };
     
+    /**
+     * Stores the SVG wrapper, Panzoom options and callbacks, and binds reusable input handlers.
+     * @public
+     * @param {HTMLElement|SVGElement} wrapper - Element transformed by Panzoom.
+     * @param {object} [options] - Panzoom configuration.
+     * @param {function(object): void} [changedCallback] - Receives the current viewport state.
+     * @param {function(Event): void} [clickCallback] - Receives the original event for a recognized click.
+     */
     constructor(wrapper = null, options = {}, changedCallback = null, clickCallback = null) {
         this.#wrapper = wrapper;
         Object.assign(this.#options, options);
@@ -161,7 +169,12 @@ export default class PanzoomController {
         }
     }
 
-    /** Reset transient pointer data after a completed or interrupted gesture. */
+    /**
+     * Reset transient pointer data after a completed or interrupted gesture.
+     * This includes clearing the last pointer down position and resetting counters.
+     * @private
+     * @returns {void}
+     */
     #resetPointerEvents() {
         this.#pointerEvents.lastPointerDownPosition = null;
         this.#pointerEvents.partialCounter = 0;