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 thanks for in-depth analysis 🙇🏼‍♂️
Given your benchmark results, I think we should go with option 2, it seems like an overall approach we could reuse later when adding new types and that one seems more scalable for constructs with multiple values like case comprehensive(Bool, Bool, Int, Int, Double, Double, String, String, String) comparing to option 3.

I'll start migration to option 2 and update PR when ready 🙏🏻

@kateinoigakukun PR updated for stack based solutions, couple of notes:

• 2 set of stacks for ret / par to avoid conflicts on roundtrips
• no particular place to clear the stacks, as we generate equal numbers of push / pop, no need for that
• normal order on Swift side, inverse order on JS side
• kept swift_js_push_string separate from swift_js_return_string (comparing to initial PR) to not mix those up
• bridgeJSLiftParameter reuses existing bridgeJSLiftParameter mechanisms, while bridgeJSLowerReturn needs to use _swift_js_push<type> as default bridgeJSLowerReturn methods would not use stacks
• it's fine to pass string to bridgeJSLiftParameter as 2 int32, but we need withUTF8 for lowering, hence strings stack

I will add comprehensive benchmark on separate branch to confirm performance based on parts of your branch, so will either add this to this PR or issue another PR against this branch 🙏🏻

@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

@kateinoigakukun I'll give it a go after the weekend to use IntrinsicJSFragment for helper functions fragments and align approach, so will issue a new PR with that, thanks for suggestion! 👍