lazy-render-virtual-scroll 1.0.7 → 1.0.9

package/dist/cjs/index.js

@@ -745,6 +745,499 @@ class AdaptiveBufferCalculator {
     }
 }
 
+class PerformanceOptimizer {
+    constructor() {
+        this.frameBudget = 16; // Target for 60fps (16.67ms per frame)
+        this.lastFrameTime = 0;
+        this.animationFrameId = null;
+        this.isOptimizing = false;
+        // Frame rate limiter to prevent excessive updates
+        this.lastUpdate = 0;
+        this.minUpdateInterval = 16; // Minimum 16ms between updates (60fps)
+        // Batch updates to reduce DOM manipulations
+        this.updateQueue = [];
+        this.isProcessingQueue = false;
+        // Memory optimization
+        this.cleanupThreshold = 1000; // Clean up items beyond this threshold
+        this.gcInterval = null;
+        this.setupPerformanceMonitoring();
+    }
+    // Optimize rendering by limiting updates to frame budget
+    scheduleOptimizedUpdate(updateFn) {
+        const now = performance.now();
+        // Throttle updates based on frame rate
+        if (now - this.lastUpdate < this.minUpdateInterval) {
+            // Queue the update for later
+            this.updateQueue.push(updateFn);
+            if (!this.isProcessingQueue) {
+                this.processUpdateQueue();
+            }
+            return;
+        }
+        // Check if we have enough time in the current frame
+        if (this.getTimeRemaining() > 4) { // Leave 4ms buffer
+            updateFn();
+            this.lastUpdate = now;
+        }
+        else {
+            // Schedule for next frame
+            this.updateQueue.push(updateFn);
+            if (!this.isProcessingQueue) {
+                this.processUpdateQueue();
+            }
+        }
+    }
+    // Process queued updates efficiently
+    async processUpdateQueue() {
+        if (this.updateQueue.length === 0) {
+            this.isProcessingQueue = false;
+            return;
+        }
+        this.isProcessingQueue = true;
+        const currentTime = performance.now();
+        // Process as many updates as possible within frame budget
+        while (this.updateQueue.length > 0 && this.getTimeRemaining() > 2) {
+            const updateFn = this.updateQueue.shift();
+            if (updateFn) {
+                updateFn();
+            }
+        }
+        this.lastUpdate = currentTime;
+        if (this.updateQueue.length > 0) {
+            // Schedule remaining updates for next frame (only in browser environment)
+            if (typeof requestAnimationFrame !== 'undefined') {
+                requestAnimationFrame(() => this.processUpdateQueue());
+            }
+            else {
+                // In Node.js environment, use setTimeout as fallback
+                setTimeout(() => this.processUpdateQueue(), 0);
+            }
+        }
+        else {
+            this.isProcessingQueue = false;
+        }
+    }
+    // Get remaining time in current frame
+    getTimeRemaining() {
+        if (typeof performance === 'undefined' || !performance.now) {
+            return 16; // Fallback to 60fps
+        }
+        const currentTime = performance.now();
+        // Typically browsers target 10ms remaining time for smoothness
+        return Math.max(0, this.frameBudget - (currentTime - this.lastFrameTime));
+    }
+    // Memory optimization: cleanup off-screen items
+    optimizeMemory(cleanupFn, visibleRange) {
+        // Determine cleanup range (items far from visible range)
+        const cleanupStart = Math.max(0, visibleRange.end + this.cleanupThreshold);
+        const cleanupEnd = Math.max(0, visibleRange.start - this.cleanupThreshold);
+        if (cleanupStart > visibleRange.end) {
+            cleanupFn(visibleRange.end, cleanupStart);
+        }
+        if (cleanupEnd < visibleRange.start) {
+            cleanupFn(cleanupEnd, visibleRange.start);
+        }
+    }
+    // Enable GPU acceleration for smoother scrolling
+    enableGPUCssAcceleration(element) {
+        // Force hardware acceleration
+        element.style.willChange = 'transform';
+        element.style.transform = 'translateZ(0)';
+        element.style.backfaceVisibility = 'hidden';
+    }
+    // Disable GPU acceleration when not needed
+    disableGPUCssAcceleration(element) {
+        element.style.willChange = 'auto';
+        element.style.transform = '';
+        element.style.backfaceVisibility = '';
+    }
+    // Optimize for different device capabilities
+    getOptimizationProfile() {
+        // Simple profile detection based on common device characteristics
+        const userAgent = navigator.userAgent || navigator.vendor || window.opera;
+        // Detect low-end devices
+        if (this.isLowEndDevice(userAgent)) {
+            return {
+                frameRate: 30, // Lower target for low-end devices
+                batchSize: 5, // Smaller batches
+                bufferMultiplier: 0.5, // Smaller buffer
+                updateInterval: 32 // 30fps interval
+            };
+        }
+        // Default profile for capable devices
+        return {
+            frameRate: 60,
+            batchSize: 10,
+            bufferMultiplier: 1.0,
+            updateInterval: 16 // 60fps interval
+        };
+    }
+    isLowEndDevice(userAgent) {
+        // Simple heuristic for low-end devices
+        const lowEndPatterns = [
+            /Android.*Mobile/,
+            /iPhone.*OS [0-9]+_[0-9]+/,
+            /Opera Mini/,
+            /IEMobile/
+        ];
+        return lowEndPatterns.some(pattern => pattern.test(userAgent));
+    }
+    // Setup performance monitoring
+    setupPerformanceMonitoring() {
+        // Check if we're in a browser environment
+        if (typeof window === 'undefined' || typeof requestAnimationFrame === 'undefined') {
+            // In Node.js environment, skip browser-specific monitoring
+            return;
+        }
+        // Monitor frame rate
+        let frameCount = 0;
+        let lastTime = performance.now();
+        const monitorFrameRate = () => {
+            frameCount++;
+            const currentTime = performance.now();
+            if (currentTime - lastTime >= 1000) { // Every second
+                const fps = frameCount;
+                frameCount = 0;
+                lastTime = currentTime;
+                // Adjust optimization based on actual FPS
+                if (fps < 30) {
+                    this.frameBudget = 32; // Target 30fps
+                }
+                else if (fps < 50) {
+                    this.frameBudget = 20; // Target 50fps
+                }
+                else {
+                    this.frameBudget = 16; // Target 60fps
+                }
+            }
+            this.animationFrameId = requestAnimationFrame(monitorFrameRate);
+        };
+        this.animationFrameId = requestAnimationFrame(monitorFrameRate);
+        // Setup garbage collection monitoring
+        this.gcInterval = window.setInterval(() => {
+            if ('gc' in window) {
+                // @ts-ignore - gc is non-standard
+                window.gc();
+            }
+        }, 30000); // GC every 30 seconds
+    }
+    // Get performance insights
+    getPerformanceInsights() {
+        return {
+            frameRate: 60, // Would be calculated from monitoring
+            memoryUsage: this.getMemoryUsage(),
+            updateFrequency: 1000 / this.minUpdateInterval,
+            optimizationActive: this.isOptimizing
+        };
+    }
+    getMemoryUsage() {
+        var _a;
+        if ('memory' in performance) {
+            // @ts-ignore - memory property is non-standard
+            return ((_a = performance.memory) === null || _a === void 0 ? void 0 : _a.usedJSHeapSize) || null;
+        }
+        return null;
+    }
+    // Cleanup resources
+    cleanup() {
+        if (this.animationFrameId && typeof cancelAnimationFrame !== 'undefined') {
+            cancelAnimationFrame(this.animationFrameId);
+        }
+        if (this.gcInterval && typeof clearInterval !== 'undefined') {
+            clearInterval(this.gcInterval);
+        }
+        this.updateQueue = [];
+        this.isProcessingQueue = false;
+    }
+}
+
+class MemoryManager {
+    constructor(maxCacheSize = 1000) {
+        this.itemCache = new Map();
+        this.maxCacheSize = 1000; // Maximum items to keep in cache
+        this.cleanupThreshold = 500; // Start cleanup when cache exceeds this
+        this.visibleRange = { start: 0, end: 0 };
+        this.totalItems = 0;
+        this.maxCacheSize = maxCacheSize;
+    }
+    // Set visible range to optimize cache
+    setVisibleRange(range) {
+        this.visibleRange = range;
+    }
+    // Set total number of items
+    setTotalItems(total) {
+        this.totalItems = total;
+    }
+    // Get item from cache
+    get(key) {
+        return this.itemCache.get(key) || null;
+    }
+    // Set item in cache
+    set(key, value) {
+        this.itemCache.set(key, value);
+        // Clean up if cache is too large
+        if (this.itemCache.size > this.maxCacheSize) {
+            this.cleanupCache();
+        }
+    }
+    // Check if item exists in cache
+    has(key) {
+        return this.itemCache.has(key);
+    }
+    // Remove item from cache
+    delete(key) {
+        return this.itemCache.delete(key);
+    }
+    // Clear entire cache
+    clear() {
+        this.itemCache.clear();
+    }
+    // Clean up cache based on visibility and distance from visible range
+    cleanupCache() {
+        if (this.itemCache.size <= this.cleanupThreshold) {
+            return; // No need to clean up
+        }
+        const itemsToRemove = [];
+        // Find items that are far from visible range
+        for (const [key] of this.itemCache.entries()) {
+            const distanceFromVisible = this.getDistanceFromVisible(key);
+            // Remove items that are far from visible range
+            if (distanceFromVisible > 100) { // Arbitrary threshold
+                itemsToRemove.push(key);
+            }
+        }
+        // If we still have too many items, remove oldest accessed items
+        if (this.itemCache.size - itemsToRemove.length > this.cleanupThreshold) {
+            const sortedKeys = Array.from(this.itemCache.keys())
+                .sort((a, b) => a - b); // Sort by key (assuming they're indexes)
+            // Remove items that are furthest from visible range
+            for (const key of sortedKeys) {
+                if (this.itemCache.size <= this.cleanupThreshold)
+                    break;
+                const distance = this.getDistanceFromVisible(key);
+                if (distance > 50) { // Remove items beyond 50 units from visible
+                    itemsToRemove.push(key);
+                }
+            }
+        }
+        // Actually remove items
+        for (const key of itemsToRemove) {
+            this.itemCache.delete(key);
+        }
+    }
+    // Calculate distance from visible range
+    getDistanceFromVisible(index) {
+        if (index >= this.visibleRange.start && index <= this.visibleRange.end) {
+            return 0; // Inside visible range
+        }
+        if (index < this.visibleRange.start) {
+            return this.visibleRange.start - index;
+        }
+        return index - this.visibleRange.end;
+    }
+    // Get cache statistics
+    getStats() {
+        const visibleItems = Array.from(this.itemCache.keys())
+            .filter(key => key >= this.visibleRange.start && key <= this.visibleRange.end)
+            .length;
+        const offScreenItems = this.itemCache.size - visibleItems;
+        // Rough estimate of memory usage (in bytes)
+        let memoryEstimate = 0;
+        for (const [_, value] of this.itemCache.entries()) {
+            memoryEstimate += this.estimateObjectSize(value);
+        }
+        return {
+            size: this.itemCache.size,
+            maxCacheSize: this.maxCacheSize,
+            visibleItems,
+            offScreenItems,
+            memoryEstimate
+        };
+    }
+    // Estimate object size in bytes
+    estimateObjectSize(obj) {
+        if (obj === null || obj === undefined)
+            return 0;
+        if (typeof obj === 'string')
+            return obj.length * 2; // UTF-16 chars
+        if (typeof obj === 'number')
+            return 8; // 8 bytes for number
+        if (typeof obj === 'boolean')
+            return 4; // 4 bytes for boolean
+        if (typeof obj === 'object') {
+            let size = 0;
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key)) {
+                    size += key.length * 2; // Key size
+                    size += this.estimateObjectSize(obj[key]); // Value size
+                }
+            }
+            return size;
+        }
+        return 0; // Other types
+    }
+    // Prune cache to only keep essential items
+    pruneEssential() {
+        const essentialItems = [];
+        // Keep items in visible range and nearby
+        for (const [key, value] of this.itemCache.entries()) {
+            if (this.isEssential(key)) {
+                essentialItems.push([key, value]);
+            }
+        }
+        // Clear cache and repopulate with essential items
+        this.itemCache.clear();
+        for (const [key, value] of essentialItems) {
+            this.itemCache.set(key, value);
+        }
+    }
+    // Check if item is essential (within buffer zone)
+    isEssential(index) {
+        const bufferZone = 20; // Keep items within 20 positions of visible range
+        return index >= (this.visibleRange.start - bufferZone) &&
+            index <= (this.visibleRange.end + bufferZone);
+    }
+    // Get cache size
+    getSize() {
+        return this.itemCache.size;
+    }
+    // Get cache keys
+    getKeys() {
+        return Array.from(this.itemCache.keys());
+    }
+}
+
+class GPUAccelerator {
+    constructor() {
+        this.gpuAccelerationEnabled = false;
+        this.gpuElements = new WeakSet();
+        this.animationFrameId = null;
+        this.gpuAccelerationEnabled = this.isGPUSupported();
+    }
+    // Check if GPU acceleration is supported
+    isGPUSupported() {
+        // Check if we're in a browser environment
+        if (typeof document === 'undefined') {
+            return false; // Not supported in Node.js environment
+        }
+        // Check for 3D transform support
+        const testEl = document.createElement('div');
+        return testEl.style.webkitTransform !== undefined ||
+            testEl.style.transform !== undefined;
+    }
+    // Enable GPU acceleration for an element
+    enableForElement(element) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        // Apply GPU-accelerated styles
+        element.style.willChange = 'transform';
+        element.style.transform = 'translateZ(0)';
+        element.style.backfaceVisibility = 'hidden';
+        element.style.perspective = '1000px';
+        // Add to tracked elements
+        this.gpuElements.add(element);
+    }
+    // Disable GPU acceleration for an element
+    disableForElement(element) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        // Remove GPU-accelerated styles
+        element.style.willChange = 'auto';
+        element.style.transform = '';
+        element.style.backfaceVisibility = '';
+        element.style.perspective = '';
+        // Remove from tracked elements
+        this.gpuElements.delete(element);
+    }
+    // Apply GPU acceleration to a list of elements
+    enableForElements(elements) {
+        elements.forEach(el => this.enableForElement(el));
+    }
+    // Batch update GPU acceleration
+    batchUpdate(elements, enable) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        if (enable) {
+            this.enableForElements(elements);
+        }
+        else {
+            elements.forEach(el => this.disableForElement(el));
+        }
+    }
+    // Optimize scrolling container for GPU acceleration
+    optimizeScrollContainer(container) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        // Apply optimizations to container
+        container.style.transform = 'translateZ(0)';
+        container.style.willChange = 'scroll-position';
+        container.style.webkitOverflowScrolling = 'touch'; // For iOS
+    }
+    // Optimize individual items for GPU acceleration
+    optimizeItem(item) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        // Apply lightweight GPU acceleration
+        item.style.transform = 'translateZ(0)';
+        item.style.willChange = 'transform';
+    }
+    // Get GPU acceleration status
+    getStatus() {
+        // Since WeakSet doesn't have a size property, we can't count directly
+        // This is a limitation of WeakSet
+        return {
+            enabled: this.gpuAccelerationEnabled,
+            supported: this.isGPUSupported(),
+            elementCount: 0 // Placeholder - would need different tracking method
+        };
+    }
+    // Optimize for different scenarios
+    optimizeForScenario(scenario) {
+        if (!this.gpuAccelerationEnabled)
+            return;
+        switch (scenario) {
+            case 'scrolling':
+                // Optimize for smooth scrolling
+                document.body.style.willChange = 'transform';
+                break;
+            case 'animation':
+                // Optimize for animations
+                document.body.style.transform = 'translateZ(0)';
+                break;
+            case 'static':
+                // Remove optimizations when not needed
+                document.body.style.willChange = 'auto';
+                document.body.style.transform = '';
+                break;
+        }
+    }
+    // Cleanup GPU acceleration resources
+    cleanup() {
+        if (this.animationFrameId) {
+            cancelAnimationFrame(this.animationFrameId);
+        }
+        // Reset any applied styles (would need to track them)
+        this.gpuElements = new WeakSet();
+    }
+    // Check if element has GPU acceleration enabled
+    isAccelerated(element) {
+        return this.gpuElements.has(element);
+    }
+    // Get optimization recommendations
+    getRecommendations() {
+        const recommendations = [];
+        if (!this.gpuAccelerationEnabled) {
+            recommendations.push('GPU acceleration not supported on this device');
+        }
+        else {
+            recommendations.push('GPU acceleration enabled for smooth performance');
+            recommendations.push('Using hardware-accelerated compositing');
+            recommendations.push('Optimized for 60fps rendering');
+        }
+        return recommendations;
+    }
+}
+
 class Engine {
     constructor(config) {
         this.fetchMoreCallback = null;
@@ -760,6 +1253,9 @@ class Engine {
         this.networkAwarePrefetchManager = new NetworkAwarePrefetchManager(this.networkDetector);
         this.networkAwareRequestQueue = new NetworkAwareRequestQueue(this.networkDetector);
         this.adaptiveBufferCalculator = new AdaptiveBufferCalculator();
+        this.performanceOptimizer = new PerformanceOptimizer();
+        this.memoryManager = new MemoryManager(1000); // Cache up to 1000 items
+        this.gpuAccelerator = new GPUAccelerator();
         this.totalItems = this.config.totalItems || Number.MAX_SAFE_INTEGER;
         this.state = {
             scrollTop: 0,
@@ -772,26 +1268,34 @@ class Engine {
      * Update scroll position and recalculate visible range with intelligent detection
      */
     async updateScrollPosition(scrollTop) {
-        // Calculate velocity and other intelligent metrics
-        const velocity = this.intelligentScrollDetector.calculateVelocity(scrollTop);
-        this.intelligentScrollDetector.getDirection(velocity);
-        // Get network quality for adaptive buffering
-        const networkQuality = await this.networkDetector.assessConnectionQuality();
-        // Calculate adaptive buffer considering all factors
-        const adaptiveBuffer = await this.adaptiveBufferCalculator.calculateOptimalBuffer({
-            scrollVelocity: velocity,
-            networkQuality,
-            baseBuffer: this.intelligentScrollDetector.calculateBuffer(velocity),
-            visibleItems: [] // In a real implementation, this would be the actual visible items
+        // Use performance optimizer to schedule updates efficiently
+        this.performanceOptimizer.scheduleOptimizedUpdate(async () => {
+            // Calculate velocity and other intelligent metrics
+            const velocity = this.intelligentScrollDetector.calculateVelocity(scrollTop);
+            this.intelligentScrollDetector.getDirection(velocity);
+            // Get network quality for adaptive buffering
+            const networkQuality = await this.networkDetector.assessConnectionQuality();
+            // Calculate adaptive buffer considering all factors
+            const adaptiveBuffer = await this.adaptiveBufferCalculator.calculateOptimalBuffer({
+                scrollVelocity: velocity,
+                networkQuality,
+                baseBuffer: this.intelligentScrollDetector.calculateBuffer(velocity),
+                visibleItems: [] // In a real implementation, this would be the actual visible items
+            });
+            // Update window manager with adaptive buffer
+            this.windowManager.updateBufferSize(adaptiveBuffer);
+            // Update memory manager with visible range
+            this.memoryManager.setVisibleRange({
+                start: Math.max(0, this.state.visibleRange.start - adaptiveBuffer),
+                end: this.state.visibleRange.end + adaptiveBuffer
+            });
+            this.state.scrollTop = scrollTop;
+            this.state.visibleRange = this.windowManager.calculateVisibleRange(scrollTop);
+            // Check if we need to fetch more items
+            if (await this.shouldFetchMore()) {
+                await this.fetchMore();
+            }
         });
-        // Update window manager with adaptive buffer
-        this.windowManager.updateBufferSize(adaptiveBuffer);
-        this.state.scrollTop = scrollTop;
-        this.state.visibleRange = this.windowManager.calculateVisibleRange(scrollTop);
-        // Check if we need to fetch more items
-        if (await this.shouldFetchMore()) {
-            await this.fetchMore();
-        }
     }
     /**
      * Get the current visible range
@@ -877,6 +1381,8 @@ class Engine {
         this.networkAwareRequestQueue.clear();
         this.fetchMoreCallback = null;
         this.intelligentScrollDetector.cleanup();
+        this.performanceOptimizer.cleanup();
+        this.memoryManager.clear();
     }
 }
 
@@ -1078,6 +1584,286 @@ const LazyList = React.forwardRef((props, ref) => {
 });
 LazyList.displayName = 'LazyList';
 
+class LazyScroll {
+  constructor(container, config) {
+    this.container = container;
+    this.config = {
+      itemHeight: config.itemHeight || 50,
+      viewportHeight: config.viewportHeight || 400,
+      bufferSize: config.bufferSize || 5,
+      fetchMore: config.fetchMore || (() => Promise.resolve([]))
+    };
+
+    this.engine = new Engine(this.config);
+    this.engine.setFetchMoreCallback(this.config.fetchMore);
+
+    this.visibleRange = { start: 0, end: 0 };
+    this.isLoading = false;
+    this.items = [];
+    this.visibleItems = [];
+
+    this.scrollHandler = this.onScroll.bind(this);
+    this.container.addEventListener('scroll', this.scrollHandler, { passive: true });
+  }
+
+  onScroll() {
+    const scrollTop = this.container.scrollTop;
+    this.engine.updateScrollPosition(scrollTop);
+
+    const state = this.engine.getState();
+    this.visibleRange = state.visibleRange;
+    this.isLoading = state.isLoading;
+
+    this.render();
+  }
+
+  setItems(items) {
+    this.items = items;
+    this.render();
+  }
+
+  render() {
+    // Calculate paddings
+    const topPadding = this.visibleRange.start * this.config.itemHeight;
+    const bottomPadding = Math.max(0, (this.items.length - this.visibleRange.end) * this.config.itemHeight);
+
+    // Get visible items
+    this.visibleItems = this.items.slice(this.visibleRange.start, this.visibleRange.end);
+
+    // Clear container except for paddings and content
+    const existingContent = this.container.querySelector('.lazy-scroll-content');
+    if (existingContent) {
+      existingContent.remove();
+    }
+
+    // Create content wrapper
+    const contentWrapper = document.createElement('div');
+    contentWrapper.className = 'lazy-scroll-content';
+
+    // Add top padding
+    const topPaddingDiv = document.createElement('div');
+    topPaddingDiv.style.height = `${topPadding}px`;
+    contentWrapper.appendChild(topPaddingDiv);
+
+    // Add visible items
+    this.visibleItems.forEach((item, index) => {
+      const itemElement = this.createItemElement(item, this.visibleRange.start + index);
+      contentWrapper.appendChild(itemElement);
+    });
+
+    // Add bottom padding
+    const bottomPaddingDiv = document.createElement('div');
+    bottomPaddingDiv.style.height = `${bottomPadding}px`;
+    contentWrapper.appendChild(bottomPaddingDiv);
+
+    // Add loading indicator if needed
+    if (this.isLoading) {
+      const loadingElement = document.createElement('div');
+      loadingElement.className = 'lazy-loading';
+      loadingElement.textContent = 'Loading more items...';
+      contentWrapper.appendChild(loadingElement);
+    }
+
+    this.container.appendChild(contentWrapper);
+  }
+
+  createItemElement(item, index) {
+    const itemElement = document.createElement('div');
+    itemElement.style.height = `${this.config.itemHeight}px`;
+    itemElement.className = 'lazy-item';
+
+    // Default content - can be customized
+    itemElement.textContent = `Item ${index}: ${item.text || item.id || 'Content'}`;
+
+    return itemElement;
+  }
+
+  updateConfig(newConfig) {
+    if (newConfig.itemHeight !== undefined) this.config.itemHeight = newConfig.itemHeight;
+    if (newConfig.viewportHeight !== undefined) this.config.viewportHeight = newConfig.viewportHeight;
+    if (newConfig.bufferSize !== undefined) this.config.bufferSize = newConfig.bufferSize;
+    if (newConfig.fetchMore !== undefined) {
+      this.config.fetchMore = newConfig.fetchMore;
+      this.engine.setFetchMoreCallback(newConfig.fetchMore);
+    }
+
+    // Re-render with new config
+    this.render();
+  }
+
+  destroy() {
+    this.container.removeEventListener('scroll', this.scrollHandler);
+    this.engine.cleanup();
+  }
+
+  // Public methods
+  getVisibleRange() {
+    return { ...this.visibleRange };
+  }
+
+  refresh() {
+    this.onScroll();
+  }
+}
+
+// Factory function for easier usage
+function createLazyScroll(container, config) {
+  return new LazyScroll(container, config);
+}
+
+class LazyScrollElement extends HTMLElement {
+  constructor() {
+    super();
+    this.shadow = this.attachShadow({ mode: 'open' });
+    
+    // Default values
+    this.itemHeight = 50;
+    this.viewportHeight = 400;
+    this.bufferSize = 5;
+    this.items = [];
+    
+    // Styles
+    const style = document.createElement('style');
+    style.textContent = `
+      :host {
+        display: block;
+      }
+      
+      .lazy-scroll-container {
+        position: relative;
+        overflow-y: auto;
+      }
+      
+      .lazy-item {
+        width: 100%;
+      }
+      
+      .lazy-loading {
+        text-align: center;
+        padding: 20px;
+        color: #666;
+      }
+    `;
+    
+    this.shadow.appendChild(style);
+  }
+
+  static get observedAttributes() {
+    return ['item-height', 'viewport-height', 'buffer-size'];
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    switch (name) {
+      case 'item-height':
+        this.itemHeight = parseInt(newValue) || 50;
+        break;
+      case 'viewport-height':
+        this.viewportHeight = parseInt(newValue) || 400;
+        break;
+      case 'buffer-size':
+        this.bufferSize = parseInt(newValue) || 5;
+        break;
+    }
+    
+    if (this.lazyScrollInstance) {
+      this.lazyScrollInstance.updateConfig({
+        itemHeight: this.itemHeight,
+        viewportHeight: this.viewportHeight,
+        bufferSize: this.bufferSize
+      });
+    }
+  }
+
+  connectedCallback() {
+    // Create container
+    this.container = document.createElement('div');
+    this.container.className = 'lazy-scroll-container';
+    this.container.style.height = `${this.viewportHeight}px`;
+    this.container.style.overflowY = 'auto';
+    
+    this.shadow.appendChild(this.container);
+
+    // Get fetchMore function from attribute or slot
+    const fetchMoreAttr = this.getAttribute('fetch-more');
+    let fetchMoreFn = () => Promise.resolve([]);
+    
+    if (fetchMoreAttr) {
+      try {
+        // If fetchMore is a function name in global scope
+        fetchMoreFn = window[fetchMoreAttr] || (() => Promise.resolve([]));
+      } catch (e) {
+        console.warn('Could not find fetchMore function:', fetchMoreAttr);
+      }
+    }
+
+    // Initialize lazy scroll
+    this.lazyScrollInstance = createLazyScroll(this.container, {
+      itemHeight: this.itemHeight,
+      viewportHeight: this.viewportHeight,
+      bufferSize: this.bufferSize,
+      fetchMore: fetchMoreFn
+    });
+
+    // Handle items from light DOM
+    this.updateItemsFromSlot();
+    
+    // Observe child changes
+    this.mutationObserver = new MutationObserver(() => {
+      this.updateItemsFromSlot();
+    });
+    
+    this.mutationObserver.observe(this, { childList: true, subtree: true });
+  }
+
+  disconnectedCallback() {
+    if (this.lazyScrollInstance) {
+      this.lazyScrollInstance.destroy();
+    }
+    
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+    }
+  }
+
+  updateItemsFromSlot() {
+    // Get items from light DOM or data attribute
+    const itemsData = this.getAttribute('items');
+    if (itemsData) {
+      try {
+        const items = JSON.parse(itemsData);
+        if (this.lazyScrollInstance) {
+          this.lazyScrollInstance.setItems(items);
+        }
+      } catch (e) {
+        console.warn('Could not parse items data:', itemsData);
+      }
+    }
+  }
+
+  // Public methods
+  setItems(items) {
+    if (this.lazyScrollInstance) {
+      this.lazyScrollInstance.setItems(items);
+    }
+  }
+
+  refresh() {
+    if (this.lazyScrollInstance) {
+      this.lazyScrollInstance.refresh();
+    }
+  }
+
+  getVisibleRange() {
+    if (this.lazyScrollInstance) {
+      return this.lazyScrollInstance.getVisibleRange();
+    }
+    return { start: 0, end: 0 };
+  }
+}
+
+// Register the custom element
+customElements.define('lazy-scroll-element', LazyScrollElement);
+
 /**
  * Debounce function to limit the rate at which a function is called
  */
@@ -1113,15 +1899,21 @@ exports.AdaptiveBufferCalculator = AdaptiveBufferCalculator;
 exports.ContentComplexityAnalyzer = ContentComplexityAnalyzer;
 exports.DevicePerformanceMonitor = DevicePerformanceMonitor;
 exports.Engine = Engine;
+exports.GPUAccelerator = GPUAccelerator;
 exports.IntelligentScrollDetector = IntelligentScrollDetector;
 exports.LazyList = LazyList;
+exports.LazyScroll = LazyScroll;
+exports.LazyScrollElement = LazyScrollElement;
+exports.MemoryManager = MemoryManager;
 exports.NetworkAwarePrefetchManager = NetworkAwarePrefetchManager;
 exports.NetworkAwareRequestQueue = NetworkAwareRequestQueue;
 exports.NetworkSpeedDetector = NetworkSpeedDetector;
+exports.PerformanceOptimizer = PerformanceOptimizer;
 exports.PrefetchManager = PrefetchManager;
 exports.RequestQueue = RequestQueue;
 exports.ScrollObserver = ScrollObserver;
 exports.WindowManager = WindowManager;
+exports.createLazyScroll = createLazyScroll;
 exports.debounce = debounce;
 exports.throttle = throttle;
 exports.useLazyList = useLazyList;