API reference

active-virtual has two entry points. Most applications use one hook from @workspace/active-virtual/react; a host without React uses the framework-neutral axis store and the browser adapter from @workspace/active-virtual. Everything below is generated from the source, grouped by what you use it for; each export appears in exactly one group. The package's own contract, with its concepts and guarantees, follows at the end.

React#

useVirtualAxis virtualizes one collection along one direction inside a scroll container: it returns what to render (the projection), a ref for each rendered item so its size is measured, and a controller for scroll requests. inspectAxis returns what a mount holds right now, for leak and lifecycle tests. Two axes on one container make a two-dimensional view.

// apps/docs/examples/virtual/long-list.tsx'use client';
import {useState} from 'react';
import {Button} from '@workspace/active-ui/components/primitives/button';import {Input} from '@workspace/active-ui/components/primitives/input';import {Label} from '@workspace/active-ui/components/primitives/label';import {useVirtualAxis} from '@workspace/active-virtual/react';
const COUNT = 10_000;
/** Every seventh row wraps to a second line: the axis measures real heights. */function rowText(position: number): string {  const base = `Row ${(position + 1).toLocaleString('en')}`;  return position % 7 === 3    ? `${base}: a longer note that wraps to a second line in a narrow column, so this row is taller than its estimate.`    : base;}
/** 10,000 rows of varying height; only the rows in view (plus overscan) are in the DOM. */export default function LongList() {  const [container, setContainer] = useState<HTMLDivElement | null>(null);  const [target, setTarget] = useState('5000');  const {projection, controller, itemRef} = useVirtualAxis({    count: COUNT,    estimate: 32,    container,  });  return (    <div className="flex flex-col gap-3">      <form        className="flex flex-wrap items-end gap-2"        onSubmit={(event) => {          event.preventDefault();          const row = Number(target);          if (Number.isInteger(row) && row >= 1 && row <= COUNT)            controller.scrollToPosition(row - 1, {align: 'center'});        }}      >        <div className="flex flex-col gap-1.5">          <Label htmlFor="virtual-target">Row</Label>          <Input            id="virtual-target"            className="w-28"            inputMode="numeric"            value={target}            onChange={(event) => setTarget(event.target.value)}          />        </div>        <Button type="submit" variant="outline">          Go to row        </Button>      </form>      <div        ref={setContainer}        className="bg-background h-72 overflow-auto rounded-md border"        tabIndex={0}        role="region"        aria-label="Ten thousand rows"        data-virtual-container      >        <div style={{height: projection.extent, position: 'relative'}}>          {projection.items.map((item) => (            <div              key={item.identity}              ref={itemRef(item.identity)}              className="border-b px-3 py-1.5 text-sm"              style={{                position: 'absolute',                top: 0,                left: 0,                width: '100%',                transform: `translateY(${item.offset}px)`,              }}              data-position={item.position}            >              {rowText(item.position)}            </div>          ))}        </div>      </div>      <p className="text-muted-foreground text-sm" aria-live="polite">        {projection.items.length} of {COUNT.toLocaleString('en')} rows in the        DOM      </p>    </div>  );}

interface VirtualAxis {
  readonly projection: Projection;
  readonly controller: AxisController;
  itemRef(identity: Key): ItemRef;
  isRendered(identity: Key): boolean;
}

type VirtualAxisOptions = CommonOptions &
  (
    | {readonly count: number; readonly keys?: undefined}
    | {readonly keys: readonly Key[]; readonly count?: undefined}
  );

