@lwrjs/loader 0.22.9 → 0.22.11

package/build/assets/prod/lwr-loader-shim-legacy.bundle.js

@@ -4,7 +4,7 @@
 * SPDX-License-Identifier: MIT
 * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
 */
-/* LWR Legacy Module Loader Shim v0.22.9 */
+/* LWR Legacy Module Loader Shim v0.22.11 */
 (function () {
   'use strict';
 
@@ -105,26 +105,121 @@
     }
   }
 
+  /**
+   * Parse AMD define args. Supports define(id, deps, factory).
+   */
+  function parseDefine(def) {
+      const [, depsOrFactory, factory] = def;
+      if (Array.isArray(depsOrFactory) && typeof factory === 'function') {
+          return { deps: depsOrFactory, factory };
+      }
+      if (typeof depsOrFactory === 'function') {
+          return { deps: [], factory: depsOrFactory };
+      }
+      throw new Error('Invalid module definition');
+  }
+
+  /**
+   * Resolve a loader dependency: 'exports' returns the bag; otherwise look up in cache and instantiate.
+   * Loader deps are assumed to be leaf modules (no deps of their own)—no recursive resolution.
+   */
+  function resolveDep(dep, exportsObj, cache) {
+      if (dep === 'exports') return exportsObj;
+      const mod = cache[dep];
+      if (!mod) {
+          throw new Error(`Dependency "${dep}" not found in defineCache for loader`);
+      }
+      try {
+          return instantiateLeafModule(mod);
+      } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          throw new Error(`Loader dependency "${dep}" has invalid definition: ${msg}`);
+      }
+  }
+
+  /**
+   * Instantiate a leaf module (loader dep). Assumes the module has no dependencies of its own.
+   * Supports only deps: [] or ['exports']; any other dep list throws.
+   */
+  function instantiateLeafModule(def) {
+      const { deps, factory } = parseDefine(def);
+      if (deps.length > 1 || (deps.length === 1 && deps[0] !== 'exports')) {
+          throw new Error(
+              `Loader dependencies must have no deps or only ['exports']; got [${deps.join(', ')}]`,
+          );
+      }
+      const exports = {};
+      const out = factory(exports);
+      return out !== undefined ? out : exports;
+  }
+
+  /**
+   * Normalize loader definition to canonical (exports, ...deps). Injects 'exports' if missing.
+   */
+  function normalizeLoaderDefinition(def) {
+      const { deps, factory } = parseDefine(def);
+      if (deps.includes('exports')) {
+          return { deps, factory };
+      }
+      const isEmptyDeps = deps.length === 0;
+      const normalizedFactory = (exports, ...rest) => {
+          const result = isEmptyDeps ? factory(exports) : factory(...rest);
+          if (result !== undefined && typeof result === 'object') {
+              Object.assign(exports, result);
+          }
+      };
+      return { deps: ['exports', ...deps], factory: normalizedFactory };
+  }
+
+  /**
+   * Resolve the loader's dependencies from defineCache. Throws if definition is invalid or deps cannot be resolved.
+   */
+  function resolveLoaderDepsFromDefineCache(
+      loaderSpecifier,
+      definition,
+      defineCache,
+  ) {
+      try {
+          const { deps, factory } = normalizeLoaderDefinition(definition);
+          const exportsObj = {};
+          const args = deps.map((dep) => resolveDep(dep, exportsObj, defineCache)) ;
+          return { factory: factory , args, exportsObj };
+      } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          throw new Error(`Expected loader with specifier "${loaderSpecifier}" to be a module. ${msg}`);
+      }
+  }
+
+  /**
+   * Create a loader from a definition. Original API preserved.
+   * Optional defineCache for resolving loader deps.
+   * definition[3] (signatures: ownHash, hashes) is passed to loader.define for cache invalidation.
+   */
   function createLoader(
       name,
       definition,
       config,
       externalModules,
+      defineCache,
   ) {
       if (!definition || typeof definition[2] !== 'function') {
           throw new Error(`Expected loader with specifier "${name}" to be a module`);
       }
 
-      // Create a Loader instance
       const exports = {};
-      definition[2].call(null, exports);
+      if (defineCache) {
+          const { factory, args, exportsObj } = resolveLoaderDepsFromDefineCache(name, definition, defineCache);
+          factory(...args);
+          Object.assign(exports, exportsObj);
+      } else {
+          definition[2].call(null, exports);
+      }
       const { Loader } = exports;
       if (!Loader) {
           throw new Error('Expected Loader class to be defined');
       }
       const loader = new Loader(config);
 
-      // register externally loaded modules
       if (externalModules && externalModules.length) {
           loader.registerExternalModules(externalModules);
       }
@@ -181,9 +276,164 @@
       }
   }
 
-  /* global document, process, console */
+  /* eslint-disable lwr/no-unguarded-apis */
+
+  const hasConsole$1 = typeof console !== 'undefined';
+
+  const hasProcess$1 = typeof process !== 'undefined';
+
+  // eslint-disable-next-line no-undef
+  hasProcess$1 && process.env;
+
+  /**
+   * List of protected module patterns that cannot be remapped.
+   * Uses case-insensitive matching to prevent bypass attempts (e.g., HF-1027).
+   */
+  const PROTECTED_PATTERNS = [
+      /^lwc$/i, // Core LWC
+      /^lwc\/v\//i, // Versioned LWC variants
+      /^@lwc\//i, // LWC scoped packages
+      /^lightningmobileruntime\//i, // Lightning mobile runtime
+  ];
+
+  /**
+   * Checks if a specifier matches any protected module pattern.
+   *
+   * @param specifier - The module specifier to check
+   * @returns true if the specifier is protected, false otherwise
+   */
+  function isProtectedSpecifier(specifier) {
+      return PROTECTED_PATTERNS.some((pattern) => pattern.test(specifier));
+  }
+
+  /**
+   * Validates that a URI does not use dangerous URL schemes.
+   *
+   * Blocks:
+   * - blob: URLs (HF-1027 bypass prevention) - case-insensitive
+   * - data: URLs (inline code injection) - case-insensitive
+   *
+   * @param uri - The URI to validate
+   * @param specifier - The specifier being mapped (for error messages)
+   * @throws Error if the URI uses a dangerous scheme
+   */
+  function validateMappingUri(uri, specifier) {
+      const lowerUri = uri.toLowerCase();
+
+      if (lowerUri.startsWith('blob:')) {
+          throw new Error(`Cannot map ${specifier} to blob: URL`);
+      }
+
+      if (lowerUri.startsWith('data:')) {
+          throw new Error(`Cannot map ${specifier} to data: URL`);
+      }
+  }
+
+  /**
+   * Validates that a specifier is well-formed and not protected.
+   *
+   * @param specifier - The module specifier to validate
+   * @throws Error if the specifier is invalid or protected
+   */
+  function validateSpecifier(specifier) {
+      if (typeof specifier !== 'string' || specifier.length === 0) {
+          throw new Error('Specifier must be a non-empty string');
+      }
+
+      if (isProtectedSpecifier(specifier)) {
+          throw new Error(`Cannot remap protected module: ${specifier}`);
+      }
+  }
+
+  /**
+   * Validates and converts an ImportMapUpdate to ImportMap format.
+   *
+   * Performs validation checks and then converts from:
+   *   { moduleScriptURL: [moduleName1, moduleName2] }
+   * To:
+   *   { imports: { moduleName1: moduleScriptURL, moduleName2: moduleScriptURL } }
+   *
+   * @param update - The ImportMapUpdate object to validate and convert
+   * @returns The converted ImportMap, or null if the update is empty
+   * @throws Error if any validation fails
+   */
+  function validateAndConvertImportMapUpdate(update) {
+      if (!update || typeof update !== 'object') {
+          throw new Error('LWR.importMap() requires an object argument');
+      }
 
+      // Check if update is empty
+      const entries = Object.entries(update);
+      if (entries.length === 0) {
+          if (hasConsole$1) {
+              // eslint-disable-next-line lwr/no-unguarded-apis
+              console.warn('LWR.importMap() called with empty update object');
+          }
+          return null;
+      }
 
+      const convertedImports = {};
+
+      for (const [moduleScriptURL, moduleNames] of entries) {
+          if (!Array.isArray(moduleNames)) {
+              throw new Error('moduleNames must be an array');
+          }
+
+          if (!moduleScriptURL || typeof moduleScriptURL !== 'string') {
+              throw new Error('moduleScriptURL must be a string');
+          }
+
+          validateMappingUri(moduleScriptURL, moduleScriptURL);
+
+          for (const moduleName of moduleNames) {
+              validateSpecifier(moduleName);
+              if (moduleName in convertedImports) {
+                  if (hasConsole$1) {
+                      // eslint-disable-next-line lwr/no-unguarded-apis
+                      console.warn(
+                          `LWR.importMap(): duplicate module "${moduleName}" — already mapped to "${convertedImports[moduleName]}", ignoring mapping to "${moduleScriptURL}"`,
+                      );
+                  }
+              } else {
+                  convertedImports[moduleName] = moduleScriptURL;
+              }
+          }
+      }
+
+      return {
+          imports: convertedImports,
+      };
+  }
+
+  function targetWarning(match, target, msg) {
+      if (hasConsole$1) {
+          // eslint-disable-next-line lwr/no-unguarded-apis, no-undef
+          console.warn('Package target ' + msg + ", resolving target '" + target + "' for " + match);
+      }
+  }
+
+  /**
+   * Import map entries are write-once: once a specifier is mapped, it cannot be overridden.
+   * This ensures deterministic module resolution and prevents runtime mutation of previously
+   * resolved dependencies. Conflicting mappings are ignored with a warning.
+   *
+   * Merges a single import map entry into a target imports object.
+   * - If the specifier doesn't exist, it is added.
+   * - If it exists with the same value, it is silently skipped.
+   * - If it exists with a different value, a warning is logged and the entry is skipped.
+   */
+  function mergeImportMapEntry(specifier, uri, target) {
+      const existing = target[specifier];
+      if (existing !== undefined) {
+          if (existing !== uri) {
+              targetWarning(specifier, uri, `already mapped to "${existing}", ignoring conflicting mapping`);
+          }
+      } else {
+          target[specifier] = uri;
+      }
+  }
+
+  function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }/* global document, process, console */
 
   /* eslint-disable lwr/no-unguarded-apis */
   const hasSetTimeout = typeof setTimeout === 'function';
