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 motion profiles, scroll-linked effects, and scroll state that persists across navigations or app sessions.

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

• Support a variety of scroll domains, including bounded, unbounded, and circular domains.
• Expose programmable hooks for host or application code to observe, modify, and respond to scroll behavior, without prescribing concrete API shapes.
• Enable rich control over scroll trajectories (for example, smoothness, easing, and custom motion policies) via pluggable components instead of fixed behavior.
• Provide a predictable basis for scroll state persistence across navigations and app sessions.
• Support explicit configuration of which component is responsible for applying scroll motion to the scroll surface for user-originated and programmatic actions, via scroll authority.
• 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 programmable 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, and specific plugin or middleware formats. It defines abstract extension points and programmable hooks; concrete mechanisms for expressing scroll programs, motion policies, plugins, and host-specific scroll authority configuration may be specified in future modules or host-specific bindings.

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.
• The definition of concrete bindings to platform-specific animation or timing APIs (for example, native animation frameworks or the Web Animations API). Such bindings MAY be defined in separate documents.
• The definition of concrete mechanisms by which host environments apply scroll updates to scroll surfaces (for example, specific methods or properties). This specification only constrains observable behavior and authority semantics.

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, or may choose to apply them directly to the scroll surface depending on the configured scroll authority.

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.

Scroll Authority

Scroll authority describes which component is responsible for applying position changes to a scroll surface for a given category of scroll action. This specification distinguishes two authorities:

• A user scroll authority, which determines whether user-originated impulses are applied to the scroll surface directly by the Host Environment or via the Scroll Engine Implementation.
• A programmatic scroll authority, which determines whether programmatic scroll operations are applied to the scroll surface directly by the Host Environment or via the Scroll Engine Implementation.

For each authority, the controlling component is called a scroll controller. A scroll controller MAY be the Scroll Engine Implementation, the Host Environment, or a composition of both, as defined by host-specific bindings, provided that:

• the scroll engine can observe the resulting canonical positions and origins, and
• Accessibility requirements, including user override, are satisfied.

When the Host Environment is the scroll controller for user or programmatic scroll, it is responsible for applying motion to the scroll surface and informing the scroll engine of resulting positions and origins. When the Scroll Engine Implementation is the scroll controller, it is responsible for computing new positions (for example, via a motion policy) and communicating them to the scroll surface using host-defined mechanisms.

Scroll Authority Profiles

This section defines four common scroll authority profiles in terms of user scroll authority and programmatic scroll authority. Host Environments MAY expose additional or more granular configurations, but any such configuration MUST be reducible to these concepts.

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.

In configurations where the Host Environment is the programmatic scroll authority, the notion of a frame can still be used for observation and coordination, even if the host applies motion using its own scheduling or animation mechanisms.

Motion Policy

A motion policy is an abstract component that determines how scroll positions evolve over time from the current position towards a target position. Examples include instantaneous jumps, exponential easing, critically damped motion, or fixed-duration transitions.

The concrete representation of motion policies (for example, code, configuration objects, or declarative descriptions) is host-specific. This specification only requires that motion policies can be selected or replaced by host or application code in a controlled manner.

When the Host Environment is the programmatic scroll authority, motion policies may be expressed in host-specific APIs while still being conceptually aligned with this model.

Scroll Program

A scroll program is host- or application-defined logic that observes or influences the behavior of a scroll engine via its programmable extension points. A scroll program may:

• observe scroll position, velocity, and direction,
• react to position or lifecycle changes,
• adjust targets or impulses within the constraints of the active scroll domain and configured scroll authorities, or
• coordinate scroll position with other host-defined effects (for example, scroll-linked visual changes).

This specification does not define a particular language or format for scroll programs; it only requires that conforming implementations provide a way for such logic to be attached and invoked.

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 configured user scroll authority and programmatic scroll authority for the axis, or an equivalent representation of which component currently controls user and programmatic motion.

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

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 and scroll programs to observe position changes together with their origin.

Programmable Extension Points

A conforming Scroll Engine Implementation MUST provide one or more abstract extension points that allow host or application code to participate in scroll behavior as scroll programs. Extension points are conceptual hook sites; their concrete API shapes are host-specific.

At minimum, an implementation MUST support the following categories of extension points:

• Observation hooks: mechanisms by which scroll programs can observe changes to canonical position, velocity, direction, domain parameters, target position, and the configured scroll authorities.
• Impulse hooks: mechanisms by which scroll programs can observe or transform impulses before they are applied to the scroll engine, subject to domain constraints, accessibility requirements, and the configured user scroll authority.
• Target hooks: mechanisms by which scroll programs can observe or adjust target positions derived from scroll operations or impulses, before motion is advanced according to a motion policy, and consistent with the configured programmatic scroll authority.
• Lifecycle hooks: mechanisms that notify scroll programs about start, continuation, and settlement of motion, including access to origin information.

Implementations MUST ensure that scroll programs cannot violate the semantics of the active scroll domain. For example, any transformed position or target MUST be interpreted in terms of canonical and logical positions as defined in Scroll Domains.

Host environments MAY expose these extension points as event listeners, callback registries, reactive signals, or other mechanisms, provided that the behavioral guarantees in this section are preserved.

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, including motion initiated by scroll programs, regardless of scroll authority configuration.
• 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.

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, including in configurations where the engine is the programmatic scroll authority.
• Stop, pause, or alter ongoing motion accordingly, rather than ignoring user attempts to stop or reverse the motion.

Host Environments MUST ensure that, when they are the user scroll authority, user interactions can still interrupt or cancel host-driven scrolling behaviors (for example, host-native smooth scrolling) in a manner consistent with platform conventions.

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