Programmable Scroll Engine

Purpose

Many interactive experiences, including narrative and storytelling interfaces, require scroll behaviors that go beyond conventional bounded content scrolling. Examples include circular or looping scrolls, custom smoothness profiles, and scroll states that persist across navigations or app sessions.

This specification defines a Scroll Engine Model: an abstract description of how a one-dimensional scroll axis is represented and controlled. The model is intended to:

• Support a variety of scroll domains, including bounded, unbounded, and circular domains.
• Enable rich control over scroll trajectories (e.g., smoothness, easing, custom motion policies).
• Provide a predictable basis for scroll state persistence across navigations and app sessions.
• Be implementable across multiple platforms and UI toolkits, such as web, Android, iOS, game engines, and custom runtime environments.

Scope

This document defines the abstract data model and high-level architecture of a scroll engine. It does not define concrete API surface or language bindings for specific platforms. Instead, it is expected that separate binding specifications will define how this model maps to:

• DOM and CSSOM View APIs in web browsers,
• native scroll views and list views on platforms such as Android and iOS,
• and other host-specific scroll surfaces.

This edition intentionally omits detailed algorithms for frame stepping, motion policies, input handling, plugins, and middleware. Those may be specified in future modules.

Out of Scope

The following are out of scope for this edition of the specification:

• Detailed algorithms for animation loops, schedulers, and motion policies.
• Concrete APIs (function signatures, classes, or IDL) for specific platforms.
• The definition of user interface design, layout, or content structure beyond what is needed to specify scroll behavior.

Scroll Axis

A scroll axis is a single logical dimension along which scrolling occurs. A scroll axis does not assume a particular physical direction; mapping to horizontal or vertical movement is defined by the host environment.

Scroll Position

A scroll position is a real-valued coordinate on a scroll axis.

The model distinguishes two related notions of position:

• A canonical position is the scroll position normalized into the canonical range of the active scroll domain (for example, [min, max] for a bounded domain or [min, min + period) for circular domains).
• A logical position is an internal representation of position that MAY differ from the canonical position by integer multiples of the domain’s period, particularly in circular domains. Logical positions are used to represent potentially unbounded motion over time.

Scroll Domain

A scroll domain describes the allowed range of scroll positions and how positions behave at or beyond the edges of that range. The kinds of scroll domains are defined in Scroll Domains.

Scroll Operation

A scroll operation is a programmatic request to change the scroll position. A scroll operation typically specifies a desired target position and possibly additional motion parameters (such as instantaneous vs. animated movement).

Impulse

An impulse is a discrete change in scroll position originating from user interaction, such as:

• mouse wheel or trackpad scrolling,
• touch or pen dragging gestures,
• keyboard or keypad navigation,
• gamepad or switch device actions.

Host environments translate such interactions into impulses that can be consumed by the scroll engine.

Origin

The origin of a position update is a tag indicating where the update came from. The following origins are defined:

• "user": updates directly caused by user actions, such as wheel or touch input, keyboard navigation, or actions from assistive technologies.
• "program": updates requested explicitly by application code, such as a scroll-to-section call.
• "momentum": updates that continue motion initially caused by the user, such as inertial scrolling.

Velocity and Direction

Velocity is a measure of the change in canonical position per unit time, as observed by the scroll engine. The exact units of velocity depend on the host environment’s choice of units for positions and time.

Direction is the sign of the most recent non-zero velocity, commonly represented as:

• -1 for movement in the decreasing direction,
• 0 for no movement,
• +1 for movement in the increasing direction.

Frame

A frame is a single evaluation step of the scroll engine in which it:

• considers any pending impulses and scroll operations,
• advances motion over time according to a motion policy, and
• updates observable state.

Scroll Domains

A scroll domain is categorized into one of several domain kinds. Each domain kind defines constraints on canonical positions and behavior at or beyond domain edges.

max = min + period

Engine Observable State

A conforming Scroll Engine Implementation MUST maintain and expose at least the following observable state:

• The current canonical position.
• The active scroll domain and any domain parameters (such as min, max, and period).
• The current velocity and direction, derived from changes in canonical position over time.
• A conceptual target position, representing the position towards which the engine is currently moving. In circular domains, implementations MAY track both canonical and logical components of the target.
• A running flag indicating whether the engine considers the scroll to be “in motion” (for example, during ongoing animation or momentum) or idle.

The concrete API shape used to expose this state is host- and language-specific, but conforming implementations MUST provide some mechanism to observe it.

Scroll State Snapshot

A Scroll State Snapshot captures the scroll engine’s position at a point in time for the purpose of persistence or restoration.

A Scroll State Snapshot MUST contain at least:

• An ordered collection of per-axis positions, where each axis state includes a position field representing the canonical position on that axis.
• A timestamp value, whose units are defined by the host environment (for example, milliseconds since epoch or a monotonic clock).

An abstract shape for a Scroll State Snapshot is:

{
  axes: [{ position: <number> }, ...],
  timestamp: <number>
}

Host environments MAY serialize snapshots to JSON, binary formats, or other representations suitable for their storage mechanisms.

Signals and Origins

A Scroll Engine Implementation MAY expose position updates via an observable scroll signal abstraction. A scroll signal has:

• a current canonical position value, and
• a set of registered listeners.

When the scroll engine updates the canonical position, it MAY notify listeners with:

• the new canonical position, and
• the origin of the update (user, program, or momentum).

Errors thrown by listeners MUST NOT compromise the scroll engine’s internal state or prevent further updates.

Even if a scroll signal abstraction is not used, conforming implementations MUST provide an equivalent mechanism for clients to observe position changes together with their origin.

General Principles

A conforming Scroll Engine Implementation and its Host Environment MUST support accessible scrolling experiences. This includes:

• Ensuring that the user remains in control of scroll motion, and that user input can override programmatic motion.
• Respecting platform accessibility settings, including preferences for reduced motion or similar features.
• Supporting keyboard, keypad, switch, and other assistive input as first-class means of controlling scroll.
• Avoiding motion that cannot be paused, stopped, or overridden by the user.

Reduced Motion and Motion Sensitivity

Host Environments MUST provide a way to propagate a user’s reduced motion preference (or equivalent) into the scroll engine.

When a reduced motion preference is active:

• Programmatic scroll operations SHOULD be implemented as immediate position changes without animation, or use significantly simplified and shortened motion.
• Long-running or continuous auto-scrolling behaviors SHOULD be disabled, minimized, or replaced with non-animated alternatives.

Regardless of motion preferences, the scroll engine MUST allow ongoing motion to be interrupted and overridden by user input.

Keyboard, Keypad, and Switch Input

Host Environments MUST be able to express discrete navigation commands from devices such as keyboards, keypads, gamepads, and switch controls as impulses or scroll operations.

A Scroll Engine Implementation MUST:

• Accept these impulses in the same way as pointer-based input (such as touch or wheel events).
• Produce predictable movements in response to such input, according to the host environment’s conventions (for example, line stepping for arrow keys, page stepping for PageUp/PageDown).

Continuous motion initiated programmatically MUST be interruptible by keyboard or assistive input. A user action SHOULD promptly adjust the target or current position to reflect the user’s intent.

Focus Navigation and Tabbing

When a focusable item becomes focused (for example, via Tab/Shift+Tab or other accessibility navigation commands), the Host Environment MAY request a scroll operation to bring the focused item into view.

A Scroll Engine Implementation MUST:

• Support such focus-driven adjustments as regular scroll operations, using the same domain and motion semantics.
• Avoid trapping focus by repeatedly re-scrolling in a way that prevents the user from moving focus away.

In circular domains, engines MUST NOT induce repeated loops in response to focus changes unless explicitly requested by the Host Environment.

User Override and Priority of User Input

When user-originated input conflicts with ongoing programmatic motion, user input MUST take precedence.

A Scroll Engine Implementation MUST:

• Allow user impulses to override or modify the current target position.
• Stop, pause, or alter ongoing motion accordingly, rather than ignoring user attempts to stop or reverse the motion.

Engines MUST NOT create non-cancelable, non-interruptible scroll loops that continue in spite of user input intended to stop or reverse them.