interface AxisController {
  scrollToPosition(position: number, options?: ScrollOptions): void;
  scrollToIdentity(identity: Key, options?: ScrollOptions): void;
  scrollToOffset(
    offset: number,
    options?: {readonly behavior?: ScrollBehavior},
  ): void;
  scrollBy(delta: number, options?: {readonly behavior?: ScrollBehavior}): void;
  scrollToEdge(
    edge: 'start' | 'end',
    options?: {readonly behavior?: ScrollBehavior},
  ): void;
  invalidate(target: 'all' | readonly Key[], strength?: 'stale' | 'void'): void;
  reset(): void;
  reportSize(identity: Key, size: number): void;
  focus(identity: Key | null): void;
  getProjection(): Projection;
  positionAt(offset: number): number | null;
  boundsOf(
    target: {readonly position: number} | {readonly identity: Key},
  ): ItemBounds | null;
  identityOf(element: Element): Key | null;
}

interface AxisOwnership {
  readonly attached: boolean;
  readonly active: boolean;
  readonly subscribers: number;
  readonly registrations: number;
  readonly observed: number;
  readonly refs: number;
  readonly generation: number;
}

type ContainerSource =
  ScrollContainer | null | (() => ScrollContainer | null);

type ItemRef = (element: Element | null) => (() => void) | undefined;

The axis store, without React#

createAxisStore is the axis itself, without a framework and without the browser: you give it inputs (the collection by count or by key, estimates, measurements, the viewport) and read the projection back. A collection is positional (count) or keyed (keys); with keys, a measurement stays with its item through insertions and removals.

(init: AxisInit, options?: AxisStoreOptions) => AxisStore

interface AxisStore {
  getProjection(): Projection;
  submit(batch: readonly AxisInput[]): void;
  subscribe(listener: ProjectionListener): () => void;
  observeRange(listener: ProjectionListener): () => void;
  positionAt(offset: number): number | null;
  boundsOf(
    target: {readonly position: number} | {readonly identity: Key},
  ): ItemBounds | null;
}

interface AxisStoreOptions {
  readonly sink?: DiagnosticSink;
}

interface AxisInit {
  readonly collection: CollectionInit;
  readonly estimate: EstimateProvider;
  readonly layout?: Partial<LayoutConfig>;
  readonly anchor?: Partial<AnchorPolicy>;
  readonly rangePolicy?: RangePolicy;
  readonly seed?: {
    readonly viewportExtent?: number;
    readonly offset?: number;
    readonly sizes?: ReadonlyArray<readonly [Key, number]>;
  };
}

type AxisInput =
  | {readonly type: 'viewport'; readonly extent: number}
  | {
      readonly type: 'scroll';
      readonly offset: number;
      readonly phase: ScrollPhase;
      readonly echo?: boolean;
      readonly time?: number;
    }
  | {
      readonly type: 'measure';
      readonly identity: Key;
      readonly epoch: number;
      readonly size: number;
    }
  | {
      readonly type: 'invalidate';
      readonly epoch: number;
      readonly target: 'all' | readonly Key[];
      readonly strength: InvalidationStrength;
    }
  | {readonly type: 'estimate'; readonly estimate: EstimateProvider}
  | {readonly type: 'layout'; readonly layout: Partial<LayoutConfig>}
  | {readonly type: 'count'; readonly count: number}
  | {readonly type: 'keys'; readonly keys: readonly Key[]}
  | {readonly type: 'edit'; readonly edits: readonly CollectionEdit[]}
  | {readonly type: 'reset'}
  | {readonly type: 'anchor'; readonly policy: Partial<AnchorPolicy>}
  | {readonly type: 'range-policy'; readonly policy: RangePolicy | null}
  | {readonly type: 'focus'; readonly identity: Key | null}
  | {
      readonly type: 'scroll-to';
      readonly target: ScrollTarget;
      readonly align?: ScrollAlign;
      readonly behavior?: ScrollBehavior;
    }
  | {readonly type: 'tick'; readonly time: number; readonly visible: boolean}
  | {readonly type: 'user-input'};

type CollectionEdit =
  | {readonly op: 'insert'; readonly at: number; readonly keys: readonly Key[]}
  | {readonly op: 'remove'; readonly at: number; readonly count: number}
  | {
      readonly op: 'move';
      readonly from: number;
      readonly count: number;
      readonly to: number;
    }
  | {
      readonly op: 'replace';
      readonly at: number;
      readonly keys: readonly Key[];
    };

