ffi M1.2 A.1 follow-up: struct args/returns in Obj-C type encoding

`appendObjcEncoding` previously bailed on `.@"struct"`, which blocked
sx-defined `#objc_class` methods from declaring CGPoint / CGRect /
NSRange-shape signatures — the `class_addMethod` registration path
would emit a "type kind not yet supported by Obj-C encoding"
diagnostic. The helper now emits Apple's `{Name=field0field1...}`
form recursively, with a small `ObjcEncodingStack` (cap 16) that
breaks transitive struct→struct cycles by emitting the abbreviated
`{Name}` form instead of recursing forever.

`{Point=dd}`, `{_NSRange=QQ}`, `{CGRect={CGPoint=dd}{CGSize=dd}}`
all flow through the existing `objc_msg_send` + `class_addMethod`
path with no further plumbing.

Tests:
- `lower.test.zig` gains four cases: optional unwrap (single + nested),
  flat struct (CGPoint, NSRange shape), nested struct (CGRect with
  CGPoint+CGSize), bringing the helper's test coverage from
  primitives + pointers to the full encoding table.
- `examples/ffi-objc-defined-class-02-struct-encoding.sx` exercises
  a sx-defined `SxMover` class with `goto(p: Point)` setter and
  `here() -> Point` getter end-to-end on macOS; the IR snapshot
  confirms `v@:{Point=dd}` and `{Point=dd}@:` land in
  `OBJC_METH_VAR_TYPE_` constants wired to `class_addMethod`.

Checkpoint cleanup: the "Next step (M1.2 A.1 — type-encoding
derivation table)" header in CHECKPOINT-FFI.md was stale (A.1
shipped in 6cc016c; A.0–A.7 all done; commit list now linked).
The encoding table stays as reference material.

224/224 example tests pass; zig build test green.

src/ir/lower.test.zig

@@ -425,3 +425,127 @@ test "lower: objcTypeEncodingFromSignature emits @ for Obj-C class pointers" {
     defer alloc.free(e2);
     try std.testing.expectEqualStrings("@@:@", e2);
 }
