sticky-scroll-trigger 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,6 +13,10 @@ The only dependency is GSAP's ScrollTrigger types.
13
13
 
14
14
  See the repository's `demo/index.html` + `demo/src/main.ts` for a live example, and `ARCHITECTURE.md` for why nested sticky was chosen over `pin`, and how it works internally.
15
15
 
16
+ ## Demo
17
+
18
+ The [CodePen demo](https://codepen.io/editor/kuninori-ogino/pen/01a083a9-37ab-79e1-a955-cc97d7957f45) shows each effect running.
19
+
16
20
  ## Requirements
17
21
 
18
22
  | requirement | description |
@@ -36,7 +40,7 @@ npm install gsap sticky-scroll-trigger
36
40
  For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
37
41
 
38
42
  ```html
39
- <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger/dist/StickyScrollTrigger.global.min.js"></script>
43
+ <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.10.0/dist/StickyScrollTrigger.global.min.js"></script>
40
44
  ```
41
45
 
42
46
  Consumers should only rely on the exports of `sticky-scroll-trigger` (or `window.StickyScrollTrigger` for the global build). The internal modules under `src/` are not part of the public API.
@@ -159,14 +163,16 @@ Registers a layer that pins a scene and advances its effect, and returns `Scroll
159
163
  | `pin` / `pinSpacing` / `anticipatePin` / `pinnedContainer` / `pinReparent` / `pinSpacer` / `pinType` | Pinning is handled by `position:sticky`, not GSAP pinning, so these have no effect |
160
164
  | `horizontal` / `scroller` / `containerAnimation` | This module assumes vertical, window-based scrolling; setting these shifts positions |
161
165
 
166
+ Nested Scene layers are accounted for automatically, so `pinnedContainer` isn't needed (see [End syntax](#end-syntax)).
167
+
162
168
  You can specify `onKill`, `invalidateOnRefresh`, and `onRefreshInit`; the module also uses them internally. `invalidateOnRefresh` defaults to `true` (GSAP defaults to `false`) so function-valued tween props are re-measured on refresh, and an explicit value is respected. Freeze-window tracking is independent of the flag, so `invalidateOnRefresh: false` won't break it.
163
169
 
164
- | option | default | description |
165
- | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
166
- | `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise |
167
- | `start` | `'top top'` | Where the scene lands in the viewport while pinned (same idea as sticky's CSS `top`). Same default GSAP itself uses for a pinned trigger. See [position syntax](#position-syntax) |
168
- | `end` | `'bottom top'` | End of the freeze window. Auto-detects between a dwell distance and a position clause (see [end syntax](#end-syntax)). Same default GSAP uses too: dwell for the trigger's own height, not a fixed distance |
169
- | `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax. Must be inside the shared container (see below) |
170
+ | option | default | description |
171
+ | ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
+ | `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise |
173
+ | `start` | `'top top'` | Where the scene lands in the viewport while pinned (same idea as sticky's CSS `top`). Same default GSAP itself uses for a pinned trigger. See [position syntax](#position-syntax) |
174
+ | `end` | `'bottom top'` | End of the freeze window. Auto-detects between a dwell distance and a position clause (see [end syntax](#end-syntax)). Same default GSAP uses too: dwell for the trigger's own height plus the dwell of the scenes nested inside it, not a fixed distance |
175
+ | `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax. Must be inside the shared container (see below) |
170
176
 
171
177
  ### `createOverlapScroll(options)`
172
178
 
@@ -182,6 +188,8 @@ Registers an overlap-scroll effect (`trigger` gets pinned while its siblings fro
182
188
 
183
189
  `start` and `end` are the two defaults this module doesn't take from GSAP, which pins at `'top top'` and ends at `'bottom top'`. The rise needs `cover` to begin off screen: pinned at the viewport's top, a `trigger` shorter than the viewport leaves the covering side already showing underneath it. `'bottom bottom'` rests `trigger` against the viewport's bottom edge instead, and the auto `end` measures the rise from there.
184
190
 
191
+ A `trigger` shorter than the viewport that also sits within a viewport height of the document top makes that default resolve to a negative freeze-window start, so part of the rise plays before scroll 0. The freeze window is not clamped here; see [Position syntax](#position-syntax) for why and how to avoid it.
192
+
185
193
  `createOverlapScroll` adjusts `position`/`z-index` on the covering side only when needed, never overrides explicit values, and restores its changes on GSAP `kill()`. The restore clears a property only while it still holds the value the lift wrote, so a different value you set on the covering side afterwards (a `gsap.set()`, say) survives.
186
194
 
187
195
  Every [`refresh()`](#refresh) runs that check again over the covering side as it stands: it raises an element added since, and hands back a property your own CSS has turned on in the meantime. Where the covering side holds a `createStickyPin` `trigger`, the pin's own wrapper rises in its place and the pinned element is left alone.
@@ -191,10 +199,10 @@ Every [`refresh()`](#refresh) runs that check again over the covering side as it
191
199
  Pinning here is plain `position:sticky`, and the browser keeps a sticky element stuck only until its containing block's bottom edge catches up with it. That containing block is `trigger`'s own parent, not the shared container:
192
200
 
193
201
  ```
194
- trigger's parent's bottom edge - trigger's bottom edge >= end - start
202
+ trigger's parent's bottom edge - trigger's bottom edge >= end - start - dwell
195
203
  ```
196
204
 
197
- With the auto `end`, that distance is where `cover`'s top edge sits when the freeze starts: `start`'s pinned offset, plus `trigger`'s own height, plus any gap between the two. Under the defaults (`start: 'bottom bottom'`, `cover` directly after `trigger`) it comes to one viewport height; a `trigger` taller than the viewport, pinned near the top, needs more.
205
+ `dwell` is that of any Scene layer freezing mid-rise: it holds the whole container, `cover` and the parent included, so it uses no room. With the auto `end`, `end - start - dwell` is where `cover`'s top edge sits when the freeze starts: `start`'s pinned offset, plus `trigger`'s own height, plus any gap between the two. Under the defaults (`start: 'bottom bottom'`, `cover` directly after `trigger`) it comes to one viewport height; a `trigger` taller than the viewport, pinned near the top, needs more.
198
206
 
199
207
  With less room than that, the browser releases the wrapper mid-rise: `trigger` scrolls away before `cover` has covered it, at a point that moves with the window size, since the requirement scales with the viewport while the room doesn't. Content after `trigger`'s parent never counts, however long the page is. Add the missing height below `trigger` (a taller `cover`, or a spacer after it), or keep the sections that follow inside the same parent rather than wrapping `trigger` and `cover` in a box of their own.
200
208
 
@@ -234,7 +242,7 @@ ScrollTrigger.create(
234
242
  );
235
243
  ```
236
244
 
237
- The rise picks up where the scrub ends, with no arithmetic on your side, because `refresh()` adds a Scene layer's dwell to the freeze window of every layer whose trigger comes later in DOM order. That is also why the marker goes after the scene rather than inside it.
245
+ The rise picks up where the scrub ends, with no arithmetic on your side, because `refresh()` adds a Scene layer's dwell to a cover layer's freeze window whenever the scene freezes first, including one that freezes just as the rise would begin.
238
246
 
239
247
  The marker sits on the scene's bottom edge, so one `'bottom bottom'` describes both layers and nothing moves at the handover. The scene pins with that edge on the viewport's bottom, and `cover`, which begins there, stays just off screen for the whole hold. Pin the scene anywhere else and you have to reconcile the two clauses by hand, since a zero-height marker resolves any clause to a plain viewport position. Its `start` has to name wherever the scene's bottom edge sits while pinned, or `trigger` jumps.
240
248
 
@@ -284,7 +292,7 @@ Clauses resolve exactly as they do elsewhere, including the one-token forms that
284
292
 
285
293
  Internally, the element wrapping `trigger` renders beyond its own section's bounds, into the visual area of following elements. Make sure the ancestor section containing `trigger` isn't hidden behind a later section in DOM order (e.g. via `position: relative; z-index: ...`).
286
294
 
287
- See the repository's `ARCHITECTURE.md` ("Why `createStickyPin` is unaffected by nested-sticky lag") for why the lag never applies here, and why `trigger` needs two nested wrapper divs.
295
+ See the repository's `ARCHITECTURE.md` ("How `createStickyPin` accounts for nested-sticky lag") for how a pin's release allows for the dwell of Scene layers between `trigger` and `endTrigger`, and why `trigger` needs two nested wrapper divs.
288
296
 
289
297
  ### `createResolvedTrigger(options)`
290
298
 
@@ -304,12 +312,12 @@ gsap.to(plainBox, {
304
312
  });
305
313
  ```
306
314
 
307
- | option | default | description |
308
- | ------------ | -------------- | ------------------------------------------------------------------------------------------ |
309
- | `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger` |
310
- | `start` | `'top bottom'` | [Position syntax](#position-syntax), resolved relative to `trigger` |
311
- | `end` | `'bottom top'` | [Position syntax](#position-syntax), resolved relative to `endTrigger` |
312
- | `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split) |
315
+ | option | default | description |
316
+ | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
317
+ | `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger` |
318
+ | `start` | `'top bottom'` | [Position syntax](#position-syntax), resolved relative to `trigger` |
319
+ | `end` | `'bottom top'` | [Position syntax](#position-syntax), resolved relative to `endTrigger` |
320
+ | `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split). May sit outside the shared container |
313
321
 
314
322
  Omit `start` and `end` and the range runs from `trigger`'s top edge entering the viewport at the bottom to `endTrigger`'s bottom edge leaving it at the top, GSAP's own defaults for a trigger that doesn't pin.
315
323
 
@@ -319,7 +327,7 @@ If you need different reference elements or custom progress logic, use `resolveS
319
327
 
320
328
  ### `resolveScrollPosition(element, position)`
321
329
 
322
- For any element inside the shared container (registered or not), returns the absolute scroll position (px) for GSAP position syntax (`element` + `position`). As with `trigger`/`endTrigger`/`cover` above, `element` also accepts a CSS selector string in addition to an `HTMLElement`. Use this to keep plain ScrollTriggers inside nested sticky in sync with real scroll distance. If `start` and `end` use the same element, [`createResolvedTrigger`](#createresolvedtriggeroptions) is usually simpler.
330
+ For any element inside the shared container (registered or not), returns the absolute scroll position (px) for GSAP position syntax (`element` + `position`). As with `trigger`/`endTrigger`/`cover` above, `element` also accepts a CSS selector string in addition to an `HTMLElement`. Use this to keep plain ScrollTriggers inside nested sticky in sync with real scroll distance. An element outside the container gets no dwell added, since the scenes don't hold it back. If `start` and `end` use the same element, [`createResolvedTrigger`](#createresolvedtriggeroptions) is usually simpler.
323
331
 
324
332
  ```ts
325
333
  const sticky = new StickyScrollTrigger(".container__inner");
@@ -393,7 +401,7 @@ It only cleans up DOM/styles managed by this module. You still need to kill acti
393
401
 
394
402
  ## Same-page links
395
403
 
396
- Pinning decouples an element's position in the document from the scroll position at which it actually reaches the top of the viewport. The browser's own "scroll an element into view" is a single calculation made from the current layout, so on its own it lands short by every preceding scene's dwell. This is true of any pinning technique, GSAP's own `pin` included.
404
+ Pinning decouples an element's position in the document from the scroll position at which it actually reaches the top of the viewport. The browser's own "scroll an element into view" is a single calculation made from the current layout, so on its own it lands short by the dwell of every scene that freezes before the element gets there. This is true of any pinning technique, GSAP's own `pin` included.
397
405
 
398
406
  `refresh()` declares that difference to the browser by keeping `scroll-margin-top` in sync on every element inside the shared container that matches `scrollMarginTargets` (`'[id]'` by default). Nothing else is needed: plain `<a href="#target">` links, `scrollIntoView()`, `:target` and a `#hash` on load all land correctly as written.
399
407
 
@@ -404,7 +412,7 @@ Pinning decouples an element's position in the document from the scroll position
404
412
 
405
413
  - Your own `scroll-margin-top` still applies. The correction is added to whatever value the element already computes to, never written over it, re-read on every `refresh()` (so a later change, e.g. a responsive breakpoint, is picked up too), and `destroy()` puts the original inline value back
406
414
  - A fixed header's offset is a different case, applying to every scroll rather than only those inside the shared container. CSSOM View says `scroll-padding-top` (on the scroller) and `scroll-margin-top` (on the target) add together, so in principle the header offset could live there, independently of this module's correction. In practice, don't: Firefox drops `scroll-padding-top` from a fragment jump once any `position:sticky` element on the page has engaged, landing short by exactly the header height (see ARCHITECTURE.md's "Firefox drops scroll-padding-top" for how this was verified). Fold it into `--sst-scroll-margin-top-offset` instead (below), as the repository's demo does in `style.css`'s `html` rule
407
- - To land deliberately short of or past a target, set the `--sst-scroll-margin-top-offset` custom property (a length) on it, or on any ancestor to cover several targets at once (it inherits like any other custom property). A positive value lands short, settling below the viewport's top edge instead of flush with it; negative overshoots. Being a plain `var()`, the browser reads it live at scroll-into-view time, so unlike the author-`scroll-margin-top` case above, no `refresh()` call is needed for a change to take effect
415
+ - To land deliberately short of or past a target, set the `--sst-scroll-margin-top-offset` custom property (a length) on it, or on any ancestor to cover several targets at once (it inherits like any other custom property). A positive value lands short, settling below the viewport's top edge instead of flush with it; negative overshoots. Being a plain `var()`, the browser reads it live at scroll-into-view time, so unlike the author-`scroll-margin-top` case above, no `refresh()` call is needed for a change to take effect, including when it changes which scenes' dwell the target waits out
408
416
 
409
417
  ```css
410
418
  /* A fixed header's height, folded in here rather than into scroll-padding-top (see above). */
@@ -425,7 +433,7 @@ Pinning decouples an element's position in the document from the scroll position
425
433
  | token | example | meaning |
426
434
  | ----------- | --------------------------- | ------------------------------------------------------------- |
427
435
  | keyword | `top` / `center` / `bottom` | 0% / 50% / 100% |
428
- | bare number | `80` / `80px` | 80px from the reference point (matches GSAP: only `%` scales) |
436
+ | bare number | `80` / `80px` / `-50` | ± px from the reference point (matches GSAP: only `%` scales) |
429
437
  | percentage | `80%` | 80% of the target's height |
430
438
  | px offset | `center+=50` / `top-=20` | ± px from the reference point |
431
439
  | % offset | `top+=10%` | ± (relative to the target's height) |
@@ -436,17 +444,19 @@ Pinning decouples an element's position in the document from the scroll position
436
444
  start: () => `center center+=${getHeaderHeight() / 2}`,
437
445
  ```
438
446
 
439
- A px/% offset needs the `=` when it follows a keyword or number (`top+=50`, `80-=10%`), because GSAP uses the `=` itself to split the base from the offset. `top+50` isn't recognized syntax: GSAP silently resolves it to 0, treating the whole string as unparseable, while this module throws instead. Without a base, the `=` is optional (`+=500` and `+500` are equivalent), since there's nothing to split it from.
447
+ A px/% offset needs the `=` when it follows a keyword or number (`top+=50`, `80-=10%`), because GSAP uses the `=` itself to split the base from the offset. `top+50` isn't recognized syntax: GSAP silently resolves it to 0, treating the whole string as unparseable, while this module throws instead. Without a base, the `=` is optional (`+=500` and `+500` are equivalent), since there's nothing to split it from. A signed number is a base like any other and can carry an offset of its own: `-50+=100` is 50px from the reference point, because GSAP splits at the `=` and reads everything before it with `parseFloat`.
448
+
449
+ A token carrying `%` on both the base and the offset (`'50%+=10%'`) is one deliberate divergence. GSAP scales the offset only when the token's first `%` sits after the `=`, so a `%` base hides the offset's own and leaves it a plain px value: against a 400px element, GSAP reads `'50%+=10%'` as 210 where this module reads 240. Both units are honored here rather than reproducing that.
440
450
 
441
451
  A trailing `px` (`top 100px`, `center+=50px`) is accepted and ignored, the same idea as GSAP's own `_offsetToPx`, which only special-cases `%` and otherwise passes the value through `parseFloat`. This module isn't as lenient as GSAP toward other unrecognized suffixes, though: an actually-unsupported unit like `top 100vh` still throws, rather than silently behaving like `top 100`.
442
452
 
443
- The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start: 'clamp(top center)'`, which holds the resolved position inside the scroller's own range) is not part of it and throws. Nothing clamps the freeze window either, so a clause that resolves past the top of the document keeps its negative value: a Scene layer sitting at the very start of the container with `start: 'top bottom'` begins one viewport height before scroll 0. `end` is the exception, already clamped to `start`.
453
+ The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start: 'clamp(top center)'`, which holds the resolved position inside the scroller's own range) is not part of it and throws. Nothing clamps the freeze window either, so a clause that resolves past the top of the document keeps its negative value: a Scene layer sitting at the very start of the container with `start: 'top bottom'` begins one viewport height before scroll 0, its wrapper torn that far down the flow and its dwell cut to match, so a scrubbed tween is already part-done at load. [`createOverlapScroll`](#createoverlapscrolloptions)'s `'bottom bottom'` default reaches this with no `start` passed when the covered `trigger` sits within a viewport height of the document top and is shorter than the viewport (`freezeStart` is `triggerTop - (viewportHeight - triggerHeight)`), so part of the rise is already showing at scroll 0. To avoid it, give `trigger` at least a viewport's height, or move it further down the page. There is no opt-out here: `clamp()` is rejected, and a cover layer's sticky offset does not reference the freeze window's start, so clamping the window would not move it. `end` is the exception, already clamped to `start`.
444
454
 
445
455
  GSAP passes the `ScrollTrigger` instance to its own function-valued `start`/`end` (`start: (self) => ...`), and this module doesn't, so a function declaring that parameter is a TypeScript error. There is nothing to pass: this module's `refresh()` resolves these functions, and it runs whether or not the returned `ScrollTrigger.Vars` was ever handed to `ScrollTrigger.create()`. `self.start`/`self.end` would be circular anyway, since the freeze window they report is what `refresh()` is in the middle of computing.
446
456
 
447
457
  ### Absolute scroll position
448
458
 
449
- If the entire value is just a number (a plain JS number, or a string that's nothing but digits, with no keyword, second token, or `%`/`px` suffix), GSAP treats it as an absolute scroll position rather than a clause, and ignores the reference element entirely (`ScrollTrigger.js`'s `_parsePosition`: `isNaN(value) || (value = +value)`). This module follows the same rule for `start` and `end`, and for [`createStickyPin`](#createstickypinoptions)'s `end`, [`createResolvedTrigger`](#createresolvedtriggeroptions)'s `start`/`end`, and [`resolveScrollPosition`](#resolvescrollpositionelement-position)'s `position`.
459
+ GSAP treats a value as an absolute scroll position rather than a clause whenever it's just a number: a plain JS number, or a string `Number()` converts on its own with no keyword, second token, or `%`/`px` suffix, `'-50'` and `'1e3'` included. It ignores the reference element entirely in that case (`ScrollTrigger.js`'s `_parsePosition`: `isNaN(value) || (value = +value)`). This module follows the same rule for `start` and `end`, and for [`createStickyPin`](#createstickypinoptions)'s `end`, [`createResolvedTrigger`](#createresolvedtriggeroptions)'s `start`/`end`, and [`resolveScrollPosition`](#resolvescrollpositionelement-position)'s `position`.
450
460
 
451
461
  `start: '500'` (or `start: 500`) freezes starting at absolute scroll position 500px, ignoring the trigger's natural position and any preceding dwell. `end: '500'` ends the freeze window at 500px the same way, clamped to `start` if that would put `end` before it, matching GSAP's own `end = Math.max(start, ...)`.
452
462
 
@@ -462,7 +472,7 @@ If the entire value is just a number (a plain JS number, or a string that's noth
462
472
 
463
473
  A bare number (or numeric string with no sign/`%`/`px`) is an absolute scroll position; see [Absolute scroll position](#absolute-scroll-position) above. `end` follows the same rule `start` uses, matching GSAP.
464
474
 
465
- "Dwell distance": how many px to keep pinning after the freeze starts. Matching GSAP, only a string starting with the literal `'+='` prefix counts (or a `%`-suffixed `'+=...'`, resolved against the viewport height). A leading `-=`/`+`/`-` without `=`, or a `%` without `+=`, is a position clause instead (see below). A dwell `end` never consults `endTrigger`, again matching GSAP: the distance runs from wherever the freeze starts.
475
+ "Dwell distance": how many px to keep pinning after the freeze starts. Matching GSAP, only a string starting with the literal `'+='` prefix and holding no space counts (or a `%`-suffixed `'+=...'`, resolved against the viewport height). A leading `-=`/`+`/`-` without `=`, or a `%` without `+=`, is a position clause instead (see below), as is a `'+='` value with a space in it. A dwell `end` never consults `endTrigger`, again matching GSAP: the distance runs from wherever the freeze starts, or from the resolved `start` in [`createResolvedTrigger`](#createresolvedtriggeroptions), which has no freeze window.
466
476
 
467
477
  | example | meaning |
468
478
  | -------------------------------- | ------------------------------------- |
@@ -481,9 +491,23 @@ sticky.createStickyTrigger({
481
491
  });
482
492
  ```
483
493
 
484
- If `endTrigger` points to another registered layer, its position is resolved using the same computation this module already does for that layer. A forward reference (pointing to a layer later in DOM order) only works from `createOverlapScroll`'s cover layer, which adds no padding and so doesn't depend on its own dwell. A `createStickyTrigger` Scene layer throws immediately instead: its own dwell padding pushes down everything after it, so the reference would depend on that dwell and never converge.
494
+ A `'+='` value with a space in it (`'+=100 bottom'`) is a position clause too, and GSAP gives it a base before resolving it: the element token from `start`. So `start: 'bottom bottom'` with `end: '+=100 bottom'` reads as `'bottom+=100 bottom'`, 100px past `endTrigger`'s own bottom edge. A `'top'` or `'0'` element token contributes nothing, which covers the `start` defaults of [`createStickyTrigger`](#createstickytriggeroptions) (`'0 0'`), [`createStickyPin`](#createstickypinoptions) (`'top top'`) and [`createResolvedTrigger`](#createresolvedtriggeroptions) (`'top bottom'`). [`createOverlapScroll`](#createoverlapscrolloptions) is the exception: its `'bottom bottom'` default puts a full `endTrigger` height into this `end` form even when the caller never passes `start`. Every method that takes a `start` and an `end` does this prefixing itself, since it resolves both sides into numbers before GSAP ever sees them.
495
+
496
+ One pair can't compose: a `start` whose element token already carries an offset (`'top+=50 bottom'`) throws. GSAP splits a token at its first `=`, so it would keep the `50` and silently discard the `end`'s own offset. A signed number (`'-50 top'`) composes normally, matching GSAP.
497
+
498
+ If `endTrigger` points to another registered layer's `trigger`, it's resolved like any other element, by the rules in the next paragraph, and that layer's own `trigger` counts as enclosing it. A forward reference (pointing to a layer later in DOM order) only works from `createOverlapScroll`'s cover layer; a `createStickyTrigger` Scene layer throws instead.
499
+
500
+ For any `endTrigger` inside the container, registered or not, its raw DOM position is measured directly, then adjusted the way GSAP's own pins would move the point on it that `end` names, by the dwell of other registered Scene layers, including ones registered after this call. A scene whose `trigger` ends above `endTrigger` counts in full. One whose `trigger` sits inside `endTrigger` in the DOM grows it rather than moving it, so it counts by the share of `endTrigger`'s height in `end`'s element side: all of it for `'bottom top'`, half for `'center top'`, none for `'top+=100 top'`. A scene that encloses `endTrigger` counts in full if it freezes before that point reaches its viewport anchor. No other scene counts, even one that freezes first. The point `start` names on `trigger`, which the window's length is measured from, moves by the same rule.
501
+
502
+ An `end` on `trigger` itself counts the scenes nested inside `trigger` by the difference between `end`'s share and `start`'s, so the default `'bottom top'` after `'top top'` takes in their whole dwell. An absolute `start` has no share, and its `end` also counts every scene whose `trigger` ends above `trigger`.
503
+
504
+ These rules assume the elements holding a scene's `trigger` grow with its spacer, as auto-height elements do under GSAP's pins. With a fixed CSS `height`, the spacer overflows the element instead, so GSAP's pins would move no point inside or after that element. This module still counts the scene as inside or above such points.
505
+
506
+ Counting an enclosing scene departs from plain GSAP pins, which measure a point inside a pinned element as if the pin weren't there, so whichever of `start` and `end` sits inside it lands early by the pin's duration unless `pinnedContainer` names that element. This module finds the nesting itself and counts an enclosing scene the way `pinnedContainer` does, but decides at each point rather than once at `start`, and for every enclosing scene rather than one. So it also counts a scene that freezes after `start` but before the point `end` names arrives, which `pinnedContainer` leaves out.
507
+
508
+ Some sets of Scene layers have no layout where every `end` agrees with what it counts, such as two nested scenes whose `endTrigger`s each lie past the other's `trigger`. Those resolve the way GSAP's pins would if created in dependency order: each layer after the layers its `end` counts and after the scenes whose `trigger` encloses its own. Each `end` then counts only the layers before it, and a scene enclosed by an earlier one no longer pushes points outside that scene.
485
509
 
486
- For an unregistered `endTrigger`, its raw DOM position is measured directly, then adjusted by the dwell of every registered Scene layer structurally positioned before it, including ones registered after this call, if their `trigger` sits between this layer's `trigger` and `endTrigger`.
510
+ A `createOverlapScroll` cover layer's `end` instead counts a scene's dwell exactly when that scene freezes before the point arrives, for any `endTrigger` inside the container, registered or not: its window describes the rise on screen, and a cover has no pin spacer to match.
487
511
 
488
512
  > Keep `createStickyTrigger`'s `endTrigger` inside the shared container: pointing at an element outside it throws. If you need to reference something outside the container, use a dwell distance (e.g. `'+=500'`) instead.
489
513
  >
@@ -509,14 +533,15 @@ sticky.createOverlapScroll({
509
533
  - `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
510
534
  - `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
511
535
  - That shared parent also caps how far `cover` can rise: it needs `end - start` worth of content below `trigger`, or the browser releases the wrapper mid-rise, at a point that shifts with the window size (see [Room for the rise](#room-for-the-rise))
536
+ - Everything in that parent up to and including `trigger` is pinned with `trigger` until the rise runs out of room, and [`resolveScrollPosition`](#resolvescrollpositionelement-position), [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances) and same-page links don't account for that pin. A position such an element reaches before the pin starts resolves correctly. A later one is only reached after `cover` has risen over the element, so it has no uncovered scroll position: a same-page link lands while the element is pinned, below the viewport's top edge and possibly already under `cover`
512
537
  - `createStickyTrigger` and `createOverlapScroll` throw if `trigger` isn't inside the shared container. Both build their structure inside it, so a `trigger` elsewhere would wrap, move and style elements the instance doesn't own
513
538
  - `createStickyPin` works on either side of the container, and throws only for a `trigger` that encloses it (the container itself, or an ancestor). A pin makes `trigger` itself `position:sticky` inside a box holding the pin range, which would pin the container and the layers' dwell padding along with it
514
539
  - Selector strings for `trigger`/`endTrigger`/`cover`/`element` resolve against the whole document, as GSAP's own `trigger` does, rather than within the shared container; only the `trigger` rules above restrict where a match may land. Validate or scope these values yourself if they come from content you don't control
515
540
  - ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
516
541
  - GSAP's `clamp()` position wrapper isn't accepted, and a function-valued `start`/`end` is called with no arguments rather than with the `ScrollTrigger` instance GSAP passes (see [Position syntax](#position-syntax))
517
- - A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can, since it adds no padding (see [End syntax](#end-syntax))
542
+ - A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can (see [End syntax](#end-syntax))
518
543
  - If a Scene layer's `end` uses a position clause, don't set `endTrigger` to an element that gets pushed down by that same scene's own dwell; the value won't converge
519
- - If several layers' unregistered or cover-layer `endTrigger`s form a dependency cycle, `refresh()` throws instead of settling on a wrong value
544
+ - If Scene layers' `endTrigger`s depend on each other in a way that never settles, the layers resolve in dependency order (see [End syntax](#end-syntax)). `refresh()` can still throw in rare arrangements, such as a scene whose `end` counts one with an absolute `start` only while a third scene's window closes before it, and that third scene's `start` moves with the first scene's dwell. Two layers whose ends each move the other settle on the one answer they share
520
545
  - `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
521
546
  - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
522
547
  - You must call `refresh()` once manually after registration. Window resize/load recomputation is automatically wired to GSAP's own `refreshInit`, but for layout changes that don't involve those (e.g. content height changes), call `ScrollTrigger.refresh()` yourself (see [Calling refresh](#calling-refresh))
@@ -1,6 +1,6 @@
1
1
  /*!
2
2
  * @license
3
- * StickyScrollTrigger v0.8.0
3
+ * StickyScrollTrigger v0.10.0
4
4
  * Copyright (c) 2026 Kuninori Ogino
5
5
  * Released under the MIT License
6
6
  * https://github.com/kuninori-ogino/sticky-scroll-trigger