@equinor/fusion-framework-vite-plugin-spa 4.0.12 → 4.0.14

package/dist/html/bootstrap.js

@@ -5093,6 +5093,7 @@ class BaseConfigBuilder {
      * If a function is provided as `value_or_cb`, it will be used as a callback for deferred or computed configuration values.
      * Otherwise, the value is wrapped in an async function for consistency.
      *
+     * @template TTarget - The dot-path string representing the target property in the configuration.
      * @protected
      * @sealed
      */
@@ -5105,6 +5106,7 @@ class BaseConfigBuilder {
      *
      * @param target - The target path in the configuration to retrieve the callback for.
      * @returns The configuration builder callback for the specified target, or `undefined` if no callback is registered.
+     * @template TTarget - The dot-path string representing the target property in the configuration.
      * @protected
      * @sealed
      */
@@ -5115,6 +5117,7 @@ class BaseConfigBuilder {
      * Checks if the given target path exists in the configuration callbacks.
      * @param target - The target path to check.
      * @returns `true` if the target path exists in the configuration callbacks, `false` otherwise.
+     * @template TTarget - The dot-path string representing the target property in the configuration.
      * @protected
      * @sealed
      */
@@ -5168,9 +5171,12 @@ class BaseConfigBuilder {
      * @readonly
      */
     _buildConfig(init, initial) {
+        // Execute every registered config callback and collect its target-value pair
         return from(Object.entries(this.#configCallbacks)).pipe(
         // Transform each config callback into a target-value pair
-        mergeMap(([target, cb]) => from(cb(init)).pipe(
+        mergeMap(([target, cb]) => 
+        // Run the callback and shape its result into a target-value pair, skipping void results
+        from(cb(init)).pipe(
         // Filter out undefined values, mostly for void return types
         filter((value) => value !== undefined), 
         // Map the value to a target-value pair
@@ -5225,6 +5231,9 @@ class BaseConfigBuilder {
  * Indicates a circular dependency or a module that never resolves.
  */
 class RequiredModuleTimeoutError extends Error {
+    /**
+     * Creates a new `RequiredModuleTimeoutError`.
+     */
     constructor() {
         super('Module initialization timed out');
         this.name = 'RequiredModuleTimeoutError';
@@ -5233,6 +5242,7 @@ class RequiredModuleTimeoutError extends Error {
 
 /** Shared base segment for module configurator lifecycle event names. */
 const ModuleConfiguratorEventBaseName = 'ModuleConfigurator';
+
 /**
  * Event names emitted by `ModulesConfigurator` and its lifecycle phase helpers.
  *
@@ -5291,7 +5301,6 @@ const ModuleConfiguratorEventName = {
     ModulesDisposed: `${ModuleConfiguratorEventBaseName}.modules.disposed`,
 };
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Defines the severity levels for module events.
  * Used to categorize events by their importance and impact.
@@ -5324,10 +5333,13 @@ var ModuleEventLevel;
  * @param ctx - The configure phase context.
  * @param ref - Optional reference forwarded to each module's configure factory.
  * @returns A promise resolving to the merged module config map.
+ * @template TRef - Reference type forwarded to module configure hooks.
+ * @throws Re-throws any error from a module's `configure` factory after emitting a failure event.
  * @internal
  */
 async function createModuleConfigs(ctx, ref) {
     const { modules, afterConfiguration, afterInit, registerEvent } = ctx;
+    // Run each module's configure factory concurrently and track timing/failures
     const config$ = from(modules).pipe(mergeMap(async (module) => {
         const configStart = performance.now();
         try {
@@ -5360,7 +5372,11 @@ async function createModuleConfigs(ctx, ref) {
             });
             throw err;
         }
-    }), reduce((acc, module) => Object.assign(acc, module), 
+    }), reduce((acc, module) => {
+        // Merge each module's config object into the shared accumulator
+        const merged = Object.assign(acc, module);
+        return merged;
+    }, 
     // Seed the config object with hooks so modules can register post-phase callbacks
     // during their own configure factory (a common pattern for cross-module wiring).
     {
@@ -5373,6 +5389,7 @@ async function createModuleConfigs(ctx, ref) {
     }));
     return lastValueFrom(config$);
 }
+
 /**
  * Runs the post-configure phase: calls each module's `postConfigure` hook and
  * then invokes all registered `afterConfiguration` callbacks.
@@ -5383,14 +5400,19 @@ async function createModuleConfigs(ctx, ref) {
  * @param ctx - The configure phase context.
  * @param config - The merged module config map produced by {@link createModuleConfigs}.
  * @returns A promise resolving when all post-configure hooks have settled.
+ * @template TRef - Reference type forwarded to module configure hooks.
  * @internal
  */
-async function runPostConfigureHooks(ctx, config) {
+async function runPostConfigureHooks(ctx, 
+// biome-ignore lint/suspicious/noExplicitAny: internal type-erased dispatch — the configure phase coordinates opaque module configs without knowing their concrete shapes
+config) {
     const { modules, afterConfiguration, registerEvent } = ctx;
     // Run each module's postConfigure hook; failures are isolated so one
     // failing module does not prevent others from completing post-configure.
     await Promise.allSettled(modules
+        // Only process modules that define a postConfigure hook
         .filter((module) => !!module.postConfigure)
+        // Call postConfigure on each module that defines the hook
         .map(async (module) => {
         try {
             const postConfigStart = performance.now();
@@ -5419,6 +5441,7 @@ async function runPostConfigureHooks(ctx, config) {
             });
         }
     }));
+    // Skip the afterConfiguration hooks entirely when none are registered
     if (!afterConfiguration.length)
         return;
     // Run all registered afterConfiguration callbacks. These were added either
@@ -5431,7 +5454,9 @@ async function runPostConfigureHooks(ctx, config) {
             message: `Post configure hooks [${afterConfiguration.length}] called`,
         });
         const postConfigHooksStart = performance.now();
-        await Promise.allSettled(afterConfiguration.map((x) => Promise.resolve(x(config))));
+        await Promise.allSettled(afterConfiguration
+            // Invoke every registered afterConfiguration callback with the final config
+            .map((x) => Promise.resolve(x(config))));
         const postConfigHooksTime = Math.round(performance.now() - postConfigHooksStart);
         registerEvent({
             level: ModuleEventLevel.Debug,
@@ -5453,6 +5478,7 @@ async function runPostConfigureHooks(ctx, config) {
         });
     }
 }
+
 /**
  * Runs the full configure lifecycle phase for a set of modules.
  *
@@ -5464,12 +5490,15 @@ async function runPostConfigureHooks(ctx, config) {
  * @param ctx - The configure phase context.
  * @param ref - Optional reference forwarded through all configure hooks.
  * @returns A promise resolving to the fully configured module config map.
+ * @template TRef - Reference type forwarded to module configure hooks.
  */
 async function runConfigurePhase(ctx, ref) {
     // Step 1: Create raw config objects for all registered modules
     const config = await createModuleConfigs(ctx, ref);
     // Step 2: Apply all user-registered configuration callbacks concurrently.
-    await Promise.all(ctx.configs.map((cb) => Promise.resolve(cb(config, ref))));
+    await Promise.all(
+    // Invoke every registered configure callback with the merged config
+    ctx.configs.map((cb) => Promise.resolve(cb(config, ref))));
     // Step 3: Run module postConfigure hooks and afterConfiguration callbacks
     await runPostConfigureHooks(ctx, config);
     return config;
@@ -5519,6 +5548,7 @@ class BaseModuleProvider {
             // where inherited properties are acceptable for instanceof checks
             'version' in instance &&
             'dispose' in instance;
+        // Only coerce version/dispose once the basic shape check has passed
         if (hasStructure) {
             const obj = instance;
             const version = semverExports.coerce(String(obj.version));
@@ -5529,6 +5559,11 @@ class BaseModuleProvider {
     }
     #version;
     #subscriptions;
+    /**
+     * The resolved semantic version of this module provider.
+     *
+     * @returns The provider's semantic version.
+     */
     get version() {
         return this.#version;
     }
@@ -5562,92 +5597,6 @@ class BaseModuleProvider {
     }
 }
 
-/**
- * Initializes a single module and emits a `[name, instance]` tuple when complete.
- *
- * Validates that the module exposes an `initialize` method, calls it with the
- * provided context, and emits lifecycle events for start, completion, and any
- * provider contract warnings.
- *
- * @internal
- */
-async function initializeModule(module, ctx) {
-    const { config, ref, requireInstance, hasModule, registerEvent } = ctx;
-    const key = module.name;
-    if (!module.initialize) {
-        const error = new Error(`Module ${module.name} does not have initialize method`);
-        error.name = 'ModuleInitializeError';
-        registerEvent({
-            level: ModuleEventLevel.Error,
-            name: ModuleConfiguratorEventName.ModuleInitializeError,
-            message: error.message,
-            properties: {
-                moduleName: module.name,
-                moduleVersion: module.version?.toString() || 'unknown',
-            },
-            error,
-        });
-        throw error;
-    }
-    registerEvent({
-        level: ModuleEventLevel.Debug,
-        name: ModuleConfiguratorEventName.ModuleInitializing,
-        message: `Initializing module ${module.name}`,
-        properties: {
-            moduleName: module.name,
-            moduleVersion: module.version?.toString() || 'unknown',
-        },
-    });
-    const moduleInitStart = performance.now();
-    const instance = await module.initialize({
-        ref,
-        config: config[key],
-        requireInstance,
-        hasModule,
-    });
-    // Warn when providers deviate from the expected base class — these modules
-    // may lack version tracking and standard provider interfaces.
-    if (!(instance instanceof BaseModuleProvider)) {
-        registerEvent({
-            level: ModuleEventLevel.Warning,
-            name: ModuleConfiguratorEventName.ProviderNotBaseModuleProvider,
-            message: `Provider for module ${module.name} does not extend BaseModuleProvider`,
-            properties: {
-                moduleName: module.name,
-                moduleVersion: module.version?.toString() || 'unknown',
-            },
-        });
-    }
-    // Providers should expose a version string for diagnostics and compatibility checks.
-    // Warn when absent so module authors catch missing version early rather than at runtime.
-    const maybeVersioned = instance;
-    if (!maybeVersioned.version) {
-        registerEvent({
-            level: ModuleEventLevel.Warning,
-            name: ModuleConfiguratorEventName.ProviderVersionWarning,
-            message: `Provider for module ${module.name} does not expose version`,
-            properties: {
-                moduleName: module.name,
-                moduleVersion: module.version?.toString() || 'unknown',
-            },
-        });
-    }
-    const moduleInitTime = Math.round(performance.now() - moduleInitStart);
-    registerEvent({
-        level: ModuleEventLevel.Debug,
-        name: ModuleConfiguratorEventName.ModuleInitialized,
-        message: `Module ${module.name} initialized in ${moduleInitTime}ms`,
-        properties: {
-            moduleName: module.name,
-            moduleVersion: module.version?.toString() || 'unknown',
-            providerName: typeof instance,
-            providerVersion: maybeVersioned.version?.toString() || 'unknown',
-            moduleInitTime,
-        },
-        metric: moduleInitTime,
-    });
-    return [key, instance];
-}
 /**
  * Creates a `requireInstance` resolver for use during module initialization.
  *
@@ -5660,6 +5609,10 @@ async function initializeModule(module, ctx) {
  * @param instance$ - Shared subject accumulating initialized module instances.
  * @param registerEvent - Function to emit lifecycle events.
  * @returns A `requireInstance` function matching the shape expected by `ModuleInitializerArgs`.
+ * @template T - The shape of the accumulated module instance map.
+ * @throws {Error} When the requested module name was never registered.
+ * @throws {RequiredModuleTimeoutError} When the requested module does not
+ *   initialize within its timeout window.
  * @internal
  */
 function createRequireInstance(moduleNames, instance$, registerEvent) {
@@ -5734,6 +5687,95 @@ function createRequireInstance(moduleNames, instance$, registerEvent) {
         })));
     };
 }
+
+/**
+ * Initializes a single module and emits a `[name, instance]` tuple when complete.
+ *
+ * Validates that the module exposes an `initialize` method, calls it with the
+ * provided context, and emits lifecycle events for start, completion, and any
+ * provider contract warnings.
+ *
+ * @internal
+ */
+async function initializeModule(module, ctx) {
+    const { config, ref, requireInstance, hasModule, registerEvent } = ctx;
+    const key = module.name;
+    // Modules must expose an initialize method to participate in the initialize phase
+    if (!module.initialize) {
+        const error = new Error(`Module ${module.name} does not have initialize method`);
+        error.name = 'ModuleInitializeError';
+        registerEvent({
+            level: ModuleEventLevel.Error,
+            name: ModuleConfiguratorEventName.ModuleInitializeError,
+            message: error.message,
+            properties: {
+                moduleName: module.name,
+                moduleVersion: module.version?.toString() || 'unknown',
+            },
+            error,
+        });
+        throw error;
+    }
+    registerEvent({
+        level: ModuleEventLevel.Debug,
+        name: ModuleConfiguratorEventName.ModuleInitializing,
+        message: `Initializing module ${module.name}`,
+        properties: {
+            moduleName: module.name,
+            moduleVersion: module.version?.toString() || 'unknown',
+        },
+    });
+    const moduleInitStart = performance.now();
+    const instance = await module.initialize({
+        ref,
+        config: config[key],
+        requireInstance,
+        hasModule,
+    });
+    // Warn when providers deviate from the expected base class — these modules
+    // may lack version tracking and standard provider interfaces.
+    if (!(instance instanceof BaseModuleProvider)) {
+        registerEvent({
+            level: ModuleEventLevel.Warning,
+            name: ModuleConfiguratorEventName.ProviderNotBaseModuleProvider,
+            message: `Provider for module ${module.name} does not extend BaseModuleProvider`,
+            properties: {
+                moduleName: module.name,
+                moduleVersion: module.version?.toString() || 'unknown',
+            },
+        });
+    }
+    // Providers should expose a version string for diagnostics and compatibility checks.
+    // Warn when absent so module authors catch missing version early rather than at runtime.
+    const maybeVersioned = instance;
+    // Only warn about missing version metadata now that we know it's actually absent
+    if (!maybeVersioned.version) {
+        registerEvent({
+            level: ModuleEventLevel.Warning,
+            name: ModuleConfiguratorEventName.ProviderVersionWarning,
+            message: `Provider for module ${module.name} does not expose version`,
+            properties: {
+                moduleName: module.name,
+                moduleVersion: module.version?.toString() || 'unknown',
+            },
+        });
+    }
+    const moduleInitTime = Math.round(performance.now() - moduleInitStart);
+    registerEvent({
+        level: ModuleEventLevel.Debug,
+        name: ModuleConfiguratorEventName.ModuleInitialized,
+        message: `Module ${module.name} initialized in ${moduleInitTime}ms`,
+        properties: {
+            moduleName: module.name,
+            moduleVersion: module.version?.toString() || 'unknown',
+            providerName: typeof instance,
+            providerVersion: maybeVersioned.version?.toString() || 'unknown',
+            moduleInitTime,
+        },
+        metric: moduleInitTime,
+    });
+    return [key, instance];
+}
 /**
  * Runs the initialize lifecycle phase for all registered modules.
  *
@@ -5748,6 +5790,7 @@ function createRequireInstance(moduleNames, instance$, registerEvent) {
  * @param config - The merged module config map produced by the configure phase.
  * @param ref - Optional reference forwarded to each module's `initialize` call.
  * @returns A promise resolving to the sealed map of initialized module providers.
+ * @template T - The shape of the resolved module instance map.
  * @throws {Error} When a module's `initialize` method is missing.
  * @throws {RequiredModuleTimeoutError} When a required dependency does not
  *   initialize within its timeout window.
@@ -5759,6 +5802,7 @@ async function runInitializePhase(ctx, config, ref) {
     if (modules.length === 0) {
         return Object.seal({});
     }
+    // Extract module names for dependency lookups before any module has initialized
     const moduleNames = modules.map((m) => m.name);
     // Accumulates initialized module providers; BehaviorSubject lets requireInstance
     // reactively wait for a dependency to appear without polling.
@@ -5773,7 +5817,9 @@ async function runInitializePhase(ctx, config, ref) {
     // Completing the subject signals that all modules are initialized.
     init$.subscribe({
         next: ([name, module]) => {
-            instance$.next(Object.assign(instance$.value, { [name]: module }));
+            // Merge the newly initialized module into the shared instance map without dropping peers
+            const nextInstance = Object.assign(instance$.value, { [name]: module });
+            instance$.next(nextInstance);
         },
         error: (err) => {
             registerEvent({
@@ -5842,7 +5888,9 @@ async function runPostInitializePhase(ctx, instance, ref) {
     });
     // Run postInitialize hooks for modules that declare them. Failures are caught
     // per-module via catchError so one failure does not abort the others.
-    const postInitialize$ = from(modules).pipe(filter((module) => !!module.postInitialize), tap((module) => {
+    const postInitialize$ = from(modules).pipe(
+    // Only process modules that define a postInitialize hook
+    filter((module) => !!module.postInitialize), tap((module) => {
         registerEvent({
             level: ModuleEventLevel.Debug,
             name: ModuleConfiguratorEventName.ModulePostInitializeStart,
@@ -5854,6 +5902,7 @@ async function runPostInitializePhase(ctx, instance, ref) {
         });
     }), mergeMap((module) => {
         const postInitStart = performance.now();
+        // Emit completion/error events for this module's postInitialize call as it settles
         return from(module.postInitialize({
             ref,
             modules: instance,
@@ -5897,6 +5946,7 @@ async function runPostInitializePhase(ctx, instance, ref) {
         properties: { modules: Object.keys(instance).join(', '), postInitTime },
         metric: postInitTime,
     });
+    // Skip the afterInit hooks entirely when none are registered
     if (!afterInit.length) {
         registerEvent({
             level: ModuleEventLevel.Debug,
@@ -5909,32 +5959,40 @@ async function runPostInitializePhase(ctx, instance, ref) {
     // Run all registered afterInit callbacks. These were added either by
     // addConfig's afterInit or via onInitialized on the configurator.
     try {
+        // Build a display string of registered hook names for the start event
+        // Extract each hook's name, falling back for anonymous functions
+        const hookNames = afterInit.map((x) => x.name || 'anonymous').join(', ');
         registerEvent({
             level: ModuleEventLevel.Debug,
             name: ModuleConfiguratorEventName.PostInitializeHooks,
             message: `Executing post-initialize hooks [${afterInit.length}]`,
-            properties: { hooks: afterInit.map((x) => x.name || 'anonymous').join(', ') },
+            properties: { hooks: hookNames },
         });
         const afterInitStart = performance.now();
-        await Promise.allSettled(afterInit.map((x) => Promise.resolve(x(instance))));
+        await Promise.allSettled(afterInit
+            // Invoke every registered afterInit callback with the initialized module instance map
+            .map((x) => Promise.resolve(x(instance))));
         const afterInitTime = Math.round(performance.now() - afterInitStart);
         registerEvent({
             level: ModuleEventLevel.Debug,
             name: ModuleConfiguratorEventName.PostInitializeHooksComplete,
             message: `Post-initialize hooks completed in ${afterInitTime}ms`,
             properties: {
-                hooks: afterInit.map((x) => x.name || 'anonymous').join(', '),
+                hooks: hookNames,
                 afterInitTime,
             },
             metric: afterInitTime,
         });
     }
     catch (err) {
+        // Build a display string of registered hook names for the error event
+        // Extract each hook's name, falling back for anonymous functions
+        const hookNames = afterInit.map((x) => x.name || 'anonymous').join(', ');
         registerEvent({
             level: ModuleEventLevel.Warning,
             name: ModuleConfiguratorEventName.PostInitializeHooksError,
             message: 'Post-initialize hooks failed',
-            properties: { hooks: afterInit.map((x) => x.name || 'anonymous').join(', ') },
+            properties: { hooks: hookNames },
             error: err,
         });
     }
@@ -5984,9 +6042,11 @@ function isPluginTeardown(value) {
  * @param modules - The initialized module instance map.
  * @param ref - Optional reference forwarded from module initialization.
  * @returns A promise resolving when all plugin callbacks have settled.
+ * @template TRef - Reference type forwarded to plugin callbacks.
  */
 async function runPluginPhase(ctx, modules, ref) {
     const { plugins, teardowns, registerEvent } = ctx;
+    // Skip the plugin phase entirely when no plugins were registered
     if (!plugins.length)
         return;
     registerEvent({
@@ -5995,7 +6055,9 @@ async function runPluginPhase(ctx, modules, ref) {
         message: `Registering plugins [${plugins.length}]`,
         properties: { count: plugins.length },
     });
-    const pluginRegistrations = await Promise.all(plugins.map(async (plugin) => {
+    const pluginRegistrations = await Promise.all(plugins
+        // Run every plugin callback concurrently so one slow plugin cannot delay the others
+        .map(async (plugin) => {
         const pluginStart = performance.now();
         const name = plugin.name || 'anonymous';
         try {
@@ -6021,7 +6083,9 @@ async function runPluginPhase(ctx, modules, ref) {
             return undefined;
         }
     }));
+    // Queue every plugin teardown returned above so the dispose phase can invoke them later
     for (const teardown of pluginRegistrations) {
+        // Only queue teardowns for plugins that actually returned one
         if (teardown) {
             teardowns.push(teardown);
         }
@@ -6038,6 +6102,7 @@ function getPluginTeardownName(teardown) {
     return typeof teardown === 'function' ? teardown.name || 'anonymous' : 'dispose';
 }
 async function runPluginTeardown(teardown) {
+    // Function-shaped teardowns are called directly; object-shaped ones expose a dispose() method
     if (typeof teardown === 'function') {
         await teardown();
         return;
@@ -6065,6 +6130,7 @@ async function runDisposePhase(ctx, instance, ref) {
         message: 'Disposing modules instance',
         properties: { modules: Object.keys(instance).join(', ') },
     });
+    // Only run the plugin teardown sequence when plugins were actually registered
     if (pluginTeardowns.length) {
         registerEvent({
             level: ModuleEventLevel.Debug,
@@ -6105,8 +6171,11 @@ async function runDisposePhase(ctx, instance, ref) {
     // Dispose all modules concurrently; failures are isolated per module so
     // one bad teardown cannot leave other modules in an inconsistent state.
     await Promise.allSettled(modules
+        // Only process modules that define a dispose hook
         .filter((module) => !!module.dispose)
+        // Dispose each module that defines the hook
         .map(async (module) => {
+        // Narrow the type for TypeScript; the filter above already guarantees this
         if (!module.dispose)
             return;
         try {
@@ -6150,7 +6219,7 @@ async function runDisposePhase(ctx, instance, ref) {
 }
 
 // Generated by genversion.
-const version$8 = '6.1.0';
+const version$8 = '6.1.1';
 
 // biome-ignore-all lint/suspicious/noExplicitAny: internal type-erased dispatch arrays — callbacks are registered with concrete module types but stored erased; the orchestrator never inspects these shapes itself
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -6204,6 +6273,11 @@ class ModulesConfigurator {
      * Preserved as a static string so minification cannot change it at runtime.
      */
     static className = 'ModulesConfigurator';
+    /**
+     * The current package version of the module configurator.
+     *
+     * @returns The semantic version string.
+     */
     get version() {
         return version$8;
     }
@@ -6213,6 +6287,12 @@ class ModulesConfigurator {
     // configuration before telemetry is wired up.
     // Memory bound: ~24 KB at ~240 bytes/event × 100 events.
     #event$ = new ReplaySubject(100);
+    /**
+     * Stream of lifecycle events emitted while modules are configured, initialized,
+     * and disposed.
+     *
+     * @returns An observable of {@link ModuleEvent} entries.
+     */
     get event$() {
         return this.#event$.asObservable();
     }
@@ -6293,6 +6373,7 @@ class ModulesConfigurator {
      * @param configs - One or more module configurator descriptors.
      */
     configure(...configs) {
+        // Delegate each descriptor to addConfig so registration logic stays in one place
         for (const x of configs) {
             this.addConfig(x);
         }
@@ -6306,6 +6387,7 @@ class ModulesConfigurator {
      *
      * @param config - The module configurator descriptor to register.
      * @template T - The module type being registered.
+     * @template TConfig - The resolved configuration type for the module.
      */
     addConfig(config) {
         const { module, afterConfig, afterInit, configure } = config;
@@ -6325,8 +6407,10 @@ class ModulesConfigurator {
         // Register each optional callback into its corresponding lifecycle phase array
         if (configure)
             this._configs.push((cfg, ref) => configure(cfg[module.name], ref));
+        // Register the afterConfig callback, if provided
         if (afterConfig)
             this._afterConfiguration.push((cfg) => afterConfig(cfg[module.name]));
+        // Register the afterInit callback, if provided
         if (afterInit)
             this._afterInit.push((instances) => afterInit(instances[module.name]));
     }
@@ -6418,17 +6502,21 @@ class ModulesConfigurator {
      * @param ref - Optional reference forwarded to all module lifecycle hooks.
      * @returns A promise resolving to the sealed, initialized module instance.
      * @template T - Additional modules to merge into the instance type.
+     * @template R - The reference type, narrowed to `TRef`.
      */
     async initialize(ref) {
         const configStart = performance.now();
         const config = await this._configure(ref);
         const configLoadTime = Math.round(performance.now() - configStart);
+        // Build a comma-separated module name list for telemetry properties
+        // Extract just the module names before joining into a display string
+        const configModuleNames = this.modules.map((m) => m.name).join(', ');
         this._registerEvent({
             level: ModuleEventLevel.Debug,
             name: ModuleConfiguratorEventName.InitializeConfigLoaded,
             message: `Modules configured in ${configLoadTime}ms`,
             properties: {
-                modules: this.modules.map((m) => m.name).join(', '),
+                modules: configModuleNames,
                 count: this.modules.length,
                 loadTime: configLoadTime,
             },
@@ -6437,24 +6525,30 @@ class ModulesConfigurator {
         const instanceStart = performance.now();
         const instance = await this._initialize(config, ref);
         const instanceLoadTime = Math.round(performance.now() - instanceStart);
+        // Build a comma-separated module name list for telemetry properties
+        // Extract just the module names before joining into a display string
+        const instanceModuleNames = this.modules.map((m) => m.name).join(', ');
         this._registerEvent({
             level: ModuleEventLevel.Debug,
             name: ModuleConfiguratorEventName.InitializeInstanceInitialized,
             message: `Modules initialized in ${instanceLoadTime}ms`,
             properties: {
-                modules: this.modules.map((m) => m.name).join(', '),
+                modules: instanceModuleNames,
                 count: this.modules.length,
                 loadTime: instanceLoadTime,
             },
             metric: instanceLoadTime,
         });
         const totalLoadTime = configLoadTime + instanceLoadTime;
+        // Build a comma-separated module name list for telemetry properties
+        // Extract just the module names before joining into a display string
+        const totalModuleNames = this.modules.map((m) => m.name).join(', ');
         this._registerEvent({
             level: ModuleEventLevel.Information,
             name: ModuleConfiguratorEventName.Initialize,
             message: `initialize in ${totalLoadTime}ms`,
             properties: {
-                modules: this.modules.map((m) => m.name).join(', '),
+                modules: totalModuleNames,
                 configLoadTime,
                 instanceLoadTime,
                 totalLoadTime,
@@ -6462,6 +6556,8 @@ class ModulesConfigurator {
             metric: totalLoadTime,
         });
         await this._postInitialize(instance, ref);
+        // `instance` is the freshly built module instance record, which is structurally compatible
+        // with `ModulesInstance<TModules>` but not nominally assignable across the generic params.
         const modules = Object.seal(Object.assign({}, instance, {
             dispose: () => this.dispose(instance),
         }));
@@ -6496,6 +6592,8 @@ class ModulesConfigurator {
      *
      * @param ref - Optional reference forwarded to module configure factories.
      * @returns A promise resolving to the merged module config map.
+     * @template T - Additional modules to merge into the instance type.
+     * @template R - The reference type, narrowed to `TRef`.
      * @protected
      */
     async _configure(ref) {
@@ -6518,6 +6616,8 @@ class ModulesConfigurator {
      * @param config - The merged module config map from the configure phase.
      * @param ref - Optional reference forwarded to each module's `initialize` call.
      * @returns A promise resolving to the sealed map of initialized module providers.
+     * @template T - Additional modules to merge into the instance type.
+     * @template R - The reference type. Defaults to `TRef`.
      * @protected
      */
     async _initialize(config, ref) {
@@ -6536,6 +6636,8 @@ class ModulesConfigurator {
      *
      * @param instance - The sealed module instance from the initialize phase.
      * @param ref - Optional reference forwarded to each module's `postInitialize` call.
+     * @template T - Additional modules to merge into the instance type.
+     * @template R - The reference type. Defaults to `TRef`.
      * @protected
      */
     async _postInitialize(instance, ref) {
@@ -6555,6 +6657,8 @@ class ModulesConfigurator {
      *
      * @param instance - The sealed module instance from the initialize phase.
      * @param ref - Optional reference forwarded to each plugin callback.
+     * @template T - Additional modules to merge into the instance type.
+     * @template R - The reference type, narrowed to `TRef`.
      * @protected
      */
     async _registerPlugins(instance, ref) {
@@ -6612,6 +6716,7 @@ class ProcessOperators {
      *                    It can be either an instance of IProcessOperators<T> or a record of string keys and ProcessOperator<T> values.
      */
     constructor(operators) {
+        // accept either a raw operators record or another IProcessOperators instance to clone from
         if (operators && 'operators' in operators) {
             this._operators = { ...operators.operators };
         }
@@ -6627,6 +6732,7 @@ class ProcessOperators {
      * @throws Error if an operator with the same key already exists.
      */
     add(key, operator) {
+        // guard against silently overwriting an existing operator under the same key
         if (Object.keys(this._operators).includes(key))
             throw Error(`Operator [${key}] already defined`);
         return this.set(key, operator);
@@ -6670,6 +6776,7 @@ class ProcessOperators {
         if (!operators.length) {
             return of(request);
         }
+        // feed the request through each operator sequentially, keeping the previous value when one returns void
         return from(Object.values(this._operators)).pipe(mergeScan(
         // resolve current operator and return result or previous if void
         (value, operator) => Promise.resolve(operator(value)).then((x) => x ?? value), 
@@ -6714,7 +6821,7 @@ class HttpRequestHandler extends ProcessOperators {
      */
     setHeader(key, value) {
         const operator = requestOperatorHeader(key, value);
-        return this.set('header-' + key, operator);
+        return this.set(`header-${key}`, operator);
     }
 }
 
@@ -22018,7 +22125,9 @@ const fetchRequestSchema = requestInitSchema.extend({
 const capitalizeRequestMethodOperator = (options) => (request) => {
     const { error, success, data } = requestMethodCasing().safeParse(request.method);
     request.method = success ? data : request.method?.toUpperCase();
+    // surface schema validation issues as warnings when not running silently
     if (error && true) {
+        // one warning per issue so callers can see exactly what failed to validate
         for (const e of error.issues) {
             console.warn(e.message);
         }
@@ -22047,6 +22156,7 @@ const requestValidationOperator = (options) => (request) => {
         return parse ? result : void 0;
     }
     catch (error) {
+        // re-throw so callers relying on `parse` can react to validation failures directly
         if (parse) {
             throw error;
         }
@@ -22061,11 +22171,17 @@ const requestValidationOperator = (options) => (request) => {
 class HttpResponseError extends Error {
     response;
     static Name = 'HttpResponseError';
+    /**
+     * @param message - The error message.
+     * @param response - The HTTP response associated with the error.
+     * @param options - Additional error options.
+     */
     constructor(message, response, options) {
         super(message, options);
         this.response = response;
     }
 }
+
 /**
  * Represents an error that occurs when handling a JSON response in an HTTP request.
  * Extends the base `HttpResponseError` class.
@@ -22089,6 +22205,7 @@ class HttpJsonResponseError extends HttpResponseError {
         this.data = options?.data;
     }
 }
+
 /**
  * Represents an error that occurs when handling a server-sent event (SSE) HTTP response.
  *
@@ -22112,6 +22229,15 @@ class ServerSentEventResponseError extends HttpResponseError {
     }
 }
 
+/**
+ * Thrown when `createClient(name)` is called with an unknown client key.
+ *
+ * This is only used when the provided string is neither a registered client name
+ * nor an absolute `http:` or `https:` URL.
+ */
+class ClientNotFoundException extends Error {
+}
+
 const defaultDataParser = (data) => {
     try {
         return JSON.parse(data);
@@ -22205,28 +22331,38 @@ async function* readStream(reader, options) {
             : [options.eventFilter]
         : null;
     const decoder = new TextDecoder();
+    // keep reading chunks from the stream until the reader signals completion
     while (true) {
         const { done, value } = await reader.read();
+        // the underlying stream has ended, nothing more to read
         if (done) {
+            // exit the read loop rather than yielding any further events
             break;
         }
         const text = decoder.decode(value, { stream: true });
         const events = parseEvents(text, { dataParser: options?.dataParser });
+        // a chunk may contain multiple complete SSE events, emit each in turn
         for (const event of events) {
+            // a retry directive reconfigures the reconnection delay rather than being a data event
             if (event.retry) {
                 await new Promise((resolve) => setTimeout(resolve, Number.parseInt(event.retry ?? '300', 10)));
+                // nothing to yield for a retry-only event
                 continue;
             }
+            // heartbeat filtering is opt-in via the skipHeartbeats option
             if (skipHeartbeats) {
                 // Skip comment-based heartbeats (no event, data, or id)
                 if (!event.event && !event.data && !event.id) {
+                    // this event carries no payload, so treat it as a heartbeat and skip it
                     continue;
                 }
                 // Skip named heartbeat events (e.g., event: heartbeat or event: ping)
                 if (event.event && ['heartbeat', 'ping'].includes(event.event)) {
+                    // an explicitly named heartbeat/ping event should also be skipped
                     continue;
                 }
             }
+            // only emit events that pass the caller-provided event type filter, if any
             if (!eventFilter || (event.event && eventFilter.includes(event.event))) {
                 yield event;
             }
@@ -22246,21 +22382,26 @@ async function* readStream(reader, options) {
  */
 const createSseSelector = (options) => {
     return (response) => {
+        // an unsuccessful HTTP status means there is no valid SSE stream to read
         if (!response.ok) {
             throw new ServerSentEventResponseError(`HTTP error! Status: ${response.status}`, response);
         }
+        // a missing body means there is nothing to stream from
         if (!response.body) {
             throw new ServerSentEventResponseError('Response body is not readable', response);
         }
+        // guard against consuming a non-SSE response as if it were an event stream
         if (!response.headers.get('Content-Type')?.includes('text/event-stream')) {
             throw new ServerSentEventResponseError('Response is not a text/event-stream', response);
         }
         const reader = response.body.getReader();
-        return from(readStream(reader, {
+        return (from(readStream(reader, {
             dataParser: options?.dataParser,
             skipHeartbeats: options?.skipHeartbeats,
             eventFilter: options?.eventFilter,
-        })).pipe(
+        }))
+            // stop the stream on abort and always release the underlying reader when done
+            .pipe(
         // Stop reading if the abort signal is triggered
         takeUntil(options?.abortSignal ? fromEvent(options.abortSignal, 'abort') : EMPTY), finalize$2(async () => {
             // cancel just in case of a pre-mature exit
@@ -22268,14 +22409,18 @@ const createSseSelector = (options) => {
                 /** ignore cancellation errors */
             });
             reader.releaseLock();
-        }));
+        })));
     };
 };
 
 /** @inheritdoc */
 class HttpClientConfigurator {
     _clients = {};
-    /** Gets a shallow clone of all named client configurations. */
+    /**
+     * Gets a shallow clone of all named client configurations.
+     *
+     * @returns A shallow clone of the named client configurations.
+     */
     get clients() {
         return { ...this._clients };
     }
@@ -22303,6 +22448,8 @@ class HttpClientConfigurator {
     configureClient(name, args) {
         const argFn = typeof args === 'string' ? { baseUri: args } : args;
         const options = typeof argFn === 'function' ? { onCreate: argFn } : argFn;
+        // `options` is `HttpClientOptions<T>` (this call's generic), but `_clients` is keyed by the
+        // configurator's own `TClient` — callers are expected to keep the two in sync.
         this._clients[name] = {
             ...this._clients[name],
             ...options,
@@ -22312,16 +22459,8 @@ class HttpClientConfigurator {
 }
 
 // Generated by genversion.
-const version$6 = '8.0.3';
+const version$6 = '8.0.4';
 
-/**
- * Thrown when `createClient(name)` is called with an unknown client key.
- *
- * This is only used when the provided string is neither a registered client name
- * nor an absolute `http:` or `https:` URL.
- */
-class ClientNotFoundException extends Error {
-}
 /** URL protocols accepted as valid ad-hoc base URIs. */
 const SUPPORTED_PROTOCOLS = ['http:', 'https:', 'ws:', 'wss:'];
 /**
@@ -22359,6 +22498,10 @@ class HttpClientProvider extends BaseModuleProvider {
     get defaultHttpRequestHandler() {
         return this.config.defaultHttpRequestHandler;
     }
+    /**
+     * Creates a new `HttpClientProvider`.
+     * @param config - The configurator providing client definitions and defaults.
+     */
     constructor(config) {
         super({
             version: version$6,
@@ -22395,6 +22538,7 @@ class HttpClientProvider extends BaseModuleProvider {
         const { baseUri, defaultScopes = [], onCreate, ctor = this.config.defaultHttpClientCtor, requestHandler = this.defaultHttpRequestHandler, responseHandler, } = config;
         const options = { requestHandler, responseHandler };
         const instance = new ctor(baseUri || '', options);
+        // attach the resolved default scopes onto the instance without overwriting other own properties
         Object.assign(instance, { defaultScopes });
         onCreate?.(instance);
         return instance;
@@ -22402,6 +22546,7 @@ class HttpClientProvider extends BaseModuleProvider {
     /**
      * Creates a client instance and returns it as the requested custom client type.
      *
+     * @template T - The custom `HttpClient` implementation type to cast the created instance to.
      * @param key - The key of the pre-configured HTTP client to create.
      * @returns The created HTTP client instance, cast to the specified type `T`.
      *
@@ -22412,6 +22557,8 @@ class HttpClientProvider extends BaseModuleProvider {
      * is configured to use a different implementation.
      */
     createCustomClient(key) {
+        // `createClient` always returns the provider's configured `HttpClient` implementation —
+        // cast through `unknown` to hand back the caller-requested implementation type `T`.
         return this.createClient(key);
     }
     /**
@@ -22423,14 +22570,19 @@ class HttpClientProvider extends BaseModuleProvider {
      *
      * @param keyOrConfig - The key or configuration object for the HTTP client.
      * @returns The resolved HTTP client configuration.
+     * @throws {ClientNotFoundException} When `keyOrConfig` is a string that is neither a registered
+     * client key nor a URL-like value.
      */
     _resolveConfig(keyOrConfig) {
+        // a string may reference a registered client key or an ad-hoc URL; anything else is used as-is
         if (typeof keyOrConfig === 'string') {
             const config = this.config.clients[keyOrConfig];
+            // an absolute http(s) URL can be used directly as an ad-hoc baseUri
             if (!config && isURL(keyOrConfig)) {
                 return { baseUri: keyOrConfig };
             }
             else if (!config && looksLikeURL(keyOrConfig)) {
+                // recover from a missing protocol instead of failing outright, but warn so it can be fixed
                 console.warn(`[HttpClientProvider] "${keyOrConfig}" looks like a URL but is missing the http:// or https:// protocol. ` +
                     `Treating it as "https://${keyOrConfig}". ` +
                     `Pass a fully-qualified URL to silence this warning.`);
@@ -22543,8 +22695,8 @@ const jsonSelector = async (response) => {
  * @throws {Error} If the response is not successful or if there is an error parsing the response.
  */
 const blobSelector = async (response) => {
+    // treat any non-2xx response as a failure rather than attempting to read its body
     if (!response.ok) {
-        // Throw an error if the network response is not successful
         throw new Error('network response was not OK');
     }
     // Status code 204 indicates no content, so throw an error
@@ -22552,6 +22704,7 @@ const blobSelector = async (response) => {
         throw new Error('no content');
     }
     // Extract the filename from the 'content-disposition' header
+    // locate the segment carrying the filename directive; other directives (e.g. inline/attachment) are ignored
     const filename = response.headers
         .get('content-disposition')
         ?.split(';')
@@ -22563,7 +22716,7 @@ const blobSelector = async (response) => {
         const blob = await response.blob();
         return { filename, blob };
     }
-    catch (err) {
+    catch (_err) {
         // Throw an error if there's a problem parsing the response
         throw Error('failed to parse response');
     }
@@ -22599,16 +22752,23 @@ class HttpClient {
     _abort$ = new Subject();
     /**
      * A stream of requests that are about to be executed.
+     * @returns An `Observable` that emits each request before it is executed.
      */
     get request$() {
         return this._request$.asObservable();
     }
     /**
      * A stream of responses that have been received.
+     * @returns An `Observable` that emits each response as it is received.
      */
     get response$() {
         return this._response$.asObservable();
     }
+    /**
+     * Creates a new `HttpClient`.
+     * @param uri - The base URI used to resolve relative request paths.
+     * @param options - Optional request and response handlers.
+     */
     constructor(uri, options) {
         this.uri = uri;
         this.requestHandler = new HttpRequestHandler(options?.requestHandler);
@@ -22627,6 +22787,7 @@ class HttpClient {
     /**
      * Fetches data from the specified path and returns a stream response.
      *
+     * @template T - The expected shape of the fetched data.
      * @param path - The path to fetch data from.
      * @param args - Optional request initialization options, including a custom selector function.
      * @returns A stream response containing the fetched data.
@@ -22637,6 +22798,7 @@ class HttpClient {
     /**
      * Fetches data from the specified path and returns a Promise containing the fetched data.
      *
+     * @template T - The expected shape of the fetched data.
      * @param path - The path to fetch data from.
      * @param args - Optional request initialization options, including a custom selector function.
      * @returns A Promise containing the fetched data.
@@ -22644,13 +22806,20 @@ class HttpClient {
     fetch(path, args) {
         return firstValueFrom(this.fetch$(path, args));
     }
-    /** @deprecated */
+    /**
+     * @deprecated Use {@link fetch} instead.
+     * @template T - The expected shape of the fetched data.
+     * @param path - The path to fetch data from.
+     * @param args - Optional request initialization options, including a custom selector function.
+     * @returns A Promise containing the fetched data.
+     */
     fetchAsync(path, args) {
         return this.fetch(path, args);
     }
     /**
      * Fetches data from the specified path and returns a stream response containing the data in JSON format.
      *
+     * @template T - The expected shape of the parsed JSON data.
      * @param path - The path to fetch the data from.
      * @param args - Optional request initialization options, including a custom selector function and request body.
      *   - `body`: The request body, which will be automatically serialized to JSON if it's an object.
@@ -22674,6 +22843,7 @@ class HttpClient {
     /**
      * Fetches data from the specified path and returns a Promise containing the fetched data in JSON format.
      *
+     * @template T - The expected shape of the parsed JSON data.
      * @param path - The path to fetch the data from.
      * @param args - Optional request initialization options, including a custom selector function and request body.
      *   - `body`: The request body, which will be automatically serialized to JSON if it's an object.
@@ -22687,6 +22857,7 @@ class HttpClient {
     /**
      * Fetches a blob resource from the specified path and returns a stream response.
      *
+     * @template T - The expected shape of the fetched blob data.
      * @param path - The path to the blob resource.
      * @param args - Optional request initialization options, including a custom selector function.
      * @returns A stream response containing the fetched blob data.
@@ -22705,6 +22876,7 @@ class HttpClient {
     /**
      * Fetches a blob from the specified path and returns a Promise that resolves to the blob result.
      *
+     * @template T - The expected shape of the fetched blob data.
      * @param path - The path to fetch the blob from.
      * @param args - Optional arguments for the fetch request, including request body, headers, and response type.
      * @returns A Promise that resolves to the blob result.
@@ -22746,13 +22918,21 @@ class HttpClient {
         // Call the fetch$ method with the provided path and the constructed init object
         return this._fetch$(path, { selector, ...args, headers });
     }
-    /** @deprecated */
+    /**
+     * @deprecated Use {@link json} instead.
+     * @template T - The expected shape of the parsed JSON data.
+     * @param path - The path to fetch the data from.
+     * @param args - Optional request initialization options, including a custom selector function and request body.
+     * @returns A Promise containing the fetched data in JSON format.
+     */
     jsonAsync(path, args) {
         return this.json(path, args);
     }
     /**
      * Executes an HTTP request using the specified method and path.
      *
+     * @template T - The expected shape of the result.
+     * @template TMethod - The name of the `IHttpClient` method to invoke.
      * @param method - The HTTP method to use for the request, such as 'fetch', 'json', or 'blob'.
      * @param path - The path to the resource to fetch.
      * @param init - Optional request initialization options, including request body, headers, and response type.
@@ -22772,10 +22952,13 @@ class HttpClient {
     /**
      * Fetches data from the specified path and returns an Observable that emits the response.
      *
+     * @template T - The expected shape of the emitted data.
      * @param path - The path to fetch the data from.
      * @param args - Optional arguments for the fetch request, including a response selector function, request body, headers, and response type.
      * @returns {Observable<T>} An Observable that emits the response data.
      *
+     * @throws {HttpResponseError} When the optional `selector` throws while transforming the response.
+     *
      * This method handles the following steps:
      * 1. Resolves the full URL by combining the base URI and the provided path.
      * 2. Prepares the request by passing it through the `requestHandler.process()` method.
@@ -22786,6 +22969,9 @@ class HttpClient {
      */
     _fetch$(path, args) {
         const { selector, ...options } = args || {};
+        // `fromFetch` yields the raw fetch `Response`, but `responseHandler.process()` (called via
+        // `_prepareResponse`) expects the pipeline's generic `TResponse` shape — cast through
+        // `unknown` since the two are only compatible after that processing step.
         const response$ = of({
             ...options,
             path,
@@ -22803,6 +22989,7 @@ class HttpClient {
         tap((x) => this._response$.next(x)), 
         /** execute selector */
         switchMap((response) => {
+            // only run the selector when one was provided; otherwise pass the response through untouched
             if (selector) {
                 try {
                     return selector(response);
@@ -22817,6 +23004,8 @@ class HttpClient {
         }), 
         /** cancel request on abort signal */
         takeUntil(this._abort$));
+        // The pipe above resolves to the per-call generic `T` (via the optional `selector`), but
+        // the observable's static type tracks the class-level `TResponse` — cast to the caller's `T`.
         return response$;
     }
     /**
@@ -22886,6 +23075,7 @@ class HttpClientMsal extends HttpClient {
      *
      * @overrides HttpClient.fetch$
      *
+     * @template T - The expected response type.
      * @param path - The path to the resource to fetch.
      * @param init - An optional `MsalFetchRequestInit` object that can include the `scopes` property.
      * @returns An `Observable` that emits the fetched resource.
@@ -22937,15 +23127,18 @@ const module$4 = {
      */
     initialize: async ({ config, hasModule, requireInstance, }) => {
         const httpProvider = new HttpClientProvider(config);
+        // wire up an MSAL bearer-token handler only when the auth module is registered
         if (hasModule('auth')) {
             const authProvider = await requireInstance('auth');
             httpProvider.defaultHttpRequestHandler.set('MSAL', async (request) => {
                 const { scopes = [] } = request;
+                // only attempt to acquire a token when the request actually declares scopes
                 if (scopes.length) {
-                    /** TODO should be try catch, check caller for handling */
+                    /** TODO(#5143): should be try catch, check caller for handling */
                     const accessToken = await authProvider.acquireAccessToken({
                         request: { scopes },
                     });
+                    // without a token there's nothing to attach, fall through to the default request
                     if (accessToken) {
                         const headers = new Headers(request.headers);
                         headers.set('Authorization', `Bearer ${accessToken}`);
@@ -23471,7 +23664,7 @@ var objectTraps = {
     ) && isArrayIndex(prop)) {
       return value;
     }
-    if (value === peek(state.base_, prop)) {
+    if (value === peek(state.base_, prop) || isRelocatedBaseRef(state, prop, value)) {
       prepareCopy(state);
       const childKey = state.type_ === 1 /* Array */ ? +prop : prop;
       const childDraft = createProxy(state.scope_, value, state, childKey);
@@ -23505,7 +23698,7 @@ var objectTraps = {
       markChanged(state);
     }
     if (state.copy_[prop] === value && // special case: handle new props with value 'undefined'
-    (value !== void 0 || prop in state.copy_) || // special case: NaN
+    (value !== void 0 || has(state.copy_, prop, state.type_)) || // special case: NaN
     Number.isNaN(value) && Number.isNaN(state.copy_[prop]))
       return true;
     state.copy_[prop] = value;
@@ -23574,6 +23767,12 @@ function peek(draft, prop) {
   const source = state ? latest(state) : draft;
   return source[prop];
 }
+function isRelocatedBaseRef(state, prop, value) {
+  if (state.type_ !== 1 /* Array */ || !state.allIndicesReassigned_ || state.assigned_?.get(prop) || !isDraftable(value) || value[DRAFT_STATE]) {
+    return false;
+  }
+  return state.baseRefs_.has(value);
+}
 function readPropFromProto(state, source, prop) {
   const desc = getDescriptorFromProto(source, prop);
   return desc ? VALUE in desc ? desc[VALUE] : (
@@ -23899,18 +24098,21 @@ class FlowSubject extends Observable {
     #state;
     /**
      * Observable stream of actions dispatched to the subject.
+     * @returns An observable of dispatched actions.
      */
     get action$() {
         return this.#action.asObservable();
     }
     /**
      * The current value of state.
+     * @returns The current state value.
      */
     get value() {
         return this.#state.value;
     }
     /**
      * Flag to indicate if the observable is closed.
+     * @returns `true` if both the state and action subjects are closed.
      */
     get closed() {
         return this.#state.closed || this.#action.closed;
@@ -23927,6 +24129,7 @@ class FlowSubject extends Observable {
         });
         const initial = 'getInitialState' in reducer ? reducer.getInitialState() : initialState;
         this.#state = new BehaviorSubject(initial);
+        // Reduce dispatched actions into state, skipping emissions that produce an unchanged value
         this.#action.pipe(scan(reducer, initial), distinctUntilChanged()).subscribe(this.#state);
         this.reset = () => this.#state.next(initial);
     }
@@ -23945,27 +24148,32 @@ class FlowSubject extends Observable {
     /**
      * Selects a derived state from the observable state and emits only when the selected state changes.
      *
+     * @template T - The derived state type returned by the selector.
      * @param selector - A function that takes the current state and returns a derived state.
      * @param comparator - An optional function that compares the previous and current derived states to determine if a change has occurred.
      * @returns An observable that emits the derived state whenever it changes.
      */
     select(selector, comparator) {
+        // Derive and de-duplicate the selected value from the state stream
         return this.#state.pipe(map$1(selector), distinctUntilChanged(comparator));
     }
     /**
      * Adds an effect that listens for actions and performs side effects.
      *
+     * @template TType - The action type(s) to listen for.
      * @param actionTypeOrFn The type of action to listen for, an array of action types, or the effect function itself.
      * @param fn The effect function to execute when the action is dispatched, if the first parameter is an action type.
      * @returns A subscription to the effect.
      */
     addEffect(actionTypeOrFn, fn) {
+        // Narrow the action stream to the requested action type(s), or use it as-is when a plain effect function was given
         const action$ = typeof actionTypeOrFn === 'function'
             ? this.action$
             : Array.isArray(actionTypeOrFn)
                 ? this.action$.pipe(filterAction(...actionTypeOrFn))
                 : this.action$.pipe(filterAction(actionTypeOrFn));
         const mapper = (fn ? fn : actionTypeOrFn);
+        // Run the effect for each matching action, then filter and reschedule any resulting action
         return action$
             .pipe(mergeMap((action) => from(new Promise((resolve, reject) => {
             try {
@@ -23974,7 +24182,9 @@ class FlowSubject extends Observable {
             catch (err) {
                 reject(err);
             }
-        })).pipe(catchError((err) => {
+        }))
+            // Swallow effect errors so a single failing effect doesn't tear down the subscription
+            .pipe(catchError((err) => {
             console.warn('unhandled effect', err);
             return EMPTY;
         }))), filter((x) => !!x), observeOn(asyncScheduler))
@@ -24016,9 +24226,11 @@ class FlowSubject extends Observable {
      */
     addFlow(fn) {
         const epic$ = fn(this.action$, this);
+        // Fail fast if the flow function forgot to return an observable
         if (!epic$) {
             throw new TypeError(`addEpic: one of the provided effects "${fn.name || '<anonymous>'}" does not return a stream. Double check you're not missing a return statement!`);
         }
+        // Log and swallow flow errors so a single failing flow doesn't tear down the subject
         return epic$
             .pipe(catchError((err) => {
             console.trace('unhandled exception, epic closed!', err);
@@ -24054,18 +24266,38 @@ class FlowSubject extends Observable {
     }
 }
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Internal helper utilities for constructing and inspecting Redux-style
+ * lifecycle action types (`::request`, `::success`, `::failure`).
+ */
+/**
+ * Separates an action's base type from its lifecycle suffix.
+ */
+const actionSuffixDivider = '::';
+
+// biome-ignore-all lint/suspicious/noExplicitAny: ported redux-toolkit conditional-type dispatch logic (e.g. IsAny<T, ...>) requires real `any`, not `unknown`, to distinguish the two at the type level
+// biome-ignore-all lint/suspicious/noConfusingVoidType: `void` here is the ported redux-toolkit sentinel meaning "no payload type provided", distinct from `undefined` (see IfVoid in ts-helpers.ts) — replacing with `undefined` would change dispatch semantics
 /**
  * taken from https://github.com/reduxjs/redux-toolkit/tree/master/packages/toolkit/src
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
+/**
+ * Creates the runtime action creator implementation shared by the overloads above.
+ *
+ * @param type - The action type to assign to created actions.
+ * @param prepareAction - An optional function that prepares payload, metadata, and errors.
+ * @returns A callable action creator with type and matching metadata.
+ * @throws {Error} When the prepare callback does not return an action object.
+ */
 function createAction(type, prepareAction) {
     function actionCreator(...args) {
+        // Use the prepare callback when the caller needs custom payload construction.
         if (prepareAction) {
             const prepared = prepareAction(...args);
+            // Reject invalid prepare callbacks before reading their action fields.
             if (!prepared) {
                 throw new Error('prepareAction did not return an object');
             }
+            // Merge optional metadata and error fields into the prepared action.
             return {
                 type,
                 payload: prepared.payload,
@@ -24080,35 +24312,50 @@ function createAction(type, prepareAction) {
     actionCreator.match = (action) => action.type === type;
     return actionCreator;
 }
-const actionSuffixDivider = '::';
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
+// biome-ignore-all lint/suspicious/noExplicitAny: generic constraints mirror create-action.ts's ported redux-toolkit PrepareAction<any> dispatch pattern
+/**
+ * Creates the runtime async action implementation shared by the overloads above.
+ *
+ * @param type - The base action type string.
+ * @param request - A prepare function for the request action payload.
+ * @param success - A prepare function for the success action payload.
+ * @param failure - An optional prepare function for the failure action payload.
+ * @returns An action creator with request, success, and optional failure actions.
+ */
 function createAsyncAction(type, request, success, failure) {
     const action = createAction([type, 'request'].join(actionSuffixDivider), request);
+    // Attach the success action only when the caller supplied its prepare function.
     if (success) {
+        // Add the success action while preserving the request creator's identity.
         Object.assign(action, {
             success: createAction([type, 'success'].join(actionSuffixDivider), success),
         });
     }
+    // Attach the failure action only for async workflows that support failure results.
     if (failure) {
+        // Add the failure action alongside the existing request and success actions.
         Object.assign(action, {
             failure: createAction([type, 'failure'].join(actionSuffixDivider), failure),
         });
     }
+    // `action` is progressively mutated with `success`/`failure` properties above, so its static
+    // type can't reflect the final shape declared by this function's overload signatures.
     return action;
 }
 
 function freezeDraftable(val) {
-    // biome-ignore lint/suspicious/noEmptyBlockStatements: This is a valid use case for an empty block statement
     return isDraftable(val) ? produce(val, () => { }) : val;
 }
 function isStateFunction(x) {
     return typeof x === 'function';
 }
+/** @inheritdoc */
 function createReducer$2(initialState, mapOrBuilderCallback) {
     const [actionsMap, finalActionMatchers, finalDefaultCaseReducer] = executeReducerBuilderCallback(mapOrBuilderCallback);
     // Ensure the initial state gets frozen either way (if draftable)
     let getInitialState;
+    // A lazy initializer must be invoked before its result can be frozen
     if (isStateFunction(initialState)) {
         getInitialState = () => freezeDraftable(initialState());
     }
@@ -24119,19 +24366,31 @@ function createReducer$2(initialState, mapOrBuilderCallback) {
     function reducer(state, action) {
         let caseReducers = [
             actionsMap[action.type],
-            ...finalActionMatchers.filter(({ matcher }) => matcher(action)).map(({ reducer }) => reducer),
+            ...finalActionMatchers
+                // Keep only matchers whose predicate matches this action
+                .filter(({ matcher }) => matcher(action))
+                // Extract just the matched reducers
+                .map(({ reducer }) => reducer),
         ];
-        if (finalDefaultCaseReducer && caseReducers.filter((cr) => !!cr).length === 0) {
+        // Fall back to the default case reducer when nothing else matched this action
+        // Check whether any slot actually holds a reducer
+        const hasMatchedReducer = caseReducers.filter((cr) => !!cr).length > 0;
+        // Only substitute the default case when no case/matcher reducer actually matched
+        if (finalDefaultCaseReducer && !hasMatchedReducer) {
             caseReducers = [finalDefaultCaseReducer];
         }
+        // Run each matched case reducer against the previous state, producing the next state
         return caseReducers.reduce((previousState, caseReducer) => {
+            // Only transform state when a case reducer was matched for this slot
             if (caseReducer) {
+                // Reuse an existing draft when already inside a `createNextState` call
                 if (isDraft(previousState)) {
                     // If it's already a draft, we must already be inside a `createNextState` call,
                     // likely because this is being wrapped in `createReducer`, `createSlice`, or nested
                     // inside an existing draft. It's safe to just pass the draft to the mutator.
                     const draft = previousState; // We can assume this is already a draft
                     const result = caseReducer(draft, action);
+                    // Treat an undefined result as "no change" rather than clearing the state
                     if (result === undefined) {
                         return previousState;
                     }
@@ -24141,7 +24400,9 @@ function createReducer$2(initialState, mapOrBuilderCallback) {
                     // If state is not draftable (ex: a primitive, such as 0), we want to directly
                     // return the caseReducer func and not wrap it with produce.
                     const result = caseReducer(previousState, action);
+                    // Treat an undefined result as "no change", unless there's no previous state to fall back to
                     if (result === undefined) {
+                        // A `null` previous state has nothing to fall back to, so undefined is legitimately "no change"
                         if (previousState === null) {
                             return previousState;
                         }
@@ -24151,7 +24412,7 @@ function createReducer$2(initialState, mapOrBuilderCallback) {
                 }
                 else {
                     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                    // @ts-ignore
+                    // @ts-expect-error
                     // createNextState() produces an Immutable<Draft<S>> rather
                     // than an Immutable<S>, and TypeScript cannot find out how to reconcile
                     // these two types.
@@ -24166,12 +24427,22 @@ function createReducer$2(initialState, mapOrBuilderCallback) {
     reducer.getInitialState = getInitialState;
     return reducer;
 }
+/**
+ * Executes a reducer builder callback against a fresh {@link ActionReducerMapBuilder},
+ * collecting the case reducers, matchers, and default case it registered.
+ *
+ * @template TState - The reducer's state type.
+ * @template TAction - The union of actions the reducer handles.
+ * @param builderCallback - The callback passed to {@link createReducer} that registers cases via the builder.
+ * @returns A tuple of the action-to-reducer map, matcher list, and optional default case reducer.
+ */
 function executeReducerBuilderCallback(builderCallback) {
     const actionsMap = {};
     const actionMatchers = [];
     let defaultCaseReducer;
     const builder = {
         addCase(typeOrActionCreator, reducer) {
+            // Skip these dev-only ordering checks in production builds to avoid the extra overhead
             if (process.env.NODE_ENV !== 'production') {
                 /*
                  * to keep the definition by the user in line with actual behavior,
@@ -24181,11 +24452,13 @@ function executeReducerBuilderCallback(builderCallback) {
                 if (actionMatchers.length > 0) {
                     throw new Error('`builder.addCase` should only be called before calling `builder.addMatcher`');
                 }
+                // A default case must always be registered last, after every specific case
                 if (defaultCaseReducer) {
                     throw new Error('`builder.addCase` should only be called before calling `builder.addDefaultCase`');
                 }
             }
             const type = typeof typeOrActionCreator === 'string' ? typeOrActionCreator : typeOrActionCreator.type;
+            // Each action type may only be handled by a single case reducer
             if (type in actionsMap) {
                 throw new Error('addCase cannot be called with two reducers for the same action type');
             }
@@ -24193,7 +24466,9 @@ function executeReducerBuilderCallback(builderCallback) {
             return builder;
         },
         addMatcher(matcher, reducer) {
+            // Skip this dev-only ordering check in production builds to avoid the extra overhead
             if (process.env.NODE_ENV !== 'production') {
+                // A default case must always be registered last, after every matcher
                 if (defaultCaseReducer) {
                     throw new Error('`builder.addMatcher` should only be called before calling `builder.addDefaultCase`');
                 }
@@ -24202,7 +24477,9 @@ function executeReducerBuilderCallback(builderCallback) {
             return builder;
         },
         addDefaultCase(reducer) {
+            // Skip this dev-only uniqueness check in production builds to avoid the extra overhead
             if (process.env.NODE_ENV !== 'production') {
+                // Only one default case reducer may be registered per builder
                 if (defaultCaseReducer) {
                     throw new Error('`builder.addDefaultCase` can only be called once');
                 }
@@ -24219,8 +24496,10 @@ function executeReducerBuilderCallback(builderCallback) {
     ];
 }
 
+/** @inheritdoc */
+function isObservableInput(
 // biome-ignore lint/suspicious/noExplicitAny: Should allow any input type
-function isObservableInput(input) {
+input) {
     // Check for null or undefined
     if (input === null || input === undefined) {
         return false;
@@ -24290,7 +24569,6 @@ function isObservableInput(input) {
  * // Primitive
  * toObservable(42).subscribe(x => console.log(x)); // 42
  */
-// biome-ignore lint/suspicious/noExplicitAny: must be any to allow any type of input
 function toObservable(input, ...args) {
     // If input is already an ObservableInput (Observable, Promise, Iterable, etc), use RxJS 'from' to convert it
     if (isObservableInput(input)) {
@@ -24468,6 +24746,7 @@ var deepmerge = /*@__PURE__*/getDefaultExportFromCjs(deepmergeExports);
  * @returns The merged `MetaData` object, or `undefined` if both inputs are undefined.
  */
 const mergeMetadata = (source, target) => {
+    // Nothing to merge when neither side has metadata
     if (!source && !target) {
         return undefined;
     }
@@ -24490,15 +24769,21 @@ const mergeMetadata = (source, target) => {
  *
  * @internal
  */
+// Deliberately co-located with `mergeMetadata` above
+// fusion-lint-disable-next-line single-export-per-file
 const mergeTelemetryItem = (target, source) => {
+    // Both arguments are required to produce a valid merged telemetry item
     if (!target || !source) {
         throw new Error('Both target and source must be defined for merging telemetry items.');
     }
+    // A type mismatch would produce an inconsistent telemetry item, so fail fast
     if (target.type && source.type && target.type !== source.type) {
         throw new Error('Mismatched telemetry item types.');
     }
+    // Combine both scopes and de-duplicate via a Set before flattening back to an array
     const scope = [...new Set([...(target.scope ?? []), ...(source.scope ?? [])])];
     const metadata = mergeMetadata(target.metadata, source.metadata);
+    // Source properties take precedence over target, with scope/metadata merged separately above
     return { ...target, ...source, scope, metadata };
 };
 
@@ -24529,11 +24814,18 @@ const mergeTelemetryItem = (target, source) => {
 class TelemetryConfigurator extends BaseConfigBuilder {
     #adaptersCallbacks = {};
     #metadata = [];
+    /**
+     * Creates a new `TelemetryConfigurator` and wires up the async adapter
+     * resolution and metadata merging pipelines used by `createConfigAsync`.
+     */
     constructor() {
         super();
         // Configure async adapter resolution using mergeMap to handle Promise/Observable adapter factories
         this._set('adapters', (args) => {
-            return from(Object.entries(this.#adaptersCallbacks)).pipe(mergeMap(([identifier, adapterFn]) => from(adapterFn(args)).pipe(filter((adapter) => !!adapter), map$1((adapter) => [identifier, adapter]))), scan((acc, [identifier, adapter]) => {
+            // Resolve every adapter factory concurrently and merge them into a single record
+            return from(Object.entries(this.#adaptersCallbacks)).pipe(mergeMap(([identifier, adapterFn]) => 
+            // Drop adapters whose factory resolved to a falsy value
+            from(adapterFn(args)).pipe(filter((adapter) => !!adapter), map$1((adapter) => [identifier, adapter]))), scan((acc, [identifier, adapter]) => {
                 acc[identifier] = adapter;
                 return acc;
             }, {}), defaultIfEmpty({}), shareReplay({ bufferSize: 1, refCount: true }));
@@ -24541,12 +24833,15 @@ class TelemetryConfigurator extends BaseConfigBuilder {
         // Configure metadata merging - handles multiple sync/async metadata sources
         this._set('metadata', async () => {
             const metadataItems = this.#metadata;
-            return (...args) => from(metadataItems).pipe(concatMap((metadata) => toObservable(metadata, ...args)), scan((acc, current) => mergeMetadata(acc, current) ?? {}, {}), last(), shareReplay({ bufferSize: 1, refCount: true }));
+            return (...args) => 
+            // Merge every registered metadata source in order, emitting the final accumulated result
+            from(metadataItems).pipe(concatMap((metadata) => toObservable(metadata, ...args)), scan((acc, current) => mergeMetadata(acc, current) ?? {}, {}), last(), shareReplay({ bufferSize: 1, refCount: true }));
         });
     }
     /**
      * Registers a telemetry adapter with the configurator.
      *
+     * @param identifier - The key used to register and later resolve this adapter.
      * @param adapter - The telemetry adapter to be added. The adapter's identifier is used as the key.
      * @returns The current instance of the configurator for method chaining.
      */
@@ -24556,7 +24851,8 @@ class TelemetryConfigurator extends BaseConfigBuilder {
     /**
      * Configures a telemetry adapter with the configurator.
      *
-     * @param adapter - A callback function that returns a telemetry adapter instance
+     * @param identifier - The key used to register and later resolve this adapter.
+     * @param adapterFn - A callback function that returns a telemetry adapter instance
      * @returns The current instance for method chaining
      */
     configureAdapter(identifier, adapterFn) {
@@ -24621,7 +24917,7 @@ class TelemetryConfigurator extends BaseConfigBuilder {
 }
 
 // Generated by genversion.
-const version$5 = '7.0.0';
+const version$5 = '7.0.1';
 
 /**
  * Enum representing the severity levels of telemetry items.
@@ -24715,6 +25011,8 @@ const TelemetryItemSchema = object({
  *
  * Extends TelemetryItemSchema and sets type to 'event'.
  */
+// Deliberately co-located with the other telemetry item schemas below
+// fusion-lint-disable-next-line single-export-per-file
 const TelemetryEventSchema = TelemetryItemSchema.extend({
     type: literal(TelemetryType.Event),
 });
@@ -24724,6 +25022,8 @@ const TelemetryEventSchema = TelemetryItemSchema.extend({
  * Extends TelemetryItemSchema and sets type to 'exception'.
  * Adds an exception property of type Error.
  */
+// Deliberately co-located with the other telemetry item schemas above/below
+// fusion-lint-disable-next-line single-export-per-file
 const TelemetryExceptionSchema = TelemetryItemSchema.extend({
     type: literal(TelemetryType.Exception),
     exception: _instanceof(Error).describe('The exception object.'),
@@ -24734,6 +25034,8 @@ const TelemetryExceptionSchema = TelemetryItemSchema.extend({
  * Extends TelemetryItemSchema and sets type to 'metric'.
  * Adds a value property for the metric value.
  */
+// Deliberately co-located with the other telemetry item schemas above/below
+// fusion-lint-disable-next-line single-export-per-file
 const TelemetryMetricSchema = TelemetryItemSchema.extend({
     type: literal(TelemetryType.Metric),
     value: number$1().describe('The value of the metric.'),
@@ -24743,6 +25045,8 @@ const TelemetryMetricSchema = TelemetryItemSchema.extend({
  *
  * Extends TelemetryEventSchema and allows passthrough of additional properties.
  */
+// Deliberately co-located with the other telemetry item schemas above
+// fusion-lint-disable-next-line single-export-per-file
 const TelemetryCustomEventSchema = TelemetryEventSchema.extend({
     type: literal(TelemetryType.Custom),
 }).passthrough();
@@ -24764,7 +25068,6 @@ const TelemetryCustomEventSchema = TelemetryEventSchema.extend({
  * @template TInit The type of the event details.
  * @template TType The type of the event type.
  */
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: no other way to define a class with multiple signatures
 class FrameworkEvent {
     __type;
     #detail;
@@ -24843,6 +25146,7 @@ class FrameworkEvent {
      * If the event is cancelable, this method sets the `canceled` property to `true`.
      */
     preventDefault() {
+        // Only cancelable events can be canceled
         if (this.cancelable) {
             this.#canceled = true;
         }
@@ -24857,44 +25161,54 @@ class FrameworkEvent {
 }
 
 /**
- * Represents a telemetry event within the framework.
+ * Event representing an error that occurred within a telemetry provider.
  *
- * This event encapsulates a `TelemetryItem` and is associated with a specific `ITelemetryProvider` source.
- * It extends the `FrameworkEvent` class, providing a standardized way to emit and handle telemetry-related events.
+ * @remarks
+ * This event is emitted when an error is encountered by an {@link ITelemetryProvider}.
+ * It encapsulates the error details and the source provider.
  *
  * @example
  * ```typescript
- * const event = new TelemetryEvent(item, provider);
+ * const errorEvent = new TelemetryErrorEvent(new Error('Something went wrong'), telemetryProvider);
  * ```
  *
- * @param item - The telemetry item containing event data.
- * @param source - The telemetry provider that is the source of this event.
+ * @extends FrameworkEvent
  */
-class TelemetryEvent extends FrameworkEvent {
-    constructor(item, source) {
-        super('onTelemetry', { detail: { item }, source });
+class TelemetryErrorEvent extends FrameworkEvent {
+    /**
+     * Creates a new `TelemetryErrorEvent`.
+     *
+     * @param error - The error instance that was thrown.
+     * @param source - The telemetry provider where the error originated.
+     */
+    constructor(error, source) {
+        super('onTelemetryError', { detail: { error }, source });
     }
 }
+
 /**
- * Event representing an error that occurred within a telemetry provider.
+ * Represents a telemetry event within the framework.
  *
- * @remarks
- * This event is emitted when an error is encountered by an {@link ITelemetryProvider}.
- * It encapsulates the error details and the source provider.
+ * This event encapsulates a `TelemetryItem` and is associated with a specific `ITelemetryProvider` source.
+ * It extends the `FrameworkEvent` class, providing a standardized way to emit and handle telemetry-related events.
  *
  * @example
  * ```typescript
- * const errorEvent = new TelemetryErrorEvent(new Error('Something went wrong'), telemetryProvider);
+ * const event = new TelemetryEvent(item, provider);
  * ```
  *
- * @extends FrameworkEvent
- *
- * @param error - The error instance that was thrown.
- * @param source - The telemetry provider where the error originated.
+ * @param item - The telemetry item containing event data.
+ * @param source - The telemetry provider that is the source of this event.
  */
-class TelemetryErrorEvent extends FrameworkEvent {
-    constructor(error, source) {
-        super('onTelemetryError', { detail: { error }, source });
+class TelemetryEvent extends FrameworkEvent {
+    /**
+     * Creates a new `TelemetryEvent`.
+     *
+     * @param item - The telemetry item containing event data.
+     * @param source - The telemetry provider that is the source of this event.
+     */
+    constructor(item, source) {
+        super('onTelemetry', { detail: { item }, source });
     }
 }
 
@@ -24942,6 +25256,7 @@ class Measurement {
      */
     clone(resetOptions = {}) {
         const clonedMeasurement = new Measurement(this.#provider, this.#data);
+        // Preserve the original start time when requested, otherwise the clone starts fresh
         if (resetOptions.preserveStartTime) {
             clonedMeasurement.#startTime = this.#startTime;
         }
@@ -24956,6 +25271,7 @@ class Measurement {
      * Resets the measured flag and, unless `preserveStartTime` is true, updates the start time to the current performance time.
      */
     reset(options) {
+        // Keep the existing start time when preserving, otherwise restart the clock
         if (!options?.preserveStartTime) {
             this.#startTime = performance.now();
         }
@@ -24970,6 +25286,7 @@ class Measurement {
      * @param options - Optional measurement options.
      * @param options.markAsMeasured - If true, marks this measurement as completed.
      * @param options.resetStartTime - If true, resets the start time after measuring.
+     * @returns The elapsed duration in milliseconds since the last start time.
      */
     measure(data, options) {
         const measuredData = mergeTelemetryItem(this.#data, data ?? {});
@@ -24978,9 +25295,11 @@ class Measurement {
             ...measuredData,
             value: duration,
         });
+        // Mark as measured only when explicitly requested by the caller
         if (options?.markAsMeasured) {
             this.#measured = true;
         }
+        // Restart the clock only when explicitly requested by the caller
         if (options?.resetStartTime) {
             this.#startTime = performance.now();
         }
@@ -24989,7 +25308,7 @@ class Measurement {
     /**
      * Resolves a given promise, measures the result using the provided options, and returns the resolved value.
      *
-     * @typeParam T - The type of the resolved value from the promise.
+     * @template T - The type of the resolved value from the promise.
      * @param promise - The promise to resolve.
      * @param options - Optional configuration for resolving and measuring:
      *   - `data`: A value or a function that receives the resolved result and returns measurement data.
@@ -25007,7 +25326,7 @@ class Measurement {
      * The function `fn` can return either a value of type `T` or a Promise of type `T`.
      * Optionally, resolution options can be provided.
      *
-     * @typeParam T - The return type of the function to execute.
+     * @template T - The return type of the function to execute.
      * @param fn - A function that returns a value or a Promise to be resolved.
      * @param options - Optional resolution options to customize the resolve behavior.
      * @returns A Promise that resolves to the result of the executed function.
@@ -25025,6 +25344,7 @@ class Measurement {
      * @see https://github.com/tc39/proposal-explicit-resource-management
      */
     [Symbol.dispose]() {
+        // Ensure a measurement is always taken before the instance is discarded
         if (!this.#measured) {
             try {
                 this.measure();
@@ -25067,7 +25387,10 @@ const resolveMetadata = (metadata, args) => {
  * @param args - The arguments required by the metadata extractor, including the telemetry item.
  * @returns An Observable emitting the telemetry item with applied metadata, or an error telemetry item if resolution fails.
  */
+// Deliberately co-located with `resolveMetadata` above
+// fusion-lint-disable-next-line single-export-per-file
 const applyMetadata = (metadata, args) => {
+    // Resolve metadata, merge it into the item, and fall back to an error item on failure
     return resolveMetadata(metadata, args).pipe(defaultIfEmpty({}), // Ensure we always have an object to merge with
     first(), // Take the first emitted value from the metadata extractor
     // Merge the resolved metadata with the telemetry item.
@@ -25121,20 +25444,39 @@ class TelemetryProvider extends BaseModuleProvider {
     #filters;
     #defaultScope;
     #eventProvider;
+    /**
+     * Stream of every telemetry item tracked by this provider.
+     *
+     * @returns An observable emitting each tracked `TelemetryItem`.
+     */
     get items() {
         return this.#items.asObservable();
     }
     /**
      * Returns true if the provider has been initialized.
+     *
+     * @returns `true` when {@link initialize} has completed, otherwise `false`.
      */
     get initialized() {
         return this.#initialized;
     }
     #metadata;
     #modules;
+    /**
+     * Sets the resolved framework module instances used to resolve metadata.
+     *
+     * @param value - The resolved framework module instances.
+     */
     set modules(value) {
         this.#modules = value;
     }
+    /**
+     * Creates a new `TelemetryProvider`.
+     *
+     * @param config - Resolved telemetry configuration (adapters, metadata, scope, filters).
+     * @param deps - Optional dependencies; supply an event module provider to dispatch
+     *   telemetry items as events.
+     */
     constructor(config, deps) {
         super({ version: version$5, config });
         this.#adapters = config?.adapters ?? {};
@@ -25194,11 +25536,13 @@ class TelemetryProvider extends BaseModuleProvider {
     async _initializeAdapters() {
         // Initialize all adapters, do it in parallel
         const adapterEntries = Object.entries(this.#adapters);
+        // Kick off every adapter's initialize() concurrently
         const initializationPromises = adapterEntries.map(([_identifier, adapter]) => adapter.initialize());
         // Wait for all adapters to settle (either resolve or reject)
         const results = await Promise.allSettled(initializationPromises);
         // Check each result and dispatch errors for failed initializations
         for (const [index, result] of results.entries()) {
+            // Only rejected adapters need an error dispatched; fulfilled ones need no action
             if (result.status === 'rejected') {
                 const [identifier] = adapterEntries[index];
                 this._dispatchError(new Error(`Failed to initialize telemetry adapter "${identifier}"`, {
@@ -25215,8 +25559,10 @@ class TelemetryProvider extends BaseModuleProvider {
      *
      * @returns Subscription to the telemetry item stream
      * @protected
+     * @throws {Error} When the provider has not been initialized yet.
      */
     _connectAdapters() {
+        // Adapters can only be connected after the provider has completed initialization
         if (!this.#initialized) {
             throw new Error('TelemetryProvider is not initialized');
         }
@@ -25269,6 +25615,7 @@ class TelemetryProvider extends BaseModuleProvider {
      * @protected
      */
     _dispatchEntityEvent(item) {
+        // Only dispatch when an event provider is configured
         if (this.#eventProvider) {
             // Wrap the telemetry item in a TelemetryEvent and dispatch it
             this.#eventProvider.dispatchEvent(new TelemetryEvent(item, this));
@@ -25281,6 +25628,7 @@ class TelemetryProvider extends BaseModuleProvider {
      * @protected
      */
     _dispatchError(error) {
+        // Only dispatch when an event provider is configured
         if (this.#eventProvider) {
             this.#eventProvider.dispatchEvent(new TelemetryErrorEvent(error, this));
         }
@@ -25298,6 +25646,7 @@ class TelemetryProvider extends BaseModuleProvider {
      * });
      */
     track(item) {
+        // Dispatch to the type-specific tracker so each item is validated with the right schema
         switch (item.type) {
             case TelemetryType.Event:
                 this.trackEvent(item);
@@ -25410,6 +25759,7 @@ class TelemetryProvider extends BaseModuleProvider {
      */
     getAdapter(identifier) {
         const adapter = this.#adapters[identifier];
+        // Report a missing adapter as a telemetry exception rather than throwing
         if (!adapter) {
             this.trackException({
                 name: 'TelemetryAdapterNotFound',
@@ -25477,6 +25827,7 @@ const module$3 = {
 const mapConfiguratorEvents = (
 // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
 configurator) => {
+    // Map each configurator event into a standardized telemetry item shape
     return configurator.event$.pipe(map$1((event) => {
         const item = {
             name: event.name,
@@ -25488,6 +25839,7 @@ configurator) => {
             },
             scope: ['configuration'],
         };
+        // An event carrying an error is reported as a telemetry exception
         if (event.error) {
             return {
                 ...item,
@@ -25495,6 +25847,7 @@ configurator) => {
                 exception: event.error,
             };
         }
+        // An event carrying a metric value is reported as a telemetry metric
         if (event.metric) {
             return {
                 ...item,
@@ -25544,9 +25897,11 @@ configurator, options) => {
     configurator.addConfig({
         module: module$3,
         configure: async (builder, ref) => {
+            // Attach configurator events to the telemetry builder only when opted in
             {
                 builder.attachItems(mapConfiguratorEvents(configurator));
             }
+            // Run the caller-supplied configure callback when one was provided
             if (options?.configure) {
                 await Promise.resolve(options.configure(builder, ref));
             }
@@ -42493,11 +42848,14 @@ class MsalClient extends PublicClientApplication {
      * - **Redirect**: Navigates browser to Microsoft login page. Returns `void` because the browser
      *   navigates to a new page. After redirect completes, the result will be available via
      *   `handleRedirectPromise()` when the app loads on the new page.
+     *
+     * @throws {Error} If an invalid `options.behavior` value is provided.
      */
     async login(options) {
         // Attempt silent authentication first if enabled
         // This provides better UX by avoiding unnecessary popups/redirects
         if (options.silent) {
+            // Warn early when neither an account nor login hint is available for silent SSO
             if (!options.request.account && !options.request.loginHint) {
                 this.getLogger().warning('No account or login hint provided, please provide an account or login hint in the request', options.request.correlationId || FUSION_CORRELATION_ID);
             }
@@ -42555,6 +42913,7 @@ class MsalClient extends PublicClientApplication {
      * ```
      */
     async logout(options) {
+        // Warn when no account was supplied since the active account will be used instead
         if (!options?.account) {
             this.getLogger().warning('No account available for logout, please provide an account in the options', FUSION_CORRELATION_ID);
         }
@@ -42586,18 +42945,23 @@ class MsalClient extends PublicClientApplication {
      *
      * The default silent behavior is determined by presence of account in the request.
      * This provides optimal UX by minimizing unnecessary user interactions.
+     *
+     * @throws {Error} If no `request` is provided in `options`.
      */
     async acquireToken(options) {
         const { behavior = 'redirect', silent = !!options.request?.account, request } = options;
+        // A request is required to know which scopes/account to acquire a token for
         if (!request) {
             throw new Error('No request provided, please provide a request in the options');
         }
+        // Warn when no scopes are requested, since MSAL requires at least one scope
         if (request.scopes.length === 0) {
             this.getLogger().warning('No scopes provided, please provide scopes in the request option, see options.request for more information.', request.correlationId || FUSION_CORRELATION_ID);
         }
         // Attempt silent token acquisition first
         // This fetches from cache or uses refresh token without user interaction
         if (silent) {
+            // Only silent-acquire when an account is available to look up cached tokens for
             if (request.account) {
                 try {
                     this.getLogger().verbose('Attempting to acquire token silently', request.correlationId || FUSION_CORRELATION_ID);
@@ -42657,6 +43021,7 @@ const levelMap = {
 const parseMsalMessage = (message) => {
     // Match the structured format: [timestamp] : [correlationId] : [package] : [level] - [component] - [message]
     const match = message.match(/^\[([^\]]+)\]\s*:\s*\[([^\]]*)\]\s*:\s*([^:]+)\s*:\s*(\w+)\s*-\s*([^-]+)\s*-\s*(.*)$/);
+    // A structured match means we can extract package/component/message parts
     if (match) {
         const [, _timestamp, _correlationId, packageInfo, _logLevel, component, logMessage] = match;
         return {
@@ -42719,7 +43084,7 @@ const createClientLogCallback = (provider, metadata, scope) => {
 };
 
 // Generated by genversion.
-const version$2 = '10.0.0';
+const version$2 = '10.0.2';
 
 /**
  * Zod schema for telemetry configuration validation.
@@ -42772,6 +43137,7 @@ class MsalConfigurator extends BaseConfigBuilder {
      * The MSAL module version being configured.
      *
      * @default Latest
+     * @returns The configured MSAL module version.
      */
     get version() {
         return version$2;
@@ -42787,6 +43153,7 @@ class MsalConfigurator extends BaseConfigBuilder {
         this._set('version', async () => this.version);
         // Auto-detect and integrate telemetry module if available
         this._set('telemetry.provider', async (args) => {
+            // Only resolve the telemetry instance when the telemetry module is registered
             if (args.hasModule('telemetry')) {
                 const telemetry = await args.requireInstance('telemetry');
                 return telemetry;
@@ -43010,7 +43377,7 @@ class MsalConfigurator extends BaseConfigBuilder {
         const config = await MsalConfigSchema.parseAsync(rawConfig);
         // Auto-create client if config provided but no client instance
         // This allows users to provide configuration without manually instantiating the client
-        if (!config.client && !!this.#msalConfig) {
+        if (!config.client && this.#msalConfig) {
             const clientConfig = this.#msalConfig;
             config.telemetry.provider?.trackEvent({
                 name: 'module-msal.configurator._processConfig.creating-client',
@@ -43179,12 +43546,15 @@ class VersionError extends Error {
 function mapVersionToEnumVersion(version) {
     console.log('Resolving version:', version);
     const coercedVersion = semver.coerce(version);
+    // An uncoercible version string cannot be mapped to a module version
     if (!coercedVersion) {
         throw new Error(`Invalid version: ${version}`);
     }
+    // Versions before 4.0.0 (including 2.x) map to the v2-compatible module version
     if (semver.satisfies(coercedVersion, '<4.0.0')) {
         return MsalModuleVersion.V2;
     }
+    // Versions before 7.0.0 (4.x and 5.x/6.x) map to the v4-compatible module version
     if (semver.satisfies(coercedVersion, '<7.0.0')) {
         return MsalModuleVersion.V4;
     }
@@ -43247,6 +43617,7 @@ function resolveVersion(version) {
         warnings.push(missingVersionWarning.message);
         wantedVersion = latestVersion;
     }
+    // Warn when the requested major version trails the latest major version
     if (wantedVersion.major < latestVersion.major) {
         const majorBehindVersionWarning = new VersionError(`Requested major version ${wantedVersion.major} is behind the latest major version ${latestVersion.major}`, wantedVersion, latestVersion);
         warnings.push(majorBehindVersionWarning.message);
@@ -43341,9 +43712,11 @@ function mapAuthenticationResult(result) {
 function createProxyClient(client) {
     const proxy = new Proxy(client, {
         get: (target, prop) => {
+            // Adapt each v4 client member to the v2-compatible shape expected by callers
             switch (prop) {
                 case 'getAllAccounts': {
                     return () => {
+                        // Map each v4 account shape to its v2-compatible equivalent
                         return target.getAllAccounts().map(mapAccountInfo);
                     };
                 }
@@ -43375,6 +43748,7 @@ function createProxyClient(client) {
                 case 'handleRedirectPromise': {
                     return async () => {
                         const result = await target.handleRedirectPromise();
+                        // No redirect result means there's nothing pending to map
                         if (!result) {
                             return null;
                         }
@@ -43384,6 +43758,7 @@ function createProxyClient(client) {
                 case 'getActiveAccount': {
                     return () => {
                         const account = target.getActiveAccount();
+                        // No active account means there's nothing to map
                         if (!account) {
                             return null;
                         }
@@ -43470,6 +43845,8 @@ function createProxyClient(client) {
             }
         },
     });
+    // The Proxy handler above implements every member of `IAuthClient` at runtime via its `get`
+    // trap, but TypeScript can't verify a `Proxy<T>` satisfies `T` structurally.
     return proxy;
 }
 
@@ -43480,6 +43857,7 @@ function createProxyClient(client) {
  * @returns True if the request is in v4 format (has a `request` property with `scopes` and `account`)
  */
 function isRequestV4(req) {
+    // Non-object/null values can never match the v4 request shape
     if (typeof req !== 'object' || req === null) {
         return false;
     }
@@ -43513,6 +43891,7 @@ function createProxyProvider$2(provider) {
     // Use Proxy to intercept property access and provide v2-compatible implementations
     const proxy = new Proxy(provider, {
         get: (target, prop) => {
+            // Adapt each v4 provider member to the v2-compatible shape expected by callers
             switch (prop) {
                 case 'version': {
                     return provider.version;
@@ -43527,6 +43906,7 @@ function createProxyProvider$2(provider) {
                 case 'defaultClient': {
                     // Deprecated property - redirect to client with warning
                     console.warn('defaultClient is deprecated, use client instead');
+                    // Same v2-compatible client wrapper as the `client` case above.
                     return v2Client;
                 }
                 case 'defaultAccount': {
@@ -43610,6 +43990,7 @@ function createProxyProvider$2(provider) {
                     };
                 }
                 default: {
+                    // The proxy is awaited in some contexts, so `then` must resolve to undefined
                     if (prop === 'then') {
                         return undefined;
                     }
@@ -43647,6 +44028,7 @@ function createProxyProvider$1(provider) {
     // Create passthrough proxy that only overrides msalVersion
     return new Proxy(provider, {
         get: (target, prop) => {
+            // Passthrough every property except msalVersion, which reports V4 compatibility
             switch (prop) {
                 case 'msalVersion': {
                     // Report as V4 for compatibility tracking
@@ -43708,6 +44090,9 @@ function createProxyProvider$1(provider) {
  * @param version - The target version string (e.g., '2.0.0', '4.0.0')
  * @returns A proxy provider compatible with the specified version
  *
+ * @template T - The provider interface type expected by the target version.
+ * @throws {Error} If the resolved version is not supported.
+ *
  * @example
  * ```typescript
  * const baseProvider = new MsalProvider(config);
@@ -43717,6 +44102,7 @@ function createProxyProvider$1(provider) {
 function createProxyProvider(provider, version) {
     // Resolve the requested version to determine which proxy to create
     const { enumVersion } = resolveVersion(version);
+    // Build the version-appropriate proxy based on the resolved MSAL module version
     switch (enumVersion) {
         case MsalModuleVersion.V2:
             // Create v2-compatible proxy with legacy API adapters
@@ -43728,6 +44114,7 @@ function createProxyProvider(provider, version) {
             // Create transparent proxy for v5 - passes through to original provider
             return new Proxy(provider, {
                 get: (target, prop) => {
+                    // Delegate every known property/method to the underlying provider
                     switch (prop) {
                         case 'version': {
                             return target.version;
@@ -43814,6 +44201,8 @@ class MsalProvider extends BaseModuleProvider {
      * Default OAuth scopes used when the caller provides no scopes.
      *
      * Resolves to the app's Entra ID configured permissions via the `/.default` scope.
+     *
+     * @returns The default OAuth scopes derived from the configured client ID.
      */
     get defaultScopes() {
         const clientId = this.#client.clientId;
@@ -43836,6 +44225,8 @@ class MsalProvider extends BaseModuleProvider {
      *
      * Provides access to the underlying MSAL PublicClientApplication for advanced use cases.
      * Prefer using provider methods for standard authentication operations.
+     *
+     * @returns The underlying MSAL client instance.
      */
     get client() {
         return this.#client;
@@ -43845,6 +44236,8 @@ class MsalProvider extends BaseModuleProvider {
      *
      * Returns the active account if a user is authenticated, or null if no user is logged in.
      * This is a shorthand for `client.getActiveAccount()`.
+     *
+     * @returns The currently authenticated account, or `null` if no user is logged in.
      */
     get account() {
         return this.#client.getActiveAccount();
@@ -43908,6 +44301,8 @@ class MsalProvider extends BaseModuleProvider {
      *
      * The provider will attempt automatic login with empty scopes if requiresAuth is true.
      * Apps should call acquireToken with actual scopes after initialization completes.
+     *
+     * @throws {Error} If auth code exchange requires a client ID but none is configured.
      */
     async initialize() {
         // Guard: skip authentication when running inside MSAL's hidden iframe.
@@ -43934,6 +44329,7 @@ class MsalProvider extends BaseModuleProvider {
                 // Use MSAL's acquireTokenByCode to exchange backend auth code for tokens
                 // This follows Microsoft's standard SPA Auth Code Flow pattern
                 const clientId = this.#client.clientId;
+                // A client ID is required to build the default scope used for the auth code exchange
                 if (!clientId) {
                     throw new Error('Client ID is required for auth code exchange');
                 }
@@ -43977,6 +44373,7 @@ class MsalProvider extends BaseModuleProvider {
             // Priority 1: Check if returning from redirect-based authentication
             // This handles cases where user just completed a login/acquireToken via redirect
             const handleRedirectResult = await this.handleRedirect();
+            // A returned account means the user just completed a redirect-based login
             if (handleRedirectResult?.account) {
                 // Successfully authenticated via redirect - set as active account
                 // This means the user was redirected to Microsoft and came back authenticated
@@ -43993,6 +44390,7 @@ class MsalProvider extends BaseModuleProvider {
                 // Note: Using default scopes here as we don't know what scopes the app needs yet
                 // App should call acquireToken with actual scopes after initialization
                 const loginResult = await this.login({ request: { scopes: this.defaultScopes } });
+                // Only set the active account when the automatic login actually returned one
                 if (loginResult?.account) {
                     // Automatic login successful - set as active account
                     this.#client.setActiveAccount(loginResult.account);
@@ -44041,6 +44439,8 @@ class MsalProvider extends BaseModuleProvider {
      * @remark Empty scopes are currently tracked as telemetry exceptions but execution continues for monitoring purposes.
      * This behavior will be changed to throw exceptions once sufficient metrics are collected.
      *
+     * @throws {Error} Re-throws any error encountered during token acquisition after tracking it via telemetry.
+     *
      * @example
      * ```typescript
      * // Modern API format
@@ -44083,6 +44483,7 @@ class MsalProvider extends BaseModuleProvider {
         }
         // Handle empty scopes - currently monitoring for telemetry, will throw in future
         if (candidateScopes.length === 0) {
+            // Fall back to the client-id-derived default scope when one is available
             if (defaultScopes.length > 0) {
                 this._trackEvent('acquireToken.missing-scope.defaulted', TelemetryLevel.Warning, {
                     properties: { ...telemetryProperties, defaultScopes },
@@ -44094,7 +44495,7 @@ class MsalProvider extends BaseModuleProvider {
                     exception,
                     properties: telemetryProperties,
                 });
-                // TODO: throw exception when sufficient metrics are collected
+                // TODO(#5113): throw exception when sufficient metrics are collected
                 // This allows us to monitor how often empty scopes are provided before enforcing validation
             }
         }
@@ -44221,6 +44622,7 @@ class MsalProvider extends BaseModuleProvider {
                 // Fall through to interactive authentication
             }
         }
+        // Perform interactive authentication based on specified behavior
         switch (behavior) {
             case 'popup':
                 return await this.#client.loginPopup(request);
@@ -44302,6 +44704,7 @@ class MsalProvider extends BaseModuleProvider {
     async handleRedirect() {
         // Process any pending redirect from authentication flow
         const result = await this.client.handleRedirectPromise();
+        // Only track/log when a redirect result is actually returned
         if (result) {
             // Track successful redirect completion for monitoring
             this._trackEvent('handleRedirect.success', TelemetryLevel.Information, {
@@ -44327,6 +44730,9 @@ class MsalProvider extends BaseModuleProvider {
      * - Version compatibility is tracked via telemetry
      * - Throws error if unsupported version is requested
      *
+     * @template T - The provider interface type expected by the target version.
+     * @throws {Error} If the requested version cannot be resolved or the proxy fails to create.
+     *
      * @example
      * ```typescript
      * // Create v2-compatible proxy
@@ -44456,6 +44862,7 @@ const module$2 = {
         // Priority 2: Check if provider exists in parent module (proxy compatibility)
         // This allows child applications to reuse parent's authentication provider
         const hostProvider = init.ref?.auth;
+        // Reuse the parent's provider (via a version-compatible proxy) when available
         if (hostProvider) {
             try {
                 const proxyProvider = hostProvider.createProxyProvider(config.version);
@@ -44464,7 +44871,7 @@ const module$2 = {
             catch (error) {
                 console.error('MsalModule::Failed to create proxy provider', error);
                 // Fallback to host provider to prevent app breakage during migration
-                // TODO: Consider throwing error instead once all apps are migrated to v4
+                // TODO(#5114): Consider throwing error instead once all apps are migrated to v4
                 return hostProvider;
             }
         }
@@ -44499,7 +44906,7 @@ const module$2 = {
  * ```
  */
 const enableMSAL = (
-// @biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
+// biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
 configurator, configure) => {
     const config = configure ? configureMsal(configure) : { module: module$2 };
     configurator.addConfig(config);
@@ -44533,7 +44940,11 @@ const configureMsal = (configure) => ({
  * @returns A function that takes an Observable stream of `QueryQueueItem` and returns an Observable
  *          stream where each item is processed in sequence by the provided callback.
  */
-const concatQueue = (...args) => (source$) => source$.pipe(concatMap(...args));
+const concatQueue = (...args) => (source$) => {
+    // process queue items one after another, waiting for each to complete before starting the next
+    return source$.pipe(concatMap(...args));
+};
+
 /**
  * Takes a function that transforms each item in a queue and returns an Observable.
  * It processes each item concurrently, potentially leading to out-of-order execution.
@@ -44544,7 +44955,10 @@ const concatQueue = (...args) => (source$) => source$.pipe(concatMap(...args));
  * @returns A function that takes an Observable stream of `QueryQueueItem` and returns an Observable
  *          stream where each item is processed concurrently by the provided callback.
  */
-const mergeQueue = (...args) => (source$) => source$.pipe(mergeMap(...args));
+const mergeQueue = (...args) => (source$) => 
+// process all queue items concurrently, without waiting for previous items to complete
+source$.pipe(mergeMap(...args));
+
 /**
  * Takes a function that transforms each item in a queue and returns an Observable.
  * It processes each item by cancelling the current task if a new one arrives.
@@ -44556,7 +44970,10 @@ const mergeQueue = (...args) => (source$) => source$.pipe(mergeMap(...args));
  *          stream where each item is processed by the provided callback, but only the latest
  *          item's result is emitted.
  */
-const switchQueue = (...args) => (source$) => source$.pipe(switchMap(...args));
+const switchQueue = (...args) => (source$) => 
+// cancel the previous in-flight item whenever a new item arrives
+source$.pipe(switchMap(...args));
+
 /**
  * Transforms a query result Observable into a plain value Observable by extracting the `value` property.
  *
@@ -44579,7 +44996,9 @@ const switchQueue = (...args) => (source$) => source$.pipe(switchMap(...args));
  * });
  * ```
  */
-const queryValue = (source$) => source$.pipe(map$1((entry) => entry.value));
+const queryValue = (source$) => 
+// strip query metadata, keeping only the raw data value
+source$.pipe(map$1((entry) => entry.value));
 
 var REGEX = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
 
@@ -44788,6 +45207,12 @@ v5.URL = URL$1;
 class QueryClientError extends Error {
     type;
     request;
+    /**
+     * Creates a new `QueryClientError`.
+     *
+     * @param type - Whether this error represents a standard failure or an aborted request.
+     * @param args - The error message, optional underlying cause, and optional request context.
+     */
     constructor(type, args) {
         super(args.message, { cause: args.cause });
         this.type = type;
@@ -44855,14 +45280,19 @@ const actions$1 = createActions$1();
  * @param action$ - The stream of actions being dispatched in the system.
  * @returns An Observable that emits execute actions for each request action.
  */
-const handleRequests = (action$) => action$.pipe(filter(actions$1.request.match), map$1((action) => actions$1.execute(action.meta.transaction)));
+const handleRequests = (action$) => 
+// convert each incoming request action into an execute action for its transaction
+action$.pipe(filter(actions$1.request.match), map$1((action) => actions$1.execute(action.meta.transaction)));
+
 /**
  * Handles the execution of a query.
  *
  * @param fetch - The function used to execute the query.
  * @returns A flow that handles the execution of the query.
  */
-const handleExecution = (fetch) => (action$, state$) => action$.pipe(filter(actions$1.execute.match), withLatestFrom(state$), mergeMap(([action, state]) => {
+const handleExecution = (fetch) => (action$, state$) => 
+// execute the query for each request and translate the outcome back into actions
+action$.pipe(filter(actions$1.execute.match), withLatestFrom(state$), mergeMap(([action, state]) => {
     const transaction = action.payload;
     const request = state[transaction];
     // Create an AbortController instance to manage cancellation.
@@ -44875,6 +45305,7 @@ const handleExecution = (fetch) => (action$, state$) => action$.pipe(filter(acti
         }
     }));
     try {
+        // map the fetch outcome to a success/failure action, cancelling early if aborted
         return from(fetch(request.args, controller.signal)).pipe(map$1((value) => actions$1.execute.success({
             ...request,
             status: 'complete',
@@ -44889,6 +45320,7 @@ const handleExecution = (fetch) => (action$, state$) => action$.pipe(filter(acti
         return of(actions$1.execute.failure(err, transaction));
     }
 }));
+
 /**
  * Handles execution failure by scheduling retries according to the provided retry options.
  * If the maximum number of retries is exceeded or no retry options are provided, it emits an error action.
@@ -44898,6 +45330,7 @@ const handleExecution = (fetch) => (action$, state$) => action$.pipe(filter(acti
  */
 const handleFailure = (config) => {
     return (action$, state$) => {
+        // filter for execution failures and decide whether to retry or report an error
         return action$.pipe(
         // Filter for actions that indicate an execution failure.
         filter(actions$1.execute.failure.match), 
@@ -44954,6 +45387,7 @@ const handleFailure = (config) => {
             filter(([_, state]) => !!state[transaction]), 
             // If the request has been removed, throw an error.
             tap(([, state]) => {
+                // Re-check inside the tap since the request could have been removed during the delay
                 if (!state[transaction]) {
                     throw new QueryClientError('error', {
                         message: 'request not found, most likely removed while scheduled for retry',
@@ -45009,9 +45443,9 @@ const createReducer$1 = (initial = {}) => createReducer$2(initial, (builder) =>
     builder.addCase(actions$1.execute, (state, action) => {
         // Locates the query entry in the state using the transaction ID provided in `action.payload`.
         const entry = state[action.payload];
+        // If the entry is found, logs the current timestamp to the `execution` array
+        // to indicate when the execution action was triggered.
         if (entry) {
-            // If the entry is found, logs the current timestamp to the `execution` array
-            // to indicate when the execution action was triggered.
             entry.execution.push(Date.now());
             // Updates the status of the entry to 'active' to reflect that the execution
             // process has started.
@@ -45026,9 +45460,9 @@ const createReducer$1 = (initial = {}) => createReducer$2(initial, (builder) =>
     builder.addCase(actions$1.execute.failure, (state, action) => {
         // Locates the query entry in the state using the transaction ID provided in `action.meta`.
         const entry = state[action.meta.transaction];
+        // If the entry is found, the error information from `action.payload.error` is added to the `errors` array of the entry.
+        // This allows tracking of all errors that have occurred during the execution of the query.
         if (entry) {
-            // If the entry is found, the error information from `action.payload.error` is added to the `errors` array of the entry.
-            // This allows tracking of all errors that have occurred during the execution of the query.
             entry.errors.push(action.payload.error);
             // The status of the entry is updated to 'failed' to indicate that the query execution has encountered an error.
             entry.status = 'failed';
@@ -45063,6 +45497,9 @@ class QueryClientJob extends Observable {
     get status() {
         return this.#status$.value;
     }
+    /**
+     * An Observable stream of the job's status, emitting whenever the status changes.
+     */
     get status$() {
         return this.#status$.asObservable();
     }
@@ -45182,8 +45619,10 @@ class QueryClientJob extends Observable {
      * This method should be called to gracefully end a job that has finished its task.
      * It will also attempt to cancel the job with a completion reason, transitioning its status to 'canceled'
      * if it was in an 'active' state but hadn't yet completed.
+     * @param reason - Optional reason recorded for the completion/cancellation.
      */
     complete(reason) {
+        // Only cancel/complete when the job isn't already in a terminal state
         if (!this.closed) {
             this.cancel(reason ?? `job: ${this.transaction} was completed`);
         }
@@ -45198,6 +45637,9 @@ class QueryClientJob extends Observable {
         const transaction = this.transaction;
         this.#client.cancel(transaction, reason ?? `job: ${transaction} was canceled`);
     }
+    /**
+     * Disposes of the job by completing it, releasing any held resources.
+     */
     [Symbol.dispose]() {
         this.complete();
     }
@@ -45311,6 +45753,7 @@ class QueryClient extends Observable {
      * @returns {Observable<TType>} An Observable stream of successful results.
      */
     get success$() {
+        // narrow the action stream down to successful execute actions and extract their payload
         return this.action$.pipe(filter(actions$1.execute.success.match), map$1(({ payload }) => payload));
     }
     /**
@@ -45319,6 +45762,7 @@ class QueryClient extends Observable {
      * @returns {Observable<QueryClientError>} An Observable stream of query errors.
      */
     get error$() {
+        // narrow the action stream down to client errors and wrap them as QueryClientError instances
         return this.action$.pipe(filterAction('client/error'), withLatestFrom(this.#state), map$1(([action, state]) => {
             const { payload, meta: { transaction }, } = action;
             const request = state[transaction];
@@ -45349,7 +45793,9 @@ class QueryClient extends Observable {
         // Add flows to handle different aspects of the query lifecycle.
         this.#subscription.add(this.#state.addFlow(handleRequests));
         this.#subscription.add(this.#state.addFlow(handleExecution(queryFn)));
-        this.#subscription.add(this.#state.addFlow(handleFailure(Object.assign({ count: 0, delay: 0 }, options?.retry))));
+        // merge caller-provided retry options over the defaults
+        const retryOptions = Object.assign({ count: 0, delay: 0 }, options?.retry);
+        this.#subscription.add(this.#state.addFlow(handleFailure(retryOptions)));
         /**
          * Register effects to emit lifecycle events for different query actions.
          *
@@ -45402,6 +45848,7 @@ class QueryClient extends Observable {
      */
     query(args, opt) {
         const job = new QueryClientJob(this, args, opt);
+        // share a single underlying job execution across all subscribers, replaying past emissions to late subscribers
         const job$ = job.pipe(share({ connector: () => new ReplaySubject(), resetOnRefCountZero: false }));
         Object.defineProperties(job$, {
             transaction: { get: () => job.transaction },
@@ -45411,6 +45858,8 @@ class QueryClient extends Observable {
             cancel: { value: (reason) => job.cancel(reason) },
             complete: { value: () => job.complete() },
         });
+        // `job$` is a plain shared Observable; the properties defined above give it the
+        // `QueryClientJob` shape at runtime, which TypeScript can't infer structurally.
         return job$;
     }
     /**
@@ -45439,7 +45888,10 @@ class QueryClient extends Observable {
      * @returns The request matching the reference, or `undefined` if not found.
      */
     getRequestByRef(ref) {
-        return Object.values(this.#state.value).find((x) => x.ref === ref);
+        const requests = Object.values(this.#state.value);
+        // scan all tracked requests for the one matching the given ref
+        const match = requests.find((x) => x.ref === ref);
+        return match;
     }
     /**
      * Cancels a task by its reference string. If a reason is provided, it will be included
@@ -45449,6 +45901,7 @@ class QueryClient extends Observable {
      */
     cancelTaskByRef(ref, reason) {
         const entry = this.getRequestByRef(ref);
+        // Only cancel when a matching request was actually found
         if (entry?.ref) {
             this.cancel(entry.transaction, reason);
         }
@@ -45460,6 +45913,7 @@ class QueryClient extends Observable {
      * @param {string} [reason] The reason for cancellation.
      */
     cancel(transaction, reason) {
+        // No transaction targeted — cancel every tracked transaction
         if (!transaction) {
             // If no specific transaction is provided, iterate through all transactions
             // in the state and cancel each one, applying a generic cancellation reason.
@@ -45504,7 +45958,7 @@ class QueryClient extends Observable {
  * @template TArgs The type of the arguments associated with the cache entry.
  * @returns An object containing the cache actions.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// biome-ignore lint/suspicious/noExplicitAny: default must be bivariant `any`; `unknown` breaks assignability of concrete `Actions<TType, TArgs>` streams (e.g. in `Observable<Actions<TType, TArgs>>` subscriptions) to the default-typed generic
 function createActions() {
     return {
         /**
@@ -45596,6 +46050,7 @@ function createReducer (actions, initial = {}) {
         .addCase(actions.insert, (state, action) => {
         const { key, entry } = action.payload;
         const record = state[key];
+        // Update the existing entry in place, or create a new one if none exists yet
         if (record) {
             // If the record exists, update the timestamp and increment the update count.
             record.updated = Date.now();
@@ -45623,8 +46078,10 @@ function createReducer (actions, initial = {}) {
         // Handles the 'invalidate' action to invalidate a cache record.
         .addCase(actions.invalidate, (state, action) => {
         const invalidKey = action.payload ? [action.payload] : Object.keys(state);
+        // Invalidate either the single targeted key, or every key when none was specified
         for (const key of invalidKey) {
             const entry = state[key];
+            // Only reset the timestamp when the record actually exists
             if (entry) {
                 // reset the updated timestamp
                 entry.updated = undefined;
@@ -45635,6 +46092,7 @@ function createReducer (actions, initial = {}) {
         .addCase(actions.mutate, (state, action) => {
         const { key, value, updated } = action.payload;
         const record = state[key];
+        // Only apply the mutation when a record exists for this key
         if (record) {
             // Update the record with the new value and metadata.
             record.value = value;
@@ -45660,8 +46118,10 @@ function createReducer (actions, initial = {}) {
             .map(([key]) => key);
         // Remove keys that are not in the list of valid keys.
         if (currentKeys.length !== validKeys.length) {
+            // Walk all current keys and drop the ones that were trimmed away
             for (const key of currentKeys) {
                 const validKeyIndex = validKeys.indexOf(key);
+                // The key survived trimming — remove it from the search list so later lookups are faster
                 if (validKeyIndex !== -1) {
                     // If the key is valid, remove it from the search list.
                     validKeys.splice(validKeyIndex, 1);
@@ -45773,6 +46233,7 @@ class QueryCache {
     constructor(args) {
         const { trimming, initial } = args ?? {};
         this.#state = new FlowSubject(createReducer(actions, initial));
+        // Only wire up automatic trimming when a trimming policy was provided
         if (trimming) {
             this.#state.addEffect('cache/set', () => this.#state.next(actions.trim(trimming)));
         }
@@ -45820,6 +46281,7 @@ class QueryCache {
     invalidate(key) {
         const item = key ? this.#state.value[key] : undefined;
         this.#state.next(actions.invalidate(key, item));
+        // Only emit an event when a specific key was invalidated (not a full-cache clear)
         if (key) {
             this._registerEvent('query_cache_entry_invalidated', {
                 key,
@@ -45831,9 +46293,12 @@ class QueryCache {
      * Mutates an item in the query cache by key.
      * @param {string} key - The key of the item to mutate.
      * @param {QueryCacheMutation | ((current: TType) => QueryCacheMutation)} changes - The changes to apply to the item.
+     * @returns A function that reverts the mutation, restoring the previous value.
+     * @throws {Error} When no cache entry exists for `key`.
      */
     mutate(key, changes) {
         const current = key in this.#state.value ? this.#state.value[key] : undefined;
+        // A missing entry cannot be mutated — mutation only ever updates existing entries
         if (!current) {
             throw new Error(`Cannot mutate cache item with key ${key}: item not found`);
         }
@@ -45857,6 +46322,7 @@ class QueryCache {
         const beforeKeys = new Set(Object.keys(this.#state.value));
         this.#state.next(actions.trim(options));
         const afterKeys = new Set(Object.keys(this.#state.value));
+        // keys that existed before trimming but not after were the ones removed
         const removedKeys = Array.from(beforeKeys).filter((key) => !afterKeys.has(key));
         this._registerEvent('query_cache_trimmed', {
             data: {
@@ -45926,6 +46392,7 @@ class QueryTask extends Subject {
     #created = Date.now();
     /**
      * Gets the creation timestamp of the query task.
+     * @returns The Unix timestamp (in milliseconds) when the task was created.
      */
     get created() {
         return this.#created;
@@ -45933,6 +46400,7 @@ class QueryTask extends Subject {
     #uuid = v4();
     /**
      * Gets the unique identifier of the query task.
+     * @returns The task's generated UUID.
      */
     get uuid() {
         return this.#uuid;
@@ -45958,6 +46426,7 @@ class QueryTask extends Subject {
      * @returns A subscription to the job's result.
      */
     processJob(job) {
+        // map the job's completion into a QueryTaskCompleted record for subscribers
         return job
             .pipe(map$1((result) => {
             const { key, uuid, created } = this;
@@ -45990,6 +46459,13 @@ class QueryEvent {
     type;
     key;
     data;
+    /**
+     * Creates a new Query event.
+     *
+     * @param type - The specific event type identifier.
+     * @param key - The cache key associated with this event.
+     * @param data - Optional event-specific data payload.
+     */
     constructor(type, key, data) {
         this.type = type;
         this.key = key;
@@ -46027,10 +46503,12 @@ const defaultCacheValidator = (expires = 0) => (entry) => (entry.updated ?? 0) +
  * @returns A function that takes a query request and returns an Observable representing the queued request.
  */
 const getQueueOperator = (type = 'switch') => {
+    // A custom queue function was provided, use it directly
     if (typeof type === 'function') {
         return type;
     }
     return (() => {
+        // Map the named operator type to its concrete implementation
         switch (type) {
             case 'concat':
                 return concatQueue;
@@ -46101,7 +46579,6 @@ const getQueueOperator = (type = 'switch') => {
  * @see {@link Query.invalidate} for more details on invalidating cache entries.
  * @see {@link QueueOperatorType} for more details on the available queue operators.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class Query {
     /**
      * Static utility that extracts the raw value from a query result Observable.
@@ -46161,16 +46638,19 @@ class Query {
     #event$;
     /**
      * A public getter for the client instance.
-     * TODO: Implement a proxy to control access to the client.
+     * TODO(#5144): Implement a proxy to control access to the client.
      * This proxy would allow for additional functionality or restrictions when accessing the client instance.
+     * @returns The internal `QueryClient` instance used to fetch data.
      */
     get client() {
-        // TODO: Proxy
+        // TODO(#5144): Proxy
         return this.#client;
     }
     /**
      * Protected helper method to register events if an event observer is configured.
+     * @template TKey - The event type key, constrained to the keys of `QueryEvents`.
      * @param type - The event type
+     * @param key - The cache/query key the event relates to
      * @param data - The event data
      */
     _registerEvent(type, key, data) {
@@ -46178,11 +46658,12 @@ class Query {
     }
     /**
      * A public getter for the cache instance.
-     * TODO: Implement a proxy to control access to the cache.
+     * TODO(#5144): Implement a proxy to control access to the cache.
      * This proxy would allow for additional functionality or restrictions when accessing the cache instance.
+     * @returns The internal `QueryCache` instance used to cache query results.
      */
     get cache() {
-        // TODO: Proxy
+        // TODO(#5144): Proxy
         return this.#cache;
     }
     /**
@@ -46247,6 +46728,7 @@ class Query {
         // shutdown the queue when the query is completed
         this.#subscription.add(() => this.#queue$.complete());
         this.#subscription.add(this.#queue$
+            // register queued events, then apply the queue operator to the ongoing tasks
             .pipe(tap((key) => {
             this._registerEvent('query_queued', key);
         }), 
@@ -46376,9 +46858,11 @@ class Query {
         const { skipResolve, ...args } = opt || {};
         const fn = skipResolve ? firstValueFrom : lastValueFrom;
         return new Promise((resolve, reject) => {
+            // Reject the promise early if the caller aborts via the signal
             if (opt?.signal) {
                 opt.signal.addEventListener('abort', () => reject(new Error('Query aborted')));
             }
+            // Throw if the query completes without emitting a value
             fn(this._query(payload, args).pipe(throwIfEmpty())).then(resolve, reject);
         });
     }
@@ -46400,7 +46884,7 @@ class Query {
     persistentQuery(args, options) {
         const key = this.#generateCacheKey(args);
         const original = this._query(args, options);
-        return new Observable((subscriber) => {
+        const cacheAwareStream = new Observable((subscriber) => {
             subscriber.add(original.subscribe({
                 next: subscriber.next.bind(subscriber),
                 error: subscriber.error.bind(subscriber),
@@ -46409,6 +46893,7 @@ class Query {
             const validateCache = options?.cache?.validate || this.#validateCacheEntry;
             // Subscribe to the cache state and filter for the specific cache entry based on the key.
             subscriber.add(this.cache.state$
+                // narrow the cache state stream down to just this key's entry
                 .pipe(filter((x) => key in x), map$1((x) => ({
                 ...x[key],
                 key,
@@ -46416,9 +46901,9 @@ class Query {
                 hasValidCache: validateCache(x[key], args),
             })))
                 .subscribe(subscriber));
-        }).pipe(
+        });
         // only emit when the transaction changes
-        distinctUntilChanged((a, b) => a.transaction === b.transaction &&
+        return cacheAwareStream.pipe(distinctUntilChanged((a, b) => a.transaction === b.transaction &&
             a.mutated === b.mutated));
     }
     /**
@@ -46438,10 +46923,15 @@ class Query {
      *
      * @param args - The arguments that identify the specific cache entry to be mutated.
      * @param changes - A function that defines the changes to be applied to the cache entry.
+     * @param options - Optional settings; `allowCreation` controls whether a missing cache entry may be created.
+     * @returns A function that reverts the mutation when called.
+     * @throws {Error} When no cache entry exists for `args` and `options.allowCreation` is `undefined`.
      */
     mutate(args, changes, options) {
         const key = this.#generateCacheKey(args);
+        // No existing cache entry for this key — decide whether to create one or fail
         if (key in this.cache.state === false) {
+            // No explicit allowCreation setting provided — fail closed rather than silently creating
             if (options?.allowCreation === undefined) {
                 throw new Error(`Cannot mutate cache item with key ${key}: item not found and option "allowCreation" is false`);
             }
@@ -46489,6 +46979,7 @@ class Query {
      * @returns A function that, when called, will unsubscribe the callback from further invalidation events.
      */
     onInvalidate(cb) {
+        // only forward cache-invalidation actions to the callback
         const subscription = this.#cache.action$
             .pipe(filterAction('cache/invalidate'))
             .subscribe((action) => cb({ detail: { item: action.meta.item } }));
@@ -46503,6 +46994,7 @@ class Query {
      * @returns A function that, when called, will unsubscribe the callback from further mutation events.
      */
     onMutate(cb) {
+        // only forward cache-mutation actions to the callback
         const subscription = this.#cache.action$
             .pipe(filterAction('cache/mutate'))
             .subscribe((action) => cb({ detail: { changes: action.payload, current: action.meta.item } }));
@@ -46560,7 +47052,9 @@ class Query {
     _createTask(key, args, options) {
         // Create a new Observable that represents the query task and will be returned to the caller.
         return new Observable((subscriber) => {
+            // Support cancellation via an AbortSignal
             if (options?.signal) {
+                // Already aborted before subscription — complete immediately without doing any work
                 if (options?.signal.aborted) {
                     this._registerEvent('query_aborted', key);
                     return subscriber.complete();
@@ -46592,6 +47086,7 @@ class Query {
                 // the status indicating that this is a cached response, and a flag indicating whether the cache
                 // is considered valid based on the validation logic.
                 subscriber.next(record);
+                // Complete without fetching when the cache is valid, or invalid entries are intentionally suppressed
                 if (hasValidCache || suppressInvalid) {
                     this._registerEvent('query_completed', key, { data: cacheEntry.value, hasValidCache });
                     // If the cache is valid, or if invalid cache entries should be suppressed (not re-fetched),
@@ -46605,6 +47100,7 @@ class Query {
             }
             // If the cache entry does not exist or is invalid, proceed to queue a new query request.
             const isExistingTask = key in this.#tasks;
+            // No task is already tracking this key — create one and register it before queuing
             if (!isExistingTask) {
                 this.#tasks[key] = new QueryTask(key, args, options);
                 this._registerEvent('query_job_created', key, {
@@ -46683,7 +47179,9 @@ const serviceResponseSelector = (response, postProcess) => {
     const result$ = from(jsonSelector(response)).pipe(
     // parse and validate the response
     map$1((value) => ApiServices.default([]).parse(value)));
+    // Only apply a transform pipeline when the caller supplied one
     if (postProcess) {
+        // Apply the caller-supplied operator (e.g. session overrides) before emitting
         return result$.pipe(postProcess);
     }
     return result$;
@@ -46734,7 +47232,9 @@ class ServiceDiscoveryClient {
     /** {@inheritDoc IServiceDiscoveryClient.resolveService} */
     async resolveService(key, allow_cache) {
         const services = await this.resolveServices(allow_cache);
+        // Locate the service matching the requested key
         const service = services.find((s) => s.key === key);
+        // Fail loudly when the requested key doesn't resolve to a known service
         if (!service) {
             throw Error(`Failed to resolve service, invalid key [${key}]`);
         }
@@ -46775,6 +47275,7 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
      * @throws {Error} When the HTTP module is not registered.
      */
     async _createConfig(init, initial) {
+        // The service discovery client depends on the http module being registered
         if (!init.hasModule('http')) {
             throw new Error('http module is required');
         }
@@ -46782,6 +47283,7 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
         if (!this._has('discoveryClient')) {
             // check if http module has a client with key 'service_discovery'
             const httpProvider = await init.requireInstance('http');
+            // Auto-configure only when a matching http client has actually been registered
             if (httpProvider.hasClient('service_discovery')) {
                 this.configureServiceDiscoveryClientByClientKey('service_discovery');
             }
@@ -46798,6 +47300,7 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
      * @throws {Error} When `discoveryClient` has not been configured.
      */
     _processConfig(config, init) {
+        // A discovery client is mandatory before the config can be considered complete
         if (!config.discoveryClient) {
             throw new Error('discoveryClient is required, please configure it');
         }
@@ -46852,6 +47355,7 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
     configureServiceDiscoveryClient(configCallback) {
         this.setServiceDiscoveryClient(async (args) => {
             const { httpClient, endpoint } = (await lastValueFrom(from(configCallback(args)))) ?? {};
+            // Only construct the client when the factory actually returned an http client
             if (httpClient) {
                 return new ServiceDiscoveryClient({
                     http: httpClient,
@@ -46867,7 +47371,9 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
                         // Check if there are any session overrides in session storage.
                         try {
                             const sessionOverrides = JSON.parse(storage.getItem('overriddenServiceDiscoveryUrls') || '{}');
+                            // Apply each session override onto the service matching its key
                             for (const [key, { url, scopes }] of Object.entries(sessionOverrides)) {
+                                // Locate the service this override applies to
                                 const service = input.find((service) => service.key === key);
                                 // If the service can be found, override the values with the values
                                 // from session override.
@@ -46879,6 +47385,8 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
                             }
                         }
                         catch (e) {
+                            // Malformed or missing session storage overrides are not fatal — fall back to
+                            // the unmodified input and just log for visibility.
                             console.error('Failed to JSON parse session overrides: "overriddenServiceDiscoveryUrls"', e);
                         }
                         return input;
@@ -46921,7 +47429,7 @@ class ServiceDiscoveryConfigurator extends BaseConfigBuilder {
 }
 
 // Generated by genversion.
-const version$1 = '10.0.1';
+const version$1 = '10.0.2';
 
 /**
  * Default implementation of {@link IServiceDiscoveryProvider}.
@@ -46956,6 +47464,7 @@ class ServiceDiscoveryProvider extends BaseModuleProvider {
     /** {@inheritDoc IServiceDiscoveryProvider.createClient} */
     async createClient(name, opt) {
         const service = await this.resolveService(name);
+        // A missing service configuration means the http client can't be constructed
         if (!service) {
             throw Error(`Could not load configuration of service [${name}]`);
         }
@@ -47135,7 +47644,7 @@ class BaseTelemetryAdapter {
      * without performing any initialization. It calls the protected `_initialize` method which
      * subclasses can override to provide custom initialization logic.
      *
-     * TODO: Consider changing return type from Promise<void> to Promise<TelemetryItem[]>
+     * TODO(#5112): Consider changing return type from Promise<void> to Promise<TelemetryItem[]>
      * to allow adapters to return telemetry items (errors/warnings) that occurred during
      * initialization, eliminating the chicken-and-egg problem with reporting init errors.
      *
@@ -47202,6 +47711,7 @@ class ConsoleAdapter extends BaseTelemetryAdapter {
      * @returns CSS background color string
      */
     _generateTitleBackground(lvl) {
+        // Pick a background color matching the severity of this telemetry level
         switch (lvl) {
             case TelemetryLevel.Critical:
                 return 'rgb(255, 0, 0)';
@@ -47228,12 +47738,12 @@ class ConsoleAdapter extends BaseTelemetryAdapter {
      * @returns Formatted time string (ms, s, or m s format)
      */
     _formatMetric = (value) => {
+        // Show milliseconds for values under 1 second
         if (value < 1000) {
-            // Show milliseconds for values under 1 second
             return `${Math.round(value)}ms`;
         }
+        // Show seconds with 1 decimal for values under 1 minute
         if (value < 60000) {
-            // Show seconds with 1 decimal for values under 1 minute
             return `${(value / 1000).toFixed(1)}s`;
         }
         // For longer durations, show minutes and seconds
@@ -47275,6 +47785,7 @@ class ConsoleAdapter extends BaseTelemetryAdapter {
             metadata,
             scope,
         };
+        // Dispatch to the right console format based on the telemetry item's type
         switch (type) {
             case TelemetryType.Event:
                 // Log events with base data
@@ -47301,6 +47812,7 @@ class ConsoleAdapter extends BaseTelemetryAdapter {
      * @param msg - Additional message arguments to log
      */
     _log(lvl, title, ...msg) {
+        // Pick the console method matching this telemetry level's severity
         switch (lvl) {
             case TelemetryLevel.Critical:
             case TelemetryLevel.Error:
@@ -47334,10 +47846,15 @@ class ConsoleAdapter extends BaseTelemetryAdapter {
  */
 const createPortalEntryPoint = (...segments) => {
     const normalized = segments
+        // Drop undefined/null segments before further processing
         .filter((segment) => segment !== undefined && segment !== null)
+        // Trim stray whitespace from each segment
         .map((segment) => segment.trim())
+        // Drop any segments that became empty after trimming
         .filter(Boolean)
+        // Strip leading slashes from every segment (and trailing slashes from the first)
         .map((segment, index) => {
+        // The first segment may have a trailing slash (e.g. a base URL) that needs stripping
         if (index === 0) {
             return segment.replace(/\/+$/g, '');
         }
@@ -47378,6 +47895,7 @@ const createPortalEntryPoint = (...segments) => {
  */
 async function registerServiceWorker(framework) {
     const telemetry = framework.telemetry;
+    // Bail out early when the browser has no service worker support at all
     if ('serviceWorker' in navigator === false) {
         const exception = new Error('Service workers are not supported in this browser.');
         exception.name = 'ServiceWorkerNotSupported';
@@ -47388,6 +47906,7 @@ async function registerServiceWorker(framework) {
         throw exception;
     }
     const resourceConfigs = import.meta.env.FUSION_SPA_SERVICE_WORKER_RESOURCES;
+    // The worker needs a resource config to know which requests to intercept
     if (!resourceConfigs) {
         const exception = new Error('Service worker config is not defined.');
         exception.name = 'ServiceWorkerConfigNotDefined';
@@ -47411,10 +47930,12 @@ async function registerServiceWorker(framework) {
         navigator.serviceWorker.startMessages();
         // listen for messages from the service worker (set up before registration)
         navigator.serviceWorker.addEventListener('message', async (event) => {
+            // Only the GET_TOKEN message type requests a token from this handler
             if (event.data.type === 'GET_TOKEN') {
                 try {
                     // extract scopes from the event data
                     const scopes = event.data.scopes;
+                    // Scopes must be a real array before they can be used to request a token
                     if (!scopes || !Array.isArray(scopes)) {
                         const error = new Error('Invalid scopes provided');
                         error.name = 'InvalidScopesProvided';
@@ -47422,6 +47943,7 @@ async function registerServiceWorker(framework) {
                     }
                     // request a token from the MSAL module
                     const token = await framework.auth.acquireToken({ request: { scopes } });
+                    // A missing token means acquisition failed and the worker can't proceed
                     if (!token) {
                         const error = new Error('Failed to acquire token');
                         error.name = 'FailedToAcquireToken';
@@ -47467,9 +47989,11 @@ async function registerServiceWorker(framework) {
         if (registration.waiting) {
             sendConfigToServiceWorker(registration.waiting);
         }
+        // A worker still installing needs to reach the 'activated' state before it can receive config
         if (registration.installing) {
             registration.installing.addEventListener('statechange', (event) => {
                 const worker = event.target;
+                // Only send config once the worker has fully activated
                 if (worker.state === 'activated') {
                     sendConfigToServiceWorker(worker);
                 }
@@ -47477,6 +48001,7 @@ async function registerServiceWorker(framework) {
         }
         // Listen for controller changes (happens during hard refresh or updates)
         navigator.serviceWorker.addEventListener('controllerchange', () => {
+            // Only send config once this page is actually controlled by a worker
             if (navigator.serviceWorker.controller) {
                 sendConfigToServiceWorker(navigator.serviceWorker.controller);
             }
@@ -47490,6 +48015,7 @@ async function registerServiceWorker(framework) {
         });
         // ensure we have an active service worker before sending config
         const activeWorker = readyRegistration.active;
+        // Without an active worker there's nothing to send config to
         if (!activeWorker) {
             console.error('[Service Worker Registration] Service worker is not active after ready state');
             return;
@@ -47509,6 +48035,7 @@ async function registerServiceWorker(framework) {
                 navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
                 // Polling fallback and timeout to prevent infinite waiting
                 checkInterval = setInterval(() => {
+                    // Stop polling once a controller has taken over
                     if (navigator.serviceWorker.controller)
                         finish();
                 }, 200);
@@ -47536,7 +48063,7 @@ async function registerServiceWorker(framework) {
 }
 
 // Generated by genversion.
-const version = '4.0.12';
+const version = '4.0.14';
 
 // Allow dynamic import without vite
 const importWithoutVite = (path) => import(/* @vite-ignore */ path);
@@ -47582,6 +48109,7 @@ enableTelemetry(configurator, {
                 },
                 // biome-ignore lint/suspicious/noExplicitAny: we need to use any here to allow dynamic properties
             };
+            // Only attach user metadata when the auth module has resolved an account
             if (modules?.auth) {
                 metadata.fusion.user = {
                     id: modules.auth.account?.homeAccountId,
@@ -47646,8 +48174,8 @@ enableTelemetry(configurator, {
     document.body.innerHTML = '';
     document.body.appendChild(el);
     const portalEntryPoint = createPortalEntryPoint(portalProxy ? '/portal-proxy' : undefined, portal_manifest.build.assetPath, portal_manifest.build.templateEntry);
-    // @todo: should test if the entrypoint is external or internal
-    // @todo: add proper return type
+    // TODO(#5066): should test if the entrypoint is external or internal
+    // TODO(#5066): add proper return type
     const { render } = await measurement
         .clone()
         .resolve(importWithoutVite(portalEntryPoint), {