mtrl-addons 0.1.1 → 0.2.1

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

@@ -0,0 +1,882 @@
+// src/core/viewport/features/collection.ts
+
+/**
+ * Collection Feature - Data management and range loading
+ * Handles collection integration, pagination, and data fetching
+ */
+
+import type { ViewportContext, ViewportComponent } from "../types";
+import { VIEWPORT_CONSTANTS } from "../constants";
+
+export interface CollectionConfig {
+  collection?: any; // Collection adapter
+  rangeSize?: number; // Default range size for loading
+  strategy?: "offset" | "page" | "cursor"; // Loading strategy
+  transform?: (item: any) => any; // Item transformation function
+  cancelLoadThreshold?: number; // Velocity threshold for cancelling loads
+  maxConcurrentRequests?: number;
+  enableRequestQueue?: boolean;
+  maxQueueSize?: number;
+  loadOnDragEnd?: boolean; // Enable loading when drag ends (safety measure)
+}
+
+export interface CollectionComponent {
+  collection: {
+    loadRange: (offset: number, limit: number) => Promise<any[]>;
+    loadMissingRanges: (
+      range: { start: number; end: number },
+      caller?: string
+    ) => Promise<void>;
+    getLoadedRanges: () => Set<number>;
+    getPendingRanges: () => Set<number>;
+    clearFailedRanges: () => void;
+    retryFailedRange: (rangeId: number) => Promise<any[]>;
+    setTotalItems: (total: number) => void;
+    getTotalItems: () => number;
+    // Cursor-specific methods
+    getCurrentCursor: () => string | null;
+    getCursorForPage: (page: number) => string | null;
+  };
+}
+
+/**
+ * Adds collection functionality to viewport component
+ */
+export function withCollection(config: CollectionConfig = {}) {
+  return <T extends ViewportContext & ViewportComponent>(
+    component: T
+  ): T & CollectionComponent => {
+    const {
+      collection,
+      rangeSize = VIEWPORT_CONSTANTS.LOADING.DEFAULT_RANGE_SIZE,
+      strategy = "offset",
+      transform,
+      cancelLoadThreshold = VIEWPORT_CONSTANTS.LOADING.CANCEL_THRESHOLD,
+      maxConcurrentRequests = VIEWPORT_CONSTANTS.LOADING
+        .MAX_CONCURRENT_REQUESTS,
+      enableRequestQueue = VIEWPORT_CONSTANTS.REQUEST_QUEUE.ENABLED,
+      maxQueueSize = VIEWPORT_CONSTANTS.REQUEST_QUEUE.MAX_QUEUE_SIZE,
+      loadOnDragEnd = true, // Default to true as safety measure
+    } = config;
+
+    // console.log("[Viewport Collection] Initialized with strategy:", strategy);
+
+    // Loading manager state
+    interface QueuedRequest {
+      range: { start: number; end: number };
+      priority: "high" | "normal" | "low";
+      timestamp: number;
+      resolve: () => void;
+      reject: (error: any) => void;
+    }
+
+    // State tracking
+    let currentVelocity = 0;
+    let activeLoadCount = 0;
+    let completedLoads = 0;
+    let failedLoads = 0;
+    let cancelledLoads = 0;
+    let isDragging = false; // Track drag state
+
+    const activeLoadRanges = new Set<string>();
+    let loadRequestQueue: QueuedRequest[] = [];
+
+    // State
+    let items: any[] = [];
+    let totalItems = 0;
+    let loadedRanges = new Set<number>();
+    let pendingRanges = new Set<number>();
+    let failedRanges = new Map<
+      number,
+      {
+        attempts: number;
+        lastError: Error;
+        timestamp: number;
+      }
+    >();
+    let activeRequests = new Map<number, Promise<any[]>>();
+
+    // Cursor pagination state
+    let currentCursor: string | null = null;
+    let cursorMap = new Map<number, string>(); // Map page number to cursor
+    let pageToOffsetMap = new Map<number, number>(); // Map page to actual offset
+    let highestLoadedPage = 0;
+    let discoveredTotal: number | null = null; // Track discovered total from API
+    let hasReachedEnd = false; // Track if we've reached the end of data
+
+    // Share items array with component
+    component.items = items;
+
+    /**
+     * Get a unique ID for a range based on offset and the base range size
+     */
+    const getRangeId = (offset: number, limit: number): number => {
+      // Always use the base rangeSize for consistent IDs
+      // This ensures merged ranges can be tracked properly
+      return Math.floor(offset / rangeSize);
+    };
+
+    // Loading manager helpers
+    const getRangeKey = (range: { start: number; end: number }): string => {
+      return `${range.start}-${range.end}`;
+    };
+
+    const canLoad = (): boolean => {
+      return currentVelocity <= cancelLoadThreshold;
+    };
+
+    const processQueue = () => {
+      if (!enableRequestQueue || loadRequestQueue.length === 0) return;
+
+      // Sort queue by priority and timestamp
+      loadRequestQueue.sort((a, b) => {
+        const priorityOrder = { high: 0, normal: 1, low: 2 };
+        const priorityDiff =
+          priorityOrder[a.priority] - priorityOrder[b.priority];
+        return priorityDiff !== 0 ? priorityDiff : a.timestamp - b.timestamp;
+      });
+
+      // Process requests up to capacity
+      while (
+        loadRequestQueue.length > 0 &&
+        activeLoadCount < maxConcurrentRequests
+      ) {
+        const request = loadRequestQueue.shift();
+        if (request) {
+          executeQueuedLoad(request);
+        }
+      }
+    };
+
+    const executeQueuedLoad = (request: QueuedRequest) => {
+      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(() => {
+          request.resolve();
+          completedLoads++;
+        })
+        .catch((error: Error) => {
+          request.reject(error);
+          failedLoads++;
+        })
+        .finally(() => {
+          activeLoadCount--;
+          activeLoadRanges.delete(getRangeKey(request.range));
+          processQueue();
+        });
+    };
+
+    /**
+     * Transform items if transform function provided
+     */
+    const transformItems = (rawItems: any[]): any[] => {
+      if (!transform) return rawItems;
+      return rawItems.map(transform);
+    };
+
+    /**
+     * Load a range of data
+     */
+    const loadRange = async (offset: number, limit: number): Promise<any[]> => {
+      // console.log(
+      //   `[Collection] loadRange called: offset=${offset}, limit=${limit}`
+      // );
+
+      if (!collection) {
+        console.warn("[Collection] No collection adapter configured");
+        return [];
+      }
+
+      const rangeId = getRangeId(offset, limit);
+      //console.log(`[Collection] Range ID: ${rangeId}`);
+
+      // Check if already loaded
+      if (loadedRanges.has(rangeId)) {
+        // console.log(
+        //   `[Collection] Range ${rangeId} already loaded, returning cached data`
+        // );
+        return items.slice(offset, offset + limit);
+      }
+
+      // Check if already pending
+      if (pendingRanges.has(rangeId)) {
+        // console.log(`[Collection] Range ${rangeId} already pending`);
+        const existingRequest = activeRequests.get(rangeId);
+        if (existingRequest) {
+          // console.log(
+          //   `[Collection] Returning existing request for range ${rangeId}`
+          // );
+          return existingRequest;
+        }
+      }
+
+      // Mark as pending
+      // console.log(
+      //   `[Collection] Marking range ${rangeId} as pending and loading...`
+      // );
+      pendingRanges.add(rangeId);
+
+      // Create request promise
+      const requestPromise = (async () => {
+        try {
+          // Call collection adapter with appropriate parameters
+          const page = Math.floor(offset / limit) + 1;
+          let params: any;
+
+          if (strategy === "cursor") {
+            // For cursor pagination
+            if (page === 1) {
+              // First page - no cursor
+              params = { limit };
+            } else {
+              // Check if we have cursor for previous page
+              const prevPageCursor = cursorMap.get(page - 1);
+              if (!prevPageCursor) {
+                // Can't load this page without previous cursor
+                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 };
+            }
+          } else if (strategy === "page") {
+            params = { page, limit };
+          } else {
+            // offset strategy
+            params = { offset, limit };
+          }
+
+          // console.log(
+          //   `[Viewport Collection] Loading range offset=${offset}, limit=${limit}, strategy=${strategy}, calculated page=${page}, params:`,
+          //   JSON.stringify(params)
+          // );
+
+          const response = await collection.read(params);
+
+          // Extract items and total
+          const rawItems = response.data || response.items || response;
+          const meta = response.meta || {};
+
+          // For cursor pagination, track the cursor (check both cursor and nextCursor)
+          const responseCursor = meta.cursor || meta.nextCursor;
+          if (strategy === "cursor" && responseCursor) {
+            currentCursor = responseCursor;
+            cursorMap.set(page, responseCursor);
+            pageToOffsetMap.set(page, offset);
+            highestLoadedPage = Math.max(highestLoadedPage, page);
+            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}`
+            );
+          }
+
+          // Update discovered total if provided
+          if (meta.total !== undefined) {
+            discoveredTotal = meta.total;
+          }
+
+          // Transform items
+          const transformedItems = transformItems(rawItems);
+
+          // Add items to array
+          transformedItems.forEach((item, index) => {
+            items[offset + index] = item;
+          });
+
+          // For cursor strategy, calculate dynamic total based on loaded data
+          let newTotal = discoveredTotal || totalItems;
+
+          if (strategy === "cursor") {
+            // Calculate total based on loaded items + margin
+            const loadedItemsCount = items.filter(
+              (item) => item !== undefined
+            ).length;
+            const marginItems = hasReachedEnd
+              ? 0
+              : rangeSize *
+                VIEWPORT_CONSTANTS.PAGINATION.CURSOR_SCROLL_MARGIN_MULTIPLIER;
+            const minVirtualItems =
+              rangeSize *
+              VIEWPORT_CONSTANTS.PAGINATION.CURSOR_MIN_VIRTUAL_SIZE_MULTIPLIER;
+
+            // Dynamic total: loaded items + margin (unless we've reached the end)
+            newTotal = Math.max(
+              loadedItemsCount + marginItems,
+              minVirtualItems
+            );
+
+            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}`
+              );
+              totalItems = newTotal;
+              setTotalItems(newTotal);
+            }
+          } else {
+            // For other strategies, use discovered total or current total
+            newTotal = discoveredTotal || totalItems;
+          }
+
+          // Update state
+          if (newTotal !== totalItems) {
+            totalItems = newTotal;
+            setTotalItems(newTotal);
+          }
+
+          // Update component items reference
+          component.items = items;
+
+          // Emit items changed event
+          component.emit?.("viewport:items-changed", {
+            totalItems: newTotal,
+            loadedCount: items.filter((item) => item !== undefined).length,
+          });
+
+          // Update viewport state
+          const viewportState = (component.viewport as any).state;
+          if (viewportState) {
+            viewportState.totalItems = newTotal || items.length;
+          }
+
+          // Mark as loaded
+          loadedRanges.add(rangeId);
+          pendingRanges.delete(rangeId);
+          failedRanges.delete(rangeId);
+
+          // console.log(
+          //   `[Collection] Range ${rangeId} loaded successfully with ${transformedItems.length} items`
+          // );
+
+          // Emit events
+          component.emit?.("viewport:range-loaded", {
+            offset,
+            limit,
+            items: transformedItems,
+            total: newTotal,
+          });
+
+          // Emit collection loaded event with more details
+          component.emit?.("collection:range-loaded", {
+            offset,
+            limit,
+            items: transformedItems,
+            total: newTotal,
+            rangeId,
+            itemsInMemory: items.filter((item) => item !== undefined).length,
+            cursor: strategy === "cursor" ? currentCursor : undefined,
+          });
+
+          // Trigger viewport update
+          component.viewport?.updateViewport?.();
+
+          return transformedItems;
+        } catch (error) {
+          // Handle error
+          pendingRanges.delete(rangeId);
+
+          const attempts = (failedRanges.get(rangeId)?.attempts || 0) + 1;
+          failedRanges.set(rangeId, {
+            attempts,
+            lastError: error as Error,
+            timestamp: Date.now(),
+          });
+
+          // Emit error event
+          component.emit?.("viewport:range-error", {
+            offset,
+            limit,
+            error,
+            attempts,
+          });
+
+          throw error;
+        } finally {
+          activeRequests.delete(rangeId);
+        }
+      })();
+
+      activeRequests.set(rangeId, requestPromise);
+      return requestPromise;
+    };
+
+    /**
+     * Load missing ranges from collection
+     */
+    const loadMissingRangesInternal = async (range: {
+      start: number;
+      end: number;
+    }): Promise<void> => {
+      if (!collection) return;
+
+      // For cursor pagination, we need to load sequentially
+      if (strategy === "cursor") {
+        const startPage = Math.floor(range.start / rangeSize) + 1;
+        const endPage = Math.floor(range.end / rangeSize) + 1;
+
+        // Limit how many pages we'll load at once
+        const maxPagesToLoad = 10;
+        const currentHighestPage = highestLoadedPage || 0;
+        const limitedEndPage = Math.min(
+          endPage,
+          currentHighestPage + maxPagesToLoad
+        );
+
+        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++) {
+          const rangeId = page - 1; // Convert to 0-based rangeId
+          const offset = rangeId * rangeSize;
+
+          // Skip if already being loaded
+          if (pendingRanges.has(rangeId)) {
+            // Range already being loaded
+            return;
+          }
+
+          if (!loadedRanges.has(rangeId) && !pendingRanges.has(rangeId)) {
+            // For cursor pagination, we must load sequentially
+            // Check if we have all previous pages loaded
+            if (page > 1) {
+              let canLoad = true;
+              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`
+                  );
+                  canLoad = false;
+
+                  // Try to load the missing page
+                  if (!pendingRanges.has(prevRangeId)) {
+                    try {
+                      await loadRange(prevRangeId * rangeSize, rangeSize);
+                    } catch (error) {
+                      console.error(
+                        `[Collection] Failed to load prerequisite page ${prevPage}:`,
+                        error
+                      );
+                      return; // Stop trying to load further pages
+                    }
+                  }
+                  break;
+                }
+              }
+
+              if (!canLoad) {
+                continue; // Skip this page for now
+              }
+            }
+
+            try {
+              await loadRange(offset, rangeSize);
+            } catch (error) {
+              console.error(`[Collection] Failed to load page ${page}:`, error);
+              break; // Stop sequential loading on error
+            }
+          }
+        }
+
+        if (endPage > limitedEndPage) {
+          console.log(
+            `[Collection] Stopped at page ${limitedEndPage} to prevent excessive loading (requested up to ${endPage})`
+          );
+        }
+
+        return;
+      }
+
+      // Original logic for offset/page strategies
+      // Calculate range boundaries
+      const startRange = Math.floor(range.start / rangeSize);
+      const endRange = Math.floor(range.end / rangeSize);
+
+      // Collect ranges that need loading
+      const rangesToLoad: number[] = [];
+      for (let rangeId = startRange; rangeId <= endRange; rangeId++) {
+        if (!loadedRanges.has(rangeId) && !pendingRanges.has(rangeId)) {
+          rangesToLoad.push(rangeId);
+        }
+      }
+
+      if (rangesToLoad.length === 0) {
+        // All ranges are already loaded or pending
+        // Check if there are queued requests we should process
+        if (
+          loadRequestQueue.length > 0 &&
+          activeLoadCount < maxConcurrentRequests
+        ) {
+          processQueue();
+        }
+        return;
+      }
+
+      // Load ranges individually - no merging to avoid loading old ranges
+      const promises = rangesToLoad.map((rangeId) =>
+        loadRange(rangeId * rangeSize, rangeSize)
+      );
+      await Promise.allSettled(promises);
+    };
+
+    /**
+     * Velocity-aware wrapper for loadMissingRanges
+     */
+    const loadMissingRanges = (
+      range: {
+        start: number;
+        end: number;
+      },
+      caller?: string
+    ): Promise<void> => {
+      return new Promise((resolve, reject) => {
+        const rangeKey = getRangeKey(range);
+        // Removed noisy log
+
+        // Check if already loading
+        if (activeLoadRanges.has(rangeKey)) {
+          // Range already being loaded
+          resolve();
+          return;
+        }
+
+        // Skip if dragging with low velocity (but not if we're idle)
+        if (isDragging && currentVelocity < 0.5 && currentVelocity > 0) {
+          // console.log(
+          //   "[Collection] Load skipped - actively dragging with low velocity"
+          // );
+          cancelledLoads++;
+          resolve();
+          return;
+        }
+
+        // Check velocity - if too high, cancel the request entirely
+        if (!canLoad()) {
+          // console.log(
+          //   `[Collection] Load cancelled - velocity ${currentVelocity.toFixed(
+          //     2
+          //   )} exceeds threshold ${cancelLoadThreshold}`
+          // );
+          cancelledLoads++;
+          resolve();
+          return;
+        }
+
+        // Check capacity
+        if (activeLoadCount < maxConcurrentRequests) {
+          // Execute immediately
+          executeQueuedLoad({
+            range,
+            priority: "normal",
+            timestamp: Date.now(),
+            resolve,
+            reject,
+          });
+        } else if (
+          enableRequestQueue &&
+          loadRequestQueue.length < maxQueueSize
+        ) {
+          // Queue the request
+          loadRequestQueue.push({
+            range,
+            priority: "normal",
+            timestamp: Date.now(),
+            resolve,
+            reject,
+          });
+          // console.log(
+          //   `[LoadingManager] Queued request (at capacity), queue size: ${loadRequestQueue.length}`
+          // );
+        } else {
+          // Queue overflow - resolve to avoid errors
+          if (loadRequestQueue.length >= maxQueueSize) {
+            const removed = loadRequestQueue.splice(
+              0,
+              loadRequestQueue.length - maxQueueSize
+            );
+            removed.forEach((r) => {
+              cancelledLoads++;
+              r.resolve();
+            });
+          }
+          resolve();
+        }
+      });
+    };
+
+    /**
+     * Retry a failed range
+     */
+    const retryFailedRange = async (rangeId: number): Promise<any[]> => {
+      failedRanges.delete(rangeId);
+      const offset = rangeId * rangeSize;
+      return loadRange(offset, rangeSize);
+    };
+
+    /**
+     * Set total items count
+     */
+    const setTotalItems = (total: number): void => {
+      totalItems = total;
+
+      // Update viewport state's total items
+      const viewportState = (component.viewport as any).state;
+      if (viewportState) {
+        viewportState.totalItems = total;
+      }
+
+      component.emit?.("viewport:total-items-changed", { total });
+    };
+
+    // Hook into viewport initialization
+    const originalInitialize = component.viewport.initialize;
+    component.viewport.initialize = () => {
+      originalInitialize();
+
+      // Set initial total if provided
+      if (component.totalItems) {
+        totalItems = component.totalItems;
+      }
+
+      // Listen for drag events
+      component.on?.("viewport:drag-start", () => {
+        isDragging = true;
+      });
+
+      component.on?.("viewport:drag-end", () => {
+        isDragging = false;
+        // Process any queued requests after drag ends (safety measure)
+        // This ensures placeholders are replaced even if idle detection fails
+        if (loadOnDragEnd) {
+          processQueue();
+        }
+      });
+
+      // Listen for range changes
+      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;
+
+        // Validate range before loading
+        if (typeof start !== "number" || typeof end !== "number") {
+          console.warn(
+            "[Collection] Invalid range in viewport:range-changed event:",
+            data
+          );
+          return;
+        }
+
+        // Load missing ranges if needed
+        await loadMissingRanges({ start, end }, "viewport:range-changed");
+
+        // For cursor mode, check if we need to update virtual size
+        if (strategy === "cursor" && !hasReachedEnd) {
+          const loadedItemsCount = items.filter(
+            (item) => item !== undefined
+          ).length;
+          const marginItems =
+            rangeSize *
+            VIEWPORT_CONSTANTS.PAGINATION.CURSOR_SCROLL_MARGIN_MULTIPLIER;
+          const minVirtualItems =
+            rangeSize *
+            VIEWPORT_CONSTANTS.PAGINATION.CURSOR_MIN_VIRTUAL_SIZE_MULTIPLIER;
+          const dynamicTotal = Math.max(
+            loadedItemsCount + marginItems,
+            minVirtualItems
+          );
+
+          if (dynamicTotal !== totalItems) {
+            console.log(
+              `[Collection] Updating cursor virtual size from ${totalItems} to ${dynamicTotal}`
+            );
+            setTotalItems(dynamicTotal);
+          }
+        }
+      });
+
+      // Listen for velocity changes
+      component.on?.("viewport:velocity-changed", (data: any) => {
+        const previousVelocity = currentVelocity;
+        currentVelocity = Math.abs(data.velocity || 0);
+
+        // When velocity drops below threshold, process queue
+        if (
+          previousVelocity > cancelLoadThreshold &&
+          currentVelocity <= cancelLoadThreshold
+        ) {
+          processQueue();
+        }
+      });
+
+      // Listen for idle state to process queue
+      component.on?.("viewport:idle", async (data: any) => {
+        //console.log("[Collection] Idle event received, velocity=0");
+        currentVelocity = 0;
+
+        // Reset dragging state on idle since user has stopped moving
+        if (isDragging) {
+          // console.log("[Collection] Resetting drag state on idle");
+          isDragging = false;
+        }
+
+        // Get current visible range from viewport
+        const viewportState = (component.viewport as any).state;
+        const visibleRange = viewportState?.visibleRange;
+
+        if (visibleRange) {
+          // console.log(
+          //   `[Collection] Loading visible range on idle: ${visibleRange.start}-${visibleRange.end}`
+          // );
+
+          // Clear stale requests from queue that are far from current visible range
+          const buffer = rangeSize * 2; // Allow some buffer
+          loadRequestQueue = loadRequestQueue.filter((request) => {
+            const requestEnd = request.range.end;
+            const requestStart = request.range.start;
+            const isRelevant =
+              requestEnd >= visibleRange.start - buffer &&
+              requestStart <= visibleRange.end + buffer;
+
+            if (!isRelevant) {
+              console.log(
+                `[Collection] Removing stale queued request: ${requestStart}-${requestEnd}`
+              );
+              request.resolve(); // Resolve to avoid hanging promises
+            }
+            return isRelevant;
+          });
+
+          // Load the current visible range if needed
+          await loadMissingRanges(visibleRange, "viewport:idle");
+        }
+
+        // Also process any queued requests
+        processQueue();
+      });
+
+      // Load initial data if collection is available
+      if (collection) {
+        loadRange(0, rangeSize)
+          .then(() => {
+            // console.log("[Collection] Initial data loaded");
+          })
+          .catch((error) => {
+            console.error("[Collection] Failed to load initial data:", error);
+          });
+      }
+    };
+
+    // Add collection API to viewport
+    component.viewport.collection = {
+      loadRange: (offset: number, limit: number) => loadRange(offset, limit),
+      loadMissingRanges: (
+        range: { start: number; end: number },
+        caller?: string
+      ) => loadMissingRanges(range, caller || "viewport.collection"),
+      getLoadedRanges: () => loadedRanges,
+      getPendingRanges: () => pendingRanges,
+      clearFailedRanges: () => failedRanges.clear(),
+      retryFailedRange,
+      setTotalItems,
+      getTotalItems: () => totalItems,
+      // Cursor-specific methods
+      getCurrentCursor: () => currentCursor,
+      getCursorForPage: (page: number) => cursorMap.get(page) || null,
+    };
+
+    // Add collection data access with direct assignment
+    (component as any).collection = {
+      items,
+      getItems: () => items,
+      getItem: (index: number) => items[index],
+      loadRange,
+      loadMissingRanges: (
+        range: { start: number; end: number },
+        caller?: string
+      ) => loadMissingRanges(range, caller || "component.collection"),
+      getLoadingStats: () => ({
+        pendingRequests: activeLoadCount,
+        completedRequests: completedLoads,
+        failedRequests: failedLoads,
+        cancelledRequests: cancelledLoads,
+        currentVelocity,
+        canLoad: canLoad(),
+        queuedRequests: loadRequestQueue.length,
+      }),
+      // Cursor methods
+      getCurrentCursor: () => currentCursor,
+      getCursorForPage: (page: number) => cursorMap.get(page) || null,
+    };
+
+    // Also ensure component.items is updated
+    component.items = items;
+
+    // Cleanup function
+    const destroy = () => {
+      // Cancel pending requests
+      activeRequests.clear();
+      pendingRanges.clear();
+    };
+
+    // Return enhanced component
+    return {
+      ...component,
+      collection: {
+        loadRange,
+        loadMissingRanges: (
+          range: { start: number; end: number },
+          caller?: string
+        ) => loadMissingRanges(range, caller || "return.collection"),
+        getLoadedRanges: () => loadedRanges,
+        getPendingRanges: () => pendingRanges,
+        clearFailedRanges: () => failedRanges.clear(),
+        retryFailedRange,
+        setTotalItems,
+        getTotalItems: () => totalItems,
+        // Cursor-specific methods
+        getCurrentCursor: () => currentCursor,
+        getCursorForPage: (page: number) => cursorMap.get(page) || null,
+      },
+    };
+  };
+}