vlist 1.9.1 → 2.0.0

package/dist/core/dom.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist v2 — DOM Structure
+ * Container resolution and DOM scaffold creation.
+ */
+import type { DOMStructure } from "./types";
+export declare function resolveContainer(container: HTMLElement | string): HTMLElement;
+export declare function createDOMStructure(container: HTMLElement, classPrefix: string, horizontal: boolean, interactive: boolean, ariaLabel?: string): DOMStructure;
+//# sourceMappingURL=dom.d.ts.map

package/dist/core/dom.js

@@ -0,0 +1,47 @@
+/**
+ * vlist v2 — DOM Structure
+ * Container resolution and DOM scaffold creation.
+ */
+// =============================================================================
+// Container Resolution
+// =============================================================================
+export function resolveContainer(container) {
+    if (typeof container === "string") {
+        const el = document.querySelector(container);
+        if (!el)
+            throw new Error(`[vlist] Container not found: ${container}`);
+        return el;
+    }
+    return container;
+}
+// =============================================================================
+// DOM Structure Factory
+// =============================================================================
+export function createDOMStructure(container, classPrefix, horizontal, interactive, ariaLabel) {
+    const rootCls = horizontal ? `${classPrefix} ${classPrefix}--horizontal` : classPrefix;
+    const vpStyle = horizontal
+        ? "overflow-x:auto;overflow-y:hidden;height:100%;width:100%"
+        : "overflow:auto;height:100%;width:100%";
+    const cStyle = horizontal ? "position:relative;height:100%" : "position:relative;width:100%";
+    let cAttrs = ` role="${interactive ? "listbox" : "list"}"`;
+    if (interactive)
+        cAttrs += ' tabindex="0"';
+    if (ariaLabel)
+        cAttrs += ` aria-label="${ariaLabel.replace(/"/g, """)}"`;
+    if (horizontal)
+        cAttrs += ' aria-orientation="horizontal"';
+    container.insertAdjacentHTML("beforeend", `<div class="${rootCls}"><div class="${classPrefix}-viewport" style="${vpStyle}" tabindex="-1"><div class="${classPrefix}-content" style="${cStyle}"${cAttrs}></div></div></div>`);
+    const root = container.lastElementChild;
+    const viewport = root.firstElementChild;
+    const content = viewport.firstElementChild;
+    const liveRegion = document.createElement("div");
+    liveRegion.className = `${classPrefix}-live`;
+    liveRegion.style.cssText =
+        "position:absolute;width:1px;height:1px;padding:0;margin:-1px;" +
+            "overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0";
+    liveRegion.setAttribute("aria-live", "polite");
+    liveRegion.setAttribute("aria-atomic", "true");
+    liveRegion.setAttribute("role", "status");
+    root.appendChild(liveRegion);
+    return { root, viewport, content, liveRegion };
+}

package/dist/core/hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * vlist v2 — Build-Time Compiled Hooks
+ *
+ * Hooks are collected during createVList() and frozen into plain arrays.
+ * On the hot path they are iterated with a for-loop — no closures,
+ * no dynamic dispatch, no allocation.
+ */
+import type { CalculateHook, CommitHook, AfterScrollHook, IdleHook, ResizeHook, CompiledHooks, VListPlugin } from "./types";
+import type { VListItem } from "../types";
+export declare function compileHooks<T extends VListItem>(plugins: readonly VListPlugin<T>[]): CompiledHooks;
+export declare function runCalculateHooks(hooks: readonly CalculateHook[], state: import("./state").EngineState): void;
+export declare function runCommitHooks(hooks: readonly CommitHook[], state: import("./state").EngineState): void;
+export declare function runAfterScrollHooks(hooks: readonly AfterScrollHook[], scrollPosition: number, direction: number): void;
+export declare function runIdleHooks(hooks: readonly IdleHook[]): void;
+export declare function runResizeHooks(hooks: readonly ResizeHook[], width: number, height: number): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/core/hooks.js

