@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/dist/gestures/nativeScroll.js

@@ -30,28 +30,9 @@
 
 import { isRtlElement } from "../hooks/isRtlElement.js";
 import { parentAcrossShadow } from "../utils/flatTree.js";
+import { isInsideScrollView, parseTouchAction, rootOverflow, SCROLLABLE_OVERFLOW as SCROLLABLE } from "../utils/scrollView.js";
 export { parentAcrossShadow };
-/** Which pans a `touch-action` value lets the browser perform. */
-export function parseTouchAction(value) {
-  const tokens = value.trim().split(/\s+/);
-  if (tokens.includes('auto') || tokens.includes('manipulation')) {
-    return {
-      x: true,
-      y: true
-    };
-  }
-  if (tokens.includes('none')) {
-    return {
-      x: false,
-      y: false
-    };
-  }
-  return {
-    x: tokens.some(token => token === 'pan-x' || token === 'pan-left' || token === 'pan-right'),
-    y: tokens.some(token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down')
-  };
-}
-const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);
+export { parseTouchAction };
 const EDGE_TOLERANCE = 1;
 function buildChain(target, readsTouchAction) {
   const doc = target.ownerDocument;
@@ -67,7 +48,6 @@ function buildChain(target, readsTouchAction) {
   let allowX = true;
   let allowY = true;
   let reachedRoot = false;
-  let isBeyondFixed = false;
   for (let node = target; node != null; node = parentAcrossShadow(node)) {
     if (!(node instanceof Element)) {
       continue;
@@ -96,16 +76,12 @@ function buildChain(target, readsTouchAction) {
         // The writing direction through core's one helper.
         isRtl: isRtlElement(element),
         stopsX: behaviorX !== 'auto',
-        stopsY: behaviorY !== 'auto',
-        isBeyondFixed
+        stopsY: behaviorY !== 'auto'
       });
     }
     if (isRoot) {
       break;
     }
-    if (style.position === 'fixed') {
-      isBeyondFixed = true;
-    }
   }
   if (!reachedRoot && root instanceof Element) {
     chain.push({
@@ -114,8 +90,7 @@ function buildChain(target, readsTouchAction) {
       y: allowY && SCROLLABLE.has(rootOverflow(doc, 'y')),
       isRtl: false,
       stopsX: false,
-      stopsY: false,
-      isBeyondFixed
+      stopsY: false
     });
   }
   return {
@@ -134,28 +109,6 @@ function overscrollBehavior(style) {
   const [first = 'auto', second = first] = (style.getPropertyValue('overscroll-behavior') || 'auto').trim().split(/\s+/);
   return [x || first, y || second];
 }
-
-/**
- * The viewport scrolls unless the root or the body clips it (a scroll lock
- * sets `overflow: hidden` on one of them).
- */
-function rootOverflow(doc, axis) {
-  const view = doc.defaultView;
-  if (view == null) {
-    return 'hidden';
-  }
-  for (const element of [doc.documentElement, doc.body]) {
-    if (element == null) {
-      continue;
-    }
-    const style = view.getComputedStyle(element);
-    const value = axis === 'x' ? style.overflowX : style.overflowY;
-    if (value === 'hidden' || value === 'clip') {
-      return 'hidden';
-    }
-  }
-  return 'auto';
-}
 function canMoveY(element, dy) {
   if (element.scrollHeight - element.clientHeight <= EDGE_TOLERANCE) {
     return false;
@@ -241,7 +194,9 @@ export function createNativeScrollProbe(target, {
       return chain?.allowsPan === true;
     },
     get isInsideScroller() {
-      return getChain().some(entry => !entry.isBeyondFixed && (entry.y && entry.element.scrollHeight - entry.element.clientHeight > EDGE_TOLERANCE || entry.x && entry.element.scrollWidth - entry.element.clientWidth > EDGE_TOLERANCE));
+      return target instanceof Element && isInsideScrollView(target, {
+        readsTouchAction
+      });
     }
   };
 }

package/dist/gestures/wheelSegmenter.d.ts

@@ -3,6 +3,7 @@
  * @input A wheel stream's deltas along one axis, with their event times
  * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
  *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   It keeps a trackpad's late or merged glide wheels in their flick.
  *   isBunched tells one stall's merge from a frame.
  * @position Read by GestureHost.ts's wheel input: the web reports no
  *   trackpad contact or phase, so both are inferred.
@@ -21,6 +22,12 @@ export interface WheelSegment {
     readonly decaying: boolean;
     /** This event came so soon after the one before that it is a merge. */
     readonly bunched: boolean;
+    /**
+     * The signed travel of the late wheel before this one, with any wheel
+     * merged with it. It is handed over when that wheel joined the glide and
+     * this one grows into a new gesture; else 0.
+     */
+    readonly carried: number;
 }
 /**
  * Whether a wheel `intervalMs` after the one before is one stall's merge, not
@@ -39,6 +46,16 @@ export declare function isBunched(intervalMs: number): boolean;
  * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
  * a jump. The decay reads it by its last step. Momentum never pauses,
  * reverses or grows.
+ *
+ * A stalled page receives a trackpad's glide late, and the engine merges the
+ * wheels it held. In momentum, a trackpad wheel that the glide's decay
+ * explains stays in the flick. It may come after a pause, or rise after more
+ * than a frame. It is at or below the next step, or near the sum of the next
+ * steps its stall spans. After such a wheel, a trackpad wheel that grows
+ * starts a new gesture and takes the late wheel's travel. The decay also
+ * reads a trackpad merge in momentum, by its last step. It reads one in a
+ * shrinking run too, where it explains the merge better than steady steps
+ * do. Other wheels keep the rules above.
  */
 export declare class WheelSegmenter {
     gesture: number;
@@ -49,7 +66,57 @@ export declare class WheelSegmenter {
     private count;
     private run;
     private runStart;
-    push(time: number, delta: number, idleMs: number): WheelSegment;
+    /** The decay's step-to-step ratio, from the last two one-step wheels. */
+    private ratio;
+    /** The gesture's last on-pace intervals, ms: their median is its frame. */
+    private paces;
+    /** The intervals in a row that came slower than the frame allows, ms. */
+    private slower;
+    /** When the gesture's last wheel within two frames of the one before came. */
+    private onPace;
+    /** The gesture's last wheel that was not bunched, px. */
+    private paced;
+    /** A wheel joined the glide late: a later one that grows is the fingers'. */
+    private resumed;
+    /**
+     * The signed travel of the last wheel that joined the glide late, with any
+     * wheel merged with it.
+     */
+    private joined;
+    /**
+     * Reads one wheel. `continuous` is whether it carries a trackpad's
+     * signature (`scrollTypeOf`). Only those wheels can join a glide late.
+     */
+    push(time: number, delta: number, idleMs: number, continuous?: boolean): WheelSegment;
+    /**
+     * Keep an interval for the frame. The gesture's first FIRST_PACES set it.
+     * After them, only an interval within half a frame and one and a half
+     * frames counts: a stall's squeezed wheels come faster. FIRST_PACES slower
+     * intervals in a row set the frame again, so a squeezed start cannot hold
+     * it down.
+     */
+    private notePace;
+    /**
+     * The gesture's frame interval: the median of its last on-pace intervals,
+     * or FRAME_MS before it shows one. A trackpad reports at 60 Hz or faster,
+     * so a longer median is a stall's.
+     */
+    private frameMs;
+    /** The sum of the decay's next `count` steps from `previous`. */
+    private glideSum;
+    /**
+     * How far a merge of `size` lies from whole steps of the run's steady
+     * size, or of its last step, whichever lies nearer.
+     */
+    private steadyOff;
+    /**
+     * How many of the decay's next steps a trackpad wheel of `size` carries,
+     * at most `most`. A wheel at or below the next step carries one. A larger
+     * one carries the fewest steps whose sum lies within FIT_PX or `share` of
+     * it. The decay goes on from `previous` at `ratio` a step. Null when
+     * no sum lies that near.
+     */
+    private glideSteps;
     /** The gesture ended on its own (its timer): the next event starts one. */
     end(): void;
 }

package/dist/gestures/wheelSegmenter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wheelSegmenter.d.ts","sourceRoot":"","sources":["../../src/gestures/wheelSegmenter.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAC3E,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAcD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,SAAK;IACZ,KAAK,EAAE,UAAU,CAAY;IAC7B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAK;IAErB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY;IAkE/D,2EAA2E;IAC3E,GAAG,IAAI,IAAI;CAGZ"}
+{"version":3,"file":"wheelSegmenter.d.ts","sourceRoot":"","sources":["../../src/gestures/wheelSegmenter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAC3E,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiCD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAc;IACzB,OAAO,SAAK;IACZ,KAAK,EAAE,UAAU,CAAY;IAC7B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAK;IACrB,yEAAyE;IACzE,OAAO,CAAC,KAAK,CAAK;IAClB,2EAA2E;IAC3E,OAAO,CAAC,KAAK,CAAgB;IAC7B,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAgB;IAC9B,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAa;IAC3B,yDAAyD;IACzD,OAAO,CAAC,KAAK,CAAK;IAClB,6EAA6E;IAC7E,OAAO,CAAC,OAAO,CAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAK;IAEnB;;;OAGG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,UAAQ,GACjB,YAAY;IA+If;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAchB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAaf,iEAAiE;IACjE,OAAO,CAAC,QAAQ;IAUhB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAUjB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAuBlB,2EAA2E;IAC3E,GAAG,IAAI,IAAI;CAGZ"}

package/dist/gestures/wheelSegmenter.js

@@ -5,6 +5,7 @@
  * @input A wheel stream's deltas along one axis, with their event times
  * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
  *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   It keeps a trackpad's late or merged glide wheels in their flick.
  *   isBunched tells one stall's merge from a frame.
  * @position Read by GestureHost.ts's wheel input: the web reports no
  *   trackpad contact or phase, so both are inferred.
@@ -21,6 +22,25 @@ const BUNCHED_MS = 1.5;
 const LIFT_RUN = 4;
 /** And how much of its size the run has lost by then. */
 const LIFT_DECAY = 0.8;
+/** How near a wheel must lie to a sum of the glide's next steps, px. */
+const FIT_PX = 1;
+/** Or as a share of that sum, when the share is larger. */
+const FIT_SHARE = 0.25;
+/** The most glide steps one wheel is read as carrying. */
+const MAX_STEPS = 64;
+/** How near a late or rising wheel must lie to the glide's sum, as a share. */
+const LATE_FIT_SHARE = 0.15;
+/**
+ * How far a wheel may grow past the last unbunched one and still be the
+ * glide, px.
+ */
+const RISE_PX = 0.5;
+/** A stream's frame interval until it shows its own, ms. */
+const FRAME_MS = 16;
+/** The longest frame interval a trackpad reports at: 60 Hz, ms. */
+const SLOWEST_FRAME_MS = 1000 / 60;
+/** The intervals that set a gesture's frame before its window applies. */
+const FIRST_PACES = 3;
 
 /**
  * Whether a wheel `intervalMs` after the one before is one stall's merge, not
@@ -42,6 +62,16 @@ export function isBunched(intervalMs) {
  * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
  * a jump. The decay reads it by its last step. Momentum never pauses,
  * reverses or grows.
+ *
+ * A stalled page receives a trackpad's glide late, and the engine merges the
+ * wheels it held. In momentum, a trackpad wheel that the glide's decay
+ * explains stays in the flick. It may come after a pause, or rise after more
+ * than a frame. It is at or below the next step, or near the sum of the next
+ * steps its stall spans. After such a wheel, a trackpad wheel that grows
+ * starts a new gesture and takes the late wheel's travel. The decay also
+ * reads a trackpad merge in momentum, by its last step. It reads one in a
+ * shrinking run too, where it explains the merge better than steady steps
+ * do. Other wheels keep the rules above.
  */
 export class WheelSegmenter {
   gesture = 0;
@@ -52,40 +82,108 @@ export class WheelSegmenter {
   count = 0;
   run = 0;
   runStart = 0;
-  push(time, delta, idleMs) {
+  /** The decay's step-to-step ratio, from the last two one-step wheels. */
+  ratio = 1;
+  /** The gesture's last on-pace intervals, ms: their median is its frame. */
+  paces = [];
+  /** The intervals in a row that came slower than the frame allows, ms. */
+  slower = [];
+  /** When the gesture's last wheel within two frames of the one before came. */
+  onPace = -Infinity;
+  /** The gesture's last wheel that was not bunched, px. */
+  paced = 0;
+  /** A wheel joined the glide late: a later one that grows is the fingers'. */
+  resumed = false;
+  /**
+   * The signed travel of the last wheel that joined the glide late, with any
+   * wheel merged with it.
+   */
+  joined = 0;
+
+  /**
+   * Reads one wheel. `continuous` is whether it carries a trackpad's
+   * signature (`scrollTypeOf`). Only those wheels can join a glide late.
+   */
+  push(time, delta, idleMs, continuous = false) {
     const size = Math.abs(delta);
     const sign = Math.sign(delta);
     const gap = time - this.last;
     const bunched = this.count > 0 && isBunched(gap);
+    const frame = this.frameMs();
     let boundary = null;
+    let carriedSteps = null;
     if (this.count === 0) {
       boundary = this.gesture === 0 ? 'first' : 'idle';
     } else if (this.phase === 'finger' && gap >= idleMs) {
       boundary = 'idle';
     } else if (this.phase === 'momentum') {
+      // A late wheel carries the steps of its whole stall, which began at the
+      // last wheel that came on pace.
+      const frames = Math.round((time - this.onPace) / frame);
+      const late = gap >= MOMENTUM_GAP_MS;
+      const rises = !bunched && size >= 2 && size > this.previous * 1.3 + 0.5;
       if (sign !== 0 && this.sign !== 0 && sign !== this.sign) {
         boundary = 'reversal';
-      } else if (gap >= MOMENTUM_GAP_MS) {
-        boundary = 'gap';
-      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
+      } else if (late || rises) {
+        // A wheel that rises on pace is the fingers'. One that rises after a
+        // skipped frame may carry the frames its stall held.
+        if (continuous && sign === this.sign && (late || gap >= 1.5 * frame)) {
+          carriedSteps = this.glideSteps(size, Math.max(1, frames), LATE_FIT_SHARE);
+        }
+        if (carriedSteps == null) {
+          boundary = late ? 'gap' : 'jump';
+        }
+      } else if (continuous && this.resumed && !bunched && size > FIT_PX && size > this.paced + RISE_PX) {
+        // A glide only falls, so after a late wheel one that grows is the
+        // fingers'. A whole-pixel glide repeats a step as it slows.
         boundary = 'jump';
       }
     }
+    if (carriedSteps == null && boundary == null && bunched && continuous) {
+      if (this.phase === 'momentum') {
+        carriedSteps = this.glideSteps(size, MAX_STEPS);
+      } else if (this.run > 0) {
+        // In a shrinking run, the decay reads a merge only where it explains
+        // the merge better than steady steps do.
+        const decay = this.glideSteps(size, MAX_STEPS);
+        if (decay != null && decay > 1 && Math.abs(size - this.glideSum(decay)) < this.steadyOff(size)) {
+          carriedSteps = decay;
+        }
+      }
+    }
     // A bunched wheel carries the steps of the frames it merged. The decay
     // goes on from its last step, so the steps after it read as they are.
-    const steps = boundary == null && bunched && this.previous > 0 ? Math.max(1, Math.round(size / this.previous)) : 1;
+    const steps = carriedSteps ?? (boundary == null && bunched && this.previous > 0 ? Math.max(1, Math.round(size / this.previous)) : 1);
+    // On the decay, a wheel of several steps ends at the decay's own step.
+    const onDecay = carriedSteps != null && carriedSteps > 1;
+    // A bunched wheel is read by its last step, as the decay goes on from it.
+    const step = onDecay ? this.previous * this.ratio ** steps : size / steps;
     if (boundary != null) {
       this.gesture += 1;
       this.phase = 'finger';
       this.count = 0;
       this.run = 0;
+      this.ratio = 1;
+      this.resumed = false;
+      this.paces = [];
+      this.slower = [];
+    }
+    // The late wheel was the fingers' when the next one grows: the new
+    // gesture takes its travel.
+    const carried = boundary === 'jump' ? this.joined : 0;
+    const joinedLate = boundary == null && carriedSteps != null && !bunched;
+    if (joinedLate) {
+      this.resumed = true;
+    }
+    // A wheel merged with the late one is the same dispatch: it adds to it.
+    this.joined = joinedLate ? delta : bunched && boundary == null && this.joined !== 0 ? this.joined + delta : 0;
+    if (!bunched) {
+      this.paced = size;
     }
     let liftNow = false;
     let decaying = false;
     if (this.phase === 'finger' && this.count >= 3 && size > 0) {
-      // A bunched wheel is read by its last step, as the decay goes on from it.
-      const step = size / steps;
-      decaying = step <= this.previous * 0.995 && step >= this.previous * 0.5;
+      decaying = onDecay ? this.ratio <= 0.995 : step <= this.previous * 0.995 && step >= this.previous * 0.5;
       if (decaying) {
         if (this.run === 0) {
           this.runStart = this.previous;
@@ -99,8 +197,17 @@ export class WheelSegmenter {
         liftNow = true;
       }
     }
+    if (steps === 1 && this.count > 0 && this.previous > 0 && step > 0) {
+      this.ratio = Math.min(1, Math.max(0.5, step / this.previous));
+    }
+    if (!bunched && boundary == null && gap < MOMENTUM_GAP_MS) {
+      this.notePace(gap, frame);
+    }
+    if (boundary != null || !bunched && gap < 2 * frame) {
+      this.onPace = time;
+    }
     this.count += 1;
-    this.previous = size / steps;
+    this.previous = step;
     if (sign !== 0) {
       this.sign = sign;
     }
@@ -111,10 +218,92 @@ export class WheelSegmenter {
       gesture: this.gesture,
       liftNow,
       decaying: decaying && !liftNow,
-      bunched: boundary == null && bunched
+      bunched: boundary == null && bunched,
+      carried
     };
   }
 
+  /**
+   * Keep an interval for the frame. The gesture's first FIRST_PACES set it.
+   * After them, only an interval within half a frame and one and a half
+   * frames counts: a stall's squeezed wheels come faster. FIRST_PACES slower
+   * intervals in a row set the frame again, so a squeezed start cannot hold
+   * it down.
+   */
+  notePace(gap, frame) {
+    const inWindow = gap >= 0.5 * frame && gap <= 1.5 * frame;
+    if (this.paces.length < FIRST_PACES || inWindow) {
+      this.paces = [...this.paces.slice(-7), gap];
+      this.slower = [];
+      return;
+    }
+    this.slower = gap > 1.5 * frame ? [...this.slower, gap] : [];
+    if (this.slower.length >= FIRST_PACES) {
+      this.paces = this.slower;
+      this.slower = [];
+    }
+  }
+
+  /**
+   * The gesture's frame interval: the median of its last on-pace intervals,
+   * or FRAME_MS before it shows one. A trackpad reports at 60 Hz or faster,
+   * so a longer median is a stall's.
+   */
+  frameMs() {
+    if (this.paces.length === 0) {
+      return FRAME_MS;
+    }
+    const sorted = [...this.paces].sort((a, b) => a - b);
+    const middle = sorted.length >> 1;
+    const median = sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+    return Math.min(median, SLOWEST_FRAME_MS);
+  }
+
+  /** The sum of the decay's next `count` steps from `previous`. */
+  glideSum(count) {
+    let next = this.previous * this.ratio;
+    let sum = 0;
+    for (let i = 0; i < count; i++) {
+      sum += next;
+      next *= this.ratio;
+    }
+    return sum;
+  }
+
+  /**
+   * How far a merge of `size` lies from whole steps of the run's steady
+   * size, or of its last step, whichever lies nearer.
+   */
+  steadyOff(size) {
+    return Math.min(...[this.runStart, this.previous].filter(step => step > 0).map(step => Math.abs(size - Math.max(1, Math.round(size / step)) * step)));
+  }
+
+  /**
+   * How many of the decay's next steps a trackpad wheel of `size` carries,
+   * at most `most`. A wheel at or below the next step carries one. A larger
+   * one carries the fewest steps whose sum lies within FIT_PX or `share` of
+   * it. The decay goes on from `previous` at `ratio` a step. Null when
+   * no sum lies that near.
+   */
+  glideSteps(size, most, share = FIT_SHARE) {
+    if (this.previous <= 0 || size <= 0) {
+      return null;
+    }
+    let next = this.previous * this.ratio;
+    if (size <= next + FIT_PX) {
+      return 1;
+    }
+    let sum = next;
+    for (let count = 2; count <= Math.min(most, MAX_STEPS); count++) {
+      next *= this.ratio;
+      sum += next;
+      if (Math.abs(size - sum) <= Math.max(FIT_PX, sum * share)) {
+        return count;
+      }
+    }
+    return null;
+  }
+
   /** The gesture ended on its own (its timer): the next event starts one. */
   end() {
     this.count = 0;

package/dist/hooks/StackItemScrollRegion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { type AriaRole, type ReactNode, type Ref } from 'react';
+export interface StackItemScrollRegionProps {
+    as: 'div' | 'span';
+    ref?: Ref<HTMLElement>;
+    elementProps: {
+        role?: AriaRole;
+        'aria-label'?: string;
+        [prop: string]: unknown;
+    };
+    children?: ReactNode;
+}
+export declare function StackItemScrollRegion({ as: element, ref, elementProps, children, }: StackItemScrollRegionProps): import("react").DetailedReactHTMLElement<{
+    ref: import("react").RefCallback<HTMLElement>;
+    role: AriaRole | undefined;
+    'aria-label': string | undefined;
+}, HTMLElement>;
+//# sourceMappingURL=StackItemScrollRegion.d.ts.map

package/dist/hooks/StackItemScrollRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StackItemScrollRegion.d.ts","sourceRoot":"","sources":["../../src/hooks/StackItemScrollRegion.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAI7E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,KAAK,GAAG,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IACvB,YAAY,EAAE;QACZ,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,qBAAqB,CAAC,EACpC,EAAE,EAAE,OAAO,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,GACT,EAAE,0BAA0B;;;;gBAiB5B"}

package/dist/hooks/StackItemScrollRegion.js

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { createElement } from 'react';
+import { useMergedRefs } from "./useMergedRefs.js";
+import { useScrollRegionProps } from "./useScrollRegionProps.js";
+export function StackItemScrollRegion({
+  as: element,
+  ref,
+  elementProps,
+  children
+}) {
+  const region = useScrollRegionProps({
+    isScrollable: true,
+    role: elementProps.role,
+    label: elementProps['aria-label']
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
+  return /*#__PURE__*/createElement(element, {
+    ...elementProps,
+    ref: mergedRef,
+    role: region.role,
+    'aria-label': region['aria-label']
+  }, children);
+}