vlist: Instructions file for Codex

AGENTS.md — working on vlist

For any coding agent (and any person in a hurry). The project tree and setup are in CONTRIBUTING.md; this page is what that tree does not tell you.

The shape in one paragraph

createVList(config, plugins) (src/core/create.ts) builds a small core — DOM, size cache, element pool, a two-phase render pipeline (src/core/pipeline.ts: calculate into typed arrays, then commit to the DOM) — and hands each plugin a PluginContext (src/core/types.ts: dom, scroll, items, sizes, render, hooks, nav, pool, config, emitter). Everything beyond a plain list is a plugin in src/plugins/<name>/. The default entry scrolls natively; vlist/synthetic owns the input for lists taller than the browser allows.

Contracts that bite

• Three index spaces. Data (the caller's items), layout (what the size cache sees: group headers, grid rows) and, under carousel(), virtual (laps of the data). Convert with the published hooks — _layoutToDataIndex, _dataToLayoutIndex, _getTotal, _getLoadedItem — never by assuming two spaces coincide. data-index and aria-posinset carry the public (data) index; an element's id carries the index it is mounted under.
• One owner per concern. A plugin that owns navigation registers it with ctx.nav.set() (carousel does); one that owns scrolling an item into view publishes _scrollItemIntoView (groups, masonry) or nav.reveal(index) (carousel: the logical item index, the same space as nav.total — not a size-cache or layout index). NavCapability.get() always carries a reveal property (null when no owner set one). Ask the owner; do not scroll behind its back. Read how the keyboard path in src/plugins/selection/plugin.ts and src/plugins/a11y/plugin.ts does it before adding a second path.
• Plugin order is priority, lowest first: layout tier 5–11 (page and autosize 5, groups 11, and grid, table, masonry, tree and carousel all on 10), scrollbar 15, data 20, sortable 30, transition 45, selection and snapshots 50, a11y and search 55. Those five share one number and sortPlugins sorts stably, so among them setup order is whatever order the caller wrote the array in — there is no defined order and you must not rely on one. What keeps that from mattering is that every pair of them is declared incompatible: a plugin that replaces size-cache methods must say which others it conflicts with (conflicts), and a missing declaration shows up as a list that works one way round and hangs the other.
• The hot path allocates nothing. pipeline.ts, state.ts and the scroll handlers run per frame: typed arrays, reused objects, no closures or array literals created per scroll event.
• A plugin pays for its own bytes. bun run size holds a budget per bundle (scripts/size.ts). Code added to src/core/ lands in every bundle; code only one plugin needs lives in that plugin, or behind what the plugin already imports. A budget is a fixed number: going over it means trimming the change, or moving the pin to measured + 1% on the lead/orchestrator's recorded decision in the pull request — never a silent re-measure.
• Public API is small on purpose. A new option or method needs a reason in the issue. Types are derived from the config (src/config.ts); no any, no @ts-ignore.