@@ -0,0 +1,67 @@
+/**
+ * vlist v2 — Build-Time Compiled Hooks
+ *
+ * Hooks are collected during createVList() and frozen into plain arrays.
+ * On the hot path they are iterated with a for-loop — no closures,
+ * no dynamic dispatch, no allocation.
+ */
+// =============================================================================
+// Compiler — collects hooks from plugins, returns frozen arrays
+// =============================================================================
+const EMPTY = [];
+const EMPTY_HOOKS = {
+    calculate: EMPTY, commit: EMPTY, afterScroll: EMPTY, idle: EMPTY, resize: EMPTY,
+};
+export function compileHooks(plugins) {
+    if (plugins.length === 0)
+        return EMPTY_HOOKS;
+    const calculate = [];
+    const commit = [];
+    const afterScroll = [];
+    const idle = [];
+    const resize = [];
+    for (let i = 0; i < plugins.length; i++) {
+        const h = plugins[i].hooks;
+        if (h === undefined)
+            continue;
+        if (h.onCalculate !== undefined)
+            calculate.push(h.onCalculate);
+        if (h.onCommit !== undefined)
+            commit.push(h.onCommit);
+        if (h.onAfterScroll !== undefined)
+            afterScroll.push(h.onAfterScroll);
+        if (h.onIdle !== undefined)
+            idle.push(h.onIdle);
+        if (h.onResize !== undefined)
+            resize.push(h.onResize);
+    }
+    return { calculate, commit, afterScroll, idle, resize };
+}
+// =============================================================================
+// Runners — zero allocation, linear iteration
+// =============================================================================
+export function runCalculateHooks(hooks, state) {
+    for (let i = 0; i < hooks.length; i++) {
+        hooks[i](state);
+    }
+}
+export function runCommitHooks(hooks, state) {
+    for (let i = 0; i < hooks.length; i++) {
+        hooks[i](state);
+    }
+}
+export function runAfterScrollHooks(hooks, scrollPosition, direction) {
+    for (let i = 0; i < hooks.length; i++) {
+        hooks[i](scrollPosition, direction);
+    }
+}
+export function runIdleHooks(hooks) {
+    for (let i = 0; i < hooks.length; i++) {
+        hooks[i]();
+    }
+}
+export function runResizeHooks(hooks, width, height) {
+    for (let i = 0; i < hooks.length; i++) {
+        hooks[i](width, height);
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vlist v2 — Core Public API
+ */
+export { createVList } from "./create";
+export { createEngineState } from "./state";
+export type { EngineState } from "./state";
+export { phase1Calculate, phase2Commit, render, createRenderConfig } from "./pipeline";
+export type { RenderConfig } from "./pipeline";
+export { compileHooks, runCalculateHooks, runCommitHooks, runAfterScrollHooks, runIdleHooks, runResizeHooks } from "./hooks";
+export { createPool } from "./pool";
+export { createSizeCache, countVisibleItems, countItemsFittingFromBottom, getOffsetForVirtualIndex } from "./sizes";
+export { createDOMStructure, resolveContainer } from "./dom";
+export { createScrollHandler } from "./scroll";
+export type { SizeCache } from "./sizes";
+export type { ScrollHandler, ScrollHandlerConfig } from "./scroll";
+export type { CalculateHook, CommitHook, AfterScrollHook, IdleHook, ResizeHook, CompiledHooks, ResolvedConfig, DOMStructure, ElementPool, VisibleRangeFn, PluginContext, VListPlugin, VList, CreateVListConfig, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * vlist v2 — Core Public API
+ */
+// Factory
+export { createVList } from "./create";
+// Engine
+export { createEngineState } from "./state";
+export { phase1Calculate, phase2Commit, render, createRenderConfig } from "./pipeline";
+export { compileHooks, runCalculateHooks, runCommitHooks, runAfterScrollHooks, runIdleHooks, runResizeHooks } from "./hooks";
+export { createPool } from "./pool";
+export { createSizeCache, countVisibleItems, countItemsFittingFromBottom, getOffsetForVirtualIndex } from "./sizes";
+export { createDOMStructure, resolveContainer } from "./dom";
+export { createScrollHandler } from "./scroll";

package/dist/core/pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * vlist v2 — 2-Phase Pipeline
+ *
+ * Phase 1: Calculate & Reconcile — zero allocation hot path.
+ *   Reads scroll position + size cache, writes into EngineState TypedArrays.
+ *
+ * Phase 2: Commit — reads EngineState buffers, updates DOM via pool.
+ *   Sub-phases: acquire → identity bind → position → release.
+ *
+ * Both phases are synchronous. No intermediate objects are allocated.
+ */
+import type { SizeCache } from "./sizes";
+import type { VListItem, ItemTemplate, ItemState, VListEvents } from "../types";
+import type { CompiledHooks, ElementPool } from "./types";
+import type { EngineState } from "./state";
+import type { Emitter } from "../events";
+export interface RenderConfig {
+    readonly prefix: string;
+    readonly selectedClass: string;
+    readonly focusedClass: string;
+    readonly placeholderClass: string;
+    readonly replacedClass: string;
+    readonly translateProp: "translateX(" | "translateY(";
+    readonly itemRole: "option" | "listitem";
+    readonly interactive: boolean;
+    readonly horizontal: boolean;
+    readonly startPadding: number;
+    readonly gap: number;
+    readonly hasCrossPad: boolean;
+    readonly crossStartProp: string;
+    readonly crossEndProp: string;
+    readonly crossStartVal: string;
+    readonly crossEndVal: string;
+    readonly oddClass: string;
+    readonly emitter: Emitter<VListEvents> | null;
+}
+export declare function createRenderConfig(classPrefix: string, horizontal: boolean, interactive: boolean, startPadding: number, crossPadStart: number, crossPadEnd: number, oddClass: string, gap: number, emitter?: Emitter<VListEvents> | null): RenderConfig;
+/**
+ * Calculate visible range and fill EngineState buffers.
+ * Zero allocation — all writes go into pre-allocated TypedArrays.
+ *
+ * Guards:
+ * - Zero container size early exit
+ * - Empty range sentinel: visibleCount = 0
+ * - Overscan application
+ * - Render count safety cap
+ */
+export declare function phase1Calculate(state: EngineState, sizeCache: SizeCache, overscan: number, hooks: CompiledHooks, startPadding?: number): boolean;
+export declare function phase2Commit<T extends VListItem>(state: EngineState, pool: ElementPool, contentElement: HTMLElement, template: ItemTemplate<T>, getItems: () => readonly T[], rendered: Map<number, HTMLElement>, rc: RenderConfig, hooks: CompiledHooks, getItemFn?: ((index: number) => T | undefined) | null, itemStateFn?: ((index: number, state: ItemState) => void) | null): void;
+export declare function render<T extends VListItem>(state: EngineState, sizeCache: SizeCache, overscan: number, pool: ElementPool, contentElement: HTMLElement, template: ItemTemplate<T>, getItems: () => readonly T[], rendered: Map<number, HTMLElement>, rc: RenderConfig, hooks: CompiledHooks, getItemFn?: ((index: number) => T | undefined) | null, itemStateFn?: ((index: number, state: ItemState) => void) | null): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/core/pipeline.js

@@ -0,0 +1,307 @@
+/**
+ * vlist v2 — 2-Phase Pipeline
+ *
+ * Phase 1: Calculate & Reconcile — zero allocation hot path.
+ *   Reads scroll position + size cache, writes into EngineState TypedArrays.
+ *
+ * Phase 2: Commit — reads EngineState buffers, updates DOM via pool.
+ *   Sub-phases: acquire → identity bind → position → release.
+ *
+ * Both phases are synchronous. No intermediate objects are allocated.
+ */
+import { runCalculateHooks, runCommitHooks } from "./hooks";
+import { PLACEHOLDER_ID_PREFIX } from "../constants";
+export function createRenderConfig(classPrefix, horizontal, interactive, startPadding, crossPadStart, crossPadEnd, oddClass, gap, emitter) {
+    const hasCrossPad = crossPadStart !== 0 || crossPadEnd !== 0;
+    return {
+        prefix: classPrefix,
+        selectedClass: `${classPrefix}-item--selected`,
+        focusedClass: `${classPrefix}-item--focused`,
+        placeholderClass: `${classPrefix}-item--placeholder`,
+        replacedClass: `${classPrefix}-item--replaced`,
+        translateProp: horizontal ? "translateX(" : "translateY(",
+        itemRole: interactive ? "option" : "listitem",
+        interactive,
+        horizontal,
+        startPadding,
+        gap,
+        hasCrossPad,
+        crossStartProp: hasCrossPad ? (horizontal ? "top" : "left") : "",
+        crossEndProp: hasCrossPad ? (horizontal ? "bottom" : "right") : "",
+        crossStartVal: hasCrossPad ? crossPadStart + "px" : "",
+        crossEndVal: hasCrossPad ? crossPadEnd + "px" : "",
+        oddClass,
+        emitter: emitter ?? null,
+    };
+}
+// =============================================================================
+// Phase 1 — Calculate & Reconcile
+// =============================================================================
+/**
+ * Calculate visible range and fill EngineState buffers.
+ * Zero allocation — all writes go into pre-allocated TypedArrays.
+ *
+ * Guards:
+ * - Zero container size early exit
+ * - Empty range sentinel: visibleCount = 0
+ * - Overscan application
+ * - Render count safety cap
+ */
+export function phase1Calculate(state, sizeCache, overscan, hooks, startPadding) {
+    if (state.containerSize <= 0 || state.totalItems === 0) {
+        state.clear();
+        return true;
+    }
+    const scrollPos = state.scrollPosition;
+    const containerSize = state.containerSize;
+    const totalItems = state.totalItems;
+    const sp = startPadding ?? 0;
+    state.totalSize = sizeCache.getTotalSize();
+    // Visible range — items are visually shifted by startPadding in the
+    // transform, so subtract it from the range start lookup to avoid
+    // missing items at the top of the viewport.
+    let visStart = sizeCache.indexAtOffset(sp > 0 ? Math.max(0, scrollPos - sp) : scrollPos);
+    let visEnd = sizeCache.indexAtOffset(scrollPos + containerSize);
+    if (visEnd < totalItems - 1)
+        visEnd++;
+    visStart = Math.max(0, visStart);
+    visEnd = Math.min(totalItems - 1, Math.max(0, visEnd));
+    // Overscan
+    const renderStart = Math.max(0, visStart - overscan);
+    const renderEnd = Math.min(totalItems - 1, visEnd + overscan);
+    // Safety cap
+    const maxRender = Math.ceil(containerSize / 1) + overscan * 2 + 10;
+    const count = renderEnd - renderStart + 1;
+    const safeCap = Math.min(count, state.capacity, maxRender);
+    // Range-unchanged fast path
+    if (renderStart === state.prevRangeStart && renderEnd === state.prevRangeEnd && !state.renderPending) {
+        return false;
+    }
+    // Fill TypedArray buffers
+    state.visibleCount = safeCap;
+    state.startIndex = renderStart;
+    for (let i = 0; i < safeCap; i++) {
+        const idx = renderStart + i;
+        state.visibleIndices[i] = idx;
+        state.visibleOffsets[i] = sizeCache.getOffset(idx);
+        state.visibleSizes[i] = sizeCache.getSize(idx);
+    }
+    runCalculateHooks(hooks.calculate, state);
+    state.prevRangeStart = renderStart;
+    state.prevRangeEnd = renderEnd;
+    state.renderPending = false;
+    return true;
+}
+// =============================================================================
+// Phase 2 — Commit (DOM Update)
+// =============================================================================
+/** Reusable ItemState singleton — never allocated per frame */
+const itemState = { selected: false, focused: false };
+/** Linear scan for idx in visibleIndices[0..count). Handles arbitrary order. Zero allocation. */
+function isInVisible(indices, count, idx) {
+    for (let i = 0; i < count; i++) {
+        if (indices[i] === idx)
+            return true;
+    }
+    return false;
+}
+/** Module-scope release state — avoids per-frame closure in rendered.forEach */
+let _relIndices;
+let _relCount;
+let _relPool;
+let _relRendered;
+function releaseIfNotVisible(element, idx) {
+    if (!isInVisible(_relIndices, _relCount, idx)) {
+        element.remove();
+        _relPool.release(element);
+        _relRendered.delete(idx);
+    }
+}
+export function phase2Commit(state, pool, contentElement, template, getItems, rendered, rc, hooks, getItemFn, itemStateFn) {
+    const items = getItemFn ? null : getItems();
+    const count = state.visibleCount;
+    const newIndices = state.visibleIndices;
+    const ariaTotal = rc.interactive ? String(state.totalItems) : "";
+    const totalChanged = rc.interactive && state.totalItems !== state.prevAriaTotal;
+    let fragment = null;
+    for (let i = 0; i < count; i++) {
+        const dataIndex = newIndices[i];
+        const offset = state.visibleOffsets[i];
+        const size = state.visibleSizes[i];
+        const item = getItemFn ? getItemFn(dataIndex) : items[dataIndex];
+        if (itemStateFn) {
+            itemStateFn(dataIndex, itemState);
+        }
+        else {
+            itemState.selected = false;
+            itemState.focused = false;
+        }
+        let element = rendered.get(dataIndex);
+        const el = element;
+        if (element === undefined) {
+            const acquired = pool.acquire();
+            if (item !== undefined) {
+                let result;
+                try {
+                    result = template(item, dataIndex, itemState);
+                }
+                catch (err) {
+                    if (rc.emitter) {
+                        rc.emitter.emit("error", {
+                            error: err instanceof Error ? err : new Error(String(err)),
+                            context: `template:render:${dataIndex}`,
+                        });
+                    }
+                    pool.release(acquired);
+                    continue;
+                }
+                if (typeof result === "string") {
+                    acquired.innerHTML = result;
+                }
+                else {
+                    acquired.innerHTML = "";
+                    acquired.appendChild(result);
+                }
+            }
+            acquired.setAttribute("role", rc.itemRole);
+            acquired.setAttribute("data-index", String(dataIndex));
+            if (rc.interactive) {
+                acquired.id = rc.prefix + "-item-" + dataIndex;
+                acquired.setAttribute("aria-posinset", String(dataIndex + 1));
+                acquired.setAttribute("aria-setsize", ariaTotal);
+            }
+            if (item !== undefined) {
+                const itemId = String(item.id);
+                acquired.setAttribute("data-id", itemId);
+                if (itemId.startsWith(PLACEHOLDER_ID_PREFIX)) {
+                    acquired.classList.add(rc.placeholderClass);
+                }
+            }
+            if (rc.hasCrossPad) {
+                acquired.style.setProperty(rc.crossStartProp, rc.crossStartVal);
+                acquired.style.setProperty(rc.crossEndProp, rc.crossEndVal);
+            }
+            if (itemStateFn) {
+                acquired.classList.toggle(rc.selectedClass, itemState.selected);
+                acquired.classList.toggle(rc.focusedClass, itemState.focused);
+                if (itemState.selected)
+                    acquired.setAttribute("aria-selected", "true");
+                else
+                    acquired.removeAttribute("aria-selected");
+                acquired._lastSelected = itemState.selected;
+                acquired._lastFocused = itemState.focused;
+            }
+            if (rc.oddClass)
+                acquired.classList.toggle(rc.oddClass, (dataIndex & 1) === 1);
+            const transformOffset = offset + rc.startPadding;
+            acquired.style.transform = rc.translateProp + transformOffset + "px)";
+            acquired._lastOffset = transformOffset;
+            const sizeVal = size - rc.gap;
+            if (rc.horizontal) {
+                acquired.style.width = sizeVal + "px";
+            }
+            else {
+                acquired.style.height = sizeVal + "px";
+            }
+            acquired._lastSize = sizeVal;
+            acquired._lastItem = item;
+            rendered.set(dataIndex, acquired);
+            if (fragment === null)
+                fragment = document.createDocumentFragment();
+            fragment.appendChild(acquired);
+        }
+        else {
+            if (totalChanged) {
+                element.setAttribute("aria-setsize", ariaTotal);
+            }
+            if (item !== undefined && el._lastItem !== item) {
+                const oldId = element.getAttribute("data-id");
+                const newId = String(item.id);
+                let result;
+                try {
+                    result = template(item, dataIndex, itemState);
+                }
+                catch (err) {
+                    if (rc.emitter) {
+                        rc.emitter.emit("error", {
+                            error: err instanceof Error ? err : new Error(String(err)),
+                            context: `template:render:${dataIndex}`,
+                        });
+                    }
+                    continue;
+                }
+                if (typeof result === "string") {
+                    element.innerHTML = result;
+                }
+                else {
+                    element.innerHTML = "";
+                    element.appendChild(result);
+                }
+                element.setAttribute("data-id", newId);
+                el._lastItem = item;
+                if (oldId !== newId) {
+                    const wasPlaceholder = oldId !== null && oldId.startsWith(PLACEHOLDER_ID_PREFIX);
+                    const isPlaceholder = newId.startsWith(PLACEHOLDER_ID_PREFIX);
+                    if (wasPlaceholder !== isPlaceholder) {
+                        element.classList.toggle(rc.placeholderClass, isPlaceholder);
+                    }
+                    if (wasPlaceholder && !isPlaceholder) {
+                        element.classList.add(rc.replacedClass);
+                        setTimeout(() => { element.classList.remove(rc.replacedClass); }, 300);
+                    }
+                }
+            }
+            if (itemStateFn) {
+                if (el._lastSelected !== itemState.selected) {
+                    element.classList.toggle(rc.selectedClass, itemState.selected);
+                    if (itemState.selected)
+                        element.setAttribute("aria-selected", "true");
+                    else
+                        element.removeAttribute("aria-selected");
+                    el._lastSelected = itemState.selected;
+                }
+                if (el._lastFocused !== itemState.focused) {
+                    element.classList.toggle(rc.focusedClass, itemState.focused);
+                    el._lastFocused = itemState.focused;
+                }
+            }
+            const transformOffset = offset + rc.startPadding;
+            if (el._lastOffset !== transformOffset) {
+                element.style.transform = rc.translateProp + transformOffset + "px)";
+                el._lastOffset = transformOffset;
+            }
+            const sizeVal = size - rc.gap;
+            if (el._lastSize !== sizeVal) {
+                if (rc.horizontal) {
+                    element.style.width = sizeVal + "px";
+                }
+                else {
+                    element.style.height = sizeVal + "px";
+                }
+                el._lastSize = sizeVal;
+            }
+        }
+    }
+    // Flush all new elements in one DOM operation
+    if (fragment !== null)
+        contentElement.appendChild(fragment);
+    // Release nodes no longer visible (after acquire so new elements are in the
+    // DOM before stale ones are removed — no single-frame gaps).
+    _relIndices = newIndices;
+    _relCount = count;
+    _relPool = pool;
+    _relRendered = rendered;
+    rendered.forEach(releaseIfNotVisible);
+    if (rc.interactive)
+        state.prevAriaTotal = state.totalItems;
+    runCommitHooks(hooks.commit, state);
+}
+// =============================================================================
+// Full Render Cycle
+// =============================================================================
+export function render(state, sizeCache, overscan, pool, contentElement, template, getItems, rendered, rc, hooks, getItemFn, itemStateFn) {
+    const changed = phase1Calculate(state, sizeCache, overscan, hooks, rc.startPadding);
+    if (changed) {
+        phase2Commit(state, pool, contentElement, template, getItems, rendered, rc, hooks, getItemFn, itemStateFn);
+    }
+}

package/dist/core/pool.d.ts

@@ -0,0 +1,9 @@
+/**
+ * vlist v2 — Element Pool
+ *
+ * acquire() = pop or create, release() = reset + push.
+ * Max pool size: 100.
+ */
+import type { ElementPool } from "./types";
+export declare function createPool(classPrefix: string): ElementPool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/core/pool.js

@@ -0,0 +1,42 @@
+/**
+ * vlist v2 — Element Pool
+ *
+ * acquire() = pop or create, release() = reset + push.
+ * Max pool size: 100.
+ */
+const MAX_POOL_SIZE = 100;
+export function createPool(classPrefix) {
+    const pool = [];
+    const itemClass = `${classPrefix}-item`;
+    const tpl = document.createElement("div");
+    tpl.className = itemClass;
+    return {
+        acquire() {
+            if (pool.length > 0) {
+                return pool.pop();
+            }
+            return tpl.cloneNode(false);
+        },
+        release(element) {
+            element.className = itemClass;
+            element.removeAttribute("style");
+            element.removeAttribute("id");
+            element.removeAttribute("role");
+            element.removeAttribute("aria-selected");
+            element.removeAttribute("aria-posinset");
+            element.removeAttribute("aria-setsize");
+            element.removeAttribute("data-index");
+            element.removeAttribute("data-id");
+            element.innerHTML = "";
+            if (pool.length < MAX_POOL_SIZE) {
+                pool.push(element);
+            }
+        },
+        get size() {
+            return pool.length;
+        },
+        clear() {
+            pool.length = 0;
+        },
+    };
+}

package/dist/core/scroll.d.ts

@@ -0,0 +1,32 @@
+/**
+ * vlist v2 — Scroll Handling
+ *
+ * Wheel interception for synchronous rendering, scroll idle detection,
+ * and smooth scroll animation.
+ */
+import type { EngineState } from "./state";
+export interface ScrollHandler {
+    /** Attach scroll and wheel listeners */
+    attach(): void;
+    /** Detach all listeners */
+    detach(): void;
+    /** Cancel smooth scroll animation */
+    cancelScroll(): void;
+    /** Animate to a target scroll position */
+    smoothScrollTo(target: number, duration: number, setFn?: (pos: number) => void, easing?: (t: number) => number): void;
+}
+export interface ScrollHandlerConfig {
+    readonly state: EngineState;
+    readonly viewport: HTMLElement;
+    readonly horizontal: boolean;
+    readonly wheelEnabled: boolean;
+    readonly idleTimeout: number;
+    /** Override the event target for scroll/wheel listeners (default: viewport) */
+    readonly scrollTarget?: EventTarget;
+    /** Called synchronously on scroll — triggers the 2-phase pipeline */
+    readonly onFrame: () => void;
+    /** Called when scrolling becomes idle */
+    readonly onIdle: () => void;
+}
+export declare function createScrollHandler(config: ScrollHandlerConfig): ScrollHandler;
+//# sourceMappingURL=scroll.d.ts.map