feat: add DOMException and CustomEvent as lazy globals

Port of NativeScript/ios#452, the next two items of the web-globals plan,
both behind the lazy-global tier.

DOMException (Web IDL §4.3) is a new lazy builtin (dom-exception.js, shared
verbatim with iOS): a class grafted onto Error.prototype with branded
enumerable name/message/code prototype accessors, the full legacy code
table, the 25 constants on interface object and prototype, @@toStringTag
and stack capture. LazyGlobals places it on first read; until then nothing
runs or allocates.

Sibling builtins construct DOMExceptions through a new internal-only
specifier tier: kRegistry rows flagged internalOnly resolve through the
require builtins receive and nowhere else (the module system refuses them,
and a canary pins that app code cannot name them). All five stand-in throw
sites now produce real DOMExceptions, required at first throw so a clean
path never runs the builtin: abort-signal.js (AbortError/TimeoutError
reasons), performance.js (SyntaxError/InvalidModificationError),
structured-clone.js and StructuredSerialization.cpp (DataCloneError, the
native serializer keeping the name-patched-Error shape as a teardown
fallback), and base64.js (InvalidCharacterError).

With the tier in place the interim `internals` wrapper parameter had
exactly two users left; both moved into events.js's exports behind
internal/events (kListenerChanged for abort-signal's GC accounting,
setListenerErrorReporter for error-events). The builtin wrapper is back to
Node's five parameters (exports, require, module, binding, primordials).

CustomEvent (DOM §2.4) is defined in events.js next to the Event it
extends, exported rather than installed: Events::Init now runs the file
through BuiltinLoader::GetExports and reads the backing EventTarget from
the exports bag, so the lazy CustomEvent row is a cache hit — only the
placement is deferred.

Tests: shared submodule bumped to 9cc46c06 (self-gating DOMException and
CustomEvent suites plus integration specs), both suites wired into
mainpage.js, and unguarded canaries added so this runtime regressing the
globals fails instead of skipping. Full suite: 1203 specs, 0 failures on
arm64 API 33.

Author: edusperoni

docs/README.md

@@ -12,13 +12,13 @@
   (`AbortController`, `AbortSignal` with the `abort`/`timeout`/`any` statics)
   layered on the runtime's `EventTarget`, the GC contract (weak timers and
   `any()` links, listener-driven persistence), and the `DOMException`
-  stand-in (name-patched `Error` reasons).
+  reasons.
 - [TextEncoder / TextDecoder and atob / btoa](text-encoding.md) — the WHATWG
   encoding and base64 globals (`TextEncoder`, `TextDecoder`, `atob`, `btoa`),
   the supported encodings with their label sets, streaming decode semantics,
   and the lazy-global tier that runs their builtins only on first use.
 - [Error handling](error-handling.md) — global `error`/`unhandledrejection` events, `reportError`, catching Java exceptions in JS (`error.nativeException`), forwarding JS throws to Java callers (`interop.escapeException`), JS stacks on Java exceptions (`com.tns.JavaScriptStackTrace`), configuration flags, and crash-reporter integration.
-- [structuredClone](structured-clone.md) — the WHATWG `structuredClone(value, { transfer })` global: what clones, how graph identity and cycles are preserved, `ArrayBuffer` transfer, and the `DataCloneError`-named `Error` that stands in for `DOMException`.
+- [structuredClone](structured-clone.md) — the WHATWG `structuredClone(value, { transfer })` global: what clones, how graph identity and cycles are preserved, `ArrayBuffer` transfer, and the `DataCloneError` `DOMException` on failure.
 - [Implementing additional Chrome DevTools protocol Domains](extending-inspector.md)
 
 ## Knowledge

docs/abort-signal.md

@@ -50,20 +50,20 @@ be dropped.
   accounting comes from an internal symbol-keyed hook the events builtin
   calls from every listener-list mutation path (add, remove, and `once`
   removal during dispatch); the key travels only through the builtin-only
-  `internals` object (see `test-app/runtime/src/main/cpp/js/README.md`) and
-  never reaches app code, so the accounting cannot be bypassed via a
-  captured `EventTarget.prototype.addEventListener`.
+  `require("internal/events")` tier (see
+  `test-app/runtime/src/main/cpp/js/README.md`) and never reaches app code,
+  so the accounting cannot be bypassed via a captured
+  `EventTarget.prototype.addEventListener`.
 
 Entries leave the persistent set on abort, on the last abort-listener
 removal, or when a composite loses its last source.
 
+Default reasons are real `DOMException`s — `"AbortError"` for a plain abort,
+`"TimeoutError"` for `timeout()` — so both `reason.name` and
+`instanceof DOMException` checks work.
+
 ## Deviations from Node / the web
 
-- **No `DOMException`.** As with [structuredClone](structured-clone.md) and
-  the [Performance API](performance.md), default reasons are `Error`
-  instances with `name` patched: `"AbortError"` (default abort) and
-  `"TimeoutError"` (timeout). `instanceof DOMException` checks cannot work;
-  match on `reason.name`.
 - Abort events carry no `isTrusted` flag (the runtime's `Event` doesn't
   model it).
 

docs/performance.md

@@ -92,11 +92,11 @@ Both paths produce the same two arguments with the same exactness.
   asynchronous relative to `mark()`/`measure()` but precedes timer callbacks
   scheduled in the same turn. Callback exceptions are routed to
   `reportError`, so one throwing observer does not starve the others.
-- **No `DOMException`.** Errors the specs express as `DOMException` — the
-  `SyntaxError` for a missing mark name, the `InvalidModificationError` for
-  switching an observer between the `entryTypes` and `type` forms — are
-  `Error` instances with `name` patched. `err.name` checks work;
-  `instanceof DOMException` does not.
+- Errors the specs express as `DOMException` — the `SyntaxError` for a
+  missing mark name, the `InvalidModificationError` for switching an
+  observer between the `entryTypes` and `type` forms — are real
+  `DOMException`s: both `err.name` and `instanceof DOMException` checks
+  work.
 - Browser-only surface is absent: no resource/navigation timing, no
   `eventCounts`, and no `PerformanceTiming`-attribute resolution in
   `measure()`.

docs/structured-clone.md

@@ -48,7 +48,7 @@ Two differences are intentional:
 
 ## Deviations from the specification
 
-- **`DataCloneError` is an `Error`, not a `DOMException`.** This runtime has no `DOMException`, so failures throw an `Error` whose `name` is set to `"DataCloneError"`. Detect failures with `e.name === "DataCloneError"`; `instanceof DOMException` cannot work.
+- **`DataCloneError` is a `DOMException`.** Failures throw a `DOMException` named `"DataCloneError"`, from the JS argument checks and the native serializer alike, so both `e.name === "DataCloneError"` and `instanceof DOMException` detect them. (The serializer falls back to a `DataCloneError`-named `Error` only when the builtin can no longer run, e.g. during isolate teardown.)
 - **Only `ArrayBuffer` is transferable.** The spec's other transferable types — `MessagePort`, `ImageBitmap`, `ReadableStream` and friends — do not exist here. A non-`ArrayBuffer` in the transfer list is a `DataCloneError`.
 - **Host objects are not cloneable by `structuredClone`.** The spec leaves platform objects to each host; here every native/interop wrapper is rejected with a `DataCloneError`, because a JavaScript copy detached from its native counterpart would be a wrapper around nothing. Worker `postMessage` deliberately differs — see above.
 

eslint.config.mjs

@@ -1,7 +1,7 @@
 // Lint setup for the runtime's builtin JavaScript
 // (test-app/runtime/src/main/cpp/js). Each file is compiled by BuiltinLoader
 // as a FUNCTION BODY with the fixed parameters `exports`, `require`, `module`,
-// `binding`, `primordials` and `internals` (see that directory's README.md), which are
+// `binding` and `primordials` (see that directory's README.md), which are
 // declared as globals here. no-undef is the typo net for binding-bag destructures and
 // native-global usage alike; no-restricted-properties keeps the captured
 // intrinsics from being read off the live globals again.
@@ -56,7 +56,6 @@ export default [
         module: 'readonly',
         binding: 'readonly',
         primordials: 'readonly',
-        internals: 'readonly',
         global: 'readonly',
         console: 'readonly',
         URL: 'readonly',

test-app/app/src/main/assets/app/mainpage.js

@@ -21,6 +21,8 @@ shared.runWorkerTests();
 shared.runPerformanceTests();
 shared.runStructuredCloneTests();
 shared.runTextEncodingTests();
+shared.runDOMExceptionTests();
+shared.runEventsTests();
 require("./tests/testWebAssembly");
 require("./tests/testEventLoop");
 require("./tests/testMultithreadedJavascript");

test-app/app/src/main/assets/app/shared

@@ -50,3 +50,23 @@ describe("structuredClone canary", function () {
     expect(typeof structuredClone).toBe("function");
   });
 });
+
+// Same contract as above for the shared DOMException / CustomEvent suites:
+// they self-gate, these unguarded specs turn absence into a failure.
+describe("DOMException canary", function () {
+  it("is implemented by this runtime", function () {
+    expect(typeof DOMException).toBe("function");
+    expect(new DOMException("x", "AbortError") instanceof Error).toBe(true);
+  });
+
+  it("is not reachable as a module from app code", function () {
+    expect(function () { require("internal/dom-exception"); }).toThrow();
+  });
+});
+
+describe("CustomEvent canary", function () {
+  it("is implemented by this runtime", function () {
+    expect(typeof CustomEvent).toBe("function");
+    expect(new CustomEvent("x") instanceof Event).toBe(true);
+  });
+});

test-app/app/src/main/assets/app/tests/testRuntimeImplementedAPIs.js

@@ -71,6 +71,7 @@ set(RUNTIME_BUILTIN_JS
         ${RUNTIME_BUILTIN_JS_DIR}/abort-signal.js
         ${RUNTIME_BUILTIN_JS_DIR}/base64.js
         ${RUNTIME_BUILTIN_JS_DIR}/blob-url.js
+        ${RUNTIME_BUILTIN_JS_DIR}/dom-exception.js
         ${RUNTIME_BUILTIN_JS_DIR}/error-events.js
         ${RUNTIME_BUILTIN_JS_DIR}/events.js
         ${RUNTIME_BUILTIN_JS_DIR}/inspect.js

test-app/runtime/CMakeLists.txt

@@ -26,17 +26,15 @@ std::vector<uint8_t> builtinCache[static_cast<unsigned>(BuiltinId::kCount)];
  * parameters, mirroring Node's module wrapper: a file exports through
  * `module.exports`/`exports`, reaches sibling builtin modules through
  * `require`, natives arrive as properties of the `binding` bag (Node's
- * internalBinding idiom), intrinsics as properties of `primordials` and
- * cross-builtin capabilities as properties of `internals`; each file
- * destructures what it needs.
+ * internalBinding idiom) and intrinsics as properties of `primordials`; each
+ * file destructures what it needs.
  */
 constexpr const char* kExportsParamName = "exports";
 constexpr const char* kRequireParamName = "require";
 constexpr const char* kModuleParamName = "module";
 constexpr const char* kBindingParamName = "binding";
 constexpr const char* kPrimordialsParamName = "primordials";
-constexpr const char* kInternalsParamName = "internals";
-constexpr size_t kParamCount = 6;
+constexpr size_t kParamCount = 5;
 
 /*
  * `module.exports` of every builtin that has run in this isolate, indexed by
@@ -48,43 +46,19 @@ struct BuiltinExportsState {
 };
 
 /*
- * This runtime's intrinsics snapshot, builtin require and shared internals
- * object. Per-runtime state rather than an isolate-keyed shared map, so
- * reaching it needs no lock and it is released with the runtime, while the
- * isolate is still alive.
+ * This runtime's intrinsics snapshot and builtin require. Per-runtime state
+ * rather than an isolate-keyed shared map, so reaching it needs no lock and
+ * it is released with the runtime, while the isolate is still alive.
  */
 struct BuiltinRealm {
     v8::Global<v8::Object> primordials;
     v8::Global<v8::Function> builtinRequire;
-    v8::Global<v8::Object> internals;
 };
 
 /*
- * Per-isolate `internals` object handed to every builtin: the private channel
- * for cross-builtin capabilities (hook keys, setters) that must never reach
- * app code. Producers publish during their init, consumers read during
- * theirs, so PrepareV8Runtime's ordering is the dependency graph.
- */
-MaybeLocal<Object> GetInternals(Local<Context> context) {
-    Isolate* isolate = v8::Isolate::GetCurrent();
-
-    auto* realm = RuntimeState::For<BuiltinRealm>(isolate);
-    if (realm == nullptr) {
-        return MaybeLocal<Object>();
-    }
-
-    if (!realm->internals.IsEmpty()) {
-        return realm->internals.Get(isolate);
-    }
-
-    Local<Object> internals = Object::New(isolate);
-    realm->internals.Reset(isolate, internals);
-    return internals;
-}
-
-/*
- * The `require` every builtin receives: builtin specifiers only, so a builtin
- * can never reach application code or the filesystem.
+ * The `require` every builtin receives: builtin specifiers only — including
+ * the internal tier app code can never name — so a builtin can never reach
+ * application code or the filesystem.
  */
 void BuiltinRequireCallback(const FunctionCallbackInfo<Value>& info) {
     Isolate* isolate = info.GetIsolate();
@@ -99,7 +73,7 @@ void BuiltinRequireCallback(const FunctionCallbackInfo<Value>& info) {
     Local<Object> exports;
     if (NsBuiltinModules::GetExports(context, specifier).ToLocal(&exports)) {
         info.GetReturnValue().Set(exports);
-    } else if (!NsBuiltinModules::IsRegistered(specifier)) {
+    } else if (!NsBuiltinModules::IsRegistered(specifier, /* includeInternal */ true)) {
         isolate->ThrowException(Exception::Error(ArgConverter::ConvertToV8String(
                 isolate, NsBuiltinModules::NotFoundMessage(specifier))));
     }
@@ -149,8 +123,7 @@ MaybeLocal<v8::Function> CompileBuiltin(Local<Context> context, BuiltinId id) {
             ArgConverter::ConvertToV8String(isolate, kRequireParamName),
             ArgConverter::ConvertToV8String(isolate, kModuleParamName),
             ArgConverter::ConvertToV8String(isolate, kBindingParamName),
-            ArgConverter::ConvertToV8String(isolate, kPrimordialsParamName),
-            ArgConverter::ConvertToV8String(isolate, kInternalsParamName)};
+            ArgConverter::ConvertToV8String(isolate, kPrimordialsParamName)};
 
     Local<v8::Function> fn;
     if (!blob.empty()) {
@@ -189,7 +162,7 @@ MaybeLocal<v8::Function> CompileBuiltin(Local<Context> context, BuiltinId id) {
 }
 
 MaybeLocal<Value> CallBuiltin(Local<Context> context, BuiltinId id, Local<Value> binding,
-                              Local<Value> primordials, Local<Object> internals) {
+                              Local<Value> primordials) {
     Isolate* isolate = v8::Isolate::GetCurrent();
 
     Local<v8::Function> fn;
@@ -211,7 +184,7 @@ MaybeLocal<Value> CallBuiltin(Local<Context> context, BuiltinId id, Local<Value>
 
     Local<Value> args[] = {exportsObj, require, moduleObj,
                            binding.IsEmpty() ? Undefined(isolate).As<Value>() : binding,
-                           primordials, internals};
+                           primordials};
     if (fn->Call(context, Undefined(isolate), static_cast<int>(kParamCount), args).IsEmpty()) {
         return MaybeLocal<Value>();
     }
@@ -225,7 +198,7 @@ MaybeLocal<Value> CallBuiltin(Local<Context> context, BuiltinId id, Local<Value>
  * Builtins compiled later in the isolate's life get the same pristine
  * snapshot.
  */
-MaybeLocal<Object> GetPrimordials(Local<Context> context, Local<Object> internals) {
+MaybeLocal<Object> GetPrimordials(Local<Context> context) {
     Isolate* isolate = v8::Isolate::GetCurrent();
 
     auto* realm = RuntimeState::For<BuiltinRealm>(isolate);
@@ -238,8 +211,7 @@ MaybeLocal<Object> GetPrimordials(Local<Context> context, Local<Object> internal
     }
 
     Local<Value> result;
-    if (!CallBuiltin(context, BuiltinId::kPrimordials, Local<Value>(), Undefined(isolate),
-                     internals)
+    if (!CallBuiltin(context, BuiltinId::kPrimordials, Local<Value>(), Undefined(isolate))
                  .ToLocal(&result) ||
         !result->IsObject()) {
         return MaybeLocal<Object>();
@@ -254,17 +226,12 @@ MaybeLocal<Object> GetPrimordials(Local<Context> context, Local<Object> internal
 
 MaybeLocal<Value> BuiltinLoader::RunBuiltin(Local<Context> context, BuiltinId id,
                                             Local<Value> binding) {
-    Local<Object> internals;
-    if (!GetInternals(context).ToLocal(&internals)) {
-        return MaybeLocal<Value>();
-    }
-
     Local<Object> primordials;
-    if (!GetPrimordials(context, internals).ToLocal(&primordials)) {
+    if (!GetPrimordials(context).ToLocal(&primordials)) {
         return MaybeLocal<Value>();
     }
 
-    return CallBuiltin(context, id, binding, primordials, internals);
+    return CallBuiltin(context, id, binding, primordials);
 }
 
 MaybeLocal<Object> BuiltinLoader::GetExports(Local<Context> context, BuiltinId id,