react-native-nitro-list 0.1.1 → 0.1.3

package/nitrogen/generated/ios/c++/{HybridNitroLayoutEngineSpecSwift.hpp → HybridNitroListSpecSwift.hpp}

@@ -1,5 +1,5 @@
 ///
-/// HybridNitroLayoutEngineSpecSwift.hpp
+/// HybridNitroListSpecSwift.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -7,15 +7,15 @@
 
 #pragma once
 
-#include "HybridNitroLayoutEngineSpec.hpp"
+#include "HybridNitroListSpec.hpp"
 
-// Forward declaration of `HybridNitroLayoutEngineSpec_cxx` to properly resolve imports.
-namespace NitroList { class HybridNitroLayoutEngineSpec_cxx; }
+// Forward declaration of `HybridNitroListSpec_cxx` to properly resolve imports.
+namespace NitroList { class HybridNitroListSpec_cxx; }
 
-// Forward declaration of `LayoutRectangle` to properly resolve imports.
-namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
+// Forward declaration of `ItemLayout` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct ItemLayout; }
 
-#include "LayoutRectangle.hpp"
+#include "ItemLayout.hpp"
 #include <vector>
 
 #include "NitroList-Swift-Cxx-Umbrella.hpp"
@@ -23,25 +23,25 @@ namespace margelo::nitro::nitrolist { struct LayoutRectangle; }
 namespace margelo::nitro::nitrolist {
 
   /**
-   * The C++ part of HybridNitroLayoutEngineSpec_cxx.swift.
+   * The C++ part of HybridNitroListSpec_cxx.swift.
    *
-   * HybridNitroLayoutEngineSpecSwift (C++) accesses HybridNitroLayoutEngineSpec_cxx (Swift), and might
+   * HybridNitroListSpecSwift (C++) accesses HybridNitroListSpec_cxx (Swift), and might
    * contain some additional bridging code for C++ <> Swift interop.
    *
    * Since this obviously introduces an overhead, I hope at some point in
-   * the future, HybridNitroLayoutEngineSpec_cxx can directly inherit from the C++ class HybridNitroLayoutEngineSpec
+   * the future, HybridNitroListSpec_cxx can directly inherit from the C++ class HybridNitroListSpec
    * to simplify the whole structure and memory management.
    */
-  class HybridNitroLayoutEngineSpecSwift: public virtual HybridNitroLayoutEngineSpec {
+  class HybridNitroListSpecSwift: public virtual HybridNitroListSpec {
   public:
     // Constructor from a Swift instance
-    explicit HybridNitroLayoutEngineSpecSwift(const NitroList::HybridNitroLayoutEngineSpec_cxx& swiftPart):
-      HybridObject(HybridNitroLayoutEngineSpec::TAG),
+    explicit HybridNitroListSpecSwift(const NitroList::HybridNitroListSpec_cxx& swiftPart):
+      HybridObject(HybridNitroListSpec::TAG),
       _swiftPart(swiftPart) { }
 
   public:
     // Get the Swift part
-    inline NitroList::HybridNitroLayoutEngineSpec_cxx& getSwiftPart() noexcept {
+    inline NitroList::HybridNitroListSpec_cxx& getSwiftPart() noexcept {
       return _swiftPart;
     }
 
@@ -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<ItemLayout> 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());
@@ -72,7 +72,7 @@ namespace margelo::nitro::nitrolist {
     }
 
   private:
-    NitroList::HybridNitroLayoutEngineSpec_cxx _swiftPart;
+    NitroList::HybridNitroListSpec_cxx _swiftPart;
   };
 
 } // namespace margelo::nitro::nitrolist

package/nitrogen/generated/ios/swift/HybridNitroListSpec.swift

@@ -0,0 +1,56 @@
+///
+/// HybridNitroListSpec.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+import Foundation
+import NitroModules
+
+/// See ``HybridNitroListSpec``
+public protocol HybridNitroListSpec_protocol: HybridObject {
+  // Properties
+  
+
+  // Methods
+  func computeLayout(containerWidth: Double, itemHeights: [Double]) throws -> [ItemLayout]
+}
+
+public extension HybridNitroListSpec_protocol {
+  /// Default implementation of ``HybridObject.toString``
+  func toString() -> String {
+    return "[HybridObject NitroList]"
+  }
+}
+
+/// See ``HybridNitroListSpec``
+open class HybridNitroListSpec_base {
+  private weak var cxxWrapper: HybridNitroListSpec_cxx? = nil
+  public init() { }
+  public func getCxxWrapper() -> HybridNitroListSpec_cxx {
+  #if DEBUG
+    guard self is HybridNitroListSpec else {
+      fatalError("`self` is not a `HybridNitroListSpec`! Did you accidentally inherit from `HybridNitroListSpec_base` instead of `HybridNitroListSpec`?")
+    }
+  #endif
+    if let cxxWrapper = self.cxxWrapper {
+      return cxxWrapper
+    } else {
+      let cxxWrapper = HybridNitroListSpec_cxx(self as! HybridNitroListSpec)
+      self.cxxWrapper = cxxWrapper
+      return cxxWrapper
+    }
+  }
+}
+
+/**
+ * A Swift base-protocol representing the NitroList HybridObject.
+ * Implement this protocol to create Swift-based instances of NitroList.
+ * ```swift
+ * class HybridNitroList : HybridNitroListSpec {
+ *   // ...
+ * }
+ * ```
+ */
+public typealias HybridNitroListSpec = HybridNitroListSpec_protocol & HybridNitroListSpec_base

package/nitrogen/generated/ios/swift/{HybridNitroLayoutEngineSpec_cxx.swift → HybridNitroListSpec_cxx.swift}

@@ -1,5 +1,5 @@
 ///
-/// HybridNitroLayoutEngineSpec_cxx.swift
+/// HybridNitroListSpec_cxx.swift
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -9,7 +9,7 @@ import Foundation
 import NitroModules
 
 /**
- * A class implementation that bridges HybridNitroLayoutEngineSpec over to C++.
+ * A class implementation that bridges HybridNitroListSpec over to C++.
  * In C++, we cannot use Swift protocols - so we need to wrap it in a class to make it strongly defined.
  *
  * Also, some Swift types need to be bridged with special handling:
@@ -17,7 +17,7 @@ import NitroModules
  * - Other HybridObjects need to be wrapped/unwrapped from the Swift TCxx wrapper
  * - Throwing methods need to be wrapped with a Result<T, Error> type, as exceptions cannot be propagated to C++
  */
-open class HybridNitroLayoutEngineSpec_cxx {
+open class HybridNitroListSpec_cxx {
   /**
    * The Swift <> C++ bridge's namespace (`margelo::nitro::nitrolist::bridge::swift`)
    * from `NitroList-Swift-Cxx-Bridge.hpp`.
@@ -26,30 +26,30 @@ open class HybridNitroLayoutEngineSpec_cxx {
   public typealias bridge = margelo.nitro.nitrolist.bridge.swift
 
   /**
-   * Holds an instance of the `HybridNitroLayoutEngineSpec` Swift protocol.
+   * Holds an instance of the `HybridNitroListSpec` Swift protocol.
    */
-  private var __implementation: any HybridNitroLayoutEngineSpec
+  private var __implementation: any HybridNitroListSpec
 
   /**
    * Holds a weak pointer to the C++ class that wraps the Swift class.
    */
-  private var __cxxPart: bridge.std__weak_ptr_HybridNitroLayoutEngineSpec_
+  private var __cxxPart: bridge.std__weak_ptr_HybridNitroListSpec_
 
   /**
-   * Create a new `HybridNitroLayoutEngineSpec_cxx` that wraps the given `HybridNitroLayoutEngineSpec`.
+   * Create a new `HybridNitroListSpec_cxx` that wraps the given `HybridNitroListSpec`.
    * All properties and methods bridge to C++ types.
    */
-  public init(_ implementation: any HybridNitroLayoutEngineSpec) {
+  public init(_ implementation: any HybridNitroListSpec) {
     self.__implementation = implementation
     self.__cxxPart = .init()
     /* no base class */
   }
 
   /**
-   * Get the actual `HybridNitroLayoutEngineSpec` instance this class wraps.
+   * Get the actual `HybridNitroListSpec` instance this class wraps.
    */
   @inline(__always)
-  public func getHybridNitroLayoutEngineSpec() -> any HybridNitroLayoutEngineSpec {
+  public func getHybridNitroListSpec() -> any HybridNitroListSpec {
     return __implementation
   }
 
@@ -62,25 +62,25 @@ open class HybridNitroLayoutEngineSpec_cxx {
   }
 
   /**
-   * Casts an unsafe pointer to a `HybridNitroLayoutEngineSpec_cxx`.
-   * The pointer has to be a retained opaque `Unmanaged<HybridNitroLayoutEngineSpec_cxx>`.
+   * Casts an unsafe pointer to a `HybridNitroListSpec_cxx`.
+   * The pointer has to be a retained opaque `Unmanaged<HybridNitroListSpec_cxx>`.
    * This removes one strong reference from the object!
    */
-  public class func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> HybridNitroLayoutEngineSpec_cxx {
-    return Unmanaged<HybridNitroLayoutEngineSpec_cxx>.fromOpaque(pointer).takeRetainedValue()
+  public class func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> HybridNitroListSpec_cxx {
+    return Unmanaged<HybridNitroListSpec_cxx>.fromOpaque(pointer).takeRetainedValue()
   }
 
   /**
    * Gets (or creates) the C++ part of this Hybrid Object.
-   * The C++ part is a `std::shared_ptr<HybridNitroLayoutEngineSpec>`.
+   * The C++ part is a `std::shared_ptr<HybridNitroListSpec>`.
    */
-  public func getCxxPart() -> bridge.std__shared_ptr_HybridNitroLayoutEngineSpec_ {
+  public func getCxxPart() -> bridge.std__shared_ptr_HybridNitroListSpec_ {
     let cachedCxxPart = self.__cxxPart.lock()
     if Bool(fromCxx: cachedCxxPart) {
       return cachedCxxPart
     } else {
-      let newCxxPart = bridge.create_std__shared_ptr_HybridNitroLayoutEngineSpec_(self.toUnsafe())
-      __cxxPart = bridge.weakify_std__shared_ptr_HybridNitroLayoutEngineSpec_(newCxxPart)
+      let newCxxPart = bridge.create_std__shared_ptr_HybridNitroListSpec_(self.toUnsafe())
+      __cxxPart = bridge.weakify_std__shared_ptr_HybridNitroListSpec_(newCxxPart)
       return newCxxPart
     }
   }
@@ -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_ItemLayout__ {
     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_ItemLayout_ in
+        var __vector = bridge.create_std__vector_ItemLayout_(__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_ItemLayout__(__resultCpp)
     } catch (let __error) {
       let __exceptionPtr = __error.toCpp()
-      return bridge.create_Result_std__vector_LayoutRectangle__(__exceptionPtr)
+      return bridge.create_Result_std__vector_ItemLayout__(__exceptionPtr)
     }
   }
 }

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

@@ -1,5 +1,5 @@
 ///
-/// LayoutRectangle.swift
+/// ItemLayout.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 `ItemLayout`, backed by a C++ struct.
  */
-public typealias LayoutRectangle = margelo.nitro.nitrolist.LayoutRectangle
+public typealias ItemLayout = margelo.nitro.nitrolist.ItemLayout
 
-public extension LayoutRectangle {
+public extension ItemLayout {
   private typealias bridge = margelo.nitro.nitrolist.bridge.swift
 
   /**
-   * Create a new instance of `LayoutRectangle`.
+   * Create a new instance of `ItemLayout`.
    */
   init(x: Double, y: Double, width: Double, height: Double) {
     self.init(x, y, width, height)

package/nitrogen/generated/shared/c++/{HybridNitroLayoutEngineSpec.cpp → HybridNitroListSpec.cpp}

@@ -1,20 +1,20 @@
 ///
-/// HybridNitroLayoutEngineSpec.cpp
+/// HybridNitroListSpec.cpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
 ///
 
-#include "HybridNitroLayoutEngineSpec.hpp"
+#include "HybridNitroListSpec.hpp"
 
 namespace margelo::nitro::nitrolist {
 
-  void HybridNitroLayoutEngineSpec::loadHybridMethods() {
+  void HybridNitroListSpec::loadHybridMethods() {
     // load base methods/properties
     HybridObject::loadHybridMethods();
     // load custom methods/properties
     registerHybrids(this, [](Prototype& prototype) {
-      prototype.registerHybridMethod("computeLayout", &HybridNitroLayoutEngineSpec::computeLayout);
+      prototype.registerHybridMethod("computeLayout", &HybridNitroListSpec::computeLayout);
     });
   }
 

package/nitrogen/generated/shared/c++/{HybridNitroLayoutEngineSpec.hpp → HybridNitroListSpec.hpp}

@@ -1,5 +1,5 @@
 ///
-/// HybridNitroLayoutEngineSpec.hpp
+/// HybridNitroListSpec.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -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 `ItemLayout` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct ItemLayout; }
 
-#include "LayoutRectangle.hpp"
+#include "ItemLayout.hpp"
 #include <vector>
 
 namespace margelo::nitro::nitrolist {
@@ -24,25 +24,25 @@ namespace margelo::nitro::nitrolist {
   using namespace margelo::nitro;
 
   /**
-   * An abstract base class for `NitroLayoutEngine`
-   * Inherit this class to create instances of `HybridNitroLayoutEngineSpec` in C++.
+   * An abstract base class for `NitroList`
+   * Inherit this class to create instances of `HybridNitroListSpec` in C++.
    * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
    * @example
    * ```cpp
-   * class HybridNitroLayoutEngine: public HybridNitroLayoutEngineSpec {
+   * class HybridNitroList: public HybridNitroListSpec {
    * public:
-   *   HybridNitroLayoutEngine(...): HybridObject(TAG) { ... }
+   *   HybridNitroList(...): HybridObject(TAG) { ... }
    *   // ...
    * };
    * ```
    */
-  class HybridNitroLayoutEngineSpec: public virtual HybridObject {
+  class HybridNitroListSpec: public virtual HybridObject {
     public:
       // Constructor
-      explicit HybridNitroLayoutEngineSpec(): HybridObject(TAG) { }
+      explicit HybridNitroListSpec(): HybridObject(TAG) { }
 
       // Destructor
-      ~HybridNitroLayoutEngineSpec() override = default;
+      ~HybridNitroListSpec() override = default;
 
     public:
       // Properties
@@ -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<ItemLayout> computeLayout(double containerWidth, const std::vector<double>& itemHeights) = 0;
 
     protected:
       // Hybrid Setup
@@ -58,7 +58,7 @@ namespace margelo::nitro::nitrolist {
 
     protected:
       // Tag for logging
-      static constexpr auto TAG = "NitroLayoutEngine";
+      static constexpr auto TAG = "NitroList";
   };
 
 } // namespace margelo::nitro::nitrolist

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

@@ -1,5 +1,5 @@
 ///
-/// LayoutRectangle.hpp
+/// ItemLayout.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 (ItemLayout).
    */
-  struct LayoutRectangle final {
+  struct ItemLayout 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) {}
+    ItemLayout() = default;
+    explicit ItemLayout(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 ItemLayout& lhs, const ItemLayout& rhs) = default;
   };
 
 } // namespace margelo::nitro::nitrolist
 
 namespace margelo::nitro {
 
-  // C++ LayoutRectangle <> JS LayoutRectangle (object)
+  // C++ ItemLayout <> JS ItemLayout (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::ItemLayout> final {
+    static inline margelo::nitro::nitrolist::ItemLayout fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       jsi::Object obj = arg.asObject(runtime);
-      return margelo::nitro::nitrolist::LayoutRectangle(
+      return margelo::nitro::nitrolist::ItemLayout(
         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::ItemLayout& 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,7 +1,7 @@
 {
   "name": "react-native-nitro-list",
-  "version": "0.1.1",
-  "description": "react-native-nitro-list is a react native package built with Nitro",
+  "version": "0.1.3",
+  "description": "High-performance list for React Native powered by Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -45,11 +45,11 @@
   "workspaces": [
     "example"
   ],
-  "repository": "https://github.com/shivshankartiwari/react-native-nitro-list.git",
+  "repository": "https://github.com/pythonsst/nitro-list",
   "author": "Shiv Shankar Tiwari",
   "license": "MIT",
-  "bugs": "https://github.com/shivshankartiwari/react-native-nitro-list/issues",
-  "homepage": "https://github.com/shivshankartiwari/react-native-nitro-list#readme",
+  "bugs": "https://github.com/pythonsst/nitro-list/issues",
+  "homepage": "https://github.com/pythonsst/nitro-list#readme",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

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'