fix: limit appearance proxy accessors to UIKit

Author: DjDeveloperr

HANDOFF.md

@@ -111,6 +111,39 @@ During this thread `agent-device` was version `0.18.0`; the npm package is
 
 ## Current Verified State
 
+Update from 2026-06-29 13:47 EDT:
+
+- Simulator-only rule remains active. Do not use physical iPhone/iPad devices.
+- GitHub Actions run `28390374047` on `ac94954e` compiled the edited V8 bridge
+  in CI, then failed macOS `ApiTests.js Appearance` before iOS ran.
+- The failure was AppKit-only:
+  `NSAppearance.appearanceNamed(NSAppearanceNameAqua).name` read back as
+  `undefined`, so the safe UIAppearance accessor change had shadowed a real
+  AppKit object's native `name` property.
+- Current runtime fix:
+  - Static `appearance*` result tagging now requires
+    `appearanceProxyCustomizableClassFromExactDescription(native)` to identify
+    an exact UIKit customizable proxy target.
+  - If the exact UIKit proxy description is not present, tagging/accessor
+    installation is skipped. This avoids applying cache-backed UIAppearance
+    accessors to AppKit `NSAppearance` instances.
+  - Source coverage now blocks the receiver-class fallback that caused the
+    shadowing regression.
+- Local verification after this correction:
+  - `node packages/react-native/test/runtime-objc-property-setter.test.js`
+    passed.
+  - 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.
+  - Focused local macOS `ApiTests`/`Appearance` launch attempt was blocked
+    before app launch by the known local metadata-generator x86_64 link
+    mismatch against arm64-only Xcode `libclang.dylib`.
+- Not done:
+  - Commit/push the UIKit-proxy-only tagging correction and watch fresh PR CI.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 Update from 2026-06-29 13:21 EDT:
 
 - Simulator-only rule remains active. Do not use physical iPhone/iPad devices.

NativeScript/ffi/shared/bridge/HostObjects.mm

@@ -1908,7 +1908,7 @@ Class tagStaticAppearanceNativeResult(
   Class customizableClass =
       appearanceProxyCustomizableClassFromExactDescription(native);
   if (customizableClass == Nil) {
-    customizableClass = appearanceClass;
+    return Nil;
   }
   const char* className = class_getName(customizableClass);
   if (className == nullptr || className[0] == '\0') {

PROGRESS.md

@@ -17,6 +17,45 @@ TypeScript/UI worklets.
 
 ## Latest Update - 2026-06-29
 
+### 2026-06-29 13:47 EDT - limit UIAppearance tagging to UIKit proxies
+
+- Goal:
+  - Keep PR #46 scoped to generic runtime primitives for the RN module branch
+    and stay simulator-only. No physical devices are part of this fix.
+- CI finding:
+  - GitHub Actions run `28390374047` on `ac94954e` compiled the edited V8
+    bridge in CI, then failed macOS `ApiTests.js Appearance` before iOS ran.
+  - The failure was AppKit-only: `NSAppearance.appearanceNamed(...)` returned
+    an object, but `appearance.name` read back as `undefined` instead of
+    containing `Aqua`.
+  - Root cause: static selector tagging matched every class selector starting
+    with `appearance`, then fell back to the receiver class when the native
+    object was not an exact UIKit `UIAppearance` proxy. That mislabeled the
+    real AppKit `NSAppearance` instance and installed cache-backed own
+    accessors that shadowed native properties such as `name`.
+- Changes:
+  - `tagStaticAppearanceNativeResult` now requires
+    `appearanceProxyCustomizableClassFromExactDescription(native)` to identify
+    an exact UIKit customizable proxy target. If it cannot, tagging/accessor
+    installation is skipped.
+  - Source coverage now blocks the receiver-class fallback so AppKit
+    appearance objects keep their native property access.
+- Verification:
+  - `node packages/react-native/test/runtime-objc-property-setter.test.js`
+    passed.
+  - 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 and compiled/linked the edited V8 bridge.
+  - Focused local macOS `ApiTests`/`Appearance` launch attempt was blocked
+    before app launch by the known local metadata-generator x86_64 link
+    mismatch against arm64-only Xcode `libclang.dylib`.
+- Still next:
+  - Commit/push the correction and watch fresh PR CI for macOS recovery plus
+    the authoritative iOS simulator result.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 ### 2026-06-29 13:21 EDT - safe UIAppearance proxy accessors
 
 - Goal:

packages/react-native/test/runtime-objc-property-setter.test.js

@@ -46,6 +46,12 @@ assert(
     runtimeHostObjects.includes("return customizableClass;"),
   "runtime UIAppearance result tagging should return the customizable target class",
 );
+assert(
+  runtimeHostObjects.includes("appearanceProxyCustomizableClassFromExactDescription(native)") &&
+    runtimeHostObjects.includes("if (customizableClass == Nil) {\n    return Nil;\n  }") &&
+    !runtimeHostObjects.includes("customizableClass = appearanceClass;"),
+  "runtime UIAppearance result tagging should require an exact UIKit proxy target and avoid shadowing AppKit appearance objects",
+);
 assert(
   runtimeHostObjects.includes("installAppearanceProxyPropertyAccessors") &&
     runtimeHostObjects.includes("makeAppearanceProxyPropertySetter") &&