GeezerVison

Conceptually, the agent concept is an architecture-independent, idealized "thread" in which JavaScript code runs. Such code can involve multiple globals/realms that can synchronously access each other, and thus needs to run in a single execution thread.

Two Window objects having the same agent does not indicate they can directly access all objects created in each other's realms. They would have to be same origin-domain; see IsPlatformObjectSameOrigin.

To create an agent, given a boolean canBlock:

1. Let signifier be a new unique internal value.

2. Let candidateExecution be a new candidate execution.

3. Let agent be a new agent whose [[CanBlock]] is canBlock, [[Signifier]] is signifier, [[CandidateExecution]] is candidateExecution, and [[IsLockFree1]], [[IsLockFree2]], and [[LittleEndian]] are set at the implementation's discretion.

4. Set agent's event loop to a new event loop.

5. Return agent.

For a realm realm, the agent whose [[Signifier]] is realm.[[AgentSignifier]] is the realm's agent.

The relevant agent for a platform object platformObject is platformObject's relevant realm's agent.

To obtain a similar-origin window agent, given an origin origin, a browsing context group group, and a boolean requestsOAC, run these steps:

1. Let site be the result of obtaining a site with origin.

2. Let key be site.

3. If group's cross-origin isolation mode is not "none", then set key to origin.

4. Otherwise, if group's historical agent cluster key map[origin] exists, then set key to group's historical agent cluster key map[origin].

5. Otherwise:

   1. If requestsOAC is true, then set key to origin.

   2. Set group's historical agent cluster key map[origin] to key.

6. If group's agent cluster map[key] does not exist:

   1. Let agentCluster be a new agent cluster.

   2. Set agentCluster's cross-origin isolation mode to group's cross-origin isolation mode.

   3. If key is an origin:

      1. Assert: key is origin.

      2. Set agentCluster's is origin-keyed to true.

   4. Add the result of creating an agent, given false, to agentCluster.

   5. Set group's agent cluster map[key] to agentCluster.

7. Return the single similar-origin window agent contained in group's agent cluster map[key].

To obtain a worker/worklet agent, given an environment settings object or null outside settings, a boolean isTopLevel, and a boolean canBlock, run these steps:

1. Let agentCluster be null.

2. If isTopLevel is true:

   1. Set agentCluster to a new agent cluster.

   2. Set agentCluster's is origin-keyed to true.

      These workers can be considered to be origin-keyed. However, this is not exposed through any APIs (in the way that originAgentCluster exposes the origin-keyedness for windows).

3. Otherwise:

   1. Assert: outside settings is not null.

   2. Let ownerAgent be outside settings's realm's agent.

   3. Set agentCluster to the agent cluster which contains ownerAgent.

4. Let agent be the result of creating an agent given canBlock.

5. Add agent to agentCluster.

6. Return agent.

To obtain a dedicated/shared worker agent, given an environment settings object outside settings and a boolean isShared, return the result of obtaining a worker/worklet agent given outside settings, isShared, and true.

To obtain a worklet agent, given an environment settings object outside settings, return the result of obtaining a worker/worklet agent given outside settings, false, and false.

To obtain a service worker agent, return the result of obtaining a worker/worklet agent given null, true, and false.

The following pairs of global objects are each within the same agent cluster, and thus can use SharedArrayBuffer instances to share memory with each other:

• A Window object and a dedicated worker that it created.

• A worker (of any type) and a dedicated worker it created.

• A Window object A and the Window object of an iframe element that A created that could be same origin-domain with A.

• A Window object and a same origin-domain Window object that opened it.

• A Window object and a worklet that it created.

The following pairs of global objects are not within the same agent cluster, and thus cannot share memory:

• A Window object and a shared worker it created.

• A worker (of any type) and a shared worker it created.

• A Window object and a service worker it created.

• A Window object A and the Window object of an iframe element that A created that cannot be same origin-domain with A.

• Any two Window objects with no opener or ancestor relationship. This holds even if the two Window objects are same origin.

An environment settings object's responsible event loop is its global object's relevant agent's event loop.

A global object is a JavaScript object that is the [[GlobalObject]] field of a realm.

To create a new realm in an agent agent, optionally with instructions to create a global object or a global this binding (or both), the following steps are taken:

1. Perform InitializeHostDefinedRealm() with the provided customizations for creating the global object and the global this binding.

2. Let realm execution context be the running JavaScript execution context.

   This is the JavaScript execution context created in the previous step.

3. Remove realm execution context from the JavaScript execution context stack.

4. Let realm be realm execution context's Realm component.

5. If agent's agent cluster's cross-origin isolation mode is "none":

   1. Let global be realm's global object.

   2. Let status be ! global.[[Delete]]("SharedArrayBuffer").

   3. Assert: status is true.

   This is done for compatibility with web content and there is some hope that this can be removed in the future. Web developers can still get at the constructor through new WebAssembly.Memory({ shared:true, initial:0, maximum:0 }).buffer.constructor.

6. Return realm execution context.

Consider the following pages, with a.html being loaded in a browser window, b.html being loaded in an iframe as shown, and c.html and d.html omitted (they can simply be empty documents):

<!-- a.html -->
<!DOCTYPE html>
<html lang="en">
<title>Entry page</title>

<iframe src="b.html"></iframe>
<button onclick="frames[0].hello()">Hello</button>

<!--b.html -->
<!DOCTYPE html>
<html lang="en">
<title>Incumbent page</title>

<iframe src="c.html" id="c"></iframe>
<iframe src="d.html" id="d"></iframe>

<script>
  const c = document.querySelector("#c").contentWindow;
  const d = document.querySelector("#d").contentWindow;

  window.hello = () => {
    c.print.call(d);
  };
</script>

Each page has its own browsing context, and thus its own realm, global object, and environment settings object.

When the print() method is called in response to pressing the button in a.html:

• The entry realm is that of a.html.

• The incumbent realm is that of b.html.

• The current realm is that of c.html (since it is the print() method from c.html whose code is running).

• The relevant realm of the object on which the print() method is being called is that of d.html.

One reason why the relevant concept is generally a better default choice than the current concept is that it is more suitable for creating an object that is to be persisted and returned multiple times. For example, the navigator.getBattery() method creates promises in the relevant realm for the Navigator object on which it is invoked. This has the following impact: [BATTERY]

<!-- outer.html -->
<!DOCTYPE html>
<html lang="en">
<title>Relevant realm demo: outer page</title>
<script>
  function doTest() {
    const promise = navigator.getBattery.call(frames[0].navigator);

    console.log(promise instanceof Promise);           // logs false
    console.log(promise instanceof frames[0].Promise); // logs true

    frames[0].hello();
  }
</script>
<iframe src="inner.html" onload="doTest()"></iframe>

<!-- inner.html -->
<!DOCTYPE html>
<html lang="en">
<title>Relevant realm demo: inner page</title>
<script>
  function hello() {
    const promise = navigator.getBattery();

    console.log(promise instanceof Promise);        // logs true
    console.log(promise instanceof parent.Promise); // logs false
  }
</script>

If the algorithm for the getBattery() method had instead used the current realm, all the results would be reversed. That is, after the first call to getBattery() in outer.html, the Navigator object in inner.html would be permanently storing a Promise object created in outer.html's realm, and calls like that inside the hello() function would thus return a promise from the "wrong" realm. Since this is undesirable, the algorithm instead uses the relevant realm, giving the sensible results indicated in the comments above.

With this in hand, we define the entry execution context to be the most recently pushed item in the JavaScript execution context stack that is a realm execution context. The entry realm is the entry execution context's Realm component.

Then, the entry settings object is the environment settings object of the entry realm.

Similarly, the entry global object is the global object of the entry realm.

To prepare to run a callback with an environment settings object settings:

1. Push settings onto the backup incumbent settings object stack.

2. Let context be the topmost script-having execution context.

3. If context is not null, increment context's skip-when-determining-incumbent counter.

To clean up after running a callback with an environment settings object settings:

1. Let context be the topmost script-having execution context.

   This will be the same as the topmost script-having execution context inside the corresponding invocation of prepare to run a callback.

2. If context is not null, decrement context's skip-when-determining-incumbent counter.

3. Assert: the topmost entry of the backup incumbent settings object stack is settings.

4. Remove settings from the backup incumbent settings object stack.

Here, the topmost script-having execution context is the topmost entry of the JavaScript execution context stack that has a non-null ScriptOrModule component, or null if there is no such entry in the JavaScript execution context stack.

With all this in place, the incumbent settings object is determined as follows:

1. Let context be the topmost script-having execution context.

2. If context is null, or if context's skip-when-determining-incumbent counter is greater than zero:

   1. Assert: the backup incumbent settings object stack is not empty.

      This assert would fail if you try to obtain the incumbent settings object from inside an algorithm that was triggered neither by calling scripts nor by Web IDL invoking a callback. For example, it would trigger if you tried to obtain the incumbent settings object inside an algorithm that ran periodically as part of the event loop, with no involvement of author code. In such cases the incumbent concept cannot be used.

   2. Return the topmost entry of the backup incumbent settings object stack.

3. Return context's Realm component's settings object.

Then, the incumbent realm is the realm of the incumbent settings object.

Similarly, the incumbent global object is the global object of the incumbent settings object.

Consider the following starter example:

<!DOCTYPE html>
<iframe></iframe>
<script>
  frames[0].postMessage("some data", "*");
</script>

There are two interesting environment settings objects here: that of window, and that of frames[0]. Our concern is: what is the incumbent settings object at the time that the algorithm for postMessage() executes?

It should be that of window, to capture the intuitive notion that the author script responsible for causing the algorithm to happen is executing in window, not frames[0]. This makes sense: the window post message steps use the incumbent settings object to determine the source property of the resulting MessageEvent, and in this case window is definitely the source of the message.

Let us now explain how the steps given above give us our intuitively-desired result of window's relevant settings object.

When the window post message steps look up the incumbent settings object, the topmost script-having execution context will be that corresponding to the script element: it was pushed onto the JavaScript execution context stack as part of ScriptEvaluation during the run a classic script algorithm. Since there are no Web IDL callback invocations involved, the context's skip-when-determining-incumbent counter is zero, so it is used to determine the incumbent settings object; the result is the environment settings object of window.

(Note how the environment settings object of frames[0] is the relevant settings object of this at the time the postMessage() method is called, and thus is involved in determining the target of the message. Whereas the incumbent is used to determine the source.)

Consider the following more complicated example:

<!DOCTYPE html>
<iframe></iframe>
<script>
  const bound = frames[0].postMessage.bind(frames[0], "some data", "*");
  window.setTimeout(bound);
</script>

This example is very similar to the previous one, but with an extra indirection through Function.prototype.bind as well as setTimeout(). But, the answer should be the same: invoking algorithms asynchronously should not change the incumbent concept.

This time, the result involves more complicated mechanisms:

When bound is converted to a Web IDL callback type, the incumbent settings object is that corresponding to window (in the same manner as in our starter example above). Web IDL stores this as the resulting callback value's callback context.

When the task posted by setTimeout() executes, the algorithm for that task uses Web IDL to invoke the stored callback value. Web IDL in turn calls the above prepare to run a callback algorithm. This pushes the stored callback context onto the backup incumbent settings object stack. At this time (inside the timer task) there is no author code on the stack, so the topmost script-having execution context is null, and nothing gets its skip-when-determining-incumbent counter incremented.

Invoking the callback then calls bound, which in turn calls the postMessage() method of frames[0]. When the postMessage() algorithm looks up the incumbent settings object, there is still no author code on the stack, since the bound function just directly calls the built-in method. So the topmost script-having execution context will be null: the JavaScript execution context stack only contains an execution context corresponding to postMessage(), with no ScriptEvaluation context or similar below it.

This is where we fall back to the backup incumbent settings object stack. As noted above, it will contain as its topmost entry the relevant settings object of window. So that is what is used as the incumbent settings object while executing the postMessage() algorithm.

Consider this final, even more convoluted example:

<!-- a.html -->
<!DOCTYPE html>
<button>click me</button>
<iframe></iframe>
<script>
const bound = frames[0].location.assign.bind(frames[0].location, "https://example.com/");
document.querySelector("button").addEventListener("click", bound);
</script>

<!-- b.html -->
<!DOCTYPE html>
<iframe src="a.html"></iframe>
<script>
  const iframe = document.querySelector("iframe");
  iframe.onload = function onLoad() {
    iframe.contentWindow.document.querySelector("button").click();
  };
</script>

Again there are two interesting environment settings objects in play: that of a.html, and that of b.html. When the location.assign() method triggers the Location-object navigate algorithm, what will be the incumbent settings object? As before, it should intuitively be that of a.html: the click listener was originally scheduled by a.html, so even if something involving b.html causes the listener to fire, the incumbent responsible is that of a.html.

The callback setup is similar to the previous example: when bound is converted to a Web IDL callback type, the incumbent settings object is that corresponding to a.html, which is stored as the callback's callback context.

When the click() method is called inside b.html, it dispatches a click event on the button that is inside a.html. This time, when the prepare to run a callback algorithm executes as part of event dispatch, there is author code on the stack; the topmost script-having execution context is that of the onLoad function, whose skip-when-determining-incumbent counter gets incremented. Additionally, a.html's environment settings object (stored as the EventHandler's callback context) is pushed onto the backup incumbent settings object stack.

Now, when the Location-object navigate algorithm looks up the incumbent settings object, the topmost script-having execution context is still that of the onLoad function (due to the fact we are using a bound function as the callback). Its skip-when-determining-incumbent counter value is one, however, so we fall back to the backup incumbent settings object stack. This gives us the environment settings object of a.html, as expected.

Note that this means that even though it is the iframe inside a.html that navigates, it is a.html itself that is used as the source Document, which determines among other things the request client. This is perhaps the only justifiable use of the incumbent concept on the web platform; in all other cases the consequences of using it are simply confusing and we hope to one day switch them to use current or relevant as appropriate.

Then, the current settings object is the environment settings object of the current realm.

Similarly, the current global object is the global object of the current realm.

The relevant realm for a platform object is the value of its [[Realm]] field.

Then, the relevant settings object for a platform object o is the environment settings object of the relevant realm for o.

Similarly, the relevant global object for a platform object o is the global object of the relevant realm for o.

Scripting is enabled for an environment settings object settings when all of the following conditions are true:

• The user agent supports scripting.
• The user has not disabled scripting for settings at this time. (User agents may provide users with the option to disable scripting globally, or in a finer-grained manner, e.g., on a per-origin basis, down to the level of individual environment settings objects.)
• Either settings's global object is not a Window object, or settings's global object's associated Document's active sandboxing flag set does not have its sandboxed scripts browsing context flag set.
• The result of WebDriver BiDi scripting is enabled with settings is true.

Scripting is disabled for an environment settings object when scripting is not enabled for it, i.e., when any of the above conditions are false.

Scripting is disabled for a platform object object if any of the following are true:

• Scripting is disabled for object's relevant settings object.

• The object implements Node, and object's node document's browsing context is null.

• The object implements Window and object's associated Document's browsing context is null.

Scripting is enabled for a platform object object, when object's scripting is not disabled.

An environment environment is a secure context if the following algorithm returns true:

1. If environment is an environment settings object:

   1. Let global be environment's global object.

   2. If global is a WorkerGlobalScope:

      1. If global's owner set[0]'s relevant settings object is a secure context, then return true.

         We only need to check the 0th item since they will necessarily all be consistent.

      2. Return false.

   3. If global is a WorkletGlobalScope, then return true.

      Worklets can only be created in secure contexts.

2. If environment's top-level creation URL's scheme is "data", then return false.

3. If the result of Is url potentially trustworthy? given environment's top-level creation URL is "Potentially Trustworthy", then return true.

4. Return false.

An environment is a non-secure context if it is not a secure context.

The active script is determined by the following algorithm:

1. Let record be GetActiveScriptOrModule().

2. If record is null, return null.

3. Return record.[[HostDefined]].

The default script fetch options are a script fetch options whose cryptographic nonce is the empty string, integrity metadata is the empty string, parser metadata is "not-parser-inserted", credentials mode is "same-origin", referrer policy is the empty string, and fetch priority is "auto".

To set up the classic script request, given a request request and a script fetch options options, set request's cryptographic nonce metadata to options's cryptographic nonce, its integrity metadata to options's integrity metadata, its parser metadata to options's parser metadata, its referrer policy to options's referrer policy, its render-blocking to options's render-blocking, and its priority to options's fetch priority.

To set up the module script request, given a request request and a script fetch options options, set request's cryptographic nonce metadata to options's cryptographic nonce, its integrity metadata to options's integrity metadata, its parser metadata to options's parser metadata, its credentials mode to options's credentials mode, its referrer policy to options's referrer policy, its render-blocking to options's render-blocking, and its priority to options's fetch priority.

To get the descendant script fetch options given a script fetch options originalOptions, a URL url, and an environment settings object settingsObject:

1. Let newOptions be a copy of originalOptions.

2. Let integrity be the result of resolving a module integrity metadata with url and settingsObject.

3. Set newOptions's integrity metadata to integrity.

4. Set newOptions's fetch priority to "auto".

5. Return newOptions.

To resolve a module integrity metadata, given a URL url and an environment settings object settingsObject:

1. Let map be settingsObject's global object's import map.

2. If map's integrity[url] does not exist, then return the empty string.

3. Return map's integrity[url].

Several of the below algorithms can be customized with a perform the fetch hook algorithm, which takes a request, a boolean isTopLevel, and a processCustomFetchResponse algorithm. It runs processCustomFetchResponse with a response and either null (on failure) or a byte sequence containing the response body. isTopLevel will be true for all classic script fetches, and for the initial fetch when fetching an external module script graph or fetching a module worker script graph, but false for the fetches resulting from import statements encountered throughout the graph or from import() expressions.

To fetch a classic script given a URL url, an environment settings object settingsObject, a script fetch options options, a CORS settings attribute state corsSetting, an encoding encoding, and an algorithm onComplete, run these steps. onComplete must be an algorithm accepting null (on failure) or a classic script (on success).

1. Let request be the result of creating a potential-CORS request given url, "script", and corsSetting.

2. Set request's client to settingsObject.

3. Set request's initiator type to "script".

4. Set up the classic script request given request and options.

5. Fetch request with the following processResponseConsumeBody steps given response response and null, failure, or a byte sequence bodyBytes:

   response can be either CORS-same-origin or CORS-cross-origin. This only affects how error reporting happens.

   1. Set response to response's unsafe response.

   2. If any of the following are true:

      • bodyBytes is null or failure; or

      • response's status is not an ok status,

      then run onComplete given null, and abort these steps.

      For historical reasons, this algorithm does not include MIME type checking, unlike the other script-fetching algorithms in this section.

   3. Let potentialMIMETypeForEncoding be the result of extracting a MIME type given response's header list.

   4. Set encoding to the result of legacy extracting an encoding given potentialMIMETypeForEncoding and encoding.

      This intentionally ignores the MIME type essence.

   5. Let sourceText be the result of decoding bodyBytes to Unicode, using encoding as the fallback encoding.

      The decode algorithm overrides encoding if the file contains a BOM.

   6. Let mutedErrors be true if response was CORS-cross-origin, and false otherwise.

   7. Let script be the result of creating a classic script given sourceText, settingsObject, response's URL, options, mutedErrors, and url.

   8. Run onComplete given script.

To fetch a classic worker script given a URL url, an environment settings object fetchClient, a destination destination, an environment settings object settingsObject, an algorithm onComplete, and an optional perform the fetch hook performFetch, run these steps. onComplete must be an algorithm accepting null (on failure) or a classic script (on success).

1. Let request be a new request whose URL is url, client is fetchClient, destination is destination, initiator type is "other", mode is "same-origin", credentials mode is "same-origin", parser metadata is "not parser-inserted", and whose use-URL-credentials flag is set.

2. If performFetch was given, run performFetch with request, true, and with processResponseConsumeBody as defined below.

   Otherwise, fetch request with processResponseConsumeBody set to processResponseConsumeBody as defined below.

   In both cases, let processResponseConsumeBody given response response and null, failure, or a byte sequence bodyBytes be the following algorithm:

   1. Set response to response's unsafe response.

   2. If any of the following are true:

      • bodyBytes is null or failure; or

      • response's status is not an ok status,

      then run onComplete given null, and abort these steps.

   3. If all of the following are true:

      • response's URL's scheme is an HTTP(S) scheme; and

      • the result of extracting a MIME type from response's header list is not a JavaScript MIME type,

      then run onComplete given null, and abort these steps.

      Other fetch schemes are exempted from MIME type checking for historical web-compatibility reasons. We might be able to tighten this in the future; see issue #3255.

   4. Let sourceText be the result of UTF-8 decoding bodyBytes.

   5. Let script be the result of creating a classic script using sourceText, settingsObject, response's URL, and the default script fetch options.

   6. Run onComplete given script.

To fetch a classic worker-imported script given a URL url, an environment settings object settingsObject, and an optional perform the fetch hook performFetch, run these steps. The algorithm will return a classic script on success, or throw an exception on failure.

1. Let response be null.

2. Let bodyBytes be null.

3. Let request be a new request whose URL is url, client is settingsObject, destination is "script", initiator type is "other", parser metadata is "not parser-inserted", and whose use-URL-credentials flag is set.

4. If performFetch was given, run performFetch with request, true, and with processResponseConsumeBody as defined below.

   Otherwise, fetch request with processResponseConsumeBody set to processResponseConsumeBody as defined below.

   In both cases, let processResponseConsumeBody given response res and null, failure, or a byte sequence bb be the following algorithm:

   1. Set bodyBytes to bb.

   2. Set response to res.

5. Pause until response is not null.

   Unlike other algorithms in this section, the fetching process is synchronous here.

6. Set response to response's unsafe response.

7. If any of the following are true:

   • bodyBytes is null or failure;

   • response's status is not an ok status; or

   • the result of extracting a MIME type from response's header list is not a JavaScript MIME type,

   then throw a "NetworkError" DOMException.

8. Let sourceText be the result of UTF-8 decoding bodyBytes.

9. Let mutedErrors be true if response was CORS-cross-origin, and false otherwise.

10. Let script be the result of creating a classic script given sourceText, settingsObject, response's URL, the default script fetch options, and mutedErrors.

11. Return script.

To fetch an external module script graph given a URL url, an environment settings object settingsObject, a script fetch options options, and an algorithm onComplete, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Fetch a single module script given url, settingsObject, "script", options, settingsObject, "client", true, and with the following steps given result:

   1. If result is null, run onComplete given null, and abort these steps.

   2. Fetch the descendants of and link result given settingsObject, "script", and onComplete.

To fetch a modulepreload module script graph given a URL url, a destination destination, an environment settings object settingsObject, a script fetch options options, and an algorithm onComplete, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Fetch a single module script given url, settingsObject, destination, options, settingsObject, "client", true, and with the following steps given result:

   1. Run onComplete given result.

   2. Assert: settingsObject's global object implements Window.

   3. If result is not null, optionally fetch the descendants of and link result given settingsObject, destination, and an empty algorithm.

      Generally, performing this step will be beneficial for performance, as it allows pre-loading the modules that will invariably be requested later, via algorithms such as fetch an external module script graph that fetch the entire graph. However, user agents might wish to skip them in bandwidth-constrained situations, or situations where the relevant fetches are already in flight.

To fetch an inline module script graph given a string sourceText, a URL baseURL, an environment settings object settingsObject, a script fetch options options, and an algorithm onComplete, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Let script be the result of creating a JavaScript module script using sourceText, settingsObject, baseURL, and options.

2. Fetch the descendants of and link script, given settingsObject, "script", and onComplete.

To fetch a module worker script graph given a URL url, an environment settings object fetchClient, a destination destination, a credentials mode credentialsMode, an environment settings object settingsObject, and an algorithm onComplete, fetch a worklet/module worker script graph given url, fetchClient, destination, credentialsMode, settingsObject, and onComplete.

To fetch a worklet script graph given a URL url, an environment settings object fetchClient, a destination destination, a credentials mode credentialsMode, an environment settings object settingsObject, a module responses map moduleResponsesMap, and an algorithm onComplete, fetch a worklet/module worker script graph given url, fetchClient, destination, credentialsMode, settingsObject, onComplete, and the following perform the fetch hook given request and processCustomFetchResponse:

1. Let requestURL be request's URL.

2. If moduleResponsesMap[requestURL] is "fetching", wait in parallel until that entry's value changes, then queue a task on the networking task source to proceed with running the following steps.

3. If moduleResponsesMap[requestURL] exists:

   1. Let cached be moduleResponsesMap[requestURL].

   2. Run processCustomFetchResponse with cached[0] and cached[1].

   3. Return.

4. Set moduleResponsesMap[requestURL] to "fetching".

5. Fetch request, with processResponseConsumeBody set to the following steps given response response and null, failure, or a byte sequence bodyBytes:

   1. Set moduleResponsesMap[requestURL] to (response, bodyBytes).

   2. Run processCustomFetchResponse with response and bodyBytes.

To fetch a worklet/module worker script graph given a URL url, an environment settings object fetchClient, a destination destination, a credentials mode credentialsMode, an environment settings object settingsObject, an algorithm onComplete, and an optional perform the fetch hook performFetch, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Let options be a script fetch options whose cryptographic nonce is the empty string, integrity metadata is the empty string, parser metadata is "not-parser-inserted", credentials mode is credentialsMode, referrer policy is the empty string, and fetch priority is "auto".

2. Fetch a single module script given url, fetchClient, destination, options, settingsObject, "client", true, and onSingleFetchComplete as defined below. If performFetch was given, pass it along as well.

   onSingleFetchComplete given result is the following algorithm:

   1. If result is null, run onComplete given null, and abort these steps.

   2. Fetch the descendants of and link result given fetchClient, destination, and onComplete. If performFetch was given, pass it along as well.

To fetch the descendants of and link a module script moduleScript, given an environment settings object fetchClient, a destination destination, an algorithm onComplete, and an optional perform the fetch hook performFetch, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Let record be moduleScript's record.

2. If record is null:

   1. Set moduleScript's error to rethrow to moduleScript's parse error.

   2. Run onComplete given moduleScript.

   3. Return.

3. Let state be Record { [[ErrorToRethrow]]: null, [[Destination]]: destination, [[PerformFetch]]: null, [[FetchClient]]: fetchClient }.

4. If performFetch was given, set state.[[PerformFetch]] to performFetch.

5. Let loadingPromise be record.LoadRequestedModules(state).

   This step will recursively load all the module transitive dependencies.

6. Upon fulfillment of loadingPromise, run the following steps:

   1. Perform record.Link().

      This step will recursively call Link on all of the module's unlinked dependencies.

      If this throws an exception, catch it, and set moduleScript's error to rethrow to that exception.

   2. Run onComplete given moduleScript.

7. Upon rejection of loadingPromise, run the following steps:

   1. If state.[[ErrorToRethrow]] is not null, set moduleScript's error to rethrow to state.[[ErrorToRethrow]] and run onComplete given moduleScript.

   2. Otherwise, run onComplete given null.

      state.[[ErrorToRethrow]] is null when loadingPromise is rejected due to a loading error.

To fetch a single module script, given a URL url, an environment settings object fetchClient, a destination destination, a script fetch options options, an environment settings object settingsObject, a referrer referrer, an optional ModuleRequest Record moduleRequest, a boolean isTopLevel, an algorithm onComplete, and an optional perform the fetch hook performFetch, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Let moduleType be "javascript-or-wasm".

2. If moduleRequest was given, then set moduleType to the result of running the module type from module request steps given moduleRequest.

3. Assert: the result of running the module type allowed steps given moduleType and settingsObject is true. Otherwise, we would not have reached this point because a failure would have been raised when inspecting moduleRequest.[[Attributes]] in HostLoadImportedModule or fetch a single imported module script.

4. Let moduleMap be settingsObject's module map.

5. If moduleMap[(url, moduleType)] is a module script, run onComplete given moduleMap[(url, moduleType)], and return.

6. If moduleMap[(url, moduleType)] is a list, append onComplete to moduleMap[(url, moduleType)], and return.

7. Set moduleMap[(url, moduleType)] to « onComplete ».

8. Let request be a new request whose URL is url, mode is "cors", referrer is referrer, and client is fetchClient.

9. Set request's destination to the result of running the fetch destination from module type steps given destination and moduleType.

10. If destination is "worker", "sharedworker", or "serviceworker", and isTopLevel is true, then set request's mode to "same-origin".

11. Set request's initiator type to "script".

12. Set up the module script request given request and options.

13. If performFetch was given, run performFetch with request, isTopLevel, and with processResponseConsumeBody as defined below.

    Otherwise, fetch request with processResponseConsumeBody set to processResponseConsumeBody as defined below.

    In both cases, let processResponseConsumeBody given response response and null, failure, or a byte sequence bodyBytes be the following algorithm:

    response is always CORS-same-origin.

    1. If any of the following are true:

       • bodyBytes is null or failure; or

       • response's status is not an ok status,

       then:

       1. Let callbacks be moduleMap[(url, moduleType)].

       2. Remove moduleMap[(url, moduleType)].

       3. For each callback of callbacks: run callback given null.

       4. Return.

    2. Let mimeType be the result of extracting a MIME type from response's header list.

    3. Let moduleScript be null.

    4. Let referrerPolicy be the result of parsing the `Referrer-Policy` header given response. [REFERRERPOLICY]

    5. If referrerPolicy is not the empty string, set options's referrer policy to referrerPolicy.

    6. If mimeType's essence is "application/wasm" and moduleType is "javascript-or-wasm", then set moduleScript to the result of creating a WebAssembly module script given bodyBytes, settingsObject, response's URL, and options.

    7. Otherwise:

       1. Let sourceText be the result of UTF-8 decoding bodyBytes.

       2. If moduleType is "text", then set moduleScript to the result of creating a text module script given sourceText and settingsObject.

       3. If mimeType is a JavaScript MIME type and moduleType is "javascript-or-wasm", then set moduleScript to the result of creating a JavaScript module script given sourceText, settingsObject, response's URL, and options.

       4. If the MIME type essence of mimeType is "text/css" and moduleType is "css", then set moduleScript to the result of creating a CSS module script given sourceText and settingsObject.

       5. If mimeType is a JSON MIME type and moduleType is "json", then set moduleScript to the result of creating a JSON module script given sourceText and settingsObject.

    8. Let callbacks be moduleMap[(url, moduleType)].

    9. If moduleScript is null, then remove moduleMap[(url, moduleType)]; otherwise set moduleMap[(url, moduleType)] to moduleScript.

       It is intentional that the module map is keyed by the request URL, whereas the base URL for the module script is set to the response URL. The former is used to deduplicate fetches, while the latter is used for URL resolution.

    10. For each callback of callbacks: run callback given moduleScript.

To fetch a single imported module script, given a URL url, an environment settings object fetchClient, a destination destination, a script fetch options options, environment settings object settingsObject, a referrer referrer, a ModuleRequest Record moduleRequest, an algorithm onComplete, and an optional perform the fetch hook performFetch, run these steps. onComplete must be an algorithm accepting null (on failure) or a module script (on success).

1. Assert: moduleRequest.[[Attributes]] does not contain any Record entry such that entry.[[Key]] is not "type", because we only asked for "type" attributes in HostGetSupportedImportAttributes.

2. Let moduleType be the result of running the module type from module request steps given moduleRequest.

3. If the result of running the module type allowed steps given moduleType and settingsObject is false, then run onComplete given null, and return.

4. Fetch a single module script given url, fetchClient, destination, options, settingsObject, referrer, moduleRequest, false, and onComplete. If performFetch was given, pass it along as well.

To create a classic script, given a string source, an environment settings object settings, a URL baseURL, a script fetch options options, an optional boolean mutedErrors (default false), an optional URL-or-null sourceURLForWindowScripts (default null), and an optional boolean bypassDisabledScripting (default false):

The bypassDisabledScripting parameter is intended to be used for running scripts even if scripting is disabled. This is required for some automation scenarios, e.g. for WebDriver BiDi command "script.evaluate".

The bypassDisabledScripting parameter is intended to be used for running scripts even if scripting is disabled. This is required for some automation scenarios, e.g. for WebDriver BiDi command "script.evaluate". When the scripting process (e.g., executing a script via a WebDriver BiDi command) is invoked with bypassDisabledScripting set to true, the event loop is allowed to run to resolve thenables (from promises) and weakmap finalizations created by that script, even if scripting is disabled. This is necessary to ensure the proper functioning of testing scripts, which often rely on asynchronous operations.

1. If mutedErrors is true, then set baseURL to about:blank.

   When mutedErrors is true, baseURL is the script's CORS-cross-origin response's URL, which shouldn't be exposed to JavaScript. Therefore, baseURL is sanitized here.

2. If scripting is disabled for settings and bypassDisabledScripting is false, then set source to the empty string.

3. Let script be a new classic script that this algorithm will subsequently initialize.

4. Set script's settings object to settings.

5. Set script's base URL to baseURL.

6. Set script's fetch options to options.

7. Set script's muted errors to mutedErrors.

8. Set script's parse error and error to rethrow to null.

9. Record classic script creation time given script and sourceURLForWindowScripts.

10. Let result be ParseScript(source, settings's realm, script).

    Passing script as the last parameter here ensures result.[[HostDefined]] will be script.

11. If result is a list of errors:

    1. Set script's parse error and its error to rethrow to result[0].

    2. Return script.

12. Set script's record to result.

13. Return script.

To create a JavaScript module script, given a string source, an environment settings object settings, a URL baseURL, and a script fetch options options:

1. If scripting is disabled for settings, then set source to the empty string.

2. Let script be a new module script that this algorithm will subsequently initialize.

3. Set script's settings object to settings.

4. Set script's base URL to baseURL.

5. Set script's fetch options to options.

6. Set script's parse error and error to rethrow to null.

7. Let result be ParseModule(source, settings's realm, script).

   Passing script as the last parameter here ensures result.[[HostDefined]] will be script.

8. If result is a list of errors:

   1. Set script's parse error to result[0].

   2. Return script.

9. Set script's record to result.

10. Return script.

To create a WebAssembly module script, given a byte sequence bodyBytes, an environment settings object settings, a URL baseURL, and a script fetch options options:

1. If scripting is disabled for settings, then set bodyBytes to the byte sequence 0x00 0x61 0x73 0x6D 0x01 0x00 0x00 0x00.

   This byte sequence corresponds to an empty WebAssembly module with only the magic bytes and version number provided.

2. Let script be a new module script that this algorithm will subsequently initialize.

3. Set script's settings object to settings.

4. Set script's base URL to baseURL.

5. Set script's fetch options to options.

6. Set script's parse error and error to rethrow to null.

7. Let result be the result of parsing a WebAssembly module given bodyBytes, settings's realm, and script.

   Passing script as the last parameter here ensures result.[[HostDefined]] will be script.

8. If the previous step threw an error error:

   1. Set script's parse error to error.

   2. Return script.

9. Set script's record to result.

10. Return script.

To create a CSS module script, given a string source and an environment settings object settings:

1. Let script be a new module script that this algorithm will subsequently initialize.

2. Set script's settings object to settings.

3. Set script's base URL and fetch options to null.

4. Set script's parse error and error to rethrow to null.

5. Let sheet be the result of running the steps to create a constructed CSSStyleSheet with an empty dictionary as the argument.

6. Run the steps to synchronously replace the rules of a CSSStyleSheet on sheet given source.

   If this throws an exception, catch it, and set script's parse error to that exception, and return script.

   The steps to synchronously replace the rules of a CSSStyleSheet will throw if source contains any @import rules. This is by-design for now because there is not yet an agreement on how to handle these for CSS module scripts; therefore they are blocked altogether until a consensus is reached.

7. Set script's record to the result of CreateDefaultExportSyntheticModule(sheet).

8. Return script.

To create a JSON module script, given a string source and an environment settings object settings:

1. Let script be a new module script that this algorithm will subsequently initialize.

2. Set script's settings object to settings.

3. Set script's base URL and fetch options to null.

4. Set script's parse error and error to rethrow to null.

5. Let result be ParseJSONModule(source).

   If this throws an exception, catch it, and set script's parse error to that exception, and return script.

6. Set script's record to result.

7. Return script.

To create a text module script, given a string text and an environment settings object settings:

1. Let script be a new module script that this algorithm will subsequently initialize.

2. Set script's settings object to settings.

3. Set script's base URL and fetch options to null.

4. Set script's parse error and error to rethrow to null.

5. Let result be CreateTextModule(text).

6. Set script's record to result.

7. Return script.

The module type from module request steps, given a ModuleRequest Record moduleRequest, are as follows:

1. Let moduleType be "javascript-or-wasm".

2. If moduleRequest.[[Attributes]] has a Record entry such that entry.[[Key]] is "type":

   1. If entry.[[Value]] is "javascript-or-wasm", then set moduleType to null.

      This specification uses the "javascript-or-wasm" module type internally for JavaScript module scripts or WebAssembly module scripts, so this step is needed to prevent modules from being imported using a "javascript-or-wasm" type attribute (a null moduleType will cause the module type allowed check to fail).

   2. Otherwise, set moduleType to entry.[[Value]].

3. Return moduleType.

The module type allowed steps, given a string moduleType and an environment settings object settings, are as follows:

1. If moduleType is not "javascript-or-wasm", "css", "json", or "text", then return false.

2. If moduleType is "css" and the CSSStyleSheet interface is not exposed in settings's realm, then return false.

3. Return true.

The fetch destination from module type steps, given a destination defaultDestination and a string moduleType, are as follows:

1. If moduleType is "json", then return "json".
2. If moduleType is "css", then return "style".
3. If moduleType is "text", then return "text".
4. Return defaultDestination.

To run a classic script given a classic script script and an optional boolean rethrow errors (default false):

1. Let settings be the settings object of script.

2. Check if we can run script with settings. If this returns "do not run", then return NormalCompletion(empty).

3. Record classic script execution start time given script.

4. Prepare to run script given settings.

5. Let evaluationStatus be null.

6. If script's error to rethrow is not null, then set evaluationStatus to ThrowCompletion(script's error to rethrow).

7. Otherwise, set evaluationStatus to ScriptEvaluation(script's record).

   If ScriptEvaluation does not complete because the user agent has aborted the running script, leave evaluationStatus as null.

8. If evaluationStatus is an abrupt completion:

   1. If rethrow errors is true and script's muted errors is false:

      1. Clean up after running script with settings.

      2. Rethrow evaluationStatus.[[Value]].

   2. If rethrow errors is true and script's muted errors is true:

      1. Clean up after running script with settings.

      2. Throw a "NetworkError" DOMException.

   3. Otherwise, rethrow errors is false. Perform the following steps:

      1. Report an exception given by evaluationStatus.[[Value]] for script's settings object's global object.

      2. Clean up after running script with settings.

      3. Return evaluationStatus.

9. Clean up after running script with settings.

10. If evaluationStatus is a normal completion, then return evaluationStatus.

11. If we've reached this point, evaluationStatus was left as null because the script was aborted prematurely during evaluation. Return ThrowCompletion(a new QuotaExceededError).

To run a module script given a module script script and an optional boolean preventErrorReporting (default false):

1. Let settings be the settings object of script.

2. Check if we can run script with settings. If this returns "do not run", then return a promise resolved with undefined.

3. Record module script execution start time given script.

4. Prepare to run script given settings.

5. Let evaluationPromise be null.

6. If script's error to rethrow is not null, then set evaluationPromise to a promise rejected with script's error to rethrow.

7. Otherwise:

   1. Let record be script's record.

   2. Set evaluationPromise to record.Evaluate().

      This step will recursively evaluate all of the module's dependencies.

      If Evaluate fails to complete as a result of the user agent aborting the running script, then set evaluationPromise to a promise rejected with a new QuotaExceededError.

8. If preventErrorReporting is false, then upon rejection of evaluationPromise with reason, report an exception given by reason for script's settings object's global object.

9. Clean up after running script with settings.

10. Return evaluationPromise.

The steps to check if we can run script with an environment settings object settings are as follows. They return either "run" or "do not run".

1. If the global object specified by settings is a Window object whose Document object is not fully active, then return "do not run".

2. If scripting is disabled for settings, then return "do not run".

3. Return "run".

The steps to prepare to run script with an environment settings object settings are as follows:

1. Push settings's realm execution context onto the JavaScript execution context stack; it is now the running JavaScript execution context.

2. Add settings to the surrounding agent's event loop's currently running task's script evaluation environment settings object set.

The steps to clean up after running script with an environment settings object settings are as follows:

1. Assert: settings's realm execution context is the running JavaScript execution context.

2. Remove settings's realm execution context from the JavaScript execution context stack.

3. If the JavaScript execution context stack is now empty, perform a microtask checkpoint. (If this runs scripts, these algorithms will be invoked reentrantly.)

The running script is the script in the [[HostDefined]] field in the ScriptOrModule component of the running JavaScript execution context.

For example, the following script never terminates. A user agent could, after waiting for a few seconds, prompt the user to either terminate the script or let it continue.

<script>
 while (true) { /* loop */ }
</script>

To extract error information from a JavaScript value exception:

1. Let attributes be an empty map keyed by IDL attributes.

2. Set attributes[error] to exception.

3. Set attributes[message], attributes[filename], attributes[lineno], and attributes[colno] to implementation-defined values derived from exception.

   Browsers implement behavior not specified here or in the JavaScript specification to gather values which are helpful, including in unusual cases (e.g., eval). In the future, this might be specified in greater detail.

4. Return attributes.

To report an exception exception which is a JavaScript value, for a particular global object global and optional boolean omitError (default false):

1. Let notHandled be true.

2. Let errorInfo be the result of extracting error information from exception.

3. Let script be a script found in an implementation-defined way, or null. This should usually be the running script (most notably during run a classic script).

   Implementations have not yet settled on interoperable behavior for which script is used to determine whether errors are muted in less common cases.

4. If script is a classic script and script's muted errors is true, then set errorInfo[error] to null, errorInfo[message] to "Script error.", errorInfo[filename] to the empty string, errorInfo[lineno] to 0, and errorInfo[colno] to 0.

5. If omitError is true, then set errorInfo[error] to null.

6. If global is not in error reporting mode:

   1. Set global's in error reporting mode to true.

   2. If global implements EventTarget, then set notHandled to the result of firing an event named error at global, using ErrorEvent, with the cancelable attribute initialized to true, and additional attributes initialized according to errorInfo.

      Returning true in an event handler cancels the event per the event handler processing algorithm.

   3. Set global's in error reporting mode to false.

7. If notHandled is true:

   1. Set errorInfo[error] to null.

   2. If global implements DedicatedWorkerGlobalScope, queue a global task on the DOM manipulation task source with the global's associated Worker's relevant global object to run these steps:

      1. Let workerObject be the Worker object associated with global.

      2. Set notHandled to the result of firing an event named error at workerObject, using ErrorEvent, with the cancelable attribute initialized to true, and additional attributes initialized according to errorInfo.

      3. If notHandled is true, then report exception for workerObject's relevant global object with omitError set to true.

         The actual exception value will not be available in the owner realm, but the user agent still carries through enough information to set the message, filename, and other attributes, as well as potentially report to a developer console.

   3. Otherwise, the user agent may report exception to a developer console.

The reportError(e) method steps are to report an exception e for this.

The message attribute must return the value it was initialized to. It represents the error message.

The filename attribute must return the value it was initialized to. It represents the URL of the script in which the error originally occurred.

The lineno attribute must return the value it was initialized to. It represents the line number where the error occurred in the script.

The colno attribute must return the value it was initialized to. It represents the column number where the error occurred in the script.

The error attribute must return the value it was initialized to. It must initially be initialized to undefined. Where appropriate, it is set to the object representing the error (e.g., the exception object in the case of an uncaught exception).

To notify about rejected promises given a global object global:

1. Let list be a clone of global's about-to-be-notified rejected promises list.

2. If list is empty, then return.

3. Empty global's about-to-be-notified rejected promises list.

4. Queue a global task on the DOM manipulation task source given global to run the following step:

   1. For each promise p of list:

      1. If p.[[PromiseIsHandled]] is true, then continue.

      2. Let notCanceled be the result of firing an event named unhandledrejection at global, using PromiseRejectionEvent, with the cancelable attribute initialized to true, the promise attribute initialized to p, and the reason attribute initialized to p.[[PromiseResult]].

      3. If notCanceled is true, then the user agent may report p.[[PromiseResult]] to a developer console.

      4. If p.[[PromiseIsHandled]] is false, then append p to global's outstanding rejected promises weak set.

The promise attribute must return the value it was initialized to. It represents the promise which this notification is about.

The reason attribute must return the value it was initialized to. It represents the rejection reason for the promise.

To create an import map parse result given a string input and a URL baseURL:

1. Let result be an import map parse result whose import map is null and whose error to rethrow is null.

2. Parse an import map string given input and baseURL, catching any exceptions. If this threw an exception, then set result's error to rethrow to that exception. Otherwise, set result's import map to the return value.

3. Return result.

To register an import map given a Window global and an import map parse result result:

1. If result's error to rethrow is not null, then report an exception given by result's error to rethrow for global and return.

2. Merge existing and new import maps, given global and result's import map.

To create a speculation rules parse result given a string input and a Document document:

1. Let result be a speculation rules parse result whose speculation rule set is null and whose error to rethrow is null.

2. Parse a speculation rule set string given input, document, and document's document base URL, catching any exceptions. If this threw an exception, then set result's error to rethrow to that exception. Otherwise, set result's speculation rule set to the return value.

3. Return result.

To register speculation rules given a Window global, a speculation rules parse result result, and an optional boolean queueErrors (default false):

1. If result's error to rethrow is not null:

   1. If queueErrors is true, then queue a global task on the DOM manipulation task source given global to perform the following step:

      1. Report an exception given by result's error to rethrow for global.

   2. Otherwise, report an exception given by result's error to rethrow for global.

   3. Return.

2. Append result's speculation rule set to global's associated Document's speculation rule sets.

3. Consider speculative loads for global's associated Document.

To unregister speculation rules given a Window global and a speculation rules parse result result:

1. If result's error to rethrow is not null, then return.

2. Remove result's speculation rule set from global's associated Document's speculation rule sets.

3. Consider speculative loads for global's associated Document.

To update speculation rules given a Window global, a speculation rules parse result oldResult, and a speculation rules parse result newResult:

1. Remove oldResult's speculation rule set from global's associated Document's speculation rule sets.

2. Register speculation rules given global, newResult, and true.

   When updating speculation rules, as opposed to registering them for the first time, we ensure that any error events are queued as tasks, instead of synchronously fired. Although synchronously executing error event handlers is OK when inserting script elements, it's best if other modifications do not cause such synchronous script execution.

To resolve a module specifier given a script-or-null referringScript and a string specifier:

1. Let settingsObject and baseURL be null.

2. If referringScript is not null:

   1. Set settingsObject to referringScript's settings object.

   2. Set baseURL to referringScript's base URL.

3. Otherwise:

   1. Assert: there is a current settings object.

   2. Set settingsObject to the current settings object.

   3. Set baseURL to settingsObject's API base URL.

4. Let importMap be an empty import map.

5. If settingsObject's global object implements Window, then set importMap to settingsObject's global object's import map.

6. Let serializedBaseURL be baseURL, serialized.

7. Let asURL be the result of resolving a URL-like module specifier given specifier and baseURL.

8. Let normalizedSpecifier be the serialization of asURL, if asURL is non-null; otherwise, specifier.

9. Let result be a URL-or-null, initially null.

10. For each scopePrefix → scopeImports of importMap's scopes:

    1. If scopePrefix is serializedBaseURL, or if scopePrefix ends with U+002F (/) and scopePrefix is a code unit prefix of serializedBaseURL:

       1. Let scopeImportsMatch be the result of resolving an imports match given normalizedSpecifier, asURL, and scopeImports.

       2. If scopeImportsMatch is not null, then set result to scopeImportsMatch, and break.

11. If result is null, set result to the result of resolving an imports match given normalizedSpecifier, asURL, and importMap's imports.

12. If result is null, set it to asURL.

    By this point, if result was null, specifier wasn't remapped to anything by importMap, but it might have been able to be turned into a URL.

13. If result is not null:

    1. Add module to resolved module set given settingsObject, serializedBaseURL, normalizedSpecifier, and asURL.

    2. Return result.

14. Throw a TypeError indicating that specifier was a bare specifier, but was not remapped to anything by importMap.

To resolve an imports match, given a string normalizedSpecifier, a URL-or-null asURL, and a module specifier map specifierMap:

1. For each specifierKey → resolutionResult of specifierMap:

   1. If specifierKey is normalizedSpecifier:

      1. If resolutionResult is null, then throw a TypeError indicating that resolution of specifierKey was blocked by a null entry.

         This will terminate the entire resolve a module specifier algorithm, without any further fallbacks.

      2. Assert: resolutionResult is a URL.

      3. Return resolutionResult.

   2. If all of the following are true:

      • specifierKey ends with U+002F (/);

      • specifierKey is a code unit prefix of normalizedSpecifier; and

      • either asURL is null, or asURL is special,

      then:

      1. If resolutionResult is null, then throw a TypeError indicating that the resolution of specifierKey was blocked by a null entry.

         This will terminate the entire resolve a module specifier algorithm, without any further fallbacks.

      2. Assert: resolutionResult is a URL.

      3. Let afterPrefix be the portion of normalizedSpecifier after the initial specifierKey prefix.

      4. Assert: resolutionResult, serialized, ends with U+002F (/), as enforced during parsing.

      5. Let url be the result of URL parsing afterPrefix with resolutionResult.

      6. If url is failure, then throw a TypeError indicating that resolution of normalizedSpecifier was blocked since the afterPrefix portion could not be URL-parsed relative to the resolutionResult mapped to by the specifierKey prefix.

         This will terminate the entire resolve a module specifier algorithm, without any further fallbacks.

      7. Assert: url is a URL.

      8. If the serialization of resolutionResult is not a code unit prefix of the serialization of url, then throw a TypeError indicating that the resolution of normalizedSpecifier was blocked due to it backtracking above its prefix specifierKey.

         This will terminate the entire resolve a module specifier algorithm, without any further fallbacks.

      9. Return url.

2. Return null.

   The resolve a module specifier algorithm will fall back to a less-specific scope, or to "imports", if possible.

To resolve a URL-like module specifier, given a string specifier and a URL baseURL:

1. If specifier starts with "/", "./", or "../":

   1. Let url be the result of URL parsing specifier with baseURL.

   2. If url is failure, then return null.

      One way this could happen is if specifier is "../foo" and baseURL is a data: URL.

   3. Return url.

   This includes cases where specifier starts with "//", i.e., scheme-relative URLs. Thus, url might end up with a different host than baseURL.

2. Let url be the result of URL parsing specifier (with no base URL).

3. If url is failure, then return null.

4. Return url.

The simplest use of import maps is to globally remap a bare module specifier:

{
  "imports": {
    "moment": "/node_modules/moment/src/moment.js"
  }
}

This enables statements like import moment from "moment"; to work, fetching and evaluating the JavaScript module at the /node_modules/moment/src/moment.js URL.

An import map can remap a class of module specifiers into a class of URLs by using trailing slashes, like so:

{
  "imports": {
    "moment/": "/node_modules/moment/src/"
  }
}

This enables statements like import localeData from "moment/locale/zh-cn.js"; to work, fetching and evaluating the JavaScript module at the /node_modules/moment/src/locale/zh-cn.js URL. Such trailing-slash mappings are often combined with bare-specifier mappings, e.g.

{
  "imports": {
    "moment": "/node_modules/moment/src/moment.js",
    "moment/": "/node_modules/moment/src/"
  }
}

so that both the "main module" specified by "moment" and the "submodules" specified by paths such as "moment/locale/zh-cn.js" are available.

Bare specifiers are not the only type of module specifiers which import maps can remap. "URL-like" specifiers, i.e., those that are either parseable as absolute URLs or start with "/", "./", or "../", can be remapped as well:

{
  "imports": {
    "https://cdn.example.com/vue/dist/vue.runtime.esm.js": "/node_modules/vue/dist/vue.runtime.esm.js",
    "/js/app.mjs": "/js/app-8e0d62a03.mjs",
    "../helpers/": "https://cdn.example/helpers/"
  }
}

Note how the URL to be remapped, as well as the URL being mapped to, can be specified either as absolute URLs, or as relative URLs starting with "/", "./", or "../". (They cannot be specified as relative URLs without those starting sigils, as those help distinguish from bare module specifiers.) Also note how the trailing slash mapping works in this context as well.

Such remappings operate on the post-canonicalization URL, and do not require a match between the literal strings supplied in the import map key and the imported module specifier. So for example, if this import map was included on https://example.com/app.html, then not only would import "/js/app.mjs" be remapped, but so would import "./js/app.mjs" and import "./foo/../js/app.mjs".

All previous examples have globally remapped module specifiers, by using the top-level "imports" key in the import map. The top-level "scopes" key can be used to provide localized remappings, which only apply when the referring module matches a specific URL prefix. For example:

{
  "scopes": {
    "/a/" : {
      "moment": "/node_modules/moment/src/moment.js"
    },
    "/b/" : {
      "moment": "https://cdn.example.com/moment/src/moment.js"
    }
  }
}

With this import map, the statement import "moment" will have different meanings depending on which referrer script contains the statement:

• Inside scripts located under /a/, this will import /node_modules/moment/src/moment.js.

• Inside scripts located under /b/, this will import https://cdn.example.com/moment/src/moment.js.

• Inside scripts located under /c/, this will fail to resolve and thus throw an exception.

A typical usage of scopes is to allow multiple versions of the "same" module to exist in a web application, with some parts of the module graph importing one version, and other parts importing another version.

Scopes can overlap each other, and overlap the global "imports" specifier map. At resolution time, scopes are consulted in order of most- to least-specific, where specificity is measured by sorting the scopes using the code unit less than operation. So, for example, "/scope2/scope3/" is treated as more specific than "/scope2/", which is treated as more specific than the top-level (unscoped) mappings.

The following import map illustrates this:

{
  "imports": {
    "a": "/a-1.mjs",
    "b": "/b-1.mjs",
    "c": "/c-1.mjs"
  },
  "scopes": {
    "/scope2/": {
      "a": "/a-2.mjs"
    },
    "/scope2/scope3/": {
      "b": "/b-3.mjs"
    }
  }
}

This results in the following resolutions (using relative URLs for brevity):

Import maps can also be used to provide modules with integrity metadata to be used in Subresource Integrity checks. [SRI]

The following import map illustrates this:

{
  "imports": {
    "a": "/a-1.mjs",
    "b": "/b-1.mjs",
    "c": "/c-1.mjs"
  },
  "integrity": {
    "/a-1.mjs": "sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7",
    "/d-1.mjs": "sha384-MBO5IDfYaE6c6Aao94oZrIOiC6CGiSN2n4QUbHNPhzk5Xhm0djZLQqTpL0HzTUxk"
  }
}

The above example provides integrity metadata to be enforced on the modules /a-1.mjs and /d-1.mjs, even if the latter is not defined as an import in the map.

The child text content of a script element representing an import map must match the following import map authoring requirements:

• It must be valid JSON. [JSON]

• The JSON must represent a JSON object, with at most the three keys "imports", "scopes", and "integrity".

• The values corresponding to the "imports", "scopes", and "integrity" keys, if present, must themselves be JSON objects.

• The value corresponding to the "imports" key, if present, must be a valid module specifier map.

• The value corresponding to the "scopes" key, if present, must be a JSON object, whose keys are valid URL strings and whose values are valid module specifier maps.

• The value corresponding to the "integrity" key, if present, must be a JSON object, whose keys are valid URL strings and whose values fit the requirements of the integrity attribute.

A valid module specifier map is a JSON object that meets the following requirements:

• All of its keys must be nonempty.

• All of its values must be strings.

• Each value must be either a valid absolute URL or a valid URL string that starts with "/", "./", or "../".

• If a given key ends with "/", then the corresponding value must also.

To add module to resolved module set given an environment settings object settingsObject, a string serializedBaseURL, a string normalizedSpecifier, and a URL-or-null asURL:

1. Let global be settingsObject's global object.

2. If global does not implement Window, then return.

3. Let record be a new specifier resolution record, with serialized base URL set to serializedBaseURL, specifier set to normalizedSpecifier, and specifier as a URL set to asURL.

4. Append record to global's resolved module set.

To parse an import map string, given a string input and a URL baseURL:

1. Let parsed be the result of parsing a JSON string to an Infra value given input.

2. If parsed is not an ordered map, then throw a TypeError indicating that the top-level value needs to be a JSON object.

3. Let sortedAndNormalizedImports be an empty ordered map.

4. If parsed["imports"] exists:

   1. If parsed["imports"] is not an ordered map, then throw a TypeError indicating that the value for the "imports" top-level key needs to be a JSON object.

   2. Set sortedAndNormalizedImports to the result of sorting and normalizing a module specifier map given parsed["imports"] and baseURL.

5. Let sortedAndNormalizedScopes be an empty ordered map.

6. If parsed["scopes"] exists:

   1. If parsed["scopes"] is not an ordered map, then throw a TypeError indicating that the value for the "scopes" top-level key needs to be a JSON object.

   2. Set sortedAndNormalizedScopes to the result of sorting and normalizing scopes given parsed["scopes"] and baseURL.

7. Let normalizedIntegrity be an empty ordered map.

8. If parsed["integrity"] exists:

   1. If parsed["integrity"] is not an ordered map, then throw a TypeError indicating that the value for the "integrity" top-level key needs to be a JSON object.

   2. Set normalizedIntegrity to the result of normalizing a module integrity map given parsed["integrity"] and baseURL.

9. If parsed's keys contains any items besides "imports", "scopes", or "integrity", then the user agent should report a warning to the console indicating that an invalid top-level key was present in the import map.

   This can help detect typos. It is not an error, because that would prevent any future extensions from being added backward-compatibly.

10. Return an import map whose imports are sortedAndNormalizedImports, whose scopes are sortedAndNormalizedScopes, and whose integrity are normalizedIntegrity.

The import map that results from this parsing algorithm is highly normalized. For example, given a base URL of https://example.com/base/page.html, the input

{
  "imports": {
    "/app/helper": "node_modules/helper/index.mjs",
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

will generate an import map with imports of

«[
  "https://example.com/app/helper" → https://example.com/base/node_modules/helper/index.mjs
  "lodash" → https://example.com/node_modules/lodash-es/lodash.js
]»

and (despite nothing being present in the input string) an empty ordered map for its scopes.

To merge module specifier maps, given a module specifier map newMap and a module specifier map oldMap:

1. Let mergedMap be a deep copy of oldMap.

2. For each specifier → url of newMap:

   1. If specifier exists in oldMap:

      1. The user agent may report a warning to the console indicating the ignored rule. They may choose to avoid reporting if the rule is identical to an existing one.

      2. Continue.

   2. Set mergedMap[specifier] to url.

3. Return mergedMap.

To merge existing and new import maps, given a global object global and an import map newImportMap:

1. Let newImportMapScopes be a deep copy of newImportMap's scopes.

   We're mutating these copies and removing items from them when they are used to ignore scope-specific rules. This is true for newImportMapScopes, as well as to newImportMapImports below.

2. Let oldImportMap be global's import map.

3. Let newImportMapImports be a deep copy of newImportMap's imports.

4. For each scopePrefix → scopeImports of newImportMapScopes:

   1. For each record of global's resolved module set:

      1. If scopePrefix is record's serialized base URL, or if scopePrefix ends with U+002F (/) and scopePrefix is a code unit prefix of record's serialized base URL:

         1. For each specifierKey → resolutionResult of scopeImports:

            1. If specifierKey is record's specifier, or if all of the following conditions are true:

               • specifierKey ends with U+002F (/);

               • specifierKey is a code unit prefix of record's specifier;

               • either record's specifier as a URL is null or is special,

               then:

               1. The user agent may report a warning to the console indicating the ignored rule. They may choose to avoid reporting if the rule is identical to an existing one.

               2. Remove scopeImports[specifierKey].

      Implementers are encouraged to implement a more efficient matching algorithm when working with the resolved module set. As guidance, the number of resolved/mapped modules in a large application can be on the order of thousands.

   2. If scopePrefix exists in oldImportMap's scopes, then set oldImportMap's scopes[scopePrefix] to the result of merging module specifier maps, given scopeImports and oldImportMap's scopes[scopePrefix].

   3. Otherwise, set oldImportMap's scopes[scopePrefix] to scopeImports.

5. For each url → integrity of newImportMap's integrity:

   1. If url exists in oldImportMap's integrity:

      1. The user agent may report a warning to the console indicating the ignored rule. They may choose to avoid reporting if the rule is identical to an existing one.

      2. Continue.

   2. Set oldImportMap's integrity[url] to integrity.

6. For each record of global's resolved module set:

   1. For each specifier → url of newImportMapImports:

      1. If specifier starts with record's specifier:

         1. The user agent may report a warning to the console indicating the ignored rule. They may choose to avoid reporting if the rule is identical to an existing one.

         2. Remove newImportMapImports[specifier].

7. Set oldImportMap's imports to the result of merge module specifier maps, given newImportMapImports and oldImportMap's imports.

There are two cases when rules of the new import map don't get merged into the existing one.

1. The new import map rule has the exact same scope and specifier as a rule in the existing import map. We'll call that "conflicting rule".

2. The new import map rule may impact the resolution of an already resolved module. We'll call that "impacted already resolved module".

When the new import map has no conflicting rules, and there are no impacted resolved modules, the resulting map would be a combination of the new and existing maps. Rules that would have individually impacted similar modules (e.g. "/app/" and "/app/helper") but are not an exact match are not conflicting, and all make it to the merged map.

So, the following existing and new import maps:

{
   "imports": {
    "/app/": "./original-app/"
  }
}

{
  "imports": {
    "/app/helper": "./helper/index.mjs"
  },
  "scopes": {
    "/js": {
      "/app/": "./js-app/"
    }
  }
}

Would be equivalent to the following single import map:

{
  "imports": {
    "/app/": "./original-app/",
    "/app/helper": "./helper/index.mjs"
  },
  "scopes": {
    "/js": {
      "/app/": "./js-app/"
    }
  }
}

When the new import map impacts an already resolved module, that rule gets dropped from the import map.

So, if the resolved module set already contains the "/app/helper", the following new import map:

{
   "imports": {
    "/app/helper": "./helper/index.mjs",
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

Would be equivalent to the following one:

{
  "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

The same is true for rules that impact already resolved modules defined in specific scopes. If we already resolved "/app/helper" from "/app/main.mjs" the following new import map:

{
  "scopes": {
    "/app/": {
      "/app/helper": "./helper/index.mjs"
    }
  },
   "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

Would similarly be equivalent to:

{
  "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

We could also have cases where a single already-resolved module specifier has multiple rules for its resolution, depending on the referring script. In such cases, only the relevant rules would not be added to the map.

For example, if we already resolved "/app/helper" from "/app/vendor/main.mjs", the following new import map:

{
  "scopes": {
    "/app/": {
      "/app/helper": "./helper/index.mjs"
    },
    "/app/vendor/": {
      "/app/": "./vendor_helper/"
    },
    "/vendor/": {
      "/app/helper": "./helper/vendor_index.mjs"
    }
  },
   "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js",
    "/app/": "./general_app_path/",
    "/app/helper": "./other_path/helper/index.mjs"
  }
}

Would be equivalent to:

{
  "scopes": {
    "/vendor/": {
      "/app/helper": "./helper/vendor_index.mjs"
    }
  },
  "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

This is achieved by the fact that the merge algorithm tracks already resolved modules and removes rules affecting them from new import maps before they are merged into the existing one.

When the new import map has conflicting rules to the existing import map, with no impacted already resolved modules, the existing import map rules persist.

For example, the following existing and new import maps:

{
   "imports": {
    "/app/helper": "./helper/index.mjs",
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

{
  "imports": {
    "/app/helper": "./main/helper/index.mjs"
  }
}

Would be equivalent to the following single import map:

{
  "imports": {
    "/app/helper": "./helper/index.mjs",
    "lodash": "/node_modules/lodash-es/lodash.js"
  }
}

To sort and normalize a module specifier map, given an ordered map originalMap and a URL baseURL:

1. Let normalized be an empty ordered map.

2. For each specifierKey → value of originalMap:

   1. Let normalizedSpecifierKey be the result of normalizing a specifier key given specifierKey and baseURL.

   2. If normalizedSpecifierKey is null, then continue.

   3. If value is not a string:

      1. The user agent may report a warning to the console indicating that addresses need to be strings.

      2. Set normalized[normalizedSpecifierKey] to null.

      3. Continue.

   4. Let addressURL be the result of resolving a URL-like module specifier given value and baseURL.

   5. If addressURL is null:

      1. The user agent may report a warning to the console indicating that the address was invalid.

      2. Set normalized[normalizedSpecifierKey] to null.

      3. Continue.

   6. If specifierKey ends with U+002F (/), and the serialization of addressURL does not end with U+002F (/):

      1. The user agent may report a warning to the console indicating that an invalid address was given for the specifier key specifierKey; since specifierKey ends with a slash, the address needs to as well.

      2. Set normalized[normalizedSpecifierKey] to null.

      3. Continue.

   7. Set normalized[normalizedSpecifierKey] to addressURL.

3. Return the result of sorting in descending order normalized, with an entry a being less than an entry b if a's key is code unit less than b's key.

To sort and normalize scopes, given an ordered map originalMap and a URL baseURL:

1. Let normalized be an empty ordered map.

2. For each scopePrefix → potentialSpecifierMap of originalMap:

   1. If potentialSpecifierMap is not an ordered map, then throw a TypeError indicating that the value of the scope with prefix scopePrefix needs to be a JSON object.

   2. Let scopePrefixURL be the result of URL parsing scopePrefix with baseURL.

   3. If scopePrefixURL is failure:

      1. The user agent may report a warning to the console that the scope prefix URL was not parseable.

      2. Continue.

   4. Let normalizedScopePrefix be the serialization of scopePrefixURL.

   5. Set normalized[normalizedScopePrefix] to the result of sorting and normalizing a module specifier map given potentialSpecifierMap and baseURL.

3. Return the result of sorting in descending order normalized, with an entry a being less than an entry b if a's key is code unit less than b's key.

To normalize a module integrity map, given an ordered map originalMap:

1. Let normalized be an empty ordered map.

2. For each key → value of originalMap:

   1. Let resolvedURL be the result of resolving a URL-like module specifier given key and baseURL.

      Unlike "imports", keys of the integrity map are treated as URLs, not module specifiers. However, we use the resolve a URL-like module specifier algorithm to prohibit "bare" relative URLs like foo, which could be mistaken for module specifiers.

   2. If resolvedURL is null:

      1. The user agent may report a warning to the console indicating that the key failed to resolve.

      2. Continue.

   3. If value is not a string:

      1. The user agent may report a warning to the console indicating that integrity metadata values need to be strings.

      2. Continue.

   4. Set normalized[resolvedURL] to value.

3. Return normalized.

To normalize a specifier key, given a string specifierKey and a URL baseURL:

1. If specifierKey is the empty string:

   1. The user agent may report a warning to the console indicating that specifier keys may not be the empty string.

   2. Return null.

2. Let url be the result of resolving a URL-like module specifier, given specifierKey and baseURL.

3. If url is not null, then return the serialization of url.

4. Return specifierKey.

8.1.6.1 HostEnsureCanAddPrivateElement(O)

JavaScript contains an implementation-defined HostEnsureCanAddPrivateElement(O) abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. If O is a WindowProxy object, or implements Location, then return ThrowCompletion(a new TypeError).

2. Return NormalCompletion(unused).

8.1.6.2 HostEnsureCanCompileStrings(realm, parameterStrings, bodyString, codeString, compilationType, parameterArgs, bodyArg)

JavaScript contains an implementation-defined HostEnsureCanCompileStrings abstract operation, redefined by the Dynamic Code Brand Checks proposal. User agents must use the following implementation: [JAVASCRIPT] [JSDYNAMICCODEBRANDCHECKS]

1. Perform ? EnsureCSPDoesNotBlockStringCompilation(realm, parameterStrings, bodyString, codeString, compilationType, parameterArgs, bodyArg). [CSP]

8.1.6.3 HostGetCodeForEval(argument)

The Dynamic Code Brand Checks proposal contains an implementation-defined HostGetCodeForEval(argument) abstract operation. User agents must use the following implementation: [JSDYNAMICCODEBRANDCHECKS]

1. If argument is a TrustedScript object, then return argument's data.

2. Otherwise, return no-code.

8.1.6.4 HostPromiseRejectionTracker(promise, operation)

JavaScript contains an implementation-defined HostPromiseRejectionTracker(promise, operation) abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Let script be the running script.

2. If script is a classic script and script's muted errors is true, then return.

3. Let settingsObject be the current settings object.

4. If script is not null, then set settingsObject to script's settings object.

5. Let global be settingsObject's global object.

6. If operation is "reject":

   1. Append promise to global's about-to-be-notified rejected promises list.

7. If operation is "handle":

   1. If global's about-to-be-notified rejected promises list contains promise, then remove promise from that list and return.

   2. If global's outstanding rejected promises weak set does not contain promise, then return.

   3. Remove promise from global's outstanding rejected promises weak set.

   4. Queue a global task on the DOM manipulation task source given global to fire an event named rejectionhandled at global, using PromiseRejectionEvent, with the promise attribute initialized to promise, and the reason attribute initialized to promise.[[PromiseResult]].

8.1.6.5 HostSystemUTCEpochNanoseconds(global)

The Temporal proposal contains an implementation-defined HostSystemUTCEpochNanoseconds abstract operation. User agents must use the following implementation: [JSTEMPORAL]

1. Let settingsObject be global's relevant settings object.

2. Let time be settingsObject's current wall time.

3. Let ns be the number of nanoseconds from the Unix epoch to time, rounded to the nearest integer.

4. Return the result of clamping ns between nsMinInstant and nsMaxInstant.

8.1.6.6.1 HostCallJobCallback(callback, V, argumentsList)

JavaScript contains an implementation-defined HostCallJobCallback(callback, V, argumentsList) abstract operation to let hosts restore state when invoking JavaScript callbacks from inside tasks. User agents must use the following implementation: [JAVASCRIPT]

1. Let incumbent settings be callback.[[HostDefined]].[[IncumbentSettings]].

2. Let script execution context be callback.[[HostDefined]].[[ActiveScriptContext]].

3. Prepare to run a callback with incumbent settings.

   This affects the incumbent concept while the callback runs.

4. If script execution context is not null, then push script execution context onto the JavaScript execution context stack.

   This affects the active script while the callback runs.

5. Let result be Call(callback.[[Callback]], V, argumentsList).

6. If script execution context is not null, then pop script execution context from the JavaScript execution context stack.

7. Clean up after running a callback with incumbent settings.

8. Return result.

8.1.6.6.2 HostEnqueueFinalizationRegistryCleanupJob(finalizationRegistry)

JavaScript has the ability to register objects with FinalizationRegistry objects, in order to schedule a cleanup action if they are found to be garbage collected. The JavaScript specification contains an implementation-defined HostEnqueueFinalizationRegistryCleanupJob(finalizationRegistry) abstract operation to schedule the cleanup action.

The timing and occurrence of cleanup work is implementation-defined in the JavaScript specification. User agents might differ in when and whether an object is garbage collected, affecting both whether the return value of the WeakRef.prototype.deref() method is undefined, and whether FinalizationRegistry cleanup callbacks occur. There are well-known cases in popular web browsers where objects are not accessible to JavaScript, but they remain retained by the garbage collector indefinitely. HTML clears kept-alive WeakRef objects in the perform a microtask checkpoint algorithm. Authors would be best off not depending on the timing details of garbage collection implementations.

Cleanup actions do not take place interspersed with synchronous JavaScript execution, but rather happen in queued tasks. User agents must use the following implementation: [JAVASCRIPT]

1. Let global be finalizationRegistry.[[Realm]]'s global object.

2. Queue a global task on the JavaScript engine task source given global to perform the following steps:

   1. Let entry be finalizationRegistry.[[CleanupCallback]].[[Callback]].[[Realm]]'s environment settings object.

   2. Prepare to run script with entry.

      This affects the entry concept while the cleanup callback runs.

   3. Let result be the result of performing CleanupFinalizationRegistry(finalizationRegistry).

   4. Clean up after running script with entry.

   5. If result is an abrupt completion, then report an exception given by result.[[Value]] for global.

8.1.6.6.3 HostEnqueueGenericJob(job, realm)

JavaScript contains an implementation-defined HostEnqueueGenericJob(job, realm) abstract operation to perform generic jobs in a particular realm (e.g., resolve promises resulting from Atomics.waitAsync). User agents must use the following implementation: [JAVASCRIPT]

1. Let global be realm's global object.

2. Queue a global task on the JavaScript engine task source given global to perform job().

8.1.6.6.4 HostEnqueuePromiseJob(job, realm)

JavaScript contains an implementation-defined HostEnqueuePromiseJob(job, realm) abstract operation to schedule Promise-related operations. HTML schedules these operations in the microtask queue. User agents must use the following implementation: [JAVASCRIPT]

1. If realm is not null, then let job settings be the settings object for realm. Otherwise, let job settings be null.

   If realm is not null, it is the realm of the author code that will run. When job is returned by NewPromiseReactionJob, it is the realm of the promise's handler function. When job is returned by NewPromiseResolveThenableJob, it is the realm of the then function.

   If realm is null, either no author code will run or author code is guaranteed to throw. For the former, the author may not have passed in code to run, such as in promise.then(null, null). For the latter, it is because a revoked Proxy was passed. In both cases, all the steps below that would otherwise use job settings get skipped.

   NewPromiseResolveThenableJob and NewPromiseReactionJob both seem to provide non-null realms (the current Realm Record) in the case of a revoked proxy. The previous text could be updated to reflect that.

2. Queue a microtask to perform the following steps:

   1. If job settings is not null, then prepare to run script with job settings.

      This affects the entry concept while the job runs.

   2. Let result be job().

      job is an abstract closure returned by NewPromiseReactionJob or NewPromiseResolveThenableJob. The promise's handler function when job is returned by NewPromiseReactionJob, and the then function when job is returned by NewPromiseResolveThenableJob, are wrapped in JobCallback Records. HTML saves the incumbent settings object and a JavaScript execution context for to the active script in HostMakeJobCallback and restores them in HostCallJobCallback.

   3. If job settings is not null, then clean up after running script with job settings.

   4. If result is an abrupt completion, then report an exception given by result.[[Value]] for realm's global object.

      There is a very gnarly case where HostEnqueuePromiseJob is called with a null realm (e.g., because Promise.prototype.then was called with null handlers) but also the job returns abruptly (because the promise capability's resolve or reject handler threw, possibly because this is a subclass of Promise that takes the supplied functions and wraps them in throwing functions before passing them on to the function passed to the Promise superclass constructor). Which global is to be used then, considering that the current realm could be different at each of those steps, by using a Promise constructor or Promise.prototype.then from another realm? See issue #10526.

8.1.6.6.5 HostEnqueueTimeoutJob(job, realm, milliseconds)

JavaScript contains an implementation-defined HostEnqueueTimeoutJob(job, milliseconds) abstract operation to schedule an operation to be performed after a timeout. HTML schedules these operations using run steps after a timeout. User agents must use the following implementation: [JAVASCRIPT]

1. Let global be realm's global object.

2. Let timeoutStep be an algorithm step which queues a global task on the JavaScript engine task source given global to perform job().

3. Run steps after a timeout given global, "JavaScript", milliseconds, and timeoutStep.

8.1.6.6.6 HostMakeJobCallback(callable)

JavaScript contains an implementation-defined HostMakeJobCallback(callable) abstract operation to let hosts attach state to JavaScript callbacks that are called from inside tasks. User agents must use the following implementation: [JAVASCRIPT]

1. Let incumbent settings be the incumbent settings object.

2. Let active script be the active script.

3. Let script execution context be null.

4. If active script is not null, set script execution context to a new JavaScript execution context, with its Function field set to null, its Realm field set to active script's settings object's realm, and its ScriptOrModule set to active script's record.

   As seen below, this is used in order to propagate the current active script forward to the time when the job callback is invoked.

   A case where active script is non-null, and saving it in this way is useful, is the following:

   Promise.resolve('import(`./example.mjs`)').then(eval);

   Without this step (and the steps that use it in HostCallJobCallback), there would be no active script when the import() expression is evaluated, since eval() is a built-in function that does not originate from any particular script.

   With this step in place, the active script is propagated from the above code into the job, allowing import() to use the original script's base URL appropriately.

   active script can be null if the user clicks on the following button:

   <button onclick="Promise.resolve('import(`./example.mjs`)').then(eval)">Click me</button>

   In this case, the JavaScript function for the event handler will be created by the get the current value of the event handler algorithm, which creates a function with null [[ScriptOrModule]] value. Thus, when the promise machinery calls HostMakeJobCallback, there will be no active script to pass along.

   As a consequence, this means that when the import() expression is evaluated, there will still be no active script. Fortunately that is handled by our implementation of HostLoadImportedModule by falling back to using the current settings object's API base URL.

5. Return the JobCallback Record { [[Callback]]: callable, [[HostDefined]]: { [[IncumbentSettings]]: incumbent settings, [[ActiveScriptContext]]: script execution context } }.

Since module maps are keyed by (URL, module type), the following code will create three separate entries in the module map, since it results in three different (URL, module type) tuples (all with "javascript-or-wasm" type):

import "https://example.com/module.mjs";
import "https://example.com/module.mjs#map-buster";
import "https://example.com/module.mjs?debug=true";

That is, URL queries and fragments can be varied to create distinct entries in the module map; they are not ignored. Thus, three separate fetches and three separate module evaluations will be performed.

In contrast, the following code would only create a single entry in the module map, since after applying the URL parser to these inputs, the resulting URL records are equal:

import "https://example.com/module2.mjs";
import "https:example.com/module2.mjs";
import "https://///example.com\\module2.mjs";
import "https://example.com/foo/../module2.mjs";

So in this second example, only one fetch and one module evaluation will occur.

Note that this behavior is the same as how shared workers are keyed by their parsed constructor URL.

Since module type is also part of the module map key, the following code will create two separate entries in the module map (the type is "javascript-or-wasm" for the first, and "css" for the second):

<script type=module>
  import "https://example.com/module";
</script>
<script type=module>
  import "https://example.com/module" with { type: "css" };
</script>

This can result in two separate fetches and two separate module evaluations being performed.

In practice, due to the as-yet-unspecified memory cache (see issue #6110) the resource may only be fetched once in WebKit and Blink-based browsers. Additionally, as long as all module types are mutually exclusive, the module type check in fetch a single module script will fail for at least one of the imports, so at most one module evaluation will occur.

The purpose of including the type in the module map key is so that an import with the wrong type attribute does not prevent a different import of the same specifier but with the correct type from succeeding.

JavaScript module scripts are the default import type when importing from another JavaScript module; that is, when an import statement lacks a type import attribute the imported module script's type will be JavaScript. Attempting to import a JavaScript resource using an import statement with a type import attribute will fail:

<script type="module">
    // All of the following will fail, assuming that the imported .mjs files are served with a
    // JavaScript MIME type. JavaScript module scripts are the default and cannot be imported with
    // any import type attribute.
    import foo from "./foo.mjs" with { type: "javascript" };
    import foo2 from "./foo2.mjs" with { type: "js" };
    import foo3 from "./foo3.mjs" with { type: "" };
    await import("./foo4.mjs", { with: { type: null } });
    await import("./foo5.mjs", { with: { type: undefined } });
</script>

8.1.6.7.1 HostGetImportMetaProperties(moduleRecord)

JavaScript contains an implementation-defined HostGetImportMetaProperties abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Let moduleScript be moduleRecord.[[HostDefined]].

2. Assert: moduleScript's base URL is not null, as moduleScript is a JavaScript module script.

3. Let urlString be moduleScript's base URL, serialized.

4. Let steps be the following steps, given the argument specifier:

   1. Set specifier to ? ToString(specifier).

   2. Let url be the result of resolving a module specifier given moduleScript and specifier.

   3. Return the serialization of url.

5. Let resolveFunction be ! CreateBuiltinFunction(steps, 1, "resolve", « »).

6. Return « Record { [[Key]]: "url", [[Value]]: urlString }, Record { [[Key]]: "resolve", [[Value]]: resolveFunction } ».

8.1.6.7.2 HostGetSupportedImportAttributes()

JavaScript contains an implementation-defined HostGetSupportedImportAttributes abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Return « "type" ».

8.1.6.7.3 HostLoadImportedModule(referrer, moduleRequest, loadState, payload)

JavaScript contains an implementation-defined HostLoadImportedModule abstract operation. User agents must use the following implementation: [JAVASCRIPT]

1. Let settingsObject be the current settings object.

2. If settingsObject's global object implements WorkletGlobalScope or ServiceWorkerGlobalScope and loadState is undefined:

   loadState is undefined when the current fetching process has been initiated by a dynamic import() call, either directly or when loading the transitive dependencies of the dynamically imported module.

   1. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, ThrowCompletion(a new TypeError)).

   2. Return.

3. Let referencingScript be null.

4. Let originalFetchOptions be the default script fetch options.

5. Let fetchReferrer be "client".

6. If referrer is a Script Record or a Cyclic Module Record:

   1. Set referencingScript to referrer.[[HostDefined]].

   2. Set settingsObject to referencingScript's settings object.

   3. Set fetchReferrer to referencingScript's base URL.

   4. Set originalFetchOptions to referencingScript's fetch options.

   referrer is usually a Script Record or a Cyclic Module Record, but it will not be so for event handlers per the get the current value of the event handler algorithm. For example, given:

   <button onclick="import('./foo.mjs')">Click me</button>

   If a click event occurs, then at the time the import() expression runs, GetActiveScriptOrModule will return null, and this operation will receive the current realm as a fallback referrer.

7. If referrer is a Cyclic Module Record and moduleRequest is equal to the first element of referrer.[[RequestedModules]]:

   1. For each ModuleRequest record requested of referrer.[[RequestedModules]]:

      1. If requested.[[Attributes]] contains a Record entry such that entry.[[Key]] is not "type":

         1. Let error be a new SyntaxError exception.

         2. If loadState is not undefined and loadState.[[ErrorToRethrow]] is null, set loadState.[[ErrorToRethrow]] to error.

         3. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, ThrowCompletion(error)).

         4. Return.

         The JavaScript specification re-performs this validation but it is duplicated here to avoid unnecessarily loading any of the dependencies on validation failure.

      2. Resolve a module specifier given referencingScript and requested.[[Specifier]], catching any exceptions. If they throw an exception, let resolutionError be the thrown exception.

      3. If the previous step threw an exception:

         1. If loadState is not undefined and loadState.[[ErrorToRethrow]] is null, set loadState.[[ErrorToRethrow]] to resolutionError.

         2. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, ThrowCompletion(resolutionError)).

         3. Return.

      4. Let moduleType be the result of running the module type from module request steps given requested.

      5. If the result of running the module type allowed steps given moduleType and settingsObject is false:

         1. Let error be a new TypeError exception.

         2. If loadState is not undefined and loadState.[[ErrorToRethrow]] is null, set loadState.[[ErrorToRethrow]] to error.

         3. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, ThrowCompletion(error)).

         4. Return.

      This step is essentially validating all of the requested module specifiers and type attributes when the first call to HostLoadImportedModule for a static module dependency list is made, to avoid further loading operations in the case any one of the dependencies has a static error. We treat a module with unresolvable module specifiers or unsupported type attributes the same as one that cannot be parsed; in both cases, a syntactic issue makes it impossible to ever contemplate linking the module later.

8. Let url be the result of resolving a module specifier given referencingScript and moduleRequest.[[Specifier]], catching any exceptions. If they throw an exception, let resolutionError be the thrown exception.

9. If the previous step threw an exception:

   1. If loadState is not undefined and loadState.[[ErrorToRethrow]] is null, set loadState.[[ErrorToRethrow]] to resolutionError.

   2. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, ThrowCompletion(resolutionError)).

   3. Return.

10. Let fetchOptions be the result of getting the descendant script fetch options given originalFetchOptions, url, and settingsObject.

11. Let destination be "script".

12. Let fetchClient be settingsObject.

13. If loadState is not undefined:

    1. Set destination to loadState.[[Destination]].

    2. Set fetchClient to loadState.[[FetchClient]].

14. Fetch a single imported module script given url, fetchClient, destination, fetchOptions, settingsObject, fetchReferrer, moduleRequest, and onSingleFetchComplete as defined below. If loadState is not undefined and loadState.[[PerformFetch]] is not null, pass loadState.[[PerformFetch]] along as well.

    onSingleFetchComplete given moduleScript is the following algorithm:

    1. Let completion be null.

    2. If moduleScript is null, then set completion to ThrowCompletion(a new TypeError).

    3. Otherwise, if moduleScript's parse error is not null:

       1. Let parseError be moduleScript's parse error.

       2. Set completion to ThrowCompletion(parseError).

       3. If loadState is not undefined and loadState.[[ErrorToRethrow]] is null, set loadState.[[ErrorToRethrow]] to parseError.

    4. Otherwise, set completion to NormalCompletion(moduleScript's record).

    5. Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).