vlist 1.9.0 → 2.0.0

package/dist/core/create.js

@@ -0,0 +1,740 @@
+/**
+ * vlist v2 — createVList()
+ *
+ * Factory function. Resolves config, creates DOM, compiles hooks from
+ * plugins, wires the 2-phase pipeline, returns the public VList API.
+ */
+import { OVERSCAN, CLASS_PREFIX, SCROLL_IDLE_TIMEOUT, SCROLL_DURATION, MAX_VIRTUAL_SIZE } from "../constants";
+import { resolvePadding, mainAxisPaddingFrom, crossAxisPaddingFrom } from "../utils/padding";
+import { createEngineState } from "./state";
+import { createSizeCache } from "./sizes";
+import { createPool } from "./pool";
+import { createDOMStructure, resolveContainer } from "./dom";
+import { createScrollHandler } from "./scroll";
+import { compileHooks, runAfterScrollHooks, runIdleHooks, runResizeHooks } from "./hooks";
+import { render, createRenderConfig } from "./pipeline";
+import { createEmitter } from "../events";
+import { createVelocityTracker, updateVelocityTracker, MIN_RELIABLE_SAMPLES } from "./velocity";
+// =============================================================================
+// Config Validation
+// =============================================================================
+function validateConfig(raw) {
+    const { item } = raw;
+    // Validate item.height (only if explicitly provided and is a number)
+    if (item.height !== undefined && typeof item.height === "number") {
+        if (!Number.isFinite(item.height) || item.height <= 0) {
+            throw new Error(`vlist: item.height must be a positive number, got ${item.height}`);
+        }
+    }
+    // Validate item.width (only if explicitly provided and is a number)
+    if (item.width !== undefined && typeof item.width === "number") {
+        if (!Number.isFinite(item.width) || item.width <= 0) {
+            throw new Error(`vlist: item.width must be a positive number, got ${item.width}`);
+        }
+    }
+    // Validate item.estimatedHeight (only if explicitly provided)
+    if (item.estimatedHeight !== undefined) {
+        if (!Number.isFinite(item.estimatedHeight) || item.estimatedHeight <= 0) {
+            throw new Error(`vlist: item.estimatedHeight must be a positive number, got ${item.estimatedHeight}`);
+        }
+    }
+    // Validate item.estimatedWidth (only if explicitly provided)
+    if (item.estimatedWidth !== undefined) {
+        if (!Number.isFinite(item.estimatedWidth) || item.estimatedWidth <= 0) {
+            throw new Error(`vlist: item.estimatedWidth must be a positive number, got ${item.estimatedWidth}`);
+        }
+    }
+    // Validate item.gap (only if explicitly provided)
+    if (item.gap !== undefined) {
+        if (typeof item.gap !== "number" || !Number.isFinite(item.gap) || item.gap < 0) {
+            throw new Error(`vlist: item.gap must be a non-negative number, got ${item.gap}`);
+        }
+    }
+    // Validate overscan (only if explicitly provided)
+    if (raw.overscan !== undefined) {
+        if (typeof raw.overscan !== "number" || !Number.isFinite(raw.overscan) || raw.overscan < 0) {
+            throw new Error(`vlist: overscan must be a non-negative number, got ${raw.overscan}`);
+        }
+    }
+}
+// =============================================================================
+// Config Resolution
+// =============================================================================
+function resolveConfig(raw) {
+    const horizontal = raw.orientation === "horizontal";
+    const pad = resolvePadding(raw.padding);
+    return {
+        overscan: raw.overscan ?? OVERSCAN,
+        horizontal,
+        reverse: raw.reverse ?? false,
+        classPrefix: raw.classPrefix ?? CLASS_PREFIX,
+        interactive: raw.interactive ?? true,
+        mainAxisPadding: mainAxisPaddingFrom(pad, horizontal),
+        crossAxisPadding: crossAxisPaddingFrom(pad, horizontal),
+        startPadding: horizontal ? pad.left : pad.top,
+        endPadding: horizontal ? pad.right : pad.bottom,
+        crossPadStart: horizontal ? pad.top : pad.left,
+        crossPadEnd: horizontal ? pad.bottom : pad.right,
+        striped: raw.item.striped || false,
+        gap: raw.item.gap ?? 0,
+    };
+}
+function resolveSizeConfig(raw, horizontal) {
+    if (horizontal) {
+        return raw.item.width ?? raw.item.estimatedWidth ?? 100;
+    }
+    return raw.item.height ?? raw.item.estimatedHeight ?? 40;
+}
+// =============================================================================
+// Plugin Sorting
+// =============================================================================
+function sortPlugins(plugins) {
+    const sorted = [...plugins];
+    sorted.sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50));
+    return sorted;
+}
+function checkConflicts(plugins) {
+    const names = new Set();
+    for (const p of plugins) {
+        if (names.has(p.name)) {
+            throw new Error(`[vlist] Duplicate plugin: ${p.name}`);
+        }
+        names.add(p.name);
+    }
+    for (const p of plugins) {
+        if (p.conflicts) {
+            for (const c of p.conflicts) {
+                if (names.has(c)) {
+                    throw new Error(`[vlist] Plugin "${p.name}" conflicts with "${c}"`);
+                }
+            }
+        }
+    }
+}
+// =============================================================================
+// createVList()
+// =============================================================================
+export function createVList(rawConfig, plugins = []) {
+    // ── Validate config ─────────────────────────────────────────────
+    validateConfig(rawConfig);
+    // ── Resolve config ──────────────────────────────────────────────
+    const config = resolveConfig(rawConfig);
+    const sizeSpec = resolveSizeConfig(rawConfig, config.horizontal);
+    const gap = config.gap;
+    const gappedSizeSpec = gap > 0
+        ? typeof sizeSpec === "function"
+            ? (index) => sizeSpec(index) + gap
+            : sizeSpec + gap
+        : sizeSpec;
+    const minItemSize = typeof sizeSpec === "number" ? sizeSpec : 20;
+    const totalItems = rawConfig.items?.length ?? 0;
+    const oddClass = config.striped ? `${config.classPrefix}-item--odd` : "";
+    const emitter = createEmitter();
+    const rc = createRenderConfig(config.classPrefix, config.horizontal, config.interactive, config.startPadding, config.crossPadStart, config.crossPadEnd, oddClass, gap, emitter);
+    // ── Sort and validate plugins ───────────────────────────────────
+    const sorted = plugins.length > 0 ? sortPlugins(plugins) : plugins;
+    if (plugins.length > 0)
+        checkConflicts(sorted);
+    // ── Create core components ──────────────────────────────────────
+    const container = resolveContainer(rawConfig.container);
+    const dom = createDOMStructure(container, config.classPrefix, config.horizontal, config.interactive, rawConfig.ariaLabel);
+    // ── Scroll config: scrollbar & gutter CSS classes ──────────────
+    const scrollbarMode = rawConfig.scroll?.scrollbar;
+    if (scrollbarMode === "none") {
+        dom.viewport.classList.add(`${config.classPrefix}-viewport--no-scrollbar`);
+    }
+    if (rawConfig.scroll?.gutter === "stable") {
+        dom.viewport.classList.add(`${config.classPrefix}-viewport--gutter-stable`);
+    }
+    // Padding is handled via transform offsets (main axis) and inline
+    // left/right or top/bottom (cross axis) in the pipeline, since items
+    // are position:absolute and CSS padding on the container has no effect.
+    const sizeCache = createSizeCache(gappedSizeSpec, totalItems);
+    if (gap > 0) {
+        const origGetTotalSize = sizeCache.getTotalSize;
+        sizeCache.getTotalSize = () => {
+            const total = origGetTotalSize();
+            return total > 0 ? total - gap : 0;
+        };
+    }
+    const pool = createPool(config.classPrefix);
+    // ── Initialize engine state ─────────────────────────────────────
+    const initialCapacity = Math.ceil(4096 / minItemSize) + config.overscan * 2 + 8;
+    const state = createEngineState(initialCapacity);
+    state.totalItems = totalItems;
+    // ── Items storage ───────────────────────────────────────────────
+    let items = rawConfig.items ?? [];
+    const getItems = () => items;
+    // ── Rendered elements tracking ──────────────────────────────────
+    const rendered = new Map();
+    // ── Velocity tracking & range:change state ─────────────────────
+    const velocityTracker = createVelocityTracker();
+    const _velEvt = { velocity: 0, reliable: false };
+    const _rangeEvt = { range: { start: 0, end: -1 } };
+    const _scrollEvt = { scrollPosition: 0, direction: "down" };
+    const _idleEvt = { scrollPosition: 0 };
+    let prevEmittedStart = -1;
+    let prevEmittedEnd = -1;
+    let lastEventScrollPos = -1;
+    let forceIdleTimer = null;
+    // ── Compile hooks from plugins ──────────────────────────────────
+    const hooks = compileHooks(sorted);
+    // ── Plugin context (cold path) ──────────────────────────────────
+    const methods = new Map();
+    const clickHandlers = [];
+    const keydownHandlers = [];
+    const destroyHandlers = [];
+    let virtualTotalFn = null;
+    let scrollGetFn = null;
+    let scrollSetFn = null;
+    let customRenderIfNeeded = null;
+    let customForceRender = null;
+    let getItemFn = null;
+    let itemStateFn = null;
+    let removeItemByIdFn = null;
+    let insertItemAtFn = null;
+    let updateItemByIdFn = null;
+    let skipDefaultScroll = false;
+    let skipDefaultResize = false;
+    let scrollTarget = null;
+    let navUd = 0;
+    let navLr = 0;
+    let navScrollIndexFn = null;
+    let navNavigateFn = null;
+    let smoothScrollFn = null;
+    let scrollToPosFn = null;
+    let scrollToIndexFn = null;
+    // ── Pre-initialize container size so plugins can read it ────────
+    state.containerSize = config.horizontal ? dom.viewport.clientWidth : dom.viewport.clientHeight;
+    state.crossSize = config.horizontal ? dom.viewport.clientHeight : dom.viewport.clientWidth;
+    // ── Run plugin setup (cold path) ────────────────────────────────
+    if (plugins.length > 0) {
+        const ctx = {
+            dom,
+            sizeCache,
+            pool,
+            config,
+            emitter,
+            template: rawConfig.item.template,
+            registerMethod(name, fn) { methods.set(name, fn); },
+            getMethod(name) { return methods.get(name); },
+            registerClickHandler(handler) { clickHandlers.push(handler); },
+            registerKeydownHandler(handler) { keydownHandlers.push(handler); },
+            registerDestroyHandler(handler) { destroyHandlers.push(handler); },
+            setSizeConfig(sc) {
+                const newCache = createSizeCache(sc, state.totalItems);
+                Object.assign(sizeCache, newCache);
+            },
+            setVisibleRangeFn(_fn) { },
+            setScrollFns(get, set) {
+                scrollGetFn = get;
+                scrollSetFn = set;
+            },
+            setVirtualTotalFn(fn) { virtualTotalFn = fn; },
+            getItems,
+            getItem(index) {
+                return getItemFn ? getItemFn(index) : items[index];
+            },
+            getState() { return state; },
+            rebuildSizeCache() {
+                sizeCache.rebuild(state.totalItems);
+            },
+            updateContentSize(size) {
+                dom.content.style[config.horizontal ? "width" : "height"] = (size + config.mainAxisPadding) + "px";
+            },
+            setRenderFn(renderFn, forceFn) {
+                customRenderIfNeeded = renderFn;
+                customForceRender = forceFn;
+            },
+            renderIfNeeded() { doRender(); },
+            forceRender() {
+                doForceRender();
+            },
+            setGetItemFn(fn) { getItemFn = fn; },
+            setItemStateFn(fn) { itemStateFn = fn; },
+            getItemStateFn() { return itemStateFn; },
+            get rawSizeSpec() { return sizeSpec; },
+            scrollTo(position) {
+                if (scrollSetFn)
+                    scrollSetFn(position);
+                else if (config.horizontal)
+                    dom.viewport.scrollLeft = position;
+                else
+                    dom.viewport.scrollTop = position;
+            },
+            smoothScrollTo(position, duration, easing) {
+                if (smoothScrollFn)
+                    smoothScrollFn(position, duration, undefined, easing);
+                else
+                    ctx.scrollTo(position);
+            },
+            disableDefaultScroll() { skipDefaultScroll = true; },
+            disableDefaultResize() { skipDefaultResize = true; },
+            setScrollTarget(target) { scrollTarget = target; },
+            setScrollToPosFn(fn) { scrollToPosFn = fn; },
+            setScrollToIndexFn(fn) { scrollToIndexFn = fn; },
+            onScrollFrame: doScrollFrame,
+            onScrollIdle: doScrollIdle,
+            removeItemById(id) {
+                if (removeItemByIdFn)
+                    return removeItemByIdFn(id);
+                const idx = items.findIndex((item) => item.id === id);
+                if (idx === -1)
+                    return -1;
+                items.splice(idx, 1);
+                state.totalItems = items.length;
+                sizeCache.rebuild(state.totalItems);
+                syncContentSize();
+                return idx;
+            },
+            insertItemAt(item, index) {
+                if (insertItemAtFn) {
+                    insertItemAtFn(item, index);
+                    return;
+                }
+                items.splice(index, 0, item);
+                state.totalItems = items.length;
+                sizeCache.rebuild(state.totalItems);
+                syncContentSize();
+            },
+            setRemoveItemFn(fn) { removeItemByIdFn = fn; },
+            setInsertItemFn(fn) { insertItemAtFn = fn; },
+            setUpdateItemFn(fn) { updateItemByIdFn = fn; },
+            getRenderedElement(index) {
+                const override = methods.get("_getRenderedElement");
+                if (override)
+                    return override(index);
+                return rendered.get(index) ?? null;
+            },
+            setNavConfig(cfg) {
+                if (cfg.ud !== undefined)
+                    navUd = cfg.ud;
+                if (cfg.lr !== undefined)
+                    navLr = cfg.lr;
+                if (cfg.scrollIndex)
+                    navScrollIndexFn = cfg.scrollIndex;
+                if (cfg.navigate)
+                    navNavigateFn = cfg.navigate;
+            },
+            getNavConfig: (() => {
+                const _nav = { ud: 0, lr: 0, scrollIndex: null, navigate: null };
+                return () => {
+                    _nav.ud = navUd;
+                    _nav.lr = navLr;
+                    _nav.scrollIndex = navScrollIndexFn;
+                    _nav.navigate = navNavigateFn;
+                    return _nav;
+                };
+            })(),
+        };
+        for (const plugin of sorted) {
+            if (plugin.setup) {
+                try {
+                    plugin.setup(ctx);
+                }
+                catch (err) {
+                    emitter.emit("error", {
+                        error: err instanceof Error ? err : new Error(String(err)),
+                        context: `plugin:setup:${plugin.name}`,
+                    });
+                }
+            }
+        }
+    }
+    // ── Scrolling class toggle ──────────────────────────────────────
+    const scrollingClass = config.classPrefix + "--scrolling";
+    let isScrolling = false;
+    // ── Render function ─────────────────────────────────────────────
+    const idleTimeout = rawConfig.scroll?.idleTimeout ?? SCROLL_IDLE_TIMEOUT;
+    function emitScrollEvents() {
+        _scrollEvt.scrollPosition = state.scrollPosition;
+        _scrollEvt.direction = state.scrollDirection > 0 ? "down" : "up";
+        emitter.emit("scroll", _scrollEvt);
+        updateVelocityTracker(velocityTracker, state.scrollPosition);
+        _velEvt.velocity = velocityTracker.velocity;
+        _velEvt.reliable = velocityTracker.sampleCount >= MIN_RELIABLE_SAMPLES;
+        emitter.emit("velocity:change", _velEvt);
+        if (state.startIndex !== prevEmittedStart || state.prevRangeEnd !== prevEmittedEnd) {
+            prevEmittedStart = state.startIndex;
+            prevEmittedEnd = state.prevRangeEnd;
+            _rangeEvt.range.start = state.startIndex;
+            _rangeEvt.range.end = state.prevRangeEnd;
+            emitter.emit("range:change", _rangeEvt);
+        }
+    }
+    let sizeWarningEmitted = false;
+    function syncContentSize() {
+        if (customRenderIfNeeded)
+            return;
+        const totalSize = sizeCache.getTotalSize();
+        dom.content.style[config.horizontal ? "width" : "height"] = (totalSize + config.mainAxisPadding) + "px";
+        if (!sizeWarningEmitted && totalSize > MAX_VIRTUAL_SIZE) {
+            sizeWarningEmitted = true;
+            emitter.emit("error", {
+                error: new Error(`Content size (${totalSize}px) exceeds browser limit (${MAX_VIRTUAL_SIZE}px). Use the scale() plugin for large datasets.`),
+                context: "content:size:overflow",
+            });
+        }
+    }
+    function doRender() {
+        if (customRenderIfNeeded) {
+            customRenderIfNeeded();
+        }
+        else {
+            render(state, sizeCache, config.overscan, pool, dom.content, rawConfig.item.template, getItems, rendered, rc, hooks, getItemFn, itemStateFn);
+        }
+    }
+    function doScrollFrame() {
+        if (!isScrolling) {
+            isScrolling = true;
+            dom.root.classList.add(scrollingClass);
+        }
+        doRender();
+        runAfterScrollHooks(hooks.afterScroll, state.scrollPosition, state.scrollDirection);
+        if (state.scrollPosition !== lastEventScrollPos) {
+            lastEventScrollPos = state.scrollPosition;
+            emitScrollEvents();
+        }
+    }
+    function doScrollIdle() {
+        if (isScrolling) {
+            isScrolling = false;
+            dom.root.classList.remove(scrollingClass);
+        }
+        state.scrollDirection = 0;
+        runIdleHooks(hooks.idle);
+        _velEvt.velocity = 0;
+        _velEvt.reliable = false;
+        emitter.emit("velocity:change", _velEvt);
+        _idleEvt.scrollPosition = state.scrollPosition;
+        emitter.emit("scroll:idle", _idleEvt);
+    }
+    function doForceRender() {
+        state.renderPending = true;
+        if (customForceRender) {
+            customForceRender();
+        }
+        else {
+            render(state, sizeCache, config.overscan, pool, dom.content, rawConfig.item.template, getItems, rendered, rc, hooks, getItemFn, itemStateFn);
+        }
+        runAfterScrollHooks(hooks.afterScroll, state.scrollPosition, state.scrollDirection);
+        if (state.scrollPosition !== lastEventScrollPos) {
+            lastEventScrollPos = state.scrollPosition;
+            emitScrollEvents();
+            if (forceIdleTimer !== null)
+                clearTimeout(forceIdleTimer);
+            forceIdleTimer = setTimeout(doScrollIdle, idleTimeout);
+        }
+    }
+    // ── Scroll handler ──────────────────────────────────────────────
+    const scrollHandler = createScrollHandler({
+        state,
+        viewport: dom.viewport,
+        horizontal: config.horizontal,
+        wheelEnabled: skipDefaultScroll ? false : rawConfig.scroll?.wheel !== false,
+        idleTimeout: rawConfig.scroll?.idleTimeout ?? SCROLL_IDLE_TIMEOUT,
+        ...(scrollTarget ? { scrollTarget } : {}),
+        onFrame: doScrollFrame,
+        onIdle: doScrollIdle,
+    });
+    smoothScrollFn = scrollHandler.smoothScrollTo;
+    // ── Event listeners ─────────────────────────────────────────────
+    function resolveClickedItem(e) {
+        const target = e.target;
+        const itemEl = target.closest("[data-index]");
+        if (!itemEl)
+            return null;
+        const index = parseInt(itemEl.getAttribute("data-index"), 10);
+        if (Number.isNaN(index))
+            return null;
+        const item = items[index];
+        if (item === undefined)
+            return null;
+        return { item, index };
+    }
+    function onContentClick(e) {
+        for (let i = 0; i < clickHandlers.length; i++)
+            clickHandlers[i](e);
+        const hit = resolveClickedItem(e);
+        if (hit)
+            emitter.emit("item:click", { item: hit.item, index: hit.index, event: e });
+    }
+    function onContentDblClick(e) {
+        const hit = resolveClickedItem(e);
+        if (hit)
+            emitter.emit("item:dblclick", { item: hit.item, index: hit.index, event: e });
+    }
+    function onContentContextMenu(e) {
+        const hit = resolveClickedItem(e);
+        if (hit)
+            emitter.emit("item:contextmenu", { item: hit.item, index: hit.index, event: e });
+    }
+    function onContentKeydown(e) {
+        for (let i = 0; i < keydownHandlers.length; i++)
+            keydownHandlers[i](e);
+    }
+    dom.content.addEventListener("click", onContentClick);
+    dom.content.addEventListener("dblclick", onContentDblClick);
+    dom.content.addEventListener("contextmenu", onContentContextMenu);
+    if (keydownHandlers.length > 0)
+        dom.content.addEventListener("keydown", onContentKeydown);
+    // ── ResizeObserver ──────────────────────────────────────────────
+    let resizeObserver = null;
+    if (!skipDefaultResize) {
+        const initObserver = () => {
+            if (state.destroyed)
+                return;
+            resizeObserver = new ResizeObserver((entries) => {
+                for (const entry of entries) {
+                    const { width, height } = entry.contentRect;
+                    const size = config.horizontal ? width : height;
+                    const cross = config.horizontal ? height : width;
+                    if (Math.abs(size - state.containerSize) < 1 && Math.abs(cross - state.crossSize) < 1)
+                        continue;
+                    state.containerSize = size;
+                    state.crossSize = cross;
+                    state.resizeCapacity(size, minItemSize, config.overscan);
+                    doForceRender();
+                    runResizeHooks(hooks.resize, width, height);
+                    emitter.emit("resize", { width, height });
+                }
+            });
+            resizeObserver.observe(dom.viewport);
+        };
+        setTimeout(initObserver, 0);
+    }
+    // ── Initialize ──────────────────────────────────────────────────
+    state.resizeCapacity(state.containerSize, minItemSize, config.overscan);
+    syncContentSize();
+    state.initialized = true;
+    let initialRafId = null;
+    if (rawConfig.defer) {
+        initialRafId = requestAnimationFrame(() => {
+            initialRafId = null;
+            if (!state.destroyed)
+                doRender();
+        });
+    }
+    else {
+        doRender();
+    }
+    if (!skipDefaultScroll)
+        scrollHandler.attach();
+    // ── Public API ──────────────────────────────────────────────────
+    const api = {
+        get element() { return dom.root; },
+        get items() { return items; },
+        get total() { return virtualTotalFn ? virtualTotalFn() : items.length; },
+        setItems(newItems) {
+            items = [...newItems];
+            state.totalItems = items.length;
+            sizeCache.rebuild(state.totalItems);
+            syncContentSize();
+            doForceRender();
+        },
+        appendItems(newItems) {
+            items.push(...newItems);
+            state.totalItems = items.length;
+            sizeCache.rebuild(state.totalItems);
+            syncContentSize();
+            doForceRender();
+        },
+        prependItems(newItems) {
+            items.unshift(...newItems);
+            state.totalItems = items.length;
+            sizeCache.rebuild(state.totalItems);
+            syncContentSize();
+            doForceRender();
+        },
+        updateItem(id, updates) {
+            if (updateItemByIdFn) {
+                if (!updateItemByIdFn(id, updates))
+                    return;
+            }
+            else {
+                const idx = items.findIndex((item) => item.id === id);
+                if (idx === -1)
+                    return;
+                items[idx] = { ...items[idx], ...updates };
+            }
+            doForceRender();
+        },
+        insertItem(item, index) {
+            if (insertItemAtFn) {
+                insertItemAtFn(item, index ?? state.totalItems);
+            }
+            else {
+                if (index === undefined) {
+                    items.push(item);
+                }
+                else {
+                    items.splice(index, 0, item);
+                }
+                state.totalItems = items.length;
+                sizeCache.rebuild(state.totalItems);
+                syncContentSize();
+            }
+            doForceRender();
+        },
+        removeItem(id) {
+            if (removeItemByIdFn) {
+                if (removeItemByIdFn(id) < 0)
+                    return;
+            }
+            else {
+                const idx = items.findIndex((item) => item.id === id);
+                if (idx === -1)
+                    return;
+                items.splice(idx, 1);
+                state.totalItems = items.length;
+                sizeCache.rebuild(state.totalItems);
+                syncContentSize();
+            }
+            doForceRender();
+        },
+        removeItems(ids) {
+            if (removeItemByIdFn) {
+                let removed = 0;
+                for (const id of ids) {
+                    if (removeItemByIdFn(id) >= 0)
+                        removed++;
+                }
+                if (removed > 0)
+                    doForceRender();
+                return removed;
+            }
+            const idSet = new Set(ids);
+            const before = items.length;
+            items = items.filter((item) => !idSet.has(item.id));
+            const removed = before - items.length;
+            if (removed > 0) {
+                state.totalItems = items.length;
+                sizeCache.rebuild(state.totalItems);
+                syncContentSize();
+                state.renderPending = true;
+                doRender();
+            }
+            return removed;
+        },
+        getItemAt(index) {
+            return items[index];
+        },
+        getIndexById(id) {
+            return items.findIndex((item) => item.id === id);
+        },
+        scrollToIndex(index, alignOrOptions = "start") {
+            const total = virtualTotalFn ? virtualTotalFn() : items.length;
+            if (total === 0)
+                return;
+            const clamped = Math.max(0, Math.min(index, total - 1));
+            const align = typeof alignOrOptions === "string" ? alignOrOptions : (alignOrOptions.align ?? "start");
+            const behavior = typeof alignOrOptions === "object" ? alignOrOptions.behavior : undefined;
+            const duration = typeof alignOrOptions === "object" ? alignOrOptions.duration : undefined;
+            const easing = typeof alignOrOptions === "object" ? alignOrOptions.easing : undefined;
+            if (scrollToIndexFn && scrollToIndexFn(clamped, align, behavior, duration, easing) !== false) {
+                return;
+            }
+            const offset = sizeCache.getOffset(clamped);
+            const itemSize = sizeCache.getSize(clamped);
+            const cs = state.containerSize;
+            const totalSize = sizeCache.getTotalSize();
+            const mp = config.mainAxisPadding;
+            const maxScroll = Math.max(0, totalSize + mp - cs);
+            let pos;
+            if (scrollToPosFn) {
+                pos = scrollToPosFn(clamped, sizeCache, cs, total, align);
+            }
+            else {
+                const sp = config.startPadding;
+                switch (align) {
+                    case "center":
+                        pos = sp + offset - (cs - itemSize) / 2;
+                        break;
+                    case "end":
+                        pos = offset + itemSize + mp - cs;
+                        break;
+                    default:
+                        pos = offset;
+                }
+                pos = Math.max(0, Math.min(pos, maxScroll));
+            }
+            if (behavior === "smooth") {
+                scrollHandler.smoothScrollTo(pos, duration ?? SCROLL_DURATION, scrollSetFn ?? undefined, easing);
+            }
+            else if (scrollSetFn) {
+                scrollSetFn(pos);
+            }
+            else {
+                if (config.horizontal)
+                    dom.viewport.scrollLeft = pos;
+                else
+                    dom.viewport.scrollTop = pos;
+            }
+        },
+        getScrollPosition() {
+            return scrollGetFn ? scrollGetFn() : state.scrollPosition;
+        },
+        on: emitter.on.bind(emitter),
+        off: emitter.off.bind(emitter),
+        destroy() {
+            if (state.destroyed)
+                return;
+            state.destroyed = true;
+            if (isScrolling) {
+                isScrolling = false;
+                dom.root.classList.remove(scrollingClass);
+            }
+            if (initialRafId !== null) {
+                cancelAnimationFrame(initialRafId);
+                initialRafId = null;
+            }
+            if (forceIdleTimer !== null) {
+                clearTimeout(forceIdleTimer);
+                forceIdleTimer = null;
+            }
+            scrollHandler.detach();
+            resizeObserver?.disconnect();
+            dom.content.removeEventListener("click", onContentClick);
+            dom.content.removeEventListener("dblclick", onContentDblClick);
+            dom.content.removeEventListener("contextmenu", onContentContextMenu);
+            dom.content.removeEventListener("keydown", onContentKeydown);
+            const destroyErrors = [];
+            for (const handler of destroyHandlers) {
+                try {
+                    handler();
+                }
+                catch (err) {
+                    destroyErrors.push(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            for (const plugin of sorted) {
+                if (plugin.destroy) {
+                    try {
+                        plugin.destroy();
+                    }
+                    catch (err) {
+                        destroyErrors.push(err instanceof Error ? err : new Error(String(err)));
+                    }
+                }
+            }
+            for (const [, element] of rendered) {
+                element.remove();
+            }
+            rendered.clear();
+            pool.clear();
+            dom.root.remove();
+            emitter.emit("destroy", undefined);
+            emitter.clear();
+            if (destroyErrors.length > 0) {
+                for (const err of destroyErrors) {
+                    console.error("vlist: error during destroy:", err);
+                }
+            }
+        },
+    };
+    // ── Attach plugin-registered methods ────────────────────────────
+    for (const [name, fn] of methods) {
+        api[name] = fn;
+    }
+    return api;
+}