add more context about strict mode and enrich info about global variables

v3-docs/v3-migration-docs/.vitepress/config.mts

@@ -32,6 +32,7 @@ export default defineConfig({
       {
         text: "API Changes",
         items: [
+          {text: "Strict Mode", link: "/api/strict-mode"},
           {text: "Global Variables", link: "/api/global-variables"},
           {text: "Renamed Functions", link: "/api/renamed-functions"},
           {text: "Removed Functions", link: "/api/removed-functions"},

v3-docs/v3-migration-docs/api/global-variables.md

@@ -1,7 +1,45 @@
 # Global Variables
 
-On apps, instead of using `GlobalVar = { ... }` to define a global variable, you should use `global.GlobalVar = { ... }`.
+In Meteor 3, there are important changes regarding the definition of global variables in applications. This document provides guidelines on how to properly define globals in Meteor 3 and explains the implications of strict mode enforcement.
 
-Defining globals in **packages** should still work the same as in Meteor 2.
+## Defining Global Variables in Applications
 
-> For packages, Meteor adds a variable declaration in the package scope, which has the side effect of avoiding this mechanic altogether. In apps, there is no  "app scope" so these globals are true globals.
+### Previous Approach
+
+In previous versions of Meteor, you might have defined a global variable in your application using the following syntax:
+
+```javascript
+GlobalVar = { ... };
+```
+
+### New Approach in Meteor 3
+
+With the introduction of strict mode in Meteor 3, the recommended approach for defining global variables in your application has changed. You should now use the `global` object to define globals:
+
+```javascript
+global.GlobalVar = { ... };
+```
+
+This change is necessary because strict mode, which is automatically enforced in certain situations in Meteor 3, does not support defining globals in the traditional way.
+
+## Defining Global Variables in Packages
+
+For packages, the process of defining global variables remains unchanged from Meteor 2. You can continue to define globals as you have previously without any modifications.
+
+### Explanation
+
+In Meteor packages, Meteor automatically adds a variable declaration within the package scope. This behavior prevents the need for using the `global` object and avoids the strict mode restrictions.
+
+However, in applications, there is no equivalent "app scope," so globals defined in applications must be true globals, requiring the use of the `global` object.
+
+## Strict Mode and Its Implications
+
+Meteor 3 enforces strict mode for modules that use top-level await (TLA) or the `import` syntax. This enforcement aligns with JavaScript specifications and improves the overall consistency and compliance of your code.
+
+For more detailed information on strict mode and its implications, refer to the [Strict Mode](./strict-mode.md) document.
+
+## Conclusion
+
+By following these guidelines, you can ensure that your global variable definitions are compatible with Meteor 3 and its strict mode enforcement. This will help maintain the stability and compliance of your application as you transition to the latest version of Meteor.
+
+For further assistance, please refer to the official Meteor documentation or reach out to the Meteor community.

v3-docs/v3-migration-docs/api/strict-mode.md

@@ -0,0 +1,25 @@
+# Strict Mode
+
+Meteor 3 introduces enhanced support for strict mode, aligning with modern JavaScript standards. This document outlines the changes related to module execution in strict mode, focusing on the use of top-level await (TLA) and module syntax (`import` and `export`).
+
+Strict mode is a restricted variant of JavaScript that eliminates some of the language's silent errors and fixes mistakes that make it difficult for JavaScript engines to perform optimizations. Modules are designed to run in strict mode by default.
+
+### Changes in Meteor 3
+
+With the introduction of Meteor 3, modules will automatically run in strict mode under certain conditions:
+
+1. **Top-Level Await (TLA):** Modules using top-level await will be executed in strict mode.
+2. **Import Syntax:** Modules using the `import` statement will be executed in strict mode.
+3. **Export Syntax:** Modules using the `export` statement should also run in strict mode.
+
+### Background
+
+Initially, there was a bug in the TLA implementation of Reify, a module used by Meteor. By default, Reify does not enforce strict mode for modules. However, the TLA implementation in Meteor did not fully adhere to this behavior, leading to modules running in strict mode when using TLA.
+
+A decision was made to retain this behavior to ensure Meteor's compliance with the ECMAScript specification. Consequently, modules will continue to run in strict mode in specific situations, enhancing spec compliance and improving the overall consistency of the development experience.
+
+While this change aims to bring Meteor more in line with the JavaScript specification, developers might notice some inconsistencies or changes in the user experience. It is important to review your code to ensure compatibility with strict mode, especially if your modules rely on defining globals or other behaviors not permitted in strict mode.
+
+The enforcement of strict mode in certain scenarios in Meteor 3 represents a step towards greater specification compliance and modernization. Developers should adapt their code to accommodate these changes, ensuring a smooth transition to Meteor 3.
+
+For further details and support, please refer to the official Meteor documentation or reach out to the Meteor community.