vlist 3.0.0 → 3.0.1-next.1

package/dist/core/adapter.d.ts

@@ -90,9 +90,9 @@ export declare function normalizeLogical(sizeCache: SizeCache, pos: LogicalScrol
 /**
  * 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.
+ * The source behind `getPixel` / `setPixel` is the native viewport scroll or a
+ * logical handler (synthetic input, carousel runway); plugins that use the
+ * adapter do not change with it.
  */
 export declare function createScrollAdapter(config: ScrollAdapterConfig): ScrollAdapter;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/core/create.d.ts

@@ -7,12 +7,17 @@
 import type { VListItem } from "../types";
 import type { CreateVListConfig, PluginMethods, VListPlugin, VList } from "./types";
 import type { SizeCache } from "./sizes";
-import type { BoundedScrollHandler, BoundedScrollConfig } from "./runway";
+import type { LogicalScrollHandler, LogicalScrollConfig } from "./logical";
 import type { ScrollHandler, ScrollHandlerConfig } from "./scroll";
 import { type Emitter } from "../events";
 import type { VListEvents } from "../types";
+type SyntheticFactory = (config: LogicalScrollConfig & {
+    sizeCache: SizeCache;
+}) => LogicalScrollHandler;
+type SyntheticDriver = typeof import("../synthetic/driver");
 /**
- * Create a list with native scrolling. Opt into synthetic input via vlist/synthetic.
+ * Create a list. `scroll.mode` chooses who owns input: `"auto"` (default)
+ * scrolls natively and goes synthetic past the browser's size limit.
  *
  * Let the item type be inferred from the config — its `items`, or the
  * `template` parameter — rather than passing it as a type argument. The list's
@@ -34,12 +39,12 @@ export declare function createVList<T extends VListItem = VListItem, const P ext
 /** @internal Shared factory; entries select the input handler. */
 export declare function createCore<T extends VListItem = VListItem>(rawConfig: CreateVListConfig<T>, plugins?: VListPlugin<T>[], 
 /** @internal Omitted by the native entry. */
-logicalHandlerFactory?: (config: BoundedScrollConfig & {
-    sizeCache: SizeCache;
-}) => BoundedScrollHandler, nativeOptions?: {
+logicalHandlerFactory?: SyntheticFactory, nativeOptions?: {
     native: (config: ScrollHandlerConfig) => ScrollHandler & {
         commitScroll(pos?: number): void;
     };
+    load: () => Promise<SyntheticDriver>;
     onContentSize: (size: number, emitter: Emitter<VListEvents<T>>) => void;
 }): VList<T>;
+export {};
 //# sourceMappingURL=create.d.ts.map

package/dist/core/fold.d.ts

@@ -5,8 +5,8 @@
  * positions are unchanged. Re-keying the map (and the `id` that encodes the
  * virtual index) lets the next commit find them instead of releasing,
  * re-templating and re-inserting the viewport. Lives here — not in pipeline
- * or create — so a native list that never wraps does not import it (runway
- * is pulled by carousel). The synthetic handler imports it because wrap
+ * or create — so a native list that never wraps does not import it (the
+ * carousel runway pulls it). The synthetic handler imports it because wrap
  * folds for that entry go through commit(), not wrapRebase; putting the
  * import in create.ts would charge every native list.
  *
@@ -18,7 +18,7 @@
  * `focusedIndex` (data space under `indexMap`), snapshots (`dataIndex`).
  */
 import type { EngineState } from "./state";
-import type { WrapConfig } from "./runway";
+import type { WrapConfig } from "./logical";
 /**
  * Move every `rendered` key by `-indexShift` without touching the DOM tree.
  * `data-index` / `aria-posinset` carry the public index and stay put.

package/dist/core/logical.d.ts

@@ -0,0 +1,93 @@
+/**
+ * vlist — logical scroll handlers (RFC-012)
+ *
+ * A handler that owns the logical position itself, instead of reading it from
+ * a native scroll offset: the synthetic driver (`scroll.mode`, RFC-014/015) and
+ * the carousel's wrap runway. Both render through `state.baseOffset`: items are
+ * placed at `getOffset(index) - baseOffset`, so the content element never has
+ * to be as large as the list.
+ */
+import type { SizeCache } from "./sizes";
+import type { EngineState } from "./state";
+import type { ScrollHandler } from "./scroll";
+export interface LogicalScrollHandler 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;
+    /** Non-cancelling coordinate correction, when supported by the input provider. */
+    shiftBy?(delta: number): void;
+    /** Maximum scrollable logical position (`virtualTotal - containerSize`, >= 0). */
+    getMaxLogical(): number;
+    /** Recompute derived geometry from the total size and resize the content element. */
+    refresh(totalSize: number): void;
+}
+/**
+ * Infinite-loop (wrap) configuration for a logical 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 stays a few
+ * viewports long, 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;
+    /**
+     * Real items in one lap (e.g. the carousel's `realTotal`). The wrap handler
+     * uses this to re-key mounted elements on a fold so the same DOM nodes
+     * survive the virtual-index shift — only the key changed; paint did not.
+     */
+    readonly itemsPerLap: () => number;
+    /** Logical position to fold back toward (the home lap). */
+    readonly home: () => number;
+    /** Fold the logical position back toward `home` once it drifts this many laps away. */
+    readonly thresholdLaps: number;
+    /** @internal Notify the wrap owner when its logical coordinates fold. */
+    readonly onFold?: (shift: number) => void;
+}
+export interface LogicalScrollConfig {
+    /** Logical row geometry for opt-in input providers (keyboard row steps). */
+    readonly sizeCache?: Pick<SizeCache, "getSize" | "indexAtOffset" | "getTotalSize">;
+    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 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;
+    /**
+     * Mounted row map. A wrap fold re-keys it in place so phase 2 finds the
+     * same nodes; omitted when the handler is constructed without a viewport.
+     */
+    readonly rendered?: Map<number, HTMLElement>;
+    /**
+     * Class prefix for rewriting `id` / `aria-activedescendant` on a wrap fold.
+     * Passed explicitly — a prefix containing `-content` cannot be recovered
+     * from the content element's class name.
+     */
+    readonly classPrefix?: string;
+    /**
+     * Stripe class (`{prefix}-item--odd`). Re-toggled on a wrap fold when
+     * `indexShift` is odd, so virtual-index parity survives the re-key.
+     */
+    readonly oddClass?: string;
+    /** @internal Coordinate fold: shift core telemetry references before rendering. */
+    readonly onFold?: (shift: number) => void;
+    /** Called synchronously per frame — triggers the 2-phase pipeline. */
+    readonly onFrame: () => void;
+    /** Called when scrolling becomes idle. */
+    readonly onIdle: () => void;
+}
+//# sourceMappingURL=logical.d.ts.map

