From d399b9e0711b408e15fdfbea1cafe956a6f3d481 Mon Sep 17 00:00:00 2001
From: Derek Schuff <dschuff@chromium.org>
Date: Fri, 26 Apr 2024 10:34:08 -0700
Subject: [PATCH] Expose the JavaScript Exception tag and allow importing it
 (#269)

As discussed in #202

The JS tag was added to the JS API spec in #301, but it is not observable. This change
exposes it on the WebAssembly namespace, allowing it to be imported into wasm modules.
This allows wasm modules to explicitly extract the thrown JS objects as externrefs from the
caught exrefs, and also to throw fresh exceptions with externref payloads that will propagate
into JS and can be caught as bare JS objects not wrapped in a WebAssembly.Exception.

It also places the restriction that WebAssembly.Exception objects cannot be created with
the JS tag, because it would result in ambiguity or asymmetry when such objects unwind
from JS into wasm and back out.
---
 document/js-api/index.bs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/document/js-api/index.bs b/document/js-api/index.bs
index ba25a4cc..d3464d92 100644
--- a/document/js-api/index.bs
+++ b/document/js-api/index.bs
@@ -267,6 +267,8 @@ namespace WebAssembly {
 
     Promise&lt;Instance> instantiate(
         Module moduleObject, optional object importObject);
+
+    readonly attribute Tag JSTag;
 };
 </pre>
 
@@ -505,6 +507,11 @@ The verification of WebAssembly type requirements is deferred to the
 
 Note: A follow-on streaming API is documented in the <a href="https://webassembly.github.io/spec/web-api/index.html">WebAssembly Web API</a>.
 
+The getter of the <dfn attribute for="WebAssembly">JSTag</dfn> attribute of the {{WebAssembly}} Namespace, when invoked, performs the following steps:
+    1. Let |JSTagAddr| be the result of [=get the JavaScript exception tag|getting the JavaScript exception tag=].
+    1. Let |JSTagObject| be the result of [=create a Tag object|creating a Tag object=] from |JSTagAddr|.
+    1. Return |JSTagObject|.
+
 <h3 id="modules">Modules</h3>
 
 <pre class="idl">
@@ -1306,6 +1313,9 @@ The <dfn constructor for=Exception
 lt="Exception(exceptionTag, payload, options)">new Exception(|exceptionTag|, |payload|, |options|)</dfn>
 constructor steps are:
 
+1. Let |JSTagAddr| be the result of [=get the JavaScript exception tag|getting the JavaScript exception tag=].
+1. If |exceptionTag|.\[[Address]] is equal to |JSTagAddr|,
+    1. Throw a {{TypeError}}.
 1. Let |store| be the [=surrounding agent=]'s [=associated store=].
 1. Let [|types|] → [] be [=tag_type=](|store|, |exceptionTag|.\[[Address]]).
 1. If |types|'s [=list/size=] is not |payload|'s [=list/size=],