From a7006179eda66c83fcb8167d475a129967753652 Mon Sep 17 00:00:00 2001
From: Derek Schuff <dschuff@chromium.org>
Date: Mon, 30 Sep 2024 14:03:20 -0700
Subject: [PATCH] Add introduction sections to JS API and Web API documents
 (#1814)

These sections provide a bit more background about their relationship to the layer beneath them.
They also solve the problem that the existing minimal introductory text was hidden in the
bottom of the "status of this document" section.
---
 document/js-api/index.bs  | 17 ++++++++++++++++-
 document/web-api/index.bs | 14 ++++++--------
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/document/js-api/index.bs b/document/js-api/index.bs
index d6cabb20f3..d9c9c87229 100644
--- a/document/js-api/index.bs
+++ b/document/js-api/index.bs
@@ -23,6 +23,12 @@ Date: now
     "title": "WebAssembly Core Specification",
     "publisher": "W3C WebAssembly Community Group",
     "status": "Draft"
+  },
+  "WASMWEB": {
+    "href": "https://webassembly.github.io/spec/js-api/",
+    "title": "WebAssembly Web API Specification",
+    "publisher": "W3C WebAssembly Community Group",
+    "status": "Draft"
   }
 }
 </pre>
@@ -48,6 +54,8 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
         text: ℤ; url: #ℤ
         text: SameValue; url: sec-samevalue
 urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: dfn
+    text: embedding interface; url: appending/embedding.html
+    text: scope; url: intro/introduction.html#scope
     url: valid/modules.html#valid-module
         text: valid
         text: WebAssembly module validation
@@ -174,7 +182,14 @@ emu-const {
 }
 </style>
 
-This API provides a way to access WebAssembly [[WEBASSEMBLY]] through a bridge to explicitly construct modules from JavaScript [[ECMASCRIPT]].
+<h2 id="intro">Introduction</h2>
+
+By design, the [=scope=] of the WebAssembly core specification [[WEBASSEMBLY]] does not include a description of how WebAssembly programs interact with their surrounding execution environment.
+Instead it defines an abstract [=embedding interface=] between WebAssembly and its environment, (called the *embedder*).
+It is only through this interface that an embedder interacts with the semantics of WebAssembly, and the embedder implements the connection between its host environment and the embedding API.
+This document describes the embedding of WebAssembly into JavaScript [[ECMASCRIPT]] environments, including how WebAssembly modules can be constructed and instantiated, how imported and exported functions are called, how data is exchanged, and how errors are handled.
+When the JavaScript environment is itself embedded in a Web browser, the Web API spec [[WASMWEB]] describes additional behavior relevant to the Web environment.
+
 
 <h2 id="sample">Sample API Usage</h2>
 
diff --git a/document/web-api/index.bs b/document/web-api/index.bs
index c2aa74b2d1..e001b0430d 100644
--- a/document/web-api/index.bs
+++ b/document/web-api/index.bs
@@ -18,12 +18,6 @@ Date: now
 
 <pre class='biblio'>
 {
-  "ECMA-262": {
-    "href": "https://tc39.github.io/ecma262",
-    "title": "ECMAScript® Language Specification",
-    "publisher": "ECMA TC39",
-    "status": "Current Editor's Draft"
-  },
   "WEBASSEMBLY": {
     "href": "https://webassembly.github.io/spec/core/",
     "title": "WebAssembly Core Specification",
@@ -40,7 +34,7 @@ Date: now
 </pre>
 
 <pre class="anchors">
-urlPrefix: https://tc39.github.io/ecma262/; spec: ECMA-262
+urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
     type: exception; for: ECMAScript
         text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
     type: interface
@@ -71,12 +65,16 @@ url:https://fetch.spec.whatwg.org/#concept-body-consume-body;text:consume body;t
 </pre>
 
 <pre class='link-defaults'>
-spec:ecma-262; type:exception; for:ECMAScript; text:TypeError
+spec:ecmascript; type:exception; for:ECMAScript; text:TypeError
 spec:fetch; type:dfn; text:get
 spec:webidl; type:dfn; text:resolve
 </pre>
 
+
+<h2 id="intro">Introduction</h2>
 This document builds off of the WebAssembly specification [[WEBASSEMBLY]] and the WebAssembly JavaScript embedding [[WASMJS]].
+It describes the integration of WebAssembly into the broader Web platform, for example with
+additional APIs that are implemented by Web user agents but are outside the scope of JavaScript [[ECMASCRIPT]] itself.
 
 <h2 id="streaming-modules">Streaming Module Compilation and Instantiation</h2>