react-native-nitro-list 0.1.1 → 0.1.2

package/nitrogen/generated/android/c++/{JLayoutRectangle.hpp → JLayoutRect.hpp}

@@ -1,5 +1,5 @@
 ///
-/// JLayoutRectangle.hpp
+/// JLayoutRect.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -8,7 +8,7 @@
 #pragma once
 
 #include <fbjni/fbjni.h>
-#include "LayoutRectangle.hpp"
+#include "LayoutRect.hpp"
 
 
 
@@ -17,19 +17,19 @@ namespace margelo::nitro::nitrolist {
   using namespace facebook;
 
   /**
-   * The C++ JNI bridge between the C++ struct "LayoutRectangle" and the the Kotlin data class "LayoutRectangle".
+   * The C++ JNI bridge between the C++ struct "LayoutRect" and the the Kotlin data class "LayoutRect".
    */
-  struct JLayoutRectangle final: public jni::JavaClass<JLayoutRectangle> {
+  struct JLayoutRect final: public jni::JavaClass<JLayoutRect> {
   public:
-    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitrolist/LayoutRectangle;";
+    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitrolist/LayoutRect;";
 
   public:
     /**
-     * Convert this Java/Kotlin-based struct to the C++ struct LayoutRectangle by copying all values to C++.
+     * Convert this Java/Kotlin-based struct to the C++ struct LayoutRect by copying all values to C++.
      */
     [[maybe_unused]]
     [[nodiscard]]
-    LayoutRectangle toCpp() const {
+    LayoutRect toCpp() const {
       static const auto clazz = javaClassStatic();
       static const auto fieldX = clazz->getField<double>("x");
       double x = this->getFieldValue(fieldX);
@@ -39,7 +39,7 @@ namespace margelo::nitro::nitrolist {
       double width = this->getFieldValue(fieldWidth);
       static const auto fieldHeight = clazz->getField<double>("height");
       double height = this->getFieldValue(fieldHeight);
-      return LayoutRectangle(
+      return LayoutRect(
         x,
         y,
         width,
@@ -52,8 +52,8 @@ namespace margelo::nitro::nitrolist {
      * Create a Java/Kotlin-based struct by copying all values from the given C++ struct to Java.
      */
     [[maybe_unused]]
-    static jni::local_ref<JLayoutRectangle::javaobject> fromCpp(const LayoutRectangle& value) {
-      using JSignature = JLayoutRectangle(double, double, double, double);
+    static jni::local_ref<JLayoutRect::javaobject> fromCpp(const LayoutRect& value) {
+      using JSignature = JLayoutRect(double, double, double, double);
       static const auto clazz = javaClassStatic();
       static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
       return create(

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitrolist/HybridNitroLayoutEngineSpec.kt

@@ -47,7 +47,7 @@ abstract class HybridNitroLayoutEngineSpec: HybridObject() {
   // Methods
   @DoNotStrip
   @Keep
-  abstract fun computeLayout(containerWidth: Double, itemHeights: DoubleArray): Array<LayoutRectangle>
+  abstract fun computeLayout(containerWidth: Double, itemHeights: DoubleArray): Array<LayoutRect>
 
   private external fun initHybrid(): HybridData
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitrolist/{LayoutRectangle.kt → LayoutRect.kt}

@@ -1,5 +1,5 @@
 ///
-/// LayoutRectangle.kt
+/// LayoutRect.kt
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -12,11 +12,11 @@ import com.facebook.proguard.annotations.DoNotStrip
 
 
 /**
- * Represents the JavaScript object/struct "LayoutRectangle".
+ * Represents the JavaScript object/struct "LayoutRect".
  */
 @DoNotStrip
 @Keep
-data class LayoutRectangle(
+data class LayoutRect(
   @DoNotStrip
   @Keep
   val x: Double,
@@ -40,8 +40,8 @@ data class LayoutRectangle(
     @Keep
     @Suppress("unused")
     @JvmStatic
-    private fun fromCpp(x: Double, y: Double, width: Double, height: Double): LayoutRectangle {
-      return LayoutRectangle(x, y, width, height)
+    private fun fromCpp(x: Double, y: Double, width: Double, height: Double): LayoutRect {
+      return LayoutRect(x, y, width, height)
     }
   }
 }

package/nitrogen/generated/ios/NitroList-Swift-Cxx-Bridge.hpp

@@ -10,8 +10,8 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `HybridNitroLayoutEngineSpec` to properly resolve imports.
 namespace margelo::nitro::nitrolist { class HybridNitroLayoutEngineSpec; }
-// Forward declaration of `LayoutRectangle` to properly resolve imports.
-namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
+// Forward declaration of `LayoutRect` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct LayoutRect; }
 
 // Forward declarations of Swift defined types
 // Forward declaration of `HybridNitroLayoutEngineSpec_cxx` to properly resolve imports.
@@ -19,7 +19,7 @@ namespace NitroList { class HybridNitroLayoutEngineSpec_cxx; }
 
 // Include C++ defined types
 #include "HybridNitroLayoutEngineSpec.hpp"
-#include "LayoutRectangle.hpp"
+#include "LayoutRect.hpp"
 #include <NitroModules/Result.hpp>
 #include <exception>
 #include <memory>
@@ -31,13 +31,13 @@ namespace NitroList { class HybridNitroLayoutEngineSpec_cxx; }
  */
 namespace margelo::nitro::nitrolist::bridge::swift {
 
-  // pragma MARK: std::vector<LayoutRectangle>
+  // pragma MARK: std::vector<LayoutRect>
   /**
-   * Specialized version of `std::vector<LayoutRectangle>`.
+   * Specialized version of `std::vector<LayoutRect>`.
    */
-  using std__vector_LayoutRectangle_ = std::vector<LayoutRectangle>;
-  inline std::vector<LayoutRectangle> create_std__vector_LayoutRectangle_(size_t size) noexcept {
-    std::vector<LayoutRectangle> vector;
+  using std__vector_LayoutRect_ = std::vector<LayoutRect>;
+  inline std::vector<LayoutRect> create_std__vector_LayoutRect_(size_t size) noexcept {
+    std::vector<LayoutRect> vector;
     vector.reserve(size);
     return vector;
   }
@@ -65,13 +65,13 @@ namespace margelo::nitro::nitrolist::bridge::swift {
   using std__weak_ptr_HybridNitroLayoutEngineSpec_ = std::weak_ptr<HybridNitroLayoutEngineSpec>;
   inline std__weak_ptr_HybridNitroLayoutEngineSpec_ weakify_std__shared_ptr_HybridNitroLayoutEngineSpec_(const std::shared_ptr<HybridNitroLayoutEngineSpec>& strong) noexcept { return strong; }
   
-  // pragma MARK: Result<std::vector<LayoutRectangle>>
-  using Result_std__vector_LayoutRectangle__ = Result<std::vector<LayoutRectangle>>;
-  inline Result_std__vector_LayoutRectangle__ create_Result_std__vector_LayoutRectangle__(const std::vector<LayoutRectangle>& value) noexcept {
-    return Result<std::vector<LayoutRectangle>>::withValue(value);
+  // pragma MARK: Result<std::vector<LayoutRect>>
+  using Result_std__vector_LayoutRect__ = Result<std::vector<LayoutRect>>;
+  inline Result_std__vector_LayoutRect__ create_Result_std__vector_LayoutRect__(const std::vector<LayoutRect>& value) noexcept {
+    return Result<std::vector<LayoutRect>>::withValue(value);
   }
-  inline Result_std__vector_LayoutRectangle__ create_Result_std__vector_LayoutRectangle__(const std::exception_ptr& error) noexcept {
-    return Result<std::vector<LayoutRectangle>>::withError(error);
+  inline Result_std__vector_LayoutRect__ create_Result_std__vector_LayoutRect__(const std::exception_ptr& error) noexcept {
+    return Result<std::vector<LayoutRect>>::withError(error);
   }
 
 } // namespace margelo::nitro::nitrolist::bridge::swift

package/nitrogen/generated/ios/NitroList-Swift-Cxx-Umbrella.hpp

@@ -10,12 +10,12 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `HybridNitroLayoutEngineSpec` to properly resolve imports.
 namespace margelo::nitro::nitrolist { class HybridNitroLayoutEngineSpec; }
-// Forward declaration of `LayoutRectangle` to properly resolve imports.
-namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
+// Forward declaration of `LayoutRect` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct LayoutRect; }
 
 // Include C++ defined types
 #include "HybridNitroLayoutEngineSpec.hpp"
-#include "LayoutRectangle.hpp"
+#include "LayoutRect.hpp"
 #include <NitroModules/Result.hpp>
 #include <exception>
 #include <memory>

package/nitrogen/generated/ios/c++/HybridNitroLayoutEngineSpecSwift.hpp

@@ -12,10 +12,10 @@
 // Forward declaration of `HybridNitroLayoutEngineSpec_cxx` to properly resolve imports.
 namespace NitroList { class HybridNitroLayoutEngineSpec_cxx; }
 
-// Forward declaration of `LayoutRectangle` to properly resolve imports.
-namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
+// Forward declaration of `LayoutRect` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct LayoutRect; }
 
-#include "LayoutRectangle.hpp"
+#include "LayoutRect.hpp"
 #include <vector>
 
 #include "NitroList-Swift-Cxx-Umbrella.hpp"
@@ -62,7 +62,7 @@ namespace margelo::nitro::nitrolist {
 
   public:
     // Methods
-    inline std::vector<LayoutRectangle> computeLayout(double containerWidth, const std::vector<double>& itemHeights) override {
+    inline std::vector<LayoutRect> computeLayout(double containerWidth, const std::vector<double>& itemHeights) override {
       auto __result = _swiftPart.computeLayout(std::forward<decltype(containerWidth)>(containerWidth), itemHeights);
       if (__result.hasError()) [[unlikely]] {
         std::rethrow_exception(__result.error());

package/nitrogen/generated/ios/swift/HybridNitroLayoutEngineSpec.swift

@@ -14,7 +14,7 @@ public protocol HybridNitroLayoutEngineSpec_protocol: HybridObject {
   
 
   // Methods
-  func computeLayout(containerWidth: Double, itemHeights: [Double]) throws -> [LayoutRectangle]
+  func computeLayout(containerWidth: Double, itemHeights: [Double]) throws -> [LayoutRect]
 }
 
 public extension HybridNitroLayoutEngineSpec_protocol {

package/nitrogen/generated/ios/swift/HybridNitroLayoutEngineSpec_cxx.swift

@@ -118,20 +118,20 @@ open class HybridNitroLayoutEngineSpec_cxx {
 
   // Methods
   @inline(__always)
-  public final func computeLayout(containerWidth: Double, itemHeights: bridge.std__vector_double_) -> bridge.Result_std__vector_LayoutRectangle__ {
+  public final func computeLayout(containerWidth: Double, itemHeights: bridge.std__vector_double_) -> bridge.Result_std__vector_LayoutRect__ {
     do {
       let __result = try self.__implementation.computeLayout(containerWidth: containerWidth, itemHeights: itemHeights.map({ __item in __item }))
-      let __resultCpp = { () -> bridge.std__vector_LayoutRectangle_ in
-        var __vector = bridge.create_std__vector_LayoutRectangle_(__result.count)
+      let __resultCpp = { () -> bridge.std__vector_LayoutRect_ in
+        var __vector = bridge.create_std__vector_LayoutRect_(__result.count)
         for __item in __result {
           __vector.push_back(__item)
         }
         return __vector
       }()
-      return bridge.create_Result_std__vector_LayoutRectangle__(__resultCpp)
+      return bridge.create_Result_std__vector_LayoutRect__(__resultCpp)
     } catch (let __error) {
       let __exceptionPtr = __error.toCpp()
-      return bridge.create_Result_std__vector_LayoutRectangle__(__exceptionPtr)
+      return bridge.create_Result_std__vector_LayoutRect__(__exceptionPtr)
     }
   }
 }

package/nitrogen/generated/ios/swift/{LayoutRectangle.swift → LayoutRect.swift}

@@ -1,5 +1,5 @@
 ///
-/// LayoutRectangle.swift
+/// LayoutRect.swift
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -9,15 +9,15 @@ import Foundation
 import NitroModules
 
 /**
- * Represents an instance of `LayoutRectangle`, backed by a C++ struct.
+ * Represents an instance of `LayoutRect`, backed by a C++ struct.
  */
-public typealias LayoutRectangle = margelo.nitro.nitrolist.LayoutRectangle
+public typealias LayoutRect = margelo.nitro.nitrolist.LayoutRect
 
-public extension LayoutRectangle {
+public extension LayoutRect {
   private typealias bridge = margelo.nitro.nitrolist.bridge.swift
 
   /**
-   * Create a new instance of `LayoutRectangle`.
+   * Create a new instance of `LayoutRect`.
    */
   init(x: Double, y: Double, width: Double, height: Double) {
     self.init(x, y, width, height)

package/nitrogen/generated/shared/c++/HybridNitroLayoutEngineSpec.hpp

@@ -13,10 +13,10 @@
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
 
-// Forward declaration of `LayoutRectangle` to properly resolve imports.
-namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
+// Forward declaration of `LayoutRect` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct LayoutRect; }
 
-#include "LayoutRectangle.hpp"
+#include "LayoutRect.hpp"
 #include <vector>
 
 namespace margelo::nitro::nitrolist {
@@ -50,7 +50,7 @@ namespace margelo::nitro::nitrolist {
 
     public:
       // Methods
-      virtual std::vector<LayoutRectangle> computeLayout(double containerWidth, const std::vector<double>& itemHeights) = 0;
+      virtual std::vector<LayoutRect> computeLayout(double containerWidth, const std::vector<double>& itemHeights) = 0;
 
     protected:
       // Hybrid Setup

package/nitrogen/generated/shared/c++/{LayoutRectangle.hpp → LayoutRect.hpp}

@@ -1,5 +1,5 @@
 ///
-/// LayoutRectangle.hpp
+/// LayoutRect.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -35,9 +35,9 @@
 namespace margelo::nitro::nitrolist {
 
   /**
-   * A struct which can be represented as a JavaScript object (LayoutRectangle).
+   * A struct which can be represented as a JavaScript object (LayoutRect).
    */
-  struct LayoutRectangle final {
+  struct LayoutRect final {
   public:
     double x     SWIFT_PRIVATE;
     double y     SWIFT_PRIVATE;
@@ -45,30 +45,30 @@ namespace margelo::nitro::nitrolist {
     double height     SWIFT_PRIVATE;
 
   public:
-    LayoutRectangle() = default;
-    explicit LayoutRectangle(double x, double y, double width, double height): x(x), y(y), width(width), height(height) {}
+    LayoutRect() = default;
+    explicit LayoutRect(double x, double y, double width, double height): x(x), y(y), width(width), height(height) {}
 
   public:
-    friend bool operator==(const LayoutRectangle& lhs, const LayoutRectangle& rhs) = default;
+    friend bool operator==(const LayoutRect& lhs, const LayoutRect& rhs) = default;
   };
 
 } // namespace margelo::nitro::nitrolist
 
 namespace margelo::nitro {
 
-  // C++ LayoutRectangle <> JS LayoutRectangle (object)
+  // C++ LayoutRect <> JS LayoutRect (object)
   template <>
-  struct JSIConverter<margelo::nitro::nitrolist::LayoutRectangle> final {
-    static inline margelo::nitro::nitrolist::LayoutRectangle fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+  struct JSIConverter<margelo::nitro::nitrolist::LayoutRect> final {
+    static inline margelo::nitro::nitrolist::LayoutRect fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       jsi::Object obj = arg.asObject(runtime);
-      return margelo::nitro::nitrolist::LayoutRectangle(
+      return margelo::nitro::nitrolist::LayoutRect(
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "x"))),
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "y"))),
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width"))),
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))
       );
     }
-    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitrolist::LayoutRectangle& arg) {
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitrolist::LayoutRect& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "x"), JSIConverter<double>::toJSI(runtime, arg.x));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "y"), JSIConverter<double>::toJSI(runtime, arg.y));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-list",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "react-native-nitro-list is a react native package built with Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/cell/Cell.ts

@@ -1,14 +1,23 @@
 /**
  * Physical reusable cell.
- * Mirrors FlashList's Cell abstraction.
+ * Represents a single mounted view instance.
  */
 export interface Cell {
-  /** Stable physical identity (never changes) */
+  /**
+   * Stable physical identity.
+   * Used as React key. NEVER changes.
+   */
   readonly key: string
 
-  /** Logical data index currently bound */
+  /**
+   * Logical data index currently bound.
+   * Changes as the cell is recycled.
+   */
   index: number
 
-  /** Compatibility type (row, header, etc.) */
+  /**
+   * Compatibility type (row, header, etc).
+   * Determines reuse eligibility.
+   */
   readonly type: string
 }

package/src/cell/CellKeyGenerator.ts

@@ -0,0 +1,17 @@
+import type { CellKey } from '../types/CellKey'
+
+/**
+ * Monotonic key generator for physical cell instances.
+ * Guarantees stable keys across the lifetime of the list.
+ */
+export class CellKeyGenerator {
+  private nextId = 0
+
+  next(): CellKey {
+    return this.nextId++
+  }
+
+  reset(): void {
+    this.nextId = 0
+  }
+}

package/src/cell/CellRecycler.ts

@@ -1,66 +1,76 @@
 import type { Cell } from './Cell'
-
-const MAX_CELLS = 40
+import { createCell } from './createCell'
 
 /**
- * Owns physical cell reuse.
- * Stateful, imperative, React-agnostic.
- *
- * FlashList equivalent: CellRecycler
+ * Manages physical cell reuse.
+ * Imperative and stateful by design.
+ * This is NOT React code.
  */
 export class CellRecycler {
-  private readonly activeCells = new Map<number, Cell>()
-  private readonly reusableCellsByType = new Map<string, Cell[]>()
-  private readonly orderedCells: Cell[] = []
-  private nextCellId = 0
+  /**
+   * Active cells mapped by logical index.
+   */
+  private readonly indexToCell = new Map<number, Cell>()
+
+  /**
+   * Pool of detached reusable cells.
+   */
+  private readonly recycledCells: Cell[] = []
 
   /**
-   * Reconcile visible indices against existing cells.
-   * Returns a stable ordered snapshot.
+   * Reconcile a contiguous visible index range
+   * into a stable list of physical cells.
+   *
+   * HOT PATH:
+   * - No index arrays
+   * - Minimal allocations
+   * - Deterministic
    */
-  reconcile(
-    visibleIndices: readonly number[],
-    getCellType: (index: number) => string
+  reconcileRange(
+    startIndex: number,
+    endIndex: number,
+    resolveCellType: (index: number) => string
   ): readonly Cell[] {
-    const visibleSet = new Set(visibleIndices)
+    const nextActive: Cell[] = []
 
-    // 1️⃣ Release cells no longer visible
-    for (const [index, cell] of this.activeCells) {
-      if (visibleSet.has(index)) continue
+    // Track which current indices are no longer visible
+    const unusedIndices = new Set(this.indexToCell.keys())
 
-      this.activeCells.delete(index)
+    for (let index = startIndex; index <= endIndex; index++) {
+      unusedIndices.delete(index)
 
-      const orderedIndex = this.orderedCells.indexOf(cell)
-      if (orderedIndex !== -1) {
-        this.orderedCells.splice(orderedIndex, 1)
+      let cell = this.indexToCell.get(index)
+      if (cell) {
+        // Existing assignment — reuse
+        nextActive.push(cell)
+        continue
       }
 
-      const pool = this.reusableCellsByType.get(cell.type) ?? []
-      if (pool.length < MAX_CELLS) pool.push(cell)
-      this.reusableCellsByType.set(cell.type, pool)
-    }
-
-    // 2️⃣ Acquire cells for newly visible indices
-    for (const index of visibleIndices) {
-      if (this.activeCells.has(index)) continue
+      const type = resolveCellType(index)
 
-      const type = getCellType(index)
-      const pool = this.reusableCellsByType.get(type)
-      let cell = pool?.pop()
+      // Try to reuse a recycled cell of same type
+      const recycledIdx = this.recycledCells.findIndex(
+        c => c.type === type
+      )
 
-      if (!cell) {
-        cell = {
-          key: `cell-${this.nextCellId++}`,
-          type,
-          index,
-        }
+      if (recycledIdx !== -1) {
+        cell = this.recycledCells.splice(recycledIdx, 1)[0]!
+      } else {
+        cell = createCell(type)
       }
 
       cell.index = index
-      this.activeCells.set(index, cell)
-      this.orderedCells.push(cell)
+      this.indexToCell.set(index, cell)
+      nextActive.push(cell)
+    }
+
+    // Recycle cells that left the visible window
+    for (const index of unusedIndices) {
+      const cell = this.indexToCell.get(index)!
+      this.indexToCell.delete(index)
+      this.recycledCells.push(cell)
     }
 
-    return this.orderedCells
+    return nextActive
   }
 }

package/src/cell/createCell.ts

@@ -0,0 +1,15 @@
+import type { Cell } from './Cell'
+
+let nextCellId = 0
+
+/**
+ * Creates a new physical cell with a stable identity.
+ * The key is generated ONCE and never changes.
+ */
+export function createCell(type: string): Cell {
+  return {
+    key: `cell-${nextCellId++}`, // stable physical identity
+    type,
+    index: -1,                  // assigned by recycler
+  }
+}

package/src/cell/index.ts

@@ -0,0 +1,5 @@
+// Public cell-layer exports
+
+export type { Cell } from './Cell'
+export { CellRecycler } from './CellRecycler'
+export { createCell } from './createCell'

package/src/getVisibleIndices.ts

@@ -1,4 +1,6 @@
-import type { LayoutRectangle } from './layout/LayoutRectangle'
+
+
+import type { LayoutRect } from './types/layout'
 import type { ScrollMetrics } from './windowing/ScrollMetrics'
 
 /**
@@ -6,7 +8,7 @@ import type { ScrollMetrics } from './windowing/ScrollMetrics'
  * Returns indices intersecting viewport ± buffer.
  */
 export function getVisibleRange(
-  layouts: readonly LayoutRectangle[],
+  layouts: readonly LayoutRect[],
   metrics: ScrollMetrics,
   bufferPx: number
 ): readonly number[] {

package/src/hooks/usePersistentCallback.ts

@@ -0,0 +1,37 @@
+import { useRef, useCallback } from 'react'
+
+/**
+ * Returns a function whose identity is stable across renders,
+ * but always invokes the latest provided implementation.
+ *
+ * Invariants:
+ * - Function reference NEVER changes
+ * - Logic is ALWAYS up to date
+ *
+ * This is critical for long-lived systems such as:
+ * - Recyclers
+ * - Effects
+ * - Native bridges
+ * - Event pipelines
+ */
+export function usePersistentCallback<
+  T extends (...args: never[]) => unknown
+>(fn: T): T {
+
+  /**
+   * Holds the latest implementation.
+   * Updating this does NOT trigger re-renders.
+   */
+  const fnRef = useRef(fn)
+  fnRef.current = fn
+
+  /**
+   * Stable wrapper that forwards calls
+   * to the latest implementation.
+   */
+  return useCallback(
+    ((...args: never[]) =>
+      fnRef.current(...args)) as T,
+    []
+  )
+}

package/src/index.ts

@@ -1,2 +1 @@
-export { RecyclerList } from './RecyclerList'
-export type { RecyclerListProps } from './RecyclerList.types'
+export { RecyclerList } from './recycler/RecyclerList'