Skip to content

Layering: Revamp InitializeHostDefinedRealm #3728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jmdyck wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Layering: Revamp InitializeHostDefinedRealm #3728

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
462fe67
Layering: Add _customizations_ param to InitializeHostDefinedRealm
jmdyck Nov 23, 2025
8c3ab5b
Layering: Make InitializeHostDefinedRealm non-throwing
jmdyck Nov 24, 2025
f68a726
Editorial: Create the realm execution context slightly later
jmdyck Nov 24, 2025
5af8789
Layering: Return the realm EC from InitializeHostDefinedRealm
jmdyck Nov 24, 2025
6156055
Layering: Rename InitializeHostDefinedRealm as MakeRealm
jmdyck Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 46 additions & 19 deletions spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11643,33 +11643,58 @@ <h1>Realms</h1>
</table>
</emu-table>

<emu-clause id="sec-initializehostdefinedrealm" type="abstract operation" oldids="sec-createrealm,sec-setrealmglobalobject">
<h1>InitializeHostDefinedRealm ( ): either a normal completion containing ~unused~ or a throw completion</h1>
<emu-clause id="sec-makerealm" type="abstract operation" oldids="sec-initializehostdefinedrealm,sec-createrealm,sec-setrealmglobalobject">
<h1>
MakeRealm (
_customizations_: an Abstract Closure that takes a Realm Record and returns a List of 2 elements, each of which is either an Object or *undefined*,

Check warning on line 11649 in spec.html

View workflow job for this annotation

GitHub Actions / check for newly-introduced spelling errors

Potential Typo 

"customizations" is not a previously used word or composed of previously used words. Perhaps it is a typo?
Copy link
Member

@annevk annevk Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be slightly nicer for callers if they can omit the second return value (or return a single value or a list). Only window agents need this complexity, everything else has them be the same.

(Also, thanks for working on this, love to see this made more formal!)

Copy link
Collaborator Author

@jmdyck jmdyck Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the HTML spec, I believe that would change 2 lines of the form

Return « <var>global</var>, undefined ».

to

Return « <var>global</var> ».

or

Return <var>global</var>.

I suppose it's slightly nicer, but I'm doubtful that it's worth the increased complexity for IHDR.

Copy link
Member

@annevk annevk Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also Service Workers and probably everything else that wants to build on the JS specification that isn't HTML, but fair enough to not optimize for that as it's largely theoretical.

): an execution context
</h1>
<dl class="header">
<dt>description</dt>
<dd>
<p>This operation invokes _customizations_, passing it the Realm Record that is being initialized. It must return a List of 2 elements:</p>

Check warning on line 11655 in spec.html

View workflow job for this annotation

GitHub Actions / check for newly-introduced spelling errors

Potential Typo 

"customizations" is not a previously used word or composed of previously used words. Perhaps it is a typo?
<ul>
<li>
<p>The first element is either:</p>
<ul>
<li>the object that is to serve as the Realm's global object, created in a host-defined manner, or</li>
<li>*undefined*, indicating that an ordinary object should be created as the global object.</li>
</ul>
<p>If the former, then the supplied object must satisfy SetDefaultGlobalBindings' constraint.</p>
</li>
<li>
<p>The second element is either:</p>
<ul>
<li>the object that is to serve as the `this` binding in the Realm's global scope, created in a host-defined manner, or</li>
<li>*undefined*, indicating that the global object should be used.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<emu-alg>
1. Let _realm_ be a new Realm Record.
1. Perform CreateIntrinsics(_realm_).
1. Set _realm_.[[AgentSignifier]] to AgentSignifier().
1. Set _realm_.[[TemplateMap]] to a new empty List.
1. Let _newContext_ be a new execution context.
1. Set the Function of _newContext_ to *null*.
1. Set the Realm of _newContext_ to _realm_.
1. Set the ScriptOrModule of _newContext_ to *null*.
1. Push _newContext_ onto the execution context stack; _newContext_ is now the running execution context.
1. If the host requires use of a specific object to serve as _realm_'s global object, then
1. Let _global_ be such an object created in a host-defined manner.
1. Let _global_ and _thisValue_ be the elements of _customizations_(_realm_).

Check warning on line 11680 in spec.html

View workflow job for this annotation

GitHub Actions / check for newly-introduced spelling errors

Potential Typo 

"customizations" is not a previously used word or composed of previously used words. Perhaps it is a typo?
1. If _global_ is *undefined*, then
1. Set _global_ to OrdinaryObjectCreate(_realm_.[[Intrinsics]].[[%Object.prototype%]]).
1. Else,
1. Let _global_ be OrdinaryObjectCreate(_realm_.[[Intrinsics]].[[%Object.prototype%]]).
1. If the host requires that the `this` binding in _realm_'s global scope return an object other than the global object, then
1. Let _thisValue_ be such an object created in a host-defined manner.
1. Assert: _global_ is an Object.
1. If _thisValue_ is *undefined*, then
1. Set _thisValue_ to _global_.
1. Else,
1. Let _thisValue_ be _global_.
1. Assert: _thisValue_ is an Object.
1. Set _realm_.[[GlobalObject]] to _global_.
1. Set _realm_.[[GlobalEnv]] to NewGlobalEnvironment(_global_, _thisValue_).
1. Perform ? SetDefaultGlobalBindings(_realm_).
1. Perform SetDefaultGlobalBindings(_realm_).
1. Create any host-defined global object properties on _global_.
1. Return ~unused~.
1. Let _newContext_ be a new execution context.
1. Set the Function of _newContext_ to *null*.
1. Set the Realm of _newContext_ to _realm_.
1. Set the ScriptOrModule of _newContext_ to *null*.
1. Return _newContext_.
</emu-alg>
</emu-clause>

Expand All @@ -11693,16 +11718,18 @@ <h1>
<h1>
SetDefaultGlobalBindings (
_realmRec_: a Realm Record,
): either a normal completion containing ~unused~ or a throw completion
): ~unused~
</h1>
<dl class="header">
<dt>description</dt>
<dd>_realmRec_.[[GlobalObject]] must be an object such that all of this operation's invocations of DefinePropertyOrThrow return a normal completion.</dd>
</dl>
<emu-alg>
1. Let _global_ be _realmRec_.[[GlobalObject]].
1. For each property of the Global Object specified in clause <emu-xref href="#sec-global-object"></emu-xref>, do
1. Let _name_ be the String value of the property name.
1. Let _desc_ be the fully populated data Property Descriptor for the property, containing the specified attributes for the property. For properties listed in <emu-xref href="#sec-function-properties-of-the-global-object"></emu-xref>, <emu-xref href="#sec-constructor-properties-of-the-global-object"></emu-xref>, or <emu-xref href="#sec-other-properties-of-the-global-object"></emu-xref> the value of the [[Value]] attribute is the corresponding intrinsic object from _realmRec_.
1. Perform ? DefinePropertyOrThrow(_global_, _name_, _desc_).
1. Perform ! DefinePropertyOrThrow(_global_, _name_, _desc_).
1. Return ~unused~.
</emu-alg>
</emu-clause>
Expand Down Expand Up @@ -11754,7 +11781,7 @@ <h1>Execution Contexts</h1>
ScriptOrModule
</td>
<td>
The Module Record or Script Record from which associated code originates. If there is no originating script or module, as is the case for the original execution context created in InitializeHostDefinedRealm, the value is *null*.
The Module Record or Script Record from which associated code originates. If there is no originating script or module, as is the case for the original execution context created in MakeRealm, the value is *null*.
</td>
</tr>
</table>
Expand Down Expand Up @@ -53280,7 +53307,7 @@ <h1>Host Hooks</h1>
<p><b>HostMakeJobCallback(...)</b></p>
<p><b>HostPromiseRejectionTracker(...)</b></p>
<p><b>HostResizeArrayBuffer(...)</b></p>
<p><b>InitializeHostDefinedRealm(...)</b></p>
<p><b>MakeRealm(...)</b></p>
</emu-annex>

<emu-annex id="sec-host-defined-fields-summary">
Expand Down
Loading