Sorry for taking a long time 🙇
I ran some experiments to compare ABI designs for passing/returning composition types, including enum and struct.
Here’s a summary of three approaches, their trade-offs, and representative benchmark results.

Option 1: Memory-encoding ABI (current in this PR)

Encode each parameter into a byte buffer on the JS side, copy into Wasm memory, and decode on the Swift side.

I think it's very straightforward but I see some drawbacks:

• Needs a custom memory layout definition for each primitive.
  • We already have 4 ABI definitions for each type: lifting parameter, lowering result, lowering parameter, lifting result
  • Adding a new memory layout definition for each type is a bit concerning, as it increases the implementation cost to add a new type support.
• Multiple copies (encode to Uint8Array -> copy into Swift [UInt8] -> decode).
• Benchmarks: consistently slower.

I think we have some perf optimization space here but my major concern is its implementation complexity

Option 2: Stack-based ABI

Push Wasm core values of lowered parameter representation onto a temporary JS stack, pop them from Swift and lift them by reusing bridgeJSLiftParameter.

Similar to what you've done for result lifting here. We can apply it to both parameter passing and result returning.

lower: (value) => {
 const enumTag = value.tag;
 switch (enumTag) {
 case APIResult.Tag.Success: {
 const bytes = textEncoder.encode(value.param0);
 const bytesId = swift.memory.retain(bytes);
 tmpParamI32s.push(bytes.byteLength);
 tmpParamI32s.push(bytesId);
 return;
 }
 case APIResult.Tag.Failure: {
 tmpParamI32s.push(value.param0);
 return;
 }
 case APIResult.Tag.Flag: {
 tmpParamI32s.push(value.param0 ? 1 : 0);
 return;
 }
 case APIResult.Tag.Rate: {
 tmpParamF64s.push(value.param0);
 return;
 }
 case APIResult.Tag.Precise: {
 tmpParamF64s.push(value.param0);
 return;
 }
 case APIResult.Tag.Info: {
 return;
 }
 default: throw new Error("Unknown APIResult tag: " + String(enumTag));
 }
},
addImports: (importObject, importsContext) => {
 ...
 bjs["swift_js_pop_param_int32"] = function() {
 return tmpParamI32s.pop();
 }
 bjs["swift_js_pop_param_float64"] = function() {
 return tmpParamF64s.pop();
 }
}

private extension APIResult {
 static func bridgeJSLiftParameter(_ caseId: Int32) -> APIResult {
 switch caseId {
 case 0:
 return .success(String.bridgeJSLiftParameter(_swift_js_pop_param_int32(), _swift_js_pop_param_int32()))
 case 1:
 return .failure(Int.bridgeJSLiftParameter(_swift_js_pop_param_int32()))
 case 2:
 return .flag(Bool.bridgeJSLiftParameter(_swift_js_pop_param_int32()))
 case 3:
 return .rate(Float.bridgeJSLiftParameter(_swift_js_pop_param_float64()))
 case 4:
 return .precise(Double.bridgeJSLiftParameter(_swift_js_pop_param_float64()))
 case 5:
 return .info
 default:
 fatalError("Unknown APIResult case ID: \(caseId)")
 }
 }
}

Pros

• Much faster in practice (~90% faster than memory ABI for enum payloads).
• Still flexible for variable-size payloads.

Cons

• Requires careful push/pop ordering.
• It's very stateful, so the state must be reset between calls.

Option 3: Flattened ABI

Use a fixed slot layout (e.g., tag: i32, i1: i32, i2: i32, f: f64) and pass values directly.

function lower(value) {
 switch (value.tag) {
 case APIResult.Tag.Flag:
 return [1, 0, 0]; // (i1=1, i2=0, f=0)
 case APIResult.Tag.Precise:
 return [0, 0, value.param0]; // (i1=0, i2=0, f=f64)
 // ...
 }
}
instance.exports.bjs_EnumRoundtrip_take(selfPtr, value.tag, i1, i2, f);

@_cdecl("bjs_EnumRoundtrip_take")
func bjs_EnumRoundtrip_take(_ selfPtr: UnsafeMutableRawPointer,
 _ tag: Int32, _ i1: Int32, _ i2: Int32, _ f: Double) {
 switch tag {
 case 1: take(.failure(Int(i1)))
 case 2: take(.flag(i1 != 0))
 case 3: take(.rate(Float(f)))
 case 4: take(.precise(f))
 case 5: take(.info)
 }
}

Pros

• Minimal boundary overhead.

Cons

• Only works when payload space is finite at compile-time. (can't be used for indirectly recursive types)

Benchmark

I conducted a benchmark with a hacky manual patches. (you can see benchmark code on my branch. I manually modified the generated bridge-js.js other than the change tracked by git flat-abi.js stack-abi.js)

My proposal

Given this, Option 2 looks like a reasonable baseline candidate, and Option 3 could be layered on as an optimization for fixed storage size types in the future. Does this direction make sense to you, or do you see other trade-offs we should weigh?

@kateinoigakukun here is the comparison for before / after changes 👌🏻

EnumRoundtrip Comparison

ComplexResultRoundtrip Comparison

Here is the branch with working benchmarks for both enums and previous approach: feat/bridgejs-benchmark-buffer