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

[SergioRZMasson]

Summary

Adds asynchronous WebAssembly support to Babylon Native's V8 path and fixes a strict TextDecoder polyfill check that broke emscripten-generated WASM glue. This unblocks every Babylon.js loader/extension that relies on async WASM — most notably KHR_draco_mesh_compression, but also KHR_texture_basisu, KTX2 textures, and any future emscripten-glued path.

Tested end-to-end with the Babylon Native IntegrationTest against the Khronos Buggy/Draco model and an internal Yeti GLB (6 Draco-compressed primitives) — load and render now complete cleanly where they previously hung indefinitely.

What was broken

Two distinct gaps in Babylon Native's V8 embedding caused KHR_draco_mesh_compression model loads to silently freeze with no exception surfaced to the embedder:

1. V8 foreground task runner was never pumped

WebAssembly.instantiate returns a Promise that resolves once V8's background WASM compile worker finishes. V8 publishes that completion by posting a task onto its foreground task runner, which the embedder owns and must drain by calling v8::platform::PumpMessageLoop. The previous dispatcher loop used arcana::manual_dispatcher::blocking_tick, which only woke on AppRuntime-side dispatches — V8 platform tasks were never observed, so the resolving Promise's continuation was never invoked.

This presented as a hard freeze inside BI_createSceneAsync → ImportMeshAsync → DracoDecoder._createModuleAsync with no JS exception and no diagnostics. The same gap also affected any other async-WASM extension (Basis, KTX2, future emscripten-glued paths).

2. TextDecoder polyfill rejected the 'utf8' alias

Emscripten-generated WASM glue (notably draco_wasm_wrapper_gltf.js) calls new TextDecoder('utf8') (no hyphen) when reading strings out of the WASM heap. The polyfill's encoding check only accepted the exact strings 'utf-8' / 'UTF-8' and threw, breaking the WASM module bootstrap immediately after the task-pump fix above unblocked it.

Per the WHATWG Encoding spec § names and labels, utf8, utf-8, UTF-8, unicode-1-1-utf-8, unicode11utf8, unicode20utf8, and x-unicode20utf8 are all valid aliases for the same encoding, case-insensitive.

Changes

Core/AppRuntime/Source/AppRuntime.cpp

• Replaced m_dispatcher.blocking_tick with non-blocking tick + a 1 ms sleep when no AppRuntime work ran. This lets the dispatcher loop periodically observe engine-side task queues without busy-spinning.
• Added a thread-local internal::g_postTickHook drained every iteration. The hook is intentionally engine-agnostic: each engine's RunEnvironmentTier can install one if it needs to pump an engine-specific queue.

Core/AppRuntime/Source/AppRuntime_V8.cpp

Installs a post-tick hook that:

1. Calls v8::platform::PumpMessageLoop(platform, isolate, kDoNotWait) in a loop until the platform task queue is empty.
2. Calls isolate->PerformMicrotaskCheckpoint() so promise .then continuations queued by the pumped tasks run immediately on the same tick.

The hook is uninstalled before the isolate is destroyed.

Polyfills/TextDecoder/Source/TextDecoder.cpp

Encoding label comparison is now case-insensitive and accepts the full set of WHATWG-spec utf-8 aliases. Unsupported labels still throw with the same error string as before.

Other engines — annotated, no behavior change

The remaining three engines have a different async-WASM story; each AppRuntime_*.cpp is annotated documenting the situation so future maintainers know why no analogous pump is required:

• V8JSI (AppRuntime_JSI.cpp): V8JSI exposes V8's foreground task runner as an injectable JSITaskRunner. The existing TaskRunnerAdapter already routes V8 platform tasks (including WASM compile completions) through AppRuntime.Dispatch.
• ChakraCore (AppRuntime_Chakra.cpp): WASM compile runs synchronously inside the Promise's resolve step, which fires through the existing JsSetPromiseContinuationCallback. No separate platform-task pump is required.
• JavaScriptCore (AppRuntime_JavaScriptCore.cpp): JSC's Wasm::Worklist background completion lands on the JS thread's microtask queue, which JSC drains automatically on every JS re-entry — and AppRuntime.Dispatch hands control to JSC on every tick. The one documented edge case (zero further dispatches between WASM call and resolution) is noted with a host-side mitigation.

Verification

• Unit tests: TextDecoder unit tests in Tests/UnitTests/Scripts/tests.ts pass unchanged; the new alias acceptance does not affect existing assertions (they exercise default-construct + 'utf-8' paths).
• Integration: Babylon Native's IntegrationTest (windowed) loads DRACO_MODEL.glb (Yeti, ~4.3 MB, 6 Draco-compressed primitives) end-to-end. Logs confirm the full WASM bootstrap completes: WASM async probe: PASS → module: script loaded → _createModuleAsync RESOLVED → all 6 primitives decoded → BI_createSceneAsync RESOLVED. Without these fixes the same model hangs indefinitely inside _createModuleAsync.
• Existing Playground and unit-test suites (run via the BabylonNative consumer) show no regressions.

Risk

• The dispatcher loop now sleeps 1 ms when no AppRuntime work is ready instead of blocking on the queue. CPU usage is unchanged in the loaded case and adds at most ~1 ms wakeup latency in the idle case — negligible relative to the 16 ms render budget Babylon Native already targets.
• The TextDecoder change is strictly additive (more labels accepted) and matches the WHATWG spec, so no callers can regress.

Related

• Companion BabylonNative change: BabylonJS/BabylonNative will bump its JsRuntimeHost pin once this PR lands.

[Copilot]

Pull request overview

This PR unblocks async WebAssembly execution in the V8-backed AppRuntime by ensuring V8 foreground tasks and microtasks are drained during the host dispatcher loop, and it relaxes the TextDecoder polyfill’s UTF-8 label checking to accept WHATWG-specified aliases used by emscripten-generated WASM glue.

Changes:

• Update the AppRuntime dispatch loop to use non-blocking ticks and add a per-thread post-tick hook mechanism.
• In the V8 environment tier, install a post-tick hook that pumps V8 platform tasks and runs a microtask checkpoint so async WASM Promise continuations can resolve.
• Expand TextDecoder’s accepted UTF-8 labels to include common aliases (e.g., utf8) with case-insensitive matching; add engine-specific notes for non-V8 paths.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Polyfills/TextDecoder/Source/TextDecoder.cpp	Accept additional UTF-8 encoding labels/aliases case-insensitively to match common emscripten usage.
Core/AppRuntime/Source/AppRuntime.cpp	Switch dispatcher loop to tick + brief sleep and add a thread-local post-tick hook to allow engine task pumping.
Core/AppRuntime/Source/AppRuntime_V8.cpp	Install/uninstall a post-tick hook that pumps V8 foreground tasks and performs microtask checkpoints.
Core/AppRuntime/Source/AppRuntime_JSI.cpp	Add documentation describing why V8JSI already handles async-WASM task routing.
Core/AppRuntime/Source/AppRuntime_JavaScriptCore.cpp	Add documentation about JSC async WASM continuation behavior and why no explicit pump is installed.
Core/AppRuntime/Source/AppRuntime_Chakra.cpp	Add documentation about Chakra promise continuation routing and why no platform-task pump is needed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.