fix: dispatch UIAppearance proxy setters via target metadata

Author: DjDeveloperr

HANDOFF.md

@@ -111,6 +111,41 @@ During this thread `agent-device` was version `0.18.0`; the npm package is
 
 ## Current Verified State
 
+Update from 2026-06-29 11:07 EDT:
+
+- Simulator-only rule remains active. Do not use physical iPhone/iPad devices.
+- GitHub Actions run `28379145481` on `c26766ef` kept setup, dependency
+  install, FFI boundary, V8 download, libffi build, metadata generation,
+  NativeScript build, CLI build, and macOS tests green, but still failed iOS
+  only in `ApiTests.js Appearance`: `UILabel.appearance().textColor` read
+  back `undefined`.
+- CI disproved the selector-group accessor cache as the final missing path.
+  The live iOS/JSC assignment is consistent with the host-object set trap
+  seeing a UIKit appearance proxy whose runtime Objective-C class is not the
+  customizable target class (`UILabel`), so exact proxy-class metadata lookup
+  misses and the write falls back to an expando on that proxy instance.
+- Runtime fix in progress:
+  - `NativeApiObjectHostObject::set` now resolves tagged/described
+    `UIAppearance` proxies back to their customizable target class metadata
+    before the runtime-discovered setter fallback.
+  - The target-class metadata setter is invoked on the appearance proxy and the
+    existing target-class-scoped appearance cache is populated only after the
+    native call succeeds.
+  - `callObjCSelector` now narrowly allows metadata-backed instance property
+    selectors on tagged/described appearance proxies to pass the availability
+    check even when UIKit handles them through Objective-C forwarding instead
+    of `respondsToSelector:`.
+- Local verification after this patch:
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `npm run check:ffi-boundaries` passed.
+  - `git diff --check` passed.
+  - `npm run build:macos-cli` passed.
+- Not done:
+  - Commit/push the host-object UIAppearance metadata fix and watch fresh PR
+    CI.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 Update from 2026-06-29 10:22 EDT:
 
 - Simulator-only rule remains active. Do not use physical iPhone/iPad devices.

NativeScript/ffi/shared/bridge/HostObjects.mm

@@ -1815,6 +1815,31 @@ throw JSError(
       }
     }
 
+    if (Class appearanceClass =
+            taggedAppearanceProxyClass(runtime, bridge_, object_)) {
+      if (const NativeApiSymbol* symbol =
+              bridge_->findClassForRuntimeClass(appearanceClass)) {
+        const auto& members = bridge_->membersForClass(*symbol);
+        if (const NativeApiMember* propertyMember =
+                selectWritablePropertyMember(members, property, false)) {
+          if (propertyMember->readonly ||
+              propertyMember->setterSelectorName.empty()) {
+            throw JSError(
+                runtime, "Attempted to assign to readonly property.");
+          }
+          NativeApiMember setterMember = *propertyMember;
+          setterMember.selectorName = propertyMember->setterSelectorName;
+          setterMember.signatureOffset = propertyMember->setterSignatureOffset;
+          Value args[] = {Value(runtime, value)};
+          callObjCSelector(runtime, bridge_, object_, false,
+                           setterMember.selectorName, &setterMember, args, 1);
+          cacheAppearanceProxyPropertyValue(runtime, bridge_, object_,
+                                            property, value);
+          NATIVE_API_SET_RETURN(true);
+        }
+      }
+    }
+
     if (auto setterSelectorName =
             runtimeWritablePropertySetter(object_, property)) {
       Value args[] = {Value(runtime, value)};

NativeScript/ffi/shared/bridge/Invocation.mm

@@ -1673,7 +1673,17 @@ throw JSError(runtime,
   Class lookupClass = dispatchSuperClass != Nil ? dispatchSuperClass : receiverClass;
   Method method = receiverIsClass ? class_getClassMethod(lookupClass, selector)
                                   : class_getInstanceMethod(lookupClass, selector);
+  bool allowForwardedAppearancePropertySelector = false;
+  if (method == nullptr && !receiverIsClass && member != nullptr &&
+      member->property && bridge != nullptr &&
+      taggedAppearanceProxyClass(runtime, bridge, receiver) != Nil) {
+    allowForwardedAppearancePropertySelector =
+        (count == 0 && selectorName == member->selectorName) ||
+        (count == 1 && !member->setterSelectorName.empty() &&
+         selectorName == member->setterSelectorName);
+  }
   if (method == nullptr &&
+      !allowForwardedAppearancePropertySelector &&
       (dispatchSuperClass != Nil || ![receiver respondsToSelector:selector])) {
     throw JSError(runtime,
                                  "Objective-C selector is not available: " +

PROGRESS.md

@@ -17,6 +17,43 @@ TypeScript/UI worklets.
 
 ## Latest Update - 2026-06-29
 
+### 2026-06-29 11:07 EDT - host-object UIAppearance target metadata
+
+- Goal:
+  - Keep PR #46 on the generic runtime primitive path and unblock the final
+    simulator-only RN Screens parity sweep; no physical devices were used.
+- CI finding:
+  - GitHub Actions run `28379145481` on `c26766ef` kept setup, dependencies,
+    FFI boundary check, V8 download, libffi build, metadata generation,
+    NativeScript build, CLI build, and macOS tests green, but still failed iOS
+    `ApiTests.js Appearance` only: `UILabel.appearance().textColor` read back
+    as `undefined`.
+  - That disproved the selector-group accessor cache as the remaining path.
+    The failing write/readback is consistent with the host-object set trap
+    receiving the UIKit appearance proxy instance directly. The proxy runtime
+    class does not carry `UILabel` metadata, so exact-class metadata lookup
+    misses and the old path could store only a per-proxy expando.
+- Changes:
+  - Host-object property writes on tagged/described `UIAppearance` proxies now
+    resolve the customizable target class metadata before falling back to
+    runtime-discovered setters.
+  - The target-class metadata setter is invoked on the appearance proxy and the
+    existing class-scoped appearance cache is populated only after that native
+    call succeeds.
+  - `callObjCSelector` now narrowly permits metadata-backed instance property
+    selectors on appearance proxies to reach UIKit's Objective-C forwarding
+    path when the proxy does not advertise the selector with
+    `respondsToSelector:`.
+- Verification:
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `npm run check:ffi-boundaries` passed.
+  - `git diff --check` passed.
+  - `npm run build:macos-cli` passed.
+- Still next:
+  - Commit/push the host-object metadata fix, watch fresh PR CI, then return
+    to the dedicated simulator-only RNS parity sweep if CI is green.
+
 ### 2026-06-29 10:22 EDT - cached selector-group UIAppearance accessors
 
 - Goal: