react-native-nitro-list 0.1.1 → 0.1.2

package/ios/HybridNitroList.swift

@@ -5,31 +5,27 @@ import NitroModules
  * Native layout engine for RecyclerList.
  * Pure, deterministic, synchronous computation.
  */
-final class HybridNitroList: HybridNitroListSpec {
+final class HybridNitroLayoutEngine: HybridNitroLayoutEngineSpec {
 
-  /**
-   * Computes absolute layout rectangles for all items.
-   * Called synchronously via JSI.
-   */
   func computeLayout(
     containerWidth: Double,
     itemHeights: [Double]
-  ) -> [LayoutRectangle] {
+  ) -> [LayoutRect] {
 
-    var layouts: [LayoutRectangle] = []
+    var layouts: [LayoutRect] = []
     layouts.reserveCapacity(itemHeights.count)
 
     var currentY: Double = 0
 
     for height in itemHeights {
-      let rect = LayoutRectangle(
-        x: 0,
-        y: currentY,
-        width: containerWidth,
-        height: height
+      layouts.append(
+        LayoutRect(
+          x: 0,
+          y: currentY,
+          width: containerWidth,
+          height: height
+        )
       )
-
-      layouts.append(rect)
       currentY += height
     }
 

package/lib/commonjs/cell/CellKeyGenerator.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CellKeyGenerator = void 0;
+/**
+ * Monotonic key generator for physical cell instances.
+ * Guarantees stable keys across the lifetime of the list.
+ */
+class CellKeyGenerator {
+  nextId = 0;
+  next() {
+    return this.nextId++;
+  }
+  reset() {
+    this.nextId = 0;
+  }
+}
+exports.CellKeyGenerator = CellKeyGenerator;
+//# sourceMappingURL=CellKeyGenerator.js.map

package/lib/commonjs/cell/CellKeyGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CellKeyGenerator","nextId","next","reset","exports"],"sourceRoot":"../../../src","sources":["cell/CellKeyGenerator.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;AACO,MAAMA,gBAAgB,CAAC;EACpBC,MAAM,GAAG,CAAC;EAElBC,IAAIA,CAAA,EAAY;IACd,OAAO,IAAI,CAACD,MAAM,EAAE;EACtB;EAEAE,KAAKA,CAAA,EAAS;IACZ,IAAI,CAACF,MAAM,GAAG,CAAC;EACjB;AACF;AAACG,OAAA,CAAAJ,gBAAA,GAAAA,gBAAA","ignoreList":[]}

package/lib/commonjs/cell/CellRecycler.js

@@ -4,58 +4,66 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.CellRecycler = void 0;
-const MAX_CELLS = 40;
-
+var _createCell = require("./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.
  */
 class CellRecycler {
-  activeCells = new Map();
-  reusableCellsByType = new Map();
-  orderedCells = [];
-  nextCellId = 0;
+  /**
+   * Active cells mapped by logical index.
+   */
+  indexToCell = new Map();
 
   /**
-   * Reconcile visible indices against existing cells.
-   * Returns a stable ordered snapshot.
+   * Pool of detached reusable cells.
    */
-  reconcile(visibleIndices, getCellType) {
-    const visibleSet = new Set(visibleIndices);
+  recycledCells = [];
 
-    // 1️⃣ Release cells no longer visible
-    for (const [index, cell] of this.activeCells) {
-      if (visibleSet.has(index)) continue;
-      this.activeCells.delete(index);
-      const orderedIndex = this.orderedCells.indexOf(cell);
-      if (orderedIndex !== -1) {
-        this.orderedCells.splice(orderedIndex, 1);
+  /**
+   * Reconcile a contiguous visible index range
+   * into a stable list of physical cells.
+   *
+   * HOT PATH:
+   * - No index arrays
+   * - Minimal allocations
+   * - Deterministic
+   */
+  reconcileRange(startIndex, endIndex, resolveCellType) {
+    const nextActive = [];
+
+    // Track which current indices are no longer visible
+    const unusedIndices = new Set(this.indexToCell.keys());
+    for (let index = startIndex; index <= endIndex; index++) {
+      unusedIndices.delete(index);
+      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);
-    }
+      const type = resolveCellType(index);
 
-    // 2️⃣ Acquire cells for newly visible indices
-    for (const index of visibleIndices) {
-      if (this.activeCells.has(index)) continue;
-      const type = getCellType(index);
-      const pool = this.reusableCellsByType.get(type);
-      let cell = pool?.pop();
-      if (!cell) {
-        cell = {
-          key: `cell-${this.nextCellId++}`,
-          type,
-          index
-        };
+      // Try to reuse a recycled cell of same type
+      const recycledIdx = this.recycledCells.findIndex(c => c.type === type);
+      if (recycledIdx !== -1) {
+        cell = this.recycledCells.splice(recycledIdx, 1)[0];
+      } else {
+        cell = (0, _createCell.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;
   }
 }
 exports.CellRecycler = CellRecycler;

package/lib/commonjs/cell/CellRecycler.js.map

@@ -1 +1 @@
-{"version":3,"names":["MAX_CELLS","CellRecycler","activeCells","Map","reusableCellsByType","orderedCells","nextCellId","reconcile","visibleIndices","getCellType","visibleSet","Set","index","cell","has","delete","orderedIndex","indexOf","splice","pool","get","type","length","push","set","pop","key","exports"],"sourceRoot":"../../../src","sources":["cell/CellRecycler.ts"],"mappings":";;;;;;AAEA,MAAMA,SAAS,GAAG,EAAE;;AAEpB;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,YAAY,CAAC;EACPC,WAAW,GAAG,IAAIC,GAAG,CAAe,CAAC;EACrCC,mBAAmB,GAAG,IAAID,GAAG,CAAiB,CAAC;EAC/CE,YAAY,GAAW,EAAE;EAClCC,UAAU,GAAG,CAAC;;EAEtB;AACF;AACA;AACA;EACEC,SAASA,CACPC,cAAiC,EACjCC,WAAsC,EACrB;IACjB,MAAMC,UAAU,GAAG,IAAIC,GAAG,CAACH,cAAc,CAAC;;IAE1C;IACA,KAAK,MAAM,CAACI,KAAK,EAAEC,IAAI,CAAC,IAAI,IAAI,CAACX,WAAW,EAAE;MAC5C,IAAIQ,UAAU,CAACI,GAAG,CAACF,KAAK,CAAC,EAAE;MAE3B,IAAI,CAACV,WAAW,CAACa,MAAM,CAACH,KAAK,CAAC;MAE9B,MAAMI,YAAY,GAAG,IAAI,CAACX,YAAY,CAACY,OAAO,CAACJ,IAAI,CAAC;MACpD,IAAIG,YAAY,KAAK,CAAC,CAAC,EAAE;QACvB,IAAI,CAACX,YAAY,CAACa,MAAM,CAACF,YAAY,EAAE,CAAC,CAAC;MAC3C;MAEA,MAAMG,IAAI,GAAG,IAAI,CAACf,mBAAmB,CAACgB,GAAG,CAACP,IAAI,CAACQ,IAAI,CAAC,IAAI,EAAE;MAC1D,IAAIF,IAAI,CAACG,MAAM,GAAGtB,SAAS,EAAEmB,IAAI,CAACI,IAAI,CAACV,IAAI,CAAC;MAC5C,IAAI,CAACT,mBAAmB,CAACoB,GAAG,CAACX,IAAI,CAACQ,IAAI,EAAEF,IAAI,CAAC;IAC/C;;IAEA;IACA,KAAK,MAAMP,KAAK,IAAIJ,cAAc,EAAE;MAClC,IAAI,IAAI,CAACN,WAAW,CAACY,GAAG,CAACF,KAAK,CAAC,EAAE;MAEjC,MAAMS,IAAI,GAAGZ,WAAW,CAACG,KAAK,CAAC;MAC/B,MAAMO,IAAI,GAAG,IAAI,CAACf,mBAAmB,CAACgB,GAAG,CAACC,IAAI,CAAC;MAC/C,IAAIR,IAAI,GAAGM,IAAI,EAAEM,GAAG,CAAC,CAAC;MAEtB,IAAI,CAACZ,IAAI,EAAE;QACTA,IAAI,GAAG;UACLa,GAAG,EAAE,QAAQ,IAAI,CAACpB,UAAU,EAAE,EAAE;UAChCe,IAAI;UACJT;QACF,CAAC;MACH;MAEAC,IAAI,CAACD,KAAK,GAAGA,KAAK;MAClB,IAAI,CAACV,WAAW,CAACsB,GAAG,CAACZ,KAAK,EAAEC,IAAI,CAAC;MACjC,IAAI,CAACR,YAAY,CAACkB,IAAI,CAACV,IAAI,CAAC;IAC9B;IAEA,OAAO,IAAI,CAACR,YAAY;EAC1B;AACF;AAACsB,OAAA,CAAA1B,YAAA,GAAAA,YAAA","ignoreList":[]}
+{"version":3,"names":["_createCell","require","CellRecycler","indexToCell","Map","recycledCells","reconcileRange","startIndex","endIndex","resolveCellType","nextActive","unusedIndices","Set","keys","index","delete","cell","get","push","type","recycledIdx","findIndex","c","splice","createCell","set","exports"],"sourceRoot":"../../../src","sources":["cell/CellRecycler.ts"],"mappings":";;;;;;AACA,IAAAA,WAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMC,YAAY,CAAC;EACxB;AACF;AACA;EACmBC,WAAW,GAAG,IAAIC,GAAG,CAAe,CAAC;;EAEtD;AACF;AACA;EACmBC,aAAa,GAAW,EAAE;;EAE3C;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEC,cAAcA,CACZC,UAAkB,EAClBC,QAAgB,EAChBC,eAA0C,EACzB;IACjB,MAAMC,UAAkB,GAAG,EAAE;;IAE7B;IACA,MAAMC,aAAa,GAAG,IAAIC,GAAG,CAAC,IAAI,CAACT,WAAW,CAACU,IAAI,CAAC,CAAC,CAAC;IAEtD,KAAK,IAAIC,KAAK,GAAGP,UAAU,EAAEO,KAAK,IAAIN,QAAQ,EAAEM,KAAK,EAAE,EAAE;MACvDH,aAAa,CAACI,MAAM,CAACD,KAAK,CAAC;MAE3B,IAAIE,IAAI,GAAG,IAAI,CAACb,WAAW,CAACc,GAAG,CAACH,KAAK,CAAC;MACtC,IAAIE,IAAI,EAAE;QACR;QACAN,UAAU,CAACQ,IAAI,CAACF,IAAI,CAAC;QACrB;MACF;MAEA,MAAMG,IAAI,GAAGV,eAAe,CAACK,KAAK,CAAC;;MAEnC;MACA,MAAMM,WAAW,GAAG,IAAI,CAACf,aAAa,CAACgB,SAAS,CAC9CC,CAAC,IAAIA,CAAC,CAACH,IAAI,KAAKA,IAClB,CAAC;MAED,IAAIC,WAAW,KAAK,CAAC,CAAC,EAAE;QACtBJ,IAAI,GAAG,IAAI,CAACX,aAAa,CAACkB,MAAM,CAACH,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE;MACtD,CAAC,MAAM;QACLJ,IAAI,GAAG,IAAAQ,sBAAU,EAACL,IAAI,CAAC;MACzB;MAEAH,IAAI,CAACF,KAAK,GAAGA,KAAK;MAClB,IAAI,CAACX,WAAW,CAACsB,GAAG,CAACX,KAAK,EAAEE,IAAI,CAAC;MACjCN,UAAU,CAACQ,IAAI,CAACF,IAAI,CAAC;IACvB;;IAEA;IACA,KAAK,MAAMF,KAAK,IAAIH,aAAa,EAAE;MACjC,MAAMK,IAAI,GAAG,IAAI,CAACb,WAAW,CAACc,GAAG,CAACH,KAAK,CAAE;MACzC,IAAI,CAACX,WAAW,CAACY,MAAM,CAACD,KAAK,CAAC;MAC9B,IAAI,CAACT,aAAa,CAACa,IAAI,CAACF,IAAI,CAAC;IAC/B;IAEA,OAAON,UAAU;EACnB;AACF;AAACgB,OAAA,CAAAxB,YAAA,GAAAA,YAAA","ignoreList":[]}

package/lib/commonjs/cell/createCell.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createCell = createCell;
+let nextCellId = 0;
+
+/**
+ * Creates a new physical cell with a stable identity.
+ * The key is generated ONCE and never changes.
+ */
+function createCell(type) {
+  return {
+    key: `cell-${nextCellId++}`,
+    // stable physical identity
+    type,
+    index: -1 // assigned by recycler
+  };
+}
+//# sourceMappingURL=createCell.js.map

package/lib/commonjs/cell/createCell.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["nextCellId","createCell","type","key","index"],"sourceRoot":"../../../src","sources":["cell/createCell.ts"],"mappings":";;;;;;AAEA,IAAIA,UAAU,GAAG,CAAC;;AAElB;AACA;AACA;AACA;AACO,SAASC,UAAUA,CAACC,IAAY,EAAQ;EAC7C,OAAO;IACLC,GAAG,EAAE,QAAQH,UAAU,EAAE,EAAE;IAAE;IAC7BE,IAAI;IACJE,KAAK,EAAE,CAAC,CAAC,CAAmB;EAC9B,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/cell/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "CellRecycler", {
+  enumerable: true,
+  get: function () {
+    return _CellRecycler.CellRecycler;
+  }
+});
+Object.defineProperty(exports, "createCell", {
+  enumerable: true,
+  get: function () {
+    return _createCell.createCell;
+  }
+});
+var _CellRecycler = require("./CellRecycler");
+var _createCell = require("./createCell");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/cell/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_CellRecycler","require","_createCell"],"sourceRoot":"../../../src","sources":["cell/index.ts"],"mappings":";;;;;;;;;;;;;;;;;AAGA,IAAAA,aAAA,GAAAC,OAAA;AACA,IAAAC,WAAA,GAAAD,OAAA","ignoreList":[]}

package/lib/commonjs/getVisibleIndices.js.map

@@ -1 +1 @@
-{"version":3,"names":["getVisibleRange","layouts","metrics","bufferPx","length","height","startY","Math","max","offsetY","endY","low","high","first","mid","rect","y","visible","i","push"],"sourceRoot":"../../src","sources":["getVisibleIndices.ts"],"mappings":";;;;;;AAGA;AACA;AACA;AACA;AACO,SAASA,eAAeA,CAC7BC,OAAmC,EACnCC,OAAsB,EACtBC,QAAgB,EACG;EACnB,IACEF,OAAO,CAACG,MAAM,KAAK,CAAC,IACpBF,OAAO,CAACG,MAAM,IAAI,CAAC,EACnB;IACA,OAAO,EAAE;EACX;EAEA,MAAMC,MAAM,GAAGC,IAAI,CAACC,GAAG,CACrB,CAAC,EACDN,OAAO,CAACO,OAAO,GAAGN,QACpB,CAAC;EAED,MAAMO,IAAI,GACRR,OAAO,CAACO,OAAO,GAAGP,OAAO,CAACG,MAAM,GAAGF,QAAQ;EAE7C,IAAIQ,GAAG,GAAG,CAAC;EACX,IAAIC,IAAI,GAAGX,OAAO,CAACG,MAAM,GAAG,CAAC;EAC7B,IAAIS,KAAK,GAAGZ,OAAO,CAACG,MAAM;EAE1B,OAAOO,GAAG,IAAIC,IAAI,EAAE;IAClB,MAAME,GAAG,GAAIH,GAAG,GAAGC,IAAI,IAAK,CAAC;IAC7B,MAAMG,IAAI,GAAGd,OAAO,CAACa,GAAG,CAAE;IAE1B,IAAIC,IAAI,CAACC,CAAC,GAAGD,IAAI,CAACV,MAAM,IAAIC,MAAM,EAAE;MAClCO,KAAK,GAAGC,GAAG;MACXF,IAAI,GAAGE,GAAG,GAAG,CAAC;IAChB,CAAC,MAAM;MACLH,GAAG,GAAGG,GAAG,GAAG,CAAC;IACf;EACF;EAEA,MAAMG,OAAiB,GAAG,EAAE;EAE5B,KAAK,IAAIC,CAAC,GAAGL,KAAK,EAAEK,CAAC,GAAGjB,OAAO,CAACG,MAAM,EAAEc,CAAC,EAAE,EAAE;IAC3C,MAAMH,IAAI,GAAGd,OAAO,CAACiB,CAAC,CAAE;IACxB,IAAIH,IAAI,CAACC,CAAC,GAAGN,IAAI,EAAE;IACnBO,OAAO,CAACE,IAAI,CAACD,CAAC,CAAC;EACjB;EAEA,OAAOD,OAAO;AAChB","ignoreList":[]}
+{"version":3,"names":["getVisibleRange","layouts","metrics","bufferPx","length","height","startY","Math","max","offsetY","endY","low","high","first","mid","rect","y","visible","i","push"],"sourceRoot":"../../src","sources":["getVisibleIndices.ts"],"mappings":";;;;;;AAKA;AACA;AACA;AACA;AACO,SAASA,eAAeA,CAC7BC,OAA8B,EAC9BC,OAAsB,EACtBC,QAAgB,EACG;EACnB,IACEF,OAAO,CAACG,MAAM,KAAK,CAAC,IACpBF,OAAO,CAACG,MAAM,IAAI,CAAC,EACnB;IACA,OAAO,EAAE;EACX;EAEA,MAAMC,MAAM,GAAGC,IAAI,CAACC,GAAG,CACrB,CAAC,EACDN,OAAO,CAACO,OAAO,GAAGN,QACpB,CAAC;EAED,MAAMO,IAAI,GACRR,OAAO,CAACO,OAAO,GAAGP,OAAO,CAACG,MAAM,GAAGF,QAAQ;EAE7C,IAAIQ,GAAG,GAAG,CAAC;EACX,IAAIC,IAAI,GAAGX,OAAO,CAACG,MAAM,GAAG,CAAC;EAC7B,IAAIS,KAAK,GAAGZ,OAAO,CAACG,MAAM;EAE1B,OAAOO,GAAG,IAAIC,IAAI,EAAE;IAClB,MAAME,GAAG,GAAIH,GAAG,GAAGC,IAAI,IAAK,CAAC;IAC7B,MAAMG,IAAI,GAAGd,OAAO,CAACa,GAAG,CAAE;IAE1B,IAAIC,IAAI,CAACC,CAAC,GAAGD,IAAI,CAACV,MAAM,IAAIC,MAAM,EAAE;MAClCO,KAAK,GAAGC,GAAG;MACXF,IAAI,GAAGE,GAAG,GAAG,CAAC;IAChB,CAAC,MAAM;MACLH,GAAG,GAAGG,GAAG,GAAG,CAAC;IACf;EACF;EAEA,MAAMG,OAAiB,GAAG,EAAE;EAE5B,KAAK,IAAIC,CAAC,GAAGL,KAAK,EAAEK,CAAC,GAAGjB,OAAO,CAACG,MAAM,EAAEc,CAAC,EAAE,EAAE;IAC3C,MAAMH,IAAI,GAAGd,OAAO,CAACiB,CAAC,CAAE;IACxB,IAAIH,IAAI,CAACC,CAAC,GAAGN,IAAI,EAAE;IACnBO,OAAO,CAACE,IAAI,CAACD,CAAC,CAAC;EACjB;EAEA,OAAOD,OAAO;AAChB","ignoreList":[]}

package/lib/commonjs/hooks/usePersistentCallback.js

@@ -0,0 +1,36 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePersistentCallback = usePersistentCallback;
+var _react = require("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
+ */
+function usePersistentCallback(fn) {
+  /**
+   * Holds the latest implementation.
+   * Updating this does NOT trigger re-renders.
+   */
+  const fnRef = (0, _react.useRef)(fn);
+  fnRef.current = fn;
+
+  /**
+   * Stable wrapper that forwards calls
+   * to the latest implementation.
+   */
+  return (0, _react.useCallback)((...args) => fnRef.current(...args), []);
+}
+//# sourceMappingURL=usePersistentCallback.js.map

package/lib/commonjs/hooks/usePersistentCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","usePersistentCallback","fn","fnRef","useRef","current","useCallback","args"],"sourceRoot":"../../../src","sources":["hooks/usePersistentCallback.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,qBAAqBA,CAEnCC,EAAK,EAAK;EAEV;AACF;AACA;AACA;EACE,MAAMC,KAAK,GAAG,IAAAC,aAAM,EAACF,EAAE,CAAC;EACxBC,KAAK,CAACE,OAAO,GAAGH,EAAE;;EAElB;AACF;AACA;AACA;EACE,OAAO,IAAAI,kBAAW,EACf,CAAC,GAAGC,IAAa,KAChBJ,KAAK,CAACE,OAAO,CAAC,GAAGE,IAAI,CAAC,EACxB,EACF,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/index.js

@@ -9,5 +9,5 @@ Object.defineProperty(exports, "RecyclerList", {
     return _RecyclerList.RecyclerList;
   }
 });
-var _RecyclerList = require("./RecyclerList");
+var _RecyclerList = require("./recycler/RecyclerList");
 //# sourceMappingURL=index.js.map

package/lib/commonjs/layout/MutableLinearLayout.js

@@ -4,61 +4,100 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.MutableLinearLayout = void 0;
+var _layoutDefaults = require("./constants/layoutDefaults");
 /**
- * INTERNAL mutable layout record.
- * This is intentionally mutable and never exposed publicly.
- */
-
-/**
- * Mutable linear layout store.
- * FlashList-style incremental relayout.
+ * Mutable, deterministic linear layout engine.
+ *
+ * Responsibilities:
+ * - Compute absolute item geometry
+ * - Own layout truth (no React, no scroll state)
+ * - Guarantee monotonic ordering along the main axis
+ *
+ * Cross-platform equivalents:
+ * - Flutter: RenderSliver / SliverList
+ * - Android: LinearLayoutManager
+ * - iOS: UICollectionViewFlowLayout (linear)
  */
 class MutableLinearLayout {
-  constructor(initialHeights, width) {
-    this.layouts = [];
-    let y = 0;
-    for (const height of initialHeights) {
-      this.layouts.push({
+  /** Absolute item layouts in index order */
+  layouts = [];
+
+  /** Total scrollable size along main axis */
+  contentSize = 0;
+  constructor(axis) {
+    this.isVertical = axis === 'vertical';
+  }
+
+  /**
+   * Computes layout synchronously from input.
+   *
+   * This method is intentionally parameter-object based
+   * to allow future extension without breaking API.
+   *
+   * Invariants:
+   * - Layouts are monotonic along main axis
+   * - No gaps except explicit spacing
+   * - Deterministic for identical inputs
+   */
+  compute(input) {
+    const {
+      crossAxisSize,
+      itemMainAxisSizes,
+      padding,
+      itemSpacing = _layoutDefaults.DEFAULT_ITEM_SPACING
+    } = input;
+    const itemCount = itemMainAxisSizes.length;
+    const layouts = new Array(itemCount);
+    let cursor = padding.start;
+    for (let i = 0; i < itemCount; i++) {
+      const mainAxisSize = itemMainAxisSizes[i];
+      layouts[i] = this.isVertical ? {
         x: 0,
-        y,
-        width,
-        height
-      });
-      y += height;
+        y: cursor,
+        width: crossAxisSize,
+        height: mainAxisSize
+      } : {
+        x: cursor,
+        y: 0,
+        width: mainAxisSize,
+        height: crossAxisSize
+      };
+      cursor += mainAxisSize;
+
+      // Space BETWEEN items, not after the last
+      if (i < itemCount - 1) {
+        cursor += itemSpacing;
+      }
     }
-    this.totalHeight = y;
+    this.layouts = layouts;
+    this.contentSize = cursor + padding.end;
   }
 
   /**
-   * Read-only snapshot for consumers.
-   * Returned type is immutable.
+   * Returns computed item layouts.
+   *
+   * Order is guaranteed monotonic along the main axis,
+   * which is required for binary-search-based windowing.
    */
   getLayouts() {
     return this.layouts;
   }
-  getContentHeight() {
-    return this.totalHeight;
-  }
 
   /**
-   * Update height of one item and shift following items.
-   * Returns true if layout changed.
+   * Returns total scrollable size along the main axis,
+   * including padding and inter-item spacing.
    */
-  updateItemHeight(index, newHeight) {
-    const layout = this.layouts[index];
-    if (!layout) return false;
-    const delta = newHeight - layout.height;
-    if (delta === 0) return false;
-
-    // Update this item
-    layout.height = newHeight;
+  getContentSize() {
+    return this.contentSize;
+  }
 
-    // Shift all items after this index
-    for (let i = index + 1; i < this.layouts.length; i++) {
-      this.layouts[i].y += delta;
-    }
-    this.totalHeight += delta;
-    return true;
+  /**
+   * Clears internal layout state.
+   * Call on severe invalidation or teardown.
+   */
+  reset() {
+    this.layouts = [];
+    this.contentSize = 0;
   }
 }
 exports.MutableLinearLayout = MutableLinearLayout;

package/lib/commonjs/layout/MutableLinearLayout.js.map

@@ -1 +1 @@
-{"version":3,"names":["MutableLinearLayout","constructor","initialHeights","width","layouts","y","height","push","x","totalHeight","getLayouts","getContentHeight","updateItemHeight","index","newHeight","layout","delta","i","length","exports"],"sourceRoot":"../../../src","sources":["layout/MutableLinearLayout.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACO,MAAMA,mBAAmB,CAAC;EAI/BC,WAAWA,CACTC,cAAiC,EACjCC,KAAa,EACb;IACA,IAAI,CAACC,OAAO,GAAG,EAAE;IACjB,IAAIC,CAAC,GAAG,CAAC;IAET,KAAK,MAAMC,MAAM,IAAIJ,cAAc,EAAE;MACnC,IAAI,CAACE,OAAO,CAACG,IAAI,CAAC;QAChBC,CAAC,EAAE,CAAC;QACJH,CAAC;QACDF,KAAK;QACLG;MACF,CAAC,CAAC;MACFD,CAAC,IAAIC,MAAM;IACb;IAEA,IAAI,CAACG,WAAW,GAAGJ,CAAC;EACtB;;EAEA;AACF;AACA;AACA;EACEK,UAAUA,CAAA,EAA+B;IACvC,OAAO,IAAI,CAACN,OAAO;EACrB;EAEAO,gBAAgBA,CAAA,EAAW;IACzB,OAAO,IAAI,CAACF,WAAW;EACzB;;EAEA;AACF;AACA;AACA;EACEG,gBAAgBA,CACdC,KAAa,EACbC,SAAiB,EACR;IACT,MAAMC,MAAM,GAAG,IAAI,CAACX,OAAO,CAACS,KAAK,CAAC;IAClC,IAAI,CAACE,MAAM,EAAE,OAAO,KAAK;IAEzB,MAAMC,KAAK,GAAGF,SAAS,GAAGC,MAAM,CAACT,MAAM;IACvC,IAAIU,KAAK,KAAK,CAAC,EAAE,OAAO,KAAK;;IAE7B;IACAD,MAAM,CAACT,MAAM,GAAGQ,SAAS;;IAEzB;IACA,KAAK,IAAIG,CAAC,GAAGJ,KAAK,GAAG,CAAC,EAAEI,CAAC,GAAG,IAAI,CAACb,OAAO,CAACc,MAAM,EAAED,CAAC,EAAE,EAAE;MACpD,IAAI,CAACb,OAAO,CAACa,CAAC,CAAC,CAAEZ,CAAC,IAAIW,KAAK;IAC7B;IAEA,IAAI,CAACP,WAAW,IAAIO,KAAK;IACzB,OAAO,IAAI;EACb;AACF;AAACG,OAAA,CAAAnB,mBAAA,GAAAA,mBAAA","ignoreList":[]}
+{"version":3,"names":["_layoutDefaults","require","MutableLinearLayout","layouts","contentSize","constructor","axis","isVertical","compute","input","crossAxisSize","itemMainAxisSizes","padding","itemSpacing","DEFAULT_ITEM_SPACING","itemCount","length","Array","cursor","start","i","mainAxisSize","x","y","width","height","end","getLayouts","getContentSize","reset","exports"],"sourceRoot":"../../../src","sources":["layout/MutableLinearLayout.ts"],"mappings":";;;;;;AAIA,IAAAA,eAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,mBAAmB,CAAC;EAG/B;EACQC,OAAO,GAAiB,EAAE;;EAElC;EACQC,WAAW,GAAG,CAAC;EAEvBC,WAAWA,CAACC,IAAU,EAAE;IACtB,IAAI,CAACC,UAAU,GAAGD,IAAI,KAAK,UAAU;EACvC;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEE,OAAOA,CAACC,KAAwB,EAAQ;IACtC,MAAM;MACJC,aAAa;MACbC,iBAAiB;MACjBC,OAAO;MACPC,WAAW,GAAGC;IAChB,CAAC,GAAGL,KAAK;IAET,MAAMM,SAAS,GAAGJ,iBAAiB,CAACK,MAAM;IAC1C,MAAMb,OAAqB,GAAG,IAAIc,KAAK,CAACF,SAAS,CAAC;IAElD,IAAIG,MAAM,GAAGN,OAAO,CAACO,KAAK;IAE1B,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGL,SAAS,EAAEK,CAAC,EAAE,EAAE;MAClC,MAAMC,YAAY,GAAGV,iBAAiB,CAACS,CAAC,CAAE;MAE1CjB,OAAO,CAACiB,CAAC,CAAC,GAAG,IAAI,CAACb,UAAU,GACxB;QACEe,CAAC,EAAE,CAAC;QACJC,CAAC,EAAEL,MAAM;QACTM,KAAK,EAAEd,aAAa;QACpBe,MAAM,EAAEJ;MACV,CAAC,GACD;QACEC,CAAC,EAAEJ,MAAM;QACTK,CAAC,EAAE,CAAC;QACJC,KAAK,EAAEH,YAAY;QACnBI,MAAM,EAAEf;MACV,CAAC;MAELQ,MAAM,IAAIG,YAAY;;MAEtB;MACA,IAAID,CAAC,GAAGL,SAAS,GAAG,CAAC,EAAE;QACrBG,MAAM,IAAIL,WAAW;MACvB;IACF;IAEA,IAAI,CAACV,OAAO,GAAGA,OAAO;IACtB,IAAI,CAACC,WAAW,GAAGc,MAAM,GAAGN,OAAO,CAACc,GAAG;EACzC;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEC,UAAUA,CAAA,EAA0B;IAClC,OAAO,IAAI,CAACxB,OAAO;EACrB;;EAEA;AACF;AACA;AACA;EACEyB,cAAcA,CAAA,EAAW;IACvB,OAAO,IAAI,CAACxB,WAAW;EACzB;;EAEA;AACF;AACA;AACA;EACEyB,KAAKA,CAAA,EAAS;IACZ,IAAI,CAAC1B,OAAO,GAAG,EAAE;IACjB,IAAI,CAACC,WAAW,GAAG,CAAC;EACtB;AACF;AAAC0B,OAAA,CAAA5B,mBAAA,GAAAA,mBAAA","ignoreList":[]}

package/lib/commonjs/layout/constants/layoutDefaults.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DEFAULT_ITEM_SPACING = void 0;
+/**
+ * Default spacing between items along the main axis.
+ *
+ * This value is used by layout engines when no explicit
+ * itemSpacing is provided.
+ *
+ * Mirrors:
+ * - Android RecyclerView ItemDecoration (typical 8–16dp)
+ * - iOS UICollectionViewFlowLayout minimumLineSpacing
+ * - Flutter SliverList spacing conventions
+ */
+const DEFAULT_ITEM_SPACING = exports.DEFAULT_ITEM_SPACING = 12;
+//# sourceMappingURL=layoutDefaults.js.map

package/lib/commonjs/layout/constants/layoutDefaults.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_ITEM_SPACING","exports"],"sourceRoot":"../../../../src","sources":["layout/constants/layoutDefaults.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,oBAAoB,GAAAC,OAAA,CAAAD,oBAAA,GAAG,EAAE","ignoreList":[]}

package/lib/commonjs/layout/index.js

@@ -1,20 +1,2 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "EstimatedLayoutProvider", {
-  enumerable: true,
-  get: function () {
-    return _EstimatedLayoutProvider.EstimatedLayoutProvider;
-  }
-});
-Object.defineProperty(exports, "computeLayouts", {
-  enumerable: true,
-  get: function () {
-    return _LayoutEngine.computeLayouts;
-  }
-});
-var _EstimatedLayoutProvider = require("./EstimatedLayoutProvider");
-var _LayoutEngine = require("./LayoutEngine");
 //# sourceMappingURL=index.js.map

package/lib/commonjs/layout/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_EstimatedLayoutProvider","require","_LayoutEngine"],"sourceRoot":"../../../src","sources":["layout/index.ts"],"mappings":";;;;;;;;;;;;;;;;;AAEA,IAAAA,wBAAA,GAAAC,OAAA;AACA,IAAAC,aAAA,GAAAD,OAAA","ignoreList":[]}
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["layout/index.ts"],"mappings":"","ignoreList":[]}

package/lib/commonjs/recycler/CellPool.js

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CellPool = void 0;
+class CellPool {
+  pools = new Map();
+  maxPerType = new Map();
+
+  /** ✅ NEW: check if a type is registered */
+  hasType(type) {
+    return this.pools.has(type);
+  }
+  registerType(type, maxCount) {
+    if (this.maxPerType.has(type)) return;
+    this.maxPerType.set(type, maxCount);
+    this.pools.set(type, []);
+  }
+  acquire(type) {
+    const bucket = this.pools.get(type);
+    if (!bucket || bucket.length === 0) return null;
+    return bucket.pop();
+  }
+  release(cell) {
+    const {
+      type
+    } = cell;
+    const bucket = this.pools.get(type);
+    const max = this.maxPerType.get(type);
+    if (!bucket || max === undefined) return;
+    cell.index = -1;
+    if (bucket.length >= max) return;
+    bucket.push(cell);
+  }
+  clear() {
+    for (const bucket of this.pools.values()) {
+      bucket.length = 0;
+    }
+  }
+  getPoolSize(type) {
+    return this.pools.get(type)?.length ?? 0;
+  }
+}
+exports.CellPool = CellPool;
+//# sourceMappingURL=CellPool.js.map

package/lib/commonjs/recycler/CellPool.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CellPool","pools","Map","maxPerType","hasType","type","has","registerType","maxCount","set","acquire","bucket","get","length","pop","release","cell","max","undefined","index","push","clear","values","getPoolSize","exports"],"sourceRoot":"../../../src","sources":["recycler/CellPool.ts"],"mappings":";;;;;;AAGO,MAAMA,QAAQ,CAAC;EACHC,KAAK,GAAG,IAAIC,GAAG,CAAmC,CAAC;EACnDC,UAAU,GAAG,IAAID,GAAG,CAAmB,CAAC;;EAEzD;EACAE,OAAOA,CAACC,IAAc,EAAW;IAC/B,OAAO,IAAI,CAACJ,KAAK,CAACK,GAAG,CAACD,IAAI,CAAC;EAC7B;EAEAE,YAAYA,CAACF,IAAc,EAAEG,QAAgB,EAAQ;IACnD,IAAI,IAAI,CAACL,UAAU,CAACG,GAAG,CAACD,IAAI,CAAC,EAAE;IAC/B,IAAI,CAACF,UAAU,CAACM,GAAG,CAACJ,IAAI,EAAEG,QAAQ,CAAC;IACnC,IAAI,CAACP,KAAK,CAACQ,GAAG,CAACJ,IAAI,EAAE,EAAE,CAAC;EAC1B;EAEAK,OAAOA,CAACL,IAAc,EAA+B;IACnD,MAAMM,MAAM,GAAG,IAAI,CAACV,KAAK,CAACW,GAAG,CAACP,IAAI,CAAC;IACnC,IAAI,CAACM,MAAM,IAAIA,MAAM,CAACE,MAAM,KAAK,CAAC,EAAE,OAAO,IAAI;IAC/C,OAAOF,MAAM,CAACG,GAAG,CAAC,CAAC;EACrB;EAEAC,OAAOA,CAACC,IAA0B,EAAQ;IACxC,MAAM;MAAEX;IAAK,CAAC,GAAGW,IAAI;IACrB,MAAML,MAAM,GAAG,IAAI,CAACV,KAAK,CAACW,GAAG,CAACP,IAAI,CAAC;IACnC,MAAMY,GAAG,GAAG,IAAI,CAACd,UAAU,CAACS,GAAG,CAACP,IAAI,CAAC;IAErC,IAAI,CAACM,MAAM,IAAIM,GAAG,KAAKC,SAAS,EAAE;IAElCF,IAAI,CAACG,KAAK,GAAG,CAAC,CAAC;IAEf,IAAIR,MAAM,CAACE,MAAM,IAAII,GAAG,EAAE;IAC1BN,MAAM,CAACS,IAAI,CAACJ,IAAI,CAAC;EACnB;EAEAK,KAAKA,CAAA,EAAS;IACZ,KAAK,MAAMV,MAAM,IAAI,IAAI,CAACV,KAAK,CAACqB,MAAM,CAAC,CAAC,EAAE;MACxCX,MAAM,CAACE,MAAM,GAAG,CAAC;IACnB;EACF;EAEAU,WAAWA,CAAClB,IAAc,EAAU;IAClC,OAAO,IAAI,CAACJ,KAAK,CAACW,GAAG,CAACP,IAAI,CAAC,EAAEQ,MAAM,IAAI,CAAC;EAC1C;AACF;AAACW,OAAA,CAAAxB,QAAA,GAAAA,QAAA","ignoreList":[]}