BridgeJS: Support @js protocol constraints on generic exports

The same protocol compositions now work on exported generics:

    @js public func storeNode<T: BridgedSwiftGenericBridgeable & GraphNode>(_ node: T) -> T { node }

Unlike imports, the Swift compiler cannot check a JavaScript caller, so
the constraint is enforced at the boundary: the link layer records every
@js type's conformed @js protocols (declared on the type or via an
extension) in a token-to-conformances map, and the generated wrapper
resolves the caller's BridgeTypes token against the constraint before
anything is lowered. A non-conforming token throws a catchable TypeError
without entering wasm, keeping the shared value stack balanced; the
Swift-side generic signature then guarantees the constraint holds inside
the thunk. The d.ts wrapper signature carries 'T extends GraphNode', so
TypeScript users get the check at compile time as well.

Author: krodak

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -189,22 +189,24 @@ public class ExportSwift {
         /// When non-empty, `render(abiName:)` wraps the standard body in a
         /// generics prologue: the entry thunk takes one trailing type-ID ABI
         /// parameter per generic, recovers the concrete types from their
-        /// `BridgeJSTypeHandle`s, and opens them into a chain of helper
+        /// `BridgeJSTypeHandle`s (enforcing any `@JS protocol` constraints via
+        /// a conditional metatype cast), and opens them into a chain of helper
         /// functions; the innermost helper runs the standard body with the
         /// generic parameters bound.
-        let genericParameterNames: [String]
+        let genericParameters: [GenericParameter]
+        var genericParameterNames: [String] { genericParameters.map(\.name) }
 
         /// The async return type settled through `_bjs_makePromise`'s `Promise_resolve_<mangled>`
         /// helper. Set for every `async` thunk.
         var asyncResolveReturnType: BridgeType?
 
         var parameterBindings: [CodeBlockItemSyntax] = []
 
-        init(effects: Effects, returnType: BridgeType, genericParameterNames: [String] = []) throws {
+        init(effects: Effects, returnType: BridgeType, genericParameters: [GenericParameter] = []) throws {
             self.effects = effects
-            self.genericParameterNames = genericParameterNames
+            self.genericParameters = genericParameters
             guard effects.isAsync else { return }
-            guard genericParameterNames.isEmpty else {
+            guard genericParameters.isEmpty else {
                 throw BridgeJSCoreError("Generic exported functions cannot be 'async' yet")
             }
             guard returnType.isAsyncResolvable else {
@@ -528,16 +530,29 @@ public class ExportSwift {
             return abiReturnType?.swiftReturnPlaceholderStmt ?? "return"
         }
 
+        /// Swift spellings of a generic parameter's `@JS protocol` constraints,
+        /// qualified as written in source (`GraphKit.Node`) so the generated
+        /// generic clause resolves; the JS-side check keys on the bare names.
+        func protocolConstraints(_ genericName: String) -> [String] {
+            guard let parameter = genericParameters.first(where: { $0.name == genericName }) else { return [] }
+            return parameter.swiftConstraints ?? parameter.constraints
+        }
+
         /// The constraint composition a generic parameter is opened under, e.g.
-        /// `BridgedSwiftGenericBridgeable`. A hook for protocol constraints.
+        /// `BridgedSwiftGenericBridgeable & GraphNode`.
         func constraintComposition(_ genericName: String) -> String {
-            "BridgedSwiftGenericBridgeable"
+            (["BridgedSwiftGenericBridgeable"] + protocolConstraints(genericName)).joined(separator: " & ")
         }
 
         /// The existential metatype spelling used to thread a not-yet-opened
-        /// generic parameter through the open chain.
+        /// generic parameter through the open chain, e.g.
+        /// `any (BridgedSwiftGenericBridgeable & GraphNode).Type`.
         func existentialMetatype(_ genericName: String) -> String {
-            "any BridgedSwiftGenericBridgeable.Type"
+            let constraints = protocolConstraints(genericName)
+            if constraints.isEmpty {
+                return "any BridgedSwiftGenericBridgeable.Type"
+            }
+            return "any (\(constraintComposition(genericName))).Type"
         }
 
         /// Renders the wasm entry point for a generic exported function.
@@ -591,12 +606,29 @@ public class ExportSwift {
                     // `BridgeJSTypeHandle`; recover the type from it. A raw wasm
                     // caller passing a garbage ID is undefined behavior — the
                     // generated JS wrapper validates tokens before calling in.
+                    let constraints = protocolConstraints(genericName)
+                    let recoveredName =
+                        constraints.isEmpty ? metatypeName(genericName) : "\(metatypeName(genericName))Base"
                     printer.write(
-                        "let \(metatypeName(genericName)) = "
+                        "let \(recoveredName) = "
                             + "Unmanaged<BridgeJSTypeHandle>.fromOpaque("
                             + "UnsafeRawPointer(bitPattern: UInt(UInt32(bitPattern: \(typeIdName(genericName)))))!"
                             + ").takeUnretainedValue().type"
                     )
+                    if !constraints.isEmpty {
+                        // Defense-in-depth: the generated JS wrapper already
+                        // rejects non-conforming tokens with a TypeError, so
+                        // this cast can only fail for a raw wasm caller.
+                        printer.write(
+                            "guard let \(metatypeName(genericName)) = \(recoveredName) as? \(existentialMetatype(genericName)) else {"
+                        )
+                        printer.indent {
+                            printer.write(
+                                "fatalError(\"BridgeJS: type '\\(\(recoveredName))' does not conform to required protocol(s): \(constraints.joined(separator: ", "))\")"
+                            )
+                        }
+                        printer.write("}")
+                    }
                 }
                 let open1Arguments = genericNames.map { metatypeName($0) } + concreteABINames
                 printer.write("_\(abiName)_open1(\(open1Arguments.joined(separator: ", ")))")
@@ -776,7 +808,7 @@ public class ExportSwift {
         let builder = try ExportedThunkBuilder(
             effects: function.effects,
             returnType: function.returnType,
-            genericParameterNames: function.genericParameterNames
+            genericParameters: function.genericParameters ?? []
         )
         for param in function.parameters {
             try builder.liftParameter(param: param)
@@ -823,7 +855,7 @@ public class ExportSwift {
         let builder = try ExportedThunkBuilder(
             effects: method.effects,
             returnType: method.returnType,
-            genericParameterNames: method.genericParameterNames
+            genericParameters: method.genericParameters ?? []
         )
         if !method.effects.isStatic {
             try builder.liftParameter(param: Parameter(label: nil, name: "_self", type: instanceSelfType))

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -300,6 +300,8 @@ public final class SwiftToSkeleton {
             collector.finalize(&exported)
         }
 
+        mergeExtensionDeclaredJSProtocolConformances(into: &exported)
+
         perSourceErrors.append(contentsOf: diagnoseProtocolConformances(in: exported))
 
         if !perSourceErrors.isEmpty {
@@ -418,6 +420,50 @@ public final class SwiftToSkeleton {
         return diagnostics
     }
 
+    /// Folds `extension Foo: SomeJSProtocol {}` conformances into the exported
+    /// skeleton's `conformedJSProtocols` lists.
+    ///
+    /// The per-declaration collectors only see the type's own inheritance
+    /// clause, but declaring the conformance in an extension is common Swift
+    /// style, and the JS-side generic constraint check
+    /// (`__bjs_tokenConformances`) must not reject a type that genuinely
+    /// conforms.
+    private func mergeExtensionDeclaredJSProtocolConformances(into exported: inout ExportedSkeleton) {
+        var protocolsByTarget: [String: [String]] = [:]
+        for (sourceFile, _) in sourceFiles {
+            let collector = ExtensionConformanceCollector(parent: self)
+            collector.walk(sourceFile)
+            for (target, protocols) in collector.protocolsByTarget {
+                protocolsByTarget[target, default: []].append(contentsOf: protocols)
+            }
+        }
+        guard !protocolsByTarget.isEmpty else { return }
+
+        func merge(_ existing: inout [String]?, additions: [String]) {
+            var result = existing ?? []
+            for name in additions where !result.contains(name) {
+                result.append(name)
+            }
+            existing = result.isEmpty ? nil : result
+        }
+
+        for index in exported.structs.indices {
+            if let additions = protocolsByTarget[exported.structs[index].swiftCallName] {
+                merge(&exported.structs[index].conformedJSProtocols, additions: additions)
+            }
+        }
+        for index in exported.classes.indices {
+            if let additions = protocolsByTarget[exported.classes[index].swiftCallName] {
+                merge(&exported.classes[index].conformedJSProtocols, additions: additions)
+            }
+        }
+        for index in exported.enums.indices {
+            if let additions = protocolsByTarget[exported.enums[index].swiftCallName] {
+                merge(&exported.enums[index].conformedJSProtocols, additions: additions)
+            }
+        }
+    }
+
     private static let jsTypedArrayTypealiasNames: [String: String] = [
         "Int8": "JSInt8Array",
         "UInt8": "JSUint8Array",
@@ -1575,6 +1621,20 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
         }
     }
 
+    /// Names of the `@JS protocol`s a type's inheritance clause declares
+    /// conformance to. Non-protocol entries (raw types, plain Swift protocols)
+    /// are ignored.
+    private func collectConformedJSProtocols(from inheritanceClause: InheritanceClauseSyntax?) -> [String]? {
+        guard let inheritanceClause else { return nil }
+        var names: [String] = []
+        for inherited in inheritanceClause.inheritedTypes {
+            if let name = parent.resolveJSProtocolConstraint(for: inherited.type), !names.contains(name) {
+                names.append(name)
+            }
+        }
+        return names.isEmpty ? nil : names
+    }
+
     /// Shared parameter parsing logic used by functions, initializers, and protocol methods
     private func parseParameters(
         from parameterClause: FunctionParameterClauseSyntax,
@@ -1682,19 +1742,16 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             return nil
         }
 
-        var genericParameterNames: [String] = []
+        var genericParameters: [GenericParameter] = []
         if let genericClause = node.genericParameterClause {
             for genericParam in genericClause.parameters {
-                let constraint = genericParam.inheritedType?.trimmedDescription ?? ""
-                guard SwiftToSkeleton.isBridgeableGenericConstraint(constraint) else {
-                    diagnose(
-                        node: node,
-                        message:
-                            "Generic parameter '\(genericParam.name.text)' must be constrained to 'BridgedSwiftGenericBridgeable' to be used with @JS."
-                    )
+                switch parent.parseGenericParameterConstraints(genericParam, attributeName: "@JS") {
+                case .failed(let message):
+                    diagnose(node: node, message: message)
                     return nil
+                case .parsed(let genericParameter):
+                    genericParameters.append(genericParameter)
                 }
-                genericParameterNames.append(genericParam.name.text)
             }
             if node.genericWhereClause != nil {
                 diagnose(
@@ -1719,6 +1776,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             }
         }
 
+        let genericParameterNames = genericParameters.map(\.name)
+
         let name = node.name.text
         let jsName = extractValidatedJSName(from: jsAttribute)
 
@@ -1883,7 +1942,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             namespace: finalNamespace,
             staticContext: staticContext,
             documentation: extractDocumentation(from: node),
-            genericParameters: genericParameterNames.isEmpty ? nil : genericParameterNames
+            genericParameters: genericParameters.isEmpty ? nil : genericParameters
         )
     }
 
@@ -2275,7 +2334,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             jsNamespace: namespaceResult.jsNamespace,
             identityMode: classIdentityMode,
             documentation: extractDocumentation(from: node),
-            isFinal: isFinal
+            isFinal: isFinal,
+            conformedJSProtocols: collectConformedJSProtocols(from: node.inheritanceClause)
         )
         let uniqueKey = makeKey(name: name, namespace: effectiveNamespace)
 
@@ -2440,7 +2500,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             emitStyle: emitStyle,
             staticMethods: [],
             staticProperties: [],
-            documentation: extractDocumentation(from: node)
+            documentation: extractDocumentation(from: node),
+            conformedJSProtocols: collectConformedJSProtocols(from: node.inheritanceClause)
         )
 
         let enumUniqueKey = makeKey(name: name, namespace: effectiveNamespace)
@@ -2693,7 +2754,8 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             methods: [],
             namespace: effectiveNamespace,
             jsNamespace: namespaceResult.jsNamespace,
-            documentation: extractDocumentation(from: node)
+            documentation: extractDocumentation(from: node),
+            conformedJSProtocols: collectConformedJSProtocols(from: node.inheritanceClause)
         )
 
         exportedStructByName[structUniqueKey] = exportedStruct
@@ -4076,3 +4138,27 @@ extension GenericArgumentListSyntax {
         #endif
     }
 }
+
+/// Collects `@JS protocol` conformances declared through extensions, keyed by
+/// the extended type's (possibly qualified) name as written in source, which
+/// matches the skeleton's `swiftCallName` for both top-level and nested types.
+private final class ExtensionConformanceCollector: SyntaxVisitor {
+    private let parent: SwiftToSkeleton
+    var protocolsByTarget: [String: [String]] = [:]
+
+    init(parent: SwiftToSkeleton) {
+        self.parent = parent
+        super.init(viewMode: .sourceAccurate)
+    }
+
+    override func visit(_ node: ExtensionDeclSyntax) -> SyntaxVisitorContinueKind {
+        guard let inheritanceClause = node.inheritanceClause else { return .visitChildren }
+        let target = node.extendedType.trimmedDescription
+        for inherited in inheritanceClause.inheritedTypes {
+            if let name = parent.resolveJSProtocolConstraint(for: inherited.type) {
+                protocolsByTarget[target, default: []].append(name)
+            }
+        }
+        return .visitChildren
+    }
+}