@@ -198,10 +448,11 @@
       
        __init() {this.defineCache = {};}
        __init2() {this.orderedDefs = [];}
+       __init3() {this.importMapUpdatesCache = {};}
       
        // eslint-disable-line no-undef, lwr/no-unguarded-apis
 
-      constructor(global) {LoaderShim.prototype.__init.call(this);LoaderShim.prototype.__init2.call(this);
+      constructor(global) {LoaderShim.prototype.__init.call(this);LoaderShim.prototype.__init2.call(this);LoaderShim.prototype.__init3.call(this);
           // Start watchdog timer
           if (hasSetTimeout) {
               this.watchdogTimerId = this.startWatchdogTimer();
@@ -210,14 +461,16 @@
           // Parse configuration
           this.global = global;
           this.config = global.LWR ;
-          this.loaderModule = 'lwr/loaderLegacy/v/0_22_9';
+          this.loaderModule = 'lwr/loaderLegacy/v/0_22_11';
 
           // Set up error handler
           this.errorHandler = this.config.onError ;
 
-          // Set up the temporary LWR.define function and customInit hook
+          // Set up the temporary LWR.define and LWR.importMap functions
           const tempDefine = this.tempDefine.bind(this);
           global.LWR.define = tempDefine;
+          const tempImportMapMethod = this.tempImportMap.bind(this);
+          global.LWR.importMap = tempImportMapMethod;
           this.bootReady = this.config.autoBoot;
 
           try {
@@ -273,6 +526,53 @@
           }
       }
 
+      /**
+       * Create a temporary LWR.importMap() function which captures all
+       * import map updates that occur BEFORE the full loader module is available
+       *
+       * Each import map update is validated, converted to moduleName -> URL mapping,
+       * and merged into the importMapUpdatesCache with write-once protection
+       */
+       tempImportMap(importMapUpdate) {
+          try {
+              // Validate and convert the import map update to { imports: { moduleName: moduleScriptURL } }
+              const importMap = validateAndConvertImportMapUpdate(importMapUpdate);
+
+              // Early return if update was empty
+              if (!importMap) {
+                  return;
+              }
+
+              // Merge into cache with write-once protection
+              for (const [moduleName, moduleScriptURL] of Object.entries(importMap.imports)) {
+                  mergeImportMapEntry(moduleName, moduleScriptURL, this.importMapUpdatesCache);
+              }
+          } catch (e) {
+              this.enterErrorState(e);
+          }
+      }
+
+      /**
+       * Apply all cached import map updates and merge with bootstrap import map
+       * Returns merged import map
+       */
+       getImportMappingsWithUpdates() {
+          // Start with bootstrap import map
+          // Cast importMappings from object to ImportMap to access properties
+          const bootstrapMappings = this.config.importMappings ;
+
+          // Merge with write-once protection: bootstrap mappings take precedence
+          const mergedImports = { ...(_optionalChain([bootstrapMappings, 'optionalAccess', _ => _.imports]) || {}) };
+          for (const [specifier, uri] of Object.entries(this.importMapUpdatesCache)) {
+              mergeImportMapEntry(specifier, uri, mergedImports);
+          }
+
+          return {
+              ...(bootstrapMappings || {}),
+              imports: mergedImports,
+          };
+      }
+
       // Called by the customInit hook via lwr.initializeApp()
        postCustomInit() {
           this.bootReady = true;
@@ -305,6 +605,7 @@
                   this.defineCache[this.loaderModule],
                   loaderConfig,
                   this.config.preloadModules,
+                  this.defineCache,
               );
               this.mountApp(loader);
               if (
@@ -360,17 +661,19 @@
           const exporter = (exports) => {
               Object.assign(exports, { logOperationStart, logOperationEnd });
           };
-          define('lwr/profiler/v/0_22_9', ['exports'], exporter, {});
+          define('lwr/profiler/v/0_22_11', ['exports'], exporter, {});
       }
 
       // Set up the application globals, import map, root custom element...
        mountApp(loader) {
-          const { bootstrapModule, rootComponent, importMappings, rootComponents, serverData, endpoints } =
-              this.config;
+          const { bootstrapModule, rootComponent, rootComponents, serverData, endpoints } = this.config;
+
+          const importMappings = this.getImportMappingsWithUpdates();
 
           // Set global LWR.define to loader.define
           this.global.LWR = Object.freeze({
               define: loader.define.bind(loader),
+              importMap: loader.importMap.bind(loader),
               rootComponent,
               rootComponents,
               serverData: serverData || {},
@@ -395,7 +698,7 @@
               .registerImportMappings(importMappings)
               .then(() => {
                   // eslint-disable-next-line lwr/no-unguarded-apis
-                  if (typeof window === 'undefined' || typeof document === undefined) {
+                  if (typeof window === 'undefined' || typeof document === 'undefined') {
                       return Promise.resolve();
                   }
                   if (initDeferDOM) {
@@ -455,14 +758,14 @@
   // The loader module is ALWAYS required
   const GLOBAL = globalThis ;
   GLOBAL.LWR.requiredModules = GLOBAL.LWR.requiredModules || [];
-  if (GLOBAL.LWR.requiredModules.indexOf('lwr/loaderLegacy/v/0_22_9') < 0) {
-      GLOBAL.LWR.requiredModules.push('lwr/loaderLegacy/v/0_22_9');
+  if (GLOBAL.LWR.requiredModules.indexOf('lwr/loaderLegacy/v/0_22_11') < 0) {
+      GLOBAL.LWR.requiredModules.push('lwr/loaderLegacy/v/0_22_11');
   }
   new LoaderShim(GLOBAL);
 
 })();
 
-LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use strict';
+LWR.define('lwr/loaderLegacy/v/0_22_11', ['exports'], (function (exports) { 'use strict';
 
     const templateRegex = /\{([0-9]+)\}/g;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -602,7 +905,7 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
         level: 0,
         message: 'Cannot dynamically import the LWR loader with importer "{0}"',
     });
-    Object.freeze({
+    const NO_IMPORT_TRANSPORT = Object.freeze({
         code: 3025,
         level: 0,
         message: 'Cannot dynamically import "transport" with importer "{0}"',
@@ -1857,9 +2160,10 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
 
 
 
+
     /**
      * Validates that the given module id is not one of the forbidden dynamic import specifiers.
-     * Throws LoaderError for: lwc, the LWR loader, and blob URLs.
+     * Throws LoaderError for: lwc, the LWR loader, transport/webruntime/transport, and blob URLs.
      *
      * @param id - Module identifier or URL
      * @param importer - Versioned specifier of the module importer (for error reporting)
@@ -1872,7 +2176,7 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
         loaderSpecifier,
         errors,
     ) {
-        const { LoaderError, NO_IMPORT_LWC, NO_IMPORT_LOADER, NO_BLOB_IMPORT } = errors;
+        const { LoaderError, NO_IMPORT_LWC, NO_IMPORT_LOADER, NO_IMPORT_TRANSPORT, NO_BLOB_IMPORT } = errors;
 
         // Throw an error if the specifier is "lwc" or a versioned lwc specifier
         // Dynamic import of LWC APIs is not allowed
@@ -1888,6 +2192,18 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
             throw new LoaderError(NO_IMPORT_LOADER, [_nullishCoalesce(importer, () => ( 'unknown'))]);
         }
 
+        // Throw an error if the specifier is "transport" or "webruntime/transport" (or versioned)
+        // Dynamic import of transport exposes unsandboxed fetch, bypassing LWS
+        // Reference: Hackforce report HF-3393
+        if (
+            id === 'transport' ||
+            id.startsWith('transport/v/') ||
+            id === 'webruntime/transport' ||
+            id.startsWith('webruntime/transport/v/')
+        ) {
+            throw new LoaderError(NO_IMPORT_TRANSPORT, [_nullishCoalesce(importer, () => ( 'unknown'))]);
+        }
+
         // Throw an error if the specifier is a blob URL (case-insensitive check)
         if (id.toLowerCase().startsWith('blob:')) {
             throw new LoaderError(NO_BLOB_IMPORT);
@@ -1906,7 +2222,8 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
             if (segment in matchObj) {
                 return segment;
             }
-        } while (path.length > 1 && (sepIndex = path.lastIndexOf('/', sepIndex - 1)) !== -1);
+            sepIndex = path.lastIndexOf('/', sepIndex - 1);
+        } while (sepIndex > 0);
     }
     function targetWarning(match, target, msg) {
         if (hasConsole) {
@@ -1915,6 +2232,27 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
         }
     }
 
+    /**
+     * Import map entries are write-once: once a specifier is mapped, it cannot be overridden.
+     * This ensures deterministic module resolution and prevents runtime mutation of previously
+     * resolved dependencies. Conflicting mappings are ignored with a warning.
+     *
+     * Merges a single import map entry into a target imports object.
+     * - If the specifier doesn't exist, it is added.
+     * - If it exists with the same value, it is silently skipped.
+     * - If it exists with a different value, a warning is logged and the entry is skipped.
+     */
+    function mergeImportMapEntry(specifier, uri, target) {
+        const existing = target[specifier];
+        if (existing !== undefined) {
+            if (existing !== uri) {
+                targetWarning(specifier, uri, `already mapped to "${existing}", ignoring conflicting mapping`);
+            }
+        } else {
+            target[specifier] = uri;
+        }
+    }
+
     /**
      * Import map support for LWR based on the spec: https://github.com/WICG/import-maps
      *
@@ -2036,7 +2374,8 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
             if (!mapped) {
                 targetWarning(p, rhs, 'bare specifier did not resolve');
             } else {
-                outPackages[resolvedLhs] = mapped.uri;
+                // Merge into cache with write-once protection
+                mergeImportMapEntry(resolvedLhs, mapped.uri, outPackages);
             }
         }
     }
@@ -2087,6 +2426,20 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
         resolve(resolvedOrPlain, parentUrl) {
             return resolveImportMapEntry(this.importMap, resolvedOrPlain, parentUrl);
         }
+
+        addImportMapEntries(importMap) {
+            if (importMap.imports) {
+                const current = this.importMap;
+                if (!current.imports) {
+                    current.imports = {};
+                }
+
+                // Merge into cache with write-once protection
+                for (const specifier in importMap.imports) {
+                    mergeImportMapEntry(specifier, importMap.imports[specifier], current.imports);
+                }
+            }
+        }
     }
 
     /**
@@ -2158,15 +2511,134 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
         return importMapPromise;
     }
 
-    function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+    /**
+     * List of protected module patterns that cannot be remapped.
+     * Uses case-insensitive matching to prevent bypass attempts (e.g., HF-1027).
+     */
+    const PROTECTED_PATTERNS = [
+        /^lwc$/i, // Core LWC
+        /^lwc\/v\//i, // Versioned LWC variants
+        /^@lwc\//i, // LWC scoped packages
+        /^lightningmobileruntime\//i, // Lightning mobile runtime
+    ];
+
+    /**
+     * Checks if a specifier matches any protected module pattern.
+     *
+     * @param specifier - The module specifier to check
+     * @returns true if the specifier is protected, false otherwise
+     */
+    function isProtectedSpecifier(specifier) {
+        return PROTECTED_PATTERNS.some((pattern) => pattern.test(specifier));
+    }
+
+    /**
+     * Validates that a URI does not use dangerous URL schemes.
+     *
+     * Blocks:
+     * - blob: URLs (HF-1027 bypass prevention) - case-insensitive
+     * - data: URLs (inline code injection) - case-insensitive
+     *
+     * @param uri - The URI to validate
+     * @param specifier - The specifier being mapped (for error messages)
+     * @throws Error if the URI uses a dangerous scheme
+     */
+    function validateMappingUri(uri, specifier) {
+        const lowerUri = uri.toLowerCase();
+
+        if (lowerUri.startsWith('blob:')) {
+            throw new Error(`Cannot map ${specifier} to blob: URL`);
+        }
 
+        if (lowerUri.startsWith('data:')) {
+            throw new Error(`Cannot map ${specifier} to data: URL`);
+        }
+    }
 
+    /**
+     * Validates that a specifier is well-formed and not protected.
+     *
+     * @param specifier - The module specifier to validate
+     * @throws Error if the specifier is invalid or protected
+     */
+    function validateSpecifier(specifier) {
+        if (typeof specifier !== 'string' || specifier.length === 0) {
+            throw new Error('Specifier must be a non-empty string');
+        }
+
+        if (isProtectedSpecifier(specifier)) {
+            throw new Error(`Cannot remap protected module: ${specifier}`);
+        }
+    }
+
+    /**
+     * Validates and converts an ImportMapUpdate to ImportMap format.
+     *
+     * Performs validation checks and then converts from:
+     *   { moduleScriptURL: [moduleName1, moduleName2] }
+     * To:
+     *   { imports: { moduleName1: moduleScriptURL, moduleName2: moduleScriptURL } }
+     *
+     * @param update - The ImportMapUpdate object to validate and convert
+     * @returns The converted ImportMap, or null if the update is empty
+     * @throws Error if any validation fails
+     */
+    function validateAndConvertImportMapUpdate(update) {
+        if (!update || typeof update !== 'object') {
+            throw new Error('LWR.importMap() requires an object argument');
+        }
+
+        // Check if update is empty
+        const entries = Object.entries(update);
+        if (entries.length === 0) {
+            if (hasConsole) {
+                // eslint-disable-next-line lwr/no-unguarded-apis
+                console.warn('LWR.importMap() called with empty update object');
+            }
+            return null;
+        }
+
+        const convertedImports = {};
+
+        for (const [moduleScriptURL, moduleNames] of entries) {
+            if (!Array.isArray(moduleNames)) {
+                throw new Error('moduleNames must be an array');
+            }
+
+            if (!moduleScriptURL || typeof moduleScriptURL !== 'string') {
+                throw new Error('moduleScriptURL must be a string');
+            }
+
+            validateMappingUri(moduleScriptURL, moduleScriptURL);
+
+            for (const moduleName of moduleNames) {
+                validateSpecifier(moduleName);
+                if (moduleName in convertedImports) {
+                    if (hasConsole) {
+                        // eslint-disable-next-line lwr/no-unguarded-apis
+                        console.warn(
+                            `LWR.importMap(): duplicate module "${moduleName}" — already mapped to "${convertedImports[moduleName]}", ignoring mapping to "${moduleScriptURL}"`,
+                        );
+                    }
+                } else {
+                    convertedImports[moduleName] = moduleScriptURL;
+                }
+            }
+        }
+
+        return {
+            imports: convertedImports,
+        };
+    }
+
+    function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
     /**
      * The LWR loader is inspired and borrows from the algorithms and native browser principles of https://github.com/systemjs/systemjs
      */
     class Loader {
         
         
+        
 
         
         constructor(config) {
@@ -2252,6 +2724,7 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
                 LoaderError,
                 NO_IMPORT_LWC,
                 NO_IMPORT_LOADER,
+                NO_IMPORT_TRANSPORT,
                 NO_BLOB_IMPORT,
             });
             return this.registry.load(id, importer);
@@ -2294,10 +2767,13 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
                 // import maps spec if we do this after resolving any imports
                 importMap = resolveAndComposeImportMap(mappings, this.baseUrl, this.parentImportMap);
             }
-            this.parentImportMap = importMap;
-            if (this.parentImportMap) {
-                const importMapResolver = new ImportMapResolver(this.parentImportMap);
-                this.registry.setImportResolver(importMapResolver);
+            if (importMap) {
+                if (this.importMapResolver || this.parentImportMap) {
+                    throw new LoaderError(BAD_IMPORT_MAP);
+                }
+                this.importMapResolver = new ImportMapResolver(importMap);
+                this.registry.setImportResolver(this.importMapResolver);
+                this.parentImportMap = this.importMapResolver.importMap;
             }
         }
 
@@ -2310,6 +2786,35 @@ LWR.define('lwr/loaderLegacy/v/0_22_9', ['exports'], (function (exports) { 'use
             this.registry.registerExternalModules(modules);
         }
 
+        /**
+         * Apply import map updates at runtime.
+         * Enables adding new import mappings dynamically.
+         *
+         * @param updates - Import Map Update object containing:
+        -   [moduleScriptURL] - Script URL containing LWR define statements
+        -   string[] - array of module names which are included in the given script
+         */
+        importMap(update) {
+            // Validate and convert the import map update to the ImportMap format (moduleName -> moduleScriptURL)
+            const importMap = validateAndConvertImportMapUpdate(update);
+
+            // Early return if update was empty
+            if (!importMap) {
+                return;
+            }
+
+            if (!this.parentImportMap || !this.importMapResolver) {
+                throw new LoaderError(BAD_IMPORT_MAP);
+            }
+
+            // Merge the new mappings with the base import map - note this goes against
+            // import maps spec if we do this after resolving any imports
+            const resolvedImportMap = resolveAndComposeImportMap(importMap, this.baseUrl, this.parentImportMap);
+
+            this.importMapResolver.addImportMapEntries(resolvedImportMap);
+            this.parentImportMap = this.importMapResolver.importMap;
+        }
+
         getModuleWarnings(isAppMounted = false) {
             return this.registry.getModuleWarnings(isAppMounted);
         }