vlist 2.2.0 → 2.4.0

package/README.github.md

@@ -1,8 +1,8 @@
 # vlist
 
-The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 8.0 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.7 KB.
 
-**v2.2.0** — [Changelog](./CHANGELOG.md) · Table `fillWidth` (fills the container by default), async loading resilience (reload keeps placeholders, auto-retry with backoff), table placeholder skeletons.
+**v2.4.0** — [Changelog](./CHANGELOG.md) · **New:** Bounded logical scroll model for 1M+ items (`scroll: { mode: "bounded" }`), `carousel()` plugin with infinite loop, snap, and focal scaling. `scale()` deprecated.
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.com/package/vlist)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/vlist)](https://bundlephobia.com/package/vlist)
@@ -11,9 +11,9 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 - **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core with tiny adapters for Vue, Svelte, Solid, React
-- **8.0 KB gzipped** — composable plugins with perfect tree-shaking
+- **9.7 KB gzipped** — composable plugins with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
-- **Tree, grid, masonry, table, groups, data, selection, sortable, transition, scale** — all opt-in
+- **Tree, grid, masonry, carousel, table, groups, data, selection, search, sortable, transition** — all opt-in
 - **Axis-neutral** — vertical and horizontal scrolling through a single code path, all plugins work in both orientations
 
 **18 interactive examples, docs & benchmarks → [vlist.io](https://vlist.io)**
@@ -94,20 +94,21 @@ const list = createVList({
 
 | Plugin | Size | Description |
 |--------|------|-------------|
-| **Base** | 8.0 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| **Base** | 9.7 KB | Virtualization, ARIA, keyboard nav, gap, padding, bounded scroll (1M+ items) |
 | `data()` | +4.8 KB | Lazy loading with velocity-aware fetching |
-| `selection()` | +2.5 KB | Single/multiple selection with 2D keyboard nav |
-| `scale()` | +3.9 KB | 1M+ items via scroll compression |
-| `groups()` | +5.2 KB | Sticky/inline headers with grid + masonry + table + data integration |
+| `selection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
+| `search()` | +3.2 KB | Search bar: filter/navigate modes, match highlighting |
+| `groups()` | +5.3 KB | Sticky/inline headers with grid + masonry + table + data integration |
 | `autosize()` | +0.8 KB | Auto-measure items via ResizeObserver |
 | `scrollbar()` | +2.0 KB | Custom scrollbar UI |
-| `grid()` | +2.9 KB | 2D grid layout |
-| `masonry()` | +3.7 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `table()` | +6.2 KB | Data table with columns, resize, sort |
-| `tree()` | +5.3 KB | Collapsible tree with async loading and indent guides |
+| `grid()` | +2.4 KB | 2D grid layout |
+| `masonry()` | +4.0 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `carousel()` | +2.3 KB | Paged horizontal carousel with snap and keyboard nav |
+| `table()` | +5.8 KB | Data table with columns, resize, sort |
+| `tree()` | +5.0 KB | Collapsible tree with async loading and indent guides |
 | `page()` | +0.8 KB | Window-level scrolling |
-| `sortable()` | +2.9 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.3 KB | Scroll position save/restore |
+| `sortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
+| `snapshots()` | +1.1 KB | Scroll position save/restore |
 | `transition()` | +1.8 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Examples
@@ -215,6 +216,24 @@ const list = createVList({
 ])
 ```
 
+### Search
+
+```typescript
+import { createVList, search } from 'vlist'
+import 'vlist/styles/search'
+
+const list = createVList({
+  container: '#app',
+  items: people,
+  item: { height: 48, template: renderPerson },
+}, [
+  // Zero-config: a search bar at the top, Ctrl/⌘+F to focus, type to filter,
+  // matches highlighted with <mark>. Use mode: 'navigate' to jump between
+  // matches instead of hiding non-matches.
+  search(),
+])
+```
+
 ## Accessibility
 
 Every vlist is accessible by default following the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):
@@ -305,7 +324,6 @@ selection({ mode: 'single' | 'multiple', initial?: [...ids] })
 data({ adapter: { read }, loading?: { cancelThreshold? } })
 table({ columns, rowHeight, headerHeight?, resizable? })
 autosize()                        // auto-measure items (requires estimatedHeight)
-scale()                           // auto-activates at 16.7M px
 scrollbar({ autoHide?, autoHideDelay?, minThumbSize? })
 transition({ duration?: 200, insert?: timing, remove?: timing })
 sortable({ handle?: '.drag-handle' })  // drag-and-drop reordering

package/README.md

@@ -1,8 +1,8 @@
 # vlist
 
-The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 8.0 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins — in 9.7 KB.
 
-**v2.2.0** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md) · **New:** table `fillWidth` (fills the container by default), async loading resilience (reload keeps placeholders, auto-retry with backoff), and table placeholder skeletons.
+**v2.4.0** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md) · **New:** Bounded logical scroll model for 1M+ items (`scroll: { mode: "bounded" }`), `carousel()` plugin with infinite loop, snap, and focal scaling. `scale()` deprecated.
 
 [![npm version](https://img.shields.io/npm/v/vlist.svg)](https://www.npmjs.com/package/vlist)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/vlist)](https://bundlephobia.com/package/vlist)
@@ -11,7 +11,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 - **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
-- **8.0 KB gzipped** — composable plugins with perfect tree-shaking
+- **9.7 KB gzipped** — composable plugins with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **Axis-neutral** — vertical and horizontal scrolling through a single code path, all plugins work in both orientations
 
@@ -56,19 +56,21 @@ const list = createVList({ container: '#app', items, item: { height: 200, templa
 
 | Plugin | Size | Description |
 |--------|------|-------------|
-| **Base** | 8.0 KB | Virtualization, ARIA, keyboard nav, gap, padding |
+| **Base** | 9.7 KB | Virtualization, ARIA, keyboard nav, gap, padding, bounded scroll (1M+ items) |
 | `data()` | +4.8 KB | Lazy loading with velocity-aware fetching |
-| `selection()` | +2.5 KB | Single/multiple selection with 2D keyboard nav |
-| `scale()` | +3.9 KB | 1M+ items via scroll compression |
-| `groups()` | +5.2 KB | Sticky/inline headers with grid + masonry + table + data integration |
+| `selection()` | +2.7 KB | Single/multiple selection with 2D keyboard nav |
+| `search()` | +3.2 KB | Search bar: filter/navigate modes, match highlighting |
+| `groups()` | +5.3 KB | Sticky/inline headers with grid + masonry + table + data integration |
 | `autosize()` | +0.8 KB | Auto-measure items via ResizeObserver |
 | `scrollbar()` | +2.0 KB | Custom scrollbar UI |
-| `grid()` | +2.9 KB | 2D grid layout |
-| `masonry()` | +3.7 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `table()` | +6.2 KB | Data table with columns, resize, sort |
+| `grid()` | +2.4 KB | 2D grid layout |
+| `masonry()` | +4.0 KB | Pinterest-style masonry with lane-aware keyboard nav |
+| `carousel()` | +2.3 KB | Paged horizontal carousel with snap and keyboard nav |
+| `table()` | +5.8 KB | Data table with columns, resize, sort |
+| `tree()` | +5.0 KB | Collapsible tree with async loading and indent guides |
 | `page()` | +0.8 KB | Window-level scrolling |
-| `sortable()` | +2.9 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.3 KB | Scroll position save/restore |
+| `sortable()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
+| `snapshots()` | +1.1 KB | Scroll position save/restore |
 | `transition()` | +1.8 KB | FLIP-based enter/exit animations for insert & remove |
 
 ## Framework Adapters

package/dist/constants.d.ts

@@ -45,6 +45,34 @@ export declare const WHEEL_SENSITIVITY = 1;
 export declare const SCROLL_EASING: (t: number) => number;
 /** Default smooth scroll duration (ms) */
 export declare const SCROLL_DURATION = 300;
+/**
+ * Runway size as a multiple of the viewport. The bounded content element is
+ * sized to `containerSize × this` (capped at total size), giving the native
+ * scrollbar room to move before a rebase shifts the logical origin.
+ */
+export declare const BOUNDED_RUNWAY_FACTOR = 2;
+/**
+ * Minimum runway multiple. The runway must exceed the viewport so native scroll
+ * and touch/trackpad momentum have room before a rebase; below this there would
+ * be little-to-no native scrollable range. User-supplied `scroll.runway` values
+ * are clamped up to this floor.
+ *
+ * 1.5 keeps a half-viewport of native scroll travel — enough for the native
+ * scrollbar and most touch gestures. The wheel/trackpad path is already fully
+ * synthetic (driven in logical space), so it is unaffected by the runway size;
+ * a small runway only risks interrupting native touch momentum at the edges.
+ */
+export declare const BOUNDED_RUNWAY_MIN = 1.5;
+/**
+ * Lower rebase trigger: when native scrollTop drops below this fraction of the
+ * runway (and we are not already at the logical start), shift the origin back.
+ */
+export declare const BOUNDED_REBASE_LOW = 0.25;
+/**
+ * Upper rebase trigger: when native scrollTop rises above this fraction of the
+ * runway (and we are not already at the logical end), shift the origin forward.
+ */
+export declare const BOUNDED_REBASE_HIGH = 0.75;
 /** Default auto-hide behavior */
 export declare const SCROLLBAR_AUTO_HIDE = true;
 /** Default auto-hide delay in milliseconds */

package/dist/core/adapter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * vlist — Logical Scroll Model (RFC-012)
+ *
+ * The scroll coordinate is logical, not a physical pixel offset into a giant
+ * container: `{ index, offsetPx }` — the top visible item plus the pixel offset
+ * within it. This is stable under variable and autosized items, because the
+ * pixel offset stays physically meaningful when an item's measured size changes
+ * (unlike a fraction, which silently shifts the visual position).
+ *
+ * The pixel equivalent (`index * itemSize + offsetPx` generalised over the size
+ * cache) is derived only at the public API boundary, so existing consumers of
+ * `getScrollPosition()` and scroll events keep seeing pixel values (RFC-012 G4).
+ *
+ * This module is pure: it owns no DOM and no engine state. It is the translation
+ * layer the `ScrollAdapter` and the render pipeline build on.
+ */
+import type { SizeCache } from "../rendering/sizes";
+/**
+ * Logical scroll position: the top visible data item plus the pixel offset
+ * scrolled past its leading edge.
+ *
+ * Invariant after {@link normalizeLogical}: `0 <= offsetPx < size(index)`
+ * (except at the list end, where `offsetPx` may exceed the final item to
+ * represent overscroll clamping).
+ */
+export interface LogicalScrollPosition {
+    /** Index of the top visible item (integer, clamped to `[0, total - 1]`). */
+    index: number;
+    /** Pixel offset scrolled past the leading edge of `index`. */
+    offsetPx: number;
+}
+/**
+ * The migration boundary between the logical scroll model and the rest of the
+ * engine and its plugins (RFC-012). Plugins read and write scroll position
+ * through this adapter rather than touching `engineState.scrollPosition` or raw
+ * DOM `scrollTop` / `scrollLeft` directly.
+ *
+ * It exposes both the logical primitive and a pixel-equivalent view so existing
+ * pixel-based code paths keep working during migration.
+ */
+export interface ScrollAdapter {
+    /** Current logical position, normalized. */
+    getLogical(): LogicalScrollPosition;
+    /** Move to a logical position. Out-of-range input is clamped. */
+    setLogical(pos: LogicalScrollPosition): void;
+    /** Pixel-equivalent of the current position (for public API / events). */
+    getPixelEquivalent(): number;
+    /** Move to a pixel-equivalent position. Out-of-range input is clamped. */
+    setPixelEquivalent(px: number): void;
+    /** Maximum scrollable pixel-equivalent (`totalSize - containerSize`, >= 0). */
+    getMaxPixelEquivalent(): number;
+    /** Advance the position by a pixel delta (used by native/wheel input). */
+    scrollByPx(delta: number): void;
+}
+/** Dependencies an adapter needs to translate and apply scroll positions. */
+export interface ScrollAdapterConfig {
+    /** Source of item offsets and sizes. */
+    readonly sizeCache: SizeCache;
+    /** Read the current pixel-equivalent position from the active scroll source. */
+    readonly getPixel: () => number;
+    /** Write a (clamped) pixel-equivalent position to the active scroll source. */
+    readonly setPixel: (px: number) => void;
+    /** Current viewport size along the main axis. */
+    readonly getContainerSize: () => number;
+}
+/**
+ * Convert a pixel offset into a logical position. The returned position is
+ * normalized: `index` is clamped to `[0, total - 1]` and `offsetPx` is the
+ * remainder past that item's leading edge.
+ */
+export declare function pixelToLogical(sizeCache: SizeCache, pixel: number): LogicalScrollPosition;
+/**
+ * Convert a logical position into a pixel offset. Input is normalized first,
+ * so callers may pass an `offsetPx` that overflows its item.
+ */
+export declare function logicalToPixel(sizeCache: SizeCache, pos: LogicalScrollPosition): number;
+/**
+ * Canonicalize a logical position so that `0 <= offsetPx < size(index)` where
+ * possible, carrying overflow/underflow across item boundaries. `index` is
+ * clamped to `[0, total - 1]`. At the list end, any remaining `offsetPx` is
+ * preserved (it represents scrolling past the start of the final item).
+ */
+export declare function normalizeLogical(sizeCache: SizeCache, pos: LogicalScrollPosition): LogicalScrollPosition;
+/**
+ * Create a {@link ScrollAdapter} over an existing pixel-based scroll source.
+ *
+ * During migration the underlying source is still the native viewport scroll;
+ * later phases can swap `getPixel` / `setPixel` for a bounded-proxy or
+ * interception input strategy without changing any plugin that uses the adapter.
+ */
+export declare function createScrollAdapter(config: ScrollAdapterConfig): ScrollAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/core/pipeline.d.ts

@@ -33,6 +33,8 @@ export interface RenderConfig {
     readonly crossEndVal: string;
     readonly oddClass: string;
     readonly emitter: Emitter<VListEvents> | null;
+    indexMap: ((renderIndex: number) => number) | null;
+    ariaTotalFn: (() => number) | null;
 }
 export declare function createRenderConfig(classPrefix: string, isX: boolean, startPadding: number, crossPadStart: number, crossPadEnd: number, oddClass: string, gap: number, emitter?: Emitter<VListEvents> | null): RenderConfig;
 /**

package/dist/core/runway.d.ts

@@ -0,0 +1,82 @@
+/**
+ * vlist — Bounded Logical Scroll Handler (RFC-012)
+ *
+ * An alternative to the native scroll handler ({@link createScrollHandler}) that
+ * decouples the native scrollable size from the virtual content size.
+ *
+ * The content element is sized to a bounded *runway* (a multiple of the
+ * viewport, capped at the real virtual size) instead of `totalItems × itemSize`.
+ * This sidesteps the browser's ~16.7M px element-size limit without the scale
+ * plugin's compression — no compression ratio leaks into offsets or hit-testing.
+ *
+ * Coordinates:
+ *   logical = baseOffset + scrollTop        (absolute virtual pixel position)
+ *
+ *   - `state.scrollPosition` always holds the *logical* (absolute) position, so
+ *     the render pipeline's `indexAtOffset(scrollPosition)` keeps working over
+ *     the full size cache, and the public pixel-equivalent surface is unchanged.
+ *   - `state.baseOffset` is the virtual offset that maps to native scrollTop=0.
+ *     The pipeline renders each item at `getOffset(index) - baseOffset`, so items
+ *     land inside the bounded runway. baseOffset is 0 for small lists (native).
+ *
+ * Rebasing: as native scrollTop approaches a runway edge we shift baseOffset and
+ * scrollTop together by the same delta, preserving `logical`. The synthetic
+ * scroll event this triggers reads the same logical position and is dropped by
+ * the "logical unchanged" guard — no suppress flag needed. The repositioning of
+ * items (their transforms depend on baseOffset) is committed by the explicit
+ * render that the rebasing scroll frame performs.
+ */
+import type { EngineState } from "./state";
+import type { ScrollHandler } from "./scroll";
+export interface BoundedScrollHandler extends ScrollHandler {
+    /** Move to an absolute logical (virtual pixel) position; renders + schedules idle. */
+    setLogical(logicalPx: number): void;
+    /** Current absolute logical position (== state.scrollPosition). */
+    getLogical(): number;
+    /** Maximum scrollable logical position (`virtualTotal - containerSize`, >= 0). */
+    getMaxLogical(): number;
+    /** Recompute runway/derived values and resize the content element. */
+    refresh(totalSize: number): void;
+}
+/**
+ * Infinite-loop (wrap) configuration for the bounded handler (carousel, RFC-011).
+ *
+ * In wrap mode the logical position is never clamped to a maximum: instead it is
+ * periodically folded back toward {@link home} by whole laps once it drifts more
+ * than {@link thresholdLaps} laps away. Because the consumer maps virtual indices
+ * to real items via `index % realTotal`, shifting the logical position (and
+ * baseOffset) by a whole lap leaves the rendered items and their on-screen
+ * positions unchanged — the loop is seamless. The content element is sized to the
+ * runway exactly as in non-wrap mode, so large item counts never blow the
+ * browser's element-size limit.
+ */
+export interface WrapConfig {
+    /** Current lap period in virtual px (`realTotal × stepSize`). */
+    readonly lapSize: () => number;
+    /** Logical position to fold back toward (e.g. the middle cycle). */
+    readonly home: () => number;
+    /** Fold the logical position back toward `home` once it drifts this many laps away. */
+    readonly thresholdLaps: number;
+}
+export interface BoundedScrollConfig {
+    readonly state: EngineState;
+    readonly viewport: HTMLElement;
+    readonly content: HTMLElement;
+    readonly isX: boolean;
+    readonly wheelEnabled: boolean;
+    readonly idleTimeout: number;
+    readonly scrollTarget?: EventTarget;
+    /** Main-axis padding folded into the virtual total (matches native content sizing). */
+    readonly mainAxisPadding: number;
+    /** Runway size as a multiple of the viewport (defaults to BOUNDED_RUNWAY_FACTOR). */
+    readonly runwayFactor?: number;
+    /** Infinite-loop config (carousel). When set, the logical position wraps by
+     *  whole laps toward `home` instead of clamping to a maximum. */
+    readonly wrap?: WrapConfig;
+    /** Called synchronously per frame — triggers the 2-phase pipeline. */
+    readonly onFrame: () => void;
+    /** Called when scrolling becomes idle. */
+    readonly onIdle: () => void;
+}
+export declare function createBoundedScrollHandler(config: BoundedScrollConfig): BoundedScrollHandler;
+//# sourceMappingURL=runway.d.ts.map

package/dist/core/state.d.ts

@@ -24,6 +24,12 @@ export interface EngineState {
     prevScrollPosition: number;
     /** 1 = forward, -1 = backward, 0 = idle */
     scrollDirection: number;
+    /**
+     * Bounded logical-scroll origin (RFC-012). The virtual offset that maps to
+     * native scrollTop=0. Items render at `getOffset(index) - baseOffset`.
+     * Defaults to 0, which makes native mode byte-identical (`offset - 0`).
+     */
+    baseOffset: number;
     containerSize: number;
     crossSize: number;
     totalItems: number;
@@ -32,8 +38,6 @@ export interface EngineState {
     renderPending: boolean;
     initialized: boolean;
     destroyed: boolean;
-    isCompressed: boolean;
-    compressionRatio: number;
     prevAriaTotal: number;
     /**
      * Resize buffers when container changes. Cold path only.

package/dist/core/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { VListItem, ItemTemplate, ItemState } from "../types";
 import type { SizeCache } from "./sizes";
+import type { ScrollAdapter } from "./adapter";
 import type { EngineState } from "./state";
 import type { Emitter } from "../events";
 /** Phase 1 hook — mutates EngineState in place, zero allocation */
@@ -60,6 +61,13 @@ export interface ElementPool {
 export interface PluginContext<T extends VListItem = VListItem> {
     readonly dom: DOMStructure;
     readonly sizeCache: SizeCache;
+    /**
+     * Logical scroll model boundary (RFC-012). Plugins read and write scroll
+     * position through this adapter rather than touching `getState().scrollPosition`
+     * or raw `scrollTop`/`scrollLeft`. Its pixel-equivalent view keeps existing
+     * pixel-based code paths working during the migration.
+     */
+    readonly scroll: ScrollAdapter;
     readonly pool: ElementPool;
     readonly config: ResolvedConfig;
     readonly emitter: Emitter<import("../types").VListEvents<T>>;
@@ -72,7 +80,10 @@ export interface PluginContext<T extends VListItem = VListItem> {
     enableListboxRole(): void;
     setSizeConfig(config: number | ((index: number) => number)): void;
     setScrollFns(get: () => number, set: (pos: number) => void): void;
+    /** Request the bounded scroll handler in infinite-loop (wrap) mode (carousel). */
+    setBoundedWrap(config: import("./runway").WrapConfig): void;
     setVirtualTotalFn(fn: () => number): void;
+    setIndexMapFn(fn: (renderIndex: number) => number): void;
     getItems(): readonly T[];
     getItem(index: number): T | undefined;
     getState(): EngineState;
@@ -87,6 +98,8 @@ export interface PluginContext<T extends VListItem = VListItem> {
     readonly rawSizeSpec: number | ((index: number, ...args: unknown[]) => number);
     scrollTo(position: number): void;
     smoothScrollTo(target: number | (() => number), duration: number, easing?: (t: number) => number, onComplete?: () => void): void;
+    /** Cancel any in-flight smooth-scroll animation on the active handler. */
+    cancelScroll(): void;
     disableDefaultScroll(): void;
     disableDefaultResize(): void;
     setScrollTarget(target: EventTarget): void;
@@ -113,6 +126,7 @@ export interface PluginContext<T extends VListItem = VListItem> {
         lr: number;
         scrollIndex: ((itemIndex: number) => number) | null;
         navigate: ((currentIndex: number, key: string, total: number) => number) | null;
+        total: (() => number) | null;
     };
 }
 export interface VListPlugin<T extends VListItem = VListItem> {
@@ -180,6 +194,23 @@ export interface CreateVListConfig<T extends VListItem = VListItem> {
         scrollbar?: "none";
         gutter?: "auto" | "stable";
         idleTimeout?: number;
+        /**
+         * Scroll model (RFC-012). `"native"` (default) sizes the content element to
+         * the full virtual size — simple, but hits the browser's ~16.7M px limit.
+         * `"bounded"` sizes the content to a viewport-multiple runway and rebases a
+         * logical origin near the edges, supporting unbounded item counts without
+         * compressing the scroll space.
+         */
+        mode?: "native" | "bounded";
+        /**
+         * Runway size as a multiple of the viewport, used only with
+         * `mode: "bounded"` (default 2). The bounded content element is sized to
+         * `viewport × runway` (capped at the real virtual size). Larger values mean
+         * more native-scroll headroom and less frequent rebasing, at the cost of a
+         * bigger content element. Clamped up to a minimum of 1.5 so native scroll and
+         * touch momentum always have some room.
+         */
+        runway?: number;
     };
     /** Defer initial render to the next animation frame. */
     defer?: boolean;

package/dist/index.d.ts

@@ -9,8 +9,6 @@
  * @packageDocumentation
  */
 export { createVList } from "./core/create";
-export { scale } from "./plugins/scale";
-export type { ScalePluginConfig } from "./plugins/scale";
 export { scrollbar } from "./plugins/scrollbar";
 export type { ScrollbarPluginConfig } from "./plugins/scrollbar";
 export { grid } from "./plugins/grid";
@@ -37,6 +35,13 @@ export { sortable } from "./plugins/sortable";
 export type { SortablePluginConfig } from "./plugins/sortable";
 export { tree } from "./plugins/tree";
 export type { TreePluginConfig, FlatNode } from "./plugins/tree";
+export { search, DEFAULT_SEARCH_TEXT } from "./plugins/search";
+export type { SearchPluginConfig, SearchText } from "./plugins/search";
+export { carousel } from "./plugins/carousel";
+export type { CarouselPluginConfig, CarouselVariant, CarouselDirection, CarouselState } from "./plugins/carousel";
+/** @deprecated Use `scroll: { mode: "bounded" }` instead. Will be removed in vlist 3.0. */
+export { scale } from "./plugins/scale";
+export type { ScalePluginConfig } from "./plugins/scale";
 export { createStats } from "./utils/stats";
 export type { Stats, StatsConfig, StatsState } from "./utils/stats";
 export { rebuild } from "./utils/rebuild";