fix: bridge indexed collection subclass aliases

Author: DjDeveloperr

HANDOFF.md

@@ -110,6 +110,49 @@ During this thread `agent-device` was version `0.18.0`; the npm package is
 
 ## Current Verified State
 
+Update from 2026-06-29 18:19 EDT:
+
+- Simulator-only rule remains active. Do not use physical iPhone/iPad devices.
+- Draft PR #46 branch is still
+  `codex/rn-module-fabric-turbomodule-worklets` and remains the RN module /
+  Fabric / TurboModule / worklets branch split from `refactor`.
+- GitHub Actions run `28404253218` on `72f1af05` kept setup, dependency
+  install, FFI boundary check, V8 download, libffi build, metadata generation,
+  NativeScript build, CLI build, and macOS tests green.
+- The improved iOS diagnostics identified the current simulator hang:
+  `ApiTests.js NSMutableArrayMethods`.
+- `ApiTests.js Appearance` passed on iOS in that run. No `44abcd` output was
+  printed for `NSMutableArrayMethods`, so the stall is before the native
+  callback's first `TNSLog`, likely during JS-backed `NSMutableArray`
+  mutation/subscript dispatch.
+- Current runtime fix:
+  - Native class extension install now synthesizes indexed collection aliases
+    for JS-backed Objective-C subclasses: `objectAtIndex` also supplies
+    `objectAtIndexedSubscript`, and `replaceObjectAtIndexWithObject` also
+    supplies `setObjectAtIndexedSubscript`.
+  - The write alias corrects Objective-C selector argument order by calling
+    `replaceObjectAtIndexWithObject(index, anObject)` from
+    `setObjectAtIndexedSubscript(anObject, index)`.
+  - The alias preparation is applied to both `.extend(...)` and TypeScript
+    `NativeClass` materialization.
+  - Source coverage was added in
+    `packages/react-native/test/runtime-indexed-collection-alias.test.js`.
+- Local verification:
+  - `node packages/react-native/test/runtime-indexed-collection-alias.test.js`
+    passed.
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `git diff --check` passed.
+  - `npm run check:ffi-boundaries` passed.
+  - `npm run build:macos-cli` passed.
+  - A focused local macOS `NSMutableArrayMethods` run was blocked before launch
+    by the known local metadata-generator x86_64/libclang mismatch, so CI is
+    still the authoritative iOS simulator signal.
+- Not done:
+  - Commit/push the indexed collection alias fix and watch fresh PR CI for the
+    iOS simulator `NSMutableArrayMethods` result.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 Update from 2026-06-29 17:34 EDT:
 
 - Simulator-only rule remains active. Do not use physical iPhone/iPad devices.

NativeScript/ffi/shared/bridge/Install.mm

@@ -237,6 +237,50 @@ function findPrototypeDescriptor(className, property) {
     return undefined;
   }
 
