Scroll Timing API proposal - clarifications to some definitions (#1233)

* Updates to clarify some of the definitions used in scroll timing API

* Enhance scroll timing proposal with detailed frame counting and smoothness metrics

* Refine entry emission rules for scroll sources in the Scroll Timing API proposal

* Add detailed examples for 150ms timeout mechanics in Scroll Timing API proposal

* Clarify boundary conditions and overscroll effects in scroll performance metrics

* Clarify duration calculation and entry emission rules in Scroll Timing API proposal

* Clarify programmatic scroll entry emission rules and provide an example for combined entries in the Scroll Timing API proposal

---------

Co-authored-by: Noam Helfman <noamh@microsoft.com>

Author: nhelfman

PerformanceScrollTiming/DESIGN_NOTES.md

@@ -70,6 +70,50 @@ Even if scroll starts quickly, dropped frames during scrolling create visible ja
 - Image decoding on the main thread
 - Garbage collection pauses
 
+### Frame Counting and Stationary Periods
+
+The frame counting mechanism (`framesExpected` vs `framesProduced`) is designed to measure **rendering performance during active scrolling**, not to penalize intentionally slow or paused scroll gestures.
+
+**Core principle:**
+During an active scroll gesture, the browser is expected to produce visual updates that reflect scroll position changes. `framesExpected` represents the number of opportunities (display refresh cycles) to update the display during the scroll duration, while `framesProduced` counts how many of those opportunities actually resulted in a position change being rendered.
+
+**Handling of stationary periods:**
+
+1. **Very slow scrolls**: For animated or smooth scrolls where scroll velocity results in sub-pixel movement per frame, implementations SHOULD still count a frame as "produced" if the browser attempted to update the scroll position, even if pixel-level rounding results in identical rendered positions across consecutive frames. The intent is to measure rendering pipeline performance, not scroll speed.
+
+2. **Mid-gesture pauses**: When a user pauses during a continuous touch gesture (finger down but not moving), the 150ms scroll-end detection threshold determines when the entry completes. Brief pauses under 150ms remain part of the same entry:
+   - Frames during the pause are included in `framesExpected` (the scroll is still "active")
+   - Frames during the pause typically won't increment `framesProduced` (no position change)
+   - This reflects that the rendering pipeline had opportunities to update but the input velocity was zero
+
+3. **Discrete scroll events with gaps**: For input sources like keyboard or wheel scrolling, multiple discrete events within 150ms are combined into a single entry:
+   - Example: Key held for 100ms, released, then pressed again after 40ms → combined into one entry
+   - Frames during the 40ms gap count toward `framesExpected`
+   - This reflects the continuous nature of the user's scrolling intent, even if input delivery is discrete
+
+**Interpreting smoothness scores:**
+
+The smoothness score (`framesProduced / framesExpected`) measures **motion continuity** during the scroll interaction. A low smoothness score can indicate:
+- **Dropped frames**: The browser couldn't render updates fast enough (performance issue)
+- **Very slow scroll velocity**: Intentionally slow scrolling where position changes less frequently than the refresh rate (not a performance issue)
+- **Pauses and gaps**: User paused mid-gesture or discrete input events had temporal gaps (not a performance issue)
+
+Developers should consider scroll velocity and duration when interpreting smoothness:
+- High velocity + low smoothness = likely rendering performance issue
+- Low velocity + low smoothness = may be intentional slow scroll
+- Short duration + low smoothness but high `framesProduced` = likely fine (few expected frames due to brief interaction)
+
+**Rationale for current design:**
+
+Alternative designs considered:
+1. **Only count "active motion" frames in `framesExpected`**: This would require detecting scroll velocity and excluding frames with zero velocity. However, this is complex to specify (what threshold defines "active"?), makes the metric harder to reason about, and obscures the difference between "couldn't render" and "no motion."
+
+2. **Separate `duration` into active vs. total time**: This adds API surface complexity and still requires defining "active" scrolling.
+
+The current design provides raw measurements that allow developers to calculate derived metrics based on their specific needs. The trade-off is that smoothness scores must be interpreted in context with velocity and duration.
+
+**Open question**: Should we provide additional metrics to help distinguish rendering performance issues from intentional low-velocity scrolling? See [OPEN_QUESTIONS.md](OPEN_QUESTIONS.md#smoothness-scoring-options) for related discussion on smoothness calculation methods.
+
 ## Scroll Checkerboarding
 Scroll checkerboarding occurs when content is not ready to be displayed as it scrolls into the viewport, resulting in blank or placeholder areas.
 
@@ -160,8 +204,8 @@ Scroll interactions can be interrupted or cancelled mid-stream. This section def
    - `duration` includes the snap animation time
 
 5. **Boundary collision**: Scroll reaches container bounds and cannot continue.
-   - Entry ends naturally when scrolling stops at the boundary
-   - Overscroll/bounce effects (on supported platforms) are included in `duration`
+   - Entry ends when scrolling reaches the boundary (last actual scroll position change)
+   - Overscroll/bounce effects (platform visual effects) are NOT included in measurements - they are not developer-controllable and don't reflect scroll performance
 
 **Entry emission timing:**
 Entries are emitted after the scroll interaction fully completes (including momentum, snap, and settle phases). Interrupted scrolls emit entries at the interruption point with metrics reflecting the partial interaction.
@@ -183,9 +227,10 @@ This section documents expected behavior for boundary conditions and unusual sce
 
 **Overscroll and bounce effects:**
 - On platforms with overscroll (iOS rubber-banding, Android overscroll glow):
-   - `deltaX`/`deltaY` reflect the actual scroll position change, not the visual overscroll
-  - `duration` includes the bounce-back animation time
-  - Overscroll does not count as checkerboarding
+   - The scroll entry ends when the scrollable boundary is reached
+   - `deltaX`/`deltaY` reflect the actual scroll distance to the boundary, not the visual overscroll effect
+   - `duration` ends when the scroll reaches the boundary, NOT including the bounce-back animation time
+   - Overscroll bounce-back is a platform visual effect that developers cannot control or optimize, so it is not measured
 
 **Scroll-linked animations:**
 - If the page uses `scroll-timeline` or JavaScript scroll-linked animations:

PerformanceScrollTiming/explainer.md

@@ -20,6 +20,7 @@
 - [Proposed Approach](#proposed-approach)
   - [`PerformanceScrollTiming` Interface](#performancescrolltiming-interface)
   - [Attribute Reference](#attribute-reference)
+  - [Entry Emission Rules](#entry-emission-rules)
   - [Example Usage with PerformanceObserver](#example-usage-with-performanceobserver)
   - [Dependencies on non-stable features](#dependencies-on-non-stable-features)
   - [Design Notes](#design-notes)
@@ -109,10 +110,10 @@ interface PerformanceScrollTiming : PerformanceEntry {
 | `name` | DOMString | Always `"scroll"` (inherited from PerformanceEntry) |
 | `startTime` | DOMHighResTimeStamp | Timestamp of the first input event that initiated the scroll or code invocation timestamp for programmatic scroll|
 | `firstFrameTime` | DOMHighResTimeStamp | Timestamp when the first visual frame reflecting the scroll was presented |
-| `duration` | DOMHighResTimeStamp | Total scroll duration from `startTime` until scrolling stops (includes momentum/inertia) |
-| `framesExpected` | unsigned long | Number of frames that should have rendered at the target refresh rate |
-| `framesProduced` | unsigned long | Number of frames actually rendered during the scroll |
-| `checkerboardTime` | DOMHighResTimeStamp | Total duration (ms) that unpainted areas were visible during scroll |
+| `duration` | DOMHighResTimeStamp | Total scroll duration from `startTime` to the last scroll position change. Entry emission is triggered when: (1) no scroll position changes have occurred for 150ms (inactivity detection), or (2) a scroll end event is explicitly signaled (e.g., `touchend`, `scrollend`). The 150ms timeout is for detecting when scrolling has stopped, but is not included in the duration. Includes momentum/inertia phases. |
+| `framesExpected` | unsigned long | Number of frames that would be rendered at the display's refresh rate during the scroll duration. Implementations SHOULD use the actual display refresh rate when available, and MAY fall back to 60Hz as a default. Calculated as `ceil(duration / vsync_interval)`. |
+| `framesProduced` | unsigned long | Count of distinct visual updates presented to the display that reflected scroll position changes. A frame is considered "produced" when it is presented and contains a different scroll position than the previous frame. |
+| `checkerboardTime` | DOMHighResTimeStamp | Duration (ms) during which any visible area of the scrolled content was not fully painted. Implementations MAY return 0 if unpainted region visibility is not tracked. |
 | `deltaX` | long | Horizontal scroll delta in pixels (positive = right, negative = left) |
 | `deltaY` | long | Vertical scroll delta in pixels (positive = down, negative = up) |
 | `scrollSource` | DOMString | Input method: `"touch"`, `"wheel"`, `"keyboard"`, `"other"`, or `"programmatic"` |
@@ -125,6 +126,135 @@ interface PerformanceScrollTiming : PerformanceEntry {
 - **Total distance**: `√(deltaX² + deltaY²)` — Euclidean scroll distance
 - **Scroll velocity**: `totalDistance / duration * 1000` — scroll speed in pixels per second
 
+### Understanding Frame Counts and Smoothness
+
+**Frame counting during stationary periods:**
+
+The `framesExpected` metric counts all frame opportunities during the scroll `duration`, including periods where scroll velocity is zero (pauses, gaps between discrete events). The `framesProduced` metric only counts frames where the scroll position actually changed.
+
+This means:
+- **Very slow scrolls** (less than ~1 pixel per frame) will show lower smoothness scores even if rendering is perfect
+- **Pauses mid-gesture** (touch finger stationary, but not lifted) will reduce smoothness scores
+- **Discrete scrolls with gaps** (keyboard presses with temporal gaps, combined due to 150ms threshold) include gap frames in expected count
+
+**Why this design?**
+
+This approach provides raw, unfiltered measurements of rendering opportunities vs. actual updates. Developers can combine smoothness with velocity and duration to distinguish:
+- **Performance issues**: High velocity + low smoothness = dropped frames
+- **Intentional behavior**: Low velocity + low smoothness = slow/paused scroll
+
+Alternative designs that exclude "stationary" frames from `framesExpected` would require arbitrary velocity thresholds and obscure the distinction between "couldn't render" and "no motion."
+
+For advanced use cases, developers can implement custom logic to filter or segment scroll entries based on velocity characteristics before calculating aggregate smoothness metrics.
+
+For detailed discussion of frame counting behavior, see the "Frame Counting and Stationary Periods" section in [DESIGN_NOTES.md](DESIGN_NOTES.md#frame-counting-and-stationary-periods).
+
+### Entry Emission Rules
+
+This section defines when `PerformanceScrollTiming` entries are emitted.
+
+#### Entry Granularity by Scroll Source
+
+Entry emission rules vary by input type to match natural interaction boundaries:
+
+| Scroll Source | Entry Boundary |
+|--------------|----------------|
+| `"touch"` | One entry per continuous gesture (`touchstart` → `touchend`), split on direction changes |
+| `"wheel"` | One entry per scroll interaction; consecutive wheel events are combined into a single entry if they occur within 150ms of each other |
+| `"keyboard"` | One entry per key repeat sequence (from `keydown` until key release + 150ms inactivity) |
+| `"programmatic"` | One entry per scroll interaction; consecutive programmatic scroll calls (e.g., `scrollTo()`, `scrollBy()`) on the same scrollable element are combined into a single entry if they occur within 150ms of each other |
+| `"other"` | One entry per scroll interaction, ending after 150ms of inactivity |
+
+#### Scroll End Detection
+
+A scroll interaction is considered **active** while the user is continuously interacting with a scroll gesture. What constitutes "active interaction" depends on the input type (see table above):
+- **Touch**: Finger is touching and moving on the screen
+- **Wheel**: Mouse wheel events are being received
+- **Keyboard**: Scroll key is held down
+- **Other**: Scrollbar is being dragged, or other input method is engaged
+
+A scroll interaction is considered **complete** when:
+1. The user is no longer actively interacting AND no scroll position changes have occurred for at least **150 milliseconds** (approximately 9 frames at 60Hz), OR
+2. A scroll end event is explicitly signaled (e.g., `touchend` for touch scrolling, `scrollend` event)
+
+This timeout allows momentum/inertia scrolling to be included in the same entry as the initiating gesture.
+
+**150ms timeout mechanics:**
+
+The 150ms inactivity timer starts from the **last scroll position change**, not from the initial input event. This timer determines when to emit the entry, but the **`duration` always ends at the last position change**, not 150ms later. The 150ms is purely a detection mechanism - it's the waiting period to confirm scrolling has stopped, but doesn't represent actual scroll activity.
+
+**Example - Wheel scrolling:**
+- Wheel event at `0ms` - this event timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs shortly after (e.g., `8ms` = `firstFrameTime`, may be later if jank)
+- Scroll position continues changing until `80ms` (last position change)
+- Inactivity timer starts at `80ms`
+- If another wheel event arrives before `230ms` (`80ms + 150ms`):
+  - Events are combined into one entry
+  - Timer resets based on when position changes from the new event stop
+- If no event arrives by `230ms`: Entry emits with `duration = 80ms` (time to last position change, not including the 150ms wait)
+
+**Example - Keyboard scrolling:**
+- Key press at `0ms` - this event timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs shortly after (e.g., `10ms` = `firstFrameTime`, may be later if jank)
+- Key held until `100ms`, position changes until `120ms`
+- Key released at `100ms`
+- Inactivity timer starts at `120ms` (last position change)
+- If another key press before `270ms` (`120ms + 150ms`): Combined into same entry
+- Otherwise entry emits with `duration = 120ms` (time to last position change)
+
+**Example - Scrollbar dragging:**
+- User starts dragging scrollbar thumb at `0ms` - this event timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs shortly after (e.g., `8ms` = `firstFrameTime`, may be later if jank)
+- Continues dragging until `200ms`, scroll position changes continuously
+- User releases thumb at `200ms` (last position change)
+- Inactivity timer starts at `200ms`
+- Entry emits at `350ms` with `duration = 200ms` (time to last position change)
+
+**Example - Autoscroll (middle-click):**
+- User middle-clicks to enter autoscroll mode (no entry yet)
+- User moves cursor away from anchor point - cursor movement event timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs shortly after (e.g., `10ms` = `firstFrameTime`, may be later if jank)
+- Autoscroll continues based on cursor position, position changes continuously
+- User clicks again to stop autoscroll at `500ms` (last position change)
+- Inactivity timer starts at `500ms`
+- Entry emits at `650ms` with `duration = 500ms` (time to last position change)
+- Note: If user middle-clicks but never moves cursor away (no cursor movement event), no entry is emitted
+
+**Example - Touch scrolling (with pause mid-gesture):**
+- User touches screen (`touchstart`) - no entry yet
+- User begins dragging finger at `0ms` - this touch gesture timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs at `16ms` (`firstFrameTime` - may be later if jank)
+- User continues dragging until `200ms`, then pauses (finger still on screen, but not moving)
+- Inactivity timer starts at `200ms` (last position change during the pause)
+- If user resumes dragging before `350ms` (`200ms + 150ms`): continues as same entry, timer resets
+- If no movement by `350ms`: entry emits with `duration = 200ms` (time to last position change), even though finger is still on screen
+- Note: `startTime` is the touch gesture event timestamp, not when viewport visually moves (this allows measuring scroll start latency)
+
+**Example - Touch scrolling (lift with momentum):**
+- User touches screen and begins dragging - touch gesture timestamp at `0ms` becomes `startTime`
+- First visual scroll position change occurs shortly after (e.g., `16ms` = `firstFrameTime`)
+- User continues dragging until lifting finger at `300ms` (`touchend`)
+- **If no momentum:** Entry emits immediately with `duration = 300ms` (or whenever last position change occurred)
+- **If momentum occurs:** Momentum scrolling continues until naturally stopping at `800ms` (last position change), entry emits with `duration = 800ms` (no 150ms timer needed - `touchend` or momentum stopping signals the end)
+- Note: If user touches screen but never moves finger (no scroll gesture occurs), no entry is emitted
+
+**Example - Programmatic scrolling (gamepad joystick mapped to scrollBy):**
+- User tilts gamepad joystick down, triggering `scrollBy(0, 50)` at `0ms` - this API call timestamp becomes `startTime` (`0ms`)
+- First visual scroll position change occurs shortly after (e.g., `10ms` = `firstFrameTime`, may be later if jank)
+- Joystick remains tilted, triggering additional `scrollBy(0, 50)` calls every 100ms at `100ms`, `200ms`, `300ms`
+- Each call causes position changes, last position change at `350ms`
+- User releases joystick at `300ms`
+- Inactivity timer starts at `350ms` (last position change)
+- If another `scrollBy()` call on the same element before `500ms` (`350ms + 150ms`): Combined into same entry
+- Otherwise entry emits at `500ms` with `duration = 350ms` (time to last position change)
+- Note: Consecutive programmatic scrolls are only grouped if they target the same scrollable element
+
+#### Direction Change Segmentation
+
+A new scroll timing entry MUST be emitted when the scroll direction reverses (i.e., `deltaX` or `deltaY` changes sign during the scroll). This means a single scroll gesture can produce multiple entries if the user reverses direction mid-scroll.
+
+**Rationale**: Direction reversals represent distinct scroll interactions from a performance measurement perspective, as they may trigger different rendering paths and affect smoothness calculations.
+
 ### Example Usage with PerformanceObserver
 
 ```javascript
@@ -281,4 +411,4 @@ See [polyfill.js](polyfill.js) for the full implementation.
 **Note:** This polyfill uses heuristics-based approximations due to the lack of relevant native APIs required for accurate scroll performance measurement. It is intended for demonstration and prototyping purposes only. Metrics like checkerboarding detection and precise frame timing cannot be accurately measured without browser-level instrumentation. A native implementation would have access to compositor data, rendering pipeline information, and other internal metrics not exposed to JavaScript.
 
 ### Acknowledgements
-Many thanks for valuable feedback and advice from: Alex Russel, Mike Jackson, Olga Gerchikov, Andy Luhr, Pninit Goldman, Roee Barnea for guidance and contributions.
+Many thanks for valuable feedback and advice from: Alex Russel, Mike Jackson, Olga Gerchikov, Andy Luhr, Hoch Hochkeppel, Pninit Goldman, Roee Barnea for guidance and contributions.