BridgeJS: Add opt-in TypedArray bridging for numeric arrays

Add typedArrayBridging config option ('always'/'never', default 'never')
and per-declaration @js(typedArray: true) override that bridges Swift
numeric arrays as JavaScript TypedArrays instead of Array<number>.

When enabled, [UInt8] becomes Uint8Array, [Float] becomes Float32Array,
[Double] becomes Float64Array, etc. Non-numeric arrays are unaffected.

Swift->JS direction uses bulk memory copy via memory.buffer.slice().
Uses .slice() (copy) instead of a zero-copy view because TypedArray
views into memory.buffer are invalidated when WASM memory grows.
JS->Swift direction falls back to element-by-element stack protocol.

- Add TypedArrayKind enum and BridgeType.typedArray case
- Add typedArrayBridging config to BridgeJSConfig
- Add @js(typedArray:) per-declaration override parameter
- Add _BridgeJSTypedArrayElement protocol and intrinsics
- Generate TypedArray construction in JS glue code
- Add UInt8 array benchmarks
- Update Documentation.docc for new config and type mapping

Author: krodak

Benchmarks/Sources/Benchmarks.swift

@@ -384,6 +384,20 @@ class IdentityCacheBenchmarkIdentity {
         return Array(1...10000)
     }
 
+    // MARK: Primitive Arrays - UInt8
+
+    @JS func takeUInt8Array(_ values: [UInt8]) {}
+    @JS func makeUInt8Array() -> [UInt8] {
+        return (0..<1000).map { UInt8($0 % 256) }
+    }
+    @JS func roundtripUInt8Array(_ values: [UInt8]) -> [UInt8] {
+        return values
+    }
+
+    @JS func makeUInt8ArrayLarge() -> [UInt8] {
+        return (0..<10000).map { UInt8($0 % 256) }
+    }
+
     // MARK: Primitive Arrays - Double
 
     @JS func takeDoubleArray(_ values: [Double]) {}

Benchmarks/Sources/Generated/BridgeJS.swift

@@ -1870,6 +1870,49 @@ public func _bjs_ArrayRoundtrip_makeIntArrayLarge(_ _self: UnsafeMutableRawPoint
     #endif
 }
 
+@_expose(wasm, "bjs_ArrayRoundtrip_takeUInt8Array")
+@_cdecl("bjs_ArrayRoundtrip_takeUInt8Array")
+public func _bjs_ArrayRoundtrip_takeUInt8Array(_ _self: UnsafeMutableRawPointer) -> Void {
+    #if arch(wasm32)
+    ArrayRoundtrip.bridgeJSLiftParameter(_self).takeUInt8Array(_: [UInt8].bridgeJSStackPop())
+    #else
+    fatalError("Only available on WebAssembly")
+    #endif
+}
+
+@_expose(wasm, "bjs_ArrayRoundtrip_makeUInt8Array")
+@_cdecl("bjs_ArrayRoundtrip_makeUInt8Array")
+public func _bjs_ArrayRoundtrip_makeUInt8Array(_ _self: UnsafeMutableRawPointer) -> Void {
+    #if arch(wasm32)
+    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).makeUInt8Array()
+    ret.bridgeJSStackPush()
+    #else
+    fatalError("Only available on WebAssembly")
+    #endif
+}
+
+@_expose(wasm, "bjs_ArrayRoundtrip_roundtripUInt8Array")
+@_cdecl("bjs_ArrayRoundtrip_roundtripUInt8Array")
+public func _bjs_ArrayRoundtrip_roundtripUInt8Array(_ _self: UnsafeMutableRawPointer) -> Void {
+    #if arch(wasm32)
+    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).roundtripUInt8Array(_: [UInt8].bridgeJSStackPop())
+    ret.bridgeJSStackPush()
+    #else
+    fatalError("Only available on WebAssembly")
+    #endif
+}
+
+@_expose(wasm, "bjs_ArrayRoundtrip_makeUInt8ArrayLarge")
+@_cdecl("bjs_ArrayRoundtrip_makeUInt8ArrayLarge")
+public func _bjs_ArrayRoundtrip_makeUInt8ArrayLarge(_ _self: UnsafeMutableRawPointer) -> Void {
+    #if arch(wasm32)
+    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).makeUInt8ArrayLarge()
+    ret.bridgeJSStackPush()
+    #else
+    fatalError("Only available on WebAssembly")
+    #endif
+}
+
 @_expose(wasm, "bjs_ArrayRoundtrip_takeDoubleArray")
 @_cdecl("bjs_ArrayRoundtrip_takeDoubleArray")
 public func _bjs_ArrayRoundtrip_takeDoubleArray(_ _self: UnsafeMutableRawPointer) -> Void {

Benchmarks/Sources/Generated/JavaScript/BridgeJS.json

@@ -1902,6 +1902,125 @@
               }
             }
           },
