Reference for stage 3 source-phase-imports

files/en-us/web/javascript/reference/global_objects/abstractmodulesource/index.md

@@ -0,0 +1,55 @@
+---
+title: AbstractModuleSource
+slug: Web/JavaScript/Reference/Global_Objects/AbstractModuleSource
+page-type: javascript-class
+browser-compat: javascript.builtins.AbstractModuleSource
+sidebar: jsref
+---
+
+An **_AbstractModuleSource_** object represents the raw module source code accessible with [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source) or [`import.source()`](/en-US/docs/Web/JavaScript/Reference/Operators/import/source). There is no directly visible `AbstractModuleSource` constructor.
+
+## Description
+
+The `AbstractModuleSource` constructor (often referred to as `%AbstractModuleSource%` to indicate its "intrinsicness", since it does not correspond to any global exposed to a JavaScript program) serves as the common superclass of all module source subclasses, providing a common interface of utility methods for all module source subclasses. This constructor is not directly exposed: there is no global `AbstractModuleSource` property. It is only accessible through `Object.getPrototypeOf(moduleSourceObject.constructor)` and similar.
+
+### AbstractModuleSource objects
+
+- [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module)
+
+JavaScript module source objects will be added by the [ECMAScript Module Phase Imports](https://github.com/tc39/proposal-esm-phase-imports) proposal.
+
+## Constructor
+
+This object cannot be instantiated directly — attempting to construct it with `new` throws a {{jsxref("TypeError")}}.
+
+```js
+import source modSource from "./module.wasm";
+
+new (Object.getPrototypeOf(modSource.constructor))();
+// TypeError: Abstract class AbstractModuleSource not directly constructable
+```
+
+You rarely need to construct an `AbstractModuleSource` object directly, since the module source objects are created by the JavaScript engine when you use `import source` or `import.source()`.
+
+## Instance properties
+
+These properties are defined on `AbstractModuleSource.prototype` and shared by all `AbstractModuleSource` subclass instances.
+
+- {{jsxref("Object/constructor", "AbstractModuleSource.prototype.constructor")}}
+  - : The constructor function that created the instance object. `AbstractModuleSource.prototype.constructor` is the hidden `AbstractModuleSource` constructor function, but each module source subclass also defines its own `constructor` property.
+- `AbstractModuleSource.prototype[Symbol.toStringTag]`
+  - : The initial value of the [`AbstractModuleSource.prototype[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is a getter that returns the same string as the module source constructor's name. It returns `undefined` if the `this` value is not one of the module source subclasses. This property is used in {{jsxref("Object.prototype.toString()")}}.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module)
+- {{jsxref("Operators/import/source", "import.source()")}}
+- {{jsxref("Statements/import/source", "import source")}}

files/en-us/web/javascript/reference/global_objects/index.md

@@ -145,6 +145,7 @@ Control abstractions can help to structure code, especially async code (without
 
 ### Reflection
 
+- {{jsxref("AbstractModuleSource")}}
 - {{jsxref("Reflect")}}
 - {{jsxref("Proxy")}}
 

files/en-us/web/javascript/reference/index.md

@@ -120,6 +120,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/
 
 ### Reflection
 
+- {{jsxref("AbstractModuleSource")}}
 - {{jsxref("Reflect")}}
 - {{jsxref("Proxy")}}
 
@@ -184,6 +185,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/
 - {{jsxref("Statements/debugger", "debugger")}}
 - {{jsxref("Statements/export", "export")}}
 - {{jsxref("Statements/import", "import")}}
+- {{jsxref("Statements/import/source", "import source")}}
 - {{jsxref("Statements/label", "label", "", 1)}}
 - {{jsxref("Statements/with", "with")}} {{deprecated_inline}}
 
@@ -215,6 +217,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/
 - {{jsxref("Operators/import.meta", "import.meta")}}
 - {{jsxref("Operators/super", "super")}}
 - {{jsxref("Operators/import", "import()")}}
+- {{jsxref("Operators/import/source", "import.source()")}}
 
 ### Increment and decrement
 

files/en-us/web/javascript/reference/operators/import/index.md

@@ -30,6 +30,8 @@ The `import()` call is a syntax that closely resembles a function call, but `imp
     - `with`
       - : The [import attributes](/en-US/docs/Web/JavaScript/Reference/Statements/import/with).
 
+"Phase modifiers" for `import` statements, such as [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source), can also be used with dynamic imports, such as `import.source()`.
+
 ### Return value
 
 Returns a promise which:

files/en-us/web/javascript/reference/operators/import/source/index.md

@@ -0,0 +1,47 @@
+---
+title: import.source()
+slug: Web/JavaScript/Reference/Operators/import/source
+page-type: javascript-language-feature
+browser-compat: javascript.operators.import.source
+---
+
+{{jsSidebar("Statements")}}
+
+The **`import.source()`** syntax behaves like regular [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import) syntax, but only obtains an object representing the module's unevaluated source code. The module can be imperatively evaluated later using a method provided by the source code object.
+
+To use `import.source()`, the target module has to support source phase imports. Currently, only WebAssembly modules support source phase imports, which result in [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module) objects. JavaScript module source objects will be added by the [ECMAScript Module Phase Imports](https://github.com/tc39/proposal-esm-phase-imports) proposal.
+
+## Syntax
+
+```js-nolint
+import.source(moduleName)
+import.source(moduleName, options)
+```
+
+### Parameters
+
+See [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#parameters).
+
+### Return value
+
+Returns a promise. The rejection conditions are largely similar to [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#return_value), except that `import.source()` does not throw exceptions related to module evaluation, because it does not evaluate the module.
+
+If the referenced module is loaded successfully, fulfills with an {{jsxref("AbstractModuleSource")}} object representing the module's unevaluated source code.
+
+## Description
+
+## Examples
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("Operators/import", "import()")}}
+- {{jsxref("Statements/import/source", "import source")}}
+- {{jsxref("AbstractModuleSource")}}

files/en-us/web/javascript/reference/operators/index.md

@@ -59,6 +59,8 @@ Left values are the destination of an assignment.
   - : The `super` keyword calls the parent constructor or allows accessing properties of the parent object.
 - {{jsxref("Operators/import", "import()")}}
   - : The `import()` syntax allows loading a module asynchronously and dynamically into a potentially non-module environment.
+- {{jsxref("Operators/import/source", "import.source()")}}
+  - : The `import.source()` syntax only obtains an object representing the module's unevaluated source code.
 
 ### Increment and decrement
 

files/en-us/web/javascript/reference/statements/export/index.md

@@ -213,6 +213,9 @@ The following is syntactically invalid despite its import equivalent:
 export DefaultExport from "bar.js"; // Invalid
 ```
 
+> [!NOTE]
+> Due to the lack of this syntax, [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source) also has no re-exporting counterpart.
+
 The correct way of doing this is to rename the export:
 
 ```js

files/en-us/web/javascript/reference/statements/import/index.md

@@ -41,6 +41,8 @@ import "module-name";
 
 The `"module-name"` may be followed by a set of [import attributes](/en-US/docs/Web/JavaScript/Reference/Statements/import/with), starting with the `with` keyword.
 
+The `import` keyword may be followed by a "phase modifier" that pauses the evaluation of the module at one phase of the module loading process. Currently, the only phase modifier is [`source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source).
+
 ## Description
 
 `import` declarations can only be present in modules, and only at the top-level (i.e., not inside blocks, functions, etc.). If an `import` declaration is encountered in non-module contexts (for example, `<script>` tags without `type="module"`, `eval`, `new Function`, which all have "script" or "function body" as parsing goals), a `SyntaxError` is thrown. To load modules in non-module contexts, use the [dynamic import](/en-US/docs/Web/JavaScript/Reference/Operators/import) syntax instead.

files/en-us/web/javascript/reference/statements/import/source/index.md

@@ -0,0 +1,43 @@
+---
+title: import source
+slug: Web/JavaScript/Reference/Statements/import/source
+page-type: javascript-language-feature
+browser-compat: javascript.statements.import.source
+---
+
+{{jsSidebar("Statements")}}
+
+The **`import source`** statement behaves like regular [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) statements, but it can only import a module using the default import syntax, and results in an object representing the module's unevaluated source code. The module can be imperatively evaluated later using a method provided by the source code object.
+
+To use `import source`, the target module has to support source phase imports. Currently, only WebAssembly modules support source phase imports, which result in [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module) objects. JavaScript module source objects will be added by the [ECMAScript Module Phase Imports](https://github.com/tc39/proposal-esm-phase-imports) proposal.
+
+## Syntax
+
+```js-nolint
+import source x from "module-name";
+```
+
+- `x`
+  - : Name that will refer to the module source object. Must be a valid JavaScript identifier.
+- `module-name`
+  - : The module to import from. Handled the same way as the [`module-name`](/en-US/docs/Web/JavaScript/Reference/Statements/import#module-name) in regular `import` statements.
+
+[Import attributes](/en-US/docs/Web/JavaScript/Reference/Statements/import/with) are also supported in `import source` statements, and are handled the same way as in regular `import` statements.
+
+## Description
+
+## Examples
+
+### Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("Statements/import", "import")}}
+- {{jsxref("Operators/import/source", "import.source()")}}
+- {{jsxref("AbstractModuleSource")}}

files/en-us/webassembly/reference/javascript_interface/module/index.md

@@ -8,6 +8,8 @@ sidebar: webassemblysidebar
 
 A **`WebAssembly.Module`** object contains stateless WebAssembly code that has already been compiled by the browser — this can be efficiently [shared with Workers](/en-US/docs/Web/API/Worker/postMessage), and instantiated multiple times.
 
+`WebAssembly.Module` is a subclass of the hidden {{jsxref("AbstractModuleSource")}} class, in environments that support `AbstractModuleSource`.
+
 > [!NOTE]
 > The `WebAssembly.Module` object is unrelated to the [`Module`](https://emscripten.org/docs/api_reference/module.html) object used in Emscripten.
 
@@ -62,6 +64,16 @@ onmessage = (e) => {
 };
 ```
 
+### Obtaining the module using `import source`
+
+In environments that support source phase imports, you can obtain a `WebAssembly.Module` object using the [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source) statement or the [`import.source()`](/en-US/docs/Web/JavaScript/Reference/Operators/import/source) operator, which avoids the need to call `fetch()` or `WebAssembly.compileStreaming()`, instead relying on the default module loader machinery.
+
+```js
+import source modSource from "./simple.wasm";
+
+worker.postMessage(modSource);
+```
+
 ## Specifications
 
 {{Specifications}}