feat: preserve identity across all return shapes

Emit a per-class extension override of _BridgedSwiftHeapObject's
bridgeJSLowerReturn that routes through the identity cache, symmetric
to the existing bridgeJSStackPush override. This was necessary for
Optional<SwiftIdentityClass> returns: the _BridgedAsOptional bridge
calls value.bridgeJSLowerReturn() on the inner heap object, which
previously hit the default implementation (passRetained + bare pointer)
and bypassed our per-class identity table.

With this override, scalar, array-element, and Optional returns all
route through the same identity handshake. Before the fix, .some(x)
returned a fresh wrapper each call; now it preserves === identity.

Side benefit: the per-method `case .swiftHeapObject where isSwiftIdentityMode`
branch in ExportedThunkBuilder.lowerReturnValue is redundant —
ret.bridgeJSLowerReturn() picks up the extension override automatically.
The builder's isSwiftIdentityMode predicate is removed; codegen is
simpler.

The upgraded E2E test now asserts === identity for Optional.some.
165/165 tests green.

Author: krodak

Benchmarks/Sources/Generated/BridgeJS.swift

@@ -1822,13 +1822,7 @@ nonisolated(unsafe) var _SimpleClassSwiftIdentity_identityTable: Set<UnsafeMutab
 public func _bjs_SimpleClassSwiftIdentity_init(_ nameBytes: Int32, _ nameLength: Int32, _ count: Int32, _ flag: Int32, _ rate: Float32, _ precise: Float64) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = SimpleClassSwiftIdentity(name: String.bridgeJSLiftParameter(nameBytes, nameLength), count: Int.bridgeJSLiftParameter(count), flag: Bool.bridgeJSLiftParameter(flag), rate: Float.bridgeJSLiftParameter(rate), precise: Double.bridgeJSLiftParameter(precise))
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -1961,6 +1955,16 @@ public func _bjs_SimpleClassSwiftIdentity_release_wrapper(_ pointer: UnsafeMutab
 }
 
 extension SimpleClassSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -2001,13 +2005,7 @@ nonisolated(unsafe) var _ClassRoundtripSwiftIdentity_identityTable: Set<UnsafeMu
 public func _bjs_ClassRoundtripSwiftIdentity_init() -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _ClassRoundtripSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2018,13 +2016,7 @@ public func _bjs_ClassRoundtripSwiftIdentity_init() -> UnsafeMutableRawPointer {
 public func _bjs_ClassRoundtripSwiftIdentity_roundtripSimpleClassSwiftIdentity(_ _self: UnsafeMutableRawPointer, _ obj: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity.bridgeJSLiftParameter(_self).roundtripSimpleClassSwiftIdentity(_: SimpleClassSwiftIdentity.bridgeJSLiftParameter(obj))
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2035,13 +2027,7 @@ public func _bjs_ClassRoundtripSwiftIdentity_roundtripSimpleClassSwiftIdentity(_
 public func _bjs_ClassRoundtripSwiftIdentity_makeSimpleClassSwiftIdentity(_ _self: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = ClassRoundtripSwiftIdentity.bridgeJSLiftParameter(_self).makeSimpleClassSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SimpleClassSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2079,6 +2065,16 @@ public func _bjs_ClassRoundtripSwiftIdentity_release_wrapper(_ pointer: UnsafeMu
 }
 
 extension ClassRoundtripSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _ClassRoundtripSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -2119,13 +2115,7 @@ nonisolated(unsafe) var _IdentityCacheBenchmarkSwiftIdentity_identityTable: Set<
 public func _bjs_IdentityCacheBenchmarkSwiftIdentity_init() -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = IdentityCacheBenchmarkSwiftIdentity()
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _IdentityCacheBenchmarkSwiftIdentity_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -2174,6 +2164,16 @@ public func _bjs_IdentityCacheBenchmarkSwiftIdentity_release_wrapper(_ pointer:
 }
 
 extension IdentityCacheBenchmarkSwiftIdentity {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _IdentityCacheBenchmarkSwiftIdentity_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -125,15 +125,9 @@ public class ExportSwift {
         var abiReturnType: WasmCoreType?
         var externDecls: [DeclSyntax] = []
         let effects: Effects
-        /// Predicate that resolves whether a class-name corresponds to an
-        /// `identityMode: "swift"` class. Default: always false. Threaded
-        /// through from `ExportSwift.isSwiftIdentityMode(_:)` at construction
-        /// time so return-lowering can emit the per-class cache glue.
-        let isSwiftIdentityMode: (String) -> Bool
 
-        init(effects: Effects, isSwiftIdentityMode: @escaping (String) -> Bool = { _ in false }) {
+        init(effects: Effects) {
             self.effects = effects
-            self.isSwiftIdentityMode = isSwiftIdentityMode
         }
 
         private func append(_ item: CodeBlockItemSyntax) {
@@ -351,27 +345,13 @@ public class ExportSwift {
                     }
                     """
                 )
-            case .swiftHeapObject(let className) where isSwiftIdentityMode(className):
-                // identityMode: "swift" — Swift's per-class Set tracks which
-                // pointers have been retained. On miss, retain once; on hit,
-                // skip. No signalling to JS needed: JS checks its own
-                // `Map<pointer, wrapper>` and derives hit/miss symmetrically.
-                // (See DECISIONS.md D20 for why dropping freshBit is safe:
-                // the Swift Set and the JS Map stay in lockstep by
-                // construction — both are keyed by pointer and updated at
-                // the same cache boundaries.)
-                append(
-                    """
-                    return withExtendedLifetime(ret) {
-                        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-                        if _\(raw: className)_identityTable.insert(ptr).inserted {
-                            _ = Unmanaged.passRetained(ret)
-                        }
-                        return ptr
-                    }
-                    """
-                )
             default:
+                // For `@JS(identityMode: .swift)` classes, the per-class
+                // `bridgeJSLowerReturn` override emitted in
+                // `renderSingleExportedClass` routes through the identity
+                // table. Array-element and Optional paths go through the same
+                // override (plus `bridgeJSStackPush`), so every return shape
+                // preserves `===` identity.
                 append("return ret.bridgeJSLowerReturn()")
             }
         }
@@ -506,8 +486,7 @@ public class ExportSwift {
         let isStatic = context.isStatic
 
         let getterBuilder = ExportedThunkBuilder(
-            effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic),
-            isSwiftIdentityMode: isSwiftIdentityMode
+            effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic)
         )
 
         if !isStatic {
@@ -528,8 +507,7 @@ public class ExportSwift {
         // Generate property setter if not readonly
         if !property.isReadonly {
             let setterBuilder = ExportedThunkBuilder(
-                effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic),
-                isSwiftIdentityMode: isSwiftIdentityMode
+                effects: Effects(isAsync: false, isThrows: false, isStatic: isStatic)
             )
 
             // Lift parameters based on property type
@@ -559,7 +537,7 @@ public class ExportSwift {
     }
 
     func renderSingleExportedFunction(function: ExportedFunction) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: function.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: function.effects)
         for param in function.parameters {
             try builder.liftParameter(param: param)
         }
@@ -588,7 +566,7 @@ public class ExportSwift {
         callName: String,
         returnType: BridgeType
     ) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: constructor.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: constructor.effects)
         for param in constructor.parameters {
             try builder.liftParameter(param: param)
         }
@@ -602,7 +580,7 @@ public class ExportSwift {
         ownerTypeName: String,
         instanceSelfType: BridgeType
     ) throws -> DeclSyntax {
-        let builder = ExportedThunkBuilder(effects: method.effects, isSwiftIdentityMode: isSwiftIdentityMode)
+        let builder = ExportedThunkBuilder(effects: method.effects)
         if !method.effects.isStatic {
             try builder.liftParameter(param: Parameter(label: nil, name: "_self", type: instanceSelfType))
         }
@@ -772,12 +750,23 @@ public class ExportSwift {
                 decls.append(DeclSyntax(releaseDecl))
             }
 
-            // Override the default `_BridgedSwiftHeapObject.bridgeJSStackPush`
-            // so array-element returns (`[SwiftCached]`) go through the same
-            // identity-cache handshake. Post-D20: no `freshBit` push — JS
-            // checks its own Map for hit/miss.
-            let stackPushExt: DeclSyntax = """
+            // Override the default `_BridgedSwiftHeapObject` return/push paths
+            // so every return type that bottoms out at a heap-object pointer —
+            // scalar, array element, Optional — goes through the identity-cache
+            // handshake. All three paths converge on the same per-class Set
+            // check + conditional retain.
+            let swiftIdentityOverridesExt: DeclSyntax = """
                 extension \(raw: klass.swiftCallName) {
+                    @_spi(BridgeJS) @_transparent
+                    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+                        return withExtendedLifetime(self) {
+                            let ptr = Unmanaged.passUnretained(self).toOpaque()
+                            if _\(raw: klass.name)_identityTable.insert(ptr).inserted {
+                                _ = Unmanaged.passRetained(self)
+                            }
+                            return ptr
+                        }
+                    }
                     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
                         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
                             let ptr = Unmanaged.passUnretained(self).toOpaque()
@@ -790,7 +779,7 @@ public class ExportSwift {
                     }
                 }
                 """
-            decls.append(stackPushExt)
+            decls.append(swiftIdentityOverridesExt)
         }
 
         // Generate ConvertibleToJSValue extension

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

@@ -5,13 +5,7 @@ nonisolated(unsafe) var _SwiftCached_identityTable: Set<UnsafeMutableRawPointer>
 public func _bjs_SwiftCached_init(_ nameBytes: Int32, _ nameLength: Int32) -> UnsafeMutableRawPointer {
     #if arch(wasm32)
     let ret = SwiftCached(name: String.bridgeJSLiftParameter(nameBytes, nameLength))
-    return withExtendedLifetime(ret) {
-        let ptr = Unmanaged.passUnretained(ret).toOpaque()
-        if _SwiftCached_identityTable.insert(ptr).inserted {
-            _ = Unmanaged.passRetained(ret)
-        }
-        return ptr
-    }
+    return ret.bridgeJSLowerReturn()
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -60,6 +54,16 @@ public func _bjs_SwiftCached_release_wrapper(_ pointer: UnsafeMutableRawPointer)
 }
 
 extension SwiftCached {
+    @_spi(BridgeJS) @_transparent
+    public consuming func bridgeJSLowerReturn() -> UnsafeMutableRawPointer {
+        return withExtendedLifetime(self) {
+            let ptr = Unmanaged.passUnretained(self).toOpaque()
+            if _SwiftCached_identityTable.insert(ptr).inserted {
+                _ = Unmanaged.passRetained(self)
+            }
+            return ptr
+        }
+    }
     @_spi(BridgeJS) public consuming func bridgeJSStackPush() {
         let ptr: UnsafeMutableRawPointer = withExtendedLifetime(self) {
             let ptr = Unmanaged.passUnretained(self).toOpaque()

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Identity-Modes-For-Exported-Classes.md

@@ -69,12 +69,20 @@ The key differences vs `.pointer`:
 ```javascript
 const b = exports.getBuilding();  // allocates a wrapper (if fresh)
 b.name;                           // stable === with any future getBuilding() that returns the same Swift object
-b.release();                      // mandatory for swift mode — frees the Swift heap object and the wrapper slot
+b.release();                      // frees the Swift heap object and the wrapper slot
 // after release(): b.name throws "Attempted to call a member on a released Building"
 ```
 
 Double-release is a safe no-op. Static members (class-level methods, constructors) are not affected by release.
 
+### Why `release()` is required
+
+`.pointer` mode uses a `WeakRef` and a `FinalizationRegistry` to let the JS garbage collector reclaim wrappers whose users have dropped all references. That safety net is exactly what makes `.pointer` mode's miss path expensive — `FinalizationRegistry.register` and `new WeakRef` allocations account for ~88% of the per-miss cost. `.swift` mode removes both, which is where its performance comes from. The tradeoff is that the JS garbage collector no longer has any hook to trigger cleanup; Swift holds a strong retain until you explicitly release.
+
+In practice this is the same discipline as any manually-managed resource (file handles, network sockets, native-backed buffers). Use `try { … } finally { x.release() }` for scopes that can throw, or wrap long-lived objects in application code that owns their release.
+
+If you can't live with explicit release, stay on `.pointer` mode.
+
 ## Benchmarks (summary)
 
 Full results in [`Benchmarks/results/swift-side-cache/Benchmarks.md`](../../../../../Benchmarks/results/swift-side-cache/Benchmarks.md). Baseline arm64-macOS, Swift 6.3, Node 22, release build, 500k iters per scenario, median ms:
@@ -91,8 +99,7 @@ Full results in [`Benchmarks/results/swift-side-cache/Benchmarks.md`](../../../.
 
 ## Known limitations
 
-- **Optional<SwiftIdentityClass> identity is not preserved.** If your Swift API returns `SomeClass?`, `.some(x)` produces a fresh wrapper each call even with `.swift` mode. Lifecycle is still correct, but `a === b` where both come from an optional return will be `false`. Workaround: wrap in `[SomeClass]` (array element identity IS preserved).
-- **No automatic cleanup.** You must call `release()` explicitly. A future version may add a Swift-side timeout or GC-assisted cleanup.
+- **No GC-driven cleanup.** Wrappers live until `release()` is called. Dropping all JS references to a wrapper without releasing leaks the Swift heap object. See "Why `release()` is required" above.
 - **Wasm-only.** Like all of BridgeJS, identity modes only activate on `wasm32`. On the host, the macro expands to no-op code paths so your test harness can still compile.
 
 ## Choosing a mode