Add MapBufferList entry type to MapBuffer (#57360)

Summary:
Pull Request resolved: #57360

Introduces a dedicated `MapBufferList` `DataType` for an ordered array of nested MapBuffers, instead of overloading the `Map` type for lists. This makes a list of MapBuffers self-describing and distinguishable from a single nested `Map` (they were byte-distinct in payload but previously shared the `Map` type tag). Updates the C++ builder (`putMapBufferList`), the Kotlin `MapBuffer` interface, `ReadableMapBuffer`, and `WritableMapBuffer`, and adds cross-language JNI round-trip coverage in the serialization instrumentation test.

Changelog:
[Android][Added] - Add a dedicated `MapBufferList` type to `MapBuffer` for ordered lists of nested `MapBuffer`s

Reviewed By: zeyap

Differential Revision: D109848477

Author: javache

packages/react-native/ReactAndroid/api/ReactAndroid.api

@@ -1687,6 +1687,7 @@ public final class com/facebook/react/common/mapbuffer/MapBuffer$DataType : java
 	public static final field INT_BUFFER Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
 	public static final field LONG Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
 	public static final field MAP Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
+	public static final field MAP_BUFFER_LIST Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
 	public static final field STRING Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
 	public static fun getEntries ()Lkotlin/enums/EnumEntries;
 	public static fun valueOf (Ljava/lang/String;)Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;
@@ -1701,6 +1702,7 @@ public abstract interface class com/facebook/react/common/mapbuffer/MapBuffer$En
 	public abstract fun getIntValue ()I
 	public abstract fun getKey ()I
 	public abstract fun getLongValue ()J
+	public abstract fun getMapBufferListValue ()Ljava/util/List;
 	public abstract fun getMapBufferValue ()Lcom/facebook/react/common/mapbuffer/MapBuffer;
 	public abstract fun getStringValue ()Ljava/lang/String;
 	public abstract fun getType ()Lcom/facebook/react/common/mapbuffer/MapBuffer$DataType;

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/common/mapbuffer/MapBuffer.kt

@@ -48,6 +48,7 @@ public interface MapBuffer : Iterable<MapBuffer.Entry> {
     LONG,
     INT_BUFFER,
     DOUBLE_BUFFER,
+    MAP_BUFFER_LIST,
   }
 
   /**
@@ -153,8 +154,8 @@ public interface MapBuffer : Iterable<MapBuffer.Entry> {
   public fun getMapBuffer(key: Int): MapBuffer
 
   /**
-   * Provides parsed [List<MapBuffer>] value if the entry for given key exists with [DataType.MAP]
-   * type
+   * Provides parsed [List<MapBuffer>] value if the entry for given key exists with
+   * [DataType.MAP_BUFFER_LIST] type
    *
    * @param key key to lookup [List<MapBuffer>] value for
    * @return value associated with the requested key
@@ -253,5 +254,12 @@ public interface MapBuffer : Iterable<MapBuffer.Entry> {
      * @throws IllegalStateException if the data type doesn't match [DataType.DOUBLE_BUFFER]
      */
     public val doubleBufferValue: DoubleArray
+
+    /**
+     * Entry value represented as [List<MapBuffer>]
+     *
+     * @throws IllegalStateException if the data type doesn't match [DataType.MAP_BUFFER_LIST]
+     */
+    public val mapBufferListValue: List<MapBuffer>
   }
 }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/common/mapbuffer/ReadableMapBuffer.kt

