@humanspeak/svelte-virtual-chat 0.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Humanspeak, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# @humanspeak/svelte-virtual-chat
+
+A high-performance virtual chat viewport for Svelte 5. Purpose-built for LLM conversations, support chat, and any message-based UI. Renders only visible messages to the DOM while maintaining smooth follow-bottom behavior, streaming stability, and history prepend with anchor preservation.
+
+[![NPM version](https://img.shields.io/npm/v/@humanspeak/svelte-virtual-chat.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-chat)
+[![Build Status](https://github.com/humanspeak/svelte-virtual-chat/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-chat/actions/workflows/npm-publish.yml)
+[![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-chat.svg)](https://github.com/humanspeak/svelte-virtual-chat/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/npm/dm/@humanspeak/svelte-virtual-chat.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-chat)
+[![Install size](https://packagephobia.com/badge?p=@humanspeak/svelte-virtual-chat)](https://packagephobia.com/result?p=@humanspeak/svelte-virtual-chat)
+[![Code Style: Trunk](https://img.shields.io/badge/code%20style-trunk-blue.svg)](https://trunk.io)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![Types](https://img.shields.io/npm/types/@humanspeak/svelte-virtual-chat.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-chat)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/humanspeak/svelte-virtual-chat/graphs/commit-activity)
+
+## Why This Exists
+
+Chat UIs are not generic lists. They have specific behaviors that general-purpose virtual list components handle poorly:
+
+- Messages anchor to the **bottom**, not the top
+- New messages should **auto-scroll** when you're at the bottom
+- Scrolling away should **not snap you back** when new messages arrive
+- LLM token streaming causes messages to **grow in height** mid-render
+- Loading older history should **preserve your scroll position**
+
+`@humanspeak/svelte-virtual-chat` is opinionated about these behaviors so you don't have to fight a generic abstraction.
+
+## Features
+
+- **Bottom gravity** — messages sit at the bottom of the viewport, like every chat app
+- **Follow-bottom** — viewport stays pinned to the newest message while at bottom
+- **Scroll-away stability** — new messages don't yank you back when you've scrolled up
+- **Virtualized rendering** — only visible messages exist in the DOM (handles 10,000+ messages)
+- **Streaming-native** — height changes from LLM token streaming are batched per frame
+- **History prepend** — load older messages at the top without viewport jumping
+- **Message-aware** — uses message IDs for identity, not array indices
+- **Full TypeScript** — strict types, generics, and exported type definitions
+- **Svelte 5 runes** — built with `$state`, `$derived`, `$effect`, and snippets
+- **Debug info** — real-time stats via `onDebugInfo` callback (total, DOM count, measured, range, following state)
+- **E2E tested** — 57 Playwright tests across 6 test suites
+- **Zero dependencies** — only `esm-env` for SSR detection
+
+## Requirements
+
+- Svelte 5
+- Node.js 18+
+
+## Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @humanspeak/svelte-virtual-chat
+
+# Using npm
+npm install @humanspeak/svelte-virtual-chat
+
+# Using yarn
+yarn add @humanspeak/svelte-virtual-chat
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualChat from '@humanspeak/svelte-virtual-chat'
+
+    type Message = { id: string; role: string; content: string }
+
+    let messages: Message[] = $state([
+        { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
+        { id: '2', role: 'user', content: 'Tell me about Svelte.' }
+    ])
+</script>
+
+<div class="h-[600px]">
+    <SvelteVirtualChat
+        {messages}
+        getMessageId={(msg) => msg.id}
+        estimatedMessageHeight={72}
+        containerClass="h-full"
+        viewportClass="h-full"
+    >
+        {#snippet renderMessage(message, index)}
+            <div class="p-4 border-b">
+                <strong>{message.role}</strong>
+                <p>{message.content}</p>
+            </div>
+        {/snippet}
+    </SvelteVirtualChat>
+</div>
+```
+
+## Props
+
+| Prop                      | Type                                         | Default  | Description                                             |
+| ------------------------- | -------------------------------------------- | -------- | ------------------------------------------------------- |
+| `messages`                | `TMessage[]`                                 | Required | Array of messages in chronological order (oldest first) |
+| `getMessageId`            | `(msg: TMessage) => string`                  | Required | Extract a unique, stable ID from a message              |
+| `renderMessage`           | `Snippet<[TMessage, number]>`                | Required | Snippet that renders a single message                   |
+| `estimatedMessageHeight`  | `number`                                     | `72`     | Height estimate in pixels for unmeasured messages       |
+| `followBottomThresholdPx` | `number`                                     | `48`     | Distance from bottom to consider "at bottom"            |
+| `overscan`                | `number`                                     | `6`      | Extra messages rendered above/below the viewport        |
+| `onNeedHistory`           | `() => void \| Promise<void>`                | -        | Called when user scrolls near top (load older messages) |
+| `onFollowBottomChange`    | `(isFollowing: boolean) => void`             | -        | Called when follow-bottom state changes                 |
+| `onDebugInfo`             | `(info: SvelteVirtualChatDebugInfo) => void` | -        | Called with live stats on every scroll/render update    |
+| `containerClass`          | `string`                                     | `''`     | CSS class for the outermost container                   |
+| `viewportClass`           | `string`                                     | `''`     | CSS class for the scrollable viewport                   |
+| `debug`                   | `boolean`                                    | `false`  | Enable console debug logging                            |
+| `testId`                  | `string`                                     | -        | Base test ID for `data-testid` attributes               |
+
+## Imperative API
+
+Bind the component to access these methods:
+
+```svelte
+<script lang="ts">
+    let chat: ReturnType<typeof SvelteVirtualChat>
+</script>
+
+<SvelteVirtualChat bind:this={chat} ... />
+
+<button onclick={() => chat.scrollToBottom({ smooth: true })}> Scroll to bottom </button>
+```
+
+| Method            | Signature                                              | Description                                         |
+| ----------------- | ------------------------------------------------------ | --------------------------------------------------- |
+| `scrollToBottom`  | `(options?: { smooth?: boolean }) => void`             | Scroll the viewport to the bottom                   |
+| `scrollToMessage` | `(id: string, options?: { smooth?: boolean }) => void` | Scroll to a specific message by its ID              |
+| `isAtBottom`      | `() => boolean`                                        | Check if the viewport is currently following bottom |
+| `getDebugInfo`    | `() => SvelteVirtualChatDebugInfo`                     | Get a snapshot of current debug stats               |
+
+## LLM Streaming
+
+The component handles streaming natively. As a message grows token by token, ResizeObserver detects the height change and the viewport stays pinned to bottom without jitter.
+
+Pair with [@humanspeak/svelte-markdown](https://www.npmjs.com/package/@humanspeak/svelte-markdown) for rich markdown rendering with streaming support:
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualChat from '@humanspeak/svelte-virtual-chat'
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+
+    type Message = {
+        id: string
+        role: 'user' | 'assistant'
+        content: string
+        isStreaming?: boolean
+    }
+
+    let messages: Message[] = $state([...])
+</script>
+
+<SvelteVirtualChat
+    {messages}
+    getMessageId={(msg) => msg.id}
+    containerClass="h-[600px]"
+    viewportClass="h-full"
+>
+    {#snippet renderMessage(message, index)}
+        <div class="p-4 border-b">
+            {#if message.role === 'assistant'}
+                <SvelteMarkdown source={message.content} streaming={message.isStreaming ?? false} />
+            {:else}
+                <p>{message.content}</p>
+            {/if}
+        </div>
+    {/snippet}
+</SvelteVirtualChat>
+```
+
+## History Loading
+
+Load older messages when the user scrolls near the top. The component preserves the user's scroll position during prepend operations.
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualChat from '@humanspeak/svelte-virtual-chat'
+
+    let messages = $state([...recentMessages])
+    let isLoading = false
+
+    async function loadHistory() {
+        if (isLoading) return
+        isLoading = true
+        const older = await fetchOlderMessages()
+        messages = [...older, ...messages]
+        isLoading = false
+    }
+</script>
+
+<SvelteVirtualChat
+    {messages}
+    getMessageId={(msg) => msg.id}
+    onNeedHistory={loadHistory}
+    containerClass="h-[600px]"
+    viewportClass="h-full"
+>
+    {#snippet renderMessage(message, index)}
+        <div class="p-4">{message.content}</div>
+    {/snippet}
+</SvelteVirtualChat>
+```
+
+## Debug Info
+
+The `onDebugInfo` callback provides real-time visibility into the component's internal state:
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualChat from '@humanspeak/svelte-virtual-chat'
+    import type { SvelteVirtualChatDebugInfo } from '@humanspeak/svelte-virtual-chat'
+
+    let stats: SvelteVirtualChatDebugInfo | null = $state(null)
+</script>
+
+<SvelteVirtualChat
+    {messages}
+    getMessageId={(msg) => msg.id}
+    onDebugInfo={(info) => (stats = info)}
+    ...
+/>
+
+{#if stats}
+    <div>
+        Total: {stats.totalMessages} | In DOM: {stats.renderedCount} | Following: {stats.isFollowingBottom}
+    </div>
+{/if}
+```
+
+| Field               | Type      | Description                              |
+| ------------------- | --------- | ---------------------------------------- |
+| `totalMessages`     | `number`  | Total messages in the array              |
+| `renderedCount`     | `number`  | Messages currently in the DOM            |
+| `measuredCount`     | `number`  | Messages with measured heights           |
+| `startIndex`        | `number`  | First rendered index                     |
+| `endIndex`          | `number`  | Last rendered index                      |
+| `totalHeight`       | `number`  | Calculated total content height (px)     |
+| `scrollTop`         | `number`  | Current scroll position (px)             |
+| `viewportHeight`    | `number`  | Viewport height (px)                     |
+| `isFollowingBottom` | `boolean` | Whether the viewport is pinned to bottom |
+| `averageHeight`     | `number`  | Average measured message height (px)     |
+
+## TypeScript
+
+Full type exports for building typed wrappers and extensions:
+
+```typescript
+import type {
+    SvelteVirtualChatProps,
+    SvelteVirtualChatDebugInfo,
+    ScrollToBottomOptions,
+    ScrollToMessageOptions,
+    VisibleRange,
+    ScrollAnchor
+} from '@humanspeak/svelte-virtual-chat'
+
+// Utility exports
+import {
+    ChatHeightCache,
+    captureScrollAnchor,
+    restoreScrollAnchor
+} from '@humanspeak/svelte-virtual-chat'
+```
+
+## How Virtualization Works
+
+The component uses standard top-to-bottom geometry (no inverted lists):
+
+1. **Height caching** — Each message's height is measured via ResizeObserver and cached by ID
+2. **Visible range** — On every scroll, the component calculates which messages fall within `scrollTop` to `scrollTop + viewportHeight`, plus an overscan buffer
+3. **Absolute positioning** — Only visible messages are rendered, positioned via `transform: translateY()` inside a content div sized to the total calculated height
+4. **Follow-bottom** — When at bottom, new messages and height changes trigger an automatic snap to `scrollHeight`
+5. **Bottom gravity** — When messages don't fill the viewport, `flex-direction: column; justify-content: flex-end` pushes them to the bottom
+
+With 10,000 messages, the DOM contains ~15-25 elements instead of 10,000.
+
+## Performance
+
+| Metric                         | Value                                    |
+| ------------------------------ | ---------------------------------------- |
+| DOM nodes with 1,000 messages  | ~15-25 (viewport + overscan)             |
+| DOM nodes with 10,000 messages | ~15-25 (same)                            |
+| Follow-bottom snap             | Single `requestAnimationFrame` per batch |
+| Height measurement             | ResizeObserver (no polling)              |
+| Streaming height updates       | Batched per animation frame              |
+
+## Companion Libraries
+
+| Package                                                                                          | Description                                                   |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [@humanspeak/svelte-markdown](https://www.npmjs.com/package/@humanspeak/svelte-markdown)         | Markdown renderer with LLM streaming mode (~1.6ms per update) |
+| [@humanspeak/svelte-virtual-list](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list) | General-purpose virtual list for non-chat use cases           |
+
+## License
+
+MIT © [Humanspeak, Inc.](LICENSE)
+
+## Credits
+
+Made with ❤️ by [Humanspeak](https://humanspeak.com)

package/dist/SvelteVirtualChat.svelte

@@ -0,0 +1,324 @@
+<script lang="ts" generics="TMessage">
+    import type { SvelteVirtualChatProps, SvelteVirtualChatDebugInfo } from './types.js'
+    import type { VisibleRange } from './virtual-chat/chatTypes.js'
+    import {
+        ChatHeightCache,
+        calculateTotalHeight,
+        calculateOffsetForIndex
+    } from './virtual-chat/chatMeasurement.svelte.js'
+
+    let {
+        messages,
+        getMessageId,
+        estimatedMessageHeight = 72,
+        followBottomThresholdPx = 48,
+        overscan = 6,
+        renderMessage,
+        onNeedHistory,
+        onFollowBottomChange,
+        onDebugInfo,
+        containerClass = '',
+        viewportClass = '',
+        debug = false,
+        testId
+    }: SvelteVirtualChatProps<TMessage> = $props()
+
+    // ── DOM refs ────────────────────────────────────────────────────
+    let viewportEl: HTMLDivElement | undefined = $state()
+
+    // ── Core state ──────────────────────────────────────────────────
+    const heightCache = new ChatHeightCache()
+    let scrollTop = $state(0)
+    let viewportHeight = $state(0)
+    let isFollowingBottom = $state(true)
+    let pendingSnapToBottom = $state(false)
+
+    // ── Derived: total content height ───────────────────────────────
+    const totalHeight = $derived.by(() => {
+        void heightCache.version
+        return calculateTotalHeight(messages, getMessageId, heightCache, estimatedMessageHeight)
+    })
+
+    // ── Derived: top gap for bottom-gravity ─────────────────────────
+    // When content is shorter than viewport, push messages to the bottom
+    const topGap = $derived(Math.max(0, viewportHeight - totalHeight))
+
+    // ── Derived: visible range ──────────────────────────────────────
+    const visibleRange: VisibleRange = $derived.by(() => {
+        void heightCache.version
+
+        if (messages.length === 0 || viewportHeight === 0) {
+            return { start: 0, end: 0, visibleStart: 0, visibleEnd: 0 }
+        }
+
+        // scrollTop is relative to the full content area (which includes topGap)
+        // Adjust to get the scroll position relative to the message content
+        const messageScrollTop = Math.max(0, scrollTop - topGap)
+        const viewTop = messageScrollTop
+        const viewBottom = messageScrollTop + viewportHeight
+
+        let offsetY = 0
+        let visibleStart = -1
+        let visibleEnd = -1
+
+        for (let i = 0; i < messages.length; i++) {
+            const id = getMessageId(messages[i])
+            const h = heightCache.get(id) ?? estimatedMessageHeight
+            const itemTop = offsetY
+            const itemBottom = offsetY + h
+
+            if (itemBottom > viewTop && visibleStart === -1) {
+                visibleStart = i
+            }
+            if (itemTop < viewBottom) {
+                visibleEnd = i
+            }
+
+            offsetY += h
+        }
+
+        if (visibleStart === -1) visibleStart = 0
+        if (visibleEnd === -1) visibleEnd = 0
+
+        const start = Math.max(0, visibleStart - overscan)
+        const end = Math.min(messages.length - 1, visibleEnd + overscan)
+
+        return { start, end, visibleStart, visibleEnd }
+    })
+
+    // ── Derived: offset for the first rendered item ─────────────────
+    const startOffset = $derived.by(() => {
+        void heightCache.version
+        return calculateOffsetForIndex(
+            messages,
+            visibleRange.start,
+            getMessageId,
+            heightCache,
+            estimatedMessageHeight
+        )
+    })
+
+    // ── Derived: slice of messages to render ────────────────────────
+    const renderedMessages = $derived(
+        messages.length === 0 ? [] : messages.slice(visibleRange.start, visibleRange.end + 1)
+    )
+
+    // ── Scroll event handler ────────────────────────────────────────
+    function handleScroll() {
+        if (!viewportEl) return
+        scrollTop = viewportEl.scrollTop
+
+        const maxScroll = viewportEl.scrollHeight - viewportEl.clientHeight
+        const wasFollowing = isFollowingBottom
+        isFollowingBottom = maxScroll <= 0 || maxScroll - scrollTop <= followBottomThresholdPx
+
+        if (wasFollowing !== isFollowingBottom) {
+            onFollowBottomChange?.(isFollowingBottom)
+        }
+
+        // Trigger history loading when near top
+        if (onNeedHistory && scrollTop - topGap < viewportHeight * 0.5) {
+            onNeedHistory()
+        }
+    }
+
+    // ── Measurement action ──────────────────────────────────────────
+    let snapNeeded = false
+
+    function scheduleSnapToBottom() {
+        if (!isFollowingBottom || !viewportEl) return
+        snapNeeded = true
+        if (pendingSnapToBottom) return // rAF already scheduled, it will re-check
+        pendingSnapToBottom = true
+        requestAnimationFrame(() => {
+            pendingSnapToBottom = false
+            if (snapNeeded && isFollowingBottom) {
+                snapNeeded = false
+                snapToBottom()
+            }
+        })
+    }
+
+    function measureMessage(node: HTMLElement, messageId: string) {
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height
+                if (height > 0) {
+                    const changed = heightCache.set(messageId, height)
+                    if (changed) {
+                        scheduleSnapToBottom()
+                    }
+                }
+            }
+        })
+        observer.observe(node)
+
+        return {
+            update(newMessageId: string) {
+                if (newMessageId !== messageId) {
+                    messageId = newMessageId
+                    const height = node.getBoundingClientRect().height
+                    if (height > 0) {
+                        heightCache.set(messageId, height)
+                    }
+                }
+            },
+            destroy() {
+                observer.disconnect()
+            }
+        }
+    }
+
+    // ── Snap to bottom helper ───────────────────────────────────────
+    function snapToBottom() {
+        if (!viewportEl) return
+        const maxScroll = viewportEl.scrollHeight - viewportEl.clientHeight
+        if (maxScroll > 0) {
+            viewportEl.scrollTop = viewportEl.scrollHeight
+        }
+        // Sync the following state directly (don't wait for scroll event)
+        scrollTop = viewportEl.scrollTop
+        isFollowingBottom = true
+    }
+
+    // ── Follow-bottom on new messages ───────────────────────────────
+    $effect(() => {
+        void messages.length
+        if (isFollowingBottom && viewportEl) {
+            requestAnimationFrame(() => snapToBottom())
+        }
+    })
+
+    // ── Follow-bottom on height changes ─────────────────────────────
+    // When measurements arrive, totalHeight changes. If following, re-snap.
+    $effect(() => {
+        void totalHeight
+        if (isFollowingBottom && viewportEl) {
+            scheduleSnapToBottom()
+        }
+    })
+
+    // ── Viewport resize tracking ────────────────────────────────────
+    $effect(() => {
+        if (!viewportEl) return
+        viewportHeight = viewportEl.clientHeight
+
+        const observer = new ResizeObserver(() => {
+            if (viewportEl) {
+                viewportHeight = viewportEl.clientHeight
+                // On initial layout (or resize), snap to bottom if following
+                if (isFollowingBottom) {
+                    requestAnimationFrame(() => snapToBottom())
+                }
+            }
+        })
+        observer.observe(viewportEl)
+        return () => observer.disconnect()
+    })
+
+    // ── Debug info builder ─────────────────────────────────────────
+    function buildDebugInfo(): SvelteVirtualChatDebugInfo {
+        const measuredCount = heightCache.size
+        return {
+            totalMessages: messages.length,
+            renderedCount: renderedMessages.length,
+            measuredCount,
+            startIndex: visibleRange.start,
+            endIndex: visibleRange.end,
+            totalHeight,
+            scrollTop,
+            viewportHeight,
+            isFollowingBottom,
+            averageHeight:
+                measuredCount > 0
+                    ? Math.round(totalHeight / messages.length)
+                    : estimatedMessageHeight
+        }
+    }
+
+    // ── Debug effect: log + callback ────────────────────────────────
+    $effect(() => {
+        void renderedMessages.length
+        void heightCache.version
+        void scrollTop
+        void isFollowingBottom
+
+        const info = buildDebugInfo()
+        if (debug) console.log('[SvelteVirtualChat]', info)
+        onDebugInfo?.(info)
+    })
+
+    // ── Public API ──────────────────────────────────────────────────
+
+    export function scrollToBottom(options?: { smooth?: boolean }) {
+        if (!viewportEl) return
+        viewportEl.scrollTo({
+            top: viewportEl.scrollHeight,
+            behavior: options?.smooth ? 'smooth' : 'instant'
+        })
+    }
+
+    export function scrollToMessage(id: string, options?: { smooth?: boolean }) {
+        const index = messages.findIndex((m) => getMessageId(m) === id)
+        if (index === -1) return
+
+        const offset =
+            topGap +
+            calculateOffsetForIndex(
+                messages,
+                index,
+                getMessageId,
+                heightCache,
+                estimatedMessageHeight
+            )
+
+        viewportEl?.scrollTo({
+            top: offset,
+            behavior: options?.smooth ? 'smooth' : 'instant'
+        })
+    }
+
+    export function isAtBottom(): boolean {
+        return isFollowingBottom
+    }
+
+    export function getDebugInfo(): SvelteVirtualChatDebugInfo {
+        return buildDebugInfo()
+    }
+</script>
+
+<div
+    class={containerClass}
+    data-testid={testId ? `${testId}-container` : undefined}
+    style="display: flex; flex-direction: column; overflow: hidden;"
+>
+    <div
+        bind:this={viewportEl}
+        class={viewportClass}
+        onscroll={handleScroll}
+        style="overflow-y: auto; flex: 1 1 0%; min-height: 0;"
+        data-testid={testId ? `${testId}-viewport` : undefined}
+    >
+        <div
+            style="min-height: 100%; position: relative; width: 100%; display: flex; flex-direction: column; justify-content: flex-end;"
+            data-testid={testId ? `${testId}-content` : undefined}
+        >
+            <div style="height: {totalHeight}px; position: relative; flex-shrink: 0;">
+                <div
+                    style="position: absolute; top: 0; left: 0; right: 0; transform: translateY({startOffset}px);"
+                >
+                    {#each renderedMessages as message, i (getMessageId(message))}
+                        {@const globalIndex = visibleRange.start + i}
+                        <div
+                            use:measureMessage={getMessageId(message)}
+                            data-testid={testId ? `${testId}-item-${globalIndex}` : undefined}
+                            data-message-id={getMessageId(message)}
+                        >
+                            {@render renderMessage(message, globalIndex)}
+                        </div>
+                    {/each}
+                </div>
+            </div>
+        </div>
+    </div>
+</div>

package/dist/SvelteVirtualChat.svelte.d.ts

@@ -0,0 +1,43 @@
+import type { SvelteVirtualChatProps, SvelteVirtualChatDebugInfo } from './types.js';
+declare function $$render<TMessage>(): {
+    props: SvelteVirtualChatProps<TMessage>;
+    exports: {
+        scrollToBottom: (options?: {
+            smooth?: boolean;
+        }) => void;
+        scrollToMessage: (id: string, options?: {
+            smooth?: boolean;
+        }) => void;
+        isAtBottom: () => boolean;
+        getDebugInfo: () => SvelteVirtualChatDebugInfo;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TMessage> {
+    props(): ReturnType<typeof $$render<TMessage>>['props'];
+    events(): ReturnType<typeof $$render<TMessage>>['events'];
+    slots(): ReturnType<typeof $$render<TMessage>>['slots'];
+    bindings(): "";
+    exports(): {
+        scrollToBottom: (options?: {
+            smooth?: boolean;
+        } | undefined) => void;
+        scrollToMessage: (id: string, options?: {
+            smooth?: boolean;
+        } | undefined) => void;
+        isAtBottom: () => boolean;
+        getDebugInfo: () => SvelteVirtualChatDebugInfo;
+    };
+}
+interface $$IsomorphicComponent {
+    new <TMessage>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TMessage>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TMessage>['props']>, ReturnType<__sveltets_Render<TMessage>['events']>, ReturnType<__sveltets_Render<TMessage>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TMessage>['bindings']>;
+    } & ReturnType<__sveltets_Render<TMessage>['exports']>;
+    <TMessage>(internal: unknown, props: ReturnType<__sveltets_Render<TMessage>['props']> & {}): ReturnType<__sveltets_Render<TMessage>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SvelteVirtualChat: $$IsomorphicComponent;
+type SvelteVirtualChat<TMessage> = InstanceType<typeof SvelteVirtualChat<TMessage>>;
+export default SvelteVirtualChat;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import SvelteVirtualChat from './SvelteVirtualChat.svelte';
+export type { ScrollToBottomOptions, ScrollToMessageOptions, SvelteVirtualChatDebugInfo, SvelteVirtualChatProps } from './types.js';
+export type { ScrollAnchor, VisibleRange } from './virtual-chat/chatTypes.js';
+export { ChatHeightCache } from './virtual-chat/chatMeasurement.svelte.js';
+export { captureScrollAnchor, restoreScrollAnchor } from './virtual-chat/chatAnchoring.js';
+export default SvelteVirtualChat;

package/dist/index.js

@@ -0,0 +1,4 @@
+import SvelteVirtualChat from './SvelteVirtualChat.svelte';
+export { ChatHeightCache } from './virtual-chat/chatMeasurement.svelte.js';
+export { captureScrollAnchor, restoreScrollAnchor } from './virtual-chat/chatAnchoring.js';
+export default SvelteVirtualChat;

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+import type { Snippet } from 'svelte';
+/**
+ * Configuration properties for the SvelteVirtualChat component.
+ */
+export type SvelteVirtualChatProps<TMessage = any> = {
+    /**
+     * Array of messages in chronological order (oldest first).
+     */
+    messages: TMessage[];
+    /**
+     * Extract a unique, stable identifier from a message.
+     * Used for height caching, keyed rendering, and scroll-to-message.
+     */
+    getMessageId: (_message: TMessage) => string;
+    /**
+     * Estimated height in pixels for messages not yet measured.
+     * @default 72
+     */
+    estimatedMessageHeight?: number;
+    /**
+     * Distance in pixels from the bottom at which the viewport
+     * is considered "at bottom" for follow-bottom behavior.
+     * @default 48
+     */
+    followBottomThresholdPx?: number;
+    /**
+     * Number of extra messages to render above and below the visible area.
+     * @default 6
+     */
+    overscan?: number;
+    /**
+     * Snippet that renders a single message.
+     * Receives the message object and its index in the messages array.
+     */
+    renderMessage: Snippet<[message: TMessage, index: number]>;
+    /**
+     * Called when the user scrolls near the top, signaling that older
+     * history should be loaded.
+     */
+    onNeedHistory?: () => void | Promise<void>;
+    /**
+     * Called when the follow-bottom state changes.
+     */
+    onFollowBottomChange?: (_isFollowing: boolean) => void;
+    /**
+     * Called whenever debug info updates (on scroll, height changes, message changes).
+     * Use this to display live stats in your UI.
+     */
+    onDebugInfo?: (_info: SvelteVirtualChatDebugInfo) => void;
+    /**
+     * CSS class for the outermost container element.
+     */
+    containerClass?: string;
+    /**
+     * CSS class for the scrollable viewport element.
+     */
+    viewportClass?: string;
+    /**
+     * Enable debug logging and stats.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Base test ID for E2E testing attributes.
+     */
+    testId?: string;
+};
+/**
+ * Debug information emitted by the chat viewport.
+ */
+export type SvelteVirtualChatDebugInfo = {
+    totalMessages: number;
+    renderedCount: number;
+    measuredCount: number;
+    startIndex: number;
+    endIndex: number;
+    totalHeight: number;
+    scrollTop: number;
+    viewportHeight: number;
+    isFollowingBottom: boolean;
+    averageHeight: number;
+};
+/**
+ * Options for the scrollToBottom imperative method.
+ */
+export type ScrollToBottomOptions = {
+    /** Use smooth scrolling animation. @default false */
+    smooth?: boolean;
+};
+/**
+ * Options for the scrollToMessage imperative method.
+ */
+export type ScrollToMessageOptions = {
+    /** Use smooth scrolling animation. @default false */
+    smooth?: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/virtual-chat/chatAnchoring.d.ts

@@ -0,0 +1,17 @@
+import { type ChatHeightCache } from './chatMeasurement.svelte.js';
+import type { ScrollAnchor } from './chatTypes.js';
+/**
+ * Capture a scroll anchor before a history prepend operation.
+ *
+ * Records the first visible message and its pixel offset from the
+ * viewport top, so we can restore the same visual position after
+ * new messages are inserted above.
+ */
+export declare function captureScrollAnchor<T>(messages: T[], getMessageId: (_message: T) => string, heightCache: ChatHeightCache, estimatedHeight: number, scrollTop: number): ScrollAnchor | null;
+/**
+ * Restore scroll position after a history prepend, using a previously captured anchor.
+ *
+ * Finds the anchor message in the (now larger) message array and sets scrollTop
+ * so the anchor appears at the same visual offset from the viewport top.
+ */
+export declare function restoreScrollAnchor<T>(anchor: ScrollAnchor, messages: T[], getMessageId: (_message: T) => string, heightCache: ChatHeightCache, estimatedHeight: number): number;

package/dist/virtual-chat/chatAnchoring.js

@@ -0,0 +1,44 @@
+import { calculateOffsetForIndex } from './chatMeasurement.svelte.js';
+/**
+ * Capture a scroll anchor before a history prepend operation.
+ *
+ * Records the first visible message and its pixel offset from the
+ * viewport top, so we can restore the same visual position after
+ * new messages are inserted above.
+ */
+export function captureScrollAnchor(messages, getMessageId, heightCache, estimatedHeight, scrollTop) {
+    if (messages.length === 0)
+        return null;
+    let offsetY = 0;
+    for (let i = 0; i < messages.length; i++) {
+        const id = getMessageId(messages[i]);
+        const h = heightCache.get(id) ?? estimatedHeight;
+        const itemBottom = offsetY + h;
+        if (itemBottom > scrollTop) {
+            return {
+                messageId: id,
+                offsetFromViewportTop: offsetY - scrollTop
+            };
+        }
+        offsetY += h;
+    }
+    // Fallback: anchor to last message
+    const lastId = getMessageId(messages[messages.length - 1]);
+    return {
+        messageId: lastId,
+        offsetFromViewportTop: offsetY - scrollTop - (heightCache.get(lastId) ?? estimatedHeight)
+    };
+}
+/**
+ * Restore scroll position after a history prepend, using a previously captured anchor.
+ *
+ * Finds the anchor message in the (now larger) message array and sets scrollTop
+ * so the anchor appears at the same visual offset from the viewport top.
+ */
+export function restoreScrollAnchor(anchor, messages, getMessageId, heightCache, estimatedHeight) {
+    const anchorIndex = messages.findIndex((m) => getMessageId(m) === anchor.messageId);
+    if (anchorIndex === -1)
+        return 0;
+    const anchorOffset = calculateOffsetForIndex(messages, anchorIndex, getMessageId, heightCache, estimatedHeight);
+    return anchorOffset - anchor.offsetFromViewportTop;
+}

package/dist/virtual-chat/chatMeasurement.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reactive height cache for chat messages.
+ *
+ * Uses Svelte 5 runes for fine-grained reactivity. Heights are stored
+ * in a plain object keyed by message ID, and a version counter triggers
+ * derived recalculations when any height changes.
+ */
+export declare class ChatHeightCache {
+    #private;
+    /** Get the measured height for a message, or undefined if not yet measured. */
+    get(id: string): number | undefined;
+    /** Set the measured height for a message. Returns true if the value changed. */
+    set(id: string, height: number): boolean;
+    /** Remove a message from the cache (e.g. when messages are pruned). */
+    delete(id: string): void;
+    /** Check if a message has been measured. */
+    has(id: string): boolean;
+    /** Number of measured entries. */
+    get size(): number;
+    /** Current version — use this to establish reactive dependencies on any height change. */
+    get version(): number;
+    /** Clear all cached heights. */
+    clear(): void;
+}
+/**
+ * Calculate the total content height given messages and a height cache.
+ */
+export declare function calculateTotalHeight<T>(messages: T[], getMessageId: (_message: T) => string, heightCache: ChatHeightCache, estimatedHeight: number): number;
+/**
+ * Calculate the Y offset for a message at a given index.
+ */
+export declare function calculateOffsetForIndex<T>(messages: T[], index: number, getMessageId: (_message: T) => string, heightCache: ChatHeightCache, estimatedHeight: number): number;

package/dist/virtual-chat/chatMeasurement.svelte.js

@@ -0,0 +1,71 @@
+/**
+ * Reactive height cache for chat messages.
+ *
+ * Uses Svelte 5 runes for fine-grained reactivity. Heights are stored
+ * in a plain object keyed by message ID, and a version counter triggers
+ * derived recalculations when any height changes.
+ */
+export class ChatHeightCache {
+    #heights = $state({});
+    #version = $state(0);
+    /** Get the measured height for a message, or undefined if not yet measured. */
+    get(id) {
+        return this.#heights[id];
+    }
+    /** Set the measured height for a message. Returns true if the value changed. */
+    set(id, height) {
+        if (this.#heights[id] === height)
+            return false;
+        this.#heights[id] = height;
+        this.#version++;
+        return true;
+    }
+    /** Remove a message from the cache (e.g. when messages are pruned). */
+    delete(id) {
+        if (id in this.#heights) {
+            delete this.#heights[id];
+            this.#version++;
+        }
+    }
+    /** Check if a message has been measured. */
+    has(id) {
+        return id in this.#heights;
+    }
+    /** Number of measured entries. */
+    get size() {
+        // Access version to establish reactive dependency
+        void this.#version;
+        return Object.keys(this.#heights).length;
+    }
+    /** Current version — use this to establish reactive dependencies on any height change. */
+    get version() {
+        return this.#version;
+    }
+    /** Clear all cached heights. */
+    clear() {
+        this.#heights = {};
+        this.#version++;
+    }
+}
+/**
+ * Calculate the total content height given messages and a height cache.
+ */
+export function calculateTotalHeight(messages, getMessageId, heightCache, estimatedHeight) {
+    let total = 0;
+    for (const msg of messages) {
+        const id = getMessageId(msg);
+        total += heightCache.get(id) ?? estimatedHeight;
+    }
+    return total;
+}
+/**
+ * Calculate the Y offset for a message at a given index.
+ */
+export function calculateOffsetForIndex(messages, index, getMessageId, heightCache, estimatedHeight) {
+    let offset = 0;
+    for (let i = 0; i < index && i < messages.length; i++) {
+        const id = getMessageId(messages[i]);
+        offset += heightCache.get(id) ?? estimatedHeight;
+    }
+    return offset;
+}

package/dist/virtual-chat/chatTypes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal height cache entry for a single message.
+ */
+export type HeightCacheEntry = {
+    /** Measured pixel height, or undefined if not yet measured */
+    measured: number | undefined;
+    /** Whether the measurement is stale and needs re-measure */
+    dirty: boolean;
+};
+/**
+ * Visible range result from the range calculation.
+ */
+export type VisibleRange = {
+    /** First rendered index (including overscan) */
+    start: number;
+    /** Last rendered index (including overscan) */
+    end: number;
+    /** First truly visible index (no overscan) */
+    visibleStart: number;
+    /** Last truly visible index (no overscan) */
+    visibleEnd: number;
+};
+/**
+ * Scroll anchor for preserving position during history prepend.
+ */
+export type ScrollAnchor = {
+    /** Message ID of the anchor */
+    messageId: string;
+    /** Pixel offset from viewport top to the anchor message top */
+    offsetFromViewportTop: number;
+};

package/dist/virtual-chat/chatTypes.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,119 @@
+{
+    "name": "@humanspeak/svelte-virtual-chat",
+    "version": "0.0.1",
+    "description": "A high-performance virtual chat viewport for Svelte 5. Purpose-built for LLM conversations, support chat, and any message-based UI. Follow-bottom, streaming-stable, history-prepend with anchor preservation.",
+    "keywords": [
+        "svelte",
+        "virtual-chat",
+        "chat-ui",
+        "llm",
+        "virtual-scroll",
+        "streaming",
+        "ai-chat",
+        "svelte5",
+        "conversation",
+        "chat-viewport"
+    ],
+    "homepage": "https://virtualchat.svelte.page",
+    "bugs": {
+        "url": "https://github.com/humanspeak/svelte-virtual-chat/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/humanspeak/svelte-virtual-chat.git"
+    },
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/humanspeak"
+    },
+    "license": "MIT",
+    "author": "Humanspeak, Inc.",
+    "sideEffects": [
+        "**/*.css"
+    ],
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "svelte": "./dist/index.js"
+        }
+    },
+    "svelte": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "!dist/**/*.test.*",
+        "!dist/**/*.spec.*",
+        "!dist/test/**/*"
+    ],
+    "scripts": {
+        "build": "vite build && pnpm run package",
+        "cf-typegen": "pnpm --filter docs cf-typegen",
+        "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+        "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+        "dev": "vite dev",
+        "dev:all": "mprocs",
+        "dev:pkg": "svelte-kit sync && svelte-package --watch",
+        "format": "prettier --write .",
+        "lint": "prettier --check . && eslint .",
+        "lint:fix": "pnpm run format && eslint . --fix",
+        "package": "svelte-kit sync && svelte-package && publint",
+        "prepare": "npx husky",
+        "prepublishOnly": "npm run package",
+        "preview": "vite preview",
+        "test": "vitest run --coverage --",
+        "test:all": "pnpm run test && pnpm run test:e2e",
+        "test:e2e": "playwright test",
+        "test:only": "vitest run --",
+        "test:unit": "vitest run --coverage",
+        "test:watch": "vitest --"
+    },
+    "dependencies": {
+        "esm-env": "^1.2.2"
+    },
+    "devDependencies": {
+        "@eslint/compat": "^2.0.5",
+        "@eslint/js": "^10.0.1",
+        "@playwright/test": "^1.59.1",
+        "@sveltejs/adapter-auto": "^7.0.1",
+        "@sveltejs/kit": "^2.57.1",
+        "@sveltejs/package": "^2.5.7",
+        "@sveltejs/vite-plugin-svelte": "^7.0.0",
+        "@tailwindcss/vite": "^4.2.2",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/svelte": "^5.3.1",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/node": "^25.6.0",
+        "@typescript-eslint/eslint-plugin": "^8.58.2",
+        "@typescript-eslint/parser": "^8.58.2",
+        "@vitest/coverage-v8": "^4.1.4",
+        "eslint": "^10.2.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-svelte": "^3.17.0",
+        "eslint-plugin-unused-imports": "^4.4.1",
+        "globals": "^17.5.0",
+        "jsdom": "^29.0.2",
+        "mprocs": "^0.9.2",
+        "prettier": "^3.8.2",
+        "prettier-plugin-organize-imports": "^4.3.0",
+        "prettier-plugin-svelte": "^3.5.1",
+        "prettier-plugin-tailwindcss": "^0.7.2",
+        "publint": "^0.3.18",
+        "svelte": "^5.55.4",
+        "svelte-check": "^4.4.6",
+        "tailwindcss": "^4.2.2",
+        "typescript": "^6.0.2",
+        "typescript-eslint": "^8.58.2",
+        "vite": "^8.0.8",
+        "vitest": "^4.1.4"
+    },
+    "peerDependencies": {
+        "svelte": "^5.0.0"
+    },
+    "volta": {
+        "node": "24.13.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}