vlist 3.0.0-next.1 → 3.0.0-next.3

package/README.github.md

@@ -2,16 +2,16 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.0.0-next.1** (prerelease on the npm `next` tag) — Synthetic input by default, native input through `vlist/native`, and removal of the deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
+**v3.0.0-next.3** (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)
 [![CI](https://github.com/floor/vlist/actions/workflows/ci.yml/badge.svg)](https://github.com/floor/vlist/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/vlist.svg)](https://github.com/floor/vlist/blob/main/LICENSE)
 
-- **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
+- **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core with tiny adapters for Vue, Svelte, Solid, React
-- **11.4 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
+- **9.5 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
@@ -22,7 +22,7 @@ The virtual list library for every framework. Ultra efficient, batteries-include
 
 | | vlist | TanStack Virtual | react-virtuoso | virtua | vue-virtual-scroller |
 |---|---|---|---|---|---|
-| **A11y built-in** | WAI-ARIA + 2D keyboard | None (DIY) | Partial | Minimal | None |
+| **A11y** | WAI-ARIA + 2D keyboard, one plugin | None (DIY) | Partial | Minimal | None |
 | **Grid + Masonry + Table** | All | Grid only | Grid + Table | Grid only | None |
 | **Vue** | 0.6 KB adapter | Yes | — | Yes | 11.8 KB |
 | **Svelte** | 0.5 KB adapter | Yes | — | Yes | — |
@@ -46,11 +46,11 @@ npm install vlist@next         # 3.0 prerelease; latest stays on 2.8
 npm install vlist vlist-vue    # or vlist-svelte / vlist-solidjs / vlist-react
 ```
 
-Adapters use synthetic input by default. With an adapter that forwards `factory`, select native input explicitly:
+Adapters use native scrolling by default. With an adapter that forwards `factory`, select synthetic input explicitly:
 
 ```ts
 import { useVList } from "vlist-react";
-import { createVList } from "vlist/native";
+import { createVList } from "vlist/synthetic";
 
 useVList({
   factory: createVList,
@@ -59,7 +59,7 @@ useVList({
 });
 ```
 
-The same factory option is available to the other adapters. `vlist/config` defaults to synthetic input. 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
 
@@ -108,10 +108,21 @@ const list = createVList({
 
 ## Scroll input
 
-Synthetic scrolling is the default in 3.0. Import `createVList` and plugins from `vlist`; there is no `scroll.mode` option. The deprecated `vlist/synthetic` entry remains an alias of the same factory.
+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 and sortable work with this factory; horizontal RTL lists are rejected by both entries. 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, scrollbar } from 'vlist'
+import { createVList } from 'vlist/synthetic'
+import { scrollbar } from 'vlist'
 import 'vlist/styles'
 
 const list = createVList({
@@ -121,69 +132,75 @@ const list = createVList({
 }, [scrollbar()])
 ```
 
-For native scrolling, import the factory from `vlist/native` and plugins from `vlist`. Native scrolling is required for `carousel()`, `sortable()`, and horizontal RTL lists; configuring these with the default entry throws. The native entry preserves carousel wrapping through a private runway implementation. Bounded scrolling is no longer a public mode.
+`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.
 
-```typescript
-import { createVList } from 'vlist/native'
-import { carousel } from 'vlist'
+`carousel()` works with either entry. Synthetic carousel folds preserve touch motion and smooth snapping across whole laps. `page()` and carousel remain incompatible. The shared carousel plugin includes its native wrap handler even when used with synthetic input; the combined size is reported below.
 
-const list = createVList({
-  container: '#slides',
-  orientation: 'horizontal',
-  items: slides,
-  item: { width: 320, template: renderSlide },
-}, [carousel()])
-```
+Synthetic input limitations:
 
-`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 default viewport scrolling for larger lists. Native viewport lists warn once when content exceeds their browser-size safety limit.
-
-Known limitations:
-
-- Horizontal RTL lists require `vlist/native`. Vertical lists and tables support `dir="rtl"` on the container, 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 `vlist/native` when boundary gestures must scroll the parent page.
-- The default entry has no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar; native visibility options belong to `vlist/native`.
+- Horizontal RTL lists throw at creation — in this entry and in `vlist`. Vertical lists and tables support `dir="rtl"` in both, 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. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
+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).
+
+### Sortable gestures
+
+`sortable()` works with either input entry. Mouse and trackpad dragging still starts after `dragThreshold` (5 px by default). Touch and pen without a handle use `touchDelay`, a 350 ms long press; moving at least `dragThreshold` pixels in any direction before it completes yields to scrolling. This delay separates a deliberate hold from a quick flick. With `handle`, dragging starts at the threshold without waiting; touches elsewhere scroll.
+
+```typescript
+sortable({ touchDelay: 350, dragThreshold: 5 })
+sortable({ handle: '.drag-handle' })
+```
+
+A touch during scrolling catches the motion and does not arm a hold for that contact. Lift and press again once the list is at rest. A second finger or `pointercancel` cancels the pending press or active drag. Edge auto-scroll uses the list's logical position and stops on drop.
+
+The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts on the pressed item. A claimed touch/pen drag adds `.vlist-sort-ghost--touch` to the ghost as a visual cue; override that class in CSS to customize it. Keyboard reordering remains Space to grab/drop, arrows to move and Escape to cancel.
 
 ## Migrating to 3.0
 
-| Removed public API | Replacement |
+`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`.
+
+| 2.x option or API | 3.0 replacement |
 |---|---|
-| `scroll.mode` (all values, both entries) | Omit it. `vlist` provides synthetic input; import `vlist/native` for native scrolling. |
-| `scroll.runway` (both entries) | Remove it. Default synthetic scrolling supports huge lists without a native runway. |
-| Core `scroll.scrollbar: "native"` or `"none"` | Use `scrollbar()` with `vlist`, or select `vlist/native` to retain either string. Native types are exported as `NativeScrollConfig` and `NativeCreateVListConfig`. |
-| `PluginContext.setScrollFns`, `disableDefaultScroll` | Use `setScrollSource` to supply an external position source and commit callback. |
-| `scale()` and `ScalePluginConfig` | Remove it; the default entry supports the full logical range. `vlist/config` no longer installs a scale stub. |
+| `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 `ctx.scroll.setSource` to supply an external position source and commit callback. |
+| Flat `PluginContext` members (`registerMethod`, `forceRender`, `sizeCache`, `scrollTo`, …) | Grouped by capability: `ctx.hooks.method`, `ctx.render.force`, `ctx.sizes.cache`, `ctx.scroll.to`, `ctx.items.all`. `pool`, `config`, `emitter`, `template` and `getState()` stay at the top level. |
+| `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-Removed scroll options throw a migration error before creating DOM. `vlist/config` retains its scrollbar omission/options convenience and its top-level `scrollbar: "none"` option; native visibility strings require an injected native factory. `baseOffset` remains private engine state for input providers; plugins continue to use `ctx.scroll.getRenderOrigin()`. No other public plugin hooks or adapter methods are removed.
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` wires only what the config asks for: `selection`, the custom scrollbar, `snapshots` and `a11y` are each opt-in, so an adapter list matches a core list built from the same options. It keeps the scrollbar options convenience and its top-level `scrollbar: "none"`; pass `scrollbar: true` for the overlay scrollbar earlier versions added to every list. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.scroll.setBoundedWrap`.
 
 ## Plugins
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 31.1 KB | 11.4 KB |
-| `vlist/synthetic` (alias) | 31.1 KB | 11.4 KB |
-| `vlist/native` | 28.1 KB | 10.2 KB |
-| `a11y()` | 34.4 KB | 12.6 KB |
-| `selection()` | 40.5 KB | 14.2 KB |
-| `data()` | 44.8 KB | 16.2 KB |
-| `scrollbar()` | 39.3 KB | 14.2 KB |
-| `sortable()` | 40.6 KB | 14.3 KB |
-| `groups()` | 47.1 KB | 16.7 KB |
-| `page()` | 33.6 KB | 12.3 KB |
-| `snapshots()` | 34.4 KB | 12.5 KB |
-| `transition()` | 37.8 KB | 13.3 KB |
-| `autosize()` | 34.2 KB | 12.4 KB |
-| `grid()` | 38.2 KB | 13.8 KB |
-| `table()` | 49.5 KB | 17.2 KB |
-| `masonry()` | 42.5 KB | 15.5 KB |
-| `tree()` | 46.4 KB | 16.4 KB |
-| `search()` | 40.2 KB | 14.5 KB |
-| `carousel()` | 41.0 KB | 14.9 KB |
-
-Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows measure the base factory plus that export for comparison across revisions; `carousel()` and `sortable()` must be used with the native factory at runtime. The base is **11,670 bytes gzipped** in this 3.0 work-in-progress build. The 9.9 KB target is not yet met; size optimization is deferred.
+| **Base (`vlist`)** | 25.7 KB | 9.5 KB |
+| `vlist/synthetic` | 31.7 KB | 11.7 KB |
+| `vlist/native` (alias) | 25.7 KB | 9.5 KB |
+| `a11y()` | 29.0 KB | 10.7 KB |
+| `selection()` | 35.1 KB | 12.3 KB |
+| `data()` | 39.4 KB | 14.3 KB |
+| `scrollbar()` | 33.9 KB | 12.4 KB |
+| `sortable()` | 37.5 KB | 13.0 KB |
+| `groups()` | 41.5 KB | 14.7 KB |
+| `page()` | 28.2 KB | 10.4 KB |
+| `snapshots()` | 29.0 KB | 10.6 KB |
+| `transition()` | 32.4 KB | 11.5 KB |
+| `autosize()` | 28.7 KB | 10.5 KB |
+| `grid()` | 32.5 KB | 11.9 KB |
+| `table()` | 44.1 KB | 15.4 KB |
+| `masonry()` | 36.9 KB | 13.6 KB |
+| `tree()` | 41.0 KB | 14.5 KB |
+| `search()` | 34.7 KB | 12.6 KB |
+| `carousel()` | 38.5 KB | 13.9 KB |
+| `vlist/synthetic` + `carousel()` | 44.4 KB | 16.2 KB |
+| `vlist/synthetic` + `sortable()` | 43.5 KB | 15.3 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,914 bytes gzipped**, below the 9.9 KB target. `bun run size` fails if a scenario fails to build, an unused plugin leaks into a bundle, or any published size exceeds its gzip budget. Synthetic input is **11,960 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Examples
 
@@ -308,6 +325,13 @@ const list = createVList({
 ])
 ```
 
+Search filters client-side over the items the list holds, so it cannot be
+combined with `data()` — creating a list with both throws. With an adapter, the
+rows in memory are only the loaded window; query the remote dataset through the
+adapter instead. It cannot be combined with `tree()` either: filtering a tree
+means keeping the ancestors of each match, which belongs to the plugin that
+owns the layout, and `tree()` offers no such hook.
+
 ## Custom scrollbar (3.0 preview)
 
 On `next`, `scrollbar()` remains a plugin. macOS and Android default to thin,
@@ -368,7 +392,9 @@ 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/):
+Accessibility is a plugin, not a default. Add `a11y()`, or a `selection()` mode
+other than `"none"` which brings the same behaviour, and the list follows the
+[WAI-ARIA listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/):
 
 - **Arrow keys** move focus between items with a visible focus ring
 - **2D navigation** in grids and masonry — Up/Down by row, Left/Right by cell
@@ -377,7 +403,9 @@ Every vlist is accessible by default following the [WAI-ARIA listbox pattern](ht
 - **Screen-reader DOM ordering** — items reordered on scroll idle for correct reading order
 - **Focus recovery** — maintains focus when items are removed
 
-Set `interactive: false` for display-only lists (log viewers, activity feeds) where items contain their own interactive elements.
+A list created without either stays display-only: `role="list"`, no item roles
+and out of the tab order. That is the right shape for log viewers and activity
+feeds, and for items carrying their own interactive elements.
 
 ## API
 
@@ -391,7 +419,7 @@ const list = createVList(config, [plugin1(), plugin2()])
 |--------|-------------|
 | `list.setItems(items)` | Replace all items |
 | `list.appendItems(items)` | Add to end (auto-scrolls in reverse mode) |
-| `list.prependItems(items)` | Add to start (preserves scroll position) |
+| `list.prependItems(items)` | Add to start (in reverse mode, the visible rows hold their position) |
 | `list.updateItem(id, partial)` | Update a single item by ID |
 | `list.insertItem(item, index?)` | Insert at index (animated with `transition`) |
 | `list.removeItem(id)` | Remove by ID (animated with `transition`) |
@@ -435,6 +463,10 @@ list.on('sort:end', ({ fromIndex, toIndex }) => {})
 list.on('sort:cancel', ({ originalItems }) => {})
 ```
 
+The `index` on `item:click`, `item:dblclick` and `item:contextmenu` is the data
+index — the one `getItemAt`, `scrollToIndex` and `removeItem` take — not the
+layout index, which counts group headers and carousel laps.
+
 ### Properties
 
 | Property | Description |
@@ -482,8 +514,7 @@ Full configuration reference → **[vlist.io](https://vlist.io)**
 | `ariaLabel` | — | Accessible label for the listbox |
 | `orientation` | `'vertical'` | `'vertical'` or `'horizontal'` scroll direction |
 | `padding` | `0` | Content inset — number, `[v, h]`, or `[top, right, bottom, left]` |
-| `interactive` | `true` | Enable built-in keyboard navigation |
-| `reverse` | `false` | Reverse mode for chat UIs |
+| `reverse` | `false` | The list reads bottom-up (chat UIs): a view sitting at the end stays there as `appendItems` adds to it, `prependItems` holds the visible rows in place as older history loads above them, arrow keys invert, and `transition()` animates from the bottom. Item order is yours to supply; the layout itself is not reversed. `masonry()` and `table()` reject it |
 
 ## Styling
 
@@ -513,23 +544,38 @@ Live benchmarks against 9 competitors → **[vlist.io/benchmarks](https://vlist.
 
 ## TypeScript
 
-Fully typed. Generic over your item type:
+Fully typed and generic over your item type. An item only needs an `id`, so ordinary
+interfaces work:
 
 ```typescript
-import { createVList, grid, type VList } from 'vlist'
+import { createVList, grid, selection, type CreateVListConfig } from 'vlist'
 
 interface Photo { id: number; url: string; title: string }
 
-const list: VList<Photo> = createVList<Photo>({
+const config: CreateVListConfig<Photo> = {
   container: '#gallery',
   items: photos,
   item: {
     height: 200,
     template: (photo) => `<img src="${photo.url}" />`,
   },
-}, [grid({ columns: 4 })])
+}
+
+const list = createVList(config, [grid({ columns: 4 }), selection<Photo>({ mode: 'multiple' })])
+
+list.select(photos[0].id)                      // typed: selection is in the array
+const chosen: Photo[] = list.getSelectedItems()
+// list.expand(1)                              // compile error: no tree plugin here
 ```
 
+`createVList` infers the methods each plugin adds, so a list exposes exactly what its
+plugins provide, and a mistyped call does not compile.
+
+TypeScript does not allow a partial type argument list. Writing
+`createVList<Photo>(config, plugins)` supplies the item type and leaves the plugin list on
+its default, so plugin methods are not inferred. Type the config as above, or let the item
+type come from your data.
+
 ## Migrating from v1
 
 v2 is a ground-up rewrite — simpler API, 55% smaller base bundle, zero-allocation scroll path. [Full announcement →](https://vlist.io/blog/v2)

package/README.md

@@ -2,16 +2,16 @@
 
 The virtual list library for every framework. Ultra efficient, batteries-included, and accessible with composable plugins.
 
-**v3.0.0-next.1** (prerelease on the npm `next` tag) — Synthetic input by default, native input through `vlist/native`, and removal of the deprecated scroll configuration and plugin hooks. See the [changelog](https://github.com/floor/vlist/blob/next/CHANGELOG.md).
+**v3.0.0-next.3** (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)
 [![CI](https://github.com/floor/vlist/actions/workflows/ci.yml/badge.svg)](https://github.com/floor/vlist/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/vlist.svg)](https://github.com/floor/vlist/blob/main/LICENSE)
 
-- **Accessible** — WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
+- **Accessible** — `a11y()` or a selection mode adds WAI-ARIA, 2D keyboard navigation, focus recovery, screen-reader DOM ordering
 - **Zero dependencies** — framework-agnostic core, tiny adapters for Vue, Svelte, Solid, React
-- **11.4 KB gzipped (3.0 prerelease)** — composable plugins with perfect tree-shaking
+- **9.4 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
 
@@ -55,10 +55,21 @@ const list = createVList({ container: '#app', items, item: { height: 200, templa
 
 ## Scroll input
 
-Synthetic scrolling is the default in 3.0. Import `createVList` and plugins from `vlist`; there is no `scroll.mode` option. The deprecated `vlist/synthetic` entry remains an alias of the same factory.
+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 and sortable work with this factory; horizontal RTL lists are rejected by both entries. 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, scrollbar } from 'vlist'
+import { createVList } from 'vlist/synthetic'
+import { scrollbar } from 'vlist'
 import 'vlist/styles'
 
 const list = createVList({
@@ -68,69 +79,74 @@ const list = createVList({
 }, [scrollbar()])
 ```
 
-For native scrolling, import the factory from `vlist/native` and plugins from `vlist`. Native scrolling is required for `carousel()`, `sortable()`, and horizontal RTL lists; configuring these with the default entry throws. The native entry preserves carousel wrapping through a private runway implementation. Bounded scrolling is no longer a public mode.
-
-```typescript
-import { createVList } from 'vlist/native'
-import { carousel } from 'vlist'
-
-const list = createVList({
-  container: '#slides',
-  orientation: 'horizontal',
-  items: slides,
-  item: { width: 320, template: renderSlide },
-}, [carousel()])
-```
+`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.
 
-`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 default viewport scrolling for larger lists. Native viewport lists warn once when content exceeds their browser-size safety limit.
+`carousel()` works with either entry. Synthetic carousel folds preserve touch motion and smooth snapping across whole laps. `page()` and carousel remain incompatible. The shared carousel plugin includes its native wrap handler even when used with synthetic input; the combined size is reported below.
 
-Known limitations:
+Synthetic input limitations:
 
-- Horizontal RTL lists require `vlist/native`. Vertical lists and tables support `dir="rtl"` on the container, 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 `vlist/native` when boundary gestures must scroll the parent page.
-- The default entry has no native main-axis scrollbar. Add `scrollbar()` for an accessible custom scrollbar; native visibility options belong to `vlist/native`.
+- Horizontal RTL lists throw at creation — in this entry and in `vlist`. Vertical lists and tables support `dir="rtl"` in both, 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. Existing plugin conflicts still apply. See the [scroll input contract](https://vlist.io/docs/rfcs/RFC-014-Scroll-Input-Model).
+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).
+
+### Sortable gestures
+
+`sortable()` works with either input entry. Mouse and trackpad dragging still starts after `dragThreshold` (5 px by default). Touch and pen without a handle use `touchDelay`, a 350 ms long press; moving at least `dragThreshold` pixels in any direction before it completes yields to scrolling. This delay separates a deliberate hold from a quick flick. With `handle`, dragging starts at the threshold without waiting; touches elsewhere scroll.
+
+```typescript
+sortable({ touchDelay: 350, dragThreshold: 5 })
+sortable({ handle: '.drag-handle' })
+```
+
+A touch during scrolling catches the motion and does not arm a hold for that contact. Lift and press again once the list is at rest. A second finger or `pointercancel` cancels the pending press or active drag. Edge auto-scroll uses the list's logical position and stops on drop.
+
+The touch-only `.vlist-item--touch-sort` class suppresses selection and callouts on the pressed item. A claimed touch/pen drag adds `.vlist-sort-ghost--touch` to the ghost as a visual cue; override that class in CSS to customize it. Keyboard reordering remains Space to grab/drop, arrows to move and Escape to cancel.
 
 ## Migrating to 3.0
 
-| Removed public API | Replacement |
+`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`.
+
+| 2.x option or API | 3.0 replacement |
 |---|---|
-| `scroll.mode` (all values, both entries) | Omit it. `vlist` provides synthetic input; import `vlist/native` for native scrolling. |
-| `scroll.runway` (both entries) | Remove it. Default synthetic scrolling supports huge lists without a native runway. |
-| Core `scroll.scrollbar: "native"` or `"none"` | Use `scrollbar()` with `vlist`, or select `vlist/native` to retain either string. Native types are exported as `NativeScrollConfig` and `NativeCreateVListConfig`. |
+| `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 it; the default entry supports the full logical range. `vlist/config` no longer installs a scale stub. |
+| `scale()` and `ScalePluginConfig` | Remove them; use `vlist/synthetic` for the full logical range. Config no longer installs a scale stub. |
 
-Removed scroll options throw a migration error before creating DOM. `vlist/config` retains its scrollbar omission/options convenience and its top-level `scrollbar: "none"` option; native visibility strings require an injected native factory. `baseOffset` remains private engine state for input providers; plugins continue to use `ctx.scroll.getRenderOrigin()`. No other public plugin hooks or adapter methods are removed.
+Removed mode/runway options throw a migration error before creating DOM. `vlist/config` wires only what the config asks for: `selection`, the custom scrollbar, `snapshots` and `a11y` are each opt-in, so an adapter list matches a core list built from the same options. It keeps the scrollbar options convenience and its top-level `scrollbar: "none"`; pass `scrollbar: true` for the overlay scrollbar earlier versions added to every list. `baseOffset` stays private engine state; plugins use `ctx.scroll.getRenderOrigin()`. Custom wrap providers now supply their handler factory as the second argument of `ctx.scroll.setBoundedWrap`.
 
 ## Plugins
 
 | Entry / export | Minified | Gzipped |
 |---|---:|---:|
-| **Base (`vlist`)** | 31.1 KB | 11.4 KB |
-| `vlist/synthetic` (alias) | 31.1 KB | 11.4 KB |
-| `vlist/native` | 28.1 KB | 10.2 KB |
-| `a11y()` | 34.4 KB | 12.6 KB |
-| `selection()` | 40.5 KB | 14.2 KB |
-| `data()` | 44.8 KB | 16.2 KB |
-| `scrollbar()` | 39.3 KB | 14.2 KB |
-| `sortable()` | 40.6 KB | 14.3 KB |
-| `groups()` | 47.1 KB | 16.7 KB |
-| `page()` | 33.6 KB | 12.3 KB |
-| `snapshots()` | 34.4 KB | 12.5 KB |
-| `transition()` | 37.8 KB | 13.3 KB |
-| `autosize()` | 34.2 KB | 12.4 KB |
-| `grid()` | 38.2 KB | 13.8 KB |
-| `table()` | 49.5 KB | 17.2 KB |
-| `masonry()` | 42.5 KB | 15.5 KB |
-| `tree()` | 46.4 KB | 16.4 KB |
-| `search()` | 40.2 KB | 14.5 KB |
-| `carousel()` | 41.0 KB | 14.9 KB |
-
-Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plugin rows measure the base factory plus that export for comparison across revisions; `carousel()` and `sortable()` must be used with the native factory at runtime. The base is **11,670 bytes gzipped** in this 3.0 work-in-progress build. The 9.9 KB target is not yet met; size optimization is deferred.
+| **Base (`vlist`)** | 25.7 KB | 9.4 KB |
+| `vlist/synthetic` | 31.7 KB | 11.7 KB |
+| `vlist/native` (alias) | 25.7 KB | 9.5 KB |
+| `a11y()` | 29.0 KB | 10.7 KB |
+| `selection()` | 35.1 KB | 12.3 KB |
+| `data()` | 39.4 KB | 14.3 KB |
+| `scrollbar()` | 33.9 KB | 12.3 KB |
+| `sortable()` | 37.4 KB | 12.9 KB |
+| `groups()` | 41.4 KB | 14.7 KB |
+| `page()` | 28.2 KB | 10.3 KB |
+| `snapshots()` | 29.0 KB | 10.6 KB |
+| `transition()` | 32.4 KB | 11.4 KB |
+| `autosize()` | 28.8 KB | 10.5 KB |
+| `grid()` | 32.6 KB | 11.8 KB |
+| `table()` | 44.2 KB | 15.3 KB |
+| `masonry()` | 37.0 KB | 13.5 KB |
+| `tree()` | 41.0 KB | 14.5 KB |
+| `search()` | 34.7 KB | 12.6 KB |
+| `carousel()` | 38.5 KB | 13.9 KB |
+| `vlist/synthetic` + `carousel()` | 44.4 KB | 16.1 KB |
+| `vlist/synthetic` + `sortable()` | 43.4 KB | 15.2 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,914 bytes gzipped**, below the 9.9 KB target. `bun run size` fails if a scenario fails to build, an unused plugin leaks into a bundle, or any published size exceeds its gzip budget. Synthetic input is **11,960 bytes** before plugins. The alias row measures the same source factory; the distributed alias re-exports it without duplicating the implementation.
 
 ## Framework Adapters
 
@@ -141,11 +157,11 @@ Sizes are tree-shaken totals from `bun run size`, not additive plugin costs. Plu
 | SolidJS | [`vlist-solidjs`](https://github.com/floor/vlist-solidjs) | 0.5 KB |
 | React | [`vlist-react`](https://github.com/floor/vlist-react) | 0.6 KB |
 
-Adapters use synthetic input by default. With an adapter that forwards `factory`, select native input explicitly:
+Adapters use native scrolling by default. With an adapter that forwards `factory`, select synthetic input explicitly:
 
 ```ts
 import { useVList } from "vlist-react";
-import { createVList } from "vlist/native";
+import { createVList } from "vlist/synthetic";
 
 useVList({
   factory: createVList,
@@ -154,7 +170,7 @@ useVList({
 });
 ```
 
-The same factory option is available to the other adapters. `vlist/config` defaults to synthetic input. 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