mtrl-addons 0.2.1 → 0.2.2

package/src/core/viewport/features/collection.ts

@@ -7,6 +7,7 @@
 
 import type { ViewportContext, ViewportComponent } from "../types";
 import { VIEWPORT_CONSTANTS } from "../constants";
+import { wrapDestroy } from "./utils";
 
 export interface CollectionConfig {
   collection?: any; // Collection adapter
@@ -18,6 +19,9 @@ export interface CollectionConfig {
   enableRequestQueue?: boolean;
   maxQueueSize?: number;
   loadOnDragEnd?: boolean; // Enable loading when drag ends (safety measure)
+  initialScrollIndex?: number; // Initial scroll position (0-based index)
+  selectId?: string | number; // ID of item to select after initial load completes
+  autoLoad?: boolean; // Whether to automatically load data on initialization (default: true)
 }
 
 export interface CollectionComponent {
@@ -25,7 +29,7 @@ export interface CollectionComponent {
     loadRange: (offset: number, limit: number) => Promise<any[]>;
     loadMissingRanges: (
       range: { start: number; end: number },
-      caller?: string
+      caller?: string,
     ) => Promise<void>;
     getLoadedRanges: () => Set<number>;
     getPendingRanges: () => Set<number>;
@@ -44,7 +48,7 @@ export interface CollectionComponent {
  */
 export function withCollection(config: CollectionConfig = {}) {
   return <T extends ViewportContext & ViewportComponent>(
-    component: T
+    component: T,
   ): T & CollectionComponent => {
     const {
       collection,
@@ -57,9 +61,21 @@ export function withCollection(config: CollectionConfig = {}) {
       enableRequestQueue = VIEWPORT_CONSTANTS.REQUEST_QUEUE.ENABLED,
       maxQueueSize = VIEWPORT_CONSTANTS.REQUEST_QUEUE.MAX_QUEUE_SIZE,
       loadOnDragEnd = true, // Default to true as safety measure
+      initialScrollIndex = 0, // Start from beginning by default
+      selectId, // ID of item to select after initial load
+      autoLoad = true, // Auto-load initial data by default
     } = config;
 
-    // console.log("[Viewport Collection] Initialized with strategy:", strategy);
+    // Track if we've completed the initial load for initialScrollIndex
+    // This prevents the viewport:range-changed listener from loading page 1
+    let hasCompletedInitialPositionLoad = false;
+    const hasInitialScrollIndex = initialScrollIndex > 0;
+
+    // console.log("[Viewport Collection] Initialized with config:", {
+    //   strategy,
+    //   rangeSize,
+    //   initialScrollIndex,
+    // });
 
     // Loading manager state
     interface QueuedRequest {
@@ -78,9 +94,75 @@ export function withCollection(config: CollectionConfig = {}) {
     let cancelledLoads = 0;
     let isDragging = false; // Track drag state
 
+    // Cache eviction configuration
+    const MAX_CACHED_ITEMS = 500; // Maximum items to keep in memory
+    const EVICTION_BUFFER = 100; // Extra items to keep around visible range
+
+    // Memory diagnostics
+    const logMemoryStats = (caller: string) => {
+      const itemCount = items.filter(Boolean).length;
+      const loadedRangeCount = loadedRanges.size;
+      const pendingRangeCount = pendingRanges.size;
+      const abortControllerCount = abortControllers.size;
+    };
+
+    /**
+     * Evict items far from the current visible range to prevent memory bloat
+     * Keeps items within EVICTION_BUFFER of the visible range
+     */
+    const evictDistantItems = (visibleStart: number, visibleEnd: number) => {
+      const itemCount = items.filter(Boolean).length;
+
+      // Only evict if we have more than MAX_CACHED_ITEMS
+      if (itemCount <= MAX_CACHED_ITEMS) {
+        return;
+      }
+
+      const keepStart = Math.max(0, visibleStart - EVICTION_BUFFER);
+      const keepEnd = visibleEnd + EVICTION_BUFFER;
+
+      let evictedCount = 0;
+      const rangesToRemove: number[] = [];
+
+      // Find items to evict
+      for (let i = 0; i < items.length; i++) {
+        if (items[i] !== undefined && (i < keepStart || i > keepEnd)) {
+          delete items[i];
+          evictedCount++;
+        }
+      }
+
+      // Update loadedRanges to reflect evicted data
+      loadedRanges.forEach((rangeId) => {
+        const rangeStart = rangeId * rangeSize;
+        const rangeEnd = rangeStart + rangeSize - 1;
+
+        // If this range is completely outside the keep window, remove it
+        if (rangeEnd < keepStart || rangeStart > keepEnd) {
+          rangesToRemove.push(rangeId);
+        }
+      });
+
+      rangesToRemove.forEach((rangeId) => {
+        loadedRanges.delete(rangeId);
+      });
+
+      if (evictedCount > 0) {
+        // Emit event for rendering to also clean up
+        component.emit?.("collection:items-evicted", {
+          keepStart,
+          keepEnd,
+          evictedCount,
+        });
+      }
+    };
+
     const activeLoadRanges = new Set<string>();
     let loadRequestQueue: QueuedRequest[] = [];
 
+    // AbortController map for cancelling in-flight requests
+    const abortControllers = new Map<number, AbortController>();
+
     // State
     let items: any[] = [];
     let totalItems = 0;
@@ -152,12 +234,6 @@ export function withCollection(config: CollectionConfig = {}) {
       activeLoadCount++;
       activeLoadRanges.add(getRangeKey(request.range));
 
-      // console.log(
-      //   `[LoadingManager] Executing load for range ${request.range.start}-${
-      //     request.range.end
-      //   } (velocity: ${currentVelocity.toFixed(2)})`
-      // );
-
       // Call the actual loadMissingRanges function
       loadMissingRangesInternal(request.range)
         .then(() => {
@@ -188,7 +264,7 @@ export function withCollection(config: CollectionConfig = {}) {
      */
     const loadRange = async (offset: number, limit: number): Promise<any[]> => {
       // console.log(
-      //   `[Collection] loadRange called: offset=${offset}, limit=${limit}`
+      //   `[Collection] loadRange called: offset=${offset}, limit=${limit}`,
       // );
 
       if (!collection) {
@@ -197,12 +273,12 @@ export function withCollection(config: CollectionConfig = {}) {
       }
 
       const rangeId = getRangeId(offset, limit);
-      //console.log(`[Collection] Range ID: ${rangeId}`);
+      // console.log(`[Collection] Range ID: ${rangeId}`);
 
       // Check if already loaded
       if (loadedRanges.has(rangeId)) {
         // console.log(
-        //   `[Collection] Range ${rangeId} already loaded, returning cached data`
+        //   `[Collection] Range ${rangeId} already loaded, returning cached data`,
         // );
         return items.slice(offset, offset + limit);
       }
@@ -213,7 +289,7 @@ export function withCollection(config: CollectionConfig = {}) {
         const existingRequest = activeRequests.get(rangeId);
         if (existingRequest) {
           // console.log(
-          //   `[Collection] Returning existing request for range ${rangeId}`
+          //   `[Collection] Returning existing request for range ${rangeId}`,
           // );
           return existingRequest;
         }
@@ -221,10 +297,14 @@ export function withCollection(config: CollectionConfig = {}) {
 
       // Mark as pending
       // console.log(
-      //   `[Collection] Marking range ${rangeId} as pending and loading...`
+      //   `[Collection] Marking range ${rangeId} as pending and loading...`,
       // );
       pendingRanges.add(rangeId);
 
+      // Create AbortController for this request
+      const abortController = new AbortController();
+      abortControllers.set(rangeId, abortController);
+
       // Create request promise
       const requestPromise = (async () => {
         try {
@@ -245,12 +325,12 @@ export function withCollection(config: CollectionConfig = {}) {
                 console.warn(
                   `[Collection] Cannot load page ${page} without cursor for page ${
                     page - 1
-                  }`
+                  }`,
                 );
                 throw new Error(
                   `Sequential loading required - missing cursor for page ${
                     page - 1
-                  }`
+                  }`,
                 );
               }
               params = { cursor: prevPageCursor, limit };
@@ -267,7 +347,11 @@ export function withCollection(config: CollectionConfig = {}) {
           //   JSON.stringify(params)
           // );
 
-          const response = await collection.read(params);
+          // Pass abort signal to the adapter if it supports it
+          const response = await collection.read({
+            ...params,
+            signal: abortController.signal,
+          });
 
           // Extract items and total
           const rawItems = response.data || response.items || response;
@@ -280,23 +364,27 @@ export function withCollection(config: CollectionConfig = {}) {
             cursorMap.set(page, responseCursor);
             pageToOffsetMap.set(page, offset);
             highestLoadedPage = Math.max(highestLoadedPage, page);
-            console.log(
-              `[Collection] Stored cursor for page ${page}: ${responseCursor}`
-            );
+            // console.log(
+            //   `[Collection] Stored cursor for page ${page}: ${responseCursor}`,
+            // );
           }
 
           // Check if we've reached the end
           if (strategy === "cursor" && meta.hasNext === false) {
             hasReachedEnd = true;
-            console.log(
-              `[Collection] Reached end of cursor pagination at page ${page}`
-            );
+            // console.log(
+            //   `[Collection] Reached end of cursor pagination at page ${page}`,
+            // );
           }
 
           // Update discovered total if provided
+          // console.log(
+          //   `[Collection] meta.total: ${meta.total}, discoveredTotal before: ${discoveredTotal}`,
+          // );
           if (meta.total !== undefined) {
             discoveredTotal = meta.total;
           }
+          // console.log(`[Collection] discoveredTotal after: ${discoveredTotal}`);
 
           // Transform items
           const transformedItems = transformItems(rawItems);
@@ -307,12 +395,27 @@ export function withCollection(config: CollectionConfig = {}) {
           });
 
           // For cursor strategy, calculate dynamic total based on loaded data
-          let newTotal = discoveredTotal || totalItems;
+          // Use nullish coalescing (??) instead of || to handle discoveredTotal = 0 correctly
+          let newTotal = discoveredTotal ?? totalItems;
+
+          // CRITICAL FIX: When API returns 0 items on page 1 (offset 0), the list is empty.
+          // We must set totalItems to 0 regardless of meta.total being undefined.
+          // This handles the case where count=false is sent but the list is actually empty.
+          if (offset === 0 && transformedItems.length === 0) {
+            // console.log(
+            //   `[Collection] Empty result on page 1 - forcing totalItems to 0`,
+            // );
+            newTotal = 0;
+            discoveredTotal = 0;
+          }
+          // console.log(
+          //   `[Collection] newTotal initial: ${newTotal}, totalItems: ${totalItems}, strategy: ${strategy}`,
+          // );
 
           if (strategy === "cursor") {
             // Calculate total based on loaded items + margin
             const loadedItemsCount = items.filter(
-              (item) => item !== undefined
+              (item) => item !== undefined,
             ).length;
             const marginItems = hasReachedEnd
               ? 0
@@ -325,28 +428,33 @@ export function withCollection(config: CollectionConfig = {}) {
             // Dynamic total: loaded items + margin (unless we've reached the end)
             newTotal = Math.max(
               loadedItemsCount + marginItems,
-              minVirtualItems
+              minVirtualItems,
             );
 
-            console.log(
-              `[Collection] Cursor mode virtual size: loaded=${loadedItemsCount}, margin=${marginItems}, total=${newTotal}, hasReachedEnd=${hasReachedEnd}`
-            );
+            // console.log(
+            //   `[Collection] Cursor mode virtual size: loaded=${loadedItemsCount}, margin=${marginItems}, total=${newTotal}, hasReachedEnd=${hasReachedEnd}`,
+            // );
 
             // Update total if it has grown
             if (newTotal > totalItems) {
-              console.log(
-                `[Collection] Updating cursor virtual size from ${totalItems} to ${newTotal}`
-              );
+              // console.log(
+              //   `[Collection] Updating cursor virtual size from ${totalItems} to ${newTotal}`,
+              // );
               totalItems = newTotal;
               setTotalItems(newTotal);
             }
           } else {
             // For other strategies, use discovered total or current total
-            newTotal = discoveredTotal || totalItems;
+            // Use nullish coalescing (??) instead of || to handle discoveredTotal = 0 correctly
+            newTotal = discoveredTotal ?? totalItems;
           }
 
           // Update state
+          // console.log(
+          //   `[Collection] Before state update: newTotal=${newTotal}, totalItems=${totalItems}, will update: ${newTotal !== totalItems}`,
+          // );
           if (newTotal !== totalItems) {
+            // console.log(`[Collection] Calling setTotalItems(${newTotal})`);
             totalItems = newTotal;
             setTotalItems(newTotal);
           }
@@ -363,7 +471,8 @@ export function withCollection(config: CollectionConfig = {}) {
           // Update viewport state
           const viewportState = (component.viewport as any).state;
           if (viewportState) {
-            viewportState.totalItems = newTotal || items.length;
+            // Use nullish coalescing (??) instead of || to handle newTotal = 0 correctly
+            viewportState.totalItems = newTotal ?? items.length;
           }
 
           // Mark as loaded
@@ -375,6 +484,11 @@ export function withCollection(config: CollectionConfig = {}) {
           //   `[Collection] Range ${rangeId} loaded successfully with ${transformedItems.length} items`
           // );
 
+          // Log memory stats periodically (every 5 loads)
+          if (completedLoads % 5 === 0) {
+            logMemoryStats(`load:${completedLoads}`);
+          }
+
           // Emit events
           component.emit?.("viewport:range-loaded", {
             offset,
@@ -399,8 +513,22 @@ export function withCollection(config: CollectionConfig = {}) {
 
           return transformedItems;
         } catch (error) {
-          // Handle error
+          // Handle AbortError and "Failed to fetch" (which can occur on abort) gracefully
+          const isAbortError =
+            (error as Error).name === "AbortError" ||
+            ((error as Error).message === "Failed to fetch" &&
+              abortController.signal.aborted);
+
+          if (isAbortError) {
+            pendingRanges.delete(rangeId);
+            cancelledLoads++;
+            // Don't throw, just return empty array
+            return [];
+          }
+
+          // Handle other errors
           pendingRanges.delete(rangeId);
+          failedLoads++;
 
           const attempts = (failedRanges.get(rangeId)?.attempts || 0) + 1;
           failedRanges.set(rangeId, {
@@ -420,6 +548,7 @@ export function withCollection(config: CollectionConfig = {}) {
           throw error;
         } finally {
           activeRequests.delete(rangeId);
+          abortControllers.delete(rangeId);
         }
       })();
 
@@ -436,6 +565,10 @@ export function withCollection(config: CollectionConfig = {}) {
     }): Promise<void> => {
       if (!collection) return;
 
+      // console.log(
+      //   `[Collection] loadMissingRangesInternal - range: ${start}-${end}, strategy: ${strategy}`,
+      // );
+
       // For cursor pagination, we need to load sequentially
       if (strategy === "cursor") {
         const startPage = Math.floor(range.start / rangeSize) + 1;
@@ -446,12 +579,12 @@ export function withCollection(config: CollectionConfig = {}) {
         const currentHighestPage = highestLoadedPage || 0;
         const limitedEndPage = Math.min(
           endPage,
-          currentHighestPage + maxPagesToLoad
+          currentHighestPage + maxPagesToLoad,
         );
 
-        console.log(
-          `[Collection] Cursor mode: need to load pages ${startPage} to ${endPage}, limited to ${limitedEndPage}`
-        );
+        // console.log(
+        //   `[Collection] Cursor mode: need to load pages ${startPage} to ${endPage}, limited to ${limitedEndPage}`,
+        // );
 
         // Check if we need to load pages sequentially
         for (let page = startPage; page <= limitedEndPage; page++) {
@@ -472,9 +605,9 @@ export function withCollection(config: CollectionConfig = {}) {
               for (let prevPage = 1; prevPage < page; prevPage++) {
                 const prevRangeId = prevPage - 1;
                 if (!loadedRanges.has(prevRangeId)) {
-                  console.log(
-                    `[Collection] Cannot load page ${page} - need to load page ${prevPage} first`
-                  );
+                  // console.log(
+                  //   `[Collection] Cannot load page ${page} - need to load page ${prevPage} first`,
+                  // );
                   canLoad = false;
 
                   // Try to load the missing page
@@ -484,7 +617,7 @@ export function withCollection(config: CollectionConfig = {}) {
                     } catch (error) {
                       console.error(
                         `[Collection] Failed to load prerequisite page ${prevPage}:`,
-                        error
+                        error,
                       );
                       return; // Stop trying to load further pages
                     }
@@ -508,9 +641,9 @@ export function withCollection(config: CollectionConfig = {}) {
         }
 
         if (endPage > limitedEndPage) {
-          console.log(
-            `[Collection] Stopped at page ${limitedEndPage} to prevent excessive loading (requested up to ${endPage})`
-          );
+          // console.log(
+          //   `[Collection] Stopped at page ${limitedEndPage} to prevent excessive loading (requested up to ${endPage})`,
+          // );
         }
 
         return;
@@ -521,6 +654,10 @@ export function withCollection(config: CollectionConfig = {}) {
       const startRange = Math.floor(range.start / rangeSize);
       const endRange = Math.floor(range.end / rangeSize);
 
+      // console.log(
+      //   `[Collection] page strategy - startRange: ${startRange}, endRange: ${endRange}, loadedRanges: [${Array.from(loadedRanges).join(", ")}]`,
+      // );
+
       // Collect ranges that need loading
       const rangesToLoad: number[] = [];
       for (let rangeId = startRange; rangeId <= endRange; rangeId++) {
@@ -529,7 +666,12 @@ export function withCollection(config: CollectionConfig = {}) {
         }
       }
 
+      // console.log(
+      //   `[Collection] rangesToLoad: [${rangesToLoad.join(", ")}], pendingRanges: [${Array.from(pendingRanges).join(", ")}]`,
+      // );
+
       if (rangesToLoad.length === 0) {
+        // console.log(`[Collection] No ranges to load - all loaded or pending`);
         // All ranges are already loaded or pending
         // Check if there are queued requests we should process
         if (
@@ -541,9 +683,13 @@ export function withCollection(config: CollectionConfig = {}) {
         return;
       }
 
+      // console.log(
+      //   `[Collection] Loading ${rangesToLoad.length} ranges: [${rangesToLoad.join(", ")}]`,
+      // );
+
       // Load ranges individually - no merging to avoid loading old ranges
       const promises = rangesToLoad.map((rangeId) =>
-        loadRange(rangeId * rangeSize, rangeSize)
+        loadRange(rangeId * rangeSize, rangeSize),
       );
       await Promise.allSettled(promises);
     };
@@ -556,14 +702,21 @@ export function withCollection(config: CollectionConfig = {}) {
         start: number;
         end: number;
       },
-      caller?: string
+      caller?: string,
     ): Promise<void> => {
       return new Promise((resolve, reject) => {
         const rangeKey = getRangeKey(range);
-        // Removed noisy log
+
+        // console.log(
+        //   `[Collection] loadMissingRanges called - range: ${range.start}-${range.end}, caller: ${caller}`,
+        // );
+        // console.log(
+        //   `[Collection] loadedRanges: [${Array.from(loadedRanges).join(", ")}]`,
+        // );
 
         // Check if already loading
         if (activeLoadRanges.has(rangeKey)) {
+          // console.log(`[Collection] Range already being loaded, skipping`);
           // Range already being loaded
           resolve();
           return;
@@ -621,7 +774,7 @@ export function withCollection(config: CollectionConfig = {}) {
           if (loadRequestQueue.length >= maxQueueSize) {
             const removed = loadRequestQueue.splice(
               0,
-              loadRequestQueue.length - maxQueueSize
+              loadRequestQueue.length - maxQueueSize,
             );
             removed.forEach((r) => {
               cancelledLoads++;
@@ -660,7 +813,11 @@ export function withCollection(config: CollectionConfig = {}) {
     // Hook into viewport initialization
     const originalInitialize = component.viewport.initialize;
     component.viewport.initialize = () => {
-      originalInitialize();
+      const result = originalInitialize();
+      // Skip if already initialized
+      if (result === false) {
+        return false;
+      }
 
       // Set initial total if provided
       if (component.totalItems) {
@@ -685,14 +842,6 @@ export function withCollection(config: CollectionConfig = {}) {
       component.on?.("viewport:range-changed", async (data: any) => {
         // Don't load during fast scrolling - loadMissingRanges will handle velocity check
 
-        // Skip initial load if we're dragging and velocity is low (drag just started)
-        // if (isDragging && currentVelocity < 0.5) {
-        //   console.log(
-        //     "[Collection] Skipping range-changed load during drag start"
-        //   );
-        //   return;
-        // }
-
         // Extract range from event data - virtual feature emits { range: { start, end }, scrollPosition }
         const range = data.range || data;
         const { start, end } = range;
@@ -701,18 +850,32 @@ export function withCollection(config: CollectionConfig = {}) {
         if (typeof start !== "number" || typeof end !== "number") {
           console.warn(
             "[Collection] Invalid range in viewport:range-changed event:",
-            data
+            data,
           );
           return;
         }
 
+        // Skip loading page 1 if we have an initialScrollIndex and haven't completed initial load yet
+        // This prevents the requestAnimationFrame in virtual.ts from triggering a page 1 load
+        // after we've already started loading the correct initial page
+        if (hasInitialScrollIndex && !hasCompletedInitialPositionLoad) {
+          const page1EndIndex = rangeSize - 1; // e.g., 29 for rangeSize=30
+          if (start === 0 && end <= page1EndIndex) {
+            // This is a request for page 1, skip it
+            return;
+          }
+        }
+
         // Load missing ranges if needed
         await loadMissingRanges({ start, end }, "viewport:range-changed");
 
+        // Evict distant items to prevent memory bloat
+        evictDistantItems(start, end);
+
         // For cursor mode, check if we need to update virtual size
         if (strategy === "cursor" && !hasReachedEnd) {
           const loadedItemsCount = items.filter(
-            (item) => item !== undefined
+            (item) => item !== undefined,
           ).length;
           const marginItems =
             rangeSize *
@@ -722,13 +885,13 @@ export function withCollection(config: CollectionConfig = {}) {
             VIEWPORT_CONSTANTS.PAGINATION.CURSOR_MIN_VIRTUAL_SIZE_MULTIPLIER;
           const dynamicTotal = Math.max(
             loadedItemsCount + marginItems,
-            minVirtualItems
+            minVirtualItems,
           );
 
           if (dynamicTotal !== totalItems) {
-            console.log(
-              `[Collection] Updating cursor virtual size from ${totalItems} to ${dynamicTotal}`
-            );
+            // console.log(
+            //   `[Collection] Updating cursor virtual size from ${totalItems} to ${dynamicTotal}`,
+            // );
             setTotalItems(dynamicTotal);
           }
         }
@@ -778,9 +941,9 @@ export function withCollection(config: CollectionConfig = {}) {
               requestStart <= visibleRange.end + buffer;
 
             if (!isRelevant) {
-              console.log(
-                `[Collection] Removing stale queued request: ${requestStart}-${requestEnd}`
-              );
+              // console.log(
+              //   `[Collection] Removing stale queued request: ${requestStart}-${requestEnd}`,
+              // );
               request.resolve(); // Resolve to avoid hanging promises
             }
             return isRelevant;
@@ -794,8 +957,99 @@ export function withCollection(config: CollectionConfig = {}) {
         processQueue();
       });
 
-      // Load initial data if collection is available
-      if (collection) {
+      // Listen for item removal - DON'T clear loadedRanges to prevent unnecessary reload
+      // The data is already shifted locally in api.ts and rendering.ts
+      // Reloading would cause race conditions and overwrite the correct totalItems
+      component.on?.("item:removed", (data: any) => {
+        // console.log(`[Collection] item:removed event - index: ${data.index}`);
+        // console.log(`[Collection] items.length: ${items.length}`);
+
+        // Update discoveredTotal to match the new count
+        // This prevents stale discoveredTotal from being used on next load
+        if (discoveredTotal !== null && discoveredTotal > 0) {
+          discoveredTotal = discoveredTotal - 1;
+          // console.log(
+          //   `[Collection] Updated discoveredTotal to: ${discoveredTotal}`,
+          // );
+        }
+
+        // NOTE: Do NOT decrement totalItems here!
+        // api.ts already calls setTotalItems() after emitting item:remove-request,
+        // which properly updates totalItems. Decrementing here would cause a double-decrement.
+
+        // DON'T clear loadedRanges - we want to keep using the local data
+        // The data has been shifted locally and is still valid
+        // Clearing would trigger a reload which causes race conditions
+        // console.log(
+        //   `[Collection] Keeping loadedRanges intact:`,
+        //   Array.from(loadedRanges),
+        // );
+      });
+
+      // Load initial data if collection is available and autoLoad is enabled
+      if (collection && autoLoad) {
+        // If we have an initial scroll index OR a selectId, load data for that position directly
+        // Don't use scrollToIndex() as it triggers animation/velocity tracking
+        // virtual.ts has already set the scroll position and calculated the visible range
+        if (initialScrollIndex > 0 || selectId !== undefined) {
+          // Get the visible range that was already calculated by virtual.ts
+          // We missed the initial viewport:range-changed event because our listener wasn't ready yet
+          const visibleRange = component.viewport?.getVisibleRange?.();
+
+          if (
+            visibleRange &&
+            (visibleRange.start > 0 || visibleRange.end > 0)
+          ) {
+            // Use the pre-calculated visible range from virtual.ts
+            loadMissingRanges(visibleRange, "initial-position")
+              .then(() => {
+                hasCompletedInitialPositionLoad = true;
+                // Emit event to select item after initial load if selectId is provided
+                if (selectId !== undefined) {
+                  component.emit?.("collection:initial-load-complete", {
+                    selectId,
+                    initialScrollIndex,
+                  });
+                }
+              })
+              .catch((error) => {
+                console.error(
+                  "[Collection] Failed to load initial position data:",
+                  error,
+                );
+                hasCompletedInitialPositionLoad = true; // Allow normal loading even on error
+              });
+          } else {
+            // Fallback: calculate range from initialScrollIndex
+            // This handles edge cases where visibleRange wasn't ready
+            const overscan = 2;
+            const estimatedVisibleCount = Math.ceil(600 / 50); // ~12 items
+            const start = Math.max(0, initialScrollIndex - overscan);
+            const end = initialScrollIndex + estimatedVisibleCount + overscan;
+
+            loadMissingRanges({ start, end }, "initial-position-fallback")
+              .then(() => {
+                hasCompletedInitialPositionLoad = true;
+                // Emit event to select item after initial load if selectId is provided
+                if (selectId !== undefined) {
+                  component.emit?.("collection:initial-load-complete", {
+                    selectId,
+                    initialScrollIndex,
+                  });
+                }
+              })
+              .catch((error) => {
+                console.error(
+                  "[Collection] Failed to load initial position data (fallback):",
+                  error,
+                );
+                hasCompletedInitialPositionLoad = true; // Allow normal loading even on error
+              });
+          }
+          return;
+        }
+
+        // No initial scroll index - load from beginning as normal
         loadRange(0, rangeSize)
           .then(() => {
             // console.log("[Collection] Initial data loaded");
@@ -804,6 +1058,8 @@ export function withCollection(config: CollectionConfig = {}) {
             console.error("[Collection] Failed to load initial data:", error);
           });
       }
+
+      return result;
     };
 
     // Add collection API to viewport
@@ -811,7 +1067,7 @@ export function withCollection(config: CollectionConfig = {}) {
       loadRange: (offset: number, limit: number) => loadRange(offset, limit),
       loadMissingRanges: (
         range: { start: number; end: number },
-        caller?: string
+        caller?: string,
       ) => loadMissingRanges(range, caller || "viewport.collection"),
       getLoadedRanges: () => loadedRanges,
       getPendingRanges: () => pendingRanges,
@@ -832,7 +1088,7 @@ export function withCollection(config: CollectionConfig = {}) {
       loadRange,
       loadMissingRanges: (
         range: { start: number; end: number },
-        caller?: string
+        caller?: string,
       ) => loadMissingRanges(range, caller || "component.collection"),
       getLoadingStats: () => ({
         pendingRequests: activeLoadCount,
@@ -843,6 +1099,9 @@ export function withCollection(config: CollectionConfig = {}) {
         canLoad: canLoad(),
         queuedRequests: loadRequestQueue.length,
       }),
+      // Total items management
+      getTotalItems: () => totalItems,
+      setTotalItems,
       // Cursor methods
       getCurrentCursor: () => currentCursor,
       getCursorForPage: (page: number) => cursorMap.get(page) || null,
@@ -851,21 +1110,62 @@ export function withCollection(config: CollectionConfig = {}) {
     // Also ensure component.items is updated
     component.items = items;
 
-    // Cleanup function
+    // Cleanup function - comprehensive memory cleanup
     const destroy = () => {
-      // Cancel pending requests
-      activeRequests.clear();
+      logMemoryStats("destroy:before");
+
+      // Abort all in-flight requests
+      abortControllers.forEach((controller) => {
+        try {
+          controller.abort();
+        } catch (e) {
+          // Ignore abort errors
+        }
+      });
+      abortControllers.clear();
+
+      // Clear all data structures
+      items.length = 0;
+      loadRequestQueue.length = 0;
+      loadedRanges.clear();
       pendingRanges.clear();
+      failedRanges.clear();
+      activeLoadRanges.clear();
+      activeRequests.clear();
+      cursorMap.clear();
+      pageToOffsetMap.clear();
+
+      // Reset state
+      totalItems = 0;
+      currentCursor = null;
+      highestLoadedPage = 0;
+      discoveredTotal = null;
+      hasReachedEnd = false;
+
+      // Clear component reference
+      if (component.items === items) {
+        component.items = [];
+      }
+
+      logMemoryStats("destroy:after");
     };
 
+    // Wire destroy into the component's destroy chain
+    wrapDestroy(component, destroy);
+
     // Return enhanced component
     return {
       ...component,
       collection: {
+        // Data access methods
+        items,
+        getItems: () => items,
+        getItem: (index: number) => items[index],
+        // Loading methods
         loadRange,
         loadMissingRanges: (
           range: { start: number; end: number },
-          caller?: string
+          caller?: string,
         ) => loadMissingRanges(range, caller || "return.collection"),
         getLoadedRanges: () => loadedRanges,
         getPendingRanges: () => pendingRanges,