+  function nativeExtensionMethodsWithIndexedCollectionAliases(methods) {
+    if (methods == null || typeof methods !== 'object') {
+      return methods;
+    }
+
+    var needsObjectAtIndexedSubscript =
+      Object.prototype.hasOwnProperty.call(methods, 'objectAtIndex') &&
+      !Object.prototype.hasOwnProperty.call(methods, 'objectAtIndexedSubscript');
+    var needsSetObjectAtIndexedSubscript =
+      Object.prototype.hasOwnProperty.call(methods, 'replaceObjectAtIndexWithObject') &&
+      !Object.prototype.hasOwnProperty.call(methods, 'setObjectAtIndexedSubscript');
+
+    if (!needsObjectAtIndexedSubscript && !needsSetObjectAtIndexedSubscript) {
+      return methods;
+    }
+
+    var prepared = Object.create(Object.getPrototypeOf(methods));
+    Object.defineProperties(prepared, Object.getOwnPropertyDescriptors(methods));
+
+    if (needsObjectAtIndexedSubscript) {
+      Object.defineProperty(prepared, 'objectAtIndexedSubscript', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: function(index) {
+          return this.objectAtIndex(index);
+        }
+      });
+    }
+
+    if (needsSetObjectAtIndexedSubscript) {
+      Object.defineProperty(prepared, 'setObjectAtIndexedSubscript', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: function(anObject, index) {
+          return this.replaceObjectAtIndexWithObject(index, anObject);
+        }
+      });
+    }
+
+    return prepared;
+  }
+
   Object.defineProperty(globalThis, '__nativeScriptCreateNativeApiIterator', {
     configurable: false,
     enumerable: false,
@@ -708,6 +752,7 @@ function rememberInstanceClass(instance) {
           if (methods == null || typeof methods !== 'object') {
             throw new Error('extend() first parameter must be an object');
           }
+          var extensionMethods = nativeExtensionMethodsWithIndexedCollectionAliases(methods);
           var extendOptions = options || {};
           if (typeof Symbol === 'function' &&
               Object.prototype.hasOwnProperty.call(methods, Symbol.iterator)) {
@@ -719,18 +764,18 @@ function rememberInstanceClass(instance) {
               extendOptions.__hasIterator = true;
             }
           }
-          var extendedNativeClass = api.__extendClass(nativeClass, methods, extendOptions);
+          var extendedNativeClass = api.__extendClass(nativeClass, extensionMethods, extendOptions);
           var extended = wrapNativeClass(extendedNativeClass);
           try {
             Object.setPrototypeOf(extended, wrapper || constructable);
           } catch (_) {
           }
           var extendedPrototype = Object.create(constructable.prototype || null);
           try {
-            Object.defineProperties(extendedPrototype, Object.getOwnPropertyDescriptors(methods));
+            Object.defineProperties(extendedPrototype, Object.getOwnPropertyDescriptors(extensionMethods));
           } catch (_) {
-            Object.keys(methods).forEach(function(key) {
-              extendedPrototype[key] = methods[key];
+            Object.keys(extensionMethods).forEach(function(key) {
+              extendedPrototype[key] = extensionMethods[key];
             });
           }
           try {
@@ -1361,7 +1406,9 @@ function materializeTypeScriptNativeClass(constructor) {
 	      }
 
 	      var nativeBase = nativeClassLikeHandle(baseWrapper);
-	      var nativeClass = api.__extendClass(nativeBase, constructor.prototype || {}, options);
+	      var extensionMethods =
+	        nativeExtensionMethodsWithIndexedCollectionAliases(constructor.prototype || {});
+	      var nativeClass = api.__extendClass(nativeBase, extensionMethods, options);
 	      var wrapper = wrapNativeClass(nativeClass);
 	      state.wrapper = wrapper;
 
@@ -1370,7 +1417,7 @@ function materializeTypeScriptNativeClass(constructor) {
 	      } catch (_) {
 	      }
 	      try {
-	        api.__rememberClassWrapper(nativeClass, constructor, constructor.prototype || {});
+	        api.__rememberClassWrapper(nativeClass, constructor, extensionMethods);
 	      } catch (_) {
 	      }
 	      return wrapper;

PROGRESS.md

@@ -17,6 +17,45 @@ TypeScript/UI worklets.
 
 ## Latest Update - 2026-06-29
 
+### 2026-06-29 18:19 EDT - indexed collection subclass aliases
+
+- Goal:
+  - Keep PR #46 on the RN module / generic runtime primitive branch and stay
+    simulator-only. No physical devices were used.
+- CI finding:
+  - GitHub Actions run `28404253218` on `72f1af05` kept setup, dependency
+    install, FFI boundary check, V8 download, libffi build, metadata
+    generation, NativeScript build, CLI build, and macOS tests green.
+  - The improved iOS diagnostics showed `ApiTests.js Appearance` passed, then
+    the iOS simulator hung in `ApiTests.js NSMutableArrayMethods`.
+  - No `44abcd` output was printed, so the stall happens before the native
+    callback's first `TNSLog`, likely during JS-backed `NSMutableArray`
+    mutation/subscript dispatch.
+- Changes:
+  - Native class extension install now synthesizes `objectAtIndexedSubscript`
+    from `objectAtIndex` and `setObjectAtIndexedSubscript` from
+    `replaceObjectAtIndexWithObject`.
+  - The write alias corrects Objective-C selector argument order by calling
+    `replaceObjectAtIndexWithObject(index, anObject)` from
+    `setObjectAtIndexedSubscript(anObject, index)`.
+  - The alias preparation now applies to both `.extend(...)` and TypeScript
+    `NativeClass` materialization.
+  - Added a source guard for the indexed collection alias behavior.
+- Verification:
+  - `node packages/react-native/test/runtime-indexed-collection-alias.test.js`
+    passed.
+  - Runtime RN JS tests passed:
+    `for f in packages/react-native/test/*.test.js; do node "$f" || exit 1; done`.
+  - `git diff --check` passed.
+  - `npm run check:ffi-boundaries` passed.
+  - `npm run build:macos-cli` passed.
+  - Focused local macOS `NSMutableArrayMethods` testing was blocked before
+    launch by the known metadata-generator x86_64/libclang mismatch.
+- Still next:
+  - Commit/push this indexed collection alias fix and watch fresh PR CI for
+    the iOS simulator `NSMutableArrayMethods` result.
+  - If CI turns green, resume the dedicated simulator-only RNS parity sweep.
+
 ### 2026-06-29 17:34 EDT - iOS simulator hang diagnostics
 
 - Goal:

packages/react-native/test/runtime-indexed-collection-alias.test.js

@@ -0,0 +1,42 @@
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "../../..");
+
+for (const relativePath of [
+  "NativeScript/ffi/shared/bridge/Install.mm",
+  "packages/react-native/native-api/ffi/shared/bridge/Install.mm",
+]) {
+  const source = fs.readFileSync(path.join(repoRoot, relativePath), "utf8");
+
+  assert(
+    source.includes("function nativeExtensionMethodsWithIndexedCollectionAliases(methods)"),
+    `${relativePath}: native class extension should prepare indexed collection method aliases`,
+  );
+  assert(
+    source.includes("needsObjectAtIndexedSubscript") &&
+      source.includes("needsSetObjectAtIndexedSubscript"),
+    `${relativePath}: indexed collection aliases should cover read and write native subscript selectors`,
+  );
+  assert(
+    source.includes("return this.objectAtIndex(index);") &&
+      source.includes("return this.replaceObjectAtIndexWithObject(index, anObject);"),
+    `${relativePath}: synthesized subscript aliases should delegate to the JS primitive methods with native argument order corrected`,
+  );
+  assert(
+    source.includes("var extensionMethods = nativeExtensionMethodsWithIndexedCollectionAliases(methods);") &&
+      source.includes("api.__extendClass(nativeClass, extensionMethods, extendOptions)") &&
+      source.includes("Object.getOwnPropertyDescriptors(extensionMethods)") &&
+      source.includes("Object.keys(extensionMethods)"),
+    `${relativePath}: NativeClass.extend should register and expose the prepared indexed collection method set`,
+  );
+  assert(
+    source.includes("nativeExtensionMethodsWithIndexedCollectionAliases(constructor.prototype || {})") &&
+      source.includes("api.__extendClass(nativeBase, extensionMethods, options)") &&
+      source.includes("api.__rememberClassWrapper(nativeClass, constructor, extensionMethods)"),
+    `${relativePath}: TypeScript native class materialization should use the same prepared method set`,
+  );
+}
+
+console.log("runtime indexed collection alias tests passed");