feat: JSWorker for all runtimes (not just V8) + Node transfers

JSC and QuickJS now implement the V8 Serializer API in order
to handle serialization of standard JS types intermingled with
Godot variants.

On the web things are a bit more complex. We try take advantage of
the web's built-in postMessage functionality as much as possible.
The browser's postMessage handles structured clone for us i.e. will
serialize plain old data, as well as more advanced types like Set,
Map etc. However, it can't handle Godot types. So before calling
postMessage we descend through the message data structure and
replace Godot objects with markers which are delivered via the
transfer list (WASM side channel). If a message contains no
Godot objects then process is particularly performant because
neither the sender or the receiver need to cross the WASM bridge
at all when sending/receiving the message.

QuickJS-NG has been updated to the latest version.

Also, implemented a test matrix for each of our runtimes:

- V8
- QuickJS (NG)
- JavaScriptCore
- Web
- QuickJS WASM on Web

Author: Benjamin-Dobell

.changeset/lemon-candies-hide.md

@@ -0,0 +1,5 @@
+---
+"@godot-js/editor": minor
+---
+
+feat: JSWorker for all runtimes (not just V8) + Node transfers

.github/workflows/build_ios.yml

@@ -36,9 +36,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # JSC isn't working at the moment
-        #        engine: [ v8, qjs-ng, jsc ]
-        engine: [ v8, qjs-ng ]
+        engine: [ v8, qjs-ng, jsc ]
         target: ${{ inputs.release && fromJSON('["template_release","template_debug"]') || fromJSON('["template_debug"]') }}
     steps:
       - name: Checkout Godot
@@ -80,6 +78,7 @@ jobs:
           scons-flags: >-
             ${{ env.SCONS_FLAGS }}
             ${{ matrix.engine == 'qjs-ng' && 'use_quickjs_ng=yes' || '' }}
+            ${{ matrix.engine == 'jsc' && 'use_jsc=yes' || '' }}
           platform: ios
           target: ${{ matrix.target }}
 

.github/workflows/build_macos.yml

@@ -35,7 +35,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        engine: [v8, qjs-ng]
+        engine: [v8, qjs-ng, jsc]
         target: ${{ inputs.release && fromJSON('["editor","template_release","template_debug"]') || fromJSON('["editor"]') }}
     steps:
       # From https://github.com/actions/runner-images/blob/main/images/macos
@@ -122,6 +122,7 @@ jobs:
             ${{ env.SCONS_FLAGS }}
             ${{ matrix.target != 'editor' && 'debug_symbols=no' || '' }}
             ${{ matrix.engine == 'qjs-ng' && 'use_quickjs_ng=yes' || '' }}
+            ${{ matrix.engine == 'jsc' && 'use_jsc=yes' || '' }}
             arch=x86_64
             vulkan=${{ steps.vulkan-sdk.outputs.VULKAN_ENABLED }}
             ${{ !inputs.release && matrix.target == 'editor' && 'tests=yes' || '' }}
@@ -135,6 +136,7 @@ jobs:
             ${{ env.SCONS_FLAGS }}
             ${{ matrix.target != 'editor' && 'debug_symbols=no' || '' }}
             ${{ matrix.engine == 'qjs-ng' && 'use_quickjs_ng=yes' || '' }}
+            ${{ matrix.engine == 'jsc' && 'use_jsc=yes' || '' }}
             arch=arm64
             vulkan=${{ steps.vulkan-sdk.outputs.VULKAN_ENABLED }}
             ${{ !inputs.release && matrix.target == 'editor' && 'tests=yes' || '' }}
@@ -181,7 +183,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        engine: [v8, qjs-ng]
+        engine: [v8, qjs-ng, jsc]
     steps:
       - name: Checkout Godot
         uses: actions/checkout@v6

.github/workflows/misc_upload_assets.yml

@@ -16,16 +16,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        engine: [ v8, qjs-ng ]
+        engine: [ v8, qjs-ng, jsc ]
         os: [ linux, macos, windows ]
-        target: [ template_release, template_debug, editor ]
-        include:
+        target: [ template_release, template_debug, editor, editor-app, template-app ]
+        exclude:
+          - os: linux
+            engine: jsc
+          - os: windows
+            engine: jsc
           - target: editor-app
-            os: macos
-            engine: v8
+            os: linux
           - target: template-app
-            os: macos
-            engine: v8
+            os: windows
     steps:
       - name: ⏬ Checkout repo
         uses: actions/checkout@v6
@@ -46,9 +48,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        engine: [ v8, qjs-ng ]
+        engine: [ v8, qjs-ng, jsc ]
         os: [ android, ios ]
         target: [ template_release, template_debug ]
+        exclude:
+          - os: android
+            engine: jsc
     steps:
       - name: ⏬ Checkout repo
         uses: actions/checkout@v6

.github/workflows/runner.yml

@@ -47,10 +47,10 @@ jobs:
       version_ref: ${{ matrix.version_ref }}
       release: ${{ github.event_name == 'release' }}
 
-  test-project:
-    name: 🔬 Test project
+  runtime-matrix:
+    name: 🧪 Runtime matrix
     needs: [engine-version-build]
-    uses: ./.github/workflows/test_project.yml
+    uses: ./.github/workflows/test_runtime_matrix.yml
     strategy:
       fail-fast: false
       matrix:
@@ -62,7 +62,7 @@ jobs:
 
   builds-done:
     name: 🏁 Builds Done
-    needs: [test-project]
+    needs: [runtime-matrix]
     runs-on: ubuntu-latest
     steps:
       - name: 🏁 Check if all builds are done

.github/workflows/test_runtime_matrix.yml

@@ -0,0 +1,114 @@
+name: 🧪 Runtime Matrix
+on:
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+
+jobs:
+  runtime-matrix:
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [host-v8, host-qjs, host-jsc, web-browser, web-qjs]
+    runs-on: ${{ matrix.runtime == 'host-jsc' && 'macos-latest' || 'ubuntu-22.04' }}
+    name: Runtime (${{ matrix.runtime }})
+    steps:
+      - name: ⏬ Checkout repository
+        uses: actions/checkout@v6
+
+      - name: 🛠️ pnpm and build
+        uses: ./.github/actions/pnpm-build
+
+      - name: ⏬ Download host-v8 artifact
+        if: matrix.runtime == 'host-v8' || matrix.runtime == 'web-browser' || matrix.runtime == 'web-qjs'
+        uses: actions/download-artifact@v4
+        with:
+          name: linux-editor-${{ inputs.version }}-v8
+          path: runtime-artifacts/host-v8
+
+      - name: ⏬ Download host-qjs artifact
+        if: matrix.runtime == 'host-qjs'
+        uses: actions/download-artifact@v4
+        with:
+          name: linux-editor-${{ inputs.version }}-qjs-ng
+          path: runtime-artifacts/host-qjs
+
+      - name: ⏬ Download host-jsc artifact
+        if: matrix.runtime == 'host-jsc'
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-editor-${{ inputs.version }}-jsc
+          path: runtime-artifacts/host-jsc
+
+      - name: ⏬ Download web-browser template artifact
+        if: matrix.runtime == 'web-browser'
+        uses: actions/download-artifact@v4
+        with:
+          name: web-template_debug-${{ inputs.version }}-browser
+          path: runtime-artifacts/web-browser
+
+      - name: ⏬ Download web-qjs template artifact
+        if: matrix.runtime == 'web-qjs'
+        uses: actions/download-artifact@v4
+        with:
+          name: web-template_debug-${{ inputs.version }}-qjs-ng
+          path: runtime-artifacts/web-qjs
+
+      - name: 📦 Stage runtime assets for run-runtime-matrix
+        shell: bash
+        run: |
+          set -euo pipefail
+          fail_missing() {
+            echo "::error::missing required runtime artifact for $1 (version ${{ inputs.version }})"
+            exit 1
+          }
+
+          pick_one() {
+            local dir="$1"
+            local name_pattern="$2"
+            local value
+            value="$(find "$dir" -type f -name "$name_pattern" 2>/dev/null | head -n1 || true)"
+            if [ -z "$value" ]; then
+              return 1
+            fi
+            echo "$value"
+          }
+
+          mkdir -p tests/bin
+          case "${{ matrix.runtime }}" in
+            host-v8)
+              src="$(pick_one runtime-artifacts/host-v8 'godot.linuxbsd.editor.*')" || fail_missing "host-v8 binary"
+              cp "$src" tests/bin/godot-host-v8
+              chmod +x tests/bin/godot-host-v8
+              ;;
+            host-qjs)
+              src="$(pick_one runtime-artifacts/host-qjs 'godot.linuxbsd.editor.*')" || fail_missing "host-qjs binary"
+              cp "$src" tests/bin/godot-host-qjs
+              chmod +x tests/bin/godot-host-qjs
+              ;;
+            host-jsc)
+              src="$(pick_one runtime-artifacts/host-jsc 'godot.macos.editor.*')" || fail_missing "host-jsc binary"
+              cp "$src" tests/bin/godot-host-jsc
+              chmod +x tests/bin/godot-host-jsc
+              ;;
+            web-browser)
+              host_src="$(pick_one runtime-artifacts/host-v8 'godot.linuxbsd.editor.*')" || fail_missing "web-browser host-v8 binary"
+              web_src="$(pick_one runtime-artifacts/web-browser '*.zip')" || fail_missing "web-browser template zip"
+              cp "$host_src" tests/bin/godot-host-v8
+              cp "$web_src" tests/bin/godot-web-browser-template_debug.zip
+              chmod +x tests/bin/godot-host-v8
+              ;;
+            web-qjs)
+              host_src="$(pick_one runtime-artifacts/host-v8 'godot.linuxbsd.editor.*')" || fail_missing "web-qjs host-v8 binary"
+              web_src="$(pick_one runtime-artifacts/web-qjs '*.zip')" || fail_missing "web-qjs template zip"
+              cp "$host_src" tests/bin/godot-host-v8
+              cp "$web_src" tests/bin/godot-web-qjs-template_debug.zip
+              chmod +x tests/bin/godot-host-v8
+              ;;
+          esac
+
+      - name: ▶️ Run selected runtime
+        run: |
+          pnpm test -- --runtimes ${{ matrix.runtime }} --skip-builds

.gitignore

@@ -32,10 +32,13 @@ __MACOSX
 .vscode
 
 # IntelliJ IDEA project files
-/.idea/
+.idea/
 
 # Node modules
-/node_modules/
+node_modules/
 
 # pnpm store
 .pnpm-store
+
+# local test artifacts
+/tests/bin/

SCsub

@@ -91,7 +91,7 @@ lws_prebuilt_libs = LibraryDescriptor("lws", \
 ])
 quickjs_src_descs = ThirdPartyDescriptor("quickjs", \
 [
-    ThirdPartyDetails("quickjs-ng", ["cutils.c", "libbf.c", "libregexp.c", "libunicode.c", "quickjs.c"]),
+    ThirdPartyDetails("quickjs-ng", ["dtoa.c", "libregexp.c", "libunicode.c", "quickjs.c"]),
     ThirdPartyDetails("quickjs",    ["cutils.c", "libbf.c", "libregexp.c", "libunicode.c", "quickjs.c"]),
 ])
 
@@ -183,7 +183,7 @@ if quickjs_support is None and jsc_support is None and is_library_supported(v8_p
     if is_library_supported(lws_prebuilt_libs):
         download_dependency("lws", deps_lws_version, "lws")
 
-v8_support = validate_library_support(v8_prebuilt_libs) if quickjs_support is None else None
+v8_support = validate_library_support(v8_prebuilt_libs) if quickjs_support is None and jsc_support is None else None
 lws_support = validate_library_support(lws_prebuilt_libs) if v8_support is not None else None
 
 jsb_defines = [
@@ -202,7 +202,6 @@ jsb_defines = [
         "Use the host browser's javascript engine.",
         "Be aware that all script sources are evaluated in the host browser, which can be fully debugged with the browser's developer tools.",
         "It's recommended to obfuscate the script sources before deploying the project in a production environment.",
-        "NOTE: web.impl is experimental and may not work as expected.",
         "NOTE: Obfuscation may not work in the current version. It'll be improved in the future versions. Report an issue if it breaks.",
     ]),
     CompileDefines("JSB_WITH_JAVASCRIPTCORE", 1 if jsc_support is not None else 0, [
@@ -574,8 +573,6 @@ if quickjs_support is not None:
 if is_defined("JSB_WITH_WEB"):
     check(os.path.exists("impl/web/js"), "impl/web/js (GodotJS web bridge) has not been built")
 
-    print_warning("web.impl is experimental and may not work as expected")
-
     env_jsb.add_source_files(module_obj, "impl/web/*.cpp")
 
     # this script is compiled from impl/web/bridge typescript source

bridge/jsb_bridge_module_loader.cpp

@@ -27,6 +27,28 @@ namespace jsb
             info.GetReturnValue().Set(impl::Helper::to_array_buffer(isolate, var));
         }
 
+        String _describe_export_name(
+            v8::Isolate* isolate,
+            const v8::Local<v8::Context>& context,
+            Environment* environment,
+            const v8::Local<v8::Object>& object)
+        {
+            v8::Local<v8::Value> name_value;
+            if (!object->Get(context, jsb_name(environment, name)).ToLocal(&name_value))
+            {
+                return String("<name:get-failed>");
+            }
+
+            if (name_value->IsString())
+            {
+                return impl::Helper::to_string(isolate, name_value);
+            }
+
+            // Keep this coercion-safe: do not call generic JS value->string conversion
+            // on arbitrary objects. js_debug_typeof provides structural categorization.
+            return jsb_format("<%s>", TypeConvert::js_debug_typeof(isolate, name_value));
+        }
+
         // construct a callable object
         // [js] function callable(fn: Function): godot.Callable;
         // [js] function callable(thiz: godot.Object, fn: Function): godot.Callable;
@@ -387,8 +409,8 @@ namespace jsb
 
             collection->Set(context, index, details).Check();
             JSB_LOG(VeryVerbose, "script %s define property(export) %s",
-                impl::Helper::to_string_opt(isolate, target->Get(context, jsb_name(environment, name))),
-                impl::Helper::to_string_opt(isolate, details->Get(context, jsb_name(environment, name))));
+                _describe_export_name(isolate, context, environment, target),
+                _describe_export_name(isolate, context, environment, details));
         }
 
         // TODO: Cache for our cache functions?: