@2112-lab/central-plant 0.3.55 → 0.3.57

package/dist/bundle/index.js

@@ -27361,13 +27361,15 @@ var EnvironmentManager = /*#__PURE__*/function () {
               return this.createSkybox();
             case 1:
               this.setupLighting();
-              _context4.n = 2;
-              return this.addTexturedGround();
-            case 2:
-              // await this.addBrickWalls()
               this.addHorizonFog();
-              console.log('Environment initialization completed');
-            case 3:
+
+              // 2. Add ground (synchronously adds basic mesh)
+              // We do NOT await the texture loading here to speed up scene "Ready" state
+              this.addTexturedGround().catch(function (err) {
+                return console.warn('⚠️ Ground texture load failed:', err);
+              });
+              console.log('Environment initialization completed (textures loading in background)');
+            case 2:
               return _context4.a(2);
           }
         }, _callee4, this);
@@ -34899,31 +34901,39 @@ var SceneOperationsManager = /*#__PURE__*/function () {
               component = this.sceneViewer;
               _context8.p = 1;
               defaultCentralPlantUrl = process.env.DEFAULT_CENTRAL_PLANT_URL;
-              _context8.n = 2;
-              return fetch(defaultCentralPlantUrl);
+              console.log('🔍 [SceneOperations] Attempting loadScene with URL:', defaultCentralPlantUrl);
+              if (defaultCentralPlantUrl) {
+                _context8.n = 2;
+                break;
+              }
+              console.log('ℹ️ [SceneOperations] No default scene URL provided, skipping automatic load');
+              return _context8.a(2);
             case 2:
-              response = _context8.v;
               _context8.n = 3;
-              return response.json();
+              return fetch(defaultCentralPlantUrl);
             case 3:
+              response = _context8.v;
+              _context8.n = 4;
+              return response.json();
+            case 4:
               data = _context8.v;
               // Store current scene data even for default scene
               component.currentSceneData = data;
 
               // Use the consolidated scene loading function (treat as imported to ensure consistent behavior)
-              _context8.n = 4;
+              _context8.n = 5;
               return this.loadSceneFromData(data);
-            case 4:
-              _context8.n = 6;
-              break;
             case 5:
-              _context8.p = 5;
+              _context8.n = 7;
+              break;
+            case 6:
+              _context8.p = 6;
               _t4 = _context8.v;
               console.error('Error loading default scene:', _t4);
-            case 6:
+            case 7:
               return _context8.a(2);
           }
-        }, _callee8, this, [[1, 5]]);
+        }, _callee8, this, [[1, 6]]);
       }));
       function loadScene() {
         return _loadScene.apply(this, arguments);
@@ -41815,7 +41825,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.3.55
+   * @version 0.3.57
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -44433,23 +44443,18 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
     /**
      * Initialize model preloading from component dictionary
      * @param {string} [basePath='/library/'] - Base path for both dictionary and models (can be local path or S3 URL)
-     * @returns {Promise<Object>} Preloading progress results
-     * @description Loads the component dictionary and preloads all models for better performance
-     * @example
-     * // Local files (default)
-     * await centralPlant.initializeModelPreloading()
-     * 
-     * // S3 bucket
-     * await centralPlant.initializeModelPreloading('https://my-bucket.s3.amazonaws.com/library/')
-     * 
-     * // Custom local path
-     * await centralPlant.initializeModelPreloading('/custom/assets/')
+     * @param {Object} [options={}] - Optimization options
+     * @param {boolean} [options.autoPreloadModels=true] - If false, only loads the dictionary and skips preloading GLBs (improves initial load)
+     * @returns {Promise<Object>} Preloading progress results or dictionary summary
      */
   }, {
     key: "initializeModelPreloading",
     value: (function () {
       var _initializeModelPreloading = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee10() {
         var basePath,
+          options,
+          _options$autoPreloadM,
+          autoPreloadModels,
           normalizedBasePath,
           dictionaryPath,
           modelsBasePath,
@@ -44463,6 +44468,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
           while (1) switch (_context10.n) {
             case 0:
               basePath = _args10.length > 0 && _args10[0] !== undefined ? _args10[0] : '/library/';
+              options = _args10.length > 1 && _args10[1] !== undefined ? _args10[1] : {};
+              _options$autoPreloadM = options.autoPreloadModels, autoPreloadModels = _options$autoPreloadM === void 0 ? true : _options$autoPreloadM;
               _context10.p = 1;
               // Ensure basePath ends with a slash
               normalizedBasePath = basePath.endsWith('/') ? basePath : "".concat(basePath, "/");
@@ -44472,6 +44479,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               console.log("\uD83D\uDCC2 Base path: ".concat(normalizedBasePath));
               console.log("\uD83D\uDCDA Dictionary path: ".concat(dictionaryPath));
               console.log("\uFFFD Models path: ".concat(modelsBasePath));
+              console.log("\u26A1 Auto-preload models: ".concat(autoPreloadModels));
 
               // Load the component dictionary
               _context10.n = 2;
@@ -44488,25 +44496,39 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               return response.json();
             case 4:
               componentDictionary = _context10.v;
-              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary));
+              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary).length);
 
-              // Start preloading all models with the specified base path
+              // Get the model preloader utility
               _modelPreloader2 = this.getUtility('modelPreloader');
-              _context10.n = 5;
-              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+              if (autoPreloadModels) {
+                _context10.n = 5;
+                break;
+              }
+              console.log('⚡ Lazy loading enabled: skipping automatic GLB preloading');
+              // We still need to give the preloader the dictionary and base path for later use
+              _modelPreloader2.componentDictionary = componentDictionary;
+              _modelPreloader2.setModelsBasePath(modelsBasePath);
+              return _context10.a(2, {
+                successCount: 0,
+                failureCount: 0,
+                dictionaryCount: Object.keys(componentDictionary).length
+              });
             case 5:
+              _context10.n = 6;
+              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+            case 6:
               progress = _context10.v;
               console.log('🎉 Model preloading completed:', progress);
               return _context10.a(2, progress);
-            case 6:
-              _context10.p = 6;
+            case 7:
+              _context10.p = 7;
               _t3 = _context10.v;
               console.error('❌ Failed to initialize model preloading:', _t3);
               throw _t3;
-            case 7:
+            case 8:
               return _context10.a(2);
           }
