### Install Playwright Browsers

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

One-time setup command to install the necessary browsers for Playwright end-to-end testing.

```bash
# Install Playwright browsers (one-time setup)
npx playwright install
```

--------------------------------

### Start Svelte Development Server

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/README.md

After installing dependencies, run this command to start the development server. Use the --open flag to automatically open the application in your browser.

```bash
npm run dev
```

```bash
npm run dev -- --open
```

--------------------------------

### Start Development Server

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/CLAUDE.md

Start the development server for the main library package. For starting both the library and docs development servers, use 'pnpm run dev:all'.

```bash
pnpm dev
```

--------------------------------

### Start Library and Docs Development Servers

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/AGENTS.md

Starts development servers for both the library and the documentation site. Allows for simultaneous development and testing of both parts of the project.

```bash
pnpm run dev:all
```

--------------------------------

### Install Dependencies

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/documentation/CONVEX_INFINITE_SCROLL.md

Install the necessary Convex and svelte-virtual-list packages using pnpm.

```bash
pnpm add convex convex-svelte @humanspeak/svelte-virtual-list
```

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/CLAUDE.md

Install all dependencies for the PNPM workspace. This command should be run before starting development or building the project.

```bash
pnpm install
```

--------------------------------

### Install Svelte Virtual List with pnpm

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

Use this command to install the library using pnpm, which is the recommended package manager.

```bash
# Using pnpm (recommended)
pnpm add @humanspeak/svelte-virtual-list
```

--------------------------------

### Install Svelte Virtual List with yarn

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

Use this command to install the library using yarn.

```bash
# Using yarn
yarn add @humanspeak/svelte-virtual-list
```

--------------------------------

### Installation of ReactiveListManager

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Shows how to import ReactiveListManager, either within the svelte-virtual-list project or for standalone usage.

```bash
# If using within svelte-virtual-list project
import { ReactiveListManager } from '$lib/reactive-list-manager'

# For standalone usage (copy the module)
cp -r src/lib/reactive-list-manager your-project/src/lib/
```

--------------------------------

### Install svelte-virtual-list

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/llms-positioning.md

Install the svelte-virtual-list package using npm.

```bash
npm install @humanspeak/svelte-virtual-list
```

--------------------------------

### Quick Start: Initialize and Process Heights

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Demonstrates the basic usage of ReactiveListManager, including initialization, processing height changes, and accessing the total height.

```typescript
import { ReactiveListManager } from './reactive-list-manager'

// Create manager
const manager = new ReactiveListManager({
    itemLength: 10000,
    itemHeight: 40
})

// Process height changes
const heightChanges = [
    { index: 0, oldHeight: undefined, newHeight: 45 },
    { index: 1, oldHeight: 40, newHeight: 50 }
]
manager.processDirtyHeights(heightChanges)

// Update calculated item height
manager.calculatedItemHeight = 42

// Get reactive total height (automatically updates)
const totalHeight = manager.totalHeight
console.log(`Total height: ${totalHeight}px`)
```

--------------------------------

### Basic Infinite Scroll Implementation

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/infinite-scroll/+page.svx

Demonstrates the fundamental setup for infinite scrolling. Use this for simple cases where you just need to load more items when the user reaches the end of the list.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)

    async function loadMore() {
        const newItems = await fetchMoreItems()
        items = [...items, ...newItems]

        if (newItems.length === 0) {
            hasMore = false
        }
    }
</script>

<VirtualList
    {items}
    onLoadMore={loadMore}
    loadMoreThreshold={20}
    {hasMore}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Minimal Virtual List Example

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/llms-positioning.md

A basic Svelte component demonstrating the usage of the VirtualList with a large number of items and a custom render function.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
</script>

<VirtualList {items}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### SvelteKit Integration Example

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/ssr/+page.svx

Import and use the VirtualList component within a SvelteKit application. Ensure you have the necessary data loaded via SvelteKit's `load` function.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    const { data } = $props()
</script>

<VirtualList items={data.items}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Variable Height Items Example

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/variable-heights/+page.svx

Demonstrates how to use VirtualList with items of varying heights. No special configuration is needed; the component measures and caches heights automatically.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    const items = [
        { id: 1, title: 'Short item' },
        { id: 2, title: 'Medium length item with more content' },
        { id: 3, title: 'Long item', description: 'This item has additional content that makes it taller than the others' }
    ]
</script>