+
+test "lower: objcTypeEncodingFromSignature unwraps optional to wire type" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // Foreign `*NSString` so the encoder recognises it as `@`.
+    const ns_name = module.types.internString("NSString");
+    const ns_struct = module.types.intern(.{ .@"struct" = .{ .name = ns_name, .fields = &.{} } });
+    const ns_ptr = module.types.ptrTo(ns_struct);
+    var ns_fcd = ast.ForeignClassDecl{
+        .name = "NSString",
+        .foreign_path = "NSString",
+        .runtime = .objc_class,
+        .members = &.{},
+        .is_foreign = true,
+        .is_main = false,
+    };
+    try lowering.foreign_class_map.put("NSString", &ns_fcd);
+
+    // `?s64 -> ?*NSString` collapses to `q -> @` at the Obj-C boundary.
+    const opt_s64 = module.types.optionalOf(.s64);
+    const opt_ns = module.types.optionalOf(ns_ptr);
+    const e1 = try lowering.objcTypeEncodingFromSignature(opt_ns, &.{opt_s64}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("@@:q", e1);
+
+    // Nested optional unwrap (`??f64`) — same as `f64` at the wire.
+    const opt_f64 = module.types.optionalOf(.f64);
+    const opt_opt_f64 = module.types.optionalOf(opt_f64);
+    const e2 = try lowering.objcTypeEncodingFromSignature(.void, &.{opt_opt_f64}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("v@:d", e2);
+}
+
+test "lower: objcTypeEncodingFromSignature emits structs as {Name=fields...}" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // CGPoint :: struct { x: f64; y: f64 } → {CGPoint=dd}
+    const cgpoint_name = module.types.internString("CGPoint");
+    const cgpoint_x_name = module.types.internString("x");
+    const cgpoint_y_name = module.types.internString("y");
+    const cgpoint_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = cgpoint_x_name, .ty = .f64 },
+        .{ .name = cgpoint_y_name, .ty = .f64 },
+    };
+    const cgpoint = module.types.intern(.{ .@"struct" = .{ .name = cgpoint_name, .fields = &cgpoint_fields } });
+
+    // `-(void)setOrigin:(CGPoint)p` → `v@:{CGPoint=dd}`
+    const e1 = try lowering.objcTypeEncodingFromSignature(.void, &.{cgpoint}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("v@:{CGPoint=dd}", e1);
+
+    // `-(CGPoint)origin` → `{CGPoint=dd}@:`
+    const e2 = try lowering.objcTypeEncodingFromSignature(cgpoint, &.{}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("{CGPoint=dd}@:", e2);
+
+    // NSRange ({u64 location; u64 length}) → {_NSRange=QQ} (Apple uses
+    // the underscore-prefixed internal name in practice, but we faithfully
+    // emit whatever the struct is registered as).
+    const nsrange_name = module.types.internString("_NSRange");
+    const loc_name = module.types.internString("location");
+    const len_name = module.types.internString("length");
+    const nsrange_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = loc_name, .ty = .u64 },
+        .{ .name = len_name, .ty = .u64 },
+    };
+    const nsrange = module.types.intern(.{ .@"struct" = .{ .name = nsrange_name, .fields = &nsrange_fields } });
+    const e3 = try lowering.objcTypeEncodingFromSignature(nsrange, &.{ nsrange, .s64 }, null);
+    defer alloc.free(e3);
+    try std.testing.expectEqualStrings("{_NSRange=QQ}@:{_NSRange=QQ}q", e3);
+}
+
+test "lower: objcTypeEncodingFromSignature emits nested structs (CGRect)" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // CGPoint and CGSize, both {f64, f64}.
+    const cgpoint_name = module.types.internString("CGPoint");
+    const cgsize_name = module.types.internString("CGSize");
+    const x_name = module.types.internString("x");
+    const y_name = module.types.internString("y");
+    const w_name = module.types.internString("width");
+    const h_name = module.types.internString("height");
+
+    const cgpoint_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = x_name, .ty = .f64 },
+        .{ .name = y_name, .ty = .f64 },
+    };
+    const cgsize_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = w_name, .ty = .f64 },
+        .{ .name = h_name, .ty = .f64 },
+    };
+    const cgpoint = module.types.intern(.{ .@"struct" = .{ .name = cgpoint_name, .fields = &cgpoint_fields } });
+    const cgsize = module.types.intern(.{ .@"struct" = .{ .name = cgsize_name, .fields = &cgsize_fields } });
+
+    // CGRect :: struct { origin: CGPoint; size: CGSize } →
+    // {CGRect={CGPoint=dd}{CGSize=dd}}
+    const cgrect_name = module.types.internString("CGRect");
+    const origin_name = module.types.internString("origin");
+    const size_name = module.types.internString("size");
+    const cgrect_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = origin_name, .ty = cgpoint },
+        .{ .name = size_name, .ty = cgsize },
+    };
+    const cgrect = module.types.intern(.{ .@"struct" = .{ .name = cgrect_name, .fields = &cgrect_fields } });
+
+    // `-(CGRect)frame` → `{CGRect={CGPoint=dd}{CGSize=dd}}@:`
+    const e1 = try lowering.objcTypeEncodingFromSignature(cgrect, &.{}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("{CGRect={CGPoint=dd}{CGSize=dd}}@:", e1);
+
+    // `-(void)setFrame:(CGRect)f` round-trip.
+    const e2 = try lowering.objcTypeEncodingFromSignature(.void, &.{cgrect}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("v@:{CGRect={CGPoint=dd}{CGSize=dd}}", e2);
+}

src/ir/lower.zig

@@ -5011,9 +5011,12 @@ pub const Lowering = struct {
     ///
     /// Foreign-class pointers (`*UIView` etc.) encode as `@` (object
     /// pointer). Other pointers fall to `^v` — the encoding is metadata,
-    /// not ABI, so being conservative here is safe. Struct returns and
-    /// other complex shapes BAIL loudly via diagnostics rather than
-    /// silently mis-encoding (per CLAUDE.md rejected-patterns rule).
+    /// not ABI, so being conservative here is safe. Pass-by-value
+    /// structs encode as `{Name=field0field1...}`; nested structs
+    /// recurse with cycle-break via `ObjcEncodingStack`. Tagged-union /
+    /// array / vector / function shapes BAIL loudly via diagnostics
+    /// rather than silently mis-encoding (per CLAUDE.md rejected-
+    /// patterns rule).
     ///
     /// Returns an allocator-owned slice; caller frees via `self.alloc`.
     fn objcTypeEncodingFromSignature(
@@ -5025,17 +5028,54 @@ pub const Lowering = struct {
         var out = std.ArrayList(u8).empty;
         errdefer out.deinit(self.alloc);
 
-        try self.appendObjcEncoding(&out, return_ty, span);
+        var stack: ObjcEncodingStack = .{};
+        try self.appendObjcEncoding(&out, return_ty, span, &stack);
         try out.append(self.alloc, '@'); // self
         try out.append(self.alloc, ':'); // _cmd
         for (param_tys) |pty| {
-            try self.appendObjcEncoding(&out, pty, span);
+            try self.appendObjcEncoding(&out, pty, span, &stack);
         }
 
         return try out.toOwnedSlice(self.alloc);
     }
 
-    fn appendObjcEncoding(self: *Lowering, out: *std.ArrayList(u8), ty: TypeId, span: ?ast.Span) !void {
+    /// Tracks struct TypeIds currently being emitted so a struct field of
+    /// `*Self` (or a transitive pointee that cycles back) emits the
+    /// abbreviated `{Name}` form instead of recursing forever. Bounded to
+    /// `cap` — well above any realistic Obj-C struct nesting depth.
+    const ObjcEncodingStack = struct {
+        const cap = 16;
+        items: [cap]TypeId = undefined,
+        len: u8 = 0,
+
+        fn push(self: *ObjcEncodingStack, tid: TypeId) bool {
+            if (self.len >= cap) return false;
+            self.items[self.len] = tid;
+            self.len += 1;
+            return true;
+        }
+
+        fn pop(self: *ObjcEncodingStack) void {
+            std.debug.assert(self.len > 0);
+            self.len -= 1;
+        }
+
+        fn contains(self: *const ObjcEncodingStack, tid: TypeId) bool {
+            var i: usize = 0;
+            while (i < self.len) : (i += 1) {
+                if (self.items[i] == tid) return true;
+            }
+            return false;
+        }
+    };
+
+    fn appendObjcEncoding(
+        self: *Lowering,
+        out: *std.ArrayList(u8),
+        ty: TypeId,
+        span: ?ast.Span,
+        stack: *ObjcEncodingStack,
+    ) !void {
         const info = self.module.types.get(ty);
         switch (info) {
             .void => try out.append(self.alloc, 'v'),
@@ -5097,7 +5137,33 @@ pub const Lowering = struct {
                 // wire-level encoding is the same as T. Unwrap and
                 // recurse. (Same goes for `?*UIView` etc. — the
                 // underlying pointer kind drives the encoding char.)
-                return self.appendObjcEncoding(out, o.child, span);
+                return self.appendObjcEncoding(out, o.child, span, stack);
+            },
+            .@"struct" => |s| {
+                // Pass-by-value struct argument or return: Apple's
+                // encoding is `{Name=field0field1...}`. A struct
+                // already on the encoding stack (i.e. transitively
+                // referenced through a struct field — extremely rare
+                // since sx structs don't recurse by value) gets the
+                // abbreviated `{Name}` form. Recursion through
+                // POINTERS is fine because `.pointer` collapses to
+                // `^v` regardless of pointee shape.
+                const name = self.module.types.getString(s.name);
+                try out.append(self.alloc, '{');
+                try out.appendSlice(self.alloc, name);
+                if (stack.contains(ty)) {
+                    try out.append(self.alloc, '}');
+                    return;
+                }
+                if (!stack.push(ty)) {
+                    return self.bailObjcEncoding(span, "Obj-C struct encoding nested deeper than supported", ObjcEncodingStack.cap);
+                }
+                defer stack.pop();
+                try out.append(self.alloc, '=');
+                for (s.fields) |f| {
+                    try self.appendObjcEncoding(out, f.ty, span, stack);
+                }
+                try out.append(self.alloc, '}');
             },
             else => return self.bailObjcEncoding(span, "type kind not yet supported by Obj-C encoding", @intFromEnum(std.meta.activeTag(info))),
         }