-        }, _callee10, this, [[1, 6]]);
+        }, _callee10, this, [[1, 7]]);
       }));
       function initializeModelPreloading() {
         return _initializeModelPreloading.apply(this, arguments);
@@ -45047,7 +45069,7 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
     key: "initializeScene",
     value: (function () {
       var _initializeScene = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
-        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
+        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, skipDefaultLoad, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
         return _regenerator().w(function (_context2) {
           while (1) switch (_context2.n) {
             case 0:
@@ -45095,7 +45117,11 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
               // Phase 3: Scene loading and transform setup (can be parallelized)
               phase3Start = performance.now();
               console.log('📍 Phase 3: Scene loading and transform setup...');
-              sceneSetupPromises = [this.loadScene().catch(function (error) {
+
+              // Explicitly check if we should skip the default load
+              skipDefaultLoad = process.env.SKIP_DEFAULT_LOAD === 'true';
+              console.log("\uD83D\uDD0D [SceneViewer] skipDefaultLoad: ".concat(skipDefaultLoad));
+              sceneSetupPromises = [skipDefaultLoad ? Promise.resolve() : this.loadScene().catch(function (error) {
                 console.error('❌ Scene loading failed:', error);
                 throw error;
               }), this.setupTransformControls().catch(function (error) {
@@ -46472,7 +46498,7 @@ var CacheManager = /*#__PURE__*/function () {
     key: "execute",
     value: (function () {
       var _execute = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(_ref) {
-        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
+        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, error, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
         return _regenerator().w(function (_context4) {
           while (1) switch (_context4.n) {
             case 0:
@@ -46525,7 +46551,9 @@ var CacheManager = /*#__PURE__*/function () {
                 _context4.n = 9;
                 break;
               }
-              throw new Error("Fetch failed: ".concat(fetchResult.status));
+              error = new Error("Fetch failed: ".concat(fetchResult.status)); // Do not retry 404s - the file is genuinely missing
+              if (fetchResult.status === 404) error.noRetry = true;
+              throw error;
             case 9:
               _context4.n = 10;
               return processor(fetchResult.clone());
@@ -46576,20 +46604,29 @@ var CacheManager = /*#__PURE__*/function () {
             case 15:
               fallbackResult = _context4.v;
               if (!(fallbackResult instanceof Response)) {
+                _context4.n = 18;
+                break;
+              }
+              if (fallbackResult.ok) {
                 _context4.n = 16;
                 break;
               }
-              return _context4.a(2, processor(fallbackResult));
+              throw new Error("Fallback fetch failed: ".concat(fallbackResult.status));
             case 16:
-              return _context4.a(2, fallbackResult);
+              _context4.n = 17;
+              return processor(fallbackResult);
             case 17:
-              _context4.p = 17;
+              return _context4.a(2, _context4.v);
+            case 18:
+              return _context4.a(2, fallbackResult);
+            case 19:
+              _context4.p = 19;
               _context4.v;
               throw _t2;
-            case 18:
+            case 20:
               return _context4.a(2);
           }
-        }, _callee4, this, [[14, 17], [1, 13]]);
+        }, _callee4, this, [[14, 19], [1, 13]]);
       }));
       function execute(_x2) {
         return _execute.apply(this, arguments);

package/dist/cjs/src/core/centralPlant.js

@@ -58,7 +58,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.3.55
+   * @version 0.3.57
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -2676,23 +2676,18 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
     /**
      * Initialize model preloading from component dictionary
      * @param {string} [basePath='/library/'] - Base path for both dictionary and models (can be local path or S3 URL)
-     * @returns {Promise<Object>} Preloading progress results
-     * @description Loads the component dictionary and preloads all models for better performance
-     * @example
-     * // Local files (default)
-     * await centralPlant.initializeModelPreloading()
-     * 
-     * // S3 bucket
-     * await centralPlant.initializeModelPreloading('https://my-bucket.s3.amazonaws.com/library/')
-     * 
-     * // Custom local path
-     * await centralPlant.initializeModelPreloading('/custom/assets/')
+     * @param {Object} [options={}] - Optimization options
+     * @param {boolean} [options.autoPreloadModels=true] - If false, only loads the dictionary and skips preloading GLBs (improves initial load)
+     * @returns {Promise<Object>} Preloading progress results or dictionary summary
      */
   }, {
     key: "initializeModelPreloading",
     value: (function () {
       var _initializeModelPreloading = _rollupPluginBabelHelpers.asyncToGenerator(/*#__PURE__*/_rollupPluginBabelHelpers.regenerator().m(function _callee10() {
         var basePath,
+          options,
+          _options$autoPreloadM,
+          autoPreloadModels,
           normalizedBasePath,
           dictionaryPath,
           modelsBasePath,
@@ -2706,6 +2701,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
           while (1) switch (_context10.n) {
             case 0:
               basePath = _args10.length > 0 && _args10[0] !== undefined ? _args10[0] : '/library/';
+              options = _args10.length > 1 && _args10[1] !== undefined ? _args10[1] : {};
+              _options$autoPreloadM = options.autoPreloadModels, autoPreloadModels = _options$autoPreloadM === void 0 ? true : _options$autoPreloadM;
               _context10.p = 1;
               // Ensure basePath ends with a slash
               normalizedBasePath = basePath.endsWith('/') ? basePath : "".concat(basePath, "/");
@@ -2715,6 +2712,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               console.log("\uD83D\uDCC2 Base path: ".concat(normalizedBasePath));
               console.log("\uD83D\uDCDA Dictionary path: ".concat(dictionaryPath));
               console.log("\uFFFD Models path: ".concat(modelsBasePath));
+              console.log("\u26A1 Auto-preload models: ".concat(autoPreloadModels));
 
               // Load the component dictionary
               _context10.n = 2;
@@ -2731,25 +2729,39 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               return response.json();
             case 4:
               componentDictionary = _context10.v;
-              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary));
+              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary).length);
 
-              // Start preloading all models with the specified base path
+              // Get the model preloader utility
               _modelPreloader2 = this.getUtility('modelPreloader');
-              _context10.n = 5;
-              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+              if (autoPreloadModels) {
+                _context10.n = 5;
+                break;
+              }
+              console.log('⚡ Lazy loading enabled: skipping automatic GLB preloading');
+              // We still need to give the preloader the dictionary and base path for later use
+              _modelPreloader2.componentDictionary = componentDictionary;
+              _modelPreloader2.setModelsBasePath(modelsBasePath);
+              return _context10.a(2, {
+                successCount: 0,
+                failureCount: 0,
+                dictionaryCount: Object.keys(componentDictionary).length
+              });
             case 5:
+              _context10.n = 6;
+              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+            case 6:
               progress = _context10.v;
               console.log('🎉 Model preloading completed:', progress);
               return _context10.a(2, progress);
-            case 6:
-              _context10.p = 6;
+            case 7:
+              _context10.p = 7;
               _t3 = _context10.v;
               console.error('❌ Failed to initialize model preloading:', _t3);
               throw _t3;
-            case 7:
+            case 8:
               return _context10.a(2);
           }
-        }, _callee10, this, [[1, 6]]);
+        }, _callee10, this, [[1, 7]]);
       }));
       function initializeModelPreloading() {
         return _initializeModelPreloading.apply(this, arguments);

package/dist/cjs/src/core/sceneViewer.js

@@ -138,7 +138,7 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
     key: "initializeScene",
     value: (function () {
       var _initializeScene = _rollupPluginBabelHelpers.asyncToGenerator(/*#__PURE__*/_rollupPluginBabelHelpers.regenerator().m(function _callee2() {
-        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
+        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, skipDefaultLoad, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
         return _rollupPluginBabelHelpers.regenerator().w(function (_context2) {
           while (1) switch (_context2.n) {
             case 0:
@@ -186,7 +186,11 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
               // Phase 3: Scene loading and transform setup (can be parallelized)
               phase3Start = performance.now();
               console.log('📍 Phase 3: Scene loading and transform setup...');
-              sceneSetupPromises = [this.loadScene().catch(function (error) {
+
+              // Explicitly check if we should skip the default load
+              skipDefaultLoad = process.env.SKIP_DEFAULT_LOAD === 'true';
+              console.log("\uD83D\uDD0D [SceneViewer] skipDefaultLoad: ".concat(skipDefaultLoad));
+              sceneSetupPromises = [skipDefaultLoad ? Promise.resolve() : this.loadScene().catch(function (error) {
                 console.error('❌ Scene loading failed:', error);
                 throw error;
               }), this.setupTransformControls().catch(function (error) {

package/dist/cjs/src/managers/cache/CacheManager.js

@@ -202,7 +202,7 @@ var CacheManager = /*#__PURE__*/function () {
     key: "execute",
     value: (function () {
       var _execute = _rollupPluginBabelHelpers.asyncToGenerator(/*#__PURE__*/_rollupPluginBabelHelpers.regenerator().m(function _callee4(_ref) {
-        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
+        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, error, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
         return _rollupPluginBabelHelpers.regenerator().w(function (_context4) {
           while (1) switch (_context4.n) {
             case 0:
@@ -255,7 +255,9 @@ var CacheManager = /*#__PURE__*/function () {
                 _context4.n = 9;
                 break;
               }
-              throw new Error("Fetch failed: ".concat(fetchResult.status));
+              error = new Error("Fetch failed: ".concat(fetchResult.status)); // Do not retry 404s - the file is genuinely missing
+              if (fetchResult.status === 404) error.noRetry = true;
+              throw error;
             case 9:
               _context4.n = 10;
               return processor(fetchResult.clone());
@@ -306,20 +308,29 @@ var CacheManager = /*#__PURE__*/function () {
             case 15:
               fallbackResult = _context4.v;
               if (!(fallbackResult instanceof Response)) {
+                _context4.n = 18;
+                break;
+              }
+              if (fallbackResult.ok) {
                 _context4.n = 16;
                 break;
               }
-              return _context4.a(2, processor(fallbackResult));
+              throw new Error("Fallback fetch failed: ".concat(fallbackResult.status));
             case 16:
-              return _context4.a(2, fallbackResult);
+              _context4.n = 17;
+              return processor(fallbackResult);
             case 17:
-              _context4.p = 17;
+              return _context4.a(2, _context4.v);
+            case 18:
+              return _context4.a(2, fallbackResult);
+            case 19:
+              _context4.p = 19;
               _context4.v;
               throw _t2;
-            case 18:
+            case 20:
               return _context4.a(2);
           }
-        }, _callee4, this, [[14, 17], [1, 13]]);
+        }, _callee4, this, [[14, 19], [1, 13]]);
       }));
       function execute(_x2) {
         return _execute.apply(this, arguments);

package/dist/cjs/src/managers/environment/environmentManager.js

@@ -423,13 +423,15 @@ var EnvironmentManager = /*#__PURE__*/function () {
               return this.createSkybox();
             case 1:
               this.setupLighting();
-              _context4.n = 2;
-              return this.addTexturedGround();
-            case 2:
-              // await this.addBrickWalls()
               this.addHorizonFog();
-              console.log('Environment initialization completed');
-            case 3:
+
+              // 2. Add ground (synchronously adds basic mesh)
+              // We do NOT await the texture loading here to speed up scene "Ready" state
+              this.addTexturedGround().catch(function (err) {
+                return console.warn('⚠️ Ground texture load failed:', err);
+              });
+              console.log('Environment initialization completed (textures loading in background)');
+            case 2:
               return _context4.a(2);
           }
         }, _callee4, this);

package/dist/cjs/src/managers/scene/sceneOperationsManager.js

@@ -1194,31 +1194,39 @@ var SceneOperationsManager = /*#__PURE__*/function () {
               component = this.sceneViewer;
               _context8.p = 1;
               defaultCentralPlantUrl = process.env.DEFAULT_CENTRAL_PLANT_URL;
-              _context8.n = 2;
-              return fetch(defaultCentralPlantUrl);
+              console.log('🔍 [SceneOperations] Attempting loadScene with URL:', defaultCentralPlantUrl);
+              if (defaultCentralPlantUrl) {
+                _context8.n = 2;
+                break;
+              }
+              console.log('ℹ️ [SceneOperations] No default scene URL provided, skipping automatic load');
+              return _context8.a(2);
             case 2:
-              response = _context8.v;
               _context8.n = 3;
-              return response.json();
+              return fetch(defaultCentralPlantUrl);
             case 3:
+              response = _context8.v;
+              _context8.n = 4;
+              return response.json();
+            case 4:
               data = _context8.v;
               // Store current scene data even for default scene
               component.currentSceneData = data;
 
               // Use the consolidated scene loading function (treat as imported to ensure consistent behavior)
-              _context8.n = 4;
+              _context8.n = 5;
               return this.loadSceneFromData(data);
-            case 4:
-              _context8.n = 6;
-              break;
             case 5:
-              _context8.p = 5;
+              _context8.n = 7;
+              break;
+            case 6:
+              _context8.p = 6;
               _t4 = _context8.v;
               console.error('Error loading default scene:', _t4);
-            case 6:
+            case 7:
               return _context8.a(2);
           }
-        }, _callee8, this, [[1, 5]]);
+        }, _callee8, this, [[1, 6]]);
       }));
       function loadScene() {
         return _loadScene.apply(this, arguments);

package/dist/esm/src/core/centralPlant.js

@@ -34,7 +34,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.3.55
+   * @version 0.3.57
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -2652,23 +2652,18 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
     /**
      * Initialize model preloading from component dictionary
      * @param {string} [basePath='/library/'] - Base path for both dictionary and models (can be local path or S3 URL)
-     * @returns {Promise<Object>} Preloading progress results
-     * @description Loads the component dictionary and preloads all models for better performance
-     * @example
-     * // Local files (default)
-     * await centralPlant.initializeModelPreloading()
-     * 
-     * // S3 bucket
-     * await centralPlant.initializeModelPreloading('https://my-bucket.s3.amazonaws.com/library/')
-     * 
-     * // Custom local path
-     * await centralPlant.initializeModelPreloading('/custom/assets/')
+     * @param {Object} [options={}] - Optimization options
+     * @param {boolean} [options.autoPreloadModels=true] - If false, only loads the dictionary and skips preloading GLBs (improves initial load)
+     * @returns {Promise<Object>} Preloading progress results or dictionary summary
      */
   }, {
     key: "initializeModelPreloading",
     value: (function () {
       var _initializeModelPreloading = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee10() {
         var basePath,
+          options,
+          _options$autoPreloadM,
+          autoPreloadModels,
           normalizedBasePath,
           dictionaryPath,
           modelsBasePath,
@@ -2682,6 +2677,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
           while (1) switch (_context10.n) {
             case 0:
               basePath = _args10.length > 0 && _args10[0] !== undefined ? _args10[0] : '/library/';
+              options = _args10.length > 1 && _args10[1] !== undefined ? _args10[1] : {};
+              _options$autoPreloadM = options.autoPreloadModels, autoPreloadModels = _options$autoPreloadM === void 0 ? true : _options$autoPreloadM;
               _context10.p = 1;
               // Ensure basePath ends with a slash
               normalizedBasePath = basePath.endsWith('/') ? basePath : "".concat(basePath, "/");
@@ -2691,6 +2688,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               console.log("\uD83D\uDCC2 Base path: ".concat(normalizedBasePath));
               console.log("\uD83D\uDCDA Dictionary path: ".concat(dictionaryPath));
               console.log("\uFFFD Models path: ".concat(modelsBasePath));
+              console.log("\u26A1 Auto-preload models: ".concat(autoPreloadModels));
 
               // Load the component dictionary
               _context10.n = 2;
@@ -2707,25 +2705,39 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
               return response.json();
             case 4:
               componentDictionary = _context10.v;
-              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary));
+              console.log('📚 Component dictionary loaded:', Object.keys(componentDictionary).length);
 
-              // Start preloading all models with the specified base path
+              // Get the model preloader utility
               _modelPreloader2 = this.getUtility('modelPreloader');
-              _context10.n = 5;
-              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+              if (autoPreloadModels) {
+                _context10.n = 5;
+                break;
+              }
+              console.log('⚡ Lazy loading enabled: skipping automatic GLB preloading');
+              // We still need to give the preloader the dictionary and base path for later use
+              _modelPreloader2.componentDictionary = componentDictionary;
+              _modelPreloader2.setModelsBasePath(modelsBasePath);
+              return _context10.a(2, {
+                successCount: 0,
+                failureCount: 0,
+                dictionaryCount: Object.keys(componentDictionary).length
+              });
             case 5:
+              _context10.n = 6;
+              return _modelPreloader2.preloadAllModels(componentDictionary, modelsBasePath);
+            case 6:
               progress = _context10.v;
               console.log('🎉 Model preloading completed:', progress);
               return _context10.a(2, progress);
-            case 6:
-              _context10.p = 6;
+            case 7:
+              _context10.p = 7;
               _t3 = _context10.v;
               console.error('❌ Failed to initialize model preloading:', _t3);
               throw _t3;
-            case 7:
+            case 8:
               return _context10.a(2);
           }
-        }, _callee10, this, [[1, 6]]);
+        }, _callee10, this, [[1, 7]]);
       }));
       function initializeModelPreloading() {
         return _initializeModelPreloading.apply(this, arguments);

package/dist/esm/src/core/sceneViewer.js

@@ -134,7 +134,7 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
     key: "initializeScene",
     value: (function () {
       var _initializeScene = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
-        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
+        var initStart, phase1Start, phase1Time, phase2Start, parallelInitPromises, phase2Time, phase3Start, skipDefaultLoad, sceneSetupPromises, phase3Time, phase4Start, phase4Time, phase5Start, phase5Time, initTime, _t2;
         return _regenerator().w(function (_context2) {
           while (1) switch (_context2.n) {
             case 0:
@@ -182,7 +182,11 @@ var sceneViewer = /*#__PURE__*/function (_BaseDisposable) {
               // Phase 3: Scene loading and transform setup (can be parallelized)
               phase3Start = performance.now();
               console.log('📍 Phase 3: Scene loading and transform setup...');
-              sceneSetupPromises = [this.loadScene().catch(function (error) {
+
+              // Explicitly check if we should skip the default load
+              skipDefaultLoad = process.env.SKIP_DEFAULT_LOAD === 'true';
+              console.log("\uD83D\uDD0D [SceneViewer] skipDefaultLoad: ".concat(skipDefaultLoad));
+              sceneSetupPromises = [skipDefaultLoad ? Promise.resolve() : this.loadScene().catch(function (error) {
                 console.error('❌ Scene loading failed:', error);
                 throw error;
               }), this.setupTransformControls().catch(function (error) {

package/dist/esm/src/managers/cache/CacheManager.js

@@ -198,7 +198,7 @@ var CacheManager = /*#__PURE__*/function () {
     key: "execute",
     value: (function () {
       var _execute = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(_ref) {
-        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
+        var cacheKey, sourceKey, expiryMs, fetcher, processor, _ref$metadata, metadata, cacheName, cache, cachedResponse, cachedTime, age, result, fetchResult, blobOrJson, error, contentType, contentSize, responseBody, headers, cacheResponse, fallbackResult, _t2;
         return _regenerator().w(function (_context4) {
           while (1) switch (_context4.n) {
             case 0:
@@ -251,7 +251,9 @@ var CacheManager = /*#__PURE__*/function () {
                 _context4.n = 9;
                 break;
               }
-              throw new Error("Fetch failed: ".concat(fetchResult.status));
+              error = new Error("Fetch failed: ".concat(fetchResult.status)); // Do not retry 404s - the file is genuinely missing
+              if (fetchResult.status === 404) error.noRetry = true;
+              throw error;
             case 9:
               _context4.n = 10;
               return processor(fetchResult.clone());
@@ -302,20 +304,29 @@ var CacheManager = /*#__PURE__*/function () {
             case 15:
               fallbackResult = _context4.v;
               if (!(fallbackResult instanceof Response)) {
+                _context4.n = 18;
+                break;
+              }
+              if (fallbackResult.ok) {
                 _context4.n = 16;
                 break;
               }
-              return _context4.a(2, processor(fallbackResult));
+              throw new Error("Fallback fetch failed: ".concat(fallbackResult.status));
             case 16:
-              return _context4.a(2, fallbackResult);
+              _context4.n = 17;
+              return processor(fallbackResult);
             case 17:
-              _context4.p = 17;
+              return _context4.a(2, _context4.v);
+            case 18:
+              return _context4.a(2, fallbackResult);
+            case 19:
+              _context4.p = 19;
               _context4.v;
               throw _t2;
-            case 18:
+            case 20:
               return _context4.a(2);
           }
-        }, _callee4, this, [[14, 17], [1, 13]]);
+        }, _callee4, this, [[14, 19], [1, 13]]);
       }));
       function execute(_x2) {
         return _execute.apply(this, arguments);

package/dist/esm/src/managers/environment/environmentManager.js

@@ -399,13 +399,15 @@ var EnvironmentManager = /*#__PURE__*/function () {
               return this.createSkybox();
             case 1:
               this.setupLighting();
-              _context4.n = 2;
-              return this.addTexturedGround();
-            case 2:
-              // await this.addBrickWalls()
               this.addHorizonFog();
-              console.log('Environment initialization completed');
-            case 3:
+
+              // 2. Add ground (synchronously adds basic mesh)
+              // We do NOT await the texture loading here to speed up scene "Ready" state
+              this.addTexturedGround().catch(function (err) {
+                return console.warn('⚠️ Ground texture load failed:', err);
+              });
+              console.log('Environment initialization completed (textures loading in background)');
+            case 2:
               return _context4.a(2);
           }
         }, _callee4, this);

package/dist/esm/src/managers/scene/sceneOperationsManager.js

@@ -1170,31 +1170,39 @@ var SceneOperationsManager = /*#__PURE__*/function () {
               component = this.sceneViewer;
               _context8.p = 1;
               defaultCentralPlantUrl = process.env.DEFAULT_CENTRAL_PLANT_URL;
-              _context8.n = 2;
-              return fetch(defaultCentralPlantUrl);
+              console.log('🔍 [SceneOperations] Attempting loadScene with URL:', defaultCentralPlantUrl);
+              if (defaultCentralPlantUrl) {
+                _context8.n = 2;
+                break;
+              }
+              console.log('ℹ️ [SceneOperations] No default scene URL provided, skipping automatic load');
+              return _context8.a(2);
             case 2:
-              response = _context8.v;
               _context8.n = 3;
-              return response.json();
+              return fetch(defaultCentralPlantUrl);
             case 3:
+              response = _context8.v;
+              _context8.n = 4;
+              return response.json();
+            case 4:
               data = _context8.v;
               // Store current scene data even for default scene
               component.currentSceneData = data;
 
               // Use the consolidated scene loading function (treat as imported to ensure consistent behavior)
-              _context8.n = 4;
+              _context8.n = 5;
               return this.loadSceneFromData(data);
-            case 4:
-              _context8.n = 6;
-              break;
             case 5:
-              _context8.p = 5;
+              _context8.n = 7;
+              break;
+            case 6:
+              _context8.p = 6;
               _t4 = _context8.v;
               console.error('Error loading default scene:', _t4);
-            case 6:
+            case 7:
               return _context8.a(2);
           }
-        }, _callee8, this, [[1, 5]]);
+        }, _callee8, this, [[1, 6]]);
       }));
       function loadScene() {
         return _loadScene.apply(this, arguments);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2112-lab/central-plant",
-  "version": "0.3.55",
+  "version": "0.3.57",
   "description": "Utility modules for the Central Plant Application",
   "main": "dist/bundle/index.js",
   "module": "dist/esm/src/index.js",