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

package/src/file-storage.js

@@ -129,6 +129,10 @@ export default class FileStorage {
     #minimumFreeSpaceRatio = 0.05; // try to keep at least 5% of quota free
     #maxQuotaEvictionRetries = 5; // max retries after quota error
     #lastCleanupAt = 0; // timestamp of last automatic cleanup run
+    // In-memory blob cache — eliminates repeated IDB round-trips for the same URI within a session.
+    // Keyed by URI; values are normalized records (blob kept in RAM). Avoids both the readonly read
+    // and the readwrite #touchFile transaction on every getURL() call during #replaceSceneURIAsync.
+    #memoryCache = new Map();
 
     constructor(dbName = "FilesDB", osName = "FilesObjectStore") {
         this.dbName = dbName; // database name
@@ -258,6 +262,7 @@ export default class FileStorage {
         const store = transaction.objectStore(this.osName);
         keys.forEach((key) => {
             store.delete(key);
+            this.#memoryCache.delete(String(key));
         });
         await transaction.done;
         return keys.length;
@@ -608,6 +613,7 @@ export default class FileStorage {
                 const store = transaction.objectStore(this.osName);
                 const result = await store.put(record, uri);
                 await transaction.done;
+                this.#memoryCache.set(uri, record);
                 return result;
             } catch (error) {
                 if (!this.#isQuotaExceededError(error) || attempt === this.#maxQuotaEvictionRetries) {
@@ -635,6 +641,19 @@ export default class FileStorage {
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
     async #getFile(uri, { touch = true, allowExpired = false } = {}) {
+        // In-memory cache hit: skip IDB entirely, update lastAccess in RAM only.
+        const inMemory = this.#memoryCache.get(uri);
+        if (inMemory) {
+            if (!allowExpired && this.#isExpired(inMemory)) {
+                this.#memoryCache.delete(uri);
+            } else {
+                if (touch) {
+                    inMemory.lastAccess = this.#now();
+                }
+                return inMemory;
+            }
+        }
+
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -651,13 +670,68 @@ export default class FileStorage {
             await this.#deleteKeys([uri]);
             return undefined;
         }
+        this.#memoryCache.set(uri, record);
         if (touch) {
-            await this.#touchFile(uri, record);
+            // Fire-and-forget: don't block the caller on a readwrite IDB transaction just to update lastAccess.
+            void this.#touchFile(uri, record);
             record.lastAccess = this.#now();
         }
         return record;
     }
 
+    /**
+     * Retrieves multiple file records from the in-memory cache and IDB in a single readonly
+     * transaction, populating the in-memory cache for all hits.
+     * @private
+     * @param {string[]} uris - URIs to look up.
+     * @returns {Promise<Map<string, object>>} Map of uri → normalized record for found entries.
+     */
+    async #getFileBatch(uris) {
+        const resultMap = new Map();
+        if (!uris.length) return resultMap;
+
+        const idbMisses = [];
+        for (const uri of uris) {
+            const cached = this.#memoryCache.get(uri);
+            if (cached) {
+                if (this.#isExpired(cached)) {
+                    this.#memoryCache.delete(uri);
+                    idbMisses.push(uri);
+                } else {
+                    resultMap.set(uri, cached);
+                }
+            } else {
+                idbMisses.push(uri);
+            }
+        }
+
+        if (!idbMisses.length) return resultMap;
+
+        if (this.#db === undefined) {
+            this.#db = await this.#openDB();
+        }
+        if (this.#db === null) return resultMap;
+
+        // One readonly transaction for all IDB misses — single lock acquisition vs N transactions.
+        const tx = this.#db.transaction(this.osName, "readonly");
+        const store = tx.objectStore(this.osName);
+        const rawRecords = await Promise.all(idbMisses.map((uri) => store.get(uri)));
+
+        const now = this.#now();
+        idbMisses.forEach((uri, i) => {
+            const record = this.#normalizeRecord(rawRecords[i]);
+            if (!record) return;
+            if (this.#isExpired(record, now)) {
+                void this.#deleteKeys([uri]);
+                return;
+            }
+            this.#memoryCache.set(uri, record);
+            resultMap.set(uri, record);
+        });
+
+        return resultMap;
+    }
+
     /**
      * ---------------------------
      * Public methods
@@ -682,6 +756,44 @@ export default class FileStorage {
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
     }
 
+    /**
+     * Resolve multiple URIs to object URLs in a single IDB batch transaction.
+     * Hits in-memory cache first, then IDB in one transaction, then falls back to individual
+     * server downloads for any URIs not found. Returns a Map<uri, objectURL|uri>.
+     * @public
+     * @param {string[]} uris - URIs to resolve.
+     * @returns {Promise<Map<string, string>>} Map of uri → resolved URL (blob: or original URI).
+     */
+    async getURLBatch(uris) {
+        if (!uris.length) return new Map();
+        if (!this.#supported) {
+            return new Map(uris.map((uri) => [uri, uri]));
+        }
+        await this.#runCleanupIfDue();
+        const records = await this.#getFileBatch(uris);
+        const urlMap = new Map();
+        const serverFetches = [];
+
+        for (const uri of uris) {
+            const record = records.get(uri);
+            if (record?.blob) {
+                urlMap.set(uri, URL.createObjectURL(record.blob));
+            } else {
+                serverFetches.push(uri);
+            }
+        }
+
+        // For URIs absent from IDB, fall back to individual get() which downloads and caches them.
+        await Promise.all(
+            serverFetches.map(async (uri) => {
+                const url = await this.getURL(uri);
+                if (url) urlMap.set(uri, url);
+            })
+        );
+
+        return urlMap;
+    }
+
     /**
      * Get the cached or server Last-Modified timestamp for a file.
      * @public
@@ -762,10 +874,18 @@ export default class FileStorage {
         }
         if (!storedFile) {
             const fileToStore = await this.#getServerFile(uri);
-            if (fileToStore && !!(await this.#putFile(fileToStore, uri))) {
-                storedFile = await this.#getFile(uri);
-            } else {
-                storedFile = fileToStore;
+            if (fileToStore) {
+                // Populate in-memory cache immediately after download so subsequent calls
+                // within this session are instant — even if the IDB write fails later.
+                const freshRecord = this.#createRecordFromFile(fileToStore);
+                if (freshRecord) {
+                    this.#memoryCache.set(uri, freshRecord);
+                }
+                if (!!(await this.#putFile(fileToStore, uri))) {
+                    storedFile = await this.#getFile(uri);
+                } else {
+                    storedFile = freshRecord ?? fileToStore;
+                }
             }
         }
         return storedFile;
@@ -801,5 +921,6 @@ export default class FileStorage {
             } catch {}
         }
         this.#db = undefined;
+        this.#memoryCache.clear();
     }
 }

package/src/gltf-resolver.js

@@ -82,27 +82,27 @@ export default class GLTFResolver {
      *   - If parsing fails, returns a Blob with MIME type "model/gltf-binary" and extension ".glb".
      *   - If decoding fails, returns nulls for blob and extension.
      */
-    #decodeBase64(base64) {
+    async #decodeBase64(base64) {
         const [, payload] = base64.split(",");
         const raw = payload || base64;
-        let decoded = "";
+        const size = raw.length;
+
+        // Detect format from first base64 chars — O(1), no full decode needed.
+        // GLB magic bytes 0x676c5446 ("glTF") encode to "Z2x" in base64.
+        // GLTF JSON always starts with '{' (0x7B), which encodes to "ey" in base64.
+        const isGlb = raw.startsWith("Z2x");
+        const extension = isGlb ? ".glb" : ".gltf";
+        const type = isGlb ? "model/gltf-binary" : "model/gltf+json";
+
         let blob = null;
-        let extension = null;
-        let size = raw.length;
         try {
-            decoded = atob(raw);
+            // Native browser decode: runs in C++ off the JS call stack, does not block the
+            // main thread. Avoids the per-character Uint8Array loop and the full JSON.parse
+            // that the previous sync implementation used to detect the file type.
+            blob = await fetch(`data:${type};base64,${raw}`).then((r) => r.blob());
         } catch {
-            return { blob, extension, size };
+            return { blob: null, extension: null, size };
         }
-        let isJson = false;
-        try {
-            JSON.parse(decoded);
-            isJson = true;
-        } catch {}
-        extension = isJson ? ".gltf" : ".glb";
-        const type = isJson ? "model/gltf+json" : "model/gltf-binary";
-        const array = Uint8Array.from(decoded, (c) => c.charCodeAt(0));
-        blob = new Blob([array], { type });
         return { blob, extension, size };
     }
 
@@ -138,6 +138,27 @@ export default class GLTFResolver {
         return typeof url === "string" && url.startsWith("blob:");
     }
 
+    /**
+     * Check whether a source should be treated as embedded base64/data URI.
+     * @private
+     * @param {string} source - Value to test.
+     * @returns {boolean} True when the source is a data URI or raw base64 payload.
+     */
+    #isEmbeddedBase64Source(source) {
+        if (typeof source !== "string") {
+            return false;
+        }
+        const normalized = source.trim();
+        if (!normalized) {
+            return false;
+        }
+        if (normalized.startsWith("data:")) {
+            return true;
+        }
+        // Raw base64 payloads use the standard alphabet and have no URL separators.
+        return /^[A-Za-z0-9+/=_-]+$/.test(normalized);
+    }
+
     /**
      * Collects asset entries that have an external URI (non-data URI) and stores a normalized absolute or relative-resolved URI for later replacement.
      * @private
@@ -204,17 +225,19 @@ export default class GLTFResolver {
             assetContainerJSON.images.forEach((asset, index, array) => this.#saveAssetData(asset, index, array, sceneURLBase, arrayOfAssetsWithURI));
         }
 
-        // Replace parallel URIs so that if files are not stored yet, they are downloaded in parallel
-        const promisesArray = arrayOfAssetsWithURI.map(async (asset) => {
-            const uri = await this.#fileStorage.getURL(asset.uri);
-            if (uri) {
-                asset.parent[asset.index].uri = uri;
-                if (this.#isBlobURL(uri)) {
-                    objectURLs.push(uri);
+        // Batch-resolve all asset URIs in a single IDB transaction to avoid per-URI transaction
+        // overhead. Falls back to individual getURL() for URIs not found in IDB.
+        const urisToResolve = arrayOfAssetsWithURI.map((asset) => asset.uri);
+        const urlMap = await this.#fileStorage.getURLBatch(urisToResolve);
+        arrayOfAssetsWithURI.forEach((asset) => {
+            const resolvedUrl = urlMap.get(asset.uri);
+            if (resolvedUrl) {
+                asset.parent[asset.index].uri = resolvedUrl;
+                if (this.#isBlobURL(resolvedUrl)) {
+                    objectURLs.push(resolvedUrl);
                 }
             }
         });
-        await Promise.all(promisesArray);
     }
 
     /**
@@ -270,7 +293,9 @@ export default class GLTFResolver {
 
         if (storage.db && storage.table && storage.id) {
             await this.#initializeStorage(storage.db, storage.table);
+            const tIdb = performance.now();
             const object = await loadModel(storage.id, storage.table);
+            console.log(`[perf][gltf:${storage.id}] IDB read ${Math.round(performance.now() - tIdb)}ms`);
             if (!object || !object.data || !object.timeStamp || !object.size) {
                 return false;
             }
@@ -290,12 +315,21 @@ export default class GLTFResolver {
         }
 
         let file = null;
-        let { blob, extension, size } = this.#decodeBase64(source);
+        let blob = null;
+        let extension = null;
+        let size = 0;
+        if (this.#isEmbeddedBase64Source(source)) {
+            const tDecode = performance.now();
+            ({ blob, extension, size } = await this.#decodeBase64(source));
+            console.log(`[perf][gltf:${storage.id ?? "url"}] decode(${extension}) ${Math.round(performance.now() - tDecode)}ms`);
+        }
 
         if (blob && extension) {
             if (extension === ".gltf") {
                 const assetContainerJSON = JSON.parse(await blob.text());
+                const tReplace = performance.now();
                 await this.#replaceSceneURIAsync(assetContainerJSON, source, objectURLs);
+                console.log(`[perf][gltf:${storage.id ?? "url"}] replaceURIs ${Math.round(performance.now() - tReplace)}ms (${objectURLs.length} assets)`);
                 source = `data:${JSON.stringify(assetContainerJSON)}`;
             } else {
                 file = new File([blob], `file${extension}`, {

package/src/pref-viewer-3d.js

@@ -62,6 +62,7 @@ import FileStorage from "./file-storage.js";
  * Events:
  *  - "scene-loading": Dispatched when a loading operation starts.
  *  - "scene-loaded": Dispatched when a loading operation completes.
+ *  - "model-first-painted": Dispatched when the model-only preview has actually painted a frame.
  *  - "scene-setting-options": Dispatched when viewer options are being set.
  *  - "scene-set-options": Dispatched when viewer options have been set.
  *
@@ -76,6 +77,7 @@ export default class PrefViewer3D extends HTMLElement {
     #isLoaded = false;
     #isVisible = false;
     #lastLoadTimestamp = undefined;
+    #suppressVisibilityAttributeCallback = false;
 
     #wrapper = null;
     #canvas = null;
@@ -112,6 +114,9 @@ export default class PrefViewer3D extends HTMLElement {
      * - "visible": shows or hides the component according to the attribute value ("true"/"false").
      */
     attributeChangedCallback(name, _old, value) {
+        if (this.#suppressVisibilityAttributeCallback && (name === "show-model" || name === "show-scene")) {
+            return;
+        }
         switch (name) {
             case "show-model":
                 if (_old === value) {
@@ -716,6 +721,62 @@ export default class PrefViewer3D extends HTMLElement {
         return { success: someSetted, detail: detail };
     }
 
+    /**
+     * Loads the model container independently in the background while the render loop keeps running.
+     * Merges the model into the scene atomically when ready, without stopping camera-dependent effects.
+     * @public
+     * @param {object} payload - Model payload with storage pointer and optional timestamp.
+     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
+     */
+    async loadModelIndependent(payload) {
+        if (!this.#babylonJSController) {
+            return { success: false, error: "Controller not initialized", loadedContainers: [] };
+        }
+        // #checkNeedToUpdateContainers passed as callback — called AFTER any in-progress #loadContainers
+        // finishes so the scene load doesn't also pick up and consume the model container.
+        return await this.#babylonJSController.loadContainerIndependent("model", () => {
+            this.#checkNeedToUpdateContainers({ model: payload });
+        }, { loadSessionId: payload?.loadSessionId ?? null });
+    }
+
+    /**
+     * Loads the environment/scene container independently in the background, in parallel with any
+     * ongoing model load. Applies IBL (HDR) if the scene payload includes an ibl property.
+     * Dispatches "scene-loading" and "scene-loaded" (or "scene-error") events directly.
+     * @public
+     * @param {object|string} scene - Scene payload: { storage, ibl?, visible? }
+     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
+     */
+    async loadSceneIndependent(scene) {
+        if (!this.#babylonJSController) {
+            return { success: false, error: "Controller not initialized", loadedContainers: [] };
+        }
+        // Pre-mark IBL as pending before entering loadContainerIndependent — the onReady callback
+        // is synchronous so async IBL resolution must happen here, not inside it.
+        if (scene?.ibl !== undefined) {
+            await this.#checkNeedToUpdateIBL({ ibl: scene.ibl });
+        }
+        return await this.#babylonJSController.loadContainerIndependent("environment", () => {
+            this.#checkNeedToUpdateContainers({ scene });
+        });
+    }
+
+    /**
+     * Loads the materials container independently in the background, in parallel with any
+     * ongoing model or environment load.
+     * @public
+     * @param {object|string} materials - Materials payload: { storage }
+     * @returns {Promise<{success: boolean, error: any, loadedContainers: string[]}>}
+     */
+    async loadMaterialsIndependent(materials) {
+        if (!this.#babylonJSController) {
+            return { success: false, error: "Controller not initialized", loadedContainers: [] };
+        }
+        return await this.#babylonJSController.loadContainerIndependent("materials", () => {
+            this.#checkNeedToUpdateContainers({ materials });
+        });
+    }
+
     /**
      * Shows the 3D model within the viewer.
      * @public
@@ -764,6 +825,31 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", false);
     }
 
+    /**
+     * Reflects the current visibility of a container without re-triggering the command queue.
+     * Used by BabylonJSController when the visibility change originated from the renderer itself.
+     * @public
+     * @param {string} name - Container name ("model" or "environment").
+     * @param {boolean} isVisible - Whether the container should be reflected as visible.
+     * @returns {void}
+     */
+    syncVisibility(name, isVisible) {
+        const attrName = name === "model" ? "show-model" : name === "environment" ? "show-scene" : null;
+        if (!attrName) {
+            return;
+        }
+        const nextValue = isVisible ? "true" : "false";
+        if (this.getAttribute(attrName) === nextValue) {
+            return;
+        }
+        this.#suppressVisibilityAttributeCallback = true;
+        try {
+            this.setAttribute(attrName, nextValue);
+        } finally {
+            this.#suppressVisibilityAttributeCallback = false;
+        }
+    }
+
     /**
      * Downloads the current 3D model as a GLB file.
      * @public
@@ -1015,4 +1101,22 @@ export default class PrefViewer3D extends HTMLElement {
     get isVisible() {
         return this.#isVisible;
     }
+
+    /**
+     * Forces the active camera to frame the visible model.
+     * @public
+     * @returns {boolean}
+     */
+    focusModel() {
+        return this.#babylonJSController?.focusModel?.() ?? false;
+    }
+
+    /**
+     * Returns a debug snapshot of the internal 3D state, including camera data.
+     * @public
+     * @returns {object|null}
+     */
+    getDebugState() {
+        return this.#babylonJSController?.getDebugState?.() ?? null;
+    }
 }

package/src/pref-viewer.js

@@ -66,6 +66,7 @@ export default class PrefViewer extends HTMLElement {
     #cultureList = SUPPORTED_LOCALES;
     #culture = "";
     #cultureSuppressAttribute = false;
+    #suppressVisibilityAttributeCallback = false;
 
     // References to internal components
     #wrapper = null;
@@ -120,6 +121,9 @@ export default class PrefViewer extends HTMLElement {
      * @returns {void}
      */
     attributeChangedCallback(name, _old, value) {
+        if (this.#suppressVisibilityAttributeCallback && (name === "show-model" || name === "show-scene")) {
+            return;
+        }
         switch (name) {
             case "config":
                 this.loadConfig(value);
@@ -627,20 +631,47 @@ export default class PrefViewer extends HTMLElement {
     /**
      * Handles the completion of a 3D loading operation.
      * Updates loading state, sets attributes, dispatches a "scene-loaded" event, and processes the next task.
+     * Dispatches granular container events ("model-loaded", "environment-loaded", "materials-loaded")
+     * for each successfully loaded container before firing "scene-loaded".
+     * The independent model path may additionally emit "model-first-painted" when the first painted
+     * frame is acknowledged by the Babylon controller.
      * @private
      * @param {object} [detail] - Optional details to include in the event.
+     * @param {string[]} [detail.loadedContainers] - Names of containers that loaded successfully.
      * @returns {void}
      */
     #on3DLoaded(detail) {
         this.#isLoaded = true;
         this.#isLoading = false;
-        
+
         this.#menu3DSyncSettings();
         this.#menu3DUpdateSwitchAvailability();
 
         this.removeAttribute("loading-3d");
         this.setAttribute("loaded-3d", "");
 
+        // Dispatch granular container events before the aggregate "scene-loaded".
+        // This lets consumers react as soon as individual assets are ready without
+        // waiting for the full scene-loaded signal.
+        const granularEventMap = {
+            model: "model-loaded",
+            environment: "environment-loaded",
+            materials: "materials-loaded",
+        };
+        if (Array.isArray(detail?.loadedContainers)) {
+            const granularEventOptions = {
+                bubbles: true,
+                cancelable: false,
+                composed: true,
+            };
+            detail.loadedContainers.forEach((containerName) => {
+                const eventName = granularEventMap[containerName];
+                if (eventName) {
+                    this.dispatchEvent(new CustomEvent(eventName, granularEventOptions));
+                }
+            });
+        }
+
         const customEventOptions = {
             bubbles: true,
             cancelable: true,
@@ -1121,6 +1152,78 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(model, "model");
     }
 
+    /**
+     * Loads the model container in parallel with any ongoing scene load, bypassing the task queue.
+     * Dispatches "model-loading", "model-first-painted", and "model-loaded" events directly.
+     * @public
+     * @param {object|string} model - Model payload with storage pointer.
+     * @returns {Promise<void>}
+     */
+    async loadModelParallel(model) {
+        model = typeof model === "string" ? JSON.parse(model) : model;
+        if (!model || !this.#component3D) return;
+        const eventOptions = { bubbles: true, cancelable: false, composed: true };
+        this.dispatchEvent(new CustomEvent("model-loading", eventOptions));
+        try {
+            const detail = await this.#component3D.loadModelIndependent(model);
+            if (detail?.success) {
+                this.dispatchEvent(new CustomEvent("model-loaded", { ...eventOptions, detail }));
+            } else {
+                this.dispatchEvent(new CustomEvent("model-error", { ...eventOptions, detail }));
+            }
+        } catch (error) {
+            this.dispatchEvent(new CustomEvent("model-error", { ...eventOptions, detail: { error } }));
+        }
+    }
+
+    /**
+     * Loads the environment/scene container in parallel with any ongoing model load, bypassing the
+     * task queue. Dispatches "scene-loading" and "scene-loaded" (or "scene-error") events directly.
+     * @public
+     * @param {object|string} scene - Scene payload: { storage, ibl?, visible? }
+     * @returns {Promise<void>}
+     */
+    async loadSceneParallel(scene) {
+        scene = typeof scene === "string" ? JSON.parse(scene) : scene;
+        if (!scene || !this.#component3D) return;
+        const eventOptions = { bubbles: true, cancelable: false, composed: true };
+        this.dispatchEvent(new CustomEvent("scene-loading", eventOptions));
+        try {
+            const detail = await this.#component3D.loadSceneIndependent(scene);
+            if (detail?.success) {
+                this.dispatchEvent(new CustomEvent("scene-loaded", { ...eventOptions, detail }));
+            } else {
+                this.dispatchEvent(new CustomEvent("scene-error", { ...eventOptions, detail }));
+            }
+        } catch (error) {
+            this.dispatchEvent(new CustomEvent("scene-error", { ...eventOptions, detail: { error } }));
+        }
+    }
+
+    /**
+     * Loads the materials container in parallel with any ongoing model or environment load,
+     * bypassing the task queue. Dispatches "materials-loading" and "materials-loaded" events.
+     * @public
+     * @param {object|string} materials - Materials payload: { storage }
+     * @returns {Promise<void>}
+     */
+    async loadMaterialsParallel(materials) {
+        materials = typeof materials === "string" ? JSON.parse(materials) : materials;
+        if (!materials || !this.#component3D) return;
+        const eventOptions = { bubbles: true, cancelable: false, composed: true };
+        this.dispatchEvent(new CustomEvent("materials-loading", eventOptions));
+        try {
+            const detail = await this.#component3D.loadMaterialsIndependent(materials);
+            if (detail?.success) {
+                this.dispatchEvent(new CustomEvent("materials-loaded", { ...eventOptions, detail }));
+            } else {
+                this.dispatchEvent(new CustomEvent("materials-error", { ...eventOptions, detail }));
+            }
+        } catch (error) {
+            this.dispatchEvent(new CustomEvent("materials-error", { ...eventOptions, detail: { error } }));
+        }
+    }
+
     /**
      * Loads a scene/environment object or JSON string and adds it to the task queue.
      * @public
@@ -1265,6 +1368,31 @@ export default class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(config, "visibility");
     }
 
+    /**
+     * Reflects the current visibility of a container without feeding the task queue.
+     * Used by the Babylon controller to keep host attributes in sync with renderer state.
+     * @public
+     * @param {string} name - Container name ("model" or "environment").
+     * @param {boolean} isVisible - Whether the container should be reflected as visible.
+     * @returns {void}
+     */
+    syncVisibility(name, isVisible) {
+        const attrName = name === "model" ? "show-model" : name === "environment" ? "show-scene" : null;
+        if (!attrName) {
+            return;
+        }
+        const nextValue = isVisible ? "true" : "false";
+        if (this.getAttribute(attrName) === nextValue) {
+            return;
+        }
+        this.#suppressVisibilityAttributeCallback = true;
+        try {
+            this.setAttribute(attrName, nextValue);
+        } finally {
+            this.#suppressVisibilityAttributeCallback = false;
+        }
+    }
+
     /**
      * Centers the 2D drawing view in the viewer.
      * @public
@@ -1519,4 +1647,22 @@ export default class PrefViewer extends HTMLElement {
     get isMode3D() {
         return this.#mode === "3d";
     }
+
+    /**
+     * Forces the 3D camera to frame the current model, when supported.
+     * @public
+     * @returns {boolean}
+     */
+    focusModel() {
+        return this.#component3D?.focusModel?.() ?? false;
+    }
+
+    /**
+     * Exposes a debug snapshot of the 3D runtime when available.
+     * @public
+     * @returns {object|null}
+     */
+    getDebugState() {
+        return this.#component3D?.getDebugState?.() ?? null;
+    }
 }

package/src/styles.js

@@ -106,6 +106,7 @@ export const PrefViewer3DStyles = `
         position: relative;
         outline: none;
         box-sizing: border-box;
+        background: #ffffff;
     }
 `;