+          {
+            "abiName" : "bjs_ArrayRoundtrip_takeUInt8Array",
+            "effects" : {
+              "isAsync" : false,
+              "isStatic" : false,
+              "isThrows" : false
+            },
+            "name" : "takeUInt8Array",
+            "parameters" : [
+              {
+                "label" : "_",
+                "name" : "values",
+                "type" : {
+                  "array" : {
+                    "_0" : {
+                      "integer" : {
+                        "_0" : {
+                          "isSigned" : false,
+                          "width" : "w8"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            ],
+            "returnType" : {
+              "void" : {
+
+              }
+            }
+          },
+          {
+            "abiName" : "bjs_ArrayRoundtrip_makeUInt8Array",
+            "effects" : {
+              "isAsync" : false,
+              "isStatic" : false,
+              "isThrows" : false
+            },
+            "name" : "makeUInt8Array",
+            "parameters" : [
+
+            ],
+            "returnType" : {
+              "array" : {
+                "_0" : {
+                  "integer" : {
+                    "_0" : {
+                      "isSigned" : false,
+                      "width" : "w8"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "abiName" : "bjs_ArrayRoundtrip_roundtripUInt8Array",
+            "effects" : {
+              "isAsync" : false,
+              "isStatic" : false,
+              "isThrows" : false
+            },
+            "name" : "roundtripUInt8Array",
+            "parameters" : [
+              {
+                "label" : "_",
+                "name" : "values",
+                "type" : {
+                  "array" : {
+                    "_0" : {
+                      "integer" : {
+                        "_0" : {
+                          "isSigned" : false,
+                          "width" : "w8"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            ],
+            "returnType" : {
+              "array" : {
+                "_0" : {
+                  "integer" : {
+                    "_0" : {
+                      "isSigned" : false,
+                      "width" : "w8"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "abiName" : "bjs_ArrayRoundtrip_makeUInt8ArrayLarge",
+            "effects" : {
+              "isAsync" : false,
+              "isStatic" : false,
+              "isThrows" : false
+            },
+            "name" : "makeUInt8ArrayLarge",
+            "parameters" : [
+
+            ],
+            "returnType" : {
+              "array" : {
+                "_0" : {
+                  "integer" : {
+                    "_0" : {
+                      "isSigned" : false,
+                      "width" : "w8"
+                    }
+                  }
+                }
+              }
+            }
+          },
           {
             "abiName" : "bjs_ArrayRoundtrip_takeDoubleArray",
             "effects" : {

Benchmarks/run.js

@@ -668,6 +668,30 @@ async function singleRun(results, nameFilter, iterations) {
         }
     })
 
+    // Primitive Arrays - UInt8
+    benchmarkRunner("ArrayRoundtrip/takeUInt8Array", () => {
+        const arr = Array.from({length: 1000}, (_, i) => i % 256)
+        for (let i = 0; i < iterations; i++) {
+            arrayRoundtrip.takeUInt8Array(arr)
+        }
+    })
+    benchmarkRunner("ArrayRoundtrip/makeUInt8Array", () => {
+        for (let i = 0; i < iterations; i++) {
+            arrayRoundtrip.makeUInt8Array()
+        }
+    })
+    benchmarkRunner("ArrayRoundtrip/roundtripUInt8Array", () => {
+        const arr = Array.from({length: 1000}, (_, i) => i % 256)
+        for (let i = 0; i < iterations; i++) {
+            arrayRoundtrip.roundtripUInt8Array(arr)
+        }
+    })
+    benchmarkRunner("ArrayRoundtrip/makeUInt8ArrayLarge", () => {
+        for (let i = 0; i < iterations; i++) {
+            arrayRoundtrip.makeUInt8ArrayLarge()
+        }
+    })
+
     // Primitive Arrays - Double
     benchmarkRunner("ArrayRoundtrip/takeDoubleArray", () => {
         const arr = Array.from({length: 1000}, (_, i) => (i + 1) * 1.1)

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -137,7 +137,7 @@ public class ExportSwift {
             case .swiftStruct(let structName):
                 typeNameForIntrinsic = structName
                 liftingExpr = ExprSyntax("\(raw: structName).bridgeJSLiftParameter()")
-            case .array:
+            case .array, .typedArray:
                 typeNameForIntrinsic = param.type.swiftType
                 liftingExpr = StackCodegen().liftExpression(for: param.type)
             case .nullable(let wrappedType, let kind):
@@ -306,6 +306,16 @@ public class ExportSwift {
                 for stmt in stackCodegen.lowerStatements(for: returnType, accessor: "ret", varPrefix: "ret") {
                     append(stmt)
                 }
+            case .typedArray:
+                // Top-level typed array return: use immediate copy via _bridgeJS_typedArrayPush
+                append("_bridgeJS_typedArrayPush(ret)")
+            case .nullable(.typedArray, _):
+                // Optional typed arrays in return position: use stack-based optional protocol
+                // (element-by-element) to match JS liftReturn's optional handling.
+                let stackCodegen = StackCodegen()
+                for stmt in stackCodegen.lowerStatements(for: returnType, accessor: "ret", varPrefix: "ret") {
+                    append(stmt)
+                }
             case .dictionary(.swiftProtocol):
                 let stackCodegen = StackCodegen()
                 for stmt in stackCodegen.lowerStatements(for: returnType, accessor: "ret", varPrefix: "ret") {
@@ -754,7 +764,8 @@ struct StackCodegen {
         switch type {
         case .string, .integer, .bool, .float, .double,
             .jsObject(nil), .jsValue, .swiftStruct, .swiftHeapObject, .unsafePointer,
-            .swiftProtocol, .caseEnum, .associatedValueEnum, .rawValueEnum, .array, .dictionary:
+            .swiftProtocol, .caseEnum, .associatedValueEnum, .rawValueEnum, .array, .dictionary,
+            .typedArray:
             return "\(raw: type.swiftType).bridgeJSStackPop()"
         case .jsObject(let className?):
             return "\(raw: className)(unsafelyWrapping: JSObject.bridgeJSStackPop())"
@@ -772,7 +783,7 @@ struct StackCodegen {
         switch wrappedType {
         case .string, .integer, .bool, .float, .double, .jsObject(nil), .jsValue,
             .swiftStruct, .swiftHeapObject, .caseEnum, .associatedValueEnum, .rawValueEnum,
-            .array, .dictionary:
+            .array, .dictionary, .typedArray:
             return "\(raw: typeName)<\(raw: wrappedType.swiftType)>.bridgeJSStackPop()"
         case .jsObject(let className?):
             return "\(raw: typeName)<JSObject>.bridgeJSStackPop().map { \(raw: className)(unsafelyWrapping: $0) }"
@@ -807,6 +818,21 @@ struct StackCodegen {
             return []
         case .array(let elementType):
             return lowerArrayStatements(elementType: elementType, accessor: accessor, varPrefix: varPrefix)
+        case .typedArray(let kind):
+            // In stack context (struct fields), use element-by-element protocol
+            // to match JS stackLiftFragment which also falls back to arrayLift.
+            let elementType: BridgeType
+            switch kind {
+            case .int8: elementType = .integer(.int8)
+            case .uint8: elementType = .integer(.uint8)
+            case .int16: elementType = .integer(.int16)
+            case .uint16: elementType = .integer(.uint16)
+            case .int32, .intWord: elementType = .integer(.int32)
+            case .uint32, .uintWord: elementType = .integer(.uint32)
+            case .float32: elementType = .float
+            case .float64: elementType = .double
+            }
+            return lowerArrayStatements(elementType: elementType, accessor: accessor, varPrefix: varPrefix)
         case .dictionary(let valueType):
             return lowerDictionaryStatements(valueType: valueType, accessor: accessor, varPrefix: varPrefix)
         }
@@ -1459,6 +1485,7 @@ extension BridgeType {
         case .nullable(let wrappedType, let kind):
             return kind == .null ? "Optional<\(wrappedType.swiftType)>" : "JSUndefinedOr<\(wrappedType.swiftType)>"
         case .array(let elementType): return "[\(elementType.swiftType)]"
+        case .typedArray(let kind): return "[\(kind.swiftElementType)]"
         case .dictionary(let valueType): return "[String: \(valueType.swiftType)]"
         case .caseEnum(let name): return name
         case .rawValueEnum(let name, _): return name
@@ -1490,7 +1517,7 @@ extension BridgeType {
 
     var isStackUsingParameter: Bool {
         switch self {
-        case .swiftStruct, .array, .dictionary, .associatedValueEnum:
+        case .swiftStruct, .array, .dictionary, .associatedValueEnum, .typedArray:
             return true
         case .nullable(let wrapped, _):
             return wrapped.isStackUsingParameter
@@ -1550,7 +1577,7 @@ extension BridgeType {
             throw BridgeJSCoreError("Namespace enums are not supported to pass as parameters")
         case .closure:
             return LiftingIntrinsicInfo(parameters: [("callbackId", .i32)])
-        case .array, .dictionary:
+        case .array, .dictionary, .typedArray:
             return LiftingIntrinsicInfo(parameters: [])
         }
     }
@@ -1601,7 +1628,7 @@ extension BridgeType {
             throw BridgeJSCoreError("Namespace enums are not supported to pass as parameters")
         case .closure:
             return .jsObject
-        case .array, .dictionary:
+        case .array, .dictionary, .typedArray:
             return .array
         }
     }

Plugins/BridgeJS/Sources/BridgeJSCore/ImportTS.swift

@@ -962,7 +962,7 @@ extension BridgeType {
             var params = [("isSome", WasmCoreType.i32)]
             params.append(contentsOf: wrappedInfo.loweredParameters)
             return LoweringParameterInfo(loweredParameters: params, useBorrowing: wrappedInfo.useBorrowing)
-        case .array, .dictionary:
+        case .array, .dictionary, .typedArray:
             return LoweringParameterInfo(loweredParameters: [])
         }
     }
@@ -1040,7 +1040,7 @@ extension BridgeType {
             }
             let wrappedInfo = try wrappedType.liftingReturnInfo(context: context)
             return LiftingReturnInfo(valueToLift: wrappedInfo.valueToLift)
-        case .array, .dictionary:
+        case .array, .dictionary, .typedArray:
             return LiftingReturnInfo(valueToLift: nil)
         }
     }

Plugins/BridgeJS/Sources/BridgeJSCore/Misc.swift

@@ -351,23 +351,40 @@ public struct BridgeJSConfig: Codable {
     /// Default: `nil` (treated as `"none"`)
     public var identityMode: String?
 
-    public init(tools: [String: String]? = nil, exposeToGlobal: Bool = false, identityMode: String? = nil) {
+    /// Controls whether numeric Swift arrays are bridged as JavaScript TypedArrays.
+    ///
+    /// - `"always"`: Numeric arrays (`[UInt8]`, `[Float]`, `[Double]`, etc.)
+    ///   are bridged as TypedArrays; non-numeric arrays remain `Array<T>`.
+    /// - `"never"` (default): All arrays use the element-by-element stack protocol (backward compat).
+    ///
+    /// Default: `nil` (treated as `"never"`)
+    public var typedArrayBridging: String?
+
+    public init(
+        tools: [String: String]? = nil,
+        exposeToGlobal: Bool = false,
+        identityMode: String? = nil,
+        typedArrayBridging: String? = nil
+    ) {
         self.tools = tools
         self.exposeToGlobal = exposeToGlobal
         self.identityMode = identityMode
+        self.typedArrayBridging = typedArrayBridging
     }
 
     enum CodingKeys: String, CodingKey {
         case tools
         case exposeToGlobal
         case identityMode
+        case typedArrayBridging
     }
 
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         tools = try container.decodeIfPresent([String: String].self, forKey: .tools)
         exposeToGlobal = try container.decodeIfPresent(Bool.self, forKey: .exposeToGlobal) ?? false
         identityMode = try container.decodeIfPresent(String.self, forKey: .identityMode)
+        typedArrayBridging = try container.decodeIfPresent(String.self, forKey: .typedArrayBridging)
     }
 
     /// Load the configuration file from the SwiftPM package target directory.
@@ -411,7 +428,8 @@ public struct BridgeJSConfig: Codable {
         return BridgeJSConfig(
             tools: (tools ?? [:]).merging(overrides.tools ?? [:], uniquingKeysWith: { $1 }),
             exposeToGlobal: overrides.exposeToGlobal,
-            identityMode: overrides.identityMode ?? identityMode
+            identityMode: overrides.identityMode ?? identityMode,
+            typedArrayBridging: overrides.typedArrayBridging ?? typedArrayBridging
         )
     }
 }