type EstimateProvider =
  number | ((position: number, identity: Key) => number);

interface LayoutConfig {
  readonly paddingStart: number;
  readonly paddingEnd: number;
  readonly gap: number;
  readonly listOrigin: number;
  readonly scrollPaddingStart: number;
  readonly scrollPaddingEnd: number;
  readonly overscan: number | AdaptiveOverscan;
  readonly lanes: number;
  readonly enabled: boolean;
  readonly debug: boolean;
}

type SizeAuthority = 'estimated' | 'seeded' | 'measured' | 'stale';

The browser adapter#

createScrollHost connects axes to a real scroll container: it observes the viewport and the item sizes and carries out the scroll writes an axis asks for. A container has one live host: createScrollHost throws when it already has one, findScrollHost returns it. toLogical and toPhysical convert between the physical scroll position and the logical one of the reading direction, so right to left needs no special case in your code.

(container: ScrollContainer, options?: ScrollHostOptions) => ScrollHost

(container: ScrollContainer) => ScrollHost | null

interface AxisAttachment {
  observeItem(element: Element, identity: Key): () => void;
  identityOf(element: Element): Key | null;
  detach(): void;
}

interface AxisAttachmentOptions {
  readonly orientation: Orientation;
  readonly direction?: 'ltr' | 'rtl';
  readonly sizeOf?: SizeReader;
}

interface ScrollHost {
  readonly container: ScrollContainer;
  attach(store: AxisStore, options: AxisAttachmentOptions): AxisAttachment;
  flush(): void;
  dispose(): void;
}

interface ScrollHostOptions {
  readonly scrollEnd?: 'native' | 'quiet';
  readonly idleDelay?: number;
  readonly nativeAnchoring?: 'suppress' | 'report';
}

type SizeReader = (element: Element, orientation: Orientation) => number;

interface ScrollPlane {
  readonly orientation: Orientation;
  readonly rtl: boolean;
}

The projection#

What to render, as a value: the rendered items with their offsets and sizes, the visible and rendered bounds, the extent to give the content, and a status. The range policy decides which positions are rendered: by default the visible ones and the overscan around them; it may add a pinned or focused item.

interface AdaptiveOverscan {
  readonly min: number;
  readonly max: number;
  readonly gain?: number;
}

type GeometryChange =
  | 'viewport'
  | 'measure'
  | 'invalidate'
  | 'estimate'
  | 'layout'
  | 'count'
  | 'keys'
  | 'edit'
  | 'reset';

interface ItemBounds {
  readonly position: number;
  readonly start: number;
  readonly end: number;
}

interface PositionRun {
  readonly first: number;
  readonly last: number;
}

interface ProjectedItem {
  readonly identity: Key;
  readonly position: number;
  readonly offset: number;
  readonly size: number;
  readonly end: number;
  readonly authority: SizeAuthority;
  readonly lane: number;
}

interface Projection {
  readonly status: ProjectionStatus;
  readonly epoch: number;
  readonly count: number;
  readonly items: readonly ProjectedItem[];
  readonly visible: PositionRun | null;
  readonly rendered: PositionRun | null;
  readonly extent: number;
  readonly layoutExtent: number;
  readonly phase: ScrollPhase;
  readonly renderOrigin: number;
  readonly slack: number;
}

type ProjectionStatus =
  'awaiting-viewport' | 'seeded' | 'live' | 'disabled';

interface RangeContext {
  readonly count: number;
  readonly visible: PositionRun;
  readonly positions: readonly number[];
  readonly direction: ScrollDirection | null;
  readonly overscan: {readonly before: number; readonly after: number};
}

type RangePolicy = (context: RangeContext) => readonly number[];

Anchoring and scrolling#

When geometry changes (a measurement arrives, items are inserted above, an estimate changes), the anchor decides which item keeps its place in the viewport. A scroll request goes to an item, an offset, a delta or an edge; the latest request wins, and a request to an item converges as its surroundings are measured.

// apps/docs/examples/virtual/keyed-prepend.tsx'use client';
import {useState} from 'react';
import {Button} from '@workspace/active-ui/components/primitives/button';import {useVirtualAxis} from '@workspace/active-virtual/react';
interface Message {  key: string;  text: string;}
function messages(from: number, count: number): Message[] {  return Array.from({length: count}, (_, index) => {    const n = from + index;    return {key: `m${n}`, text: `Message ${n}`};  });}
/** * A keyed list: loading older messages above the viewport does not move what * is on screen, because the axis anchors on a key and compensates the scroll. */export default function KeyedPrepend() {  const [container, setContainer] = useState<HTMLDivElement | null>(null);  const [items, setItems] = useState(() => messages(100, 50));  const {projection, itemRef} = useVirtualAxis({    keys: items.map((item) => item.key),    estimate: 36,    container,    // Keep the item at the top in place even when the list is scrolled to    // its very start, instead of following that edge.    startEdge: 'preserve',  });  const byKey = new Map(items.map((item) => [item.key, item]));  const first = Number(items[0]!.key.slice(1));  return (    <div className="flex flex-col gap-3">      <div className="flex flex-wrap items-center gap-2">        <Button          variant="outline"          disabled={first === 0}          onClick={() =>            setItems((list) => [              ...messages(Math.max(0, first - 20), Math.min(20, first)),              ...list,            ])          }        >          Load 20 older messages        </Button>        <span className="text-muted-foreground text-sm" aria-live="polite">          {items.length} messages, from {items[0]!.text}        </span>      </div>      <div        ref={setContainer}        className="bg-background h-60 overflow-auto rounded-md border"        tabIndex={0}        role="region"        aria-label="Messages"        data-virtual-container      >        <div style={{height: projection.extent, position: 'relative'}}>          {projection.items.map((item) => (            <div              key={item.identity}              ref={itemRef(item.identity)}              className="border-b px-3 py-2 text-sm"              style={{                position: 'absolute',                top: 0,                left: 0,                width: '100%',                transform: `translateY(${item.offset}px)`,              }}            >              {byKey.get(String(item.identity))?.text}            </div>          ))}        </div>      </div>    </div>  );}

type AnchorChoice =
  | {readonly kind: EdgeAnchorKind}
  | {
      readonly kind: 'keyed';
      readonly identity: Key;
      readonly fallback?: EdgeAnchorKind;
    }
  | {readonly kind: 'focus'; readonly fallback?: EdgeAnchorKind}
  | {readonly kind: 'none'};

interface AnchorContext {
  readonly change: GeometryChange;
  readonly visible: readonly Key[];
}

interface AnchorPolicy {
  readonly anchor: AnchorChoice | AnchorChooser;
  readonly startEdge: EdgeBehavior;
  readonly endEdge: EdgeBehavior;
}

type ScrollAlign = 'start' | 'center' | 'end' | 'auto';

type ScrollTarget =
  | {readonly kind: 'identity'; readonly identity: Key}
  | {readonly kind: 'position'; readonly position: number}
  | {readonly kind: 'offset'; readonly offset: number}
  | {readonly kind: 'delta'; readonly delta: number}
  | {readonly kind: 'edge'; readonly edge: 'start' | 'end'};

Diagnostic types#

Misuse and limits are reported as diagnostics: a level (warn or debug), a stable code, a message and primitive data. The codes are listed in the contract below.

interface Diagnostic {
  readonly level: DiagnosticLevel;
  readonly code: DiagnosticCode;
  readonly message: string;
  readonly data: Readonly<Record<string, Key | boolean | null>>;
}

type DiagnosticCode =
  | 'invalid-observation'
  | 'unknown-identity'
  | 'stale-epoch'
  | 'invalid-request'
  | 'intent-target-missing'
  | 'intent-target-removed'
  | 'intent-gave-up'
  | 'anchor-missing'
  | 'anchor-replaced'
  | 'invalid-range'
  | 'scroll-unreachable'
  | 'native-anchoring-active'
  | 'measurement-unavailable';

type DiagnosticSink = (diagnostic: Diagnostic) => void;

The package's contract#

The supported contract of @workspace/active-virtual, a workspace-private package: only what the two entry points export is API. The export lists are pinned by src/__tests__/public-api.test.ts; per-symbol TSDoc lives in the sources, and the compiler is authoritative on types. How the engine works is in ARCHITECTURE.md; the release history in CHANGELOG.md.

Entry points#

react and react-dom (^19) are optional peers, needed only for ./react. Importing either entry needs no DOM: nothing reads a browser global at import time.

// Root: valuesexport {  createAxisStore,  createScrollHost,  findScrollHost,  toLogical,  toPhysical,};// Root: typesexport type {  AdaptiveOverscan,  AnchorChoice,  AnchorContext,  AnchorPolicy,  AxisAttachment,  AxisAttachmentOptions,  AxisInit,  AxisInput,  AxisStore,  AxisStoreOptions,  CollectionEdit,  Diagnostic,  DiagnosticCode,  DiagnosticSink,  EdgeAnchorKind,  EstimateProvider,  GeometryChange,  ItemBounds,  Key,  LayoutConfig,  Orientation,  PositionRun,  ProjectedItem,  Projection,  ProjectionStatus,  RangeContext,  RangePolicy,  ScrollAlign,  ScrollBehavior,  ScrollContainer,  ScrollDirection,  ScrollHost,  ScrollHostOptions,  ScrollPlane,  ScrollTarget,  SizeAuthority,  SizeReader,};
// ./reactexport {useVirtualAxis, inspectAxis};export type {  AxisController,  AxisOwnership,  ContainerSource,  ItemRef,  VirtualAxis,  VirtualAxisOptions,};

Concepts#

• One axis. An axis virtualizes one ordered collection along one direction. Two-dimensional use is two axes on one scroll container: they share the container's scroll host and nothing else.

• Identity. A collection is either positional (count: the position is the identity, within a collection epoch) or keyed (keys: a consumer key stays with its item through every change). Measurements belong to the identity. A reset starts a new epoch; anything issued under an older epoch no longer names an item. Within an epoch a key names the item that carries it now: a key that is removed and inserted again (also within one edit list), or replaced under the same key, is a new item that starts from its estimate. A measurement that arrives after the reinsertion, from whichever element, is the new item's; use a new key or a reset where that must not happen.

• Estimates and measurements. Every item has a size: its estimate until a measurement arrives, the measurement afterwards. Measurements arrive asynchronously, through the browser adapter or reportSize.

• Projection. What to render: the rendered items with their offsets and sizes, the visible and rendered bounds, the extent to give the content, and a status. A projection is a value; no array or object identity is part of the contract.

• Anchor. Which item keeps its place in the viewport when geometry changes (a measurement, an insertion, a new estimate, a reset). The compensation is a scroll write.

• Scroll request. A request to an item, an offset, a delta or an edge. The latest request wins; a request to an item converges on it as its surroundings are measured, within a bounded budget.

Coordinates: projected item offsets and the extent are in the content box (the start of the list's leading padding is 0). Scroll offsets are logical: the content box plus the list origin, growing from the inline start in both text directions. The browser adapter alone knows physical offsets and the right-to-left convention.

Framework-neutral use (root entry)#

createAxisStore(init, options?)#

function createAxisStore(init: AxisInit, options?: AxisStoreOptions): AxisStore;

Creates one axis. Throws RangeError for invalid configuration (a negative or non-integer count, duplicate keys, an invalid length, overscan, lane count, estimate or seed).

AxisInit:

LayoutConfig (every length finite and >= 0):

AdaptiveOverscan is {min, max, gain?}: min items at rest, one more per 1 / gain of scroll speed (logical units per second when the adapter reports milliseconds), never more than max; gain defaults to 0.01. While scrolling, the full count goes ahead and a smaller share, at least one item, stays behind.

AxisStoreOptions: {sink?: DiagnosticSink}. Without a sink, diagnostics are dropped; the engine never writes to the console.

AxisStore#

The handle carries exactly these members; only createAxisStore makes one, and only such a handle can be attached to a scroll host.

Inputs (AxisInput)#

ScrollTarget is {kind: 'position', position}, {kind: 'identity', identity}, {kind: 'offset', offset}, {kind: 'delta', delta} or {kind: 'edge', edge: 'start' | 'end'}.

The projection#

A projection is published only when a value a renderer can read changed; scrolling inside an unchanged window publishes nothing.

Extent semantics. A structural change (collection, estimate, layout, reset, void invalidation) re-bases the presented extent at once, also during a scroll episode. A measurement during a scroll episode leaves the presented extent frozen until the episode ends. The declared extent is authoritative: scroll requests and compensations are clamped to listOrigin + extent - viewport. Content that follows the list inside the container is declared as paddingEnd, content before it as listOrigin (DECISIONS.md D-6).

Anchoring#

AnchorPolicy is {anchor, startEdge, endEdge}:

• anchor: an AnchorChoice or a function (context: AnchorContext) => AnchorChoice, called for each geometry change with {change: GeometryChange, visible: Key[]}. GeometryChange is one of viewport, measure, invalidate, estimate, layout, count, keys, edit, reset.

• AnchorChoice: {kind: 'start-edge'} (the first item starting at or after the viewport start keeps its distance to it), {kind: 'end-edge'} (the last item ending at or before the viewport end), {kind: 'keyed', identity, fallback?}, {kind: 'focus', fallback?}, or {kind: 'none'}.

• startEdge, endEdge: follow keeps an attached viewport at that edge (append-follow for a feed), preserve keeps the item anchor. An edge is attached within 1 logical unit.

When the anchored item is removed, the nearest surviving successor takes its place, else the nearest surviving predecessor, else the edge (DECISIONS.md D-5). While a scroll request is active it owns the offset: nothing is compensated.

A function passed as anchor is compared by identity: a new function is a new policy.

Scroll requests#

• align: start, center, end, or auto (the default): no movement when the item is fully inside the padded viewport, otherwise the nearest edge. An item that ends the content, aligned end, targets the end of the scroll range.

• behavior: instant (the default) or smooth.

• The latest request wins, also when it is submitted from a listener during a transition. A request that ends without settling (superseded, interrupted, its target missing or removed, given up) before its write has reached the browser writes nothing: its pending write is withdrawn, a compensation it replaced still lands, and the other axis's writes are untouched. A smooth animation the browser is already running for a request ends with that request's authority: when a newer request supersedes it, a collection change removes its target, or input interrupts it, the browser adapter stops the animation, also when the newer request writes nothing (a missing item, or auto to an item already visible). It stops at the offset the axis last observed, the one the newer request was resolved against; on input the adapter sees itself, where the container is. A newer smooth request replaces the animation with its own write. Only the ended request's direction loses its motion: the other axis's smooth request carries on. An animation is not stopped when its request settles or gives up, nor when the user takes over by moving the container.

• A request to an item or an edge converges: it settles when the offset has reached a target that stayed put for 2 ticks, and gives up with an intent-gave-up warning after 10 writes or 2 000 time units of visible time. Hidden time does not count. A smooth re-target of an animation still on its way does not count as a write.

• A request whose instant write lands short of its target keeps that target and never settles short of it. It writes again when its target moves, and when the container's scroll range has grown since the write landed (a layout that caught up with a grown extent after the write): the same target, for the same active request, only on growth and never because time passed. A retry is no new request: the write and visible-time budgets run on unchanged, and a target that stays out of reach gives up as before.

• A user scroll (wheel, touch, a press on the scrollbar, or an offset the request cannot explain) ends it.

• A request belongs to the axis, not to its container. A request that has not written yet is carried out on the next container the axis attaches to. A request that has written is tested against the new container's first observation like any observation: an offset it cannot explain ends it as interrupted; otherwise it carries on and writes again only when its target moves.

• A request for an item not in the collection warns (intent-target-missing); a collection change that removes the target ends it (intent-target-removed).

• During a smooth request, measurements far from the target are held back and applied when the request ends, however it ends. A held measurement keeps only the authority it had when it arrived: a newer accepted measurement of the item, an invalidation of it (either strength), a reset, or the item leaving the collection withdraws it before it is applied.

Range policy and observation#

A RangePolicy receives {count, visible, positions, direction, overscan} (the default rendered positions, ascending) and returns the positions to render, in rendered order: it may add a pinned or focused item or leave items out. A position outside the collection or a repeat is left out with an invalid-range warning. AxisStore.observeRange notifies range changes; the engine fetches nothing.

Lanes#

With lanes > 1, items are placed in collection order into the first empty lane, then into the lane that ends first (ties to the lowest lane), and keep their lane when measured. Visibility and overscan are per lane; the rendered set is in collection order and may be sparse. A lane-count change keeps the measurements, which belong to the identity; a consumer whose sizes depend on the lane width invalidates them.

Browser adapter (root entry)#

createScrollHost(container, options?), findScrollHost(container)#

function createScrollHost(  container: HTMLElement | Window,  options?: ScrollHostOptions,): ScrollHost;function findScrollHost(container: HTMLElement | Window): ScrollHost | null;

One live host per container; createScrollHost throws when the container has one, findScrollHost returns it. Every browser object comes from the container's own window, so an iframe's window is served through itself.

ScrollHostOptions:

ScrollHost: attach(axis, options), flush() (applies pending writes now), dispose(), container.

attach(axis, {orientation, direction?, sizeOf?}) returns an AxisAttachment. The axis's first input is the container's current offset (an already scrolled container keeps its position), and the scroll requests held while nothing was attached follow in the same transition. direction (ltr or rtl) is read from the container when omitted; sizeOf(element, orientation) replaces the default size, the border box along the axis rounded to whole pixels. Throws TypeError for an axis createAxisStore did not make.

AxisAttachment: observeItem(element, identity) measures the element as that item under the current epoch and returns the function that ends exactly that association; identityOf(element); detach().

Observation is routed per direction: a vertical scroll reaches only vertical axes. The scroll writes of one task are merged into one physical write per container, so a row and a column request of the same turn both land. After every instant write the axis takes the offset the browser actually reached, also when the write moved nothing and no scroll event follows, so the projection shows what the viewport shows. A write that lands short warns (scroll-unreachable); its request keeps its target, is written again only when that target moves, never settles, and gives up at its budget. Listeners, the resize observer, the frame and the idle timer exist only while an axis is attached.

toLogical(plane, physical), toPhysical(plane, logical)#

interface ScrollPlane {  orientation: 'vertical' | 'horizontal';  rtl: boolean;}function toLogical(plane: ScrollPlane, physical: number): number;function toPhysical(plane: ScrollPlane, logical: number): number;

The one conversion between the browser's physical scroll offset and the logical offset the core works in (D-12). A logical offset grows from the start of the scroll content toward its end in both directions; a horizontal right-to-left scroller follows the CSSOM View convention (0 at the inline start, negative toward the inline end). A vertical plane and a left-to-right plane are the identity. Published so a consumer that reads or writes scrollLeft beside an attached axis (active-grid's header/body sync, ADR-053) uses this conversion instead of a second one.

React adapter (./react)#

useVirtualAxis(options)#

const {projection, controller, itemRef, isRendered} = useVirtualAxis({  count: rows.length,  estimate: 36,  container: scrollElement,});

Options: count or keys (exactly one), estimate, orientation (vertical by default), the LayoutConfig fields (paddingStart, paddingEnd, gap, listOrigin, scrollPaddingStart, scrollPaddingEnd, overscan, lanes, enabled, debug), anchor, startEdge, endEdge, rangePolicy, and:

Contract:

• Render-time reads are current. The render reads the committed state with this render's inputs applied: a new count, keys, estimate, layout field or enablement shows in the render that passes it. Every change of the window or the extent re-renders the component.

• Inputs are compared by value where they are data and by identity where they are functions: a new estimate function, anchor chooser or range policy is a change. Keep them stable (module level or useCallback).

• A change of identity mode or orientation starts a new axis.

• Invalid options throw a RangeError in the render that passes them.

• Nothing happens during render besides computing. The axis attaches to the container's scroll host (shared with the other axes of that container) for the committed lifetime of the mount; development StrictMode leaves one attachment, and an unmount leaves nothing.

• No identity of projection or its arrays is promised; derive stability from values.

VirtualAxis:

AxisController: scrollToPosition(position, {align?, behavior?}), scrollToIdentity(identity, options?), scrollToOffset(offset, {behavior?}), scrollBy(delta, {behavior?}), scrollToEdge(edge, {behavior?}), invalidate(target, strength = 'stale'), reset(), reportSize(identity, size), focus(identity | null), and the queries getProjection(), positionAt(offset), boundsOf(target), identityOf(element) on the committed state. Commands never run during render; a scroll request made before the axis is attached is carried out after it attaches.

inspectAxis(controller) returns AxisOwnership, what the mount holds right now (attached, active, subscribers, registrations, observed, refs, generation), for leak and lifecycle tests.

Diagnostics#

A Diagnostic is {level: 'warn' | 'debug', code, message, data}; data holds primitives only. Codes: invalid-observation, unknown-identity, stale-epoch, invalid-request, intent-target-missing, intent-target-removed, intent-gave-up, anchor-missing, anchor-replaced, invalid-range, scroll-unreachable, native-anchoring-active, measurement-unavailable. Debug diagnostics exist only with debug: true.

Guarantees and limits#

Guaranteed in Chromium, Firefox and WebKit, proven by the browser suite in e2e/ (pnpm --filter @workspace/active-virtual test:browser):

• The viewport follows an element, a window or an iframe's window; attaching keeps an offset the container was already scrolled to.

• Items are measured by identity and epoch; a stale element or an older epoch never changes the current item.

• An item that grows above the viewport, and a prepend, leave the visible item in place.

• A request to an item converges on it under poor estimates; the latest request wins, and a request superseded before its write reaches the browser leaves the container where it was; a user wheel or an offset the request cannot explain ends it, after which it writes nothing. The browser's smooth animation of a request stops when a newer request supersedes it, also one that writes nothing, and when input the adapter sees interrupts it; the other axis's animation lands.

• Measurements held back during a smooth request are applied when it ends; hidden time does not count against its budget.

• A row and a column request of the same turn become one physical write, and both land.

• Right to left on horizontal axes; CSS sticky content keeps working (the adapter applies no transform or containment).

• A target beyond the browser's scroll range is reported (scroll-unreachable) and never claimed as reached; the axis follows the offset the browser reached, also when the write moved nothing.

• After detach no listener, observation, frame or timer remains.

• The React adapter: one attachment under StrictMode, nothing left after unmount, the same guarantees through the hook.

Best effort, measured 2026-09-25 with Playwright 1.63.0 on Windows (Chromium 153, Firefox 155, Playwright's WebKit 26.6); not promised:

Not proven: touch and momentum in Firefox and WebKit, real tab hiding (the visibility signal is simulated), a Safari build, nested scroll containers, and vertical writing modes: the default measurement assumes a horizontal writing mode. Content beyond a browser's practical extent limit is not hidden; a write that lands short is reported and the request never settles. A write that lands short because the container has not laid out a grown extent yet is written again once the scroll range has grown, within the request's budget.