BridgeJS: Support custom exported type names

Author: krodak

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -110,6 +110,14 @@ final class JSGlueVariableScope {
         intrinsicRegistry.typeOwnerModules[typeName]
     }
 
+    func exportedClassPath(forSwiftName name: String) -> [String]? {
+        intrinsicRegistry.classPaths[name]
+    }
+
+    func renamedEnumNames(forSwiftName name: String) -> (value: String, type: String)? {
+        intrinsicRegistry.renamedEnumNames[name]
+    }
+
     func makeChildScope() -> JSGlueVariableScope {
         JSGlueVariableScope(intrinsicRegistry: intrinsicRegistry)
     }
@@ -532,8 +540,6 @@ struct IntrinsicJSFragment: Sendable {
         /// Whether the fragment has direct access to the SwiftHeapObject classes.
         /// If false, the fragment needs to use `_exports` to access the class.
         var hasDirectAccessToSwiftClass: Bool = true
-        /// Maps class names to their namespace path components for resolving `_exports` access.
-        var classNamespaces: [String: [String]] = [:]
 
         func with<T>(_ keyPath: WritableKeyPath<PrintCodeContext, T>, _ value: T) -> PrintCodeContext {
             var new = self
@@ -545,20 +551,30 @@ struct IntrinsicJSFragment: Sendable {
             qualifiedName.split(separator: ".").last.map(String.init) ?? qualifiedName
         }
 
-        private func exportsAccess(forClass name: String) -> String {
-            if let namespace = classNamespaces[name], !namespace.isEmpty {
-                let path = namespace.map { ".\($0)" }.joined()
-                return "_exports\(path).\(name)"
-            }
-            return "_exports['\(name)']"
-        }
-
         func classReference(forQualifiedName qualifiedName: String) -> String {
+            if let path = scope.exportedClassPath(forSwiftName: qualifiedName), let name = path.last {
+                if hasDirectAccessToSwiftClass {
+                    return name
+                }
+                return path.count == 1 ? "_exports['\(name)']" : "_exports.\(path.joined(separator: "."))"
+            }
             if hasDirectAccessToSwiftClass {
                 return unqualifiedClassName(for: qualifiedName)
             }
-            let unqualified = unqualifiedClassName(for: qualifiedName)
-            return exportsAccess(forClass: unqualified)
+            return "_exports['\(unqualifiedClassName(for: qualifiedName))']"
+        }
+
+        func defaultValueTypeName(_ type: BridgeType, _ format: DefaultValueUtils.OutputFormat) -> String? {
+            switch type {
+            case .swiftHeapObject(let name):
+                guard let jsName = scope.exportedClassPath(forSwiftName: name)?.last else { return nil }
+                return format == .javascript ? classReference(forQualifiedName: name) : jsName
+            case .caseEnum(let name):
+                guard let renamed = scope.renamedEnumNames(forSwiftName: name) else { return nil }
+                return format == .javascript ? renamed.value : renamed.type
+            default:
+                return nil
+            }
         }
     }
 
@@ -2565,7 +2581,10 @@ struct IntrinsicJSFragment: Sendable {
 
             // Attach instance methods to the struct instance
             for method in structDef.methods where !method.effects.isStatic {
-                let paramList = DefaultValueUtils.formatParameterList(method.parameters)
+                let paramList = DefaultValueUtils.formatParameterList(
+                    method.parameters,
+                    resolveTypeName: context.defaultValueTypeName
+                )
                 printer.write(
                     "\(instanceVar).\(method.resolvedJSName) = function(\(paramList)) {"
                 )

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -5,7 +5,8 @@ import BridgeJSUtilities
 /// Registry for JS helper intrinsics used during code generation.
 final class JSIntrinsicRegistry {
     private var entries: [String: [String]] = [:]
-    var classNamespaces: [String: [String]] = [:]
+    var classPaths: [String: [String]] = [:]
+    var renamedEnumNames: [String: (value: String, type: String)] = [:]
 
     var typeOwnerModules: [String: String] = [:]
 
@@ -42,7 +43,8 @@ final class JSIntrinsicRegistry {
 
     func reset() {
         entries.removeAll()
-        classNamespaces.removeAll()
+        classPaths.removeAll()
+        renamedEnumNames.removeAll()
         typeOwnerModules.removeAll()
         codecNameOrder.removeAll()
         codecBodies.removeAll()

Plugins/BridgeJS/Sources/BridgeJSLink/JSGlueGen.swift

@@ -4,10 +4,17 @@
 
 public protocol NamespacedExportedType {
     var name: String { get }
+    var jsName: String? { get }
+    /// The namespace using Swift declaration names, retained for ABI generation.
     var namespace: [String]? { get }
+    /// The public namespace when an enclosing declaration has an exported name override.
+    var jsNamespace: [String]? { get }
 }
 
 extension NamespacedExportedType {
+    public var resolvedJSName: String { jsName ?? name }
+    public var resolvedJSNamespace: [String]? { jsNamespace ?? namespace }
+
     public var abiName: String {
         if let namespace = namespace, !namespace.isEmpty {
             return (namespace + [name]).joined(separator: "_")
@@ -16,7 +23,7 @@ extension NamespacedExportedType {
     }
 
     public var tsPathComponents: [String] {
-        (namespace ?? []) + [name]
+        (resolvedJSNamespace ?? []) + [resolvedJSName]
     }
 
     public var tsFullPath: String {
@@ -778,31 +785,37 @@ public struct StructField: Codable, Equatable, Sendable {
 
 public struct ExportedStruct: Codable, Equatable, Sendable, NamespacedExportedType {
     public let name: String
+    public let jsName: String?
     public let swiftCallName: String
     public let explicitAccessControl: String?
     public var properties: [ExportedProperty]
     public var constructor: ExportedConstructor?
     public var methods: [ExportedFunction]
     public let namespace: [String]?
+    public let jsNamespace: [String]?
     public var documentation: String?
 
     public init(
         name: String,
+        jsName: String? = nil,
         swiftCallName: String,
         explicitAccessControl: String?,
         properties: [ExportedProperty] = [],
         constructor: ExportedConstructor? = nil,
         methods: [ExportedFunction] = [],
         namespace: [String]?,
+        jsNamespace: [String]? = nil,
         documentation: String? = nil
     ) {
         self.name = name
+        self.jsName = jsName
         self.swiftCallName = swiftCallName
         self.explicitAccessControl = explicitAccessControl
         self.properties = properties
         self.constructor = constructor
         self.methods = methods
         self.namespace = namespace
+        self.jsNamespace = jsNamespace
         self.documentation = documentation
     }
 }
@@ -864,12 +877,14 @@ public struct ExportedEnum: Codable, Equatable, Sendable, NamespacedExportedType
     public static let objectSuffix = "Object"
 
     public let name: String
+    public let jsName: String?
     public let swiftCallName: String
     public let tsFullPath: String
     public let explicitAccessControl: String?
     public var cases: [EnumCase]
     public let rawType: SwiftEnumRawType?
     public let namespace: [String]?
+    public let jsNamespace: [String]?
     public let emitStyle: EnumEmitStyle
     public var staticMethods: [ExportedFunction]
     public var staticProperties: [ExportedProperty] = []
@@ -885,33 +900,36 @@ public struct ExportedEnum: Codable, Equatable, Sendable, NamespacedExportedType
     }
 
     public var valuesName: String {
-        emitStyle == .tsEnum ? name : "\(name)\(Self.valuesSuffix)"
+        emitStyle == .tsEnum ? resolvedJSName : "\(resolvedJSName)\(Self.valuesSuffix)"
     }
 
     public var objectTypeName: String {
-        "\(name)\(Self.objectSuffix)"
+        "\(resolvedJSName)\(Self.objectSuffix)"
     }
 
     public init(
         name: String,
+        jsName: String? = nil,
         swiftCallName: String,
-        tsFullPath: String,
         explicitAccessControl: String?,
         cases: [EnumCase],
         rawType: SwiftEnumRawType?,
         namespace: [String]?,
+        jsNamespace: [String]? = nil,
         emitStyle: EnumEmitStyle,
         staticMethods: [ExportedFunction] = [],
         staticProperties: [ExportedProperty] = [],
         documentation: String? = nil
     ) {
         self.name = name
+        self.jsName = jsName
         self.swiftCallName = swiftCallName
-        self.tsFullPath = tsFullPath
+        self.tsFullPath = ((jsNamespace ?? namespace ?? []) + [jsName ?? name]).joined(separator: ".")
         self.explicitAccessControl = explicitAccessControl
         self.cases = cases
         self.rawType = rawType
         self.namespace = namespace
+        self.jsNamespace = jsNamespace
         self.emitStyle = emitStyle
         self.staticMethods = staticMethods
         self.staticProperties = staticProperties
@@ -947,24 +965,30 @@ public struct ExportedProtocolProperty: Codable, Equatable, Sendable {
     }
 }
 
-public struct ExportedProtocol: Codable, Equatable {
+public struct ExportedProtocol: Codable, Equatable, NamespacedExportedType {
     public let name: String
+    public let jsName: String?
     public let methods: [ExportedFunction]
     public let properties: [ExportedProtocolProperty]
     public let namespace: [String]?
+    public let jsNamespace: [String]?
     public var documentation: String?
 
     public init(
         name: String,
+        jsName: String? = nil,
         methods: [ExportedFunction],
         properties: [ExportedProtocolProperty] = [],
         namespace: [String]? = nil,
+        jsNamespace: [String]? = nil,
         documentation: String? = nil
     ) {
         self.name = name
+        self.jsName = jsName
         self.methods = methods
         self.properties = properties
         self.namespace = namespace
+        self.jsNamespace = jsNamespace
         self.documentation = documentation
     }
 }
@@ -1007,35 +1031,41 @@ public struct ExportedFunction: Codable, Equatable, Sendable {
 
 public struct ExportedClass: Codable, NamespacedExportedType {
     public var name: String
+    public var jsName: String?
     public var swiftCallName: String
     public var explicitAccessControl: String?
     public var constructor: ExportedConstructor?
     public var methods: [ExportedFunction]
     public var properties: [ExportedProperty]
     public var namespace: [String]?
+    public var jsNamespace: [String]?
     public var identityMode: Bool?  // nil = use config default, true/false = override
     public var documentation: String?
     public var isFinal: Bool?
 
     public init(
         name: String,
+        jsName: String? = nil,
         swiftCallName: String,
         explicitAccessControl: String?,
         constructor: ExportedConstructor? = nil,
         methods: [ExportedFunction],
         properties: [ExportedProperty] = [],
         namespace: [String]? = nil,
+        jsNamespace: [String]? = nil,
         identityMode: Bool? = nil,
         documentation: String? = nil,
         isFinal: Bool? = nil
     ) {
         self.name = name
+        self.jsName = jsName
         self.swiftCallName = swiftCallName
         self.explicitAccessControl = explicitAccessControl
         self.constructor = constructor
         self.methods = methods
         self.properties = properties
         self.namespace = namespace
+        self.jsNamespace = jsNamespace
         self.identityMode = identityMode
         self.documentation = documentation
         self.isFinal = isFinal

Plugins/BridgeJS/Sources/BridgeJSLink/JSIntrinsicRegistry.swift

@@ -77,6 +77,48 @@ export type Exports = {
 }
 ```
 
+## Choosing an Exported Name
+
+Pass a name to `@JS` to expose a class under a different JavaScript and TypeScript name while keeping its Swift identifier:
+
+```swift
+@JS("Counter") class InternalCounter {
+    @JS var value: Int
+
+    @JS init(value: Int) {
+        self.value = value
+    }
+
+    @JS static func make(_ value: Int) -> InternalCounter {
+        InternalCounter(value: value)
+    }
+
+    @JS func roundTrip(_ other: InternalCounter?) -> InternalCounter? {
+        other
+    }
+}
+```
+
+After initializing the package, use the constructor and static factory on that WASM instance's `exports` object:
+
+```javascript
+const counter = new exports.Counter(1);
+const other = exports.Counter.make(2);
+const returned = counter.roundTrip(other);
+console.log(returned.value); // 2
+returned.release();
+other.release();
+counter.release();
+```
+
+The generated TypeScript interface is named `Counter`, and signatures refer to `Counter`, including in optionals, arrays, and callbacks. For example, `roundTrip` accepts and returns `Counter | null`. The old name `InternalCounter` is not also exported. Swift code continues to use `InternalCounter`, including in extensions and return types.
+
+The constructor remains instance-owned: use `exports.Counter`, not a named JavaScript module import such as `import { Counter } from "./bridge-js.js"`. A TypeScript type-only import of `Counter` refers to the generated interface, not a constructor value. Renaming does not change reference semantics, `release()`, or identity mode.
+
+This naming option also applies to structs, enums, and protocols. For namespace composition and nested types, see <doc:Using-Namespace>.
+
+> Important: `@JS("Counter")` only changes the exported symbol. `@JS(as: Other.self)` instead changes the JavaScript representation through `bridgeToJS()` and `bridgeFromJS(_:)`. Combining a name override with `as:` on the same declaration produces a diagnostic.
+
 ## Adding Members via Extensions
 
 You can add exported methods, computed properties, and static members to a `@JS` class using extensions. The extension block itself does not need `@JS` - only the individual members do:

Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift

@@ -19,6 +19,35 @@ BridgeJS generates separate objects with descriptive naming for `.const` enums:
 - **`EnumNameTag`**: Represents the union type for enums
 - **`EnumNameObject`**: Object type for all const-style enums, contains static members for enums with methods/properties or references the values type for simple enums
 
+### Choosing an Exported Name
+
+A name passed to `@JS` changes the generated naming stem, not the Swift enum or its representation:
+
+```swift
+@JS("TaskState") enum InternalTaskState: String {
+    case pending
+    case complete
+}
+
+@JS func roundTripState(_ state: InternalTaskState) -> InternalTaskState {
+    state
+}
+```
+
+With the default `.const` style, this generates `TaskStateValues`, `TaskStateTag`, and `TaskStateObject` instead of names beginning with `InternalTaskState`. The instance export is `exports.TaskState`, and function signatures use `TaskStateTag`:
+
+```typescript
+import { TaskStateValues } from "./bridge-js.js";
+import type { TaskStateTag } from "./bridge-js.js";
+
+const state: TaskStateTag = exports.roundTripState(TaskStateValues.Pending);
+console.log(state === exports.TaskState.Pending); // true
+```
+
+The same naming rule applies to associated-value enums, including their payload type references. With `@JS("TaskState", enumStyle: .tsEnum)`, the TypeScript enum itself is named `TaskState`. Case names, raw values, and associated-value layouts are unchanged.
+
+For empty enums used as namespaces, the override names the namespace object. Nested declarations use that renamed parent in their export paths; see <doc:Using-Namespace>.
+
 ### Case Enums
 
 ```swift

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Class.md

@@ -13,6 +13,8 @@ When you mark a protocol with `@JS`, BridgeJS generates:
 - A TypeScript interface with the protocol's method signatures
 - A Swift wrapper struct (`Any{ProtocolName}`) that conforms to the protocol and bridges calls to JavaScript objects
 
+Use `@JS("PublicName")` on a protocol to rename its TypeScript interface and generated type references. Swift still uses the original protocol name for conformances and signatures. JavaScript objects still satisfy the interface structurally; renaming does not create a protocol constructor or change how callbacks and protocol values cross the boundary. Unlike `@JS(as: Other.self)`, it does not change the representation, and combining the two options is not supported.
+
 ## Example: Counter Protocol
 
 Mark a Swift protocol with `@JS` to expose it:

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Enum.md

@@ -6,7 +6,9 @@ Learn how to export Swift structs to JavaScript.
 
 > Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
 
-To export a Swift struct, mark it with `@JS`:
+To export a Swift struct, mark it with `@JS`.
+
+Use `@JS("PublicName")` to choose a different JavaScript and TypeScript name while keeping the Swift struct name. Generated interfaces, type references, and the instance export containing any exported initializer or static members use the chosen name. This does not change copy semantics or field names. Unlike `@JS(as: Other.self)`, it does not change the representation; the two options cannot be combined. See <doc:Exporting-Swift-Class> for an example of naming an exported type.
 
 ```swift
 import JavaScriptKit