package/dist/core/runway.d.ts

@@ -1,113 +1,27 @@
 /**
- * vlist — Bounded Logical Scroll Handler (RFC-012)
+ * vlist — carousel runway (RFC-011, RFC-012)
  *
- * An alternative to the native scroll handler ({@link createScrollHandler}) that
- * decouples the native scrollable size from the virtual content size.
+ * The carousel's infinite loop scrolls a native element that is only a few
+ * viewports long: the *runway*. The logical position is `baseOffset +
+ * scrollTop`; as scrollTop nears an edge of the runway, baseOffset and
+ * scrollTop shift together by the same delta, so the logical position and
+ * what is on screen stay put. The scroll event that shift triggers reads the
+ * same logical position and is dropped by the "logical unchanged" guard. In
+ * wrap mode the position also folds back by whole laps toward home.
  *
- * 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 compressing
- * the coordinate space — 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.
+ * Engine code (it owns the scroll coordinates), but only `carousel()` imports
+ * it: a list without it never bundles it.
  */
-import type { SizeCache } from "./sizes";
-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;
-    /** Non-cancelling coordinate correction, when supported by the input provider. */
-    shiftBy?(delta: number): void;
-    /** Maximum scrollable logical position (`virtualTotal - containerSize`, >= 0). */
-    getMaxLogical(): number;
-    /** Recompute runway/derived values and resize the content element. */
-    refresh(totalSize: number): void;
-}
+import type { LogicalScrollConfig, LogicalScrollHandler } from "./logical";
 /**
- * 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.
+ * Runway size as a multiple of the viewport: the content element is
+ * `containerSize × this` (capped at the total size), which gives the native
+ * scrollbar room to move before a rebase shifts the logical origin.
  */
