Support async WebAssembly: pump V8 foreground tasks + relax TextDecoder labels

Core/AppRuntime/Source/AppRuntime.cpp

@@ -4,13 +4,37 @@
 #include <arcana/threading/dispatcher.h>
 
 #include <cassert>
+#include <chrono>
 #include <optional>
 #include <mutex>
 #include <thread>
 #include <type_traits>
 
 namespace Babylon
 {
+    namespace internal
+    {
+        // Per-thread post-tick hook installed by engine-specific code (e.g.
+        // the V8 environment tier) so it can drain engine-managed task
+        // queues that are NOT part of the AppRuntime dispatcher.
+        //
+        // Motivating case: V8's foreground task runner holds the
+        // continuations for asynchronous WebAssembly compilation
+        // (WebAssembly.instantiate / .compile). Those tasks are scheduled
+        // by V8's background worker threads when WASM compilation
+        // completes and must be drained by the embedder via
+        // v8::platform::PumpMessageLoop. Without that drain, any code
+        // that awaits async WASM (Draco / Basis / KTX2 emscripten glue,
+        // etc.) freezes forever because the resolving Promise's
+        // continuation is never invoked.
+        thread_local std::function<void()> g_postTickHook;
+
+        void SetPostTickHook(std::function<void()> hook)
+        {
+            g_postTickHook = std::move(hook);
+        }
+    }
+
     class AppRuntime::Impl
     {
     public:
@@ -82,9 +106,26 @@ namespace Babylon
 
         m_impl->m_dispatcher.set_affinity(std::this_thread::get_id());
 
+        // The loop uses non-blocking tick + brief sleep instead of
+        // blocking_tick so we can periodically pump the engine's own
+        // task queue (see internal::g_postTickHook). A blocking_tick
+        // would only wake on AppRuntime-side dispatches, missing V8
+        // platform tasks (e.g. async WebAssembly compile completions
+        // posted from V8 worker threads) and freezing any code that
+        // awaits them.
         while (!m_impl->m_cancelSource.cancelled())
         {
-            m_impl->m_dispatcher.blocking_tick(m_impl->m_cancelSource);
+            const bool ranWork = m_impl->m_dispatcher.tick(m_impl->m_cancelSource);
+
+            if (internal::g_postTickHook)
+            {
+                internal::g_postTickHook();
+            }
+
+            if (!ranWork)
+            {
+                std::this_thread::sleep_for(std::chrono::milliseconds(1));
+            }
         }
 
         // The dispatcher can be non-empty if something is dispatched after cancellation.

Core/AppRuntime/Source/AppRuntime_Chakra.cpp

@@ -10,6 +10,14 @@
 
 namespace Babylon
 {
+    namespace internal
+    {
+        // Defined in AppRuntime.cpp; the engine-agnostic dispatcher loop
+        // calls this between ticks so we can pump engine-managed task
+        // queues that are not part of the AppRuntime dispatcher.
+        void SetPostTickHook(std::function<void()> hook);
+    }
+
     namespace
     {
         void ThrowIfFailed(JsErrorCode errorCode)
@@ -38,6 +46,18 @@ namespace Babylon
         JsContextRef context;
         ThrowIfFailed(JsCreateContext(jsRuntime, &context));
         ThrowIfFailed(JsSetCurrentContext(context));
+
+        // Chakra/EdgeJsRt route promise microtasks (Promise.then jobs,
+        // await continuations) through this callback. Each job is wrapped
+        // in a Dispatch onto the AppRuntime queue, where it runs on the
+        // next tick.
+        //
+        // ASYNC WASM NOTE: ChakraCore's WebAssembly.compile / .instantiate
+        // do not use background worker threads in the public JSRT API --
+        // the compile runs synchronously within the Promise's resolve
+        // step, which itself fires through this PromiseContinuationCallback.
+        // No separate platform-task pump is required for async WASM here,
+        // unlike V8.
         ThrowIfFailed(JsSetPromiseContinuationCallback(
             [](JsValueRef task, void* callbackState) {
                 ThrowIfFailed(JsAddRef(task, nullptr));
@@ -63,6 +83,13 @@ namespace Babylon
 
         Napi::Env env = Napi::Attach();
 
+        // No post-tick hook needed for Chakra: there is no embedder-owned
+        // platform task queue analogous to V8's foreground task runner,
+        // and ChakraCore's WASM completion is delivered through the
+        // promise-continuation callback above. If a future host needs to
+        // drain a Chakra-managed work queue here, install via
+        // internal::SetPostTickHook.
+
         Run(env);
 
         ThrowIfFailed(JsSetCurrentContext(JS_INVALID_REFERENCE));

Core/AppRuntime/Source/AppRuntime_JSI.cpp

@@ -6,6 +6,24 @@
 
 namespace
 {
+    // ASYNC WASM NOTE: V8JSI exposes V8's foreground task runner as an
+    // injectable JSITaskRunner. V8 schedules asynchronous work --
+    // including WebAssembly.compile / .instantiate completion callbacks
+    // posted from the WASM compile worker threads -- via postTask on
+    // this runner.
+    //
+    // TaskRunnerAdapter routes each posted task into the AppRuntime
+    // dispatcher (m_runtime.Dispatch), where it will run on the next
+    // tick of the dispatcher loop. Because each tick also drains JS
+    // microtasks (V8JSI auto-pumps microtasks at the end of every JS
+    // entry it makes for us), the resolving Promise's continuation runs
+    // immediately after the WASM completion task fires.
+    //
+    // This is the moral equivalent of the explicit
+    // PumpMessageLoop + PerformMicrotaskCheckpoint hook installed by the
+    // plain-V8 AppRuntime_V8.cpp -- here V8JSI owns the platform and we
+    // bridge its foreground task runner directly. No additional
+    // post-tick hook is required for async WASM to settle on V8JSI.
     class TaskRunnerAdapter : public v8runtime::JSITaskRunner
     {
     public:

Core/AppRuntime/Source/AppRuntime_JavaScriptCore.cpp

@@ -3,6 +3,14 @@
 
 namespace Babylon
 {
+    namespace internal
+    {
+        // Defined in AppRuntime.cpp; the engine-agnostic dispatcher loop
+        // calls this between ticks so we can pump engine-managed task
+        // queues that are not part of the AppRuntime dispatcher.
+        void SetPostTickHook(std::function<void()> hook);
+    }
+
     void AppRuntime::RunEnvironmentTier(const char*)
     {
         auto globalContext = JSGlobalContextCreateInGroup(nullptr, nullptr);
@@ -16,6 +24,38 @@ namespace Babylon
 
         Napi::Env env = Napi::Attach(globalContext);
 
+        // ASYNC WASM NOTE: JavaScriptCore implements
+        // WebAssembly.instantiate / .compile with a background-thread
+        // compile pool (Wasm::Worklist). On completion, JSC posts the
+        // resolving Promise's continuation onto the JS thread's
+        // microtask queue.
+        //
+        // JSC's public C API (JSC.framework) does NOT expose a way to
+        // explicitly pump that microtask queue from the embedder; the
+        // queue is drained automatically each time JS execution returns
+        // to JSC (e.g. after every JSValueProtect, JSObjectCallAsFunction,
+        // JSEvaluateScript). Because the AppRuntime dispatcher hands
+        // control to JSC on every Dispatch() execution (via
+        // Napi::Attach's wrapping of JS calls), the microtask queue is
+        // implicitly drained for each tick.
+        //
+        // This means async WASM continuations resolve naturally as long
+        // as new JS work is dispatched after the background compile
+        // completes. For a pure "fire-and-await" pattern where the
+        // embedder issues no further dispatches between
+        // WebAssembly.instantiate and its resolution, an empty
+        // dispatch can be queued to nudge the queue. This is the only
+        // scenario where async WASM could appear to stall on JSC, and it
+        // matches the pattern actually used by Babylon.js loaders
+        // (load-and-render is followed by per-frame renders that keep
+        // dispatching).
+        //
+        // No post-tick hook is installed because the public JSC API has
+        // no standalone "drain microtasks" entry point. If a future host
+        // observes async-WASM stalls on JSC, the recommended workaround
+        // is to dispatch periodic no-op JS calls from the host (e.g. a
+        // render tick) which forces a microtask drain.
+
         Run(env);
 
         JSGlobalContextRelease(globalContext);

Core/AppRuntime/Source/AppRuntime_V8.cpp

@@ -11,6 +11,13 @@
 
 namespace Babylon
 {
+    namespace internal
+    {
+        // Defined in AppRuntime.cpp; the engine-agnostic dispatcher loop
+        // calls this between ticks so we can pump V8-side foreground tasks.
+        void SetPostTickHook(std::function<void()> hook);
+    }
+
     namespace
     {
         class Module final
@@ -81,6 +88,21 @@ namespace Babylon
 
             Napi::Env env = Napi::Attach(context);
 
+            // Install the post-tick hook so the dispatcher loop drains V8's
+            // foreground task runner (which holds async WebAssembly compile
+            // continuations and other deferred Platform-scheduled work)
+            // and any pending microtasks after each AppRuntime dispatch.
+            // Without this, async WASM-using code (Draco glTF extension,
+            // Basis, KTX2, ...) freezes because its resolving Promise
+            // continuation is never invoked.
+            v8::Platform* platformPtr = &Module::Instance().Platform();
+            internal::SetPostTickHook([platformPtr, isolate]() {
+                while (v8::platform::PumpMessageLoop(
+                    platformPtr, isolate,
+                    v8::platform::MessageLoopBehavior::kDoNotWait)) {}
+                isolate->PerformMicrotaskCheckpoint();
+            });
+
 #ifdef ENABLE_V8_INSPECTOR
             std::optional<V8InspectorAgent> agent;
             if (m_options.EnableDebugger)
@@ -105,6 +127,11 @@ namespace Babylon
 #endif
 
             Napi::Detach(env);
+
+            // Drop the hook before the isolate (captured by reference)
+            // goes out of scope; otherwise a stale capture could fire
+            // during teardown.
+            internal::SetPostTickHook(nullptr);
         }
 
         // Destroy the isolate.

Polyfills/TextDecoder/Source/TextDecoder.cpp

@@ -33,7 +33,26 @@ namespace
             if (info.Length() > 0 && info[0].IsString())
             {
                 auto encoding = info[0].As<Napi::String>().Utf8Value();
-                if (encoding != "utf-8" && encoding != "UTF-8")
+
+                // Normalize to lowercase to compare against the
+                // WHATWG Encoding spec aliases for utf-8.
+                // https://encoding.spec.whatwg.org/#names-and-labels
+                // All of these labels resolve to "utf-8" per the spec:
+                std::string normalized = encoding;
+                for (auto& c : normalized)
+                {
+                    if (c >= 'A' && c <= 'Z')
+                    {
+                        c = static_cast<char>(c - 'A' + 'a');
+                    }
+                }
+
+                if (normalized != "utf-8" &&
+                    normalized != "utf8" &&
+                    normalized != "unicode-1-1-utf-8" &&
+                    normalized != "unicode11utf8" &&
+                    normalized != "unicode20utf8" &&
+                    normalized != "x-unicode20utf8")
                 {
                     throw Napi::Error::New(Env(), "TextDecoder: unsupported encoding '" + encoding + "', only 'utf-8' is supported");
                 }