vlist 2.8.1 → 3.0.0-next.2

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 9.9 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v2.8.1** — [Changelog](./CHANGELOG.md) · deprecation notices corrected for the revised 3.0 shape (native stays the default, synthetic input stays opt-in, the scrollbar strings are not deprecated); carousel slots follow container resizes; prerelease-aware publish workflow.
+**v3.0.0-next.2** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
 
 [![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 with tiny adapters for Vue, Svelte, Solid, React
-- **9.9 KB gzipped** — composable plugins with perfect tree-shaking
+- **9.3 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
 - **Constant memory** — ~0.1 MB overhead at any scale, from 10K to 1M+ items
 - **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
@@ -42,10 +42,11 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 ```bash
 npm install vlist              # vanilla JS
+npm install vlist@next         # 3.0 prerelease; latest stays on 2.8
 npm install vlist vlist-vue    # or vlist-svelte / vlist-solidjs / vlist-react
 ```
 
-With vlist 2.8 and an adapter that forwards the `factory` option, opt into synthetic input explicitly:
+Adapters use native scrolling by default. With an adapter that forwards `factory`, select synthetic input explicitly:
 
 ```ts
 import { useVList } from "vlist-react";
@@ -53,13 +54,12 @@ import { createVList } from "vlist/synthetic";
 
 useVList({
   factory: createVList,
-  scroll: { mode: "synthetic" },
   items,
   item: { height: 48, template: item => String(item.id) },
 });
 ```
 
-The same factory option is available to the other adapters. `vlist/config` keeps the synthetic driver out of its default bundle; importing the factory opts in. The factory is structural configuration: changing it requires recreating the list.
+The same factory option is available to the other adapters. `vlist/config` defaults to native scrolling. The factory is structural configuration: changing it requires recreating the list.
 
 ## Quick Start
 
@@ -106,11 +106,19 @@ const list = createVList({
 ])
 ```
 
-## Synthetic scroll input
+## Scroll input
 
-The opt-in `vlist/synthetic` entry adds `scroll.mode: 'synthetic'` alongside native and bounded modes. Native remains the default. Import the factory from this entry and plugins from `vlist`:
-Bounded mode note: on touch devices a long native fling can outrun the 2x runway and stall at its edge (measured at 145-226% of a 16x runway on an iPhone SE and a Pixel 8a). Prefer synthetic mode for touch-heavy lists; bounded remains the right choice for wheel and keyboard driven lists.
+Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel, sortable and horizontal RTL lists work with this factory. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
 
+| Entry | Input model | Use |
+|---|---|---|
+| `vlist` | Native (default) | Browser scrolling and all supported plugins |
+| `vlist/synthetic` | Synthetic (opt-in) | Huge lists and application-owned touch motion |
+| `vlist/native` | Alias of `vlist` (deprecated) | Compatibility with `3.0.0-next.1`; use `vlist` for new code |
+
+### Synthetic input
+
+Select synthetic input by importing its factory; there is no `scroll.mode` option. Plugins still come from `vlist`.
 
 ```typescript
 import { createVList } from 'vlist/synthetic'
@@ -121,56 +129,60 @@ const list = createVList({
   container: '#my-list',
   items: Array.from({ length: 1000 }, (_, id) => ({ id, name: `Row ${id}` })),
   item: { height: 48, template: item => `<div>${item.name}</div>` },
-  scroll: { mode: 'synthetic' },
 }, [scrollbar()])
 ```
 
-Supported plugins are **table, groups, snapshots, scrollbar, autosize, transition, selection and a11y**. Existing plugin conflicts still apply; this list does not imply that all eight can be combined. `page()`, `carousel()` and `sortable()` throw when configured with synthetic mode. Carousel uses wrap scrolling, which this release does not support with synthetic input.
+`page()` uses native document scrolling through an external source with either entry. Its content must fit the 16,777,216 px document element limit; creation throws above that limit when the size is known, and later growth warns once. A deferred custom renderer whose size is first committed during rendering also warns once. Use `vlist/synthetic` viewport scrolling for larger lists. Default native viewport lists warn once when content exceeds their browser-size safety limit, pointing to that entry.
 
-Known limitations:
+Synthetic input limitations:
 
-- RTL horizontal lists throw in synthetic mode in this release; use native mode. Vertical lists on RTL pages are supported. RTL support for the synthetic driver is planned as a non-breaking addition.
-- Same-axis touch stops at either boundary with no parent handoff, including gestures that start inside an edge-pinned list. Use native mode when touch gestures must scroll the parent page at a boundary.
-- The native main-axis scrollbar is absent. Provide a custom scrollbar, such as `scrollbar()` above. Its accessibility release gate remains open; synthetic mode is not a completed scrollbar-accessibility sign-off.
+- `carousel()`, `sortable()` and horizontal RTL lists throw with instructions to use `vlist`. Vertical lists and tables support `dir="rtl"`, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
+- Same-axis touch stops at either boundary with no parent handoff, including gestures starting inside an edge-pinned list. Use the native default when boundary gestures must scroll the parent page.
+- There is no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar. The synthetic entry rejects the `"native"` and `"none"` scrollbar strings.
 - Inertia initializes its frame clock on the first frame after release, adding up to one frame of release latency.
 - Wheel input at an edge is left to the page when it cannot move the list. Native cross-axis scrolling remains available.
 
-Measurement corrections from autosize preserve ongoing motion. Synthetic input adds **2.6 KB gzipped** over the base entry (**12.5 KB** total before plugins); ordinary `vlist` imports exclude this driver. See [RFC-014](https://github.com/floor/vlist/discussions/127).
+Measurement corrections from autosize preserve ongoing synthetic motion. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
 
-## Deprecated in 2.8, removed in 3.0
+## Migrating to 3.0
 
-These notices prepare the 3.0 migration; 2.x behavior and defaults stay unchanged. Native scrolling stays the default in 3.0, and synthetic input stays the opt-in `vlist/synthetic` entry. Bounded mode remains supported in 2.x, including carousel and sortable; it emits no deprecation warning.
+`3.0.0-next.1` used synthetic input by default. `3.0.0-next.2` restores the 2.x default. Import `vlist/synthetic` explicitly to retain synthetic behavior across these prereleases. `vlist/native` remains a deprecated compatibility alias; its `NativeScrollConfig` and `NativeCreateVListConfig` types alias the standard `ScrollConfig` and `CreateVListConfig`.
 
-| Option or API | In 3.0 | Since |
-|---|---|---|
-| `scroll.mode` | Removed. `vlist` is native by default; for lists beyond the browser's element size limit, import `createVList` from `vlist/synthetic` instead of using bounded mode. | 2.8 |
-| `scroll.runway` | Removed with bounded mode. | 2.8 |
-| `PluginContext.setScrollFns`, `disableDefaultScroll` | Removed; use `setScrollSource`. | 2.8 |
-| `scale()` | Removed; use `vlist/synthetic` for huge lists. | 2.4 |
+| 2.x option or API | 3.0 replacement |
+|---|---|
+| `scroll.mode` (all values, both entries) | Omit it. `vlist` provides native scrolling; import `vlist/synthetic` for synthetic input. |
+| `scroll.runway` (both entries) | Remove it. For huge lists use `vlist/synthetic`, which needs no native runway. |
+| `scroll.scrollbar: "native"` or `"none"` | Retained in default `ScrollConfig`. With synthetic input, omit the string and optionally install `scrollbar()`. |
+| `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `setScrollSource` to supply an external position source and commit callback. |
+| `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-`scroll.scrollbar: "native"` and `"none"` are not deprecated: they stay available on the native default in 3.0. Only explicit `scale()` calls warn, once per process, and 3.0's `vlist/config` no longer installs the scale compatibility stub. Release 2.8.0 described native scrolling and the scrollbar strings as moving to a `vlist/native` entry in 3.0; that plan was revised. See the [v2 to v3 migration guide](https://vlist.io/docs/migration-v3).
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` retains scrollbar omission/options convenience and its top-level `scrollbar: "none"` option. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.setBoundedWrap`.
 
 ## Plugins
 
-| Plugin | Size | Description |
-|--------|------|-------------|
-| **Base** | 9.9 KB | Virtualization, ARIA, keyboard nav, gap, padding, bounded scroll (1M+ items) |
-| `vlist/synthetic` entry | +2.6 KB | Opt-in synthetic scroll input (12.5 KB total before plugins) |
-| `data()` | +4.8 KB | Lazy loading with velocity-aware fetching |
-| `selection()` | +2.8 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()` | +1.0 KB | Auto-measure items via ResizeObserver |
-| `scrollbar()` | +2.0 KB | Custom scrollbar UI |
-| `grid()` | +2.5 KB | 2D grid layout |
-| `masonry()` | +4.1 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `carousel()` | +3.6 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()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.2 KB | Scroll position save/restore |
-| `transition()` | +2.0 KB | FLIP-based enter/exit animations for insert & remove |
+| Entry / export | Minified | Gzipped |
+|---|---:|---:|
+| **Base (`vlist`)** | 25.4 KB | 9.3 KB |
+| `vlist/synthetic` | 31.1 KB | 11.4 KB |
+| `vlist/native` (alias) | 25.4 KB | 9.3 KB |
+| `a11y()` | 28.7 KB | 10.5 KB |
+| `selection()` | 34.8 KB | 12.1 KB |
+| `data()` | 39.0 KB | 14.1 KB |
+| `scrollbar()` | 33.6 KB | 12.2 KB |
+| `sortable()` | 34.9 KB | 12.2 KB |
+| `groups()` | 41.3 KB | 14.6 KB |
+| `page()` | 27.9 KB | 10.2 KB |
+| `snapshots()` | 28.7 KB | 10.4 KB |
+| `transition()` | 32.1 KB | 11.3 KB |
+| `autosize()` | 28.5 KB | 10.3 KB |
+| `grid()` | 32.5 KB | 11.8 KB |
+| `table()` | 43.8 KB | 15.2 KB |
+| `masonry()` | 36.8 KB | 13.4 KB |
+| `tree()` | 40.6 KB | 14.3 KB |
+| `search()` | 34.5 KB | 12.4 KB |
+| `carousel()` | 38.0 KB | 13.7 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **9,523 bytes gzipped**, below the 9.9 KB target; synthetic input is **11,687 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Examples
 
@@ -295,6 +307,64 @@ const list = createVList({
 ])
 ```
 
+## Custom scrollbar (3.0 preview)
+
+On `next`, `scrollbar()` remains a plugin. macOS and Android default to thin,
+rounded, auto-hiding overlays; Windows defaults to a wider, square, always-visible
+bar. Set `gutter: true` to reserve space. The same behavior works horizontally.
+
+```typescript
+scrollbar({
+  platform: 'windows',        // optional: macos | windows | android
+  width: 'thin',              // optional: pixels (number) | auto | thin | none
+  radius: 4,                  // optional: thumb radius in pixels
+  thumbColor: '#666',         // optional explicit colors
+  trackColor: '#eee',
+  gutter: true,
+})
+```
+
+Without explicit overrides, the plugin reads the container's standard
+`scrollbar-width` and `scrollbar-color`. `auto` uses the platform width; `thin`
+uses 6 px; `none` disables the track, hover target and gutter. Color order is
+thumb then track. Numeric `width` and `radius` override the corresponding
+`--vlist-custom-scrollbar-width` and `--vlist-custom-scrollbar-radius` variables
+on the container; those variables override platform defaults. Without a custom
+width variable, the width keywords retain their standard meaning (`none` always
+disables the bar). Explicit colors override author standard colors. `autoHide`, `autoHideDelay` and `minThumbSize` remain available.
+After changing author CSS, call `list.refreshScrollbar()` (or `refresh()` on a
+standalone `Scrollbar` instance). Refresh rereads CSS; platform selection remains
+fixed for that instance. Setting `enabled: false` disables the plugin's bar.
+
+The focusable track exposes its controlled viewport, orientation, logical range,
+and “Row N of M” value. Arrows move one row along the active axis, PageUp/PageDown
+move a viewport, and Home/End reach the bounds. Focus keeps the bar visible.
+Forced-color themes use system colors for the track, thumb and focus indicator.
+The thumb has a minimum size even for millions of rows; drag positions continue
+to use the full logical range. The real screen-reader acceptance pass is still
+pending; this is not a completed accessibility sign-off.
+
+### Migrating WebKit scrollbar selectors
+
+**The `::-webkit-scrollbar*` pseudo-elements are not mirrored.** They style
+browser-owned scrollbars, not this plugin's DOM. Migrate each rule as follows
+(the classes shown use the default `vlist` prefix):
+
+| Existing selector | Plugin replacement |
+| --- | --- |
+| `::-webkit-scrollbar` | `.vlist-scrollbar`; `--vlist-custom-scrollbar-width` for thickness |
+| `::-webkit-scrollbar-track` | `.vlist-scrollbar`; `--vlist-custom-scrollbar-track-color` |
+| `::-webkit-scrollbar-thumb` | `.vlist-scrollbar__thumb`; `--vlist-custom-scrollbar-thumb-color`, `--vlist-custom-scrollbar-radius`, `--vlist-custom-scrollbar-min-thumb-size` |
+| `::-webkit-scrollbar-thumb:hover` | `.vlist-scrollbar__thumb:hover`; `--vlist-custom-scrollbar-thumb-hover-color` |
+| `::-webkit-scrollbar-corner` | No separate corner element. Reserved gutter space uses the `.vlist` background (`--vlist-bg`). A dedicated corner rule has no direct equivalent. |
+| `::-webkit-scrollbar-button` | No arrow-button elements or direct styling equivalent. Use the scrollbar's row keys or track paging; custom buttons must be separate controls. |
+
+For width and base thumb/track colors, prefer standard `scrollbar-width` and
+`scrollbar-color` on the container, or plugin config. The plugin maps these onto
+its custom properties at setup/refresh. Use the plugin classes and remaining
+variables for radius, minimum thumb size and hover styling. High-contrast system
+colors take priority while forced colors are active.
+
 ## Accessibility
 
 Every vlist is accessible by default following the [WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):

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 9.9 KB.
+The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v2.8.1** — [Changelog](https://github.com/floor/vlist/blob/main/CHANGELOG.md) · deprecation notices corrected for the revised 3.0 shape (native stays the default, synthetic input stays opt-in, the scrollbar strings are not deprecated); carousel slots follow container resizes; prerelease-aware publish workflow.
+**v3.0.0-next.2** (prerelease on the npm `next` tag) — Native scrolling by default, opt-in `vlist/synthetic`, and removal of deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
 
 [![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
-- **9.9 KB gzipped** — composable plugins with perfect tree-shaking
+- **9.3 KB gzipped (3.0 prerelease)** — 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
 
@@ -19,6 +19,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 ```bash
 npm install vlist
+npm install vlist@next   # 3.0 prerelease; latest stays on 2.8
 ```
 
 ## Quick Start
@@ -52,11 +53,19 @@ const list = createVList({ container: '#app', items, item: { height: 200, templa
 ])
 ```
 
-## Synthetic scroll input
+## Scroll input
 
-The opt-in `vlist/synthetic` entry adds `scroll.mode: 'synthetic'` alongside native and bounded modes. Native remains the default. Import the factory from this entry and plugins from `vlist`:
-Bounded mode note: on touch devices a long native fling can outrun the 2x runway and stall at its edge (measured at 145-226% of a 16x runway on an iPhone SE and a Pixel 8a). Prefer synthetic mode for touch-heavy lists; bounded remains the right choice for wheel and keyboard driven lists.
+Native scrolling is the default: import `createVList` and plugins from `vlist`. This preserves browser scrollbars, native touch momentum, boundary handoff and native assistive-technology scrolling. Carousel, sortable and horizontal RTL lists work with this factory. Carousel supplies its private wrap runway only when the plugin is imported; bounded scrolling is no longer a public mode.
 
+| Entry | Input model | Use |
+|---|---|---|
+| `vlist` | Native (default) | Browser scrolling and all supported plugins |
+| `vlist/synthetic` | Synthetic (opt-in) | Huge lists and application-owned touch motion |
+| `vlist/native` | Alias of `vlist` (deprecated) | Compatibility with `3.0.0-next.1`; use `vlist` for new code |
+
+### Synthetic input
+
+Select synthetic input by importing its factory; there is no `scroll.mode` option. Plugins still come from `vlist`.
 
 ```typescript
 import { createVList } from 'vlist/synthetic'
@@ -67,56 +76,60 @@ const list = createVList({
   container: '#my-list',
   items: Array.from({ length: 1000 }, (_, id) => ({ id, name: `Row ${id}` })),
   item: { height: 48, template: item => `<div>${item.name}</div>` },
-  scroll: { mode: 'synthetic' },
 }, [scrollbar()])
 ```
 
-Supported plugins are **table, groups, snapshots, scrollbar, autosize, transition, selection and a11y**. Existing plugin conflicts still apply; this list does not imply that all eight can be combined. `page()`, `carousel()` and `sortable()` throw when configured with synthetic mode. Carousel uses wrap scrolling, which this release does not support with synthetic input.
+`page()` uses native document scrolling through an external source with either entry. Its content must fit the 16,777,216 px document element limit; creation throws above that limit when the size is known, and later growth warns once. A deferred custom renderer whose size is first committed during rendering also warns once. Use `vlist/synthetic` viewport scrolling for larger lists. Default native viewport lists warn once when content exceeds their browser-size safety limit, pointing to that entry.
 
-Known limitations:
+Synthetic input limitations:
 
-- RTL horizontal lists throw in synthetic mode in this release; use native mode. Vertical lists on RTL pages are supported. RTL support for the synthetic driver is planned as a non-breaking addition.
-- Same-axis touch stops at either boundary with no parent handoff, including gestures that start inside an edge-pinned list. Use native mode when touch gestures must scroll the parent page at a boundary.
-- The native main-axis scrollbar is absent. Provide a custom scrollbar, such as `scrollbar()` above. Its accessibility release gate remains open; synthetic mode is not a completed scrollbar-accessibility sign-off.
+- `carousel()`, `sortable()` and horizontal RTL lists throw with instructions to use `vlist`. Vertical lists and tables support `dir="rtl"`, including cross-axis wheel movement, aligned table headers and keyboard column navigation.
+- Same-axis touch stops at either boundary with no parent handoff, including gestures starting inside an edge-pinned list. Use the native default when boundary gestures must scroll the parent page.
+- There is no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar. The synthetic entry rejects the `"native"` and `"none"` scrollbar strings.
 - Inertia initializes its frame clock on the first frame after release, adding up to one frame of release latency.
 - Wheel input at an edge is left to the page when it cannot move the list. Native cross-axis scrolling remains available.
 
-Measurement corrections from autosize preserve ongoing motion. Synthetic input adds **2.6 KB gzipped** over the base entry (**12.5 KB** total before plugins); ordinary `vlist` imports exclude this driver. See [RFC-014](https://github.com/floor/vlist/discussions/127).
+Measurement corrections from autosize preserve ongoing synthetic motion. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
 
-## Deprecated in 2.8, removed in 3.0
+## Migrating to 3.0
 
-These notices prepare the 3.0 migration; 2.x behavior and defaults stay unchanged. Native scrolling stays the default in 3.0, and synthetic input stays the opt-in `vlist/synthetic` entry. Bounded mode remains supported in 2.x, including carousel and sortable; it emits no deprecation warning.
+`3.0.0-next.1` used synthetic input by default. `3.0.0-next.2` restores the 2.x default. Import `vlist/synthetic` explicitly to retain synthetic behavior across these prereleases. `vlist/native` remains a deprecated compatibility alias; its `NativeScrollConfig` and `NativeCreateVListConfig` types alias the standard `ScrollConfig` and `CreateVListConfig`.
 
-| Option or API | In 3.0 | Since |
-|---|---|---|
-| `scroll.mode` | Removed. `vlist` is native by default; for lists beyond the browser's element size limit, import `createVList` from `vlist/synthetic` instead of using bounded mode. | 2.8 |
-| `scroll.runway` | Removed with bounded mode. | 2.8 |
-| `PluginContext.setScrollFns`, `disableDefaultScroll` | Removed; use `setScrollSource`. | 2.8 |
-| `scale()` | Removed; use `vlist/synthetic` for huge lists. | 2.4 |
+| 2.x option or API | 3.0 replacement |
+|---|---|
+| `scroll.mode` (all values, both entries) | Omit it. `vlist` provides native scrolling; import `vlist/synthetic` for synthetic input. |
+| `scroll.runway` (both entries) | Remove it. For huge lists use `vlist/synthetic`, which needs no native runway. |
+| `scroll.scrollbar: "native"` or `"none"` | Retained in default `ScrollConfig`. With synthetic input, omit the string and optionally install `scrollbar()`. |
+| `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `setScrollSource` to supply an external position source and commit callback. |
+| `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-`scroll.scrollbar: "native"` and `"none"` are not deprecated: they stay available on the native default in 3.0. Only explicit `scale()` calls warn, once per process, and 3.0's `vlist/config` no longer installs the scale compatibility stub. Release 2.8.0 described native scrolling and the scrollbar strings as moving to a `vlist/native` entry in 3.0; that plan was revised. See the [v2 to v3 migration guide](https://vlist.io/docs/migration-v3).
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` retains scrollbar omission/options convenience and its top-level `scrollbar: "none"` option. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.setBoundedWrap`.
 
 ## Plugins
 
-| Plugin | Size | Description |
-|--------|------|-------------|
-| **Base** | 9.9 KB | Virtualization, ARIA, keyboard nav, gap, padding, bounded scroll (1M+ items) |
-| `vlist/synthetic` entry | +2.6 KB | Opt-in synthetic scroll input (12.5 KB total before plugins) |
-| `data()` | +4.8 KB | Lazy loading with velocity-aware fetching |
-| `selection()` | +2.8 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()` | +1.0 KB | Auto-measure items via ResizeObserver |
-| `scrollbar()` | +2.0 KB | Custom scrollbar UI |
-| `grid()` | +2.5 KB | 2D grid layout |
-| `masonry()` | +4.1 KB | Pinterest-style masonry with lane-aware keyboard nav |
-| `carousel()` | +3.6 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()` | +3.0 KB | Drag-and-drop reordering with auto-scroll |
-| `snapshots()` | +1.2 KB | Scroll position save/restore |
-| `transition()` | +2.0 KB | FLIP-based enter/exit animations for insert & remove |
+| Entry / export | Minified | Gzipped |
+|---|---:|---:|
+| **Base (`vlist`)** | 25.4 KB | 9.3 KB |
+| `vlist/synthetic` | 31.1 KB | 11.4 KB |
+| `vlist/native` (alias) | 25.4 KB | 9.3 KB |
+| `a11y()` | 28.7 KB | 10.5 KB |
+| `selection()` | 34.8 KB | 12.1 KB |
+| `data()` | 39.0 KB | 14.1 KB |
+| `scrollbar()` | 33.6 KB | 12.2 KB |
+| `sortable()` | 34.9 KB | 12.2 KB |
+| `groups()` | 41.3 KB | 14.6 KB |
+| `page()` | 27.9 KB | 10.2 KB |
+| `snapshots()` | 28.7 KB | 10.4 KB |
+| `transition()` | 32.1 KB | 11.3 KB |
+| `autosize()` | 28.5 KB | 10.3 KB |
+| `grid()` | 32.5 KB | 11.8 KB |
+| `table()` | 43.8 KB | 15.2 KB |
+| `masonry()` | 36.8 KB | 13.4 KB |
+| `tree()` | 40.6 KB | 14.3 KB |
+| `search()` | 34.5 KB | 12.4 KB |
+| `carousel()` | 38.0 KB | 13.7 KB |
+
+Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows include the native default factory plus that plugin. The base is **9,523 bytes gzipped**, below the 9.9 KB target; synthetic input is **11,687 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Framework Adapters
 
@@ -127,7 +140,7 @@ These notices prepare the 3.0 migration; 2.x behavior and defaults stay unchange
 | SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB |
 | React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB |
 
-With vlist 2.8 and an adapter that forwards the `factory` option, opt into synthetic input explicitly:
+Adapters use native scrolling by default. With an adapter that forwards `factory`, select synthetic input explicitly:
 
 ```ts
 import { useVList } from "vlist-react";
@@ -135,13 +148,12 @@ import { createVList } from "vlist/synthetic";
 
 useVList({
   factory: createVList,
-  scroll: { mode: "synthetic" },
   items,
   item: { height: 48, template: item => String(item.id) },
 });
 ```
 
-The same factory option is available to the other adapters. `vlist/config` keeps the synthetic driver out of its default bundle; importing the factory opts in. The factory is structural configuration: changing it requires recreating the list.
+The same factory option is available to the other adapters. `vlist/config` defaults to native scrolling. The factory is structural configuration: changing it requires recreating the list.
 
 ## Docs & Examples
 

package/dist/config.d.ts

@@ -32,10 +32,8 @@ export type VListFactory<T extends VListItem = VListItem> = typeof createVList<T
  * translated into plugins by {@link resolvePlugins}.
  */
 export interface VListConfig<T extends VListItem = VListItem> extends Omit<CreateVListConfig<T>, "container" | "scroll"> {
-    /** Synthetic mode requires a factory imported from vlist/synthetic. */
-    scroll?: Omit<ScrollConfig, "mode"> & {
-        mode?: ScrollConfig["mode"] | "synthetic";
-    };
+    /** Scroll options; select synthetic input with a factory from vlist/synthetic. */
+    scroll?: ScrollConfig;
     /** List factory; defaults to core createVList. Fixed for this instance. */
     factory?: VListFactory<T>;
     /** Layout mode. Wires the grid or masonry plugin from `grid`/`masonry`. */
@@ -65,7 +63,7 @@ export interface VListConfig<T extends VListItem = VListItem> extends Omit<Creat
 /**
  * Translate a {@link VListConfig} into the ordered plugin array that the core
  * `createVList` expects. Mirrors the adapters' historical behavior exactly:
- * `scale` and `snapshots` are always included, and `selection` is always
+ * `snapshots` is always included, and `selection` is always
  * present (in `"none"` mode when unset) so its API is available. Any user
  * `plugins` are appended last as an escape hatch.
  */