-export interface WrapConfig {
-    /** Current lap period in virtual px (`realTotal × stepSize`). */
-    readonly lapSize: () => number;
-    /**
-     * Real items in one lap (e.g. the carousel's `realTotal`). The wrap handler
-     * uses this to re-key mounted elements on a fold so the same DOM nodes
-     * survive the virtual-index shift — only the key changed; paint did not.
-     */
-    readonly itemsPerLap: () => number;
-    /** Logical position to fold back toward (the home lap). */
-    readonly home: () => number;
-    /** Fold the logical position back toward `home` once it drifts this many laps away. */
-    readonly thresholdLaps: number;
-    /** @internal Notify the wrap owner when its logical coordinates fold. */
-    readonly onFold?: (shift: number) => void;
-}
-export interface BoundedScrollConfig {
-    /** Logical row geometry for opt-in input providers (keyboard row steps). */
-    readonly sizeCache?: Pick<SizeCache, "getSize" | "indexAtOffset" | "getTotalSize">;
-    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;
-    /**
-     * Mounted row map. A wrap fold re-keys it in place so phase 2 finds the
-     * same nodes; omitted when the handler is constructed without a viewport.
-     */
-    readonly rendered?: Map<number, HTMLElement>;
-    /**
-     * Class prefix for rewriting `id` / `aria-activedescendant` on a wrap fold.
-     * Passed explicitly — a prefix containing `-content` cannot be recovered
-     * from the content element's class name.
-     */
-    readonly classPrefix?: string;
-    /**
-     * Stripe class (`{prefix}-item--odd`). Re-toggled on a wrap fold when
-     * `indexShift` is odd, so virtual-index parity survives the re-key.
-     */
-    readonly oddClass?: string;
-    /** @internal Coordinate fold: shift core telemetry references before rendering. */
-    readonly onFold?: (shift: number) => void;
-    /** 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;
+export declare const RUNWAY_FACTOR = 2;
+/** Rebase back when scrollTop drops below this fraction of the runway (away from the logical start). */
+export declare const RUNWAY_REBASE_LOW = 0.25;
+/** Rebase forward when scrollTop rises above this fraction of the runway (away from the logical end). */
+export declare const RUNWAY_REBASE_HIGH = 0.75;
+export declare function createRunwayHandler(config: LogicalScrollConfig): LogicalScrollHandler;
 //# sourceMappingURL=runway.d.ts.map

package/dist/core/state.d.ts

@@ -25,8 +25,8 @@ export interface EngineState {
     /** 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`.
+     * Logical-scroll origin (RFC-012): the virtual offset at the content
+     * element's start, moved by a logical handler (synthetic input, carousel runway). Items render at `getOffset(index) - baseOffset`.
      * Defaults to 0, which makes native mode byte-identical (`offset - 0`).
      */
     baseOffset: number;

package/dist/core/types.d.ts

@@ -90,8 +90,10 @@ export interface ScrollCapability extends ScrollAdapter {
         onContentSize?(px: number): void;
     }): void;
     setTarget(target: EventTarget): void;
-    /** Request the bounded scroll handler in infinite-loop (wrap) mode (carousel). */
-    setBoundedWrap(config: import("./runway").WrapConfig, createHandler: (config: import("./runway").BoundedScrollConfig) => import("./runway").BoundedScrollHandler): void;
+    /** Request a logical handler in infinite-loop (wrap) mode, built by `createHandler` (carousel). */
+    setWrap(config: import("./logical").WrapConfig, createHandler: (config: import("./logical").LogicalScrollConfig) => import("./logical").LogicalScrollHandler): void;
+    /** @deprecated Renamed `setWrap` in 3.0.x; kept for 3.0 plugins. */
+    setBoundedWrap(config: import("./logical").WrapConfig, createHandler: (config: import("./logical").LogicalScrollConfig) => import("./logical").LogicalScrollHandler): void;
     setToPosFn(fn: (index: number, sizeCache: import("./sizes").SizeCache, containerSize: number, totalItems: number, align: string) => number): void;
     setToIndexFn(fn: (index: number, align: string, behavior?: string, duration?: number, easing?: (t: number) => number) => void | false): void;
     onFrame(): void;