@@ -209,7 +209,7 @@ private constructor(
       readMapBufferValue(getTypedValueOffsetForKey(key, MapBuffer.DataType.MAP))
 
   override fun getMapBufferList(key: Int): List<ReadableMapBuffer> =
-      readMapBufferListValue(getTypedValueOffsetForKey(key, MapBuffer.DataType.MAP))
+      readMapBufferListValue(getTypedValueOffsetForKey(key, MapBuffer.DataType.MAP_BUFFER_LIST))
 
   override fun getIntBuffer(key: Int): IntArray =
       readIntBufferValue(getTypedValueOffsetForKey(key, MapBuffer.DataType.INT_BUFFER))
@@ -255,6 +255,7 @@ private constructor(
           MapBuffer.DataType.MAP -> append(entry.mapBufferValue.toString())
           MapBuffer.DataType.INT_BUFFER -> append(entry.intBufferValue.contentToString())
           MapBuffer.DataType.DOUBLE_BUFFER -> append(entry.doubleBufferValue.contentToString())
+          MapBuffer.DataType.MAP_BUFFER_LIST -> append(entry.mapBufferListValue.toString())
         }
       }
     }
@@ -349,6 +350,12 @@ private constructor(
         assertType(MapBuffer.DataType.DOUBLE_BUFFER)
         return readDoubleBufferValue(bucketOffset + VALUE_OFFSET)
       }
+
+    override val mapBufferListValue: List<MapBuffer>
+      get() {
+        assertType(MapBuffer.DataType.MAP_BUFFER_LIST)
+        return readMapBufferListValue(bucketOffset + VALUE_OFFSET)
+      }
   }
 
   public companion object {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/common/mapbuffer/WritableMapBuffer.kt

@@ -206,6 +206,9 @@ internal class WritableMapBuffer : MapBuffer {
 
     override val doubleBufferValue: DoubleArray
       get() = verifyValue(key, values.valueAt(index))
+
+    override val mapBufferListValue: List<MapBuffer>
+      get() = verifyValue(key, values.valueAt(index))
   }
 
   /*

packages/react-native/ReactCommon/react/renderer/mapbuffer/MapBuffer.h

@@ -112,6 +112,10 @@ class MapBuffer {
     // array within the dynamic data section.
     IntBuffer = 6,
     DoubleBuffer = 7,
+    // A homogeneous, ordered array of nested MapBuffers. Distinct from `Map` so
+    // that a list of MapBuffers is self-describing (a single Map and a list are
+    // byte-distinct in payload but previously shared the `Map` type tag).
+    MapBufferList = 8,
   };
 
   explicit MapBuffer(std::vector<uint8_t> data);

packages/react-native/ReactCommon/react/renderer/mapbuffer/MapBufferBuilder.cpp

@@ -153,10 +153,11 @@ void MapBufferBuilder::putMapBufferList(
         mapBufferSize);
   }
 
-  // Store Key and pointer to the string
+  // Store Key and pointer to the list. Uses the dedicated MapBufferList type so
+  // the entry is self-describing and distinguishable from a single Map.
   storeKeyValue(
       key,
-      MapBuffer::DataType::Map,
+      MapBuffer::DataType::MapBufferList,
       reinterpret_cast<const uint8_t*>(&offset),
       INT_SIZE);
 }

scripts/cxx-api/api-snapshots/ReactAndroidDebugCxx.api

@@ -3264,6 +3264,7 @@ enum facebook::react::MapBuffer::DataType : uint16_t {
   IntBuffer,
   Long,
   Map,
+  MapBufferList,
   String,
 }
 

scripts/cxx-api/api-snapshots/ReactAndroidNewarchCxx.api

@@ -3173,6 +3173,7 @@ enum facebook::react::MapBuffer::DataType : uint16_t {
   IntBuffer,
   Long,
   Map,
+  MapBufferList,
   String,
 }
 

scripts/cxx-api/api-snapshots/ReactAndroidReleaseCxx.api

@@ -3261,6 +3261,7 @@ enum facebook::react::MapBuffer::DataType : uint16_t {
   IntBuffer,
   Long,
   Map,
+  MapBufferList,
   String,
 }
 

scripts/cxx-api/api-snapshots/ReactAppleDebugCxx.api

@@ -5499,6 +5499,7 @@ enum facebook::react::MapBuffer::DataType : uint16_t {
   IntBuffer,
   Long,
   Map,
+  MapBufferList,
   String,
 }