BridgeJS: Register core generic type handles from JavaScriptKit

Every module's generated registration function listed the 15 core type
handles before its own types, and every module's JS registration hook
repeated the 15 primitive codec entries. The core types are owned by the
library, not by any module, so define their registration once.

`_bjs_core_register_type_handles` in JavaScriptKit exposes the core handle
buffer under `bjs_core_register_type_handles`; because JavaScriptKit is
linked into every BridgeJS binary, exactly one definition exists in the
final wasm. The link step emits the matching `bjs[...]` hook once per
linked bundle instead of once per module, and drives it before the
per-module hooks. Generated per-module registration now carries only that
module's own `@JS` types, so a module that merely uses generics emits no
registration function at all.

The ordering contract is still enforced on both sides: each hook checks the
codec array length against the count Swift pushed, and a new build-time test
checks the library's core list against
`BridgeType.genericBridgeablePrimitives`, which the link step uses to build
the core codec array.

Author: krodak

Benchmarks/Sources/Generated/BridgeJS.swift

@@ -2275,21 +2275,6 @@ fileprivate func _bjs_Benchmarks_register_type_handles_extern(_ base: UnsafePoin
 @_expose(wasm, "bjs_Benchmarks_register_type_handles")
 public func _bjs_Benchmarks_register_type_handles() {
     let typeIds: [Int32] = [
-        Bool.bridgeJSTypeID,
-        Int.bridgeJSTypeID,
-        Int8.bridgeJSTypeID,
-        UInt8.bridgeJSTypeID,
-        Int16.bridgeJSTypeID,
-        UInt16.bridgeJSTypeID,
-        Int32.bridgeJSTypeID,
-        UInt32.bridgeJSTypeID,
-        UInt.bridgeJSTypeID,
-        Int64.bridgeJSTypeID,
-        UInt64.bridgeJSTypeID,
-        Float.bridgeJSTypeID,
-        Double.bridgeJSTypeID,
-        String.bridgeJSTypeID,
-        JSValue.bridgeJSTypeID,
         SimpleStruct.bridgeJSTypeID,
         Address.bridgeJSTypeID,
         Person.bridgeJSTypeID,

Examples/PlayBridgeJS/Sources/PlayBridgeJS/Generated/BridgeJS.swift

@@ -295,21 +295,6 @@ fileprivate func _bjs_PlayBridgeJS_register_type_handles_extern(_ base: UnsafePo
 @_expose(wasm, "bjs_PlayBridgeJS_register_type_handles")
 public func _bjs_PlayBridgeJS_register_type_handles() {
     let typeIds: [Int32] = [
-        Bool.bridgeJSTypeID,
-        Int.bridgeJSTypeID,
-        Int8.bridgeJSTypeID,
-        UInt8.bridgeJSTypeID,
-        Int16.bridgeJSTypeID,
-        UInt16.bridgeJSTypeID,
-        Int32.bridgeJSTypeID,
-        UInt32.bridgeJSTypeID,
-        UInt.bridgeJSTypeID,
-        Int64.bridgeJSTypeID,
-        UInt64.bridgeJSTypeID,
-        Float.bridgeJSTypeID,
-        Double.bridgeJSTypeID,
-        String.bridgeJSTypeID,
-        JSValue.bridgeJSTypeID,
         PlayBridgeJSOutput.bridgeJSTypeID,
         PlayBridgeJSDiagnostic.bridgeJSTypeID,
         PlayBridgeJSResult.bridgeJSTypeID,

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -908,6 +908,10 @@ struct GenericConformanceCodegen {
 /// registered type's `bridgeJSTypeID` into a buffer, in the canonical order of
 /// `BridgeJSSkeleton.typeRegistrationEntries`, and passes it to the JS import
 /// hook of the same name, which pairs the IDs with its codec array by index.
+///
+/// Only the module's own `@JS` types are listed; the core (primitive) handles are
+/// registered once by the JavaScriptKit library itself
+/// (`_bjs_core_register_type_handles`).
 public struct GenericTypeRegistrationCodegen {
     public init() {}
 

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -355,6 +355,11 @@ public struct BridgeJSLink {
             declarations.append("        return;")
             declarations.append("    }")
             declarations.append("    __bjs_typeHandlesRegistered = true;")
+            // The core (primitive) handles live in the JavaScriptKit library, so
+            // they are registered once here rather than by every module.
+            declarations.append(
+                "    \(JSGlueVariableScope.reservedInstance).exports[\"\(ABINameGenerator.coreTypeRegistrationFunctionName)\"]();"
+            )
             for skeleton in skeletons {
                 guard skeleton.typeRegistrationEntries != nil else { continue }
                 let name = ABINameGenerator.typeRegistrationFunctionName(moduleName: skeleton.moduleName)
@@ -433,53 +438,88 @@ public struct BridgeJSLink {
         )
     }
 
+    /// Writes the body shared by every registration hook: verify the codec array
+    /// lines up with the buffer Swift pushed, then pair IDs with codecs by index.
+    ///
+    /// The count check is the enforcement point of the ordering contract: the
+    /// Swift side and the JS side derive their lists from the same declaration
+    /// order, so a divergence shows up here instead of as a silent mismatch.
+    private func writeTypeHandleRegistrationBody(
+        into printer: CodeFragmentPrinter,
+        mismatchDescription: String
+    ) {
+        printer.write("if (count !== codecs.length) {")
+        printer.indent {
+            printer.write(
+                "throw new Error(\"BridgeJS: type handle registration mismatch for \(mismatchDescription)\");"
+            )
+        }
+        printer.write("}")
+        printer.write(
+            "const typeIds = new Int32Array(\(JSGlueVariableScope.reservedMemory).buffer, base >>> 0, count >>> 0);"
+        )
+        printer.write("for (let i = 0; i < count; i++) {")
+        printer.indent {
+            printer.write("\(JSGlueVariableScope.reservedCodecByTypeId).set(typeIds[i], codecs[i]);")
+        }
+        printer.write("}")
+    }
+
+    /// Installs the `bjs_core_register_type_handles` hook. The core handles are
+    /// owned by the JavaScriptKit library rather than by generated code, so the
+    /// wasm import exists in every binary that links JavaScriptKit and the hook
+    /// is always installed; without generics anywhere in the build it is a no-op
+    /// and the registration export is never called.
+    private func generateCoreTypeRegistrationHook(into printer: CodeFragmentPrinter) throws {
+        let hookName = ABINameGenerator.coreTypeRegistrationFunctionName
+        guard hasGenerics else {
+            printer.write("bjs[\"\(hookName)\"] = function() {};")
+            return
+        }
+        try ContainerCodecJS.registerPrimitiveCodecs(context: makeCodecPrintContext(printer: printer))
+        printer.write("bjs[\"\(hookName)\"] = function(base, count) {")
+        printer.indent {
+            // Same canonical order as `_bjs_core_register_type_handles` in the
+            // JavaScriptKit library.
+            printer.write("const codecs = [")
+            printer.indent {
+                for primitive in BridgeType.genericBridgeablePrimitives {
+                    printer.write("\(JSGlueVariableScope.reservedPrimitiveCodecs).\(primitive.token),")
+                }
+            }
+            printer.write("];")
+            writeTypeHandleRegistrationBody(into: printer, mismatchDescription: "core types")
+        }
+        printer.write("}")
+    }
+
     /// Installs the per-module `bjs_<Module>_register_type_handles` import
     /// hooks. A module with a registration function always carries the wasm
     /// import, so a hook is always installed; without generics anywhere in the
     /// build it is a no-op and the registration export is never called.
     private func generateTypeRegistrationHooks(into printer: CodeFragmentPrinter) throws {
+        try generateCoreTypeRegistrationHook(into: printer)
         for skeleton in skeletons {
-            guard skeleton.typeRegistrationEntries != nil else { continue }
+            guard let moduleEntries = skeleton.typeRegistrationEntries else { continue }
             let hookName = ABINameGenerator.typeRegistrationFunctionName(moduleName: skeleton.moduleName)
             guard hasGenerics else {
                 printer.write("bjs[\"\(hookName)\"] = function() {};")
                 continue
             }
-            // The hooks resolve type IDs against the shared primitive codec table.
-            try ContainerCodecJS.registerPrimitiveCodecs(context: makeCodecPrintContext(printer: printer))
-            let moduleEntries = skeleton.exported?.genericBridgeableTypeEntries ?? []
             printer.write("bjs[\"\(hookName)\"] = function(base, count) {")
             try printer.indent {
-                // Same canonical order as the Swift registration function:
-                // primitives first, then the module's own types.
+                // Same order as the module's Swift registration function.
                 printer.write("const codecs = [")
-                printer.indent {
-                    for primitive in BridgeType.genericBridgeablePrimitives {
-                        printer.write("\(JSGlueVariableScope.reservedPrimitiveCodecs).\(primitive.token),")
-                    }
-                }
-                printer.write("].concat([")
                 try printer.indent {
                     for entry in moduleEntries {
                         try appendGenericCodecLiteral(type: entry.bridgeType, into: printer)
                     }
                 }
-                printer.write("]);")
-                printer.write("if (count !== codecs.length) {")
-                printer.indent {
-                    printer.write(
-                        "throw new Error(\"BridgeJS: type handle registration mismatch for module '\(skeleton.moduleName)'\");"
-                    )
-                }
-                printer.write("}")
-                printer.write(
-                    "const typeIds = new Int32Array(\(JSGlueVariableScope.reservedMemory).buffer, base >>> 0, count >>> 0);"
+                printer.write("];")
+                writeTypeHandleRegistrationBody(
+                    into: printer,
+                    mismatchDescription: "module '\(skeleton.moduleName)'"
                 )
-                printer.write("for (let i = 0; i < count; i++) {")
-                printer.indent {
-                    printer.write("\(JSGlueVariableScope.reservedCodecByTypeId).set(typeIds[i], codecs[i]);")
-                }
-                printer.write("}")
             }
             printer.write("}")
         }

Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift

@@ -32,6 +32,13 @@ public struct ABINameGenerator {
         "bjs_\(moduleName)_register_type_handles"
     }
 
+    /// Name of the core type-handle registration function. Unlike the per-module
+    /// ones, this is defined once in the JavaScriptKit library (see
+    /// `_bjs_core_register_type_handles` in `BridgeJSIntrinsics.swift`) so the
+    /// primitive handles exist exactly once in the final binary and the JS glue
+    /// registers their codecs once per linked bundle.
+    public static let coreTypeRegistrationFunctionName = "bjs_core_register_type_handles"
+
     /// Generates ABI name using standardized namespace + context pattern
     public static func generateABIName(
         baseName: String,
@@ -383,17 +390,17 @@ extension ExportedSkeleton {
 
 extension BridgeJSSkeleton {
     /// The ordered list of types this module registers type handles for, or
-    /// `nil` when it emits no registration function. Primitive handles are
-    /// library singletons, so every module re-registering them writes the same
-    /// ID-to-codec pair, and a pure-import build still gets a populated table.
+    /// `nil` when it emits no registration function.
+    ///
+    /// Only the module's own `@JS` types appear here: the core (primitive)
+    /// handles are owned by the JavaScriptKit library, which registers them once
+    /// for the whole binary via ``ABINameGenerator/coreTypeRegistrationFunctionName``.
+    /// A module that only *uses* generics therefore needs no registration
+    /// function of its own.
     public var typeRegistrationEntries: [GenericBridgeableTypeEntry]? {
         let exportedEntries = exported?.genericBridgeableTypeEntries ?? []
-        let hasGenericImports = imported?.hasGenericDeclarations ?? false
-        guard !exportedEntries.isEmpty || hasGenericImports else { return nil }
-        let primitives = BridgeType.genericBridgeablePrimitives.map {
-            GenericBridgeableTypeEntry(swiftName: $0.token, bridgeType: $0.type)
-        }
-        return primitives + exportedEntries
+        guard !exportedEntries.isEmpty else { return nil }
+        return exportedEntries
     }
 }
 

Plugins/BridgeJS/Tests/BridgeJSToolTests/BridgeJSLinkTests.swift

@@ -251,9 +251,14 @@ import Testing
         let coreEntries = try #require(core.typeRegistrationEntries)
         #expect(coreEntries.contains { $0.swiftName == "Vector3D" })
 
+        // App exports no @JS types, so it owns no handles: only the core
+        // (library-owned) registration and Core's own registration run.
+        #expect(app.typeRegistrationEntries == nil)
+
         let js = try BridgeJSLink(skeletons: [core, app], sharedMemory: false).link().outputJs
+        #expect(js.contains("instance.exports[\"bjs_core_register_type_handles\"]();"))
         #expect(js.contains("instance.exports[\"bjs_Core_register_type_handles\"]();"))
-        #expect(js.contains("instance.exports[\"bjs_App_register_type_handles\"]();"))
+        #expect(!js.contains("bjs_App_register_type_handles"))
         // `lower(v)` is unique to a codec literal in a registration array;
         // `structHelpers.Vector3D` on its own is emitted for every @JS struct.
         #expect(js.contains("structHelpers.Vector3D.lower(v);"))

Plugins/BridgeJS/Tests/BridgeJSToolTests/CoreTypeRegistrationContractTests.swift

@@ -0,0 +1,48 @@
+import Foundation
+import Testing
+
+@testable import BridgeJSSkeleton
+
+/// The core (primitive) generic type handles are registered by the JavaScriptKit
+/// library itself, not by generated code, so the ordering contract between the
+/// Swift buffer and the JS codec array spans two repositories' worth of source:
+/// `_bjs_core_register_type_handles` in `Sources/JavaScriptKit/BridgeJSIntrinsics.swift`
+/// and `BridgeType.genericBridgeablePrimitives` here.
+///
+/// The generated glue checks the *count* at registration time; this test checks
+/// the *order* at build time so a reordering cannot silently mis-pair codecs.
+@Suite struct CoreTypeRegistrationContractTests {
+    private static var repositoryRoot: URL {
+        URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()  // BridgeJSToolTests
+            .deletingLastPathComponent()  // Tests
+            .deletingLastPathComponent()  // BridgeJS
+            .deletingLastPathComponent()  // Plugins
+            .deletingLastPathComponent()  // <repo root>
+    }
+
+    @Test
+    func coreTypeHandleOrderMatchesGenericBridgeablePrimitives() throws {
+        let intrinsics = Self.repositoryRoot
+            .appendingPathComponent("Sources/JavaScriptKit/BridgeJSIntrinsics.swift")
+        let source = try String(contentsOf: intrinsics, encoding: .utf8)
+
+        let beginMarker = "// BEGIN bjs_core_type_handles"
+        let endMarker = "// END bjs_core_type_handles"
+        guard let begin = source.range(of: beginMarker), let end = source.range(of: endMarker) else {
+            Issue.record("Could not find the core type handle list markers in \(intrinsics.path)")
+            return
+        }
+
+        let names =
+            source[begin.upperBound..<end.lowerBound]
+            .split(separator: "\n")
+            .compactMap { line -> String? in
+                let trimmed = line.trimmingCharacters(in: .whitespaces)
+                guard trimmed.hasSuffix(".bridgeJSTypeID,") else { return nil }
+                return String(trimmed.dropLast(".bridgeJSTypeID,".count))
+            }
+
+        #expect(names == BridgeType.genericBridgeablePrimitives.map(\.token))
+    }
+}

Plugins/BridgeJS/Tests/BridgeJSToolTests/GenericMethodOnlyModuleCodegenTests.swift

@@ -3,8 +3,10 @@ import Testing
 @Suite struct GenericMethodOnlyModuleCodegenTests {
     @Test
     func importMethodOnlyEmitsJSRuntimeInfrastructure() throws {
-        // A module with generic imports but no exported @JS types still needs a
-        // populated codec table for the primitives, so it registers them itself.
+        // A module with generic imports but no exported @JS types needs a
+        // populated codec table, but it owns none of the entries: the core
+        // handles come from the JavaScriptKit library's own registration, so the
+        // module emits no registration function of its own.
         let js = try linkSource(
             """
             @JSClass struct OnlyConsumer {
@@ -14,8 +16,9 @@ import Testing
         ).js
         #expect(js.contains("const __bjs_codecByTypeId = new Map();"))
         #expect(js.contains("function __bjs_codecForTypeId(typeId) {"))
-        #expect(js.contains("bjs[\"bjs_TestModule_register_type_handles\"] = function(base, count) {"))
-        #expect(js.contains("instance.exports[\"bjs_TestModule_register_type_handles\"]();"))
+        #expect(js.contains("bjs[\"bjs_core_register_type_handles\"] = function(base, count) {"))
+        #expect(js.contains("instance.exports[\"bjs_core_register_type_handles\"]();"))
+        #expect(!js.contains("bjs_TestModule_register_type_handles"))
     }
 
     @Test
@@ -33,7 +36,28 @@ import Testing
         ).js
         #expect(js.contains("const __bjs_codecByTypeId = new Map();"))
         #expect(js.contains("function __bjs_codecForTypeId(typeId) {"))
+        #expect(js.contains("bjs[\"bjs_core_register_type_handles\"] = function(base, count) {"))
+        #expect(js.contains("instance.exports[\"bjs_core_register_type_handles\"]();"))
+        #expect(!js.contains("bjs_TestModule_register_type_handles"))
+    }
+
+    @Test
+    func exportedTypesStillRegisterTheirOwnHandlesOnly() throws {
+        // A module that exports @JS types registers exactly those, without
+        // repeating the core entries the library already owns.
+        let js = try linkSource(
+            """
+            @JS struct Point {
+                var x: Int
+                @JS init(x: Int) { self.x = x }
+            }
+            @JSClass struct Consumer {
+                @JSFunction func identity<T: BridgedSwiftGenericBridgeable>(_ value: T) throws(JSException) -> T
+            }
+            """
+        ).js
         #expect(js.contains("bjs[\"bjs_TestModule_register_type_handles\"] = function(base, count) {"))
-        #expect(js.contains("instance.exports[\"bjs_TestModule_register_type_handles\"]();"))
+        // The primitive entries appear exactly once, in the core hook.
+        #expect(js.components(separatedBy: "__bjs_primitiveCodecs.Bool,").count - 1 == 1)
     }
 }

Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSCodegenTests/Alias.swift

@@ -415,21 +415,6 @@ fileprivate func _bjs_TestModule_register_type_handles_extern(_ base: UnsafePoin
 @_expose(wasm, "bjs_TestModule_register_type_handles")
 public func _bjs_TestModule_register_type_handles() {
     let typeIds: [Int32] = [
-        Bool.bridgeJSTypeID,
-        Int.bridgeJSTypeID,
-        Int8.bridgeJSTypeID,
-        UInt8.bridgeJSTypeID,
-        Int16.bridgeJSTypeID,
-        UInt16.bridgeJSTypeID,
-        Int32.bridgeJSTypeID,
-        UInt32.bridgeJSTypeID,
-        UInt.bridgeJSTypeID,
-        Int64.bridgeJSTypeID,
-        UInt64.bridgeJSTypeID,
-        Float.bridgeJSTypeID,
-        Double.bridgeJSTypeID,
-        String.bridgeJSTypeID,
-        JSValue.bridgeJSTypeID,
         PolygonReference.bridgeJSTypeID,
         TagReference.bridgeJSTypeID,
         InnerTag.bridgeJSTypeID,

Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSCodegenTests/AliasInClosure.swift

@@ -200,21 +200,6 @@ fileprivate func _bjs_TestModule_register_type_handles_extern(_ base: UnsafePoin
 @_expose(wasm, "bjs_TestModule_register_type_handles")
 public func _bjs_TestModule_register_type_handles() {
     let typeIds: [Int32] = [
-        Bool.bridgeJSTypeID,
-        Int.bridgeJSTypeID,
-        Int8.bridgeJSTypeID,
-        UInt8.bridgeJSTypeID,
-        Int16.bridgeJSTypeID,
-        UInt16.bridgeJSTypeID,
-        Int32.bridgeJSTypeID,
-        UInt32.bridgeJSTypeID,
-        UInt.bridgeJSTypeID,
-        Int64.bridgeJSTypeID,
-        UInt64.bridgeJSTypeID,
-        Float.bridgeJSTypeID,
-        Double.bridgeJSTypeID,
-        String.bridgeJSTypeID,
-        JSValue.bridgeJSTypeID,
         PolygonReference.bridgeJSTypeID,
     ]
     typeIds.withUnsafeBufferPointer { buffer in