<VirtualList {items}>
    {#snippet renderItem(item)}
        <div class="p-4 border-b">
            <h3>{item.title}</h3>
            {#if item.description}
                <p>{item.description}</p>
            {/if}
        </div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Root Layout Svelte Component

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/convex/+page.svx

Call the Convex setup function in your root Svelte layout component to initialize the client.

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
    import { setup } from '$lib/convex'
    setup()
    let { children } = $props()
</script>

{@render children()}
```

--------------------------------

### Basic Svelte Virtual List Usage

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

A fundamental example demonstrating how to integrate the Svelte Virtual List component into a Svelte 5 application. It shows how to import the component, define an array of items, and render them using the default slot.

```svelte
<script lang="ts">
    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'

    const items = Array.from({ length: 1000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))
</script>

<SvelteVirtualList {items}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>
```

--------------------------------

### Basic Svelte Virtual List Usage

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/+page.svx

Render a list of items efficiently by passing an array and a render snippet to the VirtualList component. This example demonstrates rendering 10,000 items.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    const items = Array.from({ length: 10000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))
</script>

<VirtualList {items}>
    {#snippet renderItem(item)} 
        <div class="item">{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Scroll to Specific Index

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/scroll-methods/+page.svx

Example of scrolling to a specific item index using the scroll method with default options.

```svelte
<button onclick={() => listRef.scroll({ index: 500 }മ}>
    Go to item 500
</button>
```

--------------------------------

### Svelte Integration: Initialize and Update Height Manager

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Provides an example of integrating ReactiveListManager within a Svelte component, including updating item length and processing height changes reactively.

```typescript
// Create manager
const heightManager = new ReactiveListManager({
    itemLength: items.length,
    itemHeight: defaultEstimatedItemHeight
})

// Update on items change
$effect(() => {
    heightManager.updateItemLength(items.length)
})

// Process in callback
const updateHeight = () => {
    heightUpdateTimeout = calculateAverageHeightDebounced(
        // ... params
        (result) => {
            // Convert types if needed (or pass directly if compatible)
            const heightChanges = result.heightChanges

            // Process incrementally
            heightManager.processDirtyHeights(heightChanges)
        }
    )
}

// Update calculated height when needed
$effect(() => {
    heightManager.calculatedItemHeight = calculatedItemHeight
})

// Reactive total height (automatically updates)
let totalHeight = $derived(heightManager.totalHeight)
```

--------------------------------

### Get VirtualList Component Reference

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/methods/+page.svx

Obtain a reference to the VirtualList component using Svelte's bind:this directive to enable programmatic control.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let listRef: VirtualList
</script>

<VirtualList bind:this={listRef} {items}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Svelte Infinite Scroll Component

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/documentation/CONVEX_INFINITE_SCROLL.md

A Svelte component implementing infinite scroll with Convex. It uses `useQuery` for live data and `useConvexClient` for paginated queries, combining them for a seamless list experience. Ensure `setup()` is called in `+layout.svelte` and `PUBLIC_CONVEX_URL` is set.

```svelte
<script lang="ts">
    import { useQuery, useConvexClient } from 'convex-svelte'
    import { api } from '$lib/convex/api'
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Item = { _id: string; _creationTime: number; name: string }

    // Props from server-side load function (for SSR)
    let { data } = $props()

    // Real-time subscription for first page
    const liveQuery = useQuery(api.items.listRecent, { limit: 50 }, { initialData: data.items })

    // Convex client for pagination queries
    const client = useConvexClient()

    // Pagination state
    let olderItems = $state<Item[]>([])
    let cursor = $state<number | null>(null)
    let hasMore = $state(true)

    // Combine live data with paginated data
    const items = $derived<Item[]>(() => {
        const live = (liveQuery.data ?? data.items) as Item[]
        return [...live, ...olderItems]
    })

    // Update cursor when live data changes
    $effect(() => {
        const live = liveQuery.data as Item[] | undefined
        if (live && live.length > 0) {
            cursor = live[live.length - 1]._creationTime
        }
    })

    // Load more function for infinite scroll
    async function loadMore() {
        if (!hasMore || !cursor || !client) return

        const result = await client.query(api.items.listPaginated, {
            cursor,
            limit: 50
        })

        olderItems = [...olderItems, ...result.items]
        cursor = result.nextCursor
        hasMore = result.hasMore
    }

    // Live indicator
    const isLive = $derived(!liveQuery.isLoading && !liveQuery.error)
</script>

{#if isLive}
    <div class="live-indicator">
        <span class="pulse"></span>
        Live
    </div>
{/if}

<VirtualList items={items()} defaultEstimatedItemHeight={60} onLoadMore={loadMore} {hasMore}>
    {#snippet renderItem(item: Item)}
        <div class="item">
            {item.name}
        </div>
    {/snippet}
</VirtualList>

<style>
    .live-indicator {
        display: flex;
        align-items: center;
        gap: 6px;
        color: #16a34a;
    }
    .pulse {
        width: 8px;
        height: 8px;
        background: #22c55e;
        border-radius: 50%;
        animation: pulse 2s infinite;
    }
    @keyframes pulse {
        0%,
        100% {
            opacity: 1;
        }
        50% {
            opacity: 0.5;
        }
    }
</style>
```

--------------------------------

### Build Library Package

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/CLAUDE.md

Build the library package using Vite, svelte-package, and publint. This command is used for creating the production-ready library.

```bash
pnpm build
```

--------------------------------

### Getter/Setter: calculatedItemHeight

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Illustrates how to get or set the `calculatedItemHeight`, which influences the total height calculation and triggers automatic updates.

```typescript
manager.calculatedItemHeight = 42 // Updates totalHeight automatically
const currentHeight = manager.calculatedItemHeight
```

--------------------------------

### Initialize Convex Client in SvelteKit

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/convex/+page.svx

Set up the Convex client in your SvelteKit application by calling setupConvex with your public URL. This should be done in your root layout.

```typescript
import { env } from '$env/dynamic/public'
import { setupConvex, useConvexClient } from 'convex-svelte'

export const setup = () => {
    if (env.PUBLIC_CONVEX_URL) {
        setupConvex(env.PUBLIC_CONVEX_URL, {
            unsavedChangesWarning: false
        })
    }
}

export const getConvexClient = () => useConvexClient()
```

--------------------------------

### calculatedItemHeight

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Allows getting or setting the calculated average item height, which influences the total height calculation. Changes to this property trigger automatic updates to `totalHeight`.

```APIDOC
## calculatedItemHeight (getter/setter)

### Description

Get or set the calculated average item height, which affects total height calculations.

### Method

`setCalculatedItemHeight(height: number)` / `getCalculatedItemHeight(): number`

### Request Example

```typescript
manager.calculatedItemHeight = 42 // Updates totalHeight automatically
const currentHeight = manager.calculatedItemHeight
```
```

--------------------------------

### Build Package

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

Builds the main Svelte Virtual List component package for production.

```bash
pnpm run build
```

--------------------------------

### Format and Lint Files with Trunk

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/CLAUDE.md

Use the Trunk command-line tool to format code and run linters. Trunk manages tool versions and configurations automatically.

```bash
trunk fmt
trunk check
```

--------------------------------

### Standalone Usage of ReactiveListManager

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Demonstrates how to initialize and use the ReactiveListManager for standalone applications. Includes performance monitoring and triggering reactive updates.

```typescript
import { ReactiveListManager, benchmarkHeightManager } from './reactive-list-manager'

const manager = new ReactiveListManager({ itemLength: 1000, itemHeight: 50 })

// Performance monitoring
const results = benchmarkHeightManager(10000, 1000, 100)
console.log(`Average time: ${results.avgTime.toFixed(2)}ms`)
console.log(`Operations/sec: ${results.opsPerSecond.toFixed(0)}`)

// Test reactive totalHeight
manager.calculatedItemHeight = 50 // Triggers reactive update
console.log(`New total height: ${manager.totalHeight}`)
```

--------------------------------

### Convex Client Initialization

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/documentation/CONVEX_INFINITE_SCROLL.md

Set up the Convex client in your Svelte application using environment variables for the Convex URL.

```typescript
import { env } from '$env/dynamic/public'
import { setupConvex, useConvexClient } from 'convex-svelte'

export const setup = () => {
    if (env.PUBLIC_CONVEX_URL) {
        setupConvex(env.PUBLIC_CONVEX_URL, { unsavedChangesWarning: false })
    }
}

export const getConvexClient = () => useConvexClient()
```

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
    import { setup } from '$lib/convex'
    setup()
    let { children } = $props()
</script>

{@render children()}
```

--------------------------------

### Run All Tests

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

Executes all tests across both the main package and the documentation site.

```bash
pnpm test:all
```

--------------------------------

### Running Tests with npm

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Provides commands for running tests, including options for verbose output and filtering for performance tests.

```bash
# Run all tests
npm run test -- ReactiveListManager.test.ts

# Verbose output
npm run test -- ReactiveListManager.test.ts --reporter=verbose

# Performance benchmarking
npm run test -- --grep "Performance Tests"
```

--------------------------------

### Create a New Svelte Project

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/README.md

Use these commands to create a new Svelte project. You can create a project in the current directory or specify a new directory name.

```bash
npx sv create
```

```bash
npx sv create my-app
```

--------------------------------

### Format and Lint Files with Trunk

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/AGENTS.md

Use Trunk for all code formatting and linting. This command formats files according to project standards.

```bash
trunk fmt
```

--------------------------------

### Initial Data Loading in SvelteKit

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/ssr/+page.svx

Load initial data on the server using SvelteKit's `load` function to provide data during SSR and avoid loading states for the user.

```typescript
// +page.server.ts
export async function load() {
    const items = await fetchItems()
    return { items }
```

--------------------------------

### Run Performance Benchmarks

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Execute performance tests and benchmarks for ReactiveListManager using npm scripts. The benchmark function provides metrics on average execution time and operations per second.

```bash
# Run specific tests
npm run test -- ReactiveListManager.test.ts --reporter=verbose

# Performance benchmarking
import { benchmarkHeightManager } from '$lib/reactive-list-manager'

const results = benchmarkHeightManager(10000, 1000, 100)
console.log(`Average time: ${results.avgTime.toFixed(2)}ms`)
console.log(`Operations/sec: ${results.opsPerSecond.toFixed(0)}`)
```

--------------------------------

### Check Code Quality with Trunk

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/AGENTS.md

Run all configured linters and checks using Trunk. This command verifies code quality and adherence to standards.

```bash
trunk check
```

--------------------------------

### Build Svelte Project for Production

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/README.md

This command generates a production-ready build of your Svelte application. You can preview the build using 'npm run preview'.

```bash
npm run build
```

--------------------------------

### Server-Side Rendering with ConvexHttpClient

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/blog/cursor-pagination-infinite-scroll-convex-svelte/+page.svx

Fetch initial data for SSR using `ConvexHttpClient` in a SvelteKit `+page.server.ts` load function. Pass this data as `initialData` to `useQuery` on the client for SEO and a seamless transition to real-time subscriptions.

```typescript
// +page.server.ts
import { ConvexHttpClient } from 'convex/browser'

export const load = async () => {
    const client = new ConvexHttpClient(env.PUBLIC_CONVEX_URL!)
    const items = await client.query(api.items.listRecent, { limit: 50 })
    return { items }
}
```

--------------------------------

### Constructor

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Initializes a new instance of ReactiveListManager with configuration for item length and default item height.

```APIDOC
## Constructor

```typescript
new ReactiveListManager(config: ListManagerConfig)
```

**Parameters:**

- `config.itemLength` (number) - Total number of items in the list.
- `config.itemHeight` (number) - Default height for unmeasured items.
```

--------------------------------

### Type Compatibility for Height Changes

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Demonstrates how to use height changes directly if compatible with SvelteVirtualList's expected format, or how to map them to the required `HeightChange` interface.

```typescript
// If SvelteVirtualList heightChanges are compatible, use directly:
heightManager.processDirtyHeights(result.heightChanges)

// Or convert if different interface:
const heightChanges: HeightChange[] = result.heightChanges.map((change) => ({
    index: change.index,
    oldHeight: change.oldHeight,
    newHeight: change.newHeight
}))
```

--------------------------------

### Run Unit Tests with Coverage

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/CLAUDE.md

Execute Vitest unit tests and generate code coverage reports. This command is essential for verifying the correctness of the library's components.

```bash
pnpm test
```

--------------------------------

### Enable Debug Mode via Environment Variable

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/debug/+page.svx

Alternatively, enable debug mode by setting the `PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG` environment variable to `true`.

```bash
PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG=true
```

--------------------------------

### Core Method: processDirtyHeights

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Shows how to use the `processDirtyHeights` method to incrementally update height calculations with a list of changes.

```typescript
const changes = [{ index: 0, oldHeight: undefined, newHeight: 45 }]
manager.processDirtyHeights(changes)
```

--------------------------------

### Debug and Monitor Performance

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Utilize `getDebugInfo` to retrieve performance metrics like coverage and measured item count. Use `hasSufficientMeasurements` to check the accuracy of height calculations.

```typescript
// Performance monitoring
const debugInfo = heightManager.getDebugInfo()
console.log(`Coverage: ${debugInfo.coveragePercent.toFixed(1)}%`)
console.log(`Measured: ${debugInfo.measuredCount}/${debugInfo.itemLength}`)

// Check if we have sufficient measurements
if (heightManager.hasSufficientMeasurements(20)) {
    console.log('Height calculations are highly accurate')
}
```

--------------------------------

### Basic Scroll to Item 5000

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/scroll-methods/+page.svx

Demonstrates binding a reference to the VirtualList and calling the scroll method to navigate to a specific item with smooth scrolling enabled.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let listRef

    const items = Array.from({ length: 10000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))

    function goToItem5000() {
        listRef.scroll({
            index: 5000,
            smoothScroll: true,
            align: 'auto'
        })
    }
</script>

<button onclick={goToItem5000}>
    Scroll to item 5000
</button>

<VirtualList {items} bind:this={listRef}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Utility Method: getDebugInfo

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Shows how to retrieve detailed debug information using `getDebugInfo`, including coverage and measurement counts.

```typescript
const debug = manager.getDebugInfo()
console.log(`Coverage: ${debug.coveragePercent}%`)
console.log(`Measured: ${debug.measuredCount}/${debug.itemLength}`)
```

--------------------------------

### Create and Initialize ReactiveListManager

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Instantiate ReactiveListManager with initial item count and estimated item height. Use effects to update the manager when the item count or calculated item height changes.

```typescript
// Create reactive list manager
const heightManager = new ReactiveListManager({
    itemLength: items.length,
    itemHeight: defaultEstimatedItemHeight
})

// Update when items change
$effect(() => {
    heightManager.updateItemLength(items.length)
})

// Update calculated height when it changes
$effect(() => {
    heightManager.calculatedItemHeight = calculatedItemHeight
})
```

--------------------------------

### Run All Tests (Unit and E2E)

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/AGENTS.md

Runs both unit tests (Vitest) and end-to-end tests (Playwright). Provides a comprehensive test suite execution.

```bash
pnpm run test:all
```

--------------------------------

### Svelte Virtualized List with Convex

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/blog/cursor-pagination-infinite-scroll-convex-svelte/+page.svx

Combines live data subscription and paginated data fetching for an infinite scrolling virtual list. Handles real-time updates and loads older items as the user scrolls.

```svelte
<script lang="ts">
    import { useQuery, useConvexClient } from 'convex-svelte'
    import { api } from '$lib/convex/api'
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Item = {
        _id: string
        _creationTime: number
        name: string
    }

    let { data } = $props()

    // Live layer: real-time subscription for newest items
    const liveQuery = useQuery(api.items.listRecent, { limit: 50 }, { initialData: data.items })

    const client = useConvexClient()

    // Pagination state
    let olderItems = $state<Item[]>([])
    let cursor = $state<number | null>(null)
    let hasMore = $state(true)

    // Merge live + paginated data
    const items = $derived.by(() => {
        const live = (liveQuery.data ?? data.items) as Item[]
        return [...live, ...olderItems]
    })

    // Track cursor from live data
    $effect(() => {
        const live = liveQuery.data as Item[] | undefined
        if (live && live.length > 0) {
            cursor = live[live.length - 1]._creationTime
        }
    })

    // Infinite scroll handler
    async function loadMore() {
        if (!hasMore || !cursor || !client) return

        const result = await client.query(api.items.listPaginated, { cursor, limit: 50 })

        olderItems = [...olderItems, ...result.items]
        cursor = result.nextCursor
        hasMore = result.hasMore
    }
</script>

<VirtualList {items} defaultEstimatedItemHeight={60} onLoadMore={loadMore} {hasMore}>
    {#snippet renderItem(item: Item)}
        <div class="item">{item.name}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Server-Side Data Loading for SSR with Convex

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/convex/+page.svx

Loads initial data for Server-Side Rendering (SSR) using `ConvexHttpClient` in a SvelteKit `+page.server.ts` file. This is necessary because `convex-svelte` is client-side only.

```typescript
// +page.server.ts
import { env } from '$env/dynamic/public'
import { api } from '$lib/convex/api'
import { ConvexHttpClient } from 'convex/browser'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async () => {
    const client = new ConvexHttpClient(env.PUBLIC_CONVEX_URL!)
    const items = await client.query(
        api.items.listRecent,
        { limit: 50 }
    )
    return { items }
}
```

--------------------------------

### Scroll to Top Convenience Method

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/methods/+page.svx

A convenience method to quickly scroll the list to its beginning.

```typescript
await listRef.scrollToTop()
```

--------------------------------

### Performance Comparison: O(n) vs O(1)

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Compares the performance of traditional O(n) calculations with the O(1) reactive access provided by the manager.

```typescript
// Before: O(n) calculation every time
for (let i = 0; i < 100000; i++) {
    /* ... */
} // ~10-50ms

// After: O(1) reactive access
manager.totalHeight // ~0.01ms
```

--------------------------------

### Complete Infinite Scroll with Loading and Error States

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/infinite-scroll/+page.svx

Provides a robust implementation including loading indicators and error handling. This is suitable for production applications where network requests might fail or take time.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Item = { id: number; text: string }

    let items = $state<Item[]>([])
    let hasMore = $state(true)
    let isLoading = $state(false)
    let error = $state<string | null>(null)
    let page = $state(1)

    // Initial load
    $effect(() => {
        loadInitial()
    })

    async function loadInitial() {
        isLoading = true
        try {
            const response = await fetch('/api/items?page=1')
            const data = await response.json()
            items = data.items
            hasMore = data.hasMore
            page = 1
        } catch (e) {
            error = 'Failed to load items'
        } finally {
            isLoading = false
        }
    }

    async function loadMore() {
        if (isLoading) return

        isLoading = true
        error = null

        try {
            const nextPage = page + 1
            const response = await fetch(`/api/items?page=${nextPage}`)
            const data = await response.json()

            items = [...items, ...data.items]
            hasMore = data.hasMore
            page = nextPage
        } catch (e) {
            error = 'Failed to load more items'
        } finally {
            isLoading = false
        }
    }
</script>

{#if error}
    <div class="error">
        {error}
        <button onclick={loadMore}>Retry</button>
    </div>
{/if}

<VirtualList
    {items}
    onLoadMore={loadMore}
    loadMoreThreshold={10}
    {hasMore}
>
    {#snippet renderItem(item)}
        <div class="item">{item.text}</div>
    {/snippet}
</VirtualList>

{#if isLoading}
    <div class="loading">Loading...</div>
{/if}
```

--------------------------------

### Importing Types

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Demonstrates how to import the main types provided by the Svelte Virtual List package for use in your TypeScript projects.

```APIDOC
## Importing Types

TypeScript types exported by the package.

```typescript
import type {
    SvelteVirtualListProps,
    SvelteVirtualListScrollOptions,
    SvelteVirtualListScrollAlign,
    SvelteVirtualListDebugInfo
} from '@humanspeak/svelte-virtual-list'
```
```

--------------------------------

### Import ReactiveListManager

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Import the ReactiveListManager class from its module path.

```typescript
import { ReactiveListManager } from '$lib/reactive-list-manager'
```

--------------------------------

### Complete Svelte Frontend with Convex

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/convex/+page.svx

Implements a Svelte component using `convex-svelte` for real-time data subscriptions and infinite scrolling pagination. It combines live data with paginated results and displays a live indicator.

```svelte
<script lang="ts">
    import { useQuery, useConvexClient } from 'convex-svelte'
    import { api } from '$lib/convex/api'
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type Item = {
        _id: string
        _creationTime: number
        name: string
    }

    // Props from server-side load function (for SSR)
    let { data } = $props()

    // Real-time subscription for first page
    const liveQuery = useQuery(
        api.items.listRecent,
        { limit: 50 },
        { initialData: data.items }
    )

    // Convex client for pagination queries
    const client = useConvexClient()

    // Pagination state
    let olderItems = $state<Item[]>([])
    let cursor = $state<number | null>(null)
    let hasMore = $state(true)

    // Combine live data with paginated data
    const items = $derived.by(() => {
        const live = (liveQuery.data ?? data.items) as Item[]
        return [...live, ...olderItems]
    })

    // Update cursor when live data changes
    $effect(() => {
        const live = liveQuery.data as Item[] | undefined
        if (live && live.length > 0) {
            cursor = live[live.length - 1]._creationTime
        }
    })

    // Load more function for infinite scroll
    async function loadMore() {
        if (!hasMore || !cursor || !client) return

        const result = await client.query(
            api.items.listPaginated,
            { cursor, limit: 50 }
        )

        olderItems = [...olderItems, ...result.items]
        cursor = result.nextCursor
        hasMore = result.hasMore
    }

    // Live indicator
    const isLive = $derived(
        !liveQuery.isLoading && !liveQuery.error
    )
</script>

{#if isLive}
    <div class="live-indicator">
        <span class="pulse"></span>
        Live
    </div>
{/if}

<VirtualList
    {items}
    defaultEstimatedItemHeight={60}
    onLoadMore={loadMore}
    {hasMore}
>
    {#snippet renderItem(item: Item)}
        <div class="item">{item.name}</div>
    {/snippet}
</VirtualList>

<style>
    .live-indicator {
        display: flex;
        align-items: center;
        gap: 6px;
        color: #16a34a;
    }
    .pulse {
        width: 8px;
        height: 8px;
        background: #22c55e;
        border-radius: 50%;
        animation: pulse 2s infinite;
    }
    @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.5; }
    }
</style>
```

--------------------------------

### SvelteVirtualList Component Props

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/props/+page.svx

This section details all the props available for the SvelteVirtualList component, including required, optional, infinite scroll, styling, debug, and testing props.

```APIDOC
## SvelteVirtualList Component Props

### Description
This section details all the props available for the SvelteVirtualList component, including required, optional, infinite scroll, styling, debug, and testing props.

### Props

#### Required Props

- **items** (TItem[]) - Required - The array of items to render.
- **renderItem** (Svelte snippet) - Required - A Svelte snippet that defines how each item is rendered.

#### Optional Props

- **bufferSize** (number) - Optional - Number of items to render outside the visible viewport for smooth scrolling. Default: 20.
- **defaultEstimatedItemHeight** (number) - Optional - Initial height estimate (in pixels) for items before measurement. Default: 40.

#### Infinite Scroll Props

- **onLoadMore** (() => void | Promise<void>) - Optional - Callback triggered when scrolling near the end of the list.
- **loadMoreThreshold** (number) - Optional - Number of items from the end to trigger `onLoadMore`. Default: 20.
- **hasMore** (boolean) - Optional - Set to `false` when all data has been loaded. Default: true.

#### Styling Props

- **containerClass** (string) - Optional - CSS class for the outer container element.
- **viewportClass** (string) - Optional - CSS class for the scrollable viewport element.
- **contentClass** (string) - Optional - CSS class for the content wrapper element.
- **itemsClass** (string) - Optional - CSS class for the items wrapper element.

#### Debug Props

- **debug** (boolean) - Optional - Enable debug mode with visual overlay. Default: false.
- **debugFunction** ((info: SvelteVirtualListDebugInfo) => void) - Optional - Custom callback to receive debug information.

#### Testing Props

- **testId** (string) - Optional - Base test ID for component elements. When set, adds `data-testid` attributes: `{testId}-container`, `{testId}-viewport`, `{testId}-content`, `{testId}-items`.
```

--------------------------------

### scrollToTop()

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/methods/+page.svx

A convenience method to scroll the list to its beginning.

```APIDOC
## scrollToTop()

### Description
Convenience method to scroll to the beginning of the list.

### Method
```typescript
await listRef.scrollToTop()
```
```

--------------------------------

### Server-Side Data Loading for SSR

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/documentation/CONVEX_INFINITE_SCROLL.md

Load initial data for Server-Side Rendering (SSR) using `ConvexHttpClient`. This is necessary because `convex-svelte` is client-side only. Ensure `PUBLIC_CONVEX_URL` is configured in your environment variables.

```typescript
// +page.server.ts
import { env } from '$env/dynamic/public'
import { api } from '$lib/convex/api'
import { ConvexHttpClient } from 'convex/browser'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async () => {
    const client = new ConvexHttpClient(env.PUBLIC_CONVEX_URL!)
    const items = await client.query(api.items.listRecent, { limit: 50 })
    return { items }
}
```

--------------------------------

### getDebugInfo

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Retrieves detailed debug information about the current state of the list manager, including measurement coverage and item counts.

```APIDOC
## getDebugInfo(): ListManagerDebugInfo

### Description

Get comprehensive debug information.

### Method

`getDebugInfo()`

### Response Example

```typescript
const debug = manager.getDebugInfo()
console.log(`Coverage: ${debug.coveragePercent}%`)
console.log(`Measured: ${debug.measuredCount}/${debug.itemLength}`)
```
```

--------------------------------

### Configure Convex Environment Variable

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/convex/+page.svx

Set the PUBLIC_CONVEX_URL environment variable with your Convex deployment URL.

```env
PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
```

--------------------------------

### Run All E2E Tests with Playwright

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

Execute all end-to-end tests defined in the project using Playwright.

```bash
# Run all e2e tests
pnpm run test:e2e
```

--------------------------------

### SvelteVirtualListScrollOptions

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Specifies the options that can be passed to the `scroll()` method for controlling programmatic scrolling behavior within the virtual list.

```APIDOC
## SvelteVirtualListScrollOptions

Options for the `scroll()` method.

```typescript
interface SvelteVirtualListScrollOptions {
    index: number
    smoothScroll?: boolean
    shouldThrowOnBounds?: boolean
    align?: SvelteVirtualListScrollAlign
}
```
```

--------------------------------

### Implement Infinite Scroll with onLoadMore

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/events/+page.svx

Use the `onLoadMore` callback to trigger data fetching when the user scrolls near the end of the list. Ensure `hasMore` is managed to stop further requests and `loadMoreThreshold` is set appropriately.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)
    let isLoading = $state(false)

    async function loadMore() {
        if (isLoading) return
        isLoading = true

        try {
            const newItems = await fetchMoreItems()
            items = [...items, ...newItems]

            if (newItems.length === 0) {
                hasMore = false
            }
        } finally {
            isLoading = false
        }
    }
</script>

<VirtualList
    {items}
    onLoadMore={loadMore}
    {hasMore}
    loadMoreThreshold={10}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### SvelteVirtualListDebugInfo

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Represents the debug information object provided by the component, offering insights into the current state of the virtual list rendering.

```APIDOC
## SvelteVirtualListDebugInfo

Debug information provided by the component.

```typescript
type SvelteVirtualListDebugInfo = {
    startIndex: number
    endIndex: number
    totalItems: number
    visibleItemsCount: number
    processedItems: number
    averageItemHeight: number
    atTop: boolean
    atBottom: boolean
    totalHeight: number
}
```
```

--------------------------------

### Debug List State with debugFunction

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/events/+page.svx

Utilize the `debugFunction` callback to receive real-time information about the virtual list's state, such as scroll position and visible item counts. Enable debugging with the `debug={true}` prop.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'
    import type { SvelteVirtualListDebugInfo } from '@humanspeak/svelte-virtual-list'

    function onDebug(info: SvelteVirtualListDebugInfo) {
        // Track scroll position
        if (info.atBottom) {
            console.log('User reached the bottom')
        }

        // Monitor performance
        console.log(`Rendering ${info.visibleItemsCount} of ${info.totalItems} items`)
    }
</script>

<VirtualList
    {items}
    debug={true}
    debugFunction={onDebug}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Importing Core Types

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Import the necessary types for configuring the Svelte Virtual List component. These types enable type-safe usage and IntelliSense.

```typescript
import type {
    SvelteVirtualListProps,
    SvelteVirtualListScrollOptions,
    SvelteVirtualListScrollAlign,
    SvelteVirtualListDebugInfo
} from '@humanspeak/svelte-virtual-list'
```

--------------------------------

### Importing VirtualList Scroll Types

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/scroll-methods/+page.svx

Shows how to import specific scroll-related types from the svelte-virtual-list package for use in TypeScript projects.

```typescript
import type {
    SvelteVirtualListScrollOptions,
    SvelteVirtualListScrollAlign
} from '@humanspeak/svelte-virtual-list'
```

--------------------------------

### Scroll to Bottom Convenience Method

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/methods/+page.svx

A convenience method to quickly scroll the list to its end.

```typescript
await listRef.scrollToBottom()
```

--------------------------------

### Implement Infinite Scroll with Svelte Virtual List

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/README.md

This snippet demonstrates how to implement infinite scrolling using the Svelte Virtual List component. It shows how to load more data as the user scrolls near the end of the list and handle the `hasMore` state.

```svelte
<script lang="ts">
    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)

    async function loadMore() {
        const newItems = await fetchMoreItems()
        items = [...items, ...newItems]
        if (newItems.length === 0) {
            hasMore = false
        }
    }
</script>

<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>
```

--------------------------------

### Enable Debug Mode via Props

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/debug/+page.svx

Enable debug mode by setting the `debug` prop to `true` in your VirtualList component.

```svelte
<VirtualList {items} debug={true}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Scroll to Specific Index and Align to Top

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/scroll-methods/+page.svx

Shows how to scroll to a specific item index and ensure it is aligned to the top of the viewport.

```svelte
<button onclick={() => listRef.scroll({ index: 500, align: 'top' })}>
    Scroll to item 500 (top aligned)
</button>
```

--------------------------------

### O(n) vs O(dirty items) Height Calculation

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/README.md

Illustrates the performance difference between traditional O(n) height calculation and the incremental O(dirty items) approach used by ReactiveListManager.

```typescript
// ❌ O(n) - Slow for large lists
let totalHeight = 0
for (let i = 0; i < items.length; i++) {
    totalHeight += heightCache[i] || estimatedHeight
}
```

```typescript
// ✅ O(dirty items) - Fast and reactive
manager.processDirtyHeights(changedItems)
const totalHeight = manager.totalHeight
```

--------------------------------

### Using Generic Type Parameter for Items

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Demonstrates how to use the generic type parameter with the Svelte Virtual List component to provide type safety for your item data. This enhances IntelliSense and prevents runtime errors.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type User = {
        id: number
        name: string
        email: string
    }

    const users: User[] = [] // populate with user data
</script>

<VirtualList items={users}>
    {#snippet renderItem(user: User, index: number)}
        <div>
            <strong>{user.name}</strong>
            <span>{user.email}</span>
        </div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Infinite Scroll with Cursor-Based Pagination

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/infinite-scroll/+page.svx

Adapts the infinite scroll functionality for APIs that use cursor-based pagination. This is useful when the API provides a cursor for fetching the next set of data instead of page numbers.

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state<Item[]>([])
    let cursor = $state<string | null>(null)
    let hasMore = $state(true)

    async function loadMore() {
        const params = new URLSearchParams({ limit: '50' })
        if (cursor) {
            params.set('cursor', cursor)
        }

        const response = await fetch(`/api/items?${params}`)
        const data = await response.json()

        items = [...items, ...data.items]
        cursor = data.nextCursor
        hasMore = data.hasMore
    }
</script>

<VirtualList {items} onLoadMore={loadMore} {hasMore}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
```

--------------------------------

### Generic Type Parameter Usage

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Illustrates how to use the generic type parameter with the VirtualList component to provide type safety for custom item data structures.

```APIDOC
## Generic Type Parameter

The component accepts a generic type for items:

```svelte
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    type User = {
        id: number
        name: string
        email: string
    }

    const users: User[] = [] // populate with user data
</script>

<VirtualList items={users}>
    {#snippet renderItem(user: User, index: number)}
        <div>
            <strong>{user.name}</strong>
            <span>{user.email}</span>
        </div>
    {/snippet}
</VirtualList>
```
```

--------------------------------

### SvelteVirtualListProps

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/docs/src/routes/docs/api/types/+page.svx

Defines the configuration props available for the Svelte Virtual List component, including item data, rendering functions, and various customization options.

```APIDOC
## SvelteVirtualListProps

Configuration props for the component.

```typescript
type SvelteVirtualListProps<TItem = any> = {
    items: TItem[]
    renderItem: Snippet<[item: TItem, index: number]>
    bufferSize?: number
    defaultEstimatedItemHeight?: number
    debug?: boolean
    debugFunction?: (info: SvelteVirtualListDebugInfo) => void
    containerClass?: string
    viewportClass?: string
    contentClass?: string
    itemsClass?: string
    testId?: string
    onLoadMore?: () => void | Promise<void>
    loadMoreThreshold?: number
    hasMore?: boolean
}
```
```

--------------------------------

### Replace Total Height Calculation

Source: https://github.com/humanspeak/svelte-virtual-list/blob/main/src/lib/reactive-list-manager/INTEGRATION_EXAMPLE.md

Replace the old O(n) total height calculation with the O(1) reactive calculation provided by ReactiveListManager for significant performance gains.

```typescript
// OLD: O(n) calculation every time
// let totalHeight = $derived.by(() => {
//     let total = 0
//     for (let i = 0; i < items.length; i++) {
//         total += heightCache[i] || calculatedItemHeight
//     }
//     return total
// })

// NEW: O(1) reactive calculation 🚀
let totalHeight = $derived(heightManager.totalHeight)
```