From 2044ebfc8ce6e3e1ad7e9537604b8552f3b73c1b Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 16:23:41 -0300
Subject: [PATCH 1/7] feat: web-compliant error handling (unhandled rejections,
 WHATWG error events)

Ports the error model from NativeScript/ios#409 to the Android runtime.

Unhandled promise rejection tracking:
- Register SetPromiseRejectCallback (previously rejections vanished with
  no log, no callback). Rejections are tracked per-isolate and drained
  once per looper turn via a LooperTasks task, so a handler attached in
  the same turn always cancels the report.
- Unhandled ones report through the existing __onUncaughtError hook with
  an always-on "Unhandled promise rejection:" logcat entry; late-attached
  handlers fire `rejectionhandled` (as a task, per spec, carrying the
  original reason; already-reported promises are held weakly).
- Worker isolates dispatch `unhandledrejection` on the worker global
  first, then fall through to the existing worker onerror channel.

WHATWG error events on globalThis:
- Events.{h,cpp}: generic Event/EventTarget constructors, the
  addEventListener/removeEventListener/dispatchEvent mixin, and the
  internal backing target (stashed natively for future consumers).
- ErrorEvents.{h,cpp}: ErrorEvent/PromiseRejectionEvent, reportError()
  and the native dispatch closures, layered on the generic primitives
  via a one-shot _installListenerErrorReporter handoff. Dispatch
  closures are captured at init so events keep firing even if app code
  overwrites globalThis.dispatchEvent.
- NativeScriptException keeps the reporting machinery and the rejection
  tracker, mirroring the iOS file layout.

preventDefault() semantics:
- Uncaught errors dispatch a cancelable `error` ErrorEvent before the
  __onUncaughtError/__onDiscardedError hooks; preventDefault() fully
  handles the report. passExceptionToJsNative now returns that handled
  flag and NativeScriptUncaughtExceptionHandler skips the error activity
  and the default (crashing) handler when set.
- Back-compat: unprevented errors behave exactly as before.

Not ported (already native to Android): interop.escapeException - a JS
throw in a method override already surfaces as a real
com.tns.NativeScriptException to the Java caller, and caught Java
exceptions already carry error.nativeException. crashOnUncaughtJsExceptions
is likewise unnecessary - Android crashes by default on truly-uncaught
exceptions.

Testing: 30 new jasmine specs (WHATWG events/EventTarget semantics,
reportError, unhandled rejections incl. rejectionhandled); full suite
green on an API 35 arm64 emulator with no changes to existing suites.
---
 test-app/app/src/main/assets/app/mainpage.js  |   2 +
 .../main/assets/app/tests/testErrorEvents.js  | 245 +++++++++++++
 .../app/tests/testUnhandledRejections.js      | 181 ++++++++++
 .../NativeScriptUncaughtExceptionHandler.java |  10 +-
 test-app/runtime/CMakeLists.txt               |   2 +
 test-app/runtime/src/main/cpp/ErrorEvents.cpp | 244 +++++++++++++
 test-app/runtime/src/main/cpp/ErrorEvents.h   |  58 +++
 test-app/runtime/src/main/cpp/Events.cpp      | 181 ++++++++++
 test-app/runtime/src/main/cpp/Events.h        |  25 ++
 .../src/main/cpp/NativeScriptException.cpp    | 331 ++++++++++++++++++
 .../src/main/cpp/NativeScriptException.h      | 108 +++++-
 test-app/runtime/src/main/cpp/Runtime.cpp     |  42 ++-
 test-app/runtime/src/main/cpp/Runtime.h       |  51 ++-
 .../runtime/src/main/cpp/com_tns_Runtime.cpp  |   7 +-
 .../src/main/java/com/tns/Runtime.java        |  12 +-
 15 files changed, 1480 insertions(+), 19 deletions(-)
 create mode 100644 test-app/app/src/main/assets/app/tests/testErrorEvents.js
 create mode 100644 test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
 create mode 100644 test-app/runtime/src/main/cpp/ErrorEvents.cpp
 create mode 100644 test-app/runtime/src/main/cpp/ErrorEvents.h
 create mode 100644 test-app/runtime/src/main/cpp/Events.cpp
 create mode 100644 test-app/runtime/src/main/cpp/Events.h

diff --git a/test-app/app/src/main/assets/app/mainpage.js b/test-app/app/src/main/assets/app/mainpage.js
index 8184e7553..cf311f456 100644
--- a/test-app/app/src/main/assets/app/mainpage.js
+++ b/test-app/app/src/main/assets/app/mainpage.js
@@ -74,6 +74,8 @@ require('./tests/testURLImpl.js');
 require('./tests/testURLSearchParamsImpl.js');
 require('./tests/testPerformanceNow');
 require('./tests/testQueueMicrotask');
+require('./tests/testErrorEvents');
+require('./tests/testUnhandledRejections');
 require("./tests/testConcurrentAccess");
 
 require("./tests/testESModules.mjs");
diff --git a/test-app/app/src/main/assets/app/tests/testErrorEvents.js b/test-app/app/src/main/assets/app/tests/testErrorEvents.js
new file mode 100644
index 000000000..2e1cbd988
--- /dev/null
+++ b/test-app/app/src/main/assets/app/tests/testErrorEvents.js
@@ -0,0 +1,245 @@
+describe("WHATWG error events", function () {
+    // Many tests exercise the global error path, which ends in the
+    // __onUncaughtError / __onDiscardedError hooks when a listener does not
+    // preventDefault(). Install spies for every test and restore the previous
+    // hooks in afterEach. Also track listeners added on the global target so
+    // they never leak into other suites (the internal EventTarget backing the
+    // global is process-wide).
+    var previousUncaughtHook;
+    var previousDiscardedHook;
+    var uncaught;
+    var discarded;
+    var addedGlobalListeners;
+
+    beforeEach(function () {
+        previousUncaughtHook = global.__onUncaughtError;
+        previousDiscardedHook = global.__onDiscardedError;
+        uncaught = [];
+        discarded = [];
+        global.__onUncaughtError = function (error) {
+            uncaught.push(error);
+        };
+        global.__onDiscardedError = function (error) {
+            discarded.push(error);
+        };
+        addedGlobalListeners = [];
+    });
+
+    afterEach(function () {
+        global.__onUncaughtError = previousUncaughtHook;
+        global.__onDiscardedError = previousDiscardedHook;
+        for (var i = 0; i < addedGlobalListeners.length; i++) {
+            var l = addedGlobalListeners[i];
+            global.removeEventListener(l.type, l.handler);
+        }
+        addedGlobalListeners = [];
+    });
+
+    function onGlobal(type, handler) {
+        global.addEventListener(type, handler);
+        addedGlobalListeners.push({ type: type, handler: handler });
+    }
+
+    // Wait a couple of quiet looper turns before asserting a NON-event.
+    function afterQuietTurns(cb) {
+        setTimeout(function () {
+            setTimeout(cb, 25);
+        }, 25);
+    }
+
+    it("reportError fires an 'error' listener with an ErrorEvent carrying error and message", function (done) {
+        var err = new Error("x");
+        var received = null;
+        onGlobal("error", function (e) {
+            received = e;
+            e.preventDefault();
+        });
+
+        global.reportError(err);
+
+        expect(received).not.toBeNull();
+        expect(received instanceof ErrorEvent).toBe(true);
+        expect(received.type).toBe("error");
+        expect(received.error).toBe(err);
+        expect(received.message).toBe("x");
+        // preventDefault() in the listener must suppress the __onUncaughtError hook.
+        afterQuietTurns(function () {
+            expect(uncaught.length).toBe(0);
+            done();
+        });
+    });
+
+    it("reportError without preventDefault still invokes __onUncaughtError (back-compat)", function () {
+        var err = new Error("back-compat");
+        var received = null;
+        onGlobal("error", function (e) {
+            received = e;
+        });
+
+        global.reportError(err);
+
+        expect(received).not.toBeNull();
+        expect(received.error).toBe(err);
+        expect(uncaught.length).toBe(1);
+        expect(uncaught[0]).toBe(err);
+    });
+
+    it("reportError throws TypeError when called with no arguments", function () {
+        expect(function () {
+            global.reportError();
+        }).toThrowError(TypeError);
+    });
+
+    it("a discarded Java exception dispatches an 'error' event before __onDiscardedError", function () {
+        var received = null;
+        onGlobal("error", function (e) {
+            received = e;
+        });
+
+        var test = new com.tns.tests.DiscardedExceptionTest();
+        test.reportSupressedException();
+
+        expect(received).not.toBeNull();
+        expect(received instanceof ErrorEvent).toBe(true);
+        expect(received.error).not.toBeNull();
+        expect(received.error.message).toBe("Exception to suppress");
+        // Unprevented, so the existing hook still fires (back-compat).
+        expect(discarded.length).toBe(1);
+        expect(discarded[0]).toBe(received.error);
+    });
+
+    it("preventDefault() on the 'error' event suppresses __onDiscardedError", function () {
+        var received = null;
+        onGlobal("error", function (e) {
+            received = e;
+            e.preventDefault();
+        });
+
+        var test = new com.tns.tests.DiscardedExceptionTest();
+        test.reportSupressedException();
+
+        expect(received).not.toBeNull();
+        expect(discarded.length).toBe(0);
+    });
+
+    describe("constructors and EventTarget semantics", function () {
+        it("Event is spec-sane and cancelable via preventDefault", function () {
+            var e = new Event("x", { cancelable: true });
+            expect(e.type).toBe("x");
+            expect(e.cancelable).toBe(true);
+            expect(e.bubbles).toBe(false);
+            expect(e.defaultPrevented).toBe(false);
+            e.preventDefault();
+            expect(e.defaultPrevented).toBe(true);
+        });
+
+        it("a non-cancelable Event ignores preventDefault", function () {
+            var e = new Event("x");
+            e.preventDefault();
+            expect(e.defaultPrevented).toBe(false);
+        });
+
+        it("ErrorEvent exposes message/error/filename/lineno/colno", function () {
+            var err = new Error("boom");
+            var e = new ErrorEvent("error", { message: "m", error: err });
+            expect(e instanceof Event).toBe(true);
+            expect(e.message).toBe("m");
+            expect(e.error).toBe(err);
+            expect(e.filename).toBe("");
+            expect(e.lineno).toBe(0);
+            expect(e.colno).toBe(0);
+        });
+
+        it("PromiseRejectionEvent exposes promise/reason", function () {
+            var p = Promise.reject(1);
+            p.catch(function () {});
+            var r = { some: "reason" };
+            var e = new PromiseRejectionEvent("unhandledrejection", { promise: p, reason: r });
+            expect(e instanceof Event).toBe(true);
+            expect(e.promise).toBe(p);
+            expect(e.reason).toBe(r);
+        });
+
+        it("dispatchEvent returns !defaultPrevented", function () {
+            var target = new EventTarget();
+            target.addEventListener("t", function (e) { e.preventDefault(); });
+            expect(target.dispatchEvent(new Event("t", { cancelable: true }))).toBe(false);
+
+            var target2 = new EventTarget();
+            target2.addEventListener("t", function () {});
+            expect(target2.dispatchEvent(new Event("t", { cancelable: true }))).toBe(true);
+        });
+
+        it("once:true listener fires exactly once", function () {
+            var target = new EventTarget();
+            var count = 0;
+            target.addEventListener("t", function () { count++; }, { once: true });
+            target.dispatchEvent(new Event("t"));
+            target.dispatchEvent(new Event("t"));
+            expect(count).toBe(1);
+        });
+
+        it("removeEventListener stops future dispatches", function () {
+            var target = new EventTarget();
+            var count = 0;
+            var handler = function () { count++; };
+            target.addEventListener("t", handler);
+            target.dispatchEvent(new Event("t"));
+            target.removeEventListener("t", handler);
+            target.dispatchEvent(new Event("t"));
+            expect(count).toBe(1);
+        });
+
+        it("listeners run in registration order", function () {
+            var target = new EventTarget();
+            var order = [];
+            target.addEventListener("t", function () { order.push(1); });
+            target.addEventListener("t", function () { order.push(2); });
+            target.addEventListener("t", function () { order.push(3); });
+            target.dispatchEvent(new Event("t"));
+            expect(order).toEqual([1, 2, 3]);
+        });
+
+        it("stopImmediatePropagation stops remaining listeners", function () {
+            var target = new EventTarget();
+            var order = [];
+            target.addEventListener("t", function (e) { order.push(1); e.stopImmediatePropagation(); });
+            target.addEventListener("t", function () { order.push(2); });
+            target.dispatchEvent(new Event("t"));
+            expect(order).toEqual([1]);
+        });
+
+        it("a throwing listener does not stop later listeners", function () {
+            var target = new EventTarget();
+            var order = [];
+            target.addEventListener("t", function () { order.push(1); throw new Error("listener boom"); });
+            target.addEventListener("t", function () { order.push(2); });
+            target.dispatchEvent(new Event("t"));
+            expect(order).toEqual([1, 2]);
+        });
+    });
+
+    it("reportError still fires listeners after globalThis.dispatchEvent is overwritten", function (done) {
+        var err = new Error("resilient");
+        var received = null;
+        onGlobal("error", function (e) {
+            received = e;
+            e.preventDefault();
+        });
+
+        var originalDispatch = globalThis.dispatchEvent;
+        globalThis.dispatchEvent = function () { return true; };
+        try {
+            global.reportError(err);
+        } finally {
+            globalThis.dispatchEvent = originalDispatch;
+        }
+
+        expect(received).not.toBeNull();
+        expect(received.error).toBe(err);
+        afterQuietTurns(function () {
+            expect(uncaught.length).toBe(0);
+            done();
+        });
+    });
+});
diff --git a/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js b/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
new file mode 100644
index 000000000..ae8c5e6b2
--- /dev/null
+++ b/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
@@ -0,0 +1,181 @@
+describe("unhandled promise rejections", function () {
+    // Unhandled rejections are tracked per-isolate and reported once per
+    // looper turn through the same uncaught-error machinery exposed via
+    // global.__onUncaughtError. Each test installs a temporary hook and
+    // restores the previous one in afterEach no matter what. Assertions are
+    // marker-based (matching this suite's own reasons) so stray rejections
+    // from other suites can never interfere.
+    var previousHook;
+    var reported;
+    var addedGlobalListeners;
+
+    beforeEach(function () {
+        previousHook = global.__onUncaughtError;
+        reported = [];
+        global.__onUncaughtError = function (error) {
+            reported.push(error);
+        };
+        addedGlobalListeners = [];
+    });
+
+    afterEach(function () {
+        global.__onUncaughtError = previousHook;
+        for (var i = 0; i < addedGlobalListeners.length; i++) {
+            var l = addedGlobalListeners[i];
+            global.removeEventListener(l.type, l.handler);
+        }
+        addedGlobalListeners = [];
+    });
+
+    function onGlobal(type, handler) {
+        global.addEventListener(type, handler);
+        addedGlobalListeners.push({ type: type, handler: handler });
+    }
+
+    function reportedSeen(reason) {
+        return reported.indexOf(reason) !== -1;
+    }
+
+    // The drain happens on a looper turn, so poll across a few turns until the
+    // predicate holds (or give up after a bounded number of turns).
+    function pollUntil(predicate, cb) {
+        var turns = 0;
+        (function poll() {
+            if (predicate() || turns >= 25) {
+                cb();
+                return;
+            }
+            turns++;
+            setTimeout(poll, 10);
+        })();
+    }
+
+    // Wait a couple of looper turns to confirm something did NOT happen.
+    function afterQuietTurns(cb) {
+        setTimeout(function () {
+            setTimeout(cb, 20);
+        }, 20);
+    }
+
+    it("reports an unhandled Promise.reject through __onUncaughtError", function (done) {
+        var reason = new Error("unhandled-promise-reject");
+        Promise.reject(reason);
+        pollUntil(function () { return reportedSeen(reason); }, function () {
+            expect(reportedSeen(reason)).toBe(true);
+            done();
+        });
+    });
+
+    it("does not report when .catch is attached synchronously in the same turn", function (done) {
+        var reason = new Error("handled-same-turn");
+        var p = Promise.reject(reason);
+        p.catch(function () {});
+        afterQuietTurns(function () {
+            expect(reportedSeen(reason)).toBe(false);
+            done();
+        });
+    });
+
+    it("reports an uncaught throw from an async function", function (done) {
+        var reason = new Error("async-function-throw");
+        (async () => {
+            throw reason;
+        })();
+        pollUntil(function () { return reportedSeen(reason); }, function () {
+            expect(reportedSeen(reason)).toBe(true);
+            done();
+        });
+    });
+
+    it("reports an unhandled rejection thrown from a .then callback", function (done) {
+        var reason = new Error("then-callback-throw");
+        Promise.resolve().then(function () {
+            throw reason;
+        });
+        pollUntil(function () { return reportedSeen(reason); }, function () {
+            expect(reportedSeen(reason)).toBe(true);
+            done();
+        });
+    });
+
+    it("ignores a late .catch attached after the rejection was already reported", function (done) {
+        var reason = new Error("late-catch");
+        var p = Promise.reject(reason);
+        pollUntil(function () { return reportedSeen(reason); }, function () {
+            expect(reportedSeen(reason)).toBe(true);
+            var countBefore = reported.length;
+            // Attaching a handler after the report was already delivered must
+            // not crash or report again.
+            p.catch(function () {});
+            afterQuietTurns(function () {
+                expect(reported.length).toBe(countBefore);
+                done();
+            });
+        });
+    });
+
+    it("unhandledrejection listener receives reason and promise; preventDefault suppresses the hook", function (done) {
+        var reason = new Error("rejected-with-listener");
+        var received = null;
+        onGlobal("unhandledrejection", function (e) {
+            if (e.reason === reason) {
+                received = e;
+                e.preventDefault();
+            }
+        });
+
+        Promise.reject(reason);
+
+        pollUntil(function () { return received !== null; }, function () {
+            expect(received).not.toBeNull();
+            expect(received instanceof PromiseRejectionEvent).toBe(true);
+            expect(received.type).toBe("unhandledrejection");
+            expect(received.reason).toBe(reason);
+            expect(typeof received.promise.then).toBe("function");
+            afterQuietTurns(function () {
+                expect(reportedSeen(reason)).toBe(false);
+                done();
+            });
+        });
+    });
+
+    it("fires rejectionhandled when a handler is attached after the rejection was reported", function (done) {
+        var reason = new Error("late-handler");
+        var rejectionHandled = null;
+        onGlobal("rejectionhandled", function (e) {
+            if (e.reason === reason) {
+                rejectionHandled = e;
+            }
+        });
+        // Prevent the report so it does not hit the hook; the promise still
+        // counts as reported and becomes outstanding for rejectionhandled
+        // purposes.
+        var reportedPromise = null;
+        onGlobal("unhandledrejection", function (e) {
+            if (e.reason === reason) {
+                reportedPromise = e.promise;
+                e.preventDefault();
+            }
+        });
+
+        var p = Promise.reject(reason);
+
+        pollUntil(function () { return reportedPromise !== null; }, function () {
+            // Attach a late handler a couple turns after the report.
+            setTimeout(function () {
+                p.catch(function () {});
+                pollUntil(function () { return rejectionHandled !== null; }, function () {
+                    expect(rejectionHandled).not.toBeNull();
+                    expect(rejectionHandled instanceof PromiseRejectionEvent).toBe(true);
+                    expect(rejectionHandled.type).toBe("rejectionhandled");
+                    expect(typeof rejectionHandled.promise.then).toBe("function");
+                    expect(rejectionHandled.promise).toBe(reportedPromise);
+                    // The original rejection reason is retained past reporting
+                    // and carried on the rejectionhandled event, per spec.
+                    expect(rejectionHandled.reason).toBe(reason);
+                    done();
+                });
+            }, 20);
+        });
+    });
+});
diff --git a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
index 75a96c2b0..7560b1d9d 100644
--- a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
+++ b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
@@ -22,6 +22,8 @@ public void uncaughtException(Thread thread, Throwable ex) {
         String stackTraceErrorMessage = Runtime.getStackTraceErrorMessage(ex);
         String errorMessage = String.format("%s\nStackTrace:\n%s", currentThreadMessage, stackTraceErrorMessage);
 
+        boolean handledByJs = false;
+
         if (Runtime.isInitialized()) {
             try {
                 if (Util.isDebuggableApp(context)) {
@@ -31,7 +33,7 @@ public void uncaughtException(Thread thread, Throwable ex) {
                 Runtime runtime = Runtime.getCurrentRuntime();
 
                 if (runtime != null) {
-                    runtime.passUncaughtExceptionToJs(ex, ex.getMessage(), stackTraceErrorMessage, Runtime.getJSStackTrace(ex));
+                    handledByJs = runtime.passUncaughtExceptionToJs(ex, ex.getMessage(), stackTraceErrorMessage, Runtime.getJSStackTrace(ex));
                 }
             } catch (Throwable t) {
                 if (Util.isDebuggableApp(context)) {
@@ -44,6 +46,12 @@ public void uncaughtException(Thread thread, Throwable ex) {
             logger.write("Uncaught Exception Message=" + errorMessage);
         }
 
+        if (handledByJs) {
+            // A JS `error` event listener called preventDefault() - the
+            // exception is fully handled: no error activity, no crash.
+            return;
+        }
+
         boolean res = false;
 
         if (Util.isDebuggableApp(context)) {
diff --git a/test-app/runtime/CMakeLists.txt b/test-app/runtime/CMakeLists.txt
index a8e428801..5aaff73c7 100644
--- a/test-app/runtime/CMakeLists.txt
+++ b/test-app/runtime/CMakeLists.txt
@@ -103,6 +103,8 @@ add_library(
         src/main/cpp/ConcurrentQueue.cpp
         src/main/cpp/Constants.cpp
         src/main/cpp/DirectBuffer.cpp
+        src/main/cpp/ErrorEvents.cpp
+        src/main/cpp/Events.cpp
         src/main/cpp/FieldAccessor.cpp
         src/main/cpp/File.cpp
         src/main/cpp/IsolateDisposer.cpp
diff --git a/test-app/runtime/src/main/cpp/ErrorEvents.cpp b/test-app/runtime/src/main/cpp/ErrorEvents.cpp
new file mode 100644
index 000000000..eb9cb19e5
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/ErrorEvents.cpp
@@ -0,0 +1,244 @@
+#include "ErrorEvents.h"
+
+#include "ArgConverter.h"
+#include "NativeScriptAssert.h"
+#include "NativeScriptException.h"
+#include "Runtime.h"
+
+using namespace std;
+using namespace tns;
+using namespace v8;
+
+/*
+ * Non-throwing runtime lookup, safe from V8 callbacks that may fire while a
+ * runtime is being torn down (Runtime::GetRuntime throws in that window).
+ */
+static Runtime* GetRuntimeOrNull(Isolate* isolate) {
+    return static_cast<Runtime*>(
+            isolate->GetData((uint32_t) Runtime::IsolateData::RUNTIME));
+}
+
+/*
+ * Native function handed to the bootstrap IIFE as `nativeReportFatal(error,
+ * stackString)`. It runs the terminal tail (shim + log) WITHOUT re-dispatching
+ * an event: reportError and listener-thrown errors have already gone through
+ * JS dispatch, so dispatching again here would recurse.
+ */
+static void NativeReportFatalCallback(const FunctionCallbackInfo<Value>& info) {
+    auto isolate = info.GetIsolate();
+    Local<Value> error = info.Length() > 0 ? info[0]
+                                           : Undefined(isolate).As<Value>();
+    string stack;
+    if (info.Length() > 1 && info[1]->IsString()) {
+        stack = ArgConverter::ConvertToString(info[1].As<String>());
+    }
+    NativeScriptException::ReportFatalTail(isolate, error, stack);
+}
+
+void ErrorEvents::Init(Local<Context> context) {
+    /*
+     * WHATWG error-events layer, layered on top of the generic event
+     * primitives installed by Events::Init and ported from the iOS runtime.
+     * Plain (module-free) script, strict inside the IIFE, ES5-ish so it never
+     * depends on other runtime extensions. The IIFE is invoked with two
+     * arguments - the internal EventTarget backing the global (so native
+     * dispatch survives app code overwriting globalThis.dispatchEvent) and
+     * the native nativeReportFatal(error, stack) function that runs the
+     * terminal tail - and returns three closures bound to that backing store.
+     * ErrorEvent/PromiseRejectionEvent subclass the Event captured off
+     * globalThis at init time, which runs before any user code.
+     */
+    auto source = R"js(
+    (function (globalTarget, nativeReportFatal) {
+      "use strict";
+      var g = globalThis;
+      var Event = g.Event;
+
+      function ErrorEvent(type, opts) {
+        opts = opts || {};
+        Event.call(this, type, opts);
+        this.message = opts.message !== undefined ? String(opts.message) : "";
+        this.filename = opts.filename !== undefined ? String(opts.filename) : "";
+        this.lineno = opts.lineno !== undefined ? (opts.lineno | 0) : 0;
+        this.colno = opts.colno !== undefined ? (opts.colno | 0) : 0;
+        this.error = opts.error !== undefined ? opts.error : null;
+      }
+      ErrorEvent.prototype = Object.create(Event.prototype);
+      ErrorEvent.prototype.constructor = ErrorEvent;
+
+      function PromiseRejectionEvent(type, opts) {
+        opts = opts || {};
+        Event.call(this, type, opts);
+        this.promise = opts.promise;
+        this.reason = opts.reason;
+      }
+      PromiseRejectionEvent.prototype = Object.create(Event.prototype);
+      PromiseRejectionEvent.prototype.constructor = PromiseRejectionEvent;
+
+      // A listener that throws must not stop other listeners: route the thrown
+      // value to the native fatal tail instead of ever recursively dispatching
+      // another `error` event from inside dispatch.
+      globalTarget._installListenerErrorReporter(function (e) {
+        try { nativeReportFatal(e, (e && e.stack) || ""); } catch (ignored) {}
+      });
+
+      g.reportError = function (e) {
+        if (arguments.length === 0) {
+          throw new TypeError("Failed to execute 'reportError': 1 argument required, but only 0 present.");
+        }
+        var ev = new ErrorEvent("error", {
+          message: (e && e.message !== undefined && e.message !== null) ? String(e.message) : String(e),
+          error: e,
+          cancelable: true
+        });
+        if (globalTarget.dispatchEvent(ev)) {
+          nativeReportFatal(e, (e && e.stack) || "");
+        }
+      };
+
+      g.ErrorEvent = ErrorEvent;
+      g.PromiseRejectionEvent = PromiseRejectionEvent;
+
+      // Closures called by C++. They never look up globalThis.dispatchEvent,
+      // so they keep working even if app code overwrites it.
+      function dispatchErrorEvent(error, message, stack) {
+        var ev = new ErrorEvent("error", {
+          message: message !== undefined && message !== null ? String(message) : "",
+          error: error,
+          cancelable: true
+        });
+        globalTarget.dispatchEvent(ev);
+        return ev.defaultPrevented;
+      }
+      function dispatchUnhandledRejection(promise, reason) {
+        var ev = new PromiseRejectionEvent("unhandledrejection", {
+          promise: promise,
+          reason: reason,
+          cancelable: true
+        });
+        globalTarget.dispatchEvent(ev);
+        return ev.defaultPrevented;
+      }
+      function dispatchRejectionHandled(promise, reason) {
+        var ev = new PromiseRejectionEvent("rejectionhandled", {
+          promise: promise,
+          reason: reason,
+          cancelable: false
+        });
+        globalTarget.dispatchEvent(ev);
+      }
+
+      return [dispatchErrorEvent, dispatchUnhandledRejection, dispatchRejectionHandled];
+    })
+    )js";
+
+    auto isolate = context->GetIsolate();
+    auto runtime = GetRuntimeOrNull(isolate);
+    if (runtime == nullptr) {
+        throw NativeScriptException("ErrorEvents::Init: no runtime for isolate");
+    }
+    if (runtime->GlobalEventTarget().IsEmpty()) {
+        throw NativeScriptException("ErrorEvents::Init: Events::Init must run first");
+    }
+    Local<Object> globalTarget = runtime->GlobalEventTarget().Get(isolate);
+
+    Local<Script> script;
+    if (!Script::Compile(context, ArgConverter::ConvertToV8String(isolate, source))
+                 .ToLocal(&script)) {
+        throw NativeScriptException("ErrorEvents::Init: failed to compile the error-events bootstrap");
+    }
+
+    Local<Value> result;
+    if (!script->Run(context).ToLocal(&result) || !result->IsFunction()) {
+        throw NativeScriptException("ErrorEvents::Init: failed to evaluate the error-events bootstrap");
+    }
+
+    Local<Function> nativeReportFatal;
+    if (!Function::New(context, NativeReportFatalCallback).ToLocal(&nativeReportFatal)) {
+        throw NativeScriptException("ErrorEvents::Init: failed to create nativeReportFatal");
+    }
+
+    Local<Value> installArgs[] = {globalTarget, nativeReportFatal};
+    Local<Value> iifeResult;
+    if (!result.As<Function>()
+                 ->Call(context, context->Global(), 2, installArgs)
+                 .ToLocal(&iifeResult) ||
+        !iifeResult->IsArray()) {
+        throw NativeScriptException("ErrorEvents::Init: the error-events bootstrap did not return the dispatch closures");
+    }
+
+    auto closures = iifeResult.As<Array>();
+    Local<Value> errorFn, rejectionFn, handledFn;
+    if (!closures->Get(context, 0).ToLocal(&errorFn) || !errorFn->IsFunction() ||
+        !closures->Get(context, 1).ToLocal(&rejectionFn) || !rejectionFn->IsFunction() ||
+        !closures->Get(context, 2).ToLocal(&handledFn) || !handledFn->IsFunction()) {
+        throw NativeScriptException("ErrorEvents::Init: unexpected dispatch closures");
+    }
+
+    runtime->DispatchErrorEventFunc().Reset(isolate, errorFn.As<Function>());
+    runtime->DispatchUnhandledRejectionFunc().Reset(isolate, rejectionFn.As<Function>());
+    runtime->DispatchRejectionHandledFunc().Reset(isolate, handledFn.As<Function>());
+}
+
+bool ErrorEvents::DispatchError(Isolate* isolate, Local<Value> error,
+                                const string& messageString,
+                                const string& stack) {
+    auto runtime = GetRuntimeOrNull(isolate);
+    if (runtime == nullptr || runtime->DispatchErrorEventFunc().IsEmpty()) {
+        return false;
+    }
+
+    auto context = isolate->GetCurrentContext();
+    auto dispatch = runtime->DispatchErrorEventFunc().Get(isolate);
+    Local<Value> args[] = {error,
+                           ArgConverter::ConvertToV8String(isolate, messageString),
+                           ArgConverter::ConvertToV8String(isolate, stack)};
+    Local<Value> result;
+    TryCatch tc(isolate);
+    bool success = dispatch->Call(context, context->Global(), 3, args).ToLocal(&result);
+    if (tc.HasCaught()) {
+        DEBUG_WRITE_FORCE("ErrorEvents: exception while dispatching `error` event");
+        return false;
+    }
+    return success && !result.IsEmpty() && result->BooleanValue(isolate);
+}
+
+bool ErrorEvents::DispatchUnhandledRejection(Isolate* isolate,
+                                             Local<Promise> promise,
+                                             Local<Value> reason) {
+    auto runtime = GetRuntimeOrNull(isolate);
+    if (runtime == nullptr || runtime->DispatchUnhandledRejectionFunc().IsEmpty()) {
+        return false;
+    }
+
+    auto context = isolate->GetCurrentContext();
+    auto dispatch = runtime->DispatchUnhandledRejectionFunc().Get(isolate);
+    Local<Value> args[] = {promise, reason};
+    Local<Value> result;
+    TryCatch tc(isolate);
+    bool success = dispatch->Call(context, context->Global(), 2, args).ToLocal(&result);
+    if (tc.HasCaught()) {
+        DEBUG_WRITE_FORCE("ErrorEvents: exception while dispatching `unhandledrejection` event");
+        return false;
+    }
+    return success && !result.IsEmpty() && result->BooleanValue(isolate);
+}
+
+void ErrorEvents::DispatchRejectionHandled(Isolate* isolate,
+                                           Local<Promise> promise,
+                                           Local<Value> reason) {
+    auto runtime = GetRuntimeOrNull(isolate);
+    if (runtime == nullptr || runtime->DispatchRejectionHandledFunc().IsEmpty()) {
+        return;
+    }
+
+    auto context = isolate->GetCurrentContext();
+    auto dispatch = runtime->DispatchRejectionHandledFunc().Get(isolate);
+    Local<Value> args[] = {promise, reason};
+    Local<Value> result;
+    TryCatch tc(isolate);
+    if (!dispatch->Call(context, context->Global(), 2, args).ToLocal(&result) &&
+        tc.HasCaught()) {
+        DEBUG_WRITE_FORCE("ErrorEvents: exception while dispatching `rejectionhandled` event");
+    }
+}
diff --git a/test-app/runtime/src/main/cpp/ErrorEvents.h b/test-app/runtime/src/main/cpp/ErrorEvents.h
new file mode 100644
index 000000000..fead37cf1
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/ErrorEvents.h
@@ -0,0 +1,58 @@
+#ifndef ERROREVENTS_H_
+#define ERROREVENTS_H_
+
+#include <string>
+
+#include "v8.h"
+
+namespace tns {
+
+class ErrorEvents {
+public:
+    /*
+     * Installs the WHATWG error-events layer on top of the generic event
+     * primitives: the ErrorEvent and PromiseRejectionEvent constructors
+     * (subclassing the Event installed by Events::Init, captured off
+     * globalThis at init time) and global reportError. Evaluated once per
+     * isolate during PrepareV8Runtime, right after Events::Init, for both the
+     * main and worker isolates. The bootstrap IIFE is invoked with the backing
+     * event target (Runtime::GlobalEventTarget()) and the native
+     * nativeReportFatal(error, stack) function, and returns three closures
+     * bound to the internal listener store; they are stashed on the Runtime
+     * so native dispatch survives app code overwriting
+     * globalThis.dispatchEvent.
+     */
+    static void Init(v8::Local<v8::Context> context);
+
+    /*
+     * Dispatches the cancelable `error` ErrorEvent through the JS listener
+     * store. Returns true when a listener called preventDefault(). A dispatch
+     * that itself throws is logged and treated as unprevented so an error is
+     * never lost.
+     */
+    static bool DispatchError(v8::Isolate* isolate, v8::Local<v8::Value> error,
+                              const std::string& messageString,
+                              const std::string& stack);
+
+    /*
+     * Dispatches the cancelable `unhandledrejection` PromiseRejectionEvent
+     * through the JS listener store. Returns true when a listener called
+     * preventDefault(). Never re-dispatches on failure: a dispatch that itself
+     * throws is logged and treated as unprevented so the error is never lost.
+     */
+    static bool DispatchUnhandledRejection(v8::Isolate* isolate,
+                                           v8::Local<v8::Promise> promise,
+                                           v8::Local<v8::Value> reason);
+
+    /*
+     * Fires the non-cancelable `rejectionhandled` PromiseRejectionEvent for a
+     * late-attached handler, carrying the original rejection reason.
+     */
+    static void DispatchRejectionHandled(v8::Isolate* isolate,
+                                         v8::Local<v8::Promise> promise,
+                                         v8::Local<v8::Value> reason);
+};
+
+}  // namespace tns
+
+#endif /* ERROREVENTS_H_ */
diff --git a/test-app/runtime/src/main/cpp/Events.cpp b/test-app/runtime/src/main/cpp/Events.cpp
new file mode 100644
index 000000000..42f45aee1
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/Events.cpp
@@ -0,0 +1,181 @@
+#include "Events.h"
+
+#include "ArgConverter.h"
+#include "NativeScriptException.h"
+#include "Runtime.h"
+
+using namespace std;
+using namespace tns;
+using namespace v8;
+
+void Events::Init(Local<Context> context) {
+    /*
+     * Generic WHATWG event primitives, ported from the iOS runtime. Plain
+     * (module-free) script, strict inside the IIFE, ES5-ish so it never
+     * depends on other runtime extensions. The IIFE installs Event/EventTarget
+     * and the global EventTarget methods, then returns the internal
+     * EventTarget instance backing the global so native dispatch survives app
+     * code overwriting globalThis.dispatchEvent. The error-events layer
+     * (ErrorEvents::Init) runs immediately after and installs the native
+     * listener-error reporter through _installListenerErrorReporter.
+     */
+    auto source = R"js(
+    (function () {
+      "use strict";
+      var g = globalThis;
+
+      function Event(type, opts) {
+        opts = opts || {};
+        this.type = String(type);
+        this.bubbles = !!opts.bubbles;
+        this.cancelable = !!opts.cancelable;
+        this.composed = !!opts.composed;
+        this.defaultPrevented = false;
+        this.target = null;
+        this.currentTarget = null;
+        this._stopPropagation = false;
+        this._stopImmediate = false;
+      }
+      Event.prototype.preventDefault = function () {
+        if (this.cancelable) { this.defaultPrevented = true; }
+      };
+      Event.prototype.stopPropagation = function () { this._stopPropagation = true; };
+      Event.prototype.stopImmediatePropagation = function () {
+        this._stopPropagation = true;
+        this._stopImmediate = true;
+      };
+
+      // A listener that throws must not stop other listeners: route the thrown
+      // value to the native fatal tail instead of ever recursively dispatching
+      // another `error` event from inside dispatch. The error-events layer
+      // installs the real reporter via _installListenerErrorReporter (before
+      // any user code runs); until then a thrown listener is swallowed.
+      var reportListenerError = function (e) {};
+
+      function EventTargetImpl() { this._listeners = Object.create(null); }
+      EventTargetImpl.prototype.addEventListener = function (type, callback, options) {
+        if (callback === null || callback === undefined) { return; }
+        type = String(type);
+        var capture = false, once = false;
+        if (typeof options === "boolean") {
+          capture = options;
+        } else if (options && typeof options === "object") {
+          capture = !!options.capture;
+          once = !!options.once;
+        }
+        var list = this._listeners[type];
+        if (!list) { list = this._listeners[type] = []; }
+        for (var i = 0; i < list.length; i++) {
+          if (list[i].callback === callback && list[i].capture === capture) { return; }
+        }
+        list.push({ callback: callback, once: once, capture: capture });
+      };
+      EventTargetImpl.prototype.removeEventListener = function (type, callback, options) {
+        type = String(type);
+        var capture = false;
+        if (typeof options === "boolean") {
+          capture = options;
+        } else if (options && typeof options === "object") {
+          capture = !!options.capture;
+        }
+        var list = this._listeners[type];
+        if (!list) { return; }
+        for (var i = 0; i < list.length; i++) {
+          if (list[i].callback === callback && list[i].capture === capture) {
+            list.splice(i, 1);
+            return;
+          }
+        }
+      };
+      EventTargetImpl.prototype.dispatchEvent = function (event) {
+        event.target = this;
+        event.currentTarget = this;
+        var list = this._listeners[event.type];
+        if (list) {
+          // Snapshot so listeners added during dispatch are not invoked and
+          // registration order is preserved.
+          var snapshot = list.slice();
+          for (var i = 0; i < snapshot.length; i++) {
+            var entry = snapshot[i];
+            var idx = list.indexOf(entry);
+            if (idx === -1) { continue; }  // removed since snapshot
+            if (entry.once) { list.splice(idx, 1); }
+            var cb = entry.callback;
+            try {
+              if (typeof cb === "function") {
+                cb.call(this, event);
+              } else if (cb && typeof cb.handleEvent === "function") {
+                cb.handleEvent(event);
+              }
+            } catch (e) {
+              reportListenerError(e);
+            }
+            if (event._stopImmediate) { break; }
+          }
+        }
+        event.currentTarget = null;
+        return !event.defaultPrevented;
+      };
+
+      // Internal EventTarget instance backing the global. globalThis's
+      // prototype is intentionally NOT made an EventTarget; only the three
+      // methods are bound onto it.
+      var globalTarget = new EventTargetImpl();
+      // Called by the error-events layer to install the native listener-error
+      // reporter into this closure. One-shot: the backing target leaks to app
+      // code via event.target, so the hook removes itself after the install
+      // (which happens during runtime init, before any user code runs).
+      globalTarget._installListenerErrorReporter = function (fn) {
+        reportListenerError = fn;
+        delete globalTarget._installListenerErrorReporter;
+      };
+      g.addEventListener = function (type, callback, options) {
+        return globalTarget.addEventListener(type, callback, options);
+      };
+      g.removeEventListener = function (type, callback, options) {
+        return globalTarget.removeEventListener(type, callback, options);
+      };
+      g.dispatchEvent = function (event) {
+        return globalTarget.dispatchEvent(event);
+      };
+
+      function EventTarget() { EventTargetImpl.call(this); }
+      EventTarget.prototype.addEventListener = EventTargetImpl.prototype.addEventListener;
+      EventTarget.prototype.removeEventListener = EventTargetImpl.prototype.removeEventListener;
+      EventTarget.prototype.dispatchEvent = EventTargetImpl.prototype.dispatchEvent;
+
+      g.Event = Event;
+      g.EventTarget = EventTarget;
+
+      return globalTarget;
+    })
+    )js";
+
+    auto isolate = context->GetIsolate();
+    auto runtime = static_cast<Runtime*>(
+            isolate->GetData((uint32_t) Runtime::IsolateData::RUNTIME));
+    if (runtime == nullptr) {
+        throw NativeScriptException("Events::Init: no runtime for isolate");
+    }
+
+    Local<Script> script;
+    if (!Script::Compile(context, ArgConverter::ConvertToV8String(isolate, source))
+                 .ToLocal(&script)) {
+        throw NativeScriptException("Events::Init: failed to compile the event-primitives bootstrap");
+    }
+
+    Local<Value> result;
+    if (!script->Run(context).ToLocal(&result) || !result->IsFunction()) {
+        throw NativeScriptException("Events::Init: failed to evaluate the event-primitives bootstrap");
+    }
+
+    Local<Value> iifeResult;
+    if (!result.As<Function>()
+                 ->Call(context, context->Global(), 0, nullptr)
+                 .ToLocal(&iifeResult) ||
+        !iifeResult->IsObject()) {
+        throw NativeScriptException("Events::Init: the event-primitives bootstrap did not return the backing target");
+    }
+
+    runtime->GlobalEventTarget().Reset(isolate, iifeResult.As<Object>());
+}
diff --git a/test-app/runtime/src/main/cpp/Events.h b/test-app/runtime/src/main/cpp/Events.h
new file mode 100644
index 000000000..8caea3bb9
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/Events.h
@@ -0,0 +1,25 @@
+#ifndef EVENTS_H_
+#define EVENTS_H_
+
+#include "v8.h"
+
+namespace tns {
+
+class Events {
+public:
+    /*
+     * Installs the generic WHATWG event primitives: the Event and EventTarget
+     * constructors on globalThis, the EventTarget methods (addEventListener /
+     * removeEventListener / dispatchEvent) bound onto globalThis, and the
+     * internal EventTarget instance backing the global. Evaluated once per
+     * isolate during PrepareV8Runtime, before ErrorEvents::Init, for both the
+     * main and worker isolates. Stashes the backing target in
+     * Runtime::GlobalEventTarget() so native layers can dispatch without
+     * going through overwritable globals.
+     */
+    static void Init(v8::Local<v8::Context> context);
+};
+
+}  // namespace tns
+
+#endif /* EVENTS_H_ */
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.cpp b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
index 3b1105708..1f10a4340 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.cpp
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
@@ -1,13 +1,17 @@
 #include "NativeScriptException.h"
 
+#include <algorithm>
 #include <sstream>
 
 #include "ArgConverter.h"
+#include "ErrorEvents.h"
+#include "LooperTasks.h"
 #include "NativeScriptAssert.h"
 #include "Runtime.h"
 #include "Util.h"
 #include "V8GlobalHelpers.h"
 #include "V8StringConstants.h"
+#include "WorkerWrapper.h"
 
 using namespace std;
 using namespace tns;
@@ -213,10 +217,337 @@ void NativeScriptException::OnUncaughtError(Local<Message> message,
   string errorMessage = GetErrorMessage(message, error);
   string stackTrace = GetErrorStackTrace(message->GetStackTrace());
 
+  // Give WHATWG `error` event listeners a chance first; preventDefault()
+  // fully handles the report and nothing is raised to Java.
+  auto isolate = message->GetIsolate();
+  if (ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
+    return;
+  }
+
   NativeScriptException e(errorMessage, stackTrace);
   e.ReThrowToJava();
 }
 
+/*
+ * Non-throwing runtime lookup, safe from V8 callbacks that may fire while a
+ * runtime is being torn down (Runtime::GetRuntime throws in that window).
+ */
+static Runtime* GetRuntimeOrNull(Isolate* isolate) {
+  return static_cast<Runtime*>(
+      isolate->GetData((uint32_t)Runtime::IsolateData::RUNTIME));
+}
+
+static string ToDetailString(Isolate* isolate, Local<Value> value) {
+  auto context = isolate->GetCurrentContext();
+  Local<String> str;
+  if (!value.IsEmpty() && value->ToDetailString(context).ToLocal(&str)) {
+    return ArgConverter::ConvertToString(str);
+  }
+  return "";
+}
+
+static string GetStackTraceOfValue(Isolate* isolate, Local<Value> value) {
+  if (value.IsEmpty()) {
+    return "";
+  }
+  auto stackTrace = Exception::GetStackTrace(value);
+  if (stackTrace.IsEmpty()) {
+    return "";
+  }
+  return NativeScriptException::GetErrorStackTrace(stackTrace);
+}
+
+/*
+ * Splits a multi-line message so it survives logcat's per-message limit,
+ * mirroring PrintErrorMessage but always-on (these reports must be visible
+ * without verbose logging).
+ */
+static void LogLines(const string& text) {
+  stringstream ss(text);
+  string line;
+  while (getline(ss, line, '\n')) {
+    DEBUG_WRITE_FORCE("%s", line.c_str());
+  }
+}
+
+void NativeScriptException::OnPromiseRejected(v8::PromiseRejectMessage message) {
+  auto promise = message.GetPromise();
+  auto isolate = promise->GetIsolate();
+  auto runtime = GetRuntimeOrNull(isolate);
+  if (runtime == nullptr || runtime->PromiseRejections() == nullptr) {
+    return;
+  }
+
+  switch (message.GetEvent()) {
+    case v8::kPromiseRejectWithNoHandler:
+      runtime->PromiseRejections()->OnReject(promise, message.GetValue());
+      break;
+    case v8::kPromiseHandlerAddedAfterReject:
+      runtime->PromiseRejections()->OnHandlerAdded(promise);
+      break;
+    default:
+      // kPromiseResolveAfterResolved / kPromiseRejectAfterResolved are not
+      // relevant to unhandled-rejection tracking.
+      break;
+  }
+}
+
+void NativeScriptException::ReportUnhandledRejection(Isolate* isolate,
+                                                     Local<Promise> promise,
+                                                     Local<Value> reason,
+                                                     const string& stackTrace) {
+  if (ErrorEvents::DispatchUnhandledRejection(isolate, promise, reason)) {
+    return;
+  }
+  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:");
+}
+
+void NativeScriptException::ReportFatalTail(Isolate* isolate,
+                                            Local<Value> error,
+                                            const string& stackOverride,
+                                            const string& logPrefix) {
+  auto context = isolate->GetCurrentContext();
+
+  string stackTrace = stackOverride;
+  if (stackTrace.empty()) {
+    stackTrace = GetStackTraceOfValue(isolate, error);
+  }
+
+  // Match the shape the existing __onUncaughtError contract expects: the
+  // error object carries its stack as a `stackTrace` property (see
+  // Runtime::PassExceptionToJsNative).
+  if (error->IsObject() && !stackTrace.empty()) {
+    error.As<Object>()
+        ->Set(context, V8StringConstants::GetStackTrace(isolate),
+              ArgConverter::ConvertToV8String(isolate, stackTrace))
+        .FromMaybe(false);
+  }
+
+  // There is no discardUncaughtJsExceptions decision here - that flag lives
+  // on the Java side and only affects Java-initiated reports. Errors that
+  // reach this tail (reportError, unhandled rejections, throwing listeners)
+  // have no Java caller, so they report through __onUncaughtError and the
+  // process keeps running.
+  CallJsFuncWithErr(error, false /* isDiscarded */);
+
+  if (!logPrefix.empty()) {
+    DEBUG_WRITE_FORCE("%s", logPrefix.c_str());
+  }
+  LogLines(ToDetailString(isolate, error));
+  if (!stackTrace.empty()) {
+    LogLines(stackTrace);
+  }
+}
+
+void PromiseRejectionTracker::OnReject(Local<Promise> promise,
+                                       Local<Value> reason) {
+  auto isolate = promise->GetIsolate();
+  for (auto& entry : pending_) {
+    if (entry.promise.Get(isolate)->SameValue(promise)) {
+      // Already tracked; refresh the reason for the latest rejection.
+      entry.reason.Reset(isolate, reason);
+      return;
+    }
+  }
+
+  PendingRejection entry;
+  entry.promise.Reset(isolate, promise);
+  entry.reason.Reset(isolate, reason);
+  pending_.push_back(std::move(entry));
+  ScheduleDrain();
+}
+
+void PromiseRejectionTracker::OnHandlerAdded(Local<Promise> promise) {
+  auto isolate = promise->GetIsolate();
+
+  // A handler attached before the rejection was drained cancels the report.
+  for (auto it = pending_.begin(); it != pending_.end(); ++it) {
+    if (it->promise.Get(isolate)->SameValue(promise)) {
+      pending_.erase(it);
+      return;
+    }
+  }
+
+  // Otherwise, if the rejection was already reported and the promise is
+  // still outstanding, queue a `rejectionhandled` event. OnHandlerAdded runs
+  // during a microtask checkpoint, but spec fires rejectionhandled as a
+  // task, so defer to the next drain instead of dispatching synchronously.
+  for (auto it = reportedOutstanding_.begin(); it != reportedOutstanding_.end();
+       ++it) {
+    if (it->promise.IsEmpty()) {
+      continue;
+    }
+    if (it->promise.Get(isolate)->SameValue(promise)) {
+      ReportedRejection queued;
+      // Re-anchor the promise strongly (the outstanding handle is weak) and
+      // carry the original reason so the event reports it per spec.
+      queued.promise.Reset(isolate, promise);
+      queued.reason = std::move(it->reason);
+      reportedOutstanding_.erase(it);
+      pendingRejectionHandled_.push_back(std::move(queued));
+      PruneReportedOutstanding();
+      ScheduleDrain();
+      return;
+    }
+  }
+  PruneReportedOutstanding();
+}
+
+void PromiseRejectionTracker::PruneReportedOutstanding() {
+  reportedOutstanding_.erase(
+      std::remove_if(
+          reportedOutstanding_.begin(), reportedOutstanding_.end(),
+          [](const ReportedRejection& r) { return r.promise.IsEmpty(); }),
+      reportedOutstanding_.end());
+}
+
+void PromiseRejectionTracker::ScheduleDrain() {
+  if (drainScheduled_) {
+    return;
+  }
+  drainScheduled_ = true;
+
+  auto looperTasks = runtime_->GetLooperTasks();
+  if (looperTasks == nullptr) {
+    drainScheduled_ = false;
+    return;
+  }
+
+  // The task runs on the runtime's own looper thread, strictly after the
+  // microtask checkpoint of the turn that produced the rejection. It is
+  // dropped (never runs) once the runtime's LooperTasks is terminated, so
+  // capturing the raw Runtime pointer is safe.
+  Runtime* runtime = runtime_;
+  looperTasks->Post([runtime]() {
+    auto isolate = runtime->GetIsolate();
+    v8::Locker locker(isolate);
+    Isolate::Scope isolateScope(isolate);
+    HandleScope handleScope(isolate);
+    auto context = runtime->GetContext();
+    Context::Scope contextScope(context);
+
+    auto tracker = runtime->PromiseRejections();
+    if (tracker != nullptr) {
+      tracker->Drain();
+    }
+  });
+}
+
+/*
+ * Gives a worker's global `onerror` a chance to handle a rejected reason,
+ * mirroring CallbackHandlers::CallWorkerScopeOnErrorHandle (which passes the
+ * message as a string). Returns true when the handler signalled it consumed
+ * the error (truthy return).
+ */
+static bool GiveWorkerOnErrorAChance(Isolate* isolate, Local<Context> context,
+                                     const string& message) {
+  auto global = context->Global();
+  Local<Value> onErrorVal;
+  if (!global->Get(context, ArgConverter::ConvertToV8String(isolate, "onerror"))
+           .ToLocal(&onErrorVal) ||
+      onErrorVal.IsEmpty() || !onErrorVal->IsFunction()) {
+    return false;
+  }
+
+  auto onError = onErrorVal.As<Function>();
+  Local<Value> args[] = {ArgConverter::ConvertToV8String(isolate, message)};
+  Local<Value> result;
+  TryCatch tc(isolate);
+  bool success =
+      onError->Call(context, Undefined(isolate), 1, args).ToLocal(&result);
+  return success && !result.IsEmpty() && result->BooleanValue(isolate);
+}
+
+void PromiseRejectionTracker::Drain() {
+  drainScheduled_ = false;
+  if (draining_) {
+    return;
+  }
+  draining_ = true;
+
+  auto isolate = runtime_->GetIsolate();
+  auto context = isolate->GetCurrentContext();
+
+  // Fire queued rejectionhandled events first (they were deferred from a
+  // microtask checkpoint to run as a task on this drain turn), carrying the
+  // retained original rejection reason.
+  std::vector<ReportedRejection> handledSnapshot;
+  handledSnapshot.swap(pendingRejectionHandled_);
+
+  // Rejections that arrive while a drain is in progress accumulate into a
+  // fresh vector and re-schedule their own drain.
+  std::vector<PendingRejection> snapshot;
+  snapshot.swap(pending_);
+
+  for (auto& queued : handledSnapshot) {
+    if (queued.promise.IsEmpty()) {
+      continue;
+    }
+    try {
+      auto promise = queued.promise.Get(isolate);
+      Local<Value> reason = queued.reason.IsEmpty()
+                                ? Undefined(isolate).As<Value>()
+                                : queued.reason.Get(isolate);
+      ErrorEvents::DispatchRejectionHandled(isolate, promise, reason);
+    } catch (NativeScriptException& ex) {
+      DEBUG_WRITE_FORCE(
+          "PromiseRejectionTracker: exception while firing rejectionhandled: %s",
+          ex.GetErrorMessage().c_str());
+    }
+  }
+
+  auto workerWrapper = WorkerWrapper::FromIsolate(isolate);
+
+  for (auto& entry : snapshot) {
+    try {
+      auto promise = entry.promise.Get(isolate);
+      Local<Value> reason = entry.reason.IsEmpty()
+                                ? Undefined(isolate).As<Value>()
+                                : entry.reason.Get(isolate);
+
+      string stackTrace = GetStackTraceOfValue(isolate, reason);
+
+      if (workerWrapper != nullptr) {
+        // Dispatch the rejection event on the worker's own global first;
+        // preventDefault() there fully handles it. Only when unprevented fall
+        // through to the existing worker channel (worker-global onerror ->
+        // the parent Worker object's onerror).
+        if (!ErrorEvents::DispatchUnhandledRejection(isolate, promise,
+                                                     reason)) {
+          string message =
+              "Unhandled promise rejection: " + ToDetailString(isolate, reason);
+          if (!GiveWorkerOnErrorAChance(isolate, context, message) &&
+              !workerWrapper->IsTerminating() && !workerWrapper->IsDisposed()) {
+            workerWrapper->PassUncaughtExceptionFromWorkerToParent(
+                message, "", stackTrace, 0);
+          }
+        }
+      } else {
+        NativeScriptException::ReportUnhandledRejection(isolate, promise,
+                                                        reason, stackTrace);
+      }
+
+      // The rejection has now been reported (unhandledrejection fired,
+      // prevented or not). Keep the promise as a weak outstanding entry so a
+      // handler attached later fires rejectionhandled; a GC'd promise drops
+      // out on its own.
+      ReportedRejection outstanding;
+      outstanding.promise = std::move(entry.promise);
+      outstanding.reason = std::move(entry.reason);
+      reportedOutstanding_.push_back(std::move(outstanding));
+      reportedOutstanding_.back().promise.SetWeak();
+    } catch (NativeScriptException& ex) {
+      DEBUG_WRITE_FORCE(
+          "PromiseRejectionTracker: exception while reporting rejection: %s",
+          ex.GetErrorMessage().c_str());
+    }
+  }
+
+  PruneReportedOutstanding();
+
+  draining_ = false;
+}
+
 void NativeScriptException::CallJsFuncWithErr(Local<Value> errObj,
                                               jboolean isDiscarded) {
   auto isolate = Isolate::GetCurrent();
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.h b/test-app/runtime/src/main/cpp/NativeScriptException.h
index 255fcd5cb..d44bc6593 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.h
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.h
@@ -2,6 +2,7 @@
 #define NATIVESCRIPTEXCEPTION_H_
 
 #include <exception>
+#include <vector>
 
 #include "JEnv.h"
 #include "JniLocalRef.h"
@@ -10,6 +11,8 @@
 #include "v8.h"
 
 namespace tns {
+class Runtime;
+
 class NativeScriptException : public std::exception {
  public:
   /*
@@ -49,6 +52,33 @@ class NativeScriptException : public std::exception {
   static void OnUncaughtError(v8::Local<v8::Message> message,
                               v8::Local<v8::Value> error);
 
+  /*
+   * Isolate-level promise rejection callback (SetPromiseRejectCallback).
+   * Feeds the per-isolate PromiseRejectionTracker owned by Runtime.
+   */
+  static void OnPromiseRejected(v8::PromiseRejectMessage message);
+
+  /*
+   * Reports an unhandled promise rejection on a non-worker isolate:
+   * dispatches `unhandledrejection` and, when unprevented, falls through to
+   * ReportFatalTail with the "Unhandled promise rejection:" prefix.
+   */
+  static void ReportUnhandledRejection(v8::Isolate* isolate,
+                                       v8::Local<v8::Promise> promise,
+                                       v8::Local<v8::Value> reason,
+                                       const std::string& stackTrace);
+
+  /*
+   * The terminal tail shared by reportError, listener-thrown errors and the
+   * rejection path: calls the __onUncaughtError shim and logs. Does NOT
+   * dispatch any event (the caller already has), preventing recursion.
+   * Unlike a Java-side uncaught exception this never crashes the process -
+   * there is no Java caller to re-throw into.
+   */
+  static void ReportFatalTail(v8::Isolate* isolate, v8::Local<v8::Value> error,
+                              const std::string& stackOverride = "",
+                              const std::string& logPrefix = "");
+
   /*
    * Calls the global "__onUncaughtError" or "__onDiscardedError" if such is
    * provided
@@ -56,6 +86,12 @@ class NativeScriptException : public std::exception {
   static void CallJsFuncWithErr(v8::Local<v8::Value> errObj,
                                 jboolean isDiscarded);
 
+  /*
+   * Generates string stack trace from js StackTrace
+   */
+  static std::string GetErrorStackTrace(
+      const v8::Local<v8::StackTrace>& stackTrace);
+
  private:
   /*
    * Try to get native exception or NativeScriptException from js object
@@ -94,12 +130,6 @@ class NativeScriptException : public std::exception {
                                      v8::Local<v8::Value>& error,
                                      const std::string& prependMessage = "");
 
-  /*
-   * Generates string stack trace from js StackTrace
-   */
-  static std::string GetErrorStackTrace(
-      const v8::Local<v8::StackTrace>& stackTrace);
-
   /*
    *	Adds a prepend message to the normal message process
    */
@@ -123,6 +153,72 @@ class NativeScriptException : public std::exception {
 
   static void PrintErrorMessage(const std::string& errorMessage);
 };
+
+/*
+ * Per-isolate tracker for unhandled promise rejections (ported from the iOS
+ * runtime's PromiseRejectionTracker). All members are touched only while the
+ * v8::Locker for the runtime's isolate is held: OnReject/OnHandlerAdded run
+ * inside V8 callbacks and Drain runs in a LooperTasks task that acquires the
+ * lock, so no extra synchronization is required.
+ */
+class PromiseRejectionTracker {
+ public:
+  explicit PromiseRejectionTracker(Runtime* runtime) : runtime_(runtime) {}
+
+  void OnReject(v8::Local<v8::Promise> promise, v8::Local<v8::Value> reason);
+  void OnHandlerAdded(v8::Local<v8::Promise> promise);
+  /*
+   * Reports every still-unhandled rejection and fires queued
+   * `rejectionhandled` events. Runs on the runtime's own looper turn, after
+   * the microtask checkpoint of the turn that produced the rejection, so a
+   * handler attached in the same turn always cancels the report.
+   */
+  void Drain();
+
+ private:
+  /*
+   * Posts a Drain task to the owning runtime's LooperTasks queue (at most one
+   * outstanding). Tasks posted during runtime teardown are dropped by
+   * LooperTasks itself.
+   */
+  void ScheduleDrain();
+  /* Drop weak handles the GC has already cleared. */
+  void PruneReportedOutstanding();
+
+  /* A promise that was rejected without a handler. */
+  struct PendingRejection {
+    v8::Global<v8::Promise> promise;
+    v8::Global<v8::Value> reason;
+  };
+
+  /*
+   * A rejection that was already reported (`unhandledrejection` fired,
+   * prevented or not). The original reason is retained so a late
+   * `rejectionhandled` event carries it per spec.
+   */
+  struct ReportedRejection {
+    v8::Global<v8::Promise> promise;
+    v8::Global<v8::Value> reason;
+  };
+
+  Runtime* runtime_;
+  std::vector<PendingRejection> pending_;
+  /*
+   * Reported rejections still outstanding. The promise handle is weak
+   * (SetWeak) so a GC'd promise drops the whole entry; a handler added later
+   * moves the entry into pendingRejectionHandled_.
+   */
+  std::vector<ReportedRejection> reportedOutstanding_;
+  /*
+   * `rejectionhandled` events queued by OnHandlerAdded (which runs during a
+   * microtask checkpoint) to fire as a task on the next drain, per spec. Held
+   * strong so the promise survives until the event fires.
+   */
+  std::vector<ReportedRejection> pendingRejectionHandled_;
+  bool drainScheduled_ = false;
+  bool draining_ = false;
+};
+
 }  // namespace tns
 
 #endif /* NATIVESCRIPTEXCEPTION_H_ */
diff --git a/test-app/runtime/src/main/cpp/Runtime.cpp b/test-app/runtime/src/main/cpp/Runtime.cpp
index df0fb6e60..1c4814c91 100644
--- a/test-app/runtime/src/main/cpp/Runtime.cpp
+++ b/test-app/runtime/src/main/cpp/Runtime.cpp
@@ -14,6 +14,8 @@
 #include "ArrayHelper.h"
 #include "CallbackHandlers.h"
 #include "Constants.h"
+#include "ErrorEvents.h"
+#include "Events.h"
 #include "File.h"
 #include "IsolateDisposer.h"
 #include "JsArgConverter.h"
@@ -495,11 +497,11 @@ bool Runtime::TryCallGC() {
   return success;
 }
 
-void Runtime::PassExceptionToJsNative(JNIEnv* env, jobject obj,
-                                      jthrowable exception, jstring message,
-                                      jstring fullStackTrace,
-                                      jstring jsStackTrace,
-                                      jboolean isDiscarded) {
+jboolean Runtime::PassExceptionToJsNative(JNIEnv* env, jobject obj,
+                                          jthrowable exception, jstring message,
+                                          jstring fullStackTrace,
+                                          jstring jsStackTrace,
+                                          jboolean isDiscarded) {
   auto isolate = m_isolate;
 
   string errMsg = ArgConverter::jstringToString(message);
@@ -534,8 +536,17 @@ void Runtime::PassExceptionToJsNative(JNIEnv* env, jobject obj,
                 ArgConverter::jstringToV8String(isolate, jsStackTrace));
   }
 
+  // Give WHATWG `error` event listeners a chance first; preventDefault()
+  // fully handles the report - no __on*Error shim, and the Java caller is
+  // told the exception was handled.
+  string stackTraceStr = ArgConverter::jstringToString(fullStackTrace);
+  if (ErrorEvents::DispatchError(isolate, errObj, errMsg, stackTraceStr)) {
+    return JNI_TRUE;
+  }
+
   // pass err to JS
   NativeScriptException::CallJsFuncWithErr(errObj, isDiscarded);
+  return JNI_FALSE;
 }
 
 static void InitializeV8() {
@@ -603,6 +614,7 @@ Isolate* Runtime::PrepareV8Runtime(const string& filesPath,
       ImportModuleDynamicallyCallback);
 
   isolate->AddMessageListener(NativeScriptException::OnUncaughtError);
+  isolate->SetPromiseRejectCallback(NativeScriptException::OnPromiseRejected);
 
   __android_log_print(ANDROID_LOG_DEBUG, "TNS.Runtime", "V8 version %s",
                       V8::GetVersion());
@@ -779,6 +791,10 @@ Isolate* Runtime::PrepareV8Runtime(const string& filesPath,
   m_looperTasks = std::make_shared<LooperTasks>();
   m_looperTasks->Initialize(ALooper_forThread());
 
+  // Unhandled-promise-rejection tracker; fed by the SetPromiseRejectCallback
+  // above and drained via a LooperTasks task once per looper turn.
+  m_promiseRejections = std::make_unique<PromiseRejectionTracker>(this);
+
   SimpleProfiler::Init(isolate, globalTemplate);
 
   CallbackHandlers::CreateGlobalCastFunctions(isolate, globalTemplate);
@@ -858,6 +874,14 @@ Isolate* Runtime::PrepareV8Runtime(const string& filesPath,
 
   v8::Local<v8::Value> out;
   script->Run(context).ToLocal(&out);
+
+  // Generic WHATWG event primitives (Event/EventTarget + the globalThis
+  // mixin), then the error-events layer on top (ErrorEvent/
+  // PromiseRejectionEvent, reportError and the native dispatch closures) -
+  // installed for both the main and worker isolates.
+  Events::Init(context);
+  ErrorEvents::Init(context);
+
   m_objectManager->Init(isolate);
 
   m_module.Init(isolate, callingDir);
@@ -973,6 +997,14 @@ void Runtime::DestroyRuntime() {
     // will have their posts dropped from now on
     m_looperTasks->Terminate();
   }
+  // The events state holds v8::Global handles (backing event target, dispatch
+  // closures and tracked promise rejections) - reset them while the isolate
+  // is still alive.
+  m_promiseRejections.reset();
+  m_globalEventTarget.Reset();
+  m_dispatchErrorEventFunc.Reset();
+  m_dispatchUnhandledRejectionFunc.Reset();
+  m_dispatchRejectionHandledFunc.Reset();
   tns::disposeIsolate(m_isolate);
 }
 
diff --git a/test-app/runtime/src/main/cpp/Runtime.h b/test-app/runtime/src/main/cpp/Runtime.h
index c317eebe3..424955515 100644
--- a/test-app/runtime/src/main/cpp/Runtime.h
+++ b/test-app/runtime/src/main/cpp/Runtime.h
@@ -19,6 +19,8 @@
 #include <fcntl.h>
 
 namespace tns {
+class PromiseRejectionTracker;
+
 class Runtime {
     public:
         enum IsolateData {
@@ -62,7 +64,14 @@ class Runtime {
         void AdjustAmountOfExternalAllocatedMemory();
         bool NotifyGC(JNIEnv* env, jobject obj);
         bool TryCallGC();
-        void PassExceptionToJsNative(JNIEnv* env, jobject obj, jthrowable exception, jstring message, jstring fullStackTrace, jstring jsStackTrace, jboolean isDiscarded);
+        /*
+         * Reports a Java-side exception to JS: dispatches the WHATWG `error`
+         * event first and, unless a listener called preventDefault(), calls
+         * the __onUncaughtError/__onDiscardedError shim. Returns JNI_TRUE
+         * when a listener prevented the default, so the Java caller can treat
+         * the exception as fully handled (e.g. skip crashing the process).
+         */
+        jboolean PassExceptionToJsNative(JNIEnv* env, jobject obj, jthrowable exception, jstring message, jstring fullStackTrace, jstring jsStackTrace, jboolean isDiscarded);
         void DestroyRuntime();
 
         void Lock();
@@ -94,6 +103,40 @@ class Runtime {
             return m_looperTasks;
         }
 
+        /*
+         * WHATWG events state, the Android analogue of the iOS runtime's
+         * Caches members of the same names. The backing event target is set
+         * by Events::Init, the three dispatch closures by ErrorEvents::Init,
+         * and the rejection tracker is created in PrepareV8Runtime. All are
+         * released in DestroyRuntime before the isolate is disposed.
+         *
+         * Internal EventTarget instance backing the global. Holds the real
+         * listener store, so native layers dispatch through it without going
+         * through overwritable globals (future native consumers like
+         * AbortSignal dispatch through it too).
+         */
+        v8::Global<v8::Object>& GlobalEventTarget() {
+            return m_globalEventTarget;
+        }
+        /*
+         * Error-events dispatch closures returned by the bootstrap IIFE
+         * (ErrorEvents::Init). They close over the internal listener store,
+         * so native dispatch keeps working even if app code overwrites
+         * globalThis.dispatchEvent.
+         */
+        v8::Global<v8::Function>& DispatchErrorEventFunc() {
+            return m_dispatchErrorEventFunc;
+        }
+        v8::Global<v8::Function>& DispatchUnhandledRejectionFunc() {
+            return m_dispatchUnhandledRejectionFunc;
+        }
+        v8::Global<v8::Function>& DispatchRejectionHandledFunc() {
+            return m_dispatchRejectionHandledFunc;
+        }
+        PromiseRejectionTracker* PromiseRejections() const {
+            return m_promiseRejections.get();
+        }
+
     private:
         Runtime(JNIEnv* env, jobject runtime, int id);
 
@@ -115,6 +158,12 @@ class Runtime {
 
         std::shared_ptr<LooperTasks> m_looperTasks;
 
+        v8::Global<v8::Object> m_globalEventTarget;
+        v8::Global<v8::Function> m_dispatchErrorEventFunc;
+        v8::Global<v8::Function> m_dispatchUnhandledRejectionFunc;
+        v8::Global<v8::Function> m_dispatchRejectionHandledFunc;
+        std::unique_ptr<PromiseRejectionTracker> m_promiseRejections;
+
         int64_t m_lastUsedMemory;
 
         v8::Persistent<v8::Function>* m_gcFunc;
diff --git a/test-app/runtime/src/main/cpp/com_tns_Runtime.cpp b/test-app/runtime/src/main/cpp/com_tns_Runtime.cpp
index 5b6981156..71800c0d9 100644
--- a/test-app/runtime/src/main/cpp/com_tns_Runtime.cpp
+++ b/test-app/runtime/src/main/cpp/com_tns_Runtime.cpp
@@ -299,10 +299,10 @@ extern "C" JNIEXPORT void Java_com_tns_Runtime_unlock(JNIEnv* env, jobject obj,
     }
 }
 
-extern "C" JNIEXPORT void Java_com_tns_Runtime_passExceptionToJsNative(JNIEnv* env, jobject obj, jint runtimeId, jthrowable exception, jstring message, jstring fullStackTrace, jstring jsStackTrace, jboolean isDiscarded) {
+extern "C" JNIEXPORT jboolean Java_com_tns_Runtime_passExceptionToJsNative(JNIEnv* env, jobject obj, jint runtimeId, jthrowable exception, jstring message, jstring fullStackTrace, jstring jsStackTrace, jboolean isDiscarded) {
     auto runtime = TryGetRuntime(runtimeId);
     if (runtime == nullptr) {
-        return;
+        return JNI_FALSE;
     }
 
     auto isolate = runtime->GetIsolate();
@@ -313,7 +313,7 @@ extern "C" JNIEXPORT void Java_com_tns_Runtime_passExceptionToJsNative(JNIEnv* e
     v8::Context::Scope context_scope(context);
 
     try {
-        runtime->PassExceptionToJsNative(env, obj, exception, message, fullStackTrace, jsStackTrace, isDiscarded);
+        return runtime->PassExceptionToJsNative(env, obj, exception, message, fullStackTrace, jsStackTrace, isDiscarded);
     } catch (NativeScriptException& e) {
         e.ReThrowToJava();
     } catch (std::exception e) {
@@ -325,6 +325,7 @@ extern "C" JNIEXPORT void Java_com_tns_Runtime_passExceptionToJsNative(JNIEnv* e
         NativeScriptException nsEx(std::string("Error: c++ exception!"));
         nsEx.ReThrowToJava();
     }
+    return JNI_FALSE;
 }
 
 // @CriticalNative ABI: no JNIEnv* / jclass.
diff --git a/test-app/runtime/src/main/java/com/tns/Runtime.java b/test-app/runtime/src/main/java/com/tns/Runtime.java
index bb8f3db19..9bf61d1d8 100644
--- a/test-app/runtime/src/main/java/com/tns/Runtime.java
+++ b/test-app/runtime/src/main/java/com/tns/Runtime.java
@@ -75,7 +75,7 @@ private boolean notifyGc(int runtimeId) {
 
     private native void unlock(int runtimeId);
 
-    private native void passExceptionToJsNative(int runtimeId, Throwable ex, String message, String fullStackTrace, String jsStackTrace, boolean isDiscarded);
+    private native boolean passExceptionToJsNative(int runtimeId, Throwable ex, String message, String fullStackTrace, String jsStackTrace, boolean isDiscarded);
 
     @CriticalNative
     private static native int getCurrentRuntimeIdCritical();
@@ -107,8 +107,14 @@ public static void SetManualInstrumentationMode(String mode) {
 
     private static native void ResetDateTimeConfigurationCache(int runtimeId);
 
-    void passUncaughtExceptionToJs(Throwable ex, String message, String fullStackTrace, String jsStackTrace) {
-        passExceptionToJsNative(getRuntimeId(), ex, message, fullStackTrace, jsStackTrace, false);
+    /**
+     * Reports an uncaught exception to JS (WHATWG `error` event, then the
+     * `__onUncaughtError` hook). Returns true when an `error` event listener
+     * called preventDefault(), i.e. the exception is fully handled and the
+     * caller should not crash the process.
+     */
+    boolean passUncaughtExceptionToJs(Throwable ex, String message, String fullStackTrace, String jsStackTrace) {
+        return passExceptionToJsNative(getRuntimeId(), ex, message, fullStackTrace, jsStackTrace, false);
     }
 
     void passDiscardedExceptionToJs(Throwable ex, String prefix) {

From 302691c1e11a6da02f5d0e5d191ed74bfc637937 Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 16:58:42 -0300
Subject: [PATCH 2/7] feat: interop.escapeException (forward original Java
 exceptions to native callers)

Ports the identity-preservation half of iOS's interop.escapeException
(NativeScript/ios#409). The escape direction itself is already Android's
default - a JS throw in a native-invoked override surfaces to the Java
caller as a real com.tns.NativeScriptException - but a rethrown *Java*
exception lost its identity: ReThrowToJava wrapped it, so the caller's
catch of the concrete type (e.g. IOException) never matched.

Now, mirroring iOS:

- New `interop` global (per isolate, workers included) with
  interop.escapeException(x): returns a fresh JS Error branded via a
  private symbol whose payload carries the original Java throwable when
  x is/carries one (nativeException), or {name, message, stack}
  synthesis info otherwise. Idempotent; TypeError with no arguments.
- At the JS->Java boundary, a branded error carrying a Java throwable is
  rethrown UNWRAPPED (env.Throw of the original object), so a native
  `catch (IOException e)` above the caller matches and Throwable
  identity is preserved. JNI does not enforce checked-exception
  declarations, so any Throwable propagates.
- Branded errors bypass discardUncaughtJsExceptions (which only handles
  com.tns.NativeScriptException) - an explicit forward request, matching
  iOS semantics where branded escapes ignore the discard flag.
- Unbranded throws keep today's semantics exactly (wrapper with the
  original as cause); branded plain JS errors keep the default
  NativeScriptException escape shape.

Testing: 7 new specs (brand semantics + boundary round-trips through a
new EscapeExceptionTest fixture, asserting the caller catches the
original java.io.IOException by identity, and that unbranded/plain
behavior is unchanged). Full suite green on an API 35 arm64 emulator.
---
 test-app/app/src/main/assets/app/mainpage.js  |   1 +
 .../assets/app/tests/testEscapeException.js   | 100 ++++++++
 .../com/tns/tests/EscapeExceptionTest.java    |  22 ++
 test-app/runtime/CMakeLists.txt               |   1 +
 test-app/runtime/src/main/cpp/Interop.cpp     | 216 ++++++++++++++++++
 test-app/runtime/src/main/cpp/Interop.h       |  45 ++++
 .../src/main/cpp/NativeScriptException.cpp    |  11 +
 test-app/runtime/src/main/cpp/Runtime.cpp     |   4 +
 8 files changed, 400 insertions(+)
 create mode 100644 test-app/app/src/main/assets/app/tests/testEscapeException.js
 create mode 100644 test-app/app/src/main/java/com/tns/tests/EscapeExceptionTest.java
 create mode 100644 test-app/runtime/src/main/cpp/Interop.cpp
 create mode 100644 test-app/runtime/src/main/cpp/Interop.h

diff --git a/test-app/app/src/main/assets/app/mainpage.js b/test-app/app/src/main/assets/app/mainpage.js
index cf311f456..696466fb2 100644
--- a/test-app/app/src/main/assets/app/mainpage.js
+++ b/test-app/app/src/main/assets/app/mainpage.js
@@ -76,6 +76,7 @@ require('./tests/testPerformanceNow');
 require('./tests/testQueueMicrotask');
 require('./tests/testErrorEvents');
 require('./tests/testUnhandledRejections');
+require('./tests/testEscapeException');
 require("./tests/testConcurrentAccess");
 
 require("./tests/testESModules.mjs");
diff --git a/test-app/app/src/main/assets/app/tests/testEscapeException.js b/test-app/app/src/main/assets/app/tests/testEscapeException.js
new file mode 100644
index 000000000..edf18b412
--- /dev/null
+++ b/test-app/app/src/main/assets/app/tests/testEscapeException.js
@@ -0,0 +1,100 @@
+describe("interop.escapeException", function () {
+    it("exists on the interop global", function () {
+        expect(typeof interop).toBe("object");
+        expect(typeof interop.escapeException).toBe("function");
+    });
+
+    it("returns a throwable Error preserving the message", function () {
+        var wrapped = interop.escapeException(new Error("boom"));
+        expect(wrapped instanceof Error).toBe(true);
+        expect(wrapped.message).toBe("boom");
+
+        var caught = null;
+        try {
+            throw wrapped;
+        } catch (e) {
+            caught = e;
+        }
+        expect(caught).toBe(wrapped);
+    });
+
+    it("throws TypeError when called with no arguments", function () {
+        expect(function () {
+            interop.escapeException();
+        }).toThrowError(TypeError);
+    });
+
+    it("is idempotent (double-wrap returns the same object)", function () {
+        var once = interop.escapeException(new Error("once"));
+        var twice = interop.escapeException(once);
+        expect(twice).toBe(once);
+    });
+
+    it("rethrows the ORIGINAL Java exception to a native caller", function () {
+        var caught = null;
+        try {
+            com.tns.tests.EscapeExceptionTest.throwIOException();
+        } catch (e) {
+            caught = e;
+        }
+        expect(caught).not.toBeNull();
+        expect(caught.nativeException).toBeDefined();
+
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw interop.escapeException(caught);
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        // The native caller caught the original java.io.IOException - not a
+        // com.tns.NativeScriptException wrapper - so a concrete
+        // `catch (IOException e)` in native code would match.
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("java.io.IOException");
+        expect(ret.getMessage()).toBe("original-io-exception");
+        expect(ret.equals(caught.nativeException)).toBe(true);
+
+        // JS is still alive after the escape round-trip.
+        expect(1 + 1).toBe(2);
+    });
+
+    it("an unbranded rethrow keeps today's wrapping semantics", function () {
+        var caught = null;
+        try {
+            com.tns.tests.EscapeExceptionTest.throwIOException();
+        } catch (e) {
+            caught = e;
+        }
+        expect(caught).not.toBeNull();
+
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw caught;
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        // Without the brand the caller receives the NativeScriptException
+        // wrapper, with the original exception preserved as its cause.
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("com.tns.NativeScriptException");
+        expect(ret.getCause().equals(caught.nativeException)).toBe(true);
+    });
+
+    it("a branded plain JS error escapes with the default NativeScriptException shape", function () {
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw interop.escapeException(new Error("plain-escape"));
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        // No underlying Java throwable to unwrap, so the standard escape path
+        // applies: the caller gets a com.tns.NativeScriptException carrying
+        // the JS message.
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("com.tns.NativeScriptException");
+        expect(ret.getMessage()).toContain("plain-escape");
+    });
+});
diff --git a/test-app/app/src/main/java/com/tns/tests/EscapeExceptionTest.java b/test-app/app/src/main/java/com/tns/tests/EscapeExceptionTest.java
new file mode 100644
index 000000000..6167ed9da
--- /dev/null
+++ b/test-app/app/src/main/java/com/tns/tests/EscapeExceptionTest.java
@@ -0,0 +1,22 @@
+package com.tns.tests;
+
+public class EscapeExceptionTest {
+    public static void throwIOException() throws java.io.IOException {
+        throw new java.io.IOException("original-io-exception");
+    }
+
+    /*
+     * Invokes a callback implemented in JS and returns whatever Throwable
+     * escapes it (or null). Catching Throwable (rather than a concrete type)
+     * lets the tests assert exactly which exception class crossed the
+     * JS->Java boundary.
+     */
+    public static Throwable invokeCatchingThrowable(Runnable runnable) {
+        try {
+            runnable.run();
+            return null;
+        } catch (Throwable t) {
+            return t;
+        }
+    }
+}
diff --git a/test-app/runtime/CMakeLists.txt b/test-app/runtime/CMakeLists.txt
index 5aaff73c7..63a33e196 100644
--- a/test-app/runtime/CMakeLists.txt
+++ b/test-app/runtime/CMakeLists.txt
@@ -107,6 +107,7 @@ add_library(
         src/main/cpp/Events.cpp
         src/main/cpp/FieldAccessor.cpp
         src/main/cpp/File.cpp
+        src/main/cpp/Interop.cpp
         src/main/cpp/IsolateDisposer.cpp
         src/main/cpp/JEnv.cpp
         src/main/cpp/DesugaredInterfaceCompanionClassNameResolver.cpp
diff --git a/test-app/runtime/src/main/cpp/Interop.cpp b/test-app/runtime/src/main/cpp/Interop.cpp
new file mode 100644
index 000000000..341cde99d
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/Interop.cpp
@@ -0,0 +1,216 @@
+#include "Interop.h"
+
+#include <string>
+
+#include "ArgConverter.h"
+#include "JniLocalRef.h"
+#include "NativeScriptException.h"
+#include "ObjectManager.h"
+#include "Runtime.h"
+#include "V8StringConstants.h"
+
+using namespace std;
+using namespace tns;
+using namespace v8;
+
+/*
+ * The brand is a per-isolate private symbol: invisible to JS property
+ * enumeration, so app code can neither observe nor forge it. Its value is the
+ * escape payload - `{nativeException}` when the branded error carries an
+ * original Java throwable, `{name, message, stack}` synthesis info otherwise
+ * (mirroring the iOS runtime's payload shape).
+ */
+static Local<Private> GetBrand(Isolate* isolate) {
+    return Private::ForApi(
+            isolate,
+            ArgConverter::ConvertToV8String(isolate, "tns::escapedExceptionPayload"));
+}
+
+/*
+ * Resolves the JS wrapper of a Java throwable carried by `value` - `value`
+ * itself when it wraps a java.lang.Throwable, or its `nativeException` when
+ * `value` is an Error carrying one. Empty handle otherwise.
+ */
+static Local<Value> GetWrappedJavaThrowable(Local<Context> context, Local<Value> value) {
+    auto isolate = context->GetIsolate();
+
+    auto isWrappedThrowable = [&](Local<Value> v) -> bool {
+        if (v.IsEmpty() || !v->IsObject()) {
+            return false;
+        }
+        auto objectManager = Runtime::GetObjectManager(isolate);
+        auto javaObj = objectManager->GetJavaObjectByJsObject(v.As<Object>());
+        if (javaObj.IsNull()) {
+            return false;
+        }
+        JEnv env;
+        JniLocalRef objClass(env.GetObjectClass(javaObj));
+        jclass throwableClass = env.FindClass("java/lang/Throwable");
+        return env.IsAssignableFrom(objClass, throwableClass) == JNI_TRUE;
+    };
+
+    if (isWrappedThrowable(value)) {
+        return value;
+    }
+    if (value->IsObject()) {
+        Local<Value> nativeExc;
+        if (value.As<Object>()
+                    ->Get(context, V8StringConstants::GetNativeException(isolate))
+                    .ToLocal(&nativeExc) &&
+            isWrappedThrowable(nativeExc)) {
+            return nativeExc;
+        }
+    }
+    return Local<Value>();
+}
+
+static void EscapeExceptionCallback(const FunctionCallbackInfo<Value>& info) {
+    auto isolate = info.GetIsolate();
+    auto context = isolate->GetCurrentContext();
+
+    if (info.Length() < 1) {
+        isolate->ThrowException(Exception::TypeError(ArgConverter::ConvertToV8String(
+                isolate,
+                "interop.escapeException requires 1 argument, but only 0 present.")));
+        return;
+    }
+
+    Local<Value> x = info[0];
+    Local<Private> brand = GetBrand(isolate);
+
+    // Idempotent: an already-branded value is returned unchanged.
+    if (x->IsObject() &&
+        x.As<Object>()->HasPrivate(context, brand).FromMaybe(false)) {
+        info.GetReturnValue().Set(x);
+        return;
+    }
+
+    // Derive the message string, preferring x.message when x is an Error.
+    string message;
+    bool xIsObject = x->IsObject();
+    Local<String> strVal;
+    if (xIsObject) {
+        Local<Value> msgVal;
+        if (x.As<Object>()
+                    ->Get(context, ArgConverter::ConvertToV8String(isolate, "message"))
+                    .ToLocal(&msgVal) &&
+            !msgVal->IsNullOrUndefined() && msgVal->ToString(context).ToLocal(&strVal)) {
+            message = ArgConverter::ConvertToString(strVal);
+        } else if (x->ToString(context).ToLocal(&strVal)) {
+            message = ArgConverter::ConvertToString(strVal);
+        }
+    } else if (x->ToString(context).ToLocal(&strVal)) {
+        message = ArgConverter::ConvertToString(strVal);
+    }
+
+    // The returned value is a real JS Error so `throw interop.escapeException(x)`
+    // behaves like a normal throw in pure-JS paths.
+    auto errObj = Exception::Error(ArgConverter::ConvertToV8String(isolate, message))
+                          .As<Object>();
+
+    // Copy stack from x when it is an Error carrying one.
+    string stack;
+    if (xIsObject) {
+        Local<Value> stackVal;
+        if (x.As<Object>()
+                    ->Get(context, V8StringConstants::GetStack(isolate))
+                    .ToLocal(&stackVal) &&
+            stackVal->IsString()) {
+            stack = ArgConverter::ConvertToString(stackVal.As<String>());
+            errObj->Set(context, V8StringConstants::GetStack(isolate), stackVal)
+                    .FromMaybe(false);
+        }
+    }
+
+    // Build the branded payload: the original Java throwable when x carries
+    // one, otherwise synthesis info (name/message/stack).
+    auto payload = Object::New(isolate);
+    Local<Value> nativeExc = GetWrappedJavaThrowable(context, x);
+    if (!nativeExc.IsEmpty()) {
+        payload->Set(context, V8StringConstants::GetNativeException(isolate), nativeExc)
+                .FromMaybe(false);
+    } else {
+        string name = "Error";
+        if (xIsObject) {
+            Local<Value> nameVal;
+            if (x.As<Object>()
+                        ->Get(context, ArgConverter::ConvertToV8String(isolate, "name"))
+                        .ToLocal(&nameVal) &&
+                nameVal->IsString()) {
+                name = ArgConverter::ConvertToString(nameVal.As<String>());
+            }
+        }
+        payload->Set(context, ArgConverter::ConvertToV8String(isolate, "name"),
+                     ArgConverter::ConvertToV8String(isolate, name))
+                .FromMaybe(false);
+        payload->Set(context, ArgConverter::ConvertToV8String(isolate, "message"),
+                     ArgConverter::ConvertToV8String(isolate, message))
+                .FromMaybe(false);
+        payload->Set(context, V8StringConstants::GetStack(isolate),
+                     ArgConverter::ConvertToV8String(isolate, stack))
+                .FromMaybe(false);
+    }
+
+    errObj->SetPrivate(context, brand, payload).FromMaybe(false);
+
+    info.GetReturnValue().Set(errObj);
+}
+
+void Interop::Init(Local<Context> context) {
+    auto isolate = context->GetIsolate();
+    auto global = context->Global();
+
+    auto interop = Object::New(isolate);
+
+    Local<Function> escapeException;
+    if (!Function::New(context, EscapeExceptionCallback).ToLocal(&escapeException)) {
+        throw NativeScriptException("Interop::Init: failed to create escapeException");
+    }
+
+    if (!interop->Set(context, ArgConverter::ConvertToV8String(isolate, "escapeException"),
+                      escapeException)
+                 .FromMaybe(false) ||
+        !global->Set(context, ArgConverter::ConvertToV8String(isolate, "interop"), interop)
+                 .FromMaybe(false)) {
+        throw NativeScriptException("Interop::Init: failed to install the interop global");
+    }
+}
+
+jthrowable Interop::ExtractEscapedJavaException(JEnv& env,
+                                                const Local<Object>& errObj) {
+    auto isolate = Isolate::GetCurrent();
+    auto context = isolate->GetCurrentContext();
+    if (context.IsEmpty()) {
+        return nullptr;
+    }
+
+    Local<Private> brand = GetBrand(isolate);
+    Local<Value> payload;
+    if (!errObj->HasPrivate(context, brand).FromMaybe(false) ||
+        !errObj->GetPrivate(context, brand).ToLocal(&payload) ||
+        !payload->IsObject()) {
+        return nullptr;
+    }
+
+    Local<Value> nativeExc;
+    if (!payload.As<Object>()
+                 ->Get(context, V8StringConstants::GetNativeException(isolate))
+                 .ToLocal(&nativeExc) ||
+        nativeExc.IsEmpty() || !nativeExc->IsObject()) {
+        return nullptr;
+    }
+
+    auto objectManager = Runtime::GetObjectManager(isolate);
+    auto javaObj = objectManager->GetJavaObjectByJsObject(nativeExc.As<Object>());
+    if (javaObj.IsNull()) {
+        return nullptr;
+    }
+
+    JniLocalRef objClass(env.GetObjectClass(javaObj));
+    jclass throwableClass = env.FindClass("java/lang/Throwable");
+    if (env.IsAssignableFrom(objClass, throwableClass) != JNI_TRUE) {
+        return nullptr;
+    }
+
+    return static_cast<jthrowable>(env.NewLocalRef(javaObj));
+}
diff --git a/test-app/runtime/src/main/cpp/Interop.h b/test-app/runtime/src/main/cpp/Interop.h
new file mode 100644
index 000000000..9c08dbd78
--- /dev/null
+++ b/test-app/runtime/src/main/cpp/Interop.h
@@ -0,0 +1,45 @@
+#ifndef INTEROP_H_
+#define INTEROP_H_
+
+#include "JEnv.h"
+#include "v8.h"
+
+namespace tns {
+
+/*
+ * The `interop` global, mirroring the iOS runtime's interop namespace. On
+ * Android it currently exposes a single member:
+ *
+ *   interop.escapeException(x)
+ *
+ * Brands an error so the JS->Java boundary (NativeScriptException::
+ * ReThrowToJava) forwards the ORIGINAL Java throwable carried by `x` (its
+ * `nativeException`, or `x` itself when it wraps a throwable) to the native
+ * caller unwrapped - so a Java `catch` of the concrete exception type still
+ * matches, instead of receiving a com.tns.NativeScriptException wrapper.
+ * A branded error with no underlying Java throwable keeps the default escape
+ * behavior (a com.tns.NativeScriptException carrying the JS message/stack).
+ * Branded escapes bypass discardUncaughtJsExceptions, which only handles
+ * com.tns.NativeScriptException.
+ */
+class Interop {
+public:
+    /*
+     * Installs the `interop` object on the global. Evaluated once per isolate
+     * during PrepareV8Runtime, for both the main and worker isolates.
+     */
+    static void Init(v8::Local<v8::Context> context);
+
+    /*
+     * Returns the original Java throwable carried by a branded
+     * interop.escapeException(...) error, as a new local reference the caller
+     * may env.Throw() directly, or nullptr when `errObj` is not branded or
+     * carries no Java throwable.
+     */
+    static jthrowable ExtractEscapedJavaException(JEnv& env,
+                                                  const v8::Local<v8::Object>& errObj);
+};
+
+}  // namespace tns
+
+#endif /* INTEROP_H_ */
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.cpp b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
index 1f10a4340..cb52ec248 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.cpp
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
@@ -5,6 +5,7 @@
 
 #include "ArgConverter.h"
 #include "ErrorEvents.h"
+#include "Interop.h"
 #include "LooperTasks.h"
 #include "NativeScriptAssert.h"
 #include "Runtime.h"
@@ -108,6 +109,16 @@ void NativeScriptException::ReThrowToJava() {
     auto isolate = Isolate::GetCurrent();
     auto errObj = Local<Value>::New(isolate, *m_javascriptException);
     if (errObj->IsObject()) {
+      // A branded interop.escapeException(...) throw carrying an original
+      // Java throwable: rethrow it unwrapped, so a native catch of its
+      // concrete type still matches (instead of receiving a
+      // com.tns.NativeScriptException wrapper).
+      jthrowable escaped =
+          Interop::ExtractEscapedJavaException(env, errObj.As<Object>());
+      if (escaped != nullptr) {
+        env.Throw(escaped);
+        return;
+      }
       auto exObj = TryGetJavaThrowableObject(env, errObj.As<Object>());
       ex = (jthrowable)exObj.Move();
     }
diff --git a/test-app/runtime/src/main/cpp/Runtime.cpp b/test-app/runtime/src/main/cpp/Runtime.cpp
index 1c4814c91..471a81fc4 100644
--- a/test-app/runtime/src/main/cpp/Runtime.cpp
+++ b/test-app/runtime/src/main/cpp/Runtime.cpp
@@ -17,6 +17,7 @@
 #include "ErrorEvents.h"
 #include "Events.h"
 #include "File.h"
+#include "Interop.h"
 #include "IsolateDisposer.h"
 #include "JsArgConverter.h"
 #include "JsArgToArrayConverter.h"
@@ -882,6 +883,9 @@ Isolate* Runtime::PrepareV8Runtime(const string& filesPath,
   Events::Init(context);
   ErrorEvents::Init(context);
 
+  // The `interop` global (interop.escapeException), mirroring iOS.
+  Interop::Init(context);
+
   m_objectManager->Init(isolate);
 
   m_module.Init(isolate, callingDir);

From f2ebdf5021fe436d0aa6ef4dbec82eaca164f764 Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 17:31:59 -0300
Subject: [PATCH 3/7] feat: carry the JS stack trace across escaped exceptions

Companion to the iOS runtime's JS-stack DX work on NativeScript/ios#409,
using the JVM primitive iOS doesn't have: Throwable.addSuppressed.

- New com.tns.JavaScriptStackTrace: a never-thrown Throwable carrying a
  JS stack, with StackTraceElements synthesized from the V8 frames (its
  own Java capture is suppressed). Attached generically via attach() so
  future exception paths can adopt it; SDK integrations read the raw
  stacks through getJavaScriptStack()/getEscapeSiteStack().
- Original-throwable escapes: the boundary attaches the carrier as a
  suppressed exception before rethrowing, so the JS journey renders
  automatically in printStackTrace(), logcat fatal logs and crash
  reporters ("Suppressed: com.tns.JavaScriptStackTrace: ...") while the
  original object's identity, class, stack and cause chain stay
  untouched. Idempotent: the same throwable escaping twice through
  nested overrides gets one carrier.
- Escape-site capture: escapeException() now records the stack of its
  own call site (the branded Error's natural V8 stack, grabbed before
  the origin stack overwrites it) alongside the origin stack. For
  non-Error values it is the only stack available and was previously
  lost.
- Synthesized escapes: the com.tns.NativeScriptException thrown for a
  branded error with no underlying Java throwable gets its stack trace
  replaced with the synthesized JS frames, so crash reporters group
  these by where they actually happened in JS instead of bucketing
  everything under the identical JNI boundary machinery.

Testing: 3 new specs (suppressed carrier contents + escape-site
accessor, duplicate-carrier guard across nested escapes, non-Error
escape-site fallback) plus JS-frame assertions on the synthesized path.
Full suite green on an API 35 arm64 emulator.
---
 .../assets/app/tests/testEscapeException.js   | 115 ++++++++++++
 test-app/runtime/src/main/cpp/Interop.cpp     | 164 +++++++++++++-----
 test-app/runtime/src/main/cpp/Interop.h       |  46 ++++-
 .../src/main/cpp/NativeScriptException.cpp    |  22 ++-
 .../java/com/tns/JavaScriptStackTrace.java    | 159 +++++++++++++++++
 5 files changed, 452 insertions(+), 54 deletions(-)
 create mode 100644 test-app/runtime/src/main/java/com/tns/JavaScriptStackTrace.java

diff --git a/test-app/app/src/main/assets/app/tests/testEscapeException.js b/test-app/app/src/main/assets/app/tests/testEscapeException.js
index edf18b412..c59109d60 100644
--- a/test-app/app/src/main/assets/app/tests/testEscapeException.js
+++ b/test-app/app/src/main/assets/app/tests/testEscapeException.js
@@ -59,6 +59,79 @@ describe("interop.escapeException", function () {
         expect(1 + 1).toBe(2);
     });
 
+    it("carries the JS trace on the original exception as a suppressed JavaScriptStackTrace", function () {
+        var caught = null;
+        try {
+            com.tns.tests.EscapeExceptionTest.throwIOException();
+        } catch (e) {
+            caught = e;
+        }
+
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw interop.escapeException(caught);
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        var suppressed = ret.getSuppressed();
+        expect(suppressed.length).toBe(1);
+        var carrier = suppressed[0];
+        expect(carrier.getClass().getName()).toBe("com.tns.JavaScriptStackTrace");
+
+        // The carrier renders the JS frames as real StackTraceElements
+        // pointing at this spec file.
+        var frames = carrier.getStackTrace();
+        expect(frames.length).toBeGreaterThan(0);
+        var sawThisFile = false;
+        for (var i = 0; i < frames.length; i++) {
+            var file = frames[i].getFileName();
+            if (file && file.indexOf("testEscapeException.js") !== -1) {
+                sawThisFile = true;
+                break;
+            }
+        }
+        expect(sawThisFile).toBe(true);
+
+        // The escape call site is recorded too, for SDK integrations.
+        expect(carrier.getEscapeSiteStack()).toContain("testEscapeException.js");
+    });
+
+    it("does not stack duplicate carriers when the same throwable escapes twice", function () {
+        var caught = null;
+        try {
+            com.tns.tests.EscapeExceptionTest.throwIOException();
+        } catch (e) {
+            caught = e;
+        }
+
+        var escapeOnce = new java.lang.Runnable({
+            run: function () {
+                throw interop.escapeException(caught);
+            }
+        });
+        var first = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(escapeOnce);
+        expect(first.getSuppressed().length).toBe(1);
+
+        // Re-escape the SAME original throwable (re-caught and re-forwarded,
+        // as through nested overrides).
+        var reCaught = null;
+        try {
+            throw interop.escapeException(caught);
+        } catch (e) {
+            reCaught = e;
+        }
+        var escapeAgain = new java.lang.Runnable({
+            run: function () {
+                throw reCaught;
+            }
+        });
+        var second = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(escapeAgain);
+
+        expect(second.equals(first)).toBe(true);
+        expect(second.getSuppressed().length).toBe(1);
+    });
+
     it("an unbranded rethrow keeps today's wrapping semantics", function () {
         var caught = null;
         try {
@@ -96,5 +169,47 @@ describe("interop.escapeException", function () {
         expect(ret).not.toBeNull();
         expect(ret.getClass().getName()).toBe("com.tns.NativeScriptException");
         expect(ret.getMessage()).toContain("plain-escape");
+
+        // Its Java stack is replaced with frames synthesized from the JS
+        // stack, so crash reporters group by where it actually happened
+        // instead of the (identical) JNI boundary machinery.
+        var frames = ret.getStackTrace();
+        expect(frames.length).toBeGreaterThan(0);
+        var sawThisFile = false;
+        for (var i = 0; i < frames.length; i++) {
+            var file = frames[i].getFileName();
+            if (file && file.indexOf("testEscapeException.js") !== -1) {
+                sawThisFile = true;
+                break;
+            }
+        }
+        expect(sawThisFile).toBe(true);
+    });
+
+    it("a non-Error escape carries the escape-site stack", function () {
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw interop.escapeException("boom-string");
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("com.tns.NativeScriptException");
+        expect(ret.getMessage()).toContain("boom-string");
+
+        // A string has no stack of its own, so the escapeException() call
+        // site - the only stack available - provides the frames.
+        var frames = ret.getStackTrace();
+        expect(frames.length).toBeGreaterThan(0);
+        var sawThisFile = false;
+        for (var i = 0; i < frames.length; i++) {
+            var file = frames[i].getFileName();
+            if (file && file.indexOf("testEscapeException.js") !== -1) {
+                sawThisFile = true;
+                break;
+            }
+        }
+        expect(sawThisFile).toBe(true);
     });
 });
diff --git a/test-app/runtime/src/main/cpp/Interop.cpp b/test-app/runtime/src/main/cpp/Interop.cpp
index 341cde99d..cedd7e190 100644
--- a/test-app/runtime/src/main/cpp/Interop.cpp
+++ b/test-app/runtime/src/main/cpp/Interop.cpp
@@ -108,6 +108,19 @@ static void EscapeExceptionCallback(const FunctionCallbackInfo<Value>& info) {
     auto errObj = Exception::Error(ArgConverter::ConvertToV8String(isolate, message))
                           .As<Object>();
 
+    // The freshly-created Error's own stack IS the escapeException() call
+    // site - capture it before the origin stack overwrites it below. It is
+    // the only stack available for non-Error values, and often the more
+    // useful frame when debugging where an error was forwarded from.
+    string escapeSiteStack;
+    {
+        Local<Value> ownStack;
+        if (errObj->Get(context, V8StringConstants::GetStack(isolate)).ToLocal(&ownStack) &&
+            ownStack->IsString()) {
+            escapeSiteStack = ArgConverter::ConvertToString(ownStack.As<String>());
+        }
+    }
+
     // Copy stack from x when it is an Error carrying one.
     string stack;
     if (xIsObject) {
@@ -122,33 +135,37 @@ static void EscapeExceptionCallback(const FunctionCallbackInfo<Value>& info) {
         }
     }
 
-    // Build the branded payload: the original Java throwable when x carries
-    // one, otherwise synthesis info (name/message/stack).
+    string name = "Error";
+    if (xIsObject) {
+        Local<Value> nameVal;
+        if (x.As<Object>()
+                    ->Get(context, ArgConverter::ConvertToV8String(isolate, "name"))
+                    .ToLocal(&nameVal) &&
+            nameVal->IsString()) {
+            name = ArgConverter::ConvertToString(nameVal.As<String>());
+        }
+    }
+
+    // Build the branded payload: name/message and both stacks always (so the
+    // boundary can carry the JS journey over to Java), plus the original Java
+    // throwable when x carries one.
     auto payload = Object::New(isolate);
+    payload->Set(context, ArgConverter::ConvertToV8String(isolate, "name"),
+                 ArgConverter::ConvertToV8String(isolate, name))
+            .FromMaybe(false);
+    payload->Set(context, ArgConverter::ConvertToV8String(isolate, "message"),
+                 ArgConverter::ConvertToV8String(isolate, message))
+            .FromMaybe(false);
+    payload->Set(context, V8StringConstants::GetStack(isolate),
+                 ArgConverter::ConvertToV8String(isolate, stack))
+            .FromMaybe(false);
+    payload->Set(context, ArgConverter::ConvertToV8String(isolate, "escapeSiteStack"),
+                 ArgConverter::ConvertToV8String(isolate, escapeSiteStack))
+            .FromMaybe(false);
     Local<Value> nativeExc = GetWrappedJavaThrowable(context, x);
     if (!nativeExc.IsEmpty()) {
         payload->Set(context, V8StringConstants::GetNativeException(isolate), nativeExc)
                 .FromMaybe(false);
-    } else {
-        string name = "Error";
-        if (xIsObject) {
-            Local<Value> nameVal;
-            if (x.As<Object>()
-                        ->Get(context, ArgConverter::ConvertToV8String(isolate, "name"))
-                        .ToLocal(&nameVal) &&
-                nameVal->IsString()) {
-                name = ArgConverter::ConvertToString(nameVal.As<String>());
-            }
-        }
-        payload->Set(context, ArgConverter::ConvertToV8String(isolate, "name"),
-                     ArgConverter::ConvertToV8String(isolate, name))
-                .FromMaybe(false);
-        payload->Set(context, ArgConverter::ConvertToV8String(isolate, "message"),
-                     ArgConverter::ConvertToV8String(isolate, message))
-                .FromMaybe(false);
-        payload->Set(context, V8StringConstants::GetStack(isolate),
-                     ArgConverter::ConvertToV8String(isolate, stack))
-                .FromMaybe(false);
     }
 
     errObj->SetPrivate(context, brand, payload).FromMaybe(false);
@@ -176,41 +193,102 @@ void Interop::Init(Local<Context> context) {
     }
 }
 
-jthrowable Interop::ExtractEscapedJavaException(JEnv& env,
-                                                const Local<Object>& errObj) {
+static string GetPayloadString(Local<Context> context, Local<Object> payload,
+                               Local<v8::String> key) {
+    Local<Value> val;
+    if (payload->Get(context, key).ToLocal(&val) && val->IsString()) {
+        return ArgConverter::ConvertToString(val.As<String>());
+    }
+    return "";
+}
+
+bool Interop::GetEscapedExceptionInfo(JEnv& env, const Local<Object>& errObj,
+                                      EscapedExceptionInfo& out) {
     auto isolate = Isolate::GetCurrent();
     auto context = isolate->GetCurrentContext();
     if (context.IsEmpty()) {
-        return nullptr;
+        return false;
     }
 
     Local<Private> brand = GetBrand(isolate);
-    Local<Value> payload;
+    Local<Value> payloadVal;
     if (!errObj->HasPrivate(context, brand).FromMaybe(false) ||
-        !errObj->GetPrivate(context, brand).ToLocal(&payload) ||
-        !payload->IsObject()) {
-        return nullptr;
+        !errObj->GetPrivate(context, brand).ToLocal(&payloadVal) ||
+        !payloadVal->IsObject()) {
+        return false;
     }
+    auto payload = payloadVal.As<Object>();
+
+    out.branded = true;
+    out.name = GetPayloadString(context, payload,
+                                ArgConverter::ConvertToV8String(isolate, "name"));
+    out.message = GetPayloadString(context, payload,
+                                   ArgConverter::ConvertToV8String(isolate, "message"));
+    out.stack = GetPayloadString(context, payload, V8StringConstants::GetStack(isolate));
+    out.escapeSiteStack = GetPayloadString(
+            context, payload, ArgConverter::ConvertToV8String(isolate, "escapeSiteStack"));
 
     Local<Value> nativeExc;
-    if (!payload.As<Object>()
-                 ->Get(context, V8StringConstants::GetNativeException(isolate))
-                 .ToLocal(&nativeExc) ||
-        nativeExc.IsEmpty() || !nativeExc->IsObject()) {
-        return nullptr;
+    if (payload->Get(context, V8StringConstants::GetNativeException(isolate))
+                 .ToLocal(&nativeExc) &&
+        !nativeExc.IsEmpty() && nativeExc->IsObject()) {
+        auto objectManager = Runtime::GetObjectManager(isolate);
+        auto javaObj = objectManager->GetJavaObjectByJsObject(nativeExc.As<Object>());
+        if (!javaObj.IsNull()) {
+            JniLocalRef objClass(env.GetObjectClass(javaObj));
+            jclass throwableClass = env.FindClass("java/lang/Throwable");
+            if (env.IsAssignableFrom(objClass, throwableClass) == JNI_TRUE) {
+                out.original = static_cast<jthrowable>(env.NewLocalRef(javaObj));
+            }
+        }
     }
 
-    auto objectManager = Runtime::GetObjectManager(isolate);
-    auto javaObj = objectManager->GetJavaObjectByJsObject(nativeExc.As<Object>());
-    if (javaObj.IsNull()) {
-        return nullptr;
+    return true;
+}
+
+/*
+ * com.tns.JavaScriptStackTrace bridge. JEnv::FindClass returns cached global
+ * refs, so the jclass/jmethodIDs are safe to keep in statics (resolved once,
+ * on the first escape that needs them).
+ */
+static jclass GetCarrierClass(JEnv& env) {
+    static jclass clazz = env.FindClass("com/tns/JavaScriptStackTrace");
+    return clazz;
+}
+
+void Interop::AttachJavaScriptStackTrace(JEnv& env, jthrowable target,
+                                         const EscapedExceptionInfo& info) {
+    if (target == nullptr) {
+        return;
     }
+    jclass carrierClass = GetCarrierClass(env);
+    static jmethodID attachMethod = env.GetStaticMethodID(
+            carrierClass, "attach",
+            "(Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V");
 
-    JniLocalRef objClass(env.GetObjectClass(javaObj));
-    jclass throwableClass = env.FindClass("java/lang/Throwable");
-    if (env.IsAssignableFrom(objClass, throwableClass) != JNI_TRUE) {
-        return nullptr;
+    string header = info.name.empty()
+                            ? info.message
+                            : (info.message.empty() ? info.name
+                                                    : info.name + ": " + info.message);
+    JniLocalRef headerRef(env.NewStringUTF(header.c_str()));
+    JniLocalRef stackRef(env.NewStringUTF(info.stack.c_str()));
+    JniLocalRef escapeRef(env.NewStringUTF(info.escapeSiteStack.c_str()));
+    env.CallStaticVoidMethod(carrierClass, attachMethod, target, (jstring) headerRef,
+                             (jstring) stackRef, (jstring) escapeRef);
+}
+
+void Interop::ApplyJavaScriptFrames(JEnv& env, jthrowable target,
+                                    const EscapedExceptionInfo& info) {
+    if (target == nullptr) {
+        return;
     }
+    jclass carrierClass = GetCarrierClass(env);
+    static jmethodID applyMethod = env.GetStaticMethodID(
+            carrierClass, "applyFrames",
+            "(Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V");
 
-    return static_cast<jthrowable>(env.NewLocalRef(javaObj));
+    JniLocalRef stackRef(env.NewStringUTF(info.stack.c_str()));
+    JniLocalRef escapeRef(env.NewStringUTF(info.escapeSiteStack.c_str()));
+    env.CallStaticVoidMethod(carrierClass, applyMethod, target, (jstring) stackRef,
+                             (jstring) escapeRef);
 }
diff --git a/test-app/runtime/src/main/cpp/Interop.h b/test-app/runtime/src/main/cpp/Interop.h
index 9c08dbd78..b5dec0310 100644
--- a/test-app/runtime/src/main/cpp/Interop.h
+++ b/test-app/runtime/src/main/cpp/Interop.h
@@ -24,6 +24,23 @@ namespace tns {
  */
 class Interop {
 public:
+    /*
+     * The brand payload of an interop.escapeException(...) error, decoded at
+     * the JS->Java boundary. `original` (a new local reference the caller may
+     * env.Throw() directly) is nullptr for a branded error that carries no
+     * Java throwable - the synthesized-escape case.
+     */
+    struct EscapedExceptionInfo {
+        bool branded = false;
+        jthrowable original = nullptr;
+        std::string name;
+        std::string message;
+        /* The JS stack of the escaped error itself (may be empty). */
+        std::string stack;
+        /* The JS stack of the interop.escapeException(...) call site. */
+        std::string escapeSiteStack;
+    };
+
     /*
      * Installs the `interop` object on the global. Evaluated once per isolate
      * during PrepareV8Runtime, for both the main and worker isolates.
@@ -31,13 +48,30 @@ class Interop {
     static void Init(v8::Local<v8::Context> context);
 
     /*
-     * Returns the original Java throwable carried by a branded
-     * interop.escapeException(...) error, as a new local reference the caller
-     * may env.Throw() directly, or nullptr when `errObj` is not branded or
-     * carries no Java throwable.
+     * Decodes the brand payload of `errObj` into `out`. Returns true when the
+     * object is branded.
+     */
+    static bool GetEscapedExceptionInfo(JEnv& env,
+                                        const v8::Local<v8::Object>& errObj,
+                                        EscapedExceptionInfo& out);
+
+    /*
+     * Attaches a com.tns.JavaScriptStackTrace carrier to `target` as a
+     * suppressed exception, so the JS journey of an escaped original Java
+     * throwable renders in stack dumps and crash reports. Idempotent (the
+     * Java side skips duplicates).
+     */
+    static void AttachJavaScriptStackTrace(JEnv& env, jthrowable target,
+                                           const EscapedExceptionInfo& info);
+
+    /*
+     * Replaces `target`'s stack trace with frames synthesized from the JS
+     * stack (com.tns.JavaScriptStackTrace.applyFrames), so JS-originated
+     * escapes group by their actual JS frames in crash reporters. Only used
+     * on throwables the runtime itself constructs.
      */
-    static jthrowable ExtractEscapedJavaException(JEnv& env,
-                                                  const v8::Local<v8::Object>& errObj);
+    static void ApplyJavaScriptFrames(JEnv& env, jthrowable target,
+                                      const EscapedExceptionInfo& info);
 };
 
 }  // namespace tns
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.cpp b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
index cb52ec248..4daa46d98 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.cpp
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
@@ -108,15 +108,19 @@ void NativeScriptException::ReThrowToJava() {
      */
     auto isolate = Isolate::GetCurrent();
     auto errObj = Local<Value>::New(isolate, *m_javascriptException);
+    Interop::EscapedExceptionInfo escapeInfo;
     if (errObj->IsObject()) {
+      Interop::GetEscapedExceptionInfo(env, errObj.As<Object>(), escapeInfo);
       // A branded interop.escapeException(...) throw carrying an original
       // Java throwable: rethrow it unwrapped, so a native catch of its
       // concrete type still matches (instead of receiving a
-      // com.tns.NativeScriptException wrapper).
-      jthrowable escaped =
-          Interop::ExtractEscapedJavaException(env, errObj.As<Object>());
-      if (escaped != nullptr) {
-        env.Throw(escaped);
+      // com.tns.NativeScriptException wrapper). The JS journey rides along as
+      // a suppressed com.tns.JavaScriptStackTrace, which stack dumps and
+      // crash reporters render automatically.
+      if (escapeInfo.original != nullptr) {
+        Interop::AttachJavaScriptStackTrace(env, escapeInfo.original,
+                                            escapeInfo);
+        env.Throw(escapeInfo.original);
         return;
       }
       auto exObj = TryGetJavaThrowableObject(env, errObj.As<Object>());
@@ -140,6 +144,14 @@ void NativeScriptException::ReThrowToJava() {
                           (jstring)stackTrace, ex));
       }
     }
+
+    // A branded escape with no underlying Java throwable takes the default
+    // NativeScriptException shape, but its Java stack is the (identical) JNI
+    // boundary machinery - replace it with frames synthesized from the JS
+    // stack so crash reporters group these by where they actually happened.
+    if (escapeInfo.branded && ex != nullptr) {
+      Interop::ApplyJavaScriptFrames(env, ex, escapeInfo);
+    }
   } else if (!m_message.empty()) {
     JniLocalRef msg(env.NewStringUTF(m_message.c_str()));
     JniLocalRef stackTrace(env.NewStringUTF(m_stackTrace.c_str()));
diff --git a/test-app/runtime/src/main/java/com/tns/JavaScriptStackTrace.java b/test-app/runtime/src/main/java/com/tns/JavaScriptStackTrace.java
new file mode 100644
index 000000000..8e5177c85
--- /dev/null
+++ b/test-app/runtime/src/main/java/com/tns/JavaScriptStackTrace.java
@@ -0,0 +1,159 @@
+package com.tns;
+
+import java.util.ArrayList;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Carries a JavaScript stack trace on a Java exception. Never thrown - it is
+ * attached via {@link Throwable#addSuppressed} so the JS frames render
+ * automatically in stack dumps and crash reporters ("Suppressed: ..."), with
+ * the frames synthesized as real {@link StackTraceElement}s.
+ *
+ * Currently attached by the runtime when a JS error branded with
+ * {@code interop.escapeException} forwards an original Java throwable to a
+ * native caller; the API is intentionally generic so other exception paths can
+ * adopt it. Crash-SDK integrations can look the carrier up via
+ * {@link Throwable#getSuppressed} and read the raw stacks through
+ * {@link #getJavaScriptStack()} / {@link #getEscapeSiteStack()}.
+ */
+public final class JavaScriptStackTrace extends Throwable {
+    private static final long serialVersionUID = 1L;
+
+    private final String javaScriptStack;
+    private final String escapeSiteStack;
+
+    private JavaScriptStackTrace(String message, String javaScriptStack, String escapeSiteStack) {
+        super(message);
+        this.javaScriptStack = javaScriptStack;
+        this.escapeSiteStack = escapeSiteStack;
+    }
+
+    /**
+     * The JS stack of the error itself (where it was created/thrown), as the
+     * raw V8-formatted string. May be empty when the escaped value carried no
+     * stack (e.g. a non-Error value).
+     */
+    public String getJavaScriptStack() {
+        return javaScriptStack;
+    }
+
+    /**
+     * The JS stack of the {@code interop.escapeException(...)} call site, as
+     * the raw V8-formatted string.
+     */
+    public String getEscapeSiteStack() {
+        return escapeSiteStack;
+    }
+
+    /**
+     * The carrier's own Java capture point is machinery noise - its stack is
+     * replaced with the synthesized JS frames, so skip the capture entirely.
+     */
+    @Override
+    public synchronized Throwable fillInStackTrace() {
+        return this;
+    }
+
+    /**
+     * Attaches a carrier to {@code target} as a suppressed exception. The
+     * rendered frames come from {@code javaScriptStack}, falling back to
+     * {@code escapeSiteStack} when the error carried no stack of its own.
+     * Idempotent: a target already carrying an identical stack is left
+     * unchanged (e.g. the same throwable escaping twice through nested
+     * overrides). No-ops when suppression is disabled on the target.
+     */
+    @RuntimeCallable
+    public static void attach(Throwable target, String message, String javaScriptStack, String escapeSiteStack) {
+        if (target == null) {
+            return;
+        }
+        String stackToRender = (javaScriptStack != null && !javaScriptStack.isEmpty())
+                               ? javaScriptStack
+                               : escapeSiteStack;
+        if (stackToRender == null || stackToRender.isEmpty()) {
+            return;
+        }
+        for (Throwable suppressed : target.getSuppressed()) {
+            if (suppressed instanceof JavaScriptStackTrace &&
+                    stackToRender.equals(((JavaScriptStackTrace) suppressed).renderedStack())) {
+                return;
+            }
+        }
+        JavaScriptStackTrace carrier = new JavaScriptStackTrace(message, javaScriptStack, escapeSiteStack);
+        carrier.setStackTrace(parseFrames(stackToRender));
+        target.addSuppressed(carrier);
+    }
+
+    /**
+     * Replaces {@code target}'s stack trace with frames synthesized from the
+     * JS stack, so crash reporters group JS-originated exceptions by their
+     * actual JS frames instead of the (identical) JNI boundary machinery.
+     * Only ever called on throwables the runtime itself constructs.
+     */
+    @RuntimeCallable
+    public static void applyFrames(Throwable target, String javaScriptStack, String escapeSiteStack) {
+        if (target == null) {
+            return;
+        }
+        String stackToRender = (javaScriptStack != null && !javaScriptStack.isEmpty())
+                               ? javaScriptStack
+                               : escapeSiteStack;
+        if (stackToRender == null || stackToRender.isEmpty()) {
+            return;
+        }
+        StackTraceElement[] frames = parseFrames(stackToRender);
+        if (frames.length > 0) {
+            target.setStackTrace(frames);
+        }
+    }
+
+    private String renderedStack() {
+        return (javaScriptStack != null && !javaScriptStack.isEmpty()) ? javaScriptStack : escapeSiteStack;
+    }
+
+    /*
+     * Both V8's standard format ("    at fn (file:line:col)", "    at
+     * file:line:col") and the runtime's own GetErrorStackTrace format
+     * ("fn(file:line:col)") end each frame with "(file:line:col)" or
+     * "file:line:col". A line that matches neither still becomes a frame
+     * (with the raw text as the method name) so no information is dropped.
+     */
+    private static final Pattern FRAME_TAIL =
+            Pattern.compile("^(?:\\s*at\\s+)?(?:(.*?)\\s*\\()?\\s*(\\S+?):(\\d+)(?::\\d+)?\\)?\\s*$");
+
+    private static StackTraceElement[] parseFrames(String stack) {
+        ArrayList<StackTraceElement> frames = new ArrayList<StackTraceElement>();
+        for (String line : stack.split("\n")) {
+            String trimmed = line.trim();
+            if (trimmed.isEmpty()) {
+                continue;
+            }
+            Matcher m = FRAME_TAIL.matcher(trimmed);
+            if (!m.matches()) {
+                // Leading unparseable lines are the "Error: message" heading
+                // of a standard V8 stack; later ones are kept as raw frames
+                // so no information is dropped.
+                if (!frames.isEmpty()) {
+                    frames.add(new StackTraceElement("<js>", trimmed, null, -1));
+                }
+                continue;
+            }
+            String fn = m.group(1);
+            if (fn == null || fn.isEmpty()) {
+                fn = "<anonymous>";
+            } else if (fn.startsWith("at ")) {
+                fn = fn.substring(3).trim();
+            }
+            String file = m.group(2);
+            int lineNumber;
+            try {
+                lineNumber = Integer.parseInt(m.group(3));
+            } catch (NumberFormatException e) {
+                lineNumber = -1;
+            }
+            frames.add(new StackTraceElement("<js>", fn, file, lineNumber));
+        }
+        return frames.toArray(new StackTraceElement[0]);
+    }
+}

From a189cb41368c342679568b1dd0574c8444f2b899 Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 17:47:28 -0300
Subject: [PATCH 4/7] docs: add error handling documentation

Documents the web-compliant error model: global error/unhandledrejection/
rejectionhandled events and reportError, Java exception round-tripping
(error.nativeException), interop.escapeException and the
com.tns.JavaScriptStackTrace carrier, configuration flags with the
terminal-path decision table, and crash-reporter integration on both the
JS and Java sides. Adds a docs/ index and links it from the README,
mirroring the docs added on the iOS PR (NativeScript/ios#409).
---
 README.md              |   5 +
 docs/README.md         |   4 +
 docs/error-handling.md | 202 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 211 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/error-handling.md

diff --git a/README.md b/README.md
index b41749a16..e4170a6f6 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ Contains the source code for the NativeScript's Android Runtime. [NativeScript](
 - [Build Prerequisites](#build-prerequisites)
 - [How to build](#how-to-build)
 - [How to run tests](#how-to-run-tests)
+- [Documentation](#documentation)
 - [Misc](#misc)
 - [Get Help](#get-help)
 
@@ -124,6 +125,10 @@ npx ns debug android --start
 We love PRs! Check out the [contributing guidelines](CONTRIBUTING.md). If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/android-runtime/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
 
 
+## Documentation
+
+Runtime feature documentation lives in the [docs](docs/README.md) folder — see [Error handling](docs/error-handling.md) for the global error events, Java exception round-tripping and `interop.escapeException`.
+
 ## Misc
 
 * [Implementing additional Chrome DevTools protocol Domains](docs/extending-inspector.md)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..761f8d702
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,4 @@
+# Runtime documentation
+
+- [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.
+- [Implementing additional Chrome DevTools protocol Domains](extending-inspector.md)
diff --git a/docs/error-handling.md b/docs/error-handling.md
new file mode 100644
index 000000000..4be910887
--- /dev/null
+++ b/docs/error-handling.md
@@ -0,0 +1,202 @@
+# Error handling
+
+The runtime implements the WHATWG error model at the global level: uncaught JavaScript exceptions and unhandled promise rejections are dispatched as cancelable events on `globalThis`, Java exceptions round-trip into JavaScript with the original `Throwable` attached, and `interop.escapeException` forwards a JavaScript throw to the Java caller as the **original** Java exception. Unlike iOS, a truly-uncaught exception crashes the app by default (the Java default uncaught-exception handler ends the process) — `preventDefault()` and `discardUncaughtJsExceptions` are the opt-outs. Unhandled rejections and `reportError` only report; they never crash.
+
+## Quick reference
+
+| Situation | Default behavior |
+|---|---|
+| Uncaught JS exception during a Java→JS call (overridden method, interface implementation) | Becomes a real `com.tns.NativeScriptException` thrown to the Java caller. If nothing catches it, the thread's uncaught-exception handler reports it (cancelable `error` event → `__onUncaughtError` hook → error activity in debug builds) and the process exits — unless a listener called `preventDefault()`. |
+| Unhandled promise rejection | Tracked per isolate, reported once per looper turn: cancelable `unhandledrejection` event → `__onUncaughtError` hook, logcat entry prefixed `Unhandled promise rejection:`. The app keeps running. |
+| `.catch()` added after the report | `rejectionhandled` event (non-cancelable), carrying the original reason. |
+| Java exception during a JS→Java call | Surfaced to JS as an `Error` carrying the original as `error.nativeException`. |
+| `throw interop.escapeException(x)` in JS called from Java | The original Java `Throwable` carried by `x` is rethrown **unwrapped** to the Java caller (JS trace attached as a suppressed `com.tns.JavaScriptStackTrace`); with no underlying `Throwable`, a `com.tns.NativeScriptException` whose stack trace is the JS frames. |
+| `reportError(x)` | Routed through the same pipeline as an uncaught error; never crashes. |
+
+## JavaScript API
+
+### Global error events
+
+```js
+globalThis.addEventListener("error", (e) => {
+  // e is an ErrorEvent: { message, error, filename, lineno, colno }
+  // (filename/lineno/colno are not populated yet)
+  console.log(e.message, e.error);
+  e.preventDefault(); // marks the error handled: no hook, no crash, no error activity
+});
+
+globalThis.addEventListener("unhandledrejection", (e) => {
+  // e is a PromiseRejectionEvent: { promise, reason }
+  console.log(e.reason);
+  e.preventDefault();
+});
+
+globalThis.addEventListener("rejectionhandled", (e) => {
+  // fired (as a task, on a following looper turn) when a handler is attached
+  // to a promise whose rejection was already reported; carries the original
+  // reason. Not cancelable.
+});
+```
+
+Notes:
+
+- `error` and `unhandledrejection` are `cancelable`; `preventDefault()` suppresses every downstream consequence (legacy hooks, logcat report, the error activity, the process crash).
+- Events fire even if app code overwrites `globalThis.dispatchEvent` — native dispatch goes through closures captured at startup.
+- A listener that throws does not stop the remaining listeners; the thrown value is routed to the fatal reporting tail directly (never recursively dispatched as another `error` event).
+- The events also fire on worker globals. A worker's unhandled rejection dispatches `unhandledrejection` on the worker's own global first; only when unprevented does it continue to the worker-global `onerror` and then to the parent's `worker.onerror`, mirroring uncaught worker errors.
+
+### `reportError`
+
+Routes a caught-but-fatal error through the exact same pipeline as an uncaught exception:
+
+```js
+reportError(new Error("something unrecoverable"));
+```
+
+### Event classes
+
+`Event`, `EventTarget`, `ErrorEvent` and `PromiseRejectionEvent` are installed as global constructors. `Event`/`EventTarget` are general-purpose (registration order, `once`/`capture` options, `stopImmediatePropagation`, `handleEvent` objects) and usable for your own eventing:
+
+```js
+const target = new EventTarget();
+target.addEventListener("tick", (e) => { /* ... */ }, { once: true });
+target.dispatchEvent(new Event("tick")); // returns !defaultPrevented
+```
+
+### What lands on the events
+
+The stacks live on the error/reason **value**, not on the event — and the thrown value can be anything, so shape-check before use:
+
+| You wrote | `e.error` / `e.reason` is | JS stack | Native exception |
+|---|---|---|---|
+| `throw new Error("x")` | that `Error` | `e.error.stack` | — |
+| called a Java method that threw, without try/catch | an `Error` with `message` from the Java exception's message | `e.error.stack` (the JS call site); `e.error.stackTrace` combines it with the Java frames | `e.error.nativeException` — the original `Throwable` (call `.getClass()`, `.getMessage()`, `.getCause()`, ... on it) |
+
+### Catching native exceptions
+
+```js
+try {
+  someJavaObject.methodThatThrowsIOException();
+} catch (e) {
+  e.nativeException instanceof java.io.IOException; // true
+  e.nativeException.getMessage();                   // the Java message
+  e.stackTrace;                                     // combined JS + Java stack as a string
+}
+```
+
+### Forwarding a throw to native: `interop.escapeException`
+
+A plain JS throw inside a Java-invoked callback already escapes to the Java caller — as a `com.tns.NativeScriptException`. That is the right default, but when the caller is waiting for a *concrete* exception type, the wrapper doesn't match its `catch`. Branding the throw forwards the **original** Java exception instead:
+
+```js
+const listener = new some.api.Listener({
+  onEvent() {
+    try {
+      riskyJavaCall(); // throws java.io.IOException
+    } catch (e) {
+      throw interop.escapeException(e); // the Java caller catches the ORIGINAL IOException
+    }
+  },
+});
+```
+
+Semantics:
+
+- `escapeException(err)` returns a JS `Error` (message/stack copied), so it behaves like a normal throw in pure-JS paths; the brand is an isolate-private symbol that user code cannot forge. Passing an already-branded value is a no-op; calling with no argument throws `TypeError`.
+- If `err` is (or carries via `.nativeException`) a Java `Throwable`, the **original object** is rethrown at the boundary — a Java `catch (IOException e)` above the caller matches, and `Throwable` identity is preserved (same object, untouched class/stack/cause chain). The JS journey rides along as a suppressed `com.tns.JavaScriptStackTrace` (see the native section).
+- Otherwise a `com.tns.NativeScriptException` is thrown as usual, but with its stack trace replaced by frames synthesized from the JS stack, so crash reporters group it by where it actually happened in JS.
+- The `escapeException()` call site's stack is recorded too — for non-Error values (`escapeException("boom")`) it is the only stack available.
+- Branded escapes bypass `discardUncaughtJsExceptions` (an explicit forward request must reach the caller).
+
+## Native (Java) API
+
+### Catching escaped exceptions
+
+```java
+try {
+    listener.onEvent(); // implemented in JS
+} catch (java.io.IOException e) {
+    // For rethrown originals: e is the very same object the JS code caught.
+    // For synthesized escapes: catch com.tns.NativeScriptException instead -
+    // its message is the JS error's message and its stack trace is the JS frames.
+}
+```
+
+### JS stack traces on Java exceptions: `com.tns.JavaScriptStackTrace`
+
+An escaped original exception carries its JavaScript journey as a suppressed throwable, so it renders automatically in `printStackTrace()`, logcat fatal logs and crash reporters:
+
+```
+java.io.IOException: original-io-exception
+    at com.example.SomeApi.riskyJavaCall(SomeApi.java:42)
+    ...
+    Suppressed: com.tns.JavaScriptStackTrace: Error: original-io-exception
+        at <js>.onEvent(main-view-model.js:17)
+        ...
+```
+
+`JavaScriptStackTrace` is never thrown — only attached — and its stack trace elements are synthesized from the V8 frames. Crash-SDK integrations can look it up and read the raw stacks:
+
+```java
+for (Throwable suppressed : caught.getSuppressed()) {
+    if (suppressed instanceof com.tns.JavaScriptStackTrace) {
+        com.tns.JavaScriptStackTrace jsTrace = (com.tns.JavaScriptStackTrace) suppressed;
+        String originStack = jsTrace.getJavaScriptStack();   // where the JS error was created
+        String escapeStack = jsTrace.getEscapeSiteStack();   // where interop.escapeException() was called
+    }
+}
+```
+
+| Exception | Where the JS stack lives |
+|---|---|
+| Rethrown original `Throwable` | suppressed `com.tns.JavaScriptStackTrace` (identity, stack and cause chain of the original are untouched) |
+| Synthesized escape (`com.tns.NativeScriptException`) | the exception's own stack trace elements are the JS frames; the message is the JS error's message |
+
+`JavaScriptStackTrace` and its two accessors are the stable contract for crash-SDK integrations; other exception paths may adopt the carrier in the future.
+
+## Configuration
+
+| Flag (app `package.json`, default off) | Effect |
+|---|---|
+| `discardUncaughtJsExceptions` | JS exceptions escaping an overridden-method call are swallowed on the Java side and reported through `__onDiscardedError` instead of crashing the app. Branded `interop.escapeException` throws bypass it. |
+
+There is no `crashOnUncaughtJsExceptions` flag (unlike iOS): crashing on truly-uncaught exceptions is already Android's default.
+
+Terminal-path decision table:
+
+| Condition | legacy hook called | process crash |
+|---|---|---|
+| uncaught exception, default | `__onUncaughtError` | yes |
+| uncaught exception, `discardUncaughtJsExceptions` | `__onDiscardedError` | no |
+| uncaught exception, listener called `preventDefault()` | none | no |
+| unhandled rejection / `reportError`, unprevented | `__onUncaughtError` | no |
+| unhandled rejection / `reportError`, `preventDefault()` | none | no |
+
+## Crash reporter integration
+
+JS side — attach both the JS and native exception from one listener:
+
+```js
+globalThis.addEventListener("error", (e) => {
+  const err = e.error;
+  const native = err && err.nativeException;
+  crashReporter.capture(err instanceof Error ? err : new Error(e.message), {
+    nativeClass: native ? native.getClass().getName() : undefined,
+    nativeMessage: native ? native.getMessage() : undefined,
+  });
+  // e.preventDefault(); // only if the reporter fully owns error handling
+});
+```
+
+Java side — for exceptions that never pass through the JS event layer (escaped originals crashing a thread), walk `getSuppressed()` for `com.tns.JavaScriptStackTrace` to attach the JS frames. For embedders with a custom `Thread.UncaughtExceptionHandler`: `Runtime.passUncaughtExceptionToJs(...)` returns `true` when a listener called `preventDefault()` — honor it by not killing the process (see `NativeScriptUncaughtExceptionHandler`).
+
+## Legacy hooks (deprecated)
+
+`global.__onUncaughtError` and `global.__onDiscardedError` keep working exactly as before and are what `@nativescript/core` currently installs (surfaced as `Application.uncaughtErrorEvent` / `discardedErrorEvent`). They are invoked only when no event listener called `preventDefault()`. New code should prefer `globalThis.addEventListener("error" | "unhandledrejection", ...)`.
+
+## Behavior details
+
+- Every error is reported exactly once: either the JS→Java boundary (synchronous throws during Java-invoked JS), the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), or `reportError` — never two of them for the same error.
+- A rejection that gets a handler before the end-of-turn drain is never reported (and produces no `rejectionhandled` either).
+- The `error` event for uncaught exceptions fires when the exception is reported to JS (from the uncaught-exception handler via `passUncaughtExceptionToJs`, or the discard path) — after the Java stack has already unwound. `preventDefault()` prevents the crash, but on the main thread the app's looper has exited by then; for background and JS-only threads the process genuinely keeps running.
+- Worker isolates run the same machinery: each worker has its own tracker, drain, and event layer.

From 029b1552706e501795f267d91cebbdfe444b032b Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 18:52:26 -0300
Subject: [PATCH 5/7] feat!: contain uncaught JS errors by default
 (uncaughtErrorPolicy)

Adopts the web's model as the default: an erroring page doesn't crash
the browser, and an uncaught JS error no longer crashes the app. This is
the Android half of the unified NativeScript 9.1 error-handling spec.

Containment:
- An uncaught throw in a NATIVE-initiated callback (the OS invoking an
  overridden method or interface implementation, a posted Runnable, a
  timer, __runOnMainThread, a frame callback) is contained at the
  boundary: reported through the WHATWG pipeline (cancelable `error`
  event -> __onUncaughtError -> logcat) and the native caller resumes
  with the return type's default value. preventDefault() suppresses the
  report entirely.
- A JS-INITIATED chain (JS -> Java -> JS callback throws) keeps
  propagating to the outer JS catch with the original JS error object -
  correct JavaScript semantics, tracked via a per-isolate JS->Java call
  depth around CallJavaMethod/RegisterInstance. Containment applies only
  at an outermost native-initiated boundary.
- Contained primitive-returning overrides yield the type's default
  (dispatchCallJSMethodNative substitutes it before unboxing), fixing
  the NPE the old discard path produced.
- Branded interop.escapeException throws are never contained; module/
  script evaluation (bootstrap) is not contained.

uncaughtErrorPolicy (app package.json, root level):
- "report" (default): report and continue, never crash.
- "throw": unprevented errors are thrown to the native layer as real
  Java exceptions - com.tns.NativeScriptException with the JS frames as
  its stack trace - restoring the pre-9.1 behavior (typically a crash,
  via the thread's uncaught-exception path, which performs the single
  report). Unhandled rejections are thrown from a clean Java frame
  posted to the runtime's looper. Named for the mechanism, not a
  guaranteed crash: native catch-alls above the boundary can still
  intercept.

discardUncaughtJsExceptions is deprecated (logcat warning): `true` keeps
its legacy quiet routing (__onDiscardedError, no log) on top of the new
default; `false` - which used to mean "crash" - is ignored. Branded
escapes are now exempt from the discard handling (escapedFromJs marker).

Testing: 5 new specs (containment + app liveness with event/hook
identity, preventDefault suppression, timer containment, primitive
default instead of NPE, JS-initiated chain identity) plus the
direct-throw escape specs; "throw" policy is a documented manual smoke.
Full suite green on an API 35 arm64 emulator - every pre-existing suite
passes unchanged thanks to the JS-initiated-chain rule.
---
 docs/error-handling.md                        |  56 ++++--
 test-app/app/src/main/assets/app/mainpage.js  |   1 +
 .../assets/app/tests/testEscapeException.js   |  47 +++++
 .../app/tests/testUncaughtErrorPolicy.js      | 170 ++++++++++++++++++
 .../tns/tests/UncaughtErrorPolicyTest.java    |  28 +++
 .../runtime/src/main/cpp/CallbackHandlers.cpp |  41 ++++-
 .../runtime/src/main/cpp/CallbackHandlers.h   |   3 +-
 .../src/main/cpp/NativeScriptException.cpp    | 123 ++++++++++++-
 .../src/main/cpp/NativeScriptException.h      |  39 +++-
 test-app/runtime/src/main/cpp/Runtime.cpp     |  24 +++
 test-app/runtime/src/main/cpp/Runtime.h       |  41 +++++
 test-app/runtime/src/main/cpp/Timers.cpp      |   3 +-
 .../src/main/java/com/tns/AppConfig.java      |  28 ++-
 .../java/com/tns/NativeScriptException.java   |  11 ++
 .../src/main/java/com/tns/Runtime.java        |  55 +++++-
 15 files changed, 630 insertions(+), 40 deletions(-)
 create mode 100644 test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
 create mode 100644 test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java

diff --git a/docs/error-handling.md b/docs/error-handling.md
index 4be910887..c3bfb2f22 100644
--- a/docs/error-handling.md
+++ b/docs/error-handling.md
@@ -1,17 +1,19 @@
 # Error handling
 
-The runtime implements the WHATWG error model at the global level: uncaught JavaScript exceptions and unhandled promise rejections are dispatched as cancelable events on `globalThis`, Java exceptions round-trip into JavaScript with the original `Throwable` attached, and `interop.escapeException` forwards a JavaScript throw to the Java caller as the **original** Java exception. Unlike iOS, a truly-uncaught exception crashes the app by default (the Java default uncaught-exception handler ends the process) — `preventDefault()` and `discardUncaughtJsExceptions` are the opt-outs. Unhandled rejections and `reportError` only report; they never crash.
+The runtime implements the WHATWG error model at the global level: uncaught JavaScript exceptions and unhandled promise rejections are dispatched as cancelable events on `globalThis`, Java exceptions round-trip into JavaScript with the original `Throwable` attached, and `interop.escapeException` forwards a JavaScript throw to the Java caller as the **original** Java exception. Following the web's model — an erroring page doesn't crash the browser — **an uncaught error never crashes the app by default**: it is reported (event → hook → log) and execution continues. Crashing is opt-in via `uncaughtErrorPolicy: "throw"`; suppressing a report entirely is per-error via `preventDefault()`.
 
 ## Quick reference
 
 | Situation | Default behavior |
 |---|---|
-| Uncaught JS exception during a Java→JS call (overridden method, interface implementation) | Becomes a real `com.tns.NativeScriptException` thrown to the Java caller. If nothing catches it, the thread's uncaught-exception handler reports it (cancelable `error` event → `__onUncaughtError` hook → error activity in debug builds) and the process exits — unless a listener called `preventDefault()`. |
+| Uncaught JS exception in a **native-initiated** callback (the OS invoking an overridden method or interface implementation, a posted `Runnable`, a timer, `__runOnMainThread`, a frame callback) | **Contained at the boundary**: reported (cancelable `error` event → `__onUncaughtError` hook → logcat), the Java caller receives the default value for the return type, and the app keeps running. |
+| Uncaught JS exception in a **JS-initiated** chain (JS → Java → JS callback throws) | **Propagates back to the outer JS `catch`** as the very same JS error object — correct JavaScript semantics; each JS frame on the way gets its chance to catch. Only if it reaches an outermost native-initiated boundary is it contained. |
 | Unhandled promise rejection | Tracked per isolate, reported once per looper turn: cancelable `unhandledrejection` event → `__onUncaughtError` hook, logcat entry prefixed `Unhandled promise rejection:`. The app keeps running. |
 | `.catch()` added after the report | `rejectionhandled` event (non-cancelable), carrying the original reason. |
 | Java exception during a JS→Java call | Surfaced to JS as an `Error` carrying the original as `error.nativeException`. |
-| `throw interop.escapeException(x)` in JS called from Java | The original Java `Throwable` carried by `x` is rethrown **unwrapped** to the Java caller (JS trace attached as a suppressed `com.tns.JavaScriptStackTrace`); with no underlying `Throwable`, a `com.tns.NativeScriptException` whose stack trace is the JS frames. |
+| `throw interop.escapeException(x)` in JS called from Java | Never contained. The original Java `Throwable` carried by `x` is rethrown **unwrapped** to the Java caller (JS trace attached as a suppressed `com.tns.JavaScriptStackTrace`); with no underlying `Throwable`, a `com.tns.NativeScriptException` whose stack trace is the JS frames. |
 | `reportError(x)` | Routed through the same pipeline as an uncaught error; never crashes. |
+| `uncaughtErrorPolicy: "throw"` | Restores the pre-9.1 behavior: unprevented uncaught errors are thrown to the native layer as real Java exceptions (which typically ends the process via the default uncaught-exception handler). |
 
 ## JavaScript API
 
@@ -69,8 +71,9 @@ The stacks live on the error/reason **value**, not on the event — and the thro
 
 | You wrote | `e.error` / `e.reason` is | JS stack | Native exception |
 |---|---|---|---|
-| `throw new Error("x")` | that `Error` | `e.error.stack` | — |
+| `throw new Error("x")` | that `Error` (the actual thrown value) | `e.error.stack` | — |
 | called a Java method that threw, without try/catch | an `Error` with `message` from the Java exception's message | `e.error.stack` (the JS call site); `e.error.stackTrace` combines it with the Java frames | `e.error.nativeException` — the original `Throwable` (call `.getClass()`, `.getMessage()`, `.getCause()`, ... on it) |
+| `throw new java.io.IOException("x")` — a directly-thrown wrapped `Throwable` | the wrapped `Throwable` itself — not an `Error`, no `.stack` | — | `e.error` directly (`instanceof java.io.IOException`) |
 
 ### Catching native exceptions
 
@@ -103,7 +106,17 @@ const listener = new some.api.Listener({
 Semantics:
 
 - `escapeException(err)` returns a JS `Error` (message/stack copied), so it behaves like a normal throw in pure-JS paths; the brand is an isolate-private symbol that user code cannot forge. Passing an already-branded value is a no-op; calling with no argument throws `TypeError`.
-- If `err` is (or carries via `.nativeException`) a Java `Throwable`, the **original object** is rethrown at the boundary — a Java `catch (IOException e)` above the caller matches, and `Throwable` identity is preserved (same object, untouched class/stack/cause chain). The JS journey rides along as a suppressed `com.tns.JavaScriptStackTrace` (see the native section).
+- If `err` is (or carries via `.nativeException`) a Java `Throwable`, the **original object** is rethrown at the boundary — a Java `catch (IOException e)` above the caller matches, and `Throwable` identity is preserved (same object, untouched class/stack/cause chain). The JS journey rides along as a suppressed `com.tns.JavaScriptStackTrace` (see the native section). This includes directly-constructed exceptions:
+
+```js
+// The caller catches THIS exact IOException - no wrapper. Without the brand,
+// a directly-thrown wrapped Throwable behaves like any other uncaught throw:
+// contained (reported, caller resumes) in a native-initiated callback, or -
+// in a JS-initiated chain - propagated to the outer JS catch (and, if it
+// reaches Java code with no JS below, wrapped in a com.tns.NativeScriptException
+// with the IOException as its cause).
+throw interop.escapeException(new java.io.IOException("x"));
+```
 - Otherwise a `com.tns.NativeScriptException` is thrown as usual, but with its stack trace replaced by frames synthesized from the JS stack, so crash reporters group it by where it actually happened in JS.
 - The `escapeException()` call site's stack is recorded too — for non-Error values (`escapeException("boom")`) it is the only stack available.
 - Branded escapes bypass `discardUncaughtJsExceptions` (an explicit forward request must reach the caller).
@@ -156,20 +169,29 @@ for (Throwable suppressed : caught.getSuppressed()) {
 
 ## Configuration
 
-| Flag (app `package.json`, default off) | Effect |
+One policy key in the app's `package.json` (root level) governs what happens to an **unprevented** uncaught error or unhandled rejection:
+
+| `uncaughtErrorPolicy` | Effect |
 |---|---|
-| `discardUncaughtJsExceptions` | JS exceptions escaping an overridden-method call are swallowed on the Java side and reported through `__onDiscardedError` instead of crashing the app. Branded `interop.escapeException` throws bypass it. |
+| `"report"` (default) | Report (event → hook → log) and continue. Never crashes. |
+| `"throw"` | After the (cancelable) event, the error is thrown to the native layer as a real Java exception — `com.tns.NativeScriptException` with the JS frames as its stack trace — and reported through the thread's uncaught-exception path. This typically ends the process (the pre-9.1 default), though a native catch or a custom `UncaughtExceptionHandler` above the boundary can still intercept it, which is why the policy names the mechanism, not a guaranteed crash. Unhandled rejections are thrown from a clean frame on the runtime's looper. |
+
+Deprecated (kept for the transition, both emit a logcat warning):
 
-There is no `crashOnUncaughtJsExceptions` flag (unlike iOS): crashing on truly-uncaught exceptions is already Android's default.
+| Flag | Behavior |
+|---|---|
+| `discardUncaughtJsExceptions: true` | Legacy quiet routing: contained reports call `__onDiscardedError` instead of `__onUncaughtError` and skip the logcat report. Branded `interop.escapeException` throws bypass it. |
+| `discardUncaughtJsExceptions: false` | Ignored (this used to mean "crash on uncaught errors" — set `uncaughtErrorPolicy: "throw"` for that). |
 
 Terminal-path decision table:
 
 | Condition | legacy hook called | process crash |
 |---|---|---|
-| uncaught exception, default | `__onUncaughtError` | yes |
-| uncaught exception, `discardUncaughtJsExceptions` | `__onDiscardedError` | no |
-| uncaught exception, listener called `preventDefault()` | none | no |
-| unhandled rejection / `reportError`, unprevented | `__onUncaughtError` | no |
+| uncaught error, default (`"report"`) | `__onUncaughtError` | no |
+| uncaught error, `"report"` + `discardUncaughtJsExceptions: true` | `__onDiscardedError` | no |
+| uncaught error, listener called `preventDefault()` | none | no |
+| uncaught error / unhandled rejection, `"throw"`, unprevented | `__onUncaughtError` (via the uncaught-exception path) | yes, normally |
+| unhandled rejection / `reportError`, `"report"`, unprevented | `__onUncaughtError` | no |
 | unhandled rejection / `reportError`, `preventDefault()` | none | no |
 
 ## Crash reporter integration
@@ -188,7 +210,7 @@ globalThis.addEventListener("error", (e) => {
 });
 ```
 
-Java side — for exceptions that never pass through the JS event layer (escaped originals crashing a thread), walk `getSuppressed()` for `com.tns.JavaScriptStackTrace` to attach the JS frames. For embedders with a custom `Thread.UncaughtExceptionHandler`: `Runtime.passUncaughtExceptionToJs(...)` returns `true` when a listener called `preventDefault()` — honor it by not killing the process (see `NativeScriptUncaughtExceptionHandler`).
+Java side — for exceptions that never pass through the JS event layer (escaped originals crashing a thread, `"throw"`-policy fatals), walk `getSuppressed()` for `com.tns.JavaScriptStackTrace` to attach the JS frames. For embedders with a custom `Thread.UncaughtExceptionHandler`: `Runtime.passUncaughtExceptionToJs(...)` returns `true` when a listener called `preventDefault()` — honor it by not killing the process (see `NativeScriptUncaughtExceptionHandler`).
 
 ## Legacy hooks (deprecated)
 
@@ -196,7 +218,9 @@ Java side — for exceptions that never pass through the JS event layer (escaped
 
 ## Behavior details
 
-- Every error is reported exactly once: either the JS→Java boundary (synchronous throws during Java-invoked JS), the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), or `reportError` — never two of them for the same error.
+- **Containment is boundary-outermost.** The runtime tracks the depth of in-flight JS→Java calls; a throw with JS frames waiting below the boundary propagates (so `try { javaApi.call(cb) } catch` works, with the original JS error object restored across the crossing), and is contained only at an outermost native-initiated entry. `interop.escapeException` and `uncaughtErrorPolicy: "throw"` are the two ways an error crosses that outermost boundary.
+- **Contained callbacks return type defaults.** A throwing overridden method hands its Java caller `null` for reference types and `0`/`false` for primitives (the runtime substitutes the default before unboxing, so no `NullPointerException` from the binding). The error is loudly reported *before* the caller resumes, so logcat shows the real failure ahead of any downstream symptom. If the Java contract genuinely needs the exception, use `interop.escapeException`.
+- Every error is reported exactly once: either the containment point, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), `reportError`, or — under `"throw"` — the thread's uncaught-exception path. Never two of them for the same error.
 - A rejection that gets a handler before the end-of-turn drain is never reported (and produces no `rejectionhandled` either).
-- The `error` event for uncaught exceptions fires when the exception is reported to JS (from the uncaught-exception handler via `passUncaughtExceptionToJs`, or the discard path) — after the Java stack has already unwound. `preventDefault()` prevents the crash, but on the main thread the app's looper has exited by then; for background and JS-only threads the process genuinely keeps running.
-- Worker isolates run the same machinery: each worker has its own tracker, drain, and event layer.
+- Module/script evaluation (`runModule`/`runScript`, app bootstrap) is not contained — an app whose main module fails to load still fails loudly.
+- Worker isolates run the same machinery: each worker has its own tracker, drain, event layer and containment.
diff --git a/test-app/app/src/main/assets/app/mainpage.js b/test-app/app/src/main/assets/app/mainpage.js
index 696466fb2..2ff19f79d 100644
--- a/test-app/app/src/main/assets/app/mainpage.js
+++ b/test-app/app/src/main/assets/app/mainpage.js
@@ -77,6 +77,7 @@ require('./tests/testQueueMicrotask');
 require('./tests/testErrorEvents');
 require('./tests/testUnhandledRejections');
 require('./tests/testEscapeException');
+require('./tests/testUncaughtErrorPolicy');
 require("./tests/testConcurrentAccess");
 
 require("./tests/testESModules.mjs");
diff --git a/test-app/app/src/main/assets/app/tests/testEscapeException.js b/test-app/app/src/main/assets/app/tests/testEscapeException.js
index c59109d60..cc459a85f 100644
--- a/test-app/app/src/main/assets/app/tests/testEscapeException.js
+++ b/test-app/app/src/main/assets/app/tests/testEscapeException.js
@@ -132,6 +132,53 @@ describe("interop.escapeException", function () {
         expect(second.getSuppressed().length).toBe(1);
     });
 
+    it("escapes a directly-constructed Java exception (not wrapped in an Error)", function () {
+        var original = new java.io.IOException("direct-io");
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                // The escaped value IS the wrapped Throwable - there is no JS
+                // Error and no .nativeException property involved.
+                throw interop.escapeException(original);
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("java.io.IOException");
+        expect(ret.getMessage()).toBe("direct-io");
+        expect(ret.equals(original)).toBe(true);
+
+        // A wrapped Throwable has no JS stack of its own, so the carrier
+        // renders the escape site.
+        var suppressed = ret.getSuppressed();
+        expect(suppressed.length).toBe(1);
+        expect(suppressed[0].getClass().getName()).toBe("com.tns.JavaScriptStackTrace");
+        var frames = suppressed[0].getStackTrace();
+        var sawThisFile = false;
+        for (var i = 0; i < frames.length; i++) {
+            var file = frames[i].getFileName();
+            if (file && file.indexOf("testEscapeException.js") !== -1) {
+                sawThisFile = true;
+                break;
+            }
+        }
+        expect(sawThisFile).toBe(true);
+    });
+
+    it("an unbranded directly-thrown Java exception surfaces wrapped, original as cause", function () {
+        var original = new java.io.IOException("direct-unbranded");
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw original;
+            }
+        });
+        var ret = com.tns.tests.EscapeExceptionTest.invokeCatchingThrowable(runnable);
+
+        expect(ret).not.toBeNull();
+        expect(ret.getClass().getName()).toBe("com.tns.NativeScriptException");
+        expect(ret.getCause().equals(original)).toBe(true);
+    });
+
     it("an unbranded rethrow keeps today's wrapping semantics", function () {
         var caught = null;
         try {
diff --git a/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
new file mode 100644
index 000000000..96b967220
--- /dev/null
+++ b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
@@ -0,0 +1,170 @@
+describe("uncaughtErrorPolicy (default: report)", function () {
+    // Under the default "report" policy, an uncaught JS throw in a
+    // native-initiated callback is contained: reported through the `error`
+    // event and the __onUncaughtError hook, while the native caller resumes
+    // with a default value and the app keeps running. JS-initiated chains
+    // (JS -> Java -> JS) keep propagating to the outer JS catch.
+    var previousUncaughtHook;
+    var uncaught;
+    var addedGlobalListeners;
+
+    beforeEach(function () {
+        previousUncaughtHook = global.__onUncaughtError;
+        uncaught = [];
+        global.__onUncaughtError = function (error) {
+            uncaught.push(error);
+        };
+        addedGlobalListeners = [];
+    });
+
+    afterEach(function () {
+        global.__onUncaughtError = previousUncaughtHook;
+        for (var i = 0; i < addedGlobalListeners.length; i++) {
+            var l = addedGlobalListeners[i];
+            global.removeEventListener(l.type, l.handler);
+        }
+        addedGlobalListeners = [];
+    });
+
+    function onGlobal(type, handler) {
+        global.addEventListener(type, handler);
+        addedGlobalListeners.push({ type: type, handler: handler });
+    }
+
+    function uncaughtSeen(err) {
+        return uncaught.indexOf(err) !== -1;
+    }
+
+    function pollUntil(predicate, cb) {
+        var turns = 0;
+        (function poll() {
+            if (predicate() || turns >= 25) {
+                cb();
+                return;
+            }
+            turns++;
+            setTimeout(poll, 10);
+        })();
+    }
+
+    function afterQuietTurns(cb) {
+        setTimeout(function () {
+            setTimeout(cb, 20);
+        }, 20);
+    }
+
+    it("contains an uncaught throw in a native-initiated callback and keeps the app alive", function (done) {
+        var reason = new Error("contained-post-throw");
+        var received = null;
+        onGlobal("error", function (e) {
+            if (e.error === reason) {
+                received = e;
+            }
+        });
+
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                throw reason;
+            }
+        });
+        new android.os.Handler(android.os.Looper.myLooper()).post(runnable);
+
+        pollUntil(function () { return received !== null; }, function () {
+            expect(received).not.toBeNull();
+            // The event carries the actual thrown value.
+            expect(received.error).toBe(reason);
+            // Unprevented, so the legacy hook fired too.
+            expect(uncaughtSeen(reason)).toBe(true);
+            // And the app is still running.
+            expect(1 + 1).toBe(2);
+            done();
+        });
+    });
+
+    it("preventDefault() on the error event suppresses the legacy hook", function (done) {
+        var reason = new Error("contained-prevented-throw");
+        var ran = false;
+        onGlobal("error", function (e) {
+            if (e.error === reason) {
+                e.preventDefault();
+            }
+        });
+
+        var runnable = new java.lang.Runnable({
+            run: function () {
+                ran = true;
+                throw reason;
+            }
+        });
+        new android.os.Handler(android.os.Looper.myLooper()).post(runnable);
+
+        pollUntil(function () { return ran; }, function () {
+            afterQuietTurns(function () {
+                expect(uncaughtSeen(reason)).toBe(false);
+                done();
+            });
+        });
+    });
+
+    it("contains an uncaught throw in a setTimeout callback", function (done) {
+        var reason = new Error("contained-timer-throw");
+        setTimeout(function () {
+            throw reason;
+        }, 1);
+
+        pollUntil(function () { return uncaughtSeen(reason); }, function () {
+            expect(uncaughtSeen(reason)).toBe(true);
+            expect(1 + 1).toBe(2);
+            done();
+        });
+    });
+
+    it("a contained throw in a primitive-returning override yields the type's default", function (done) {
+        var reason = new Error("contained-compare-throw");
+        var doneRan = false;
+        var comparator = new java.util.Comparator({
+            compare: function () {
+                throw reason;
+            }
+        });
+        var doneCb = new java.lang.Runnable({
+            run: function () {
+                doneRan = true;
+            }
+        });
+        com.tns.tests.UncaughtErrorPolicyTest.compareOnLooper(comparator, doneCb);
+
+        pollUntil(function () { return doneRan; }, function () {
+            // The Java caller received int's default instead of an NPE.
+            expect(com.tns.tests.UncaughtErrorPolicyTest.lastCompareResult).toBe(0);
+            expect(uncaughtSeen(reason)).toBe(true);
+            done();
+        });
+    });
+
+    it("propagates a JS-initiated chain back to the outer JS catch with identity", function () {
+        var reason = new Error("chain-identity");
+        var caught = null;
+        try {
+            com.tns.tests.UncaughtErrorPolicyTest.invoke(new java.lang.Runnable({
+                run: function () {
+                    throw reason;
+                }
+            }));
+        } catch (e) {
+            caught = e;
+        }
+        // The exception crossed JS -> Java -> JS and surfaced as the very
+        // same JS object - not contained, not wrapped.
+        expect(caught).toBe(reason);
+        expect(uncaughtSeen(reason)).toBe(false);
+    });
+
+    // uncaughtErrorPolicy: "throw" is not exercised automatically because a
+    // real crash would kill the test runner. To smoke it manually, set
+    // { "uncaughtErrorPolicy": "throw" } in the app's package.json and throw
+    // from a native-initiated callback (or leave a promise rejection
+    // unhandled) - the app must terminate with a com.tns.NativeScriptException
+    // whose stack trace points at the JS frames. Default-off behavior is
+    // covered by every other suite here.
+});
diff --git a/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java b/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java
new file mode 100644
index 000000000..5244bce03
--- /dev/null
+++ b/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java
@@ -0,0 +1,28 @@
+package com.tns.tests;
+
+public class UncaughtErrorPolicyTest {
+    public static volatile int lastCompareResult = -999;
+
+    /*
+     * Invokes the comparator from a posted looper message - a native-initiated
+     * entry into JS with no JS frames below it - so an uncaught throw in the
+     * JS implementation is contained and compare() returns the int default.
+     */
+    public static void compareOnLooper(final java.util.Comparator<Object> comparator, final Runnable done) {
+        new android.os.Handler(android.os.Looper.myLooper()).post(new Runnable() {
+            @Override
+            public void run() {
+                lastCompareResult = comparator.compare("a", "b");
+                done.run();
+            }
+        });
+    }
+
+    /*
+     * Direct pass-through with no catch: lets tests verify that a JS->Java->JS
+     * chain propagates the JS exception back to the outer JS catch.
+     */
+    public static void invoke(Runnable runnable) {
+        runnable.run();
+    }
+}
diff --git a/test-app/runtime/src/main/cpp/CallbackHandlers.cpp b/test-app/runtime/src/main/cpp/CallbackHandlers.cpp
index 5ce450fef..a7fe67236 100644
--- a/test-app/runtime/src/main/cpp/CallbackHandlers.cpp
+++ b/test-app/runtime/src/main/cpp/CallbackHandlers.cpp
@@ -63,6 +63,24 @@ void CallbackHandlers::Init(Isolate *isolate) {
     MethodCache::Init();
 }
 
+/*
+ * Marks a JS -> Java call in flight on the runtime (see
+ * Runtime::JavaCallDepth): a JS callback that throws while the depth is
+ * non-zero is part of a JS-initiated chain and must propagate back to the
+ * outer JS catch instead of being contained at the boundary.
+ */
+namespace {
+struct JavaCallScope {
+    explicit JavaCallScope(Runtime* runtime) : runtime_(runtime) {
+        runtime_->EnterJavaCall();
+    }
+    ~JavaCallScope() {
+        runtime_->LeaveJavaCall();
+    }
+    Runtime* runtime_;
+};
+}  // namespace
+
 bool CallbackHandlers::RegisterInstance(Isolate *isolate, const Local<Object> &jsObject,
                                         const std::string &fullClassName,
                                         const ArgsWrapper &argWrapper,
@@ -76,6 +94,10 @@ bool CallbackHandlers::RegisterInstance(Isolate *isolate, const Local<Object> &j
     auto runtime = Runtime::GetRuntime(isolate);
     auto objectManager = runtime->GetObjectManager();
 
+    // The Java constructor may synchronously call back into JS (extended
+    // class init) - that whole window is a JS-initiated chain.
+    JavaCallScope javaCallScope(runtime);
+
     JEnv env;
 
     jclass generatedJavaClass = ResolveClass(isolate, baseClassName, fullClassName,
@@ -211,6 +233,10 @@ void CallbackHandlers::CallJavaMethod(const Local<Object> &caller, const string
 
     auto isolate = args.GetIsolate();
 
+    // The Java method may synchronously call back into JS (an overridden
+    // method on the receiver) - that whole window is a JS-initiated chain.
+    JavaCallScope javaCallScope(Runtime::GetRuntime(isolate));
+
     if ((entry != nullptr) && entry->getIsResolved()) {
         auto &entrySignature = entry->getSig();
         isStatic = entry->isStatic;
@@ -694,7 +720,8 @@ int CallbackHandlers::RunOnMainThreadFdCallback(int fd, int events, void *data)
 
     cb->Call(context, context->Global(), 0, nullptr);  // ignore JS return value
 
-    if(tc.HasCaught()){
+    if (tc.HasCaught() &&
+        !NativeScriptException::ContainUncaughtCallbackException(isolate, tc)) {
         throw NativeScriptException(tc);
     }
 
@@ -931,9 +958,15 @@ Local<Value> CallbackHandlers::CallJSMethod(Isolate *isolate, JNIEnv *_env,
         //TODO: if javaResult is a pure js object create a java object that represents this object in java land
 
         if (tc.HasCaught()) {
-            stringstream ss;
-            ss << "Calling js method " << methodName << " failed";
-            throw NativeScriptException(tc, ss.str());
+            if (NativeScriptException::ContainUncaughtCallbackException(isolate, tc)) {
+                // Reported per uncaughtErrorPolicy; the native caller resumes
+                // with a default value.
+                jsResult = v8::Undefined(isolate);
+            } else {
+                stringstream ss;
+                ss << "Calling js method " << methodName << " failed";
+                throw NativeScriptException(tc, ss.str());
+            }
         }
 
         result = handleScope.Escape(jsResult);
diff --git a/test-app/runtime/src/main/cpp/CallbackHandlers.h b/test-app/runtime/src/main/cpp/CallbackHandlers.h
index eddcca93d..f62eeef7d 100644
--- a/test-app/runtime/src/main/cpp/CallbackHandlers.h
+++ b/test-app/runtime/src/main/cpp/CallbackHandlers.h
@@ -340,7 +340,8 @@ namespace tns {
                     }
 
 
-                    if(tc.HasCaught()){
+                    if (tc.HasCaught() &&
+                        !NativeScriptException::ContainUncaughtCallbackException(isolate, tc)) {
                         throw NativeScriptException(tc);
                     }
 
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.cpp b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
index 4daa46d98..a7a145d97 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.cpp
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
@@ -149,8 +149,13 @@ void NativeScriptException::ReThrowToJava() {
     // NativeScriptException shape, but its Java stack is the (identical) JNI
     // boundary machinery - replace it with frames synthesized from the JS
     // stack so crash reporters group these by where they actually happened.
+    // The escapedFromJs mark exempts it from the deprecated
+    // discardUncaughtJsExceptions handling in the Java dispatch layer.
     if (escapeInfo.branded && ex != nullptr) {
       Interop::ApplyJavaScriptFrames(env, ex, escapeInfo);
+      static jfieldID escapedFromJsField =
+          env.GetFieldID(NATIVESCRIPTEXCEPTION_CLASS, "escapedFromJs", "Z");
+      env.SetBooleanField(ex, escapedFromJsField, JNI_TRUE);
     }
   } else if (!m_message.empty()) {
     JniLocalRef msg(env.NewStringUTF(m_message.c_str()));
@@ -322,13 +327,31 @@ void NativeScriptException::ReportUnhandledRejection(Isolate* isolate,
   if (ErrorEvents::DispatchUnhandledRejection(isolate, promise, reason)) {
     return;
   }
-  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:");
+
+  auto runtime = GetRuntimeOrNull(isolate);
+  if (runtime != nullptr &&
+      runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
+    // Hand the rejection to the native layer; the post-mortem uncaught path
+    // performs the (single) report, exactly as for a sync uncaught error.
+    string message =
+        "Unhandled promise rejection: " + ToDetailString(isolate, reason);
+    ThrowUncaughtJsErrorToJava(message, stackTrace);
+    return;
+  }
+
+  jboolean isDiscarded =
+      (runtime != nullptr && runtime->GetDiscardUncaughtJsExceptions())
+          ? JNI_TRUE
+          : JNI_FALSE;
+  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:",
+                  isDiscarded);
 }
 
 void NativeScriptException::ReportFatalTail(Isolate* isolate,
                                             Local<Value> error,
                                             const string& stackOverride,
-                                            const string& logPrefix) {
+                                            const string& logPrefix,
+                                            jboolean isDiscarded) {
   auto context = isolate->GetCurrentContext();
 
   string stackTrace = stackOverride;
@@ -346,12 +369,16 @@ void NativeScriptException::ReportFatalTail(Isolate* isolate,
         .FromMaybe(false);
   }
 
-  // There is no discardUncaughtJsExceptions decision here - that flag lives
-  // on the Java side and only affects Java-initiated reports. Errors that
-  // reach this tail (reportError, unhandled rejections, throwing listeners)
-  // have no Java caller, so they report through __onUncaughtError and the
-  // process keeps running.
-  CallJsFuncWithErr(error, false /* isDiscarded */);
+  CallJsFuncWithErr(error, isDiscarded);
+
+  if (isDiscarded == JNI_TRUE) {
+    // Deprecated legacy routing: quiet, like the old Java-side discard path.
+    if (!logPrefix.empty()) {
+      DEBUG_WRITE_FORCE("%s", logPrefix.c_str());
+    }
+    DEBUG_WRITE_FORCE("NativeScript discarding uncaught JS exception!");
+    return;
+  }
 
   if (!logPrefix.empty()) {
     DEBUG_WRITE_FORCE("%s", logPrefix.c_str());
@@ -362,6 +389,86 @@ void NativeScriptException::ReportFatalTail(Isolate* isolate,
   }
 }
 
+bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
+                                                             v8::TryCatch& tc) {
+  auto runtime = GetRuntimeOrNull(isolate);
+  if (runtime == nullptr) {
+    return false;
+  }
+
+  // JS-initiated chain (JS -> Java -> JS): a JS frame below this boundary is
+  // waiting for the exception - propagate so it reaches the outer JS catch
+  // (the boundary machinery restores the original JS error object there).
+  if (runtime->JavaCallDepth() > 0) {
+    return false;
+  }
+
+  Local<Value> error = tc.Exception();
+  if (error.IsEmpty()) {
+    return false;
+  }
+
+  // Branded interop.escapeException: an explicit forward to the native
+  // caller - never contained.
+  if (error->IsObject()) {
+    JEnv env;
+    Interop::EscapedExceptionInfo escapeInfo;
+    if (Interop::GetEscapedExceptionInfo(env, error.As<Object>(), escapeInfo)) {
+      if (escapeInfo.original != nullptr) {
+        env.DeleteLocalRef(escapeInfo.original);
+      }
+      return false;
+    }
+  }
+
+  if (runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
+    // Pre-9.1 semantics: the exception is thrown to the Java caller and the
+    // post-mortem uncaught-exception path performs the (single) report.
+    return false;
+  }
+
+  // Contain: report through the WHATWG pipeline (`error` event -> legacy
+  // hook -> log) and let the caller resume with a default value.
+  string errorMessage;
+  string stackTrace;
+  auto message = tc.Message();
+  if (!message.IsEmpty()) {
+    errorMessage = GetErrorMessage(message, error);
+    stackTrace = GetErrorStackTrace(message->GetStackTrace());
+  } else {
+    errorMessage = ToDetailString(isolate, error);
+    stackTrace = GetStackTraceOfValue(isolate, error);
+  }
+
+  {
+    // A throwing listener or hook must not escape into the caller.
+    v8::TryCatch reportTc(isolate);
+    if (!ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
+      jboolean isDiscarded =
+          runtime->GetDiscardUncaughtJsExceptions() ? JNI_TRUE : JNI_FALSE;
+      ReportFatalTail(isolate, error, stackTrace, "", isDiscarded);
+    }
+    if (reportTc.HasCaught()) {
+      DEBUG_WRITE_FORCE(
+          "ContainUncaughtCallbackException: exception while reporting");
+    }
+  }
+
+  tc.Reset();
+  return true;
+}
+
+void NativeScriptException::ThrowUncaughtJsErrorToJava(const string& message,
+                                                       const string& stackTrace) {
+  JEnv env;
+  static jmethodID mid = env.GetStaticMethodID(
+      RUNTIME_CLASS, "throwUncaughtJsErrorOnCurrentThread",
+      "(Ljava/lang/String;Ljava/lang/String;)V");
+  JniLocalRef msg(env.NewStringUTF(message.c_str()));
+  JniLocalRef stack(env.NewStringUTF(stackTrace.c_str()));
+  env.CallStaticVoidMethod(RUNTIME_CLASS, mid, (jstring)msg, (jstring)stack);
+}
+
 void PromiseRejectionTracker::OnReject(Local<Promise> promise,
                                        Local<Value> reason) {
   auto isolate = promise->GetIsolate();
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.h b/test-app/runtime/src/main/cpp/NativeScriptException.h
index d44bc6593..8f3af83d0 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.h
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.h
@@ -69,15 +69,42 @@ class NativeScriptException : public std::exception {
                                        const std::string& stackTrace);
 
   /*
-   * The terminal tail shared by reportError, listener-thrown errors and the
-   * rejection path: calls the __onUncaughtError shim and logs. Does NOT
-   * dispatch any event (the caller already has), preventing recursion.
-   * Unlike a Java-side uncaught exception this never crashes the process -
-   * there is no Java caller to re-throw into.
+   * The terminal tail shared by reportError, listener-thrown errors, the
+   * rejection path and contained callback exceptions: calls the
+   * __onUncaughtError shim (or __onDiscardedError under the deprecated
+   * discardUncaughtJsExceptions flag) and logs. Does NOT dispatch any event
+   * (the caller already has), preventing recursion, and never crashes the
+   * process itself.
    */
   static void ReportFatalTail(v8::Isolate* isolate, v8::Local<v8::Value> error,
                               const std::string& stackOverride = "",
-                              const std::string& logPrefix = "");
+                              const std::string& logPrefix = "",
+                              jboolean isDiscarded = JNI_FALSE);
+
+  /*
+   * Policy-aware handling of an uncaught JS exception at a native->JS
+   * callback boundary (overridden method invoked by native code, timer,
+   * __runOnMainThread / frame callback). Returns true when the error was
+   * CONTAINED - reported through the WHATWG pipeline (`error` event ->
+   * legacy hook -> log) with the TryCatch reset, and the caller should
+   * proceed with a default value. Returns false when the caller must
+   * propagate the exception to Java: the chain is JS-initiated (a JS frame
+   * is waiting for it below the boundary), the throw is a branded
+   * interop.escapeException (explicit forward), or uncaughtErrorPolicy is
+   * "throw".
+   */
+  static bool ContainUncaughtCallbackException(v8::Isolate* isolate,
+                                               v8::TryCatch& tc);
+
+  /*
+   * Hands an unhandled promise rejection to the native layer under
+   * uncaughtErrorPolicy: "throw": schedules a com.tns.NativeScriptException
+   * throw from a clean Java frame on this thread's looper, so the thread's
+   * uncaught-exception handler (and its reporting) runs exactly as for a
+   * sync uncaught error.
+   */
+  static void ThrowUncaughtJsErrorToJava(const std::string& message,
+                                         const std::string& stackTrace);
 
   /*
    * Calls the global "__onUncaughtError" or "__onDiscardedError" if such is
diff --git a/test-app/runtime/src/main/cpp/Runtime.cpp b/test-app/runtime/src/main/cpp/Runtime.cpp
index 471a81fc4..201dc061a 100644
--- a/test-app/runtime/src/main/cpp/Runtime.cpp
+++ b/test-app/runtime/src/main/cpp/Runtime.cpp
@@ -19,6 +19,7 @@
 #include "File.h"
 #include "Interop.h"
 #include "IsolateDisposer.h"
+#include "JType.h"
 #include "JsArgConverter.h"
 #include "JsArgToArrayConverter.h"
 #include "ManualInstrumentation.h"
@@ -259,6 +260,29 @@ void Runtime::Init(JNIEnv* env, jstring filesPath, jstring nativeLibDir,
   Constants::V8_CACHE_COMPILED_CODE = (bool)cacheCode;
   JniLocalRef profilerOutputDir(env->GetObjectArrayElement(args, 2));
 
+  {
+    JEnv jEnv(env);
+    JniLocalRef discardUncaught(env->GetObjectArrayElement(
+        args, (jsize)11 /* KnownKeys.DiscardUncaughtJsExceptions */));
+    if (!discardUncaught.IsNull()) {
+      m_discardUncaughtJsExceptions =
+          JType::BooleanValue(jEnv, discardUncaught) == JNI_TRUE;
+    }
+
+    JniLocalRef uncaughtErrorPolicy(env->GetObjectArrayElement(
+        args, (jsize)15 /* KnownKeys.UncaughtErrorPolicy */));
+    if (!uncaughtErrorPolicy.IsNull()) {
+      auto policy = ArgConverter::jstringToString(uncaughtErrorPolicy);
+      if (policy == "throw") {
+        m_uncaughtErrorPolicy = UncaughtErrorPolicy::Throw;
+      } else {
+        // AppConfig validates and warns about unknown values; anything that
+        // is not "throw" behaves as the default.
+        m_uncaughtErrorPolicy = UncaughtErrorPolicy::Report;
+      }
+    }
+  }
+
   DEBUG_WRITE("Initializing Telerik NativeScript");
 
   auto profilerOutputDirStr = ArgConverter::jstringToString(profilerOutputDir);
diff --git a/test-app/runtime/src/main/cpp/Runtime.h b/test-app/runtime/src/main/cpp/Runtime.h
index 424955515..9fad92f65 100644
--- a/test-app/runtime/src/main/cpp/Runtime.h
+++ b/test-app/runtime/src/main/cpp/Runtime.h
@@ -29,6 +29,18 @@ class Runtime {
             WORKER_WRAPPER = 2
         };
 
+        /*
+         * What happens to an unprevented uncaught JS error (sync throw in a
+         * native-initiated callback, or an unhandled promise rejection):
+         * Report (default) - report and continue, never crash; Throw - hand
+         * it to the native layer as a real Java exception (pre-9.1 behavior).
+         * Configured via `uncaughtErrorPolicy` in the app's package.json.
+         */
+        enum class UncaughtErrorPolicy {
+            Report,
+            Throw
+        };
+
         ~Runtime();
 
         static Runtime* GetRuntime(int runtimeId);
@@ -137,6 +149,31 @@ class Runtime {
             return m_promiseRejections.get();
         }
 
+        UncaughtErrorPolicy GetUncaughtErrorPolicy() const {
+            return m_uncaughtErrorPolicy;
+        }
+        bool GetDiscardUncaughtJsExceptions() const {
+            return m_discardUncaughtJsExceptions;
+        }
+
+        /*
+         * Depth of in-flight JS->Java calls on this runtime's thread. When a
+         * JS callback invoked from Java throws while the depth is non-zero,
+         * the whole chain is JS-initiated (JS -> Java -> JS), so the throw
+         * must propagate back to the outer JS catch instead of being
+         * contained at the boundary. Maintained by CallbackHandlers around
+         * the JS->Java invocation sites.
+         */
+        int JavaCallDepth() const {
+            return m_javaCallDepth;
+        }
+        void EnterJavaCall() {
+            ++m_javaCallDepth;
+        }
+        void LeaveJavaCall() {
+            --m_javaCallDepth;
+        }
+
     private:
         Runtime(JNIEnv* env, jobject runtime, int id);
 
@@ -164,6 +201,10 @@ class Runtime {
         v8::Global<v8::Function> m_dispatchRejectionHandledFunc;
         std::unique_ptr<PromiseRejectionTracker> m_promiseRejections;
 
+        UncaughtErrorPolicy m_uncaughtErrorPolicy = UncaughtErrorPolicy::Report;
+        bool m_discardUncaughtJsExceptions = false;
+        int m_javaCallDepth = 0;
+
         int64_t m_lastUsedMemory;
 
         v8::Persistent<v8::Function>* m_gcFunc;
diff --git a/test-app/runtime/src/main/cpp/Timers.cpp b/test-app/runtime/src/main/cpp/Timers.cpp
index ebf9896d5..e19d632d9 100644
--- a/test-app/runtime/src/main/cpp/Timers.cpp
+++ b/test-app/runtime/src/main/cpp/Timers.cpp
@@ -298,7 +298,8 @@ void Timers::FireTimer() {
         nesting = 0;
 #endif
 
-        if (tc.HasCaught()) {
+        if (tc.HasCaught() &&
+            !NativeScriptException::ContainUncaughtCallbackException(isolate, tc)) {
             NativeScriptException(tc).ReThrowToJava();
         }
 
diff --git a/test-app/runtime/src/main/java/com/tns/AppConfig.java b/test-app/runtime/src/main/java/com/tns/AppConfig.java
index c163cbd54..d1379a440 100644
--- a/test-app/runtime/src/main/java/com/tns/AppConfig.java
+++ b/test-app/runtime/src/main/java/com/tns/AppConfig.java
@@ -24,7 +24,9 @@ protected enum KnownKeys {
         DiscardUncaughtJsExceptions("discardUncaughtJsExceptions", false),
         EnableLineBreakpoins("enableLineBreakpoints", false),
         EnableMultithreadedJavascript("enableMultithreadedJavascript", false),
-        LogScriptLoading("logScriptLoading", false);
+        LogScriptLoading("logScriptLoading", false),
+        // Appended last: native code reads this array by ordinal.
+        UncaughtErrorPolicy("uncaughtErrorPolicy", "report");
 
         private final String name;
         private final Object defaultValue;
@@ -87,7 +89,25 @@ public AppConfig(File appDir) {
                     values[KnownKeys.LogScriptLoading.ordinal()] = rootObject.getBoolean(KnownKeys.LogScriptLoading.getName());
                 }
                 if (rootObject.has(KnownKeys.DiscardUncaughtJsExceptions.getName())) {
-                    values[KnownKeys.DiscardUncaughtJsExceptions.ordinal()] = rootObject.getBoolean(KnownKeys.DiscardUncaughtJsExceptions.getName());
+                    boolean discard = rootObject.getBoolean(KnownKeys.DiscardUncaughtJsExceptions.getName());
+                    if (discard) {
+                        // Legacy routing (__onDiscardedError) is preserved for the transition.
+                        values[KnownKeys.DiscardUncaughtJsExceptions.ordinal()] = true;
+                        Log.w("JS", "discardUncaughtJsExceptions is deprecated: uncaught JS errors no longer crash the app by default. Remove the flag, or use uncaughtErrorPolicy.");
+                    } else {
+                        // `false` used to mean "crash on uncaught errors" (the old
+                        // default). It is NOT mapped to uncaughtErrorPolicy: "throw" -
+                        // set that explicitly if crashing is desired.
+                        Log.w("JS", "discardUncaughtJsExceptions is deprecated and `false` is ignored: uncaught JS errors are reported without crashing by default. Set uncaughtErrorPolicy: \"throw\" to restore the old crashing behavior.");
+                    }
+                }
+                if (rootObject.has(KnownKeys.UncaughtErrorPolicy.getName())) {
+                    String policy = rootObject.getString(KnownKeys.UncaughtErrorPolicy.getName());
+                    if ("report".equals(policy) || "throw".equals(policy)) {
+                        values[KnownKeys.UncaughtErrorPolicy.ordinal()] = policy;
+                    } else {
+                        Log.w("JS", String.format("Unknown uncaughtErrorPolicy \"%s\" - expected \"report\" or \"throw\". The default \"report\" will be used.", policy));
+                    }
                 }
                 if (rootObject.has(AndroidKey)) {
                     JSONObject androidObject = rootObject.getJSONObject(AndroidKey);
@@ -197,6 +217,10 @@ public boolean getDiscardUncaughtJsExceptions() {
         return (boolean)values[KnownKeys.DiscardUncaughtJsExceptions.ordinal()];
     }
 
+    public String getUncaughtErrorPolicy() {
+        return (String)values[KnownKeys.UncaughtErrorPolicy.ordinal()];
+    }
+
     public boolean getEnableMultithreadedJavascript() {
         return (boolean)values[KnownKeys.EnableMultithreadedJavascript.ordinal()];
     }
diff --git a/test-app/runtime/src/main/java/com/tns/NativeScriptException.java b/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
index 808f19531..5c00875c5 100644
--- a/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
+++ b/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
@@ -5,6 +5,17 @@ public class NativeScriptException extends RuntimeException {
     @SuppressWarnings("unused")
     private long jsValueAddress = 0;
     private String incomingStackTrace;
+    /*
+     * Set by the native side when this exception is a branded
+     * interop.escapeException(...) forward. An explicit forward always
+     * reaches the Java caller - it is exempt from the (deprecated)
+     * discardUncaughtJsExceptions handling.
+     */
+    private boolean escapedFromJs = false;
+
+    boolean isEscapedFromJs() {
+        return escapedFromJs;
+    }
 
     public NativeScriptException() {
         super();
diff --git a/test-app/runtime/src/main/java/com/tns/Runtime.java b/test-app/runtime/src/main/java/com/tns/Runtime.java
index 9bf61d1d8..d0b15ad55 100644
--- a/test-app/runtime/src/main/java/com/tns/Runtime.java
+++ b/test-app/runtime/src/main/java/com/tns/Runtime.java
@@ -1273,7 +1273,7 @@ private Object dispatchCallJSMethodNative(final int javaObjectID, final String m
             try {
                 ret = callJSMethodNative(getRuntimeId(), javaObjectID, methodName, returnType, isConstructor, packagedArgs);
             } catch (NativeScriptException e) {
-                if (discardUncaughtJsExceptions) {
+                if (discardUncaughtJsExceptions && !e.isEscapedFromJs()) {
                     String errorMessage = "Error on \"" + Thread.currentThread().getName() + "\" thread for callJSMethodNative\n";
                     android.util.Log.w("Warning", "NativeScript discarding uncaught JS exception!");
                     passDiscardedExceptionToJs(e, errorMessage);
@@ -1294,7 +1294,7 @@ public void run() {
                             final Object[] packagedArgs = packageArgs(tmpArgs);
                             arr[0] = callJSMethodNative(getRuntimeId(), javaObjectID, methodName, returnType, isCtor, packagedArgs);
                         } catch (NativeScriptException e) {
-                            if (discardUncaughtJsExceptions) {
+                            if (discardUncaughtJsExceptions && !e.isEscapedFromJs()) {
                                 String errorMessage = "Error on \"" + Thread.currentThread().getName() + "\" thread for callJSMethodNative\n";
                                 passDiscardedExceptionToJs(e, errorMessage);
                                 android.util.Log.w("Warning", "NativeScript discarding uncaught JS exception!");
@@ -1333,9 +1333,60 @@ public void run() {
             ret = arr[0];
         }
 
+        // A contained uncaught JS error (or a discarded one) yields null; for
+        // primitive return types the generated binding would NPE unboxing it,
+        // so substitute the type's default value.
+        if (ret == null && retType != null && retType.isPrimitive() && retType != void.class) {
+            ret = defaultPrimitiveValue(retType);
+        }
+
         return ret;
     }
 
+    private static Object defaultPrimitiveValue(Class<?> type) {
+        if (type == boolean.class) {
+            return Boolean.FALSE;
+        } else if (type == byte.class) {
+            return (byte) 0;
+        } else if (type == char.class) {
+            return (char) 0;
+        } else if (type == short.class) {
+            return (short) 0;
+        } else if (type == int.class) {
+            return 0;
+        } else if (type == long.class) {
+            return 0L;
+        } else if (type == float.class) {
+            return 0f;
+        } else if (type == double.class) {
+            return 0d;
+        }
+        return null;
+    }
+
+    /*
+     * Called by the native runtime under uncaughtErrorPolicy: "throw" for
+     * errors with no Java caller to unwind into (unhandled promise
+     * rejections): throws from a clean Java frame on this thread's looper so
+     * the thread's uncaught-exception handler (and its reporting) runs
+     * exactly as for a sync uncaught error.
+     */
+    @RuntimeCallable
+    private static void throwUncaughtJsErrorOnCurrentThread(String message, String stackTrace) {
+        final NativeScriptException ex = new NativeScriptException(message, stackTrace, 0);
+        JavaScriptStackTrace.applyFrames(ex, stackTrace, null);
+        android.os.Looper looper = android.os.Looper.myLooper();
+        if (looper == null) {
+            throw ex;
+        }
+        new android.os.Handler(looper).post(new Runnable() {
+            @Override
+            public void run() {
+                throw ex;
+            }
+        });
+    }
+
     @RuntimeCallable
     private static Class<?> getCachedClass(String className) {
         Class<?> clazz;

From 10c006a80ef3e5d061e329388dd894ecbaa2cf5a Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Thu, 23 Jul 2026 23:10:25 -0300
Subject: [PATCH 6/7] fix: single report under "throw" policy, pre-dispatch
 stackTrace (iOS parity)

Parity round with NativeScript/ios#409's claim-slot commit, closing the
review's cross-platform divergences:

- Single report per failure under uncaughtErrorPolicy: "throw": the full
  report (cancelable event -> hook -> log) now runs at the decision
  point BEFORE the native throw, for both the sync boundary and the
  rejection drain, and the thrown com.tns.NativeScriptException is
  marked reportedToJs (isolate-private brand carried to a Java field by
  ReThrowToJava; set directly for the rejection looper throw) so
  NativeScriptUncaughtExceptionHandler skips the post-mortem
  re-report. Previously a "throw"-policy rejection fired
  unhandledrejection AND a second post-mortem error event. The public
  NativeScriptException.isReportedToJs() lets custom
  Thread.UncaughtExceptionHandler implementations honor the same
  contract.
- preventDefault() now beats the "throw" policy at the sync boundary
  too: the event dispatches before the propagation decision, so a
  prevented error is fully contained with the app alive (iOS behavior).
  The deprecated discard flag disables the throw, matching iOS.
- error.stackTrace / reason.stackTrace (the combined legacy stack, a
  NativeScript extension) are populated BEFORE the error /
  unhandledrejection events dispatch - including the worker branch of
  the rejection drain - so listeners see the same shape the hooks do;
  pinned by new spec assertions mirroring the iOS ones.
- Docs: unified "throw" sequencing and the cross-platform catchability
  note (Android sync at the method boundary; iOS sync only at
  own-frame-reporting boundaries, deferred for block/method callbacks
  and loop-originated errors; escapeException is the portable per-call
  interception tool), plus the Android-only native-crash event
  asymmetry and the interop feature-detection note.

Full suite green on an API 35 arm64 emulator: 604 specs, 0 failures.
---
 docs/error-handling.md                        |  12 +-
 .../app/tests/testUncaughtErrorPolicy.js      |   4 +
 .../app/tests/testUnhandledRejections.js      |   4 +
 .../NativeScriptUncaughtExceptionHandler.java |   7 +-
 .../src/main/cpp/NativeScriptException.cpp    | 132 ++++++++++++++----
 .../java/com/tns/NativeScriptException.java   |  17 +++
 .../src/main/java/com/tns/Runtime.java        |   4 +
 7 files changed, 151 insertions(+), 29 deletions(-)

diff --git a/docs/error-handling.md b/docs/error-handling.md
index c3bfb2f22..217a648f3 100644
--- a/docs/error-handling.md
+++ b/docs/error-handling.md
@@ -120,6 +120,7 @@ throw interop.escapeException(new java.io.IOException("x"));
 - Otherwise a `com.tns.NativeScriptException` is thrown as usual, but with its stack trace replaced by frames synthesized from the JS stack, so crash reporters group it by where it actually happened in JS.
 - The `escapeException()` call site's stack is recorded too — for non-Error values (`escapeException("boom")`) it is the only stack available.
 - Branded escapes bypass `discardUncaughtJsExceptions` (an explicit forward request must reach the caller).
+- The `interop` global is new in this release with `escapeException` as its only member — shared code targeting older runtimes should feature-detect: `global.interop?.escapeException`.
 
 ## Native (Java) API
 
@@ -174,7 +175,7 @@ One policy key in the app's `package.json` (root level) governs what happens to
 | `uncaughtErrorPolicy` | Effect |
 |---|---|
 | `"report"` (default) | Report (event → hook → log) and continue. Never crashes. |
-| `"throw"` | After the (cancelable) event, the error is thrown to the native layer as a real Java exception — `com.tns.NativeScriptException` with the JS frames as its stack trace — and reported through the thread's uncaught-exception path. This typically ends the process (the pre-9.1 default), though a native catch or a custom `UncaughtExceptionHandler` above the boundary can still intercept it, which is why the policy names the mechanism, not a guaranteed crash. Unhandled rejections are thrown from a clean frame on the runtime's looper. |
+| `"throw"` | The full report runs first, at the decision point — cancelable event (`preventDefault()` still fully contains the error, same as iOS), then hook and log — and the error is *then* thrown to the native layer as a real Java exception: `com.tns.NativeScriptException` with the JS frames as its stack trace, marked `isReportedToJs()` so the uncaught-exception path does not report the same failure twice. This typically ends the process (the pre-9.1 default), though the policy names the mechanism, not a guaranteed crash. Unhandled rejections are thrown from a clean frame on the runtime's looper. **Cross-platform note:** on Android the sync throw unwinds through the native caller at the method boundary, so a Java `try/catch` above it can intercept; on iOS the rethrow is synchronous (catchable) only at boundaries that report within their own frame (property accessors, adapter reads) — block/overridden-method callbacks and loop-originated errors fall back to a deferred clean-frame throw. Portable code that needs a native-interceptable exception for a *specific* call should use `interop.escapeException`, which behaves identically on both platforms at every boundary; the policy governs unprevented, already-reported errors only. |
 
 Deprecated (kept for the transition, both emit a logcat warning):
 
@@ -189,8 +190,9 @@ Terminal-path decision table:
 |---|---|---|
 | uncaught error, default (`"report"`) | `__onUncaughtError` | no |
 | uncaught error, `"report"` + `discardUncaughtJsExceptions: true` | `__onDiscardedError` | no |
-| uncaught error, listener called `preventDefault()` | none | no |
-| uncaught error / unhandled rejection, `"throw"`, unprevented | `__onUncaughtError` (via the uncaught-exception path) | yes, normally |
+| uncaught error, listener called `preventDefault()` (either policy) | none | no |
+| uncaught error / unhandled rejection, `"throw"`, unprevented | `__onUncaughtError` (at the decision point, before the throw) | yes, normally |
+| uncaught error / unhandled rejection, `"throw"` + `discardUncaughtJsExceptions: true` | `__onDiscardedError` | no (discard disables the throw, matching iOS) |
 | unhandled rejection / `reportError`, `"report"`, unprevented | `__onUncaughtError` | no |
 | unhandled rejection / `reportError`, `preventDefault()` | none | no |
 
@@ -220,7 +222,9 @@ Java side — for exceptions that never pass through the JS event layer (escaped
 
 - **Containment is boundary-outermost.** The runtime tracks the depth of in-flight JS→Java calls; a throw with JS frames waiting below the boundary propagates (so `try { javaApi.call(cb) } catch` works, with the original JS error object restored across the crossing), and is contained only at an outermost native-initiated entry. `interop.escapeException` and `uncaughtErrorPolicy: "throw"` are the two ways an error crosses that outermost boundary.
 - **Contained callbacks return type defaults.** A throwing overridden method hands its Java caller `null` for reference types and `0`/`false` for primitives (the runtime substitutes the default before unboxing, so no `NullPointerException` from the binding). The error is loudly reported *before* the caller resumes, so logcat shows the real failure ahead of any downstream symptom. If the Java contract genuinely needs the exception, use `interop.escapeException`.
-- Every error is reported exactly once: either the containment point, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), `reportError`, or — under `"throw"` — the thread's uncaught-exception path. Never two of them for the same error.
+- Every error is reported exactly once, at its decision point: the containment boundary, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), or `reportError`. Under `"throw"` the report still happens at the decision point and the thrown `NativeScriptException` carries `isReportedToJs()`, which the uncaught-exception handler honors by not reporting again — one event per failure on both platforms.
+- The legacy `stackTrace` property (combined JS + Java frames, a NativeScript extension) is set on the error/reason **before** the event dispatches, so listeners and hooks see the same shape. The standard `e.error.stack` is always there for spec-shaped code.
 - A rejection that gets a handler before the end-of-turn drain is never reported (and produces no `rejectionhandled` either).
+- **Android-only asymmetry:** the `error` event also fires for *pure-native* Java uncaught exceptions — the app-level `NativeScriptUncaughtExceptionHandler` reports any crashing `Throwable` through `passUncaughtExceptionToJs`, with no iOS analogue. `preventDefault()` there suppresses the error activity and the default (killing) handler, but the throwing thread has already unwound — on the main thread the looper is gone, so realistic recovery is limited to background threads.
 - Module/script evaluation (`runModule`/`runScript`, app bootstrap) is not contained — an app whose main module fails to load still fails loudly.
 - Worker isolates run the same machinery: each worker has its own tracker, drain, event layer and containment.
diff --git a/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
index 96b967220..448601049 100644
--- a/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
+++ b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
@@ -73,6 +73,10 @@ describe("uncaughtErrorPolicy (default: report)", function () {
             expect(received).not.toBeNull();
             // The event carries the actual thrown value.
             expect(received.error).toBe(reason);
+            // The combined `stackTrace` string is populated BEFORE dispatch,
+            // so listeners can read it (not only e.error.stack).
+            expect(typeof received.error.stackTrace).toBe("string");
+            expect(received.error.stackTrace.length).toBeGreaterThan(0);
             // Unprevented, so the legacy hook fired too.
             expect(uncaughtSeen(reason)).toBe(true);
             // And the app is still running.
diff --git a/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js b/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
index ae8c5e6b2..e847aa6d0 100644
--- a/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
+++ b/test-app/app/src/main/assets/app/tests/testUnhandledRejections.js
@@ -132,6 +132,10 @@ describe("unhandled promise rejections", function () {
             expect(received.type).toBe("unhandledrejection");
             expect(received.reason).toBe(reason);
             expect(typeof received.promise.then).toBe("function");
+            // The drain sets a combined `stackTrace` on the (object) reason
+            // BEFORE dispatching the event, so a listener sees it.
+            expect(typeof received.reason.stackTrace).toBe("string");
+            expect(received.reason.stackTrace.length).toBeGreaterThan(0);
             afterQuietTurns(function () {
                 expect(reportedSeen(reason)).toBe(false);
                 done();
diff --git a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
index 7560b1d9d..9cc8c6608 100644
--- a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
+++ b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
@@ -24,7 +24,12 @@ public void uncaughtException(Thread thread, Throwable ex) {
 
         boolean handledByJs = false;
 
-        if (Runtime.isInitialized()) {
+        // An uncaughtErrorPolicy: "throw" exception was already fully reported
+        // to JS (event + hook + log) at the throw decision point - reporting
+        // it again here would double-dispatch the same failure.
+        boolean alreadyReportedToJs = ex instanceof NativeScriptException && ((NativeScriptException) ex).isReportedToJs();
+
+        if (Runtime.isInitialized() && !alreadyReportedToJs) {
             try {
                 if (Util.isDebuggableApp(context)) {
                     System.err.println(errorMessage);
diff --git a/test-app/runtime/src/main/cpp/NativeScriptException.cpp b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
index a7a145d97..3d3898fda 100644
--- a/test-app/runtime/src/main/cpp/NativeScriptException.cpp
+++ b/test-app/runtime/src/main/cpp/NativeScriptException.cpp
@@ -18,6 +18,10 @@ using namespace std;
 using namespace tns;
 using namespace v8;
 
+/* Defined below, next to ContainUncaughtCallbackException. */
+static void MarkReportedToJs(Isolate* isolate, Local<Value> error);
+static bool IsMarkedReportedToJs(Isolate* isolate, Local<Value> error);
+
 NativeScriptException::NativeScriptException(JEnv& env)
     : m_javascriptException(nullptr) {
   m_javaException = JniLocalRef(env.ExceptionOccurred());
@@ -157,6 +161,16 @@ void NativeScriptException::ReThrowToJava() {
           env.GetFieldID(NATIVESCRIPTEXCEPTION_CLASS, "escapedFromJs", "Z");
       env.SetBooleanField(ex, escapedFromJsField, JNI_TRUE);
     }
+
+    // A `uncaughtErrorPolicy: "throw"` propagation whose report already ran
+    // at the boundary: carry the mark so the post-mortem uncaught path does
+    // not report the same failure a second time. `ex` is always a
+    // com.tns.NativeScriptException at this point.
+    if (ex != nullptr && IsMarkedReportedToJs(isolate, errObj)) {
+      static jfieldID reportedToJsField =
+          env.GetFieldID(NATIVESCRIPTEXCEPTION_CLASS, "reportedToJs", "Z");
+      env.SetBooleanField(ex, reportedToJsField, JNI_TRUE);
+    }
   } else if (!m_message.empty()) {
     JniLocalRef msg(env.NewStringUTF(m_message.c_str()));
     JniLocalRef stackTrace(env.NewStringUTF(m_stackTrace.c_str()));
@@ -324,27 +338,37 @@ void NativeScriptException::ReportUnhandledRejection(Isolate* isolate,
                                                      Local<Promise> promise,
                                                      Local<Value> reason,
                                                      const string& stackTrace) {
+  // Populate the legacy `stackTrace` property before dispatch so event
+  // listeners see the same shape the hooks do (matches the sync path).
+  if (reason->IsObject() && !stackTrace.empty()) {
+    auto context = isolate->GetCurrentContext();
+    reason.As<Object>()
+        ->Set(context, V8StringConstants::GetStackTrace(isolate),
+              ArgConverter::ConvertToV8String(isolate, stackTrace))
+        .FromMaybe(false);
+  }
+
   if (ErrorEvents::DispatchUnhandledRejection(isolate, promise, reason)) {
     return;
   }
 
   auto runtime = GetRuntimeOrNull(isolate);
-  if (runtime != nullptr &&
+  bool discard =
+      runtime != nullptr && runtime->GetDiscardUncaughtJsExceptions();
+  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:",
+                  discard ? JNI_TRUE : JNI_FALSE);
+
+  // The report is complete (event + hook + log, exactly once). Under the
+  // "throw" policy the rejection is additionally handed to the native layer;
+  // the thrown exception is marked reported-to-JS so the post-mortem
+  // uncaught path does not report it a second time. The deprecated discard
+  // flag disables the throw, matching iOS.
+  if (runtime != nullptr && !discard &&
       runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
-    // Hand the rejection to the native layer; the post-mortem uncaught path
-    // performs the (single) report, exactly as for a sync uncaught error.
     string message =
         "Unhandled promise rejection: " + ToDetailString(isolate, reason);
     ThrowUncaughtJsErrorToJava(message, stackTrace);
-    return;
   }
-
-  jboolean isDiscarded =
-      (runtime != nullptr && runtime->GetDiscardUncaughtJsExceptions())
-          ? JNI_TRUE
-          : JNI_FALSE;
-  ReportFatalTail(isolate, reason, stackTrace, "Unhandled promise rejection:",
-                  isDiscarded);
 }
 
 void NativeScriptException::ReportFatalTail(Isolate* isolate,
@@ -389,6 +413,38 @@ void NativeScriptException::ReportFatalTail(Isolate* isolate,
   }
 }
 
+/*
+ * Marks a JS error value whose report already ran (event + hook + log), via
+ * an isolate-private symbol. ReThrowToJava carries the mark over to the Java
+ * com.tns.NativeScriptException so the post-mortem uncaught-exception path
+ * does not report the same failure a second time.
+ */
+static Local<Private> GetReportedToJsBrand(Isolate* isolate) {
+  return Private::ForApi(
+      isolate, ArgConverter::ConvertToV8String(isolate, "tns::reportedToJs"));
+}
+
+static void MarkReportedToJs(Isolate* isolate, Local<Value> error) {
+  if (!error->IsObject()) {
+    return;
+  }
+  auto context = isolate->GetCurrentContext();
+  error.As<Object>()
+      ->SetPrivate(context, GetReportedToJsBrand(isolate),
+                   v8::True(isolate))
+      .FromMaybe(false);
+}
+
+static bool IsMarkedReportedToJs(Isolate* isolate, Local<Value> error) {
+  if (!error->IsObject()) {
+    return false;
+  }
+  auto context = isolate->GetCurrentContext();
+  return error.As<Object>()
+      ->HasPrivate(context, GetReportedToJsBrand(isolate))
+      .FromMaybe(false);
+}
+
 bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
                                                              v8::TryCatch& tc) {
   auto runtime = GetRuntimeOrNull(isolate);
@@ -409,7 +465,7 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
   }
 
   // Branded interop.escapeException: an explicit forward to the native
-  // caller - never contained.
+  // caller - never contained, never reported here.
   if (error->IsObject()) {
     JEnv env;
     Interop::EscapedExceptionInfo escapeInfo;
@@ -421,14 +477,10 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
     }
   }
 
-  if (runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
-    // Pre-9.1 semantics: the exception is thrown to the Java caller and the
-    // post-mortem uncaught-exception path performs the (single) report.
-    return false;
-  }
-
-  // Contain: report through the WHATWG pipeline (`error` event -> legacy
-  // hook -> log) and let the caller resume with a default value.
+  // Report through the WHATWG pipeline at the decision point, for both
+  // policies (same sequence as iOS): `error` event first - preventDefault()
+  // fully contains the error even under the "throw" policy - then the legacy
+  // hook and log.
   string errorMessage;
   string stackTrace;
   auto message = tc.Message();
@@ -440,20 +492,42 @@ bool NativeScriptException::ContainUncaughtCallbackException(Isolate* isolate,
     stackTrace = GetStackTraceOfValue(isolate, error);
   }
 
+  // Populate the legacy `stackTrace` property before dispatch so event
+  // listeners see the same shape the hooks do.
+  if (error->IsObject() && !stackTrace.empty()) {
+    auto context = isolate->GetCurrentContext();
+    error.As<Object>()
+        ->Set(context, V8StringConstants::GetStackTrace(isolate),
+              ArgConverter::ConvertToV8String(isolate, stackTrace))
+        .FromMaybe(false);
+  }
+
+  bool discard = runtime->GetDiscardUncaughtJsExceptions();
   {
     // A throwing listener or hook must not escape into the caller.
     v8::TryCatch reportTc(isolate);
-    if (!ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
-      jboolean isDiscarded =
-          runtime->GetDiscardUncaughtJsExceptions() ? JNI_TRUE : JNI_FALSE;
-      ReportFatalTail(isolate, error, stackTrace, "", isDiscarded);
+    if (ErrorEvents::DispatchError(isolate, error, errorMessage, stackTrace)) {
+      tc.Reset();
+      return true;
     }
+    ReportFatalTail(isolate, error, stackTrace, "",
+                    discard ? JNI_TRUE : JNI_FALSE);
     if (reportTc.HasCaught()) {
       DEBUG_WRITE_FORCE(
           "ContainUncaughtCallbackException: exception while reporting");
     }
   }
 
+  // The report is complete (exactly once). Under the "throw" policy the
+  // exception is additionally propagated to the Java caller, marked so the
+  // post-mortem uncaught path skips re-reporting. The deprecated discard
+  // flag disables the throw, matching iOS.
+  if (!discard &&
+      runtime->GetUncaughtErrorPolicy() == Runtime::UncaughtErrorPolicy::Throw) {
+    MarkReportedToJs(isolate, error);
+    return false;
+  }
+
   tc.Reset();
   return true;
 }
@@ -637,6 +711,16 @@ void PromiseRejectionTracker::Drain() {
 
       string stackTrace = GetStackTraceOfValue(isolate, reason);
 
+      // Populate the legacy `stackTrace` property before dispatch so event
+      // listeners see it - covers both the worker and main branches below
+      // (ReportUnhandledRejection's own set is idempotent).
+      if (reason->IsObject() && !stackTrace.empty()) {
+        reason.As<Object>()
+            ->Set(context, V8StringConstants::GetStackTrace(isolate),
+                  ArgConverter::ConvertToV8String(isolate, stackTrace))
+            .FromMaybe(false);
+      }
+
       if (workerWrapper != nullptr) {
         // Dispatch the rejection event on the worker's own global first;
         // preventDefault() there fully handles it. Only when unprevented fall
diff --git a/test-app/runtime/src/main/java/com/tns/NativeScriptException.java b/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
index 5c00875c5..f4d5c571b 100644
--- a/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
+++ b/test-app/runtime/src/main/java/com/tns/NativeScriptException.java
@@ -12,11 +12,28 @@ public class NativeScriptException extends RuntimeException {
      * discardUncaughtJsExceptions handling.
      */
     private boolean escapedFromJs = false;
+    /*
+     * Set (natively or by the runtime) when this exception's failure was
+     * already reported to JS (error/unhandledrejection event, hooks, log) at
+     * the uncaughtErrorPolicy: "throw" decision point. Custom
+     * Thread.UncaughtExceptionHandler implementations should skip
+     * Runtime.passUncaughtExceptionToJs for such exceptions so the failure
+     * is not reported twice.
+     */
+    private boolean reportedToJs = false;
 
     boolean isEscapedFromJs() {
         return escapedFromJs;
     }
 
+    void markReportedToJs() {
+        reportedToJs = true;
+    }
+
+    public boolean isReportedToJs() {
+        return reportedToJs;
+    }
+
     public NativeScriptException() {
         super();
     }
diff --git a/test-app/runtime/src/main/java/com/tns/Runtime.java b/test-app/runtime/src/main/java/com/tns/Runtime.java
index d0b15ad55..291d934f8 100644
--- a/test-app/runtime/src/main/java/com/tns/Runtime.java
+++ b/test-app/runtime/src/main/java/com/tns/Runtime.java
@@ -1375,6 +1375,10 @@ private static Object defaultPrimitiveValue(Class<?> type) {
     private static void throwUncaughtJsErrorOnCurrentThread(String message, String stackTrace) {
         final NativeScriptException ex = new NativeScriptException(message, stackTrace, 0);
         JavaScriptStackTrace.applyFrames(ex, stackTrace, null);
+        // The failure was already reported (event + hook + log) at the throw
+        // decision point - the uncaught-exception handler must not report it
+        // a second time.
+        ex.markReportedToJs();
         android.os.Looper looper = android.os.Looper.myLooper();
         if (looper == null) {
             throw ex;

From 17cd44851d788de299c431e2581e31bd081d6f14 Mon Sep 17 00:00:00 2001
From: Eduardo Speroni <edusperoni@gmail.com>
Date: Fri, 24 Jul 2026 12:24:37 -0300
Subject: [PATCH 7/7] feat: nativeuncaughterror event with main-runtime
 fallback

Separates native-layer deaths from the WHATWG `error` event, completing
the invariant that error/unhandledrejection only fire while the failure
is still containable (the app fully alive, preventDefault() honest).

- New cancelable `nativeuncaughterror` ErrorEvent, dispatched
  synchronously from the uncaught-exception handler for everything that
  reaches it un-marked: pure-native Java crashes, uncaught
  interop.escapeException forwards, bootstrap failures. The handler
  classifies nothing - the simple rule IS the spec. e.error carries the
  wrapped original Throwable via nativeException. preventDefault() is
  best-effort: it skips the error activity and the default (killing)
  handler - meaningful for background-thread crashes (this is what
  keeps the new spec's test runner alive). The legacy __onUncaughtError
  hook still fires for unprevented native crashes (deprecated
  back-compat - it is what Application.uncaughtErrorEvent has received
  for years). This also removes the blanket-preventDefault footgun: a
  generic `error` listener can no longer accidentally spare a process
  whose crashed thread is already gone.

- Main-runtime fallback: crashes on threads with no runtime of their
  own (plugin/executor threads) previously got NO JS reporting at all -
  Runtime.isInitialized() and getCurrentRuntime() are thread-local, so
  the handler silently skipped them. The handler now resolves current
  -> main (new Runtime.getMainRuntime(), set when the workerId-0
  runtime initializes) and enters the main isolate cross-thread (the
  JNI layer takes the v8::Locker).

- Already-reported fast path: an uncaughtErrorPolicy "throw" exception
  (isReportedToJs) now short-circuits the handler before any work -
  no JS roundtrip and no eager stack rendering; the message strings are
  built lazily, only when the logger, debug print or error activity
  actually consumes them.

Testing: new spec crashes a fresh runtime-less Java thread and asserts
nativeuncaughterror arrives via the main-runtime fallback carrying the
original Throwable, `error` never fires (invariant pin), the prevented
report skips the legacy hook, and the process survives. Full suite
green on an API 35 arm64 emulator: 605 specs, 0 failures.
---
 docs/error-handling.md                        | 19 +++-
 .../app/tests/testUncaughtErrorPolicy.js      | 93 +++++++++++++++++++
 .../NativeScriptUncaughtExceptionHandler.java | 62 +++++++++----
 .../tns/tests/UncaughtErrorPolicyTest.java    | 14 +++
 test-app/runtime/src/main/cpp/ErrorEvents.cpp | 41 +++++++-
 test-app/runtime/src/main/cpp/ErrorEvents.h   | 13 +++
 test-app/runtime/src/main/cpp/Runtime.cpp     | 20 +++-
 test-app/runtime/src/main/cpp/Runtime.h       |  4 +
 .../src/main/java/com/tns/Runtime.java        | 21 ++++-
 9 files changed, 257 insertions(+), 30 deletions(-)

diff --git a/docs/error-handling.md b/docs/error-handling.md
index 217a648f3..de84aa6cc 100644
--- a/docs/error-handling.md
+++ b/docs/error-handling.md
@@ -14,6 +14,7 @@ The runtime implements the WHATWG error model at the global level: uncaught Java
 | `throw interop.escapeException(x)` in JS called from Java | Never contained. The original Java `Throwable` carried by `x` is rethrown **unwrapped** to the Java caller (JS trace attached as a suppressed `com.tns.JavaScriptStackTrace`); with no underlying `Throwable`, a `com.tns.NativeScriptException` whose stack trace is the JS frames. |
 | `reportError(x)` | Routed through the same pipeline as an uncaught error; never crashes. |
 | `uncaughtErrorPolicy: "throw"` | Restores the pre-9.1 behavior: unprevented uncaught errors are thrown to the native layer as real Java exceptions (which typically ends the process via the default uncaught-exception handler). |
+| Uncaught **native** exception (a Java thread crashing — pure-native errors, uncaught `escapeException` forwards, bootstrap failures) | Cancelable `nativeuncaughterror` event, dispatched synchronously from the uncaught-exception handler (falling back to the **main runtime** for threads with no runtime of their own) → `__onUncaughtError` hook → error activity in debug → process exits. `preventDefault()` skips the error activity and the killing handler — meaningful for background-thread crashes. |
 
 ## JavaScript API
 
@@ -38,6 +39,19 @@ globalThis.addEventListener("rejectionhandled", (e) => {
   // to a promise whose rejection was already reported; carries the original
   // reason. Not cancelable.
 });
+
+globalThis.addEventListener("nativeuncaughterror", (e) => {
+  // The native-layer death notification: an uncaught NATIVE exception (a Java
+  // thread crashing) - not a JS error. e.error.nativeException is the original
+  // Throwable. Dispatched synchronously from the uncaught-exception handler;
+  // crashes on threads with no runtime of their own report through the main
+  // runtime. preventDefault() is BEST-EFFORT: on Android it skips the error
+  // activity and the default (killing) handler - realistic for background
+  // threads (the crashed thread itself is gone; a main-thread crash has
+  // already lost its looper). On iOS termination is unavoidable and the
+  // cancel is ignored.
+  crashReporter.capture(e.error);
+});
 ```
 
 Notes:
@@ -198,7 +212,7 @@ Terminal-path decision table:
 
 ## Crash reporter integration
 
-JS side — attach both the JS and native exception from one listener:
+JS side — two listeners with distinct roles: `error` for recoverable JS failures, `nativeuncaughterror` for native-layer deaths. Blanket `preventDefault()` belongs only on the former; suppressing the latter keeps a process alive whose crashed thread is already gone.
 
 ```js
 globalThis.addEventListener("error", (e) => {
@@ -225,6 +239,7 @@ Java side — for exceptions that never pass through the JS event layer (escaped
 - Every error is reported exactly once, at its decision point: the containment boundary, the rejection drain (once per looper turn, scheduled on the runtime's `ALooper`), or `reportError`. Under `"throw"` the report still happens at the decision point and the thrown `NativeScriptException` carries `isReportedToJs()`, which the uncaught-exception handler honors by not reporting again — one event per failure on both platforms.
 - The legacy `stackTrace` property (combined JS + Java frames, a NativeScript extension) is set on the error/reason **before** the event dispatches, so listeners and hooks see the same shape. The standard `e.error.stack` is always there for spec-shaped code.
 - A rejection that gets a handler before the end-of-turn drain is never reported (and produces no `rejectionhandled` either).
-- **Android-only asymmetry:** the `error` event also fires for *pure-native* Java uncaught exceptions — the app-level `NativeScriptUncaughtExceptionHandler` reports any crashing `Throwable` through `passUncaughtExceptionToJs`, with no iOS analogue. `preventDefault()` there suppresses the error activity and the default (killing) handler, but the throwing thread has already unwound — on the main thread the looper is gone, so realistic recovery is limited to background threads.
+- **`error` never lies about recoverability.** The invariant across the whole model: `error`/`unhandledrejection` fire only while the failure is still containable (the app is fully alive, `preventDefault()` really means "handled, continue"); `nativeuncaughterror` fires when the native layer is already dying. The uncaught-exception handler classifies nothing: *everything* that reaches it un-marked — pure-native crashes, uncaught `escapeException` forwards, bootstrap failures — dispatches `nativeuncaughterror`. Exceptions already reported at a `"throw"`-policy decision point (`NativeScriptException.isReportedToJs()`) are skipped entirely.
+- **Runtime-less threads report through the main runtime.** `NativeScriptUncaughtExceptionHandler` falls back to `Runtime.getMainRuntime()` when the crashing thread has no runtime of its own, entering the main isolate cross-thread (the JNI layer takes the `v8::Locker`), so plugin/executor-thread crashes are no longer invisible to JS. The legacy `__onUncaughtError` hook keeps firing for unprevented native crashes (deprecated back-compat — it is what `Application.uncaughtErrorEvent` has received for years).
 - Module/script evaluation (`runModule`/`runScript`, app bootstrap) is not contained — an app whose main module fails to load still fails loudly.
 - Worker isolates run the same machinery: each worker has its own tracker, drain, event layer and containment.
diff --git a/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
index 448601049..655bd76fb 100644
--- a/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
+++ b/test-app/app/src/main/assets/app/tests/testUncaughtErrorPolicy.js
@@ -172,3 +172,96 @@ describe("uncaughtErrorPolicy (default: report)", function () {
     // whose stack trace points at the JS frames. Default-off behavior is
     // covered by every other suite here.
 });
+
+describe("nativeuncaughterror", function () {
+    // The native-layer death notification: fired synchronously from the
+    // uncaught-exception handler for exceptions the JS layer does not own.
+    // preventDefault() is best-effort - on Android it skips the error
+    // activity and the default (killing) handler, which is what keeps the
+    // test runner alive here.
+    var previousUncaughtHook;
+    var uncaught;
+    var addedGlobalListeners;
+
+    beforeEach(function () {
+        previousUncaughtHook = global.__onUncaughtError;
+        uncaught = [];
+        global.__onUncaughtError = function (error) {
+            uncaught.push(error);
+        };
+        addedGlobalListeners = [];
+    });
+
+    afterEach(function () {
+        global.__onUncaughtError = previousUncaughtHook;
+        for (var i = 0; i < addedGlobalListeners.length; i++) {
+            var l = addedGlobalListeners[i];
+            global.removeEventListener(l.type, l.handler);
+        }
+        addedGlobalListeners = [];
+    });
+
+    function onGlobal(type, handler) {
+        global.addEventListener(type, handler);
+        addedGlobalListeners.push({ type: type, handler: handler });
+    }
+
+    function pollUntil(predicate, cb) {
+        var turns = 0;
+        (function poll() {
+            if (predicate() || turns >= 50) {
+                cb();
+                return;
+            }
+            turns++;
+            setTimeout(poll, 10);
+        })();
+    }
+
+    it("fires for a native crash on a runtime-less thread (via the main runtime); preventDefault() spares the process", function (done) {
+        var marker = "native-crash-on-alien-thread";
+        var received = null;
+        var errorEventFired = false;
+
+        onGlobal("nativeuncaughterror", function (e) {
+            if (e.message && e.message.indexOf(marker) !== -1) {
+                received = e;
+                // Best-effort cancel: skip the error activity and the default
+                // (killing) handler. Without this the test runner would die.
+                e.preventDefault();
+            }
+        });
+        onGlobal("error", function (e) {
+            if (e.message && e.message.indexOf(marker) !== -1) {
+                errorEventFired = true;
+            }
+        });
+
+        com.tns.tests.UncaughtErrorPolicyTest.throwOnNewThread(marker);
+
+        pollUntil(function () { return received !== null; }, function () {
+            expect(received).not.toBeNull();
+            expect(received instanceof ErrorEvent).toBe(true);
+            expect(received.type).toBe("nativeuncaughterror");
+            // The event carries the wrapped original Java exception.
+            expect(received.error.nativeException).toBeDefined();
+            expect(received.error.nativeException.getMessage()).toBe(marker);
+            // `error` keeps its still-containable invariant: it never fires
+            // for a native-layer death.
+            expect(errorEventFired).toBe(false);
+            // Prevented, so the legacy hook did not fire either.
+            var hookSaw = false;
+            for (var i = 0; i < uncaught.length; i++) {
+                var err = uncaught[i];
+                if (err && err.message === marker) {
+                    hookSaw = true;
+                    break;
+                }
+            }
+            expect(hookSaw).toBe(false);
+            // And the app survived the background-thread crash.
+            expect(1 + 1).toBe(2);
+            done();
+        });
+    });
+});
diff --git a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
index 9cc8c6608..cefac2d48 100644
--- a/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
+++ b/test-app/app/src/main/java/com/tns/NativeScriptUncaughtExceptionHandler.java
@@ -18,48 +18,65 @@ public NativeScriptUncaughtExceptionHandler(Logger logger, Context context) {
 
     @Override
     public void uncaughtException(Thread thread, Throwable ex) {
-        String currentThreadMessage = String.format("An uncaught Exception occurred on \"%s\" thread.\n%s\n", thread.getName(), ex.getMessage());
-        String stackTraceErrorMessage = Runtime.getStackTraceErrorMessage(ex);
-        String errorMessage = String.format("%s\nStackTrace:\n%s", currentThreadMessage, stackTraceErrorMessage);
-
-        boolean handledByJs = false;
-
         // An uncaughtErrorPolicy: "throw" exception was already fully reported
         // to JS (event + hook + log) at the throw decision point - reporting
-        // it again here would double-dispatch the same failure.
+        // it again here would double-dispatch the same failure. Checked first
+        // so the already-reported path does no work at all: no JS roundtrip
+        // and no eager stack rendering (the message strings below are built
+        // lazily, only when something actually consumes them).
         boolean alreadyReportedToJs = ex instanceof NativeScriptException && ((NativeScriptException) ex).isReportedToJs();
 
-        if (Runtime.isInitialized() && !alreadyReportedToJs) {
-            try {
-                if (Util.isDebuggableApp(context)) {
-                    System.err.println(errorMessage);
-                }
+        String errorMessage = null;
+        boolean handledByJs = false;
+
+        if (!alreadyReportedToJs) {
+            // Resolve the reporting runtime FIRST: Runtime.isInitialized() is
+            // thread-local, so gating on it would silently skip reporting for
+            // crashes on threads with no runtime of their own. Those fall back
+            // to the main runtime's isolate (the JNI layer takes the
+            // v8::Locker, so entering it cross-thread is safe).
+            Runtime runtime = Runtime.getCurrentRuntime();
+            if (runtime == null) {
+                runtime = Runtime.getMainRuntime();
+            }
+
+            if (runtime != null && runtime.isInitializedImpl()) {
+                try {
+                    String stackTraceErrorMessage = Runtime.getStackTraceErrorMessage(ex);
+                    errorMessage = buildErrorMessage(thread, ex, stackTraceErrorMessage);
 
-                Runtime runtime = Runtime.getCurrentRuntime();
+                    if (Util.isDebuggableApp(context)) {
+                        System.err.println(errorMessage);
+                    }
 
-                if (runtime != null) {
                     handledByJs = runtime.passUncaughtExceptionToJs(ex, ex.getMessage(), stackTraceErrorMessage, Runtime.getJSStackTrace(ex));
-                }
-            } catch (Throwable t) {
-                if (Util.isDebuggableApp(context)) {
-                    t.printStackTrace();
+                } catch (Throwable t) {
+                    if (Util.isDebuggableApp(context)) {
+                        t.printStackTrace();
+                    }
                 }
             }
         }
 
         if (logger.isEnabled()) {
+            if (errorMessage == null) {
+                errorMessage = buildErrorMessage(thread, ex, Runtime.getStackTraceErrorMessage(ex));
+            }
             logger.write("Uncaught Exception Message=" + errorMessage);
         }
 
         if (handledByJs) {
-            // A JS `error` event listener called preventDefault() - the
-            // exception is fully handled: no error activity, no crash.
+            // A JS `nativeuncaughterror` listener called preventDefault() -
+            // the exception is fully handled: no error activity, no crash.
             return;
         }
 
         boolean res = false;
 
         if (Util.isDebuggableApp(context)) {
+            if (errorMessage == null) {
+                errorMessage = buildErrorMessage(thread, ex, Runtime.getStackTraceErrorMessage(ex));
+            }
             try {
                 Class<?> ErrReport = null;
                 java.lang.reflect.Method startActivity = null;
@@ -82,4 +99,9 @@ public void uncaughtException(Thread thread, Throwable ex) {
             defaultHandler.uncaughtException(thread, ex);
         }
     }
+
+    private static String buildErrorMessage(Thread thread, Throwable ex, String stackTraceErrorMessage) {
+        String currentThreadMessage = String.format("An uncaught Exception occurred on \"%s\" thread.\n%s\n", thread.getName(), ex.getMessage());
+        return String.format("%s\nStackTrace:\n%s", currentThreadMessage, stackTraceErrorMessage);
+    }
 }
diff --git a/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java b/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java
index 5244bce03..4567d17b5 100644
--- a/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java
+++ b/test-app/app/src/main/java/com/tns/tests/UncaughtErrorPolicyTest.java
@@ -25,4 +25,18 @@ public void run() {
     public static void invoke(Runnable runnable) {
         runnable.run();
     }
+
+    /*
+     * Crashes a brand-new thread that has no runtime of its own: the default
+     * uncaught-exception handler must fall back to the main runtime and
+     * dispatch `nativeuncaughterror` there.
+     */
+    public static void throwOnNewThread(final String message) {
+        new Thread(new Runnable() {
+            @Override
+            public void run() {
+                throw new RuntimeException(message);
+            }
+        }).start();
+    }
 }
diff --git a/test-app/runtime/src/main/cpp/ErrorEvents.cpp b/test-app/runtime/src/main/cpp/ErrorEvents.cpp
index eb9cb19e5..56ef451cf 100644
--- a/test-app/runtime/src/main/cpp/ErrorEvents.cpp
+++ b/test-app/runtime/src/main/cpp/ErrorEvents.cpp
@@ -127,8 +127,17 @@ void ErrorEvents::Init(Local<Context> context) {
         });
         globalTarget.dispatchEvent(ev);
       }
+      function dispatchNativeUncaughtError(error, message, stack) {
+        var ev = new ErrorEvent("nativeuncaughterror", {
+          message: message !== undefined && message !== null ? String(message) : "",
+          error: error,
+          cancelable: true
+        });
+        globalTarget.dispatchEvent(ev);
+        return ev.defaultPrevented;
+      }
 
-      return [dispatchErrorEvent, dispatchUnhandledRejection, dispatchRejectionHandled];
+      return [dispatchErrorEvent, dispatchUnhandledRejection, dispatchRejectionHandled, dispatchNativeUncaughtError];
     })
     )js";
 
@@ -168,16 +177,18 @@ void ErrorEvents::Init(Local<Context> context) {
     }
 
     auto closures = iifeResult.As<Array>();
-    Local<Value> errorFn, rejectionFn, handledFn;
+    Local<Value> errorFn, rejectionFn, handledFn, nativeUncaughtFn;
     if (!closures->Get(context, 0).ToLocal(&errorFn) || !errorFn->IsFunction() ||
         !closures->Get(context, 1).ToLocal(&rejectionFn) || !rejectionFn->IsFunction() ||
-        !closures->Get(context, 2).ToLocal(&handledFn) || !handledFn->IsFunction()) {
+        !closures->Get(context, 2).ToLocal(&handledFn) || !handledFn->IsFunction() ||
+        !closures->Get(context, 3).ToLocal(&nativeUncaughtFn) || !nativeUncaughtFn->IsFunction()) {
         throw NativeScriptException("ErrorEvents::Init: unexpected dispatch closures");
     }
 
     runtime->DispatchErrorEventFunc().Reset(isolate, errorFn.As<Function>());
     runtime->DispatchUnhandledRejectionFunc().Reset(isolate, rejectionFn.As<Function>());
     runtime->DispatchRejectionHandledFunc().Reset(isolate, handledFn.As<Function>());
+    runtime->DispatchNativeUncaughtErrorFunc().Reset(isolate, nativeUncaughtFn.As<Function>());
 }
 
 bool ErrorEvents::DispatchError(Isolate* isolate, Local<Value> error,
@@ -224,6 +235,30 @@ bool ErrorEvents::DispatchUnhandledRejection(Isolate* isolate,
     return success && !result.IsEmpty() && result->BooleanValue(isolate);
 }
 
+bool ErrorEvents::DispatchNativeUncaughtError(Isolate* isolate,
+                                              Local<Value> error,
+                                              const string& messageString,
+                                              const string& stack) {
+    auto runtime = GetRuntimeOrNull(isolate);
+    if (runtime == nullptr || runtime->DispatchNativeUncaughtErrorFunc().IsEmpty()) {
+        return false;
+    }
+
+    auto context = isolate->GetCurrentContext();
+    auto dispatch = runtime->DispatchNativeUncaughtErrorFunc().Get(isolate);
+    Local<Value> args[] = {error,
+                           ArgConverter::ConvertToV8String(isolate, messageString),
+                           ArgConverter::ConvertToV8String(isolate, stack)};
+    Local<Value> result;
+    TryCatch tc(isolate);
+    bool success = dispatch->Call(context, context->Global(), 3, args).ToLocal(&result);
+    if (tc.HasCaught()) {
+        DEBUG_WRITE_FORCE("ErrorEvents: exception while dispatching `nativeuncaughterror` event");
+        return false;
+    }
+    return success && !result.IsEmpty() && result->BooleanValue(isolate);
+}
+
 void ErrorEvents::DispatchRejectionHandled(Isolate* isolate,
                                            Local<Promise> promise,
                                            Local<Value> reason) {
diff --git a/test-app/runtime/src/main/cpp/ErrorEvents.h b/test-app/runtime/src/main/cpp/ErrorEvents.h
index fead37cf1..624c7b051 100644
--- a/test-app/runtime/src/main/cpp/ErrorEvents.h
+++ b/test-app/runtime/src/main/cpp/ErrorEvents.h
@@ -51,6 +51,19 @@ class ErrorEvents {
     static void DispatchRejectionHandled(v8::Isolate* isolate,
                                          v8::Local<v8::Promise> promise,
                                          v8::Local<v8::Value> reason);
+
+    /*
+     * Dispatches the `nativeuncaughterror` ErrorEvent - the native-layer
+     * death notification, fired synchronously from the uncaught-exception
+     * handler for exceptions the JS layer does not own (pure-native crashes,
+     * uncaught escapeException forwards, bootstrap failures). Returns true
+     * when a listener called preventDefault() - best-effort semantics: on
+     * Android it skips the error activity and the default (killing) handler.
+     */
+    static bool DispatchNativeUncaughtError(v8::Isolate* isolate,
+                                            v8::Local<v8::Value> error,
+                                            const std::string& messageString,
+                                            const std::string& stack);
 };
 
 }  // namespace tns
diff --git a/test-app/runtime/src/main/cpp/Runtime.cpp b/test-app/runtime/src/main/cpp/Runtime.cpp
index 201dc061a..4f0cc262a 100644
--- a/test-app/runtime/src/main/cpp/Runtime.cpp
+++ b/test-app/runtime/src/main/cpp/Runtime.cpp
@@ -561,11 +561,22 @@ jboolean Runtime::PassExceptionToJsNative(JNIEnv* env, jobject obj,
                 ArgConverter::jstringToV8String(isolate, jsStackTrace));
   }
 
-  // Give WHATWG `error` event listeners a chance first; preventDefault()
-  // fully handles the report - no __on*Error shim, and the Java caller is
-  // told the exception was handled.
+  // Give WHATWG listeners a chance first; preventDefault() fully handles the
+  // report - no __on*Error shim, and the Java caller is told the exception
+  // was handled. The discard path (a containment variant - the app is alive)
+  // dispatches the `error` event; the uncaught path is the post-mortem
+  // native-layer death notification and dispatches `nativeuncaughterror`,
+  // preserving the invariant that `error` only fires while the failure is
+  // still containable.
   string stackTraceStr = ArgConverter::jstringToString(fullStackTrace);
-  if (ErrorEvents::DispatchError(isolate, errObj, errMsg, stackTraceStr)) {
+  bool prevented;
+  if (isDiscarded == JNI_TRUE) {
+    prevented = ErrorEvents::DispatchError(isolate, errObj, errMsg, stackTraceStr);
+  } else {
+    prevented = ErrorEvents::DispatchNativeUncaughtError(isolate, errObj, errMsg,
+                                                         stackTraceStr);
+  }
+  if (prevented) {
     return JNI_TRUE;
   }
 
@@ -1033,6 +1044,7 @@ void Runtime::DestroyRuntime() {
   m_dispatchErrorEventFunc.Reset();
   m_dispatchUnhandledRejectionFunc.Reset();
   m_dispatchRejectionHandledFunc.Reset();
+  m_dispatchNativeUncaughtErrorFunc.Reset();
   tns::disposeIsolate(m_isolate);
 }
 
diff --git a/test-app/runtime/src/main/cpp/Runtime.h b/test-app/runtime/src/main/cpp/Runtime.h
index 9fad92f65..ec80975f9 100644
--- a/test-app/runtime/src/main/cpp/Runtime.h
+++ b/test-app/runtime/src/main/cpp/Runtime.h
@@ -145,6 +145,9 @@ class Runtime {
         v8::Global<v8::Function>& DispatchRejectionHandledFunc() {
             return m_dispatchRejectionHandledFunc;
         }
+        v8::Global<v8::Function>& DispatchNativeUncaughtErrorFunc() {
+            return m_dispatchNativeUncaughtErrorFunc;
+        }
         PromiseRejectionTracker* PromiseRejections() const {
             return m_promiseRejections.get();
         }
@@ -199,6 +202,7 @@ class Runtime {
         v8::Global<v8::Function> m_dispatchErrorEventFunc;
         v8::Global<v8::Function> m_dispatchUnhandledRejectionFunc;
         v8::Global<v8::Function> m_dispatchRejectionHandledFunc;
+        v8::Global<v8::Function> m_dispatchNativeUncaughtErrorFunc;
         std::unique_ptr<PromiseRejectionTracker> m_promiseRejections;
 
         UncaughtErrorPolicy m_uncaughtErrorPolicy = UncaughtErrorPolicy::Report;
diff --git a/test-app/runtime/src/main/java/com/tns/Runtime.java b/test-app/runtime/src/main/java/com/tns/Runtime.java
index 291d934f8..4a02c22c4 100644
--- a/test-app/runtime/src/main/java/com/tns/Runtime.java
+++ b/test-app/runtime/src/main/java/com/tns/Runtime.java
@@ -201,6 +201,13 @@ public int compare(Method lhs, Method rhs) {
 
     private static AtomicInteger nextRuntimeId = new AtomicInteger(0);
     private final static ThreadLocal<Runtime> currentRuntime = new ThreadLocal<Runtime>();
+    /*
+     * The main (workerId 0) runtime. Fallback reporting target for uncaught
+     * exceptions on threads that have no runtime of their own (see
+     * NativeScriptUncaughtExceptionHandler): entering the main isolate from an
+     * arbitrary crashing thread is safe - the JNI layer takes the v8::Locker.
+     */
+    private static volatile Runtime mainRuntime;
     private final static Map<Integer, Runtime> runtimeCache = new ConcurrentHashMap<>();
     public static boolean nativeLibraryLoaded;
 
@@ -577,10 +584,22 @@ private static Runtime initRuntime(DynamicConfiguration dynamicConfiguration) {
             throw t;
         }
 
+        if (runtime.workerId == 0) {
+            mainRuntime = runtime;
+        }
+
         return runtime;
     }
 
-    private boolean isInitializedImpl() {
+    /**
+     * The main runtime, or null before initialization. Used as the reporting
+     * fallback for uncaught exceptions on threads with no runtime of their own.
+     */
+    public static Runtime getMainRuntime() {
+        return mainRuntime;
+    }
+
+    boolean isInitializedImpl() {
         return initialized;
     }