@lwrjs/loader 0.22.9 → 0.22.11

package/build/modules/lwr/loaderLegacy/loaderLegacy.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 v0.22.9 */
+/* LWR Legacy Module Loader v0.22.11 */
 const templateRegex = /\{([0-9]+)\}/g;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function templateString(template, args) {
@@ -143,7 +143,7 @@ const NO_IMPORT_LOADER = Object.freeze({
     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}"',
@@ -1399,9 +1399,10 @@ function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else {
 
 
 
+
 /**
  * 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)
@@ -1414,7 +1415,7 @@ function validateLoadSpecifier(
     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
@@ -1430,6 +1431,18 @@ function validateLoadSpecifier(
         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);
@@ -1448,7 +1461,8 @@ function getMatch(path, matchObj) {
         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) {
@@ -1457,6 +1471,27 @@ function targetWarning(match, target, msg) {
     }
 }
 
+/**
+ * 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
  *
@@ -1578,7 +1613,8 @@ function resolveAndComposePackages(
         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);
         }
     }
 }
@@ -1629,6 +1665,20 @@ class ImportMapResolver  {
     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);
+            }
+        }
+    }
 }
 
 /**
@@ -1700,15 +1750,134 @@ async function evaluateImportMaps(baseUrl) {
     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) {
@@ -1794,6 +1963,7 @@ class Loader {
             LoaderError,
             NO_IMPORT_LWC,
             NO_IMPORT_LOADER,
+            NO_IMPORT_TRANSPORT,
             NO_BLOB_IMPORT,
         });
         return this.registry.load(id, importer);
@@ -1836,10 +2006,13 @@ class Loader {
             // 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;
         }
     }
 
@@ -1852,6 +2025,35 @@ class Loader {
         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);
     }

package/build/modules/lwr/loaderLegacy/utils/validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Validation logic for LWR.importMap() API
+ *
+ * This module provides validation functions to ensure that import map updates:
+ * 1. Do not remap protected system modules (lwc, lwr/*, etc.)
+ * 2. Do not use dangerous URL schemes (blob:, data:)
+ * 3. Have well-formed specifiers and URIs
+ */
+import type { ImportMapUpdate } from '../../../../types.js';
+import type { ImportMap } from '../importMap/importMap.js';
+/**
+ * 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
+ */
+export declare function isProtectedSpecifier(specifier: string): boolean;
+/**
+ * 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
+ */
+export declare function validateMappingUri(uri: string, specifier: string): void;
+/**
+ * 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
+ */
+export declare function validateSpecifier(specifier: string): void;
+/**
+ * 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
+ */
+export declare function validateAndConvertImportMapUpdate(update: ImportMapUpdate): ImportMap | null;
+//# sourceMappingURL=validation.d.ts.map

package/build/modules/lwr/loaderLegacy/utils/validation.js

@@ -0,0 +1,114 @@
+/**
+ * Validation logic for LWR.importMap() API
+ *
+ * This module provides validation functions to ensure that import map updates:
+ * 1. Do not remap protected system modules (lwc, lwr/*, etc.)
+ * 2. Do not use dangerous URL schemes (blob:, data:)
+ * 3. Have well-formed specifiers and URIs
+ */
+import { hasConsole } from '../utils/dom.js';
+/**
+ * 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,
+    /^lwc\/v\//i,
+    /^@lwc\//i,
+    /^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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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,
+    };
+}
+//# sourceMappingURL=validation.js.map

package/build/shim/defineCacheResolver.d.ts

@@ -0,0 +1,10 @@
+import type { DefineArguments, DefineArgsInput, ParseDefineResult, ResolvedLoader } from '../types.js';
+/**
+ * Parse AMD define args. Supports define(id, deps, factory).
+ */
+export declare function parseDefine(def: DefineArgsInput): ParseDefineResult;
+/**
+ * Resolve the loader's dependencies from defineCache. Throws if definition is invalid or deps cannot be resolved.
+ */
+export declare function resolveLoaderDepsFromDefineCache(loaderSpecifier: string, definition: DefineArguments, defineCache: Record<string, DefineArguments>): ResolvedLoader;
+//# sourceMappingURL=defineCacheResolver.d.ts.map

package/build/shim/defineCacheResolver.js

@@ -0,0 +1,78 @@
+/**
+ * Parse AMD define args. Supports define(id, deps, factory).
+ */
+export 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.
+ */
+export 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}`);
+    }
+}
+//# sourceMappingURL=defineCacheResolver.js.map

package/build/shim/loader.d.ts

@@ -1,3 +1,7 @@
 import type { DefineArguments, FingerprintsLoaderAPI as LoaderAPI, FingerprintsLoaderConfig as LoaderConfig } from '../types.js';
-export declare function createLoader(name: string, definition: DefineArguments, config: LoaderConfig, externalModules?: string[]): LoaderAPI;
+/**
+ * Create a loader from a definition. Original API preserved.
+ * Optional defineCache for resolving loader deps (when loader has dependencies).
+ */
+export declare function createLoader(name: string, definition: DefineArguments, config: LoaderConfig, externalModules?: string[], defineCache?: Record<string, DefineArguments>): LoaderAPI;
 //# sourceMappingURL=loader.d.ts.map

package/build/shim/loader.js

@@ -1,10 +1,21 @@
-export function createLoader(name, definition, config, externalModules) {
+import { resolveLoaderDepsFromDefineCache } from './defineCacheResolver.js';
+/**
+ * Create a loader from a definition. Original API preserved.
+ * Optional defineCache for resolving loader deps (when loader has dependencies).
+ */
+export 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');

package/build/shim/shim.js

@@ -112,7 +112,7 @@ export default class LoaderShim {
                     rootComponents: this.config.rootComponents,
                 },
             };
-            const loader = createLoader(this.loaderSpecifier, this.defineCache[this.loaderSpecifier], loaderConfig, this.config.preloadModules);
+            const loader = createLoader(this.loaderSpecifier, this.defineCache[this.loaderSpecifier], loaderConfig, this.config.preloadModules, this.defineCache);
             this.mountApp(loader);
             if (loader &&
                 typeof loader.getModuleWarnings === 'function' &&
@@ -134,6 +134,7 @@ export default class LoaderShim {
                 resolve();
             }
             else {
+                /* istanbul ignore next */
                 const observer = new MutationObserver(() => {
                     // eslint-disable-next-line lwr/no-unguarded-apis
                     if (document.body) {
@@ -198,7 +199,7 @@ export default class LoaderShim {
         ])
             .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) {

package/build/shim-legacy/loaderLegacy.d.ts

@@ -1,3 +1,8 @@
-import type { LoaderConfig, DefineArguments, LoaderAPI } from '../types.js';
-export declare function createLoader(name: string, definition: DefineArguments, config: LoaderConfig, externalModules?: string[]): LoaderAPI;
+import type { LoaderAPI, LoaderConfig, DefineArguments } from '../types.js';
+/**
+ * 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.
+ */
+export declare function createLoader(name: string, definition: DefineArguments, config: LoaderConfig, externalModules?: string[], defineCache?: Record<string, DefineArguments>): LoaderAPI;
 //# sourceMappingURL=loaderLegacy.d.ts.map

package/build/shim-legacy/loaderLegacy.js

@@ -1,16 +1,27 @@
-export function createLoader(name, definition, config, externalModules) {
+import { resolveLoaderDepsFromDefineCache } from '../shim/defineCacheResolver.js';
+/**
+ * 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.
+ */
+export 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);
     }