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.
@@ -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
@@ -48,11 +48,35 @@ var StickyScrollTrigger = (function() {
48
48
  probe.remove();
49
49
  return height;
50
50
  };
51
- const measureDocumentMaxScroll = (viewportHeight) => {
52
- const doc = document.documentElement;
53
- return Math.max(0, (doc.scrollHeight || document.body.scrollHeight) - viewportHeight);
51
+ const measureDocumentHeight = () => document.documentElement.scrollHeight || document.body.scrollHeight;
52
+ const pinRanges = new Set();
53
+ const measureDocumentHeightWithoutPinRanges = () => {
54
+ pinRanges.forEach((inner) => {
55
+ if (!inner.isConnected) pinRanges.delete(inner);
56
+ });
57
+ const saved = [...pinRanges].map((inner) => ({
58
+ inner,
59
+ height: inner.style.height
60
+ }));
61
+ saved.forEach(({ inner }) => {
62
+ inner.style.height = "";
63
+ });
64
+ const height = measureDocumentHeight();
65
+ saved.forEach(({ inner, height: range }) => {
66
+ inner.style.height = range;
67
+ });
68
+ return height;
69
+ };
70
+ const measureDocumentMaxScroll = (viewportHeight) => Math.max(0, measureDocumentHeight() - viewportHeight);
71
+ const measureBorderWidth = (borderStyle, width) => borderStyle === "none" || borderStyle === "hidden" ? 0 : parseFloat(width);
72
+ const measureUsedHeight = (el) => {
73
+ const rounded = el.offsetHeight;
74
+ const style = getComputedStyle(el);
75
+ const height = parseFloat(style.height);
76
+ if (!Number.isFinite(height)) return rounded;
77
+ const measured = style.boxSizing === "border-box" ? height : height + parseFloat(style.paddingTop) + parseFloat(style.paddingBottom) + measureBorderWidth(style.borderTopStyle, style.borderTopWidth) + measureBorderWidth(style.borderBottomStyle, style.borderBottomWidth);
78
+ return rounded > 0 && Math.abs(measured - rounded) >= 1 ? rounded : measured;
54
79
  };
55
- const measureUsedHeight = (el) => parseFloat(getComputedStyle(el).height) || 0;
56
80
  const compareDocumentOrder = (a, b) => {
57
81
  const position = a.compareDocumentPosition(b);
58
82
  if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
@@ -114,10 +138,11 @@ var StickyScrollTrigger = (function() {
114
138
  if (!trigger.parentNode) throw new Error(`createStickyPin: trigger ${describeElement(trigger)} is not attached to the document`);
115
139
  const outer = document.createElement("div");
116
140
  const inner = document.createElement("div");
117
- outer.style.contain = "layout";
141
+ outer.style.display = "flow-root";
118
142
  trigger.parentNode.insertBefore(outer, trigger);
119
143
  outer.appendChild(inner);
120
144
  inner.appendChild(trigger);
145
+ pinRanges.add(inner);
121
146
  return {
122
147
  outer,
123
148
  inner
@@ -127,6 +152,7 @@ var StickyScrollTrigger = (function() {
127
152
  const parent = outer.parentNode;
128
153
  restoreInlinePosition(trigger, saved);
129
154
  if (parent) parent.insertBefore(trigger, outer);
155
+ if (outer.firstElementChild instanceof HTMLElement) pinRanges.delete(outer.firstElementChild);
130
156
  outer.remove();
131
157
  };
132
158
  const LIFT_VALUES = {
@@ -170,6 +196,417 @@ var StickyScrollTrigger = (function() {
170
196
  lifted.length = 0;
171
197
  };
172
198
  };
199
+ const resolveMaybeFn = (value) => typeof value === "function" ? value() : value;
200
+ const KEYWORD_FRACTIONS = {
201
+ top: 0,
202
+ center: .5,
203
+ bottom: 1
204
+ };
205
+ const signedPx = (sign, value, unit, refSize) => {
206
+ const magnitude = unit === "%" ? parseFloat(value) / 100 * refSize : parseFloat(value);
207
+ return sign?.startsWith("-") ? -magnitude : magnitude;
208
+ };
209
+ const CLAUSE_TOKEN_RE = /^(top|center|bottom|[+-]?(?:\d+(?:\.\d*)?|\.\d+))?(%|px)?(?:([+-]=?)(\d+(?:\.\d*)?|\.\d+)(%|px)?)?$/;
210
+ const parseClauseToken = (token, refSize) => {
211
+ const match = CLAUSE_TOKEN_RE.exec(token);
212
+ if (!match || !match[1] && !match[3]) {
213
+ if (MAX_TOKEN_RE.test(token)) throw new Error(`StickyScrollTrigger: unsupported position clause "${token}": 'max' is GSAP's end-only keyword for the scroller's maximum scroll position.`);
214
+ throw new Error(`StickyScrollTrigger: unsupported position clause "${token}"`);
215
+ }
216
+ const [, base, baseUnit, sign, offsetValue, offsetUnit] = match;
217
+ if (base !== void 0 && sign && !sign.includes("=")) {
218
+ const suggestion = `${base}${baseUnit ?? ""}${sign}=${offsetValue}${offsetUnit ?? ""}`;
219
+ throw new Error(`StickyScrollTrigger: unsupported position clause "${token}": a signed offset needs an explicit '=' when it follows a keyword or number (GSAP needs it to tell "${base}" from the offset). Did you mean "${suggestion}"?`);
220
+ }
221
+ const isKeyword = base !== void 0 && base in KEYWORD_FRACTIONS;
222
+ const basePercent = baseUnit === "%";
223
+ return {
224
+ fraction: isKeyword ? KEYWORD_FRACTIONS[base] : basePercent ? parseFloat(base) / 100 : 0,
225
+ offsetPx: (!isKeyword && !basePercent && base !== void 0 ? parseFloat(base) : 0) + (sign ? signedPx(sign, offsetValue, offsetUnit, refSize) : 0)
226
+ };
227
+ };
228
+ const isAbsoluteFormat = (resolved) => {
229
+ if (typeof resolved === "number") return true;
230
+ return resolved.trim() !== "" && !Number.isNaN(Number(resolved));
231
+ };
232
+ const resolveAbsolute = (resolved) => typeof resolved === "number" ? resolved : Number(resolved);
233
+ const CLAMP_PREFIX = "clamp(";
234
+ const assertNotClamped = (trimmed) => {
235
+ if (!trimmed.startsWith(CLAMP_PREFIX)) return;
236
+ const inner = trimmed.slice(6).replace(/\)$/, "").trim();
237
+ throw new Error(`StickyScrollTrigger: unsupported position clause "${trimmed}": GSAP's clamp() wrapper isn't supported here.` + (inner ? ` Did you mean "${inner}"?` : ""));
238
+ };
239
+ const resolveElementAnchor = (position, elementHeight) => {
240
+ const trimmed = position.trim();
241
+ assertNotClamped(trimmed);
242
+ const elementClause = parseClauseToken(trimmed.split(/\s+/)[0], elementHeight);
243
+ return elementHeight * elementClause.fraction + elementClause.offsetPx;
244
+ };
245
+ const resolveElementFraction = (position) => resolveElementAnchor(position, 1) - resolveElementAnchor(position, 0);
246
+ const resolveAnchorTop = (position, elementHeight, viewportHeight) => {
247
+ const trimmed = position.trim();
248
+ assertNotClamped(trimmed);
249
+ const viewportToken = trimmed.split(/\s+/)[1] ?? "top";
250
+ const viewportClause = parseClauseToken(viewportToken, viewportHeight);
251
+ return viewportHeight * viewportClause.fraction + viewportClause.offsetPx - resolveElementAnchor(trimmed, elementHeight);
252
+ };
253
+ const DWELL_RELATIVE_RE = /^\+=(\d+(?:\.\d*)?|\.\d+)(%|px)?$/;
254
+ const isDwellFormat = (resolved) => typeof resolved === "string" && DWELL_RELATIVE_RE.test(resolved.trim());
255
+ const prefixSpacedRelativeEnd = (start, endResolved) => {
256
+ if (typeof endResolved !== "string") return endResolved;
257
+ const trimmedEnd = endResolved.trim();
258
+ if (!trimmedEnd.startsWith("+=") || !/\s/.test(trimmedEnd)) return endResolved;
259
+ const startResolved = resolveMaybeFn(start);
260
+ if (typeof startResolved !== "string") return endResolved;
261
+ const trimmedStart = startResolved.trim();
262
+ assertNotClamped(trimmedStart);
263
+ const [elementToken] = trimmedStart.split(/\s+/);
264
+ try {
265
+ parseClauseToken(elementToken, 0);
266
+ } catch (error) {
267
+ if (!isAbsoluteFormat(startResolved)) throw error;
268
+ return endResolved;
269
+ }
270
+ parseClauseToken(trimmedEnd.split(/\s+/)[0], 0);
271
+ if (elementToken.includes("=")) throw new Error(`StickyScrollTrigger: end "${endResolved}" can't be resolved against start "${startResolved}": GSAP reads an end that starts with '+=' and holds a space by prefixing it with the start clause's element token, and "${elementToken}" carries an offset of its own, which GSAP resolves by discarding the end's. Give end a complete position clause instead, such as 'top+=100 bottom'.`);
272
+ return elementToken + trimmedEnd;
273
+ };
274
+ const resolveDwell = (resolved, viewportHeight) => {
275
+ const match = DWELL_RELATIVE_RE.exec(String(resolved).trim());
276
+ if (!match) throw new Error(`StickyScrollTrigger: unsupported end format "${resolved}"`);
277
+ const [, value, unit] = match;
278
+ return signedPx(void 0, value, unit, viewportHeight);
279
+ };
280
+ const MAX_TOKEN_RE = /^max(?:([+-]=)(\d+(?:\.\d*)?|\.\d+)(%|px)?)?$/;
281
+ const isMaxFormat = (resolved) => typeof resolved === "string" && MAX_TOKEN_RE.test(resolved.trim());
282
+ const resolveMaxOffset = (resolved, viewportHeight) => {
283
+ const match = MAX_TOKEN_RE.exec(resolved.trim());
284
+ if (!match) throw new Error(`StickyScrollTrigger: unsupported max-position format "${resolved}"`);
285
+ const [, sign, value, unit] = match;
286
+ return sign ? signedPx(sign, value, unit, viewportHeight) : 0;
287
+ };
288
+ const classifyPosition = (resolved) => {
289
+ if (typeof resolved === "number") return {
290
+ kind: "absolute",
291
+ value: resolved
292
+ };
293
+ if (isDwellFormat(resolved)) return {
294
+ kind: "dwell",
295
+ value: resolved
296
+ };
297
+ if (isMaxFormat(resolved)) return {
298
+ kind: "max",
299
+ value: resolved
300
+ };
301
+ if (isAbsoluteFormat(resolved)) return {
302
+ kind: "absolute",
303
+ value: resolveAbsolute(resolved)
304
+ };
305
+ return {
306
+ kind: "clause",
307
+ value: resolved
308
+ };
309
+ };
310
+ const isHeldIn = (measurements, index, enclosedBy, anchorElement, order) => measurements[index].triggerEnclosedBy.some((m) => m !== index && measurements[m].kind === "scene" && order.isBefore(m, index) && !(enclosedBy.includes(m) && m !== anchorElement));
311
+ const nestedIn = (measurements, index) => measurements.flatMap(({ triggerEnclosedBy }, k) => k !== index && triggerEnclosedBy.includes(index) ? [k] : []);
312
+ const anchorShare = (measurements, windows, index, freezeStart, box, reachedAt, enclosedBy, anchorElement, order, ownIndex) => {
313
+ const measurement = measurements[index];
314
+ if (enclosedBy.includes(index)) return (measurement.start.mode === "absolute" ? freezeStart - windows.reduce((earlier, other) => other.index !== index && other.index !== ownIndex && !(order && order.isBefore(ownIndex, other.index)) && other.freezeEnd <= freezeStart + .05 ? earlier + other.freezeEnd - other.freezeStart : earlier, 0) : measurement.triggerTop - measurement.start.anchorOffset) < reachedAt - .05 ? 1 : 0;
315
+ if (order && isHeldIn(measurements, index, enclosedBy, anchorElement, order)) return 0;
316
+ if (box.nests.includes(index)) return box.fraction;
317
+ return measurement.triggerTop + measurement.triggerHeight <= box.top + .05 ? 1 : 0;
318
+ };
319
+ const gapsBeforeEndAnchor = (measurements, windows, box, reachedAt, enclosedBy, ownIndex, anchorElement, order, counted) => windows.reduce((total, { index, freezeStart, freezeEnd }) => {
320
+ if (index === ownIndex || order && order.isBefore(ownIndex, index)) return total;
321
+ const weight = anchorShare(measurements, windows, index, freezeStart, box, reachedAt, enclosedBy, anchorElement, order, ownIndex);
322
+ if (weight === 0) return total;
323
+ counted?.add(index);
324
+ return total + weight * (freezeEnd - freezeStart);
325
+ }, 0);
326
+ const clauseFreezeStart = (measurements, index, paddingOf) => {
327
+ const reachOf = (k) => {
328
+ const { start, triggerTop } = measurements[k];
329
+ return start.mode === "clause" ? triggerTop - start.anchorOffset : null;
330
+ };
331
+ const scenes = measurements.flatMap(({ kind }, k) => kind === "scene" ? [k] : []);
332
+ const clauses = scenes.filter((k) => reachOf(k) !== null).sort((a, b) => {
333
+ const gap = reachOf(a) - reachOf(b);
334
+ return Math.abs(gap) <= .05 ? a - b : gap;
335
+ });
336
+ const absolutes = scenes.flatMap((k) => {
337
+ const { start } = measurements[k];
338
+ return start.mode === "absolute" ? [{
339
+ k,
340
+ value: start.value
341
+ }] : [];
342
+ }).sort((a, b) => a.value - b.value);
343
+ let dwell = 0;
344
+ let nextAbsolute = 0;
345
+ for (const k of clauses) {
346
+ const reachedAt = reachOf(k);
347
+ while (nextAbsolute < absolutes.length && absolutes[nextAbsolute].value < reachedAt + dwell + .05) {
348
+ dwell += paddingOf(absolutes[nextAbsolute].k);
349
+ nextAbsolute += 1;
350
+ }
351
+ if (k === index) return reachedAt + dwell;
352
+ dwell += paddingOf(k);
353
+ }
354
+ throw new Error("StickyScrollTrigger: internal error: clauseFreezeStart was given a layer without a clause start.");
355
+ };
356
+ const runPass = (measurements, { viewportHeight, measureLiveEndTriggerTop }, previous, order, record) => {
357
+ const fresh = [];
358
+ const knownWindows = () => measurements.flatMap((measurement, k) => {
359
+ if (measurement.kind !== "scene") return [];
360
+ const plan = fresh[k];
361
+ if (plan) return [{
362
+ index: k,
363
+ freezeStart: plan.freezeStart,
364
+ freezeEnd: plan.freezeEnd
365
+ }];
366
+ const freezeStart = previous?.freezeStarts[k] ?? null;
367
+ const paddingHeight = previous?.paddings[k] ?? null;
368
+ return freezeStart === null || paddingHeight === null ? [] : [{
369
+ index: k,
370
+ freezeStart,
371
+ freezeEnd: freezeStart + paddingHeight
372
+ }];
373
+ });
374
+ const paddingOf = (k) => fresh[k]?.paddingHeight ?? previous?.paddings[k] ?? 0;
375
+ const recounts = [];
376
+ const plans = measurements.map((measurement, index) => {
377
+ fresh[index] = null;
378
+ if (measurement.kind === "cover") return null;
379
+ const recount = {
380
+ index,
381
+ counted: new Set(),
382
+ runs: []
383
+ };
384
+ recounts.push(recount);
385
+ const { start } = measurement;
386
+ const freezeStart = start.mode === "absolute" ? start.value : clauseFreezeStart(measurements, index, paddingOf);
387
+ let freezeEnd;
388
+ switch (measurement.end.mode) {
389
+ case "dwell":
390
+ freezeEnd = freezeStart + measurement.end.distancePx;
391
+ break;
392
+ case "absolute":
393
+ freezeEnd = Math.max(freezeStart, measurement.end.value);
394
+ break;
395
+ case "auto":
396
+ case "max": throw new Error(`StickyScrollTrigger: internal error: a Scene layer reached '${measurement.end.mode}' end mode, which only a cover layer can have.`);
397
+ case "clause": {
398
+ const anchorOffsetEnd = resolveAnchorTop(measurement.end.clause, measurement.endTriggerHeight, viewportHeight);
399
+ if (measurement.endTriggerIsSelf) {
400
+ const nests = nestedIn(measurements, index);
401
+ const weight = resolveElementFraction(measurement.end.clause) - (start.mode === "clause" ? start.elementFraction : 0);
402
+ const dwellInside = measurements.reduce((total, other, k) => {
403
+ if (weight === 0 || other.kind !== "scene" || !nests.includes(k) || order && (order.isBefore(index, k) || isHeldIn(measurements, k, measurement.triggerEnclosedBy, index, order))) return total;
404
+ recount.counted.add(k);
405
+ return total + weight * paddingOf(k);
406
+ }, 0);
407
+ if (start.mode === "clause") {
408
+ freezeEnd = freezeStart + Math.max(0, start.anchorOffset - anchorOffsetEnd + dwellInside);
409
+ break;
410
+ }
411
+ const dwellAbove = measurements.reduce((total, other, k) => {
412
+ if (k === index || other.kind !== "scene" || nests.includes(k) || other.triggerTop + other.triggerHeight > measurement.triggerTop + .05 || order && (order.isBefore(index, k) || isHeldIn(measurements, k, measurement.triggerEnclosedBy, index, order))) return total;
413
+ recount.counted.add(k);
414
+ return total + paddingOf(k);
415
+ }, 0);
416
+ freezeEnd = Math.max(freezeStart, measurement.triggerTop - anchorOffsetEnd + dwellAbove + dwellInside);
417
+ break;
418
+ }
419
+ let endTop;
420
+ if (measurement.end.measureLive) endTop = measureLiveEndTriggerTop(index);
421
+ else {
422
+ const rawTop = measurement.endTriggerIndex === null ? measurement.end.rawTop : measurements[measurement.endTriggerIndex].triggerTop;
423
+ if (rawTop === null) endTop = 0;
424
+ else {
425
+ const box = {
426
+ top: rawTop,
427
+ fraction: resolveElementFraction(measurement.end.clause),
428
+ nests: measurement.endTriggerNests
429
+ };
430
+ const gaps = (w, counted) => gapsBeforeEndAnchor(measurements, w, box, rawTop - anchorOffsetEnd, measurement.endTriggerEnclosedBy, index, measurement.endTriggerIndex, order, counted);
431
+ endTop = rawTop + gaps(knownWindows());
432
+ recount.runs.push((w) => gaps(w, recount.counted));
433
+ }
434
+ }
435
+ let layoutStart;
436
+ if (start.mode === "absolute") layoutStart = start.value;
437
+ else {
438
+ const gaps = (w, counted) => gapsBeforeEndAnchor(measurements, w, {
439
+ top: measurement.triggerTop,
440
+ fraction: start.elementFraction,
441
+ nests: nestedIn(measurements, index)
442
+ }, measurement.triggerTop - start.anchorOffset, measurement.triggerEnclosedBy, index, index, order, counted);
443
+ layoutStart = measurement.triggerTop - start.anchorOffset + gaps(knownWindows());
444
+ recount.runs.push((w) => gaps(w, recount.counted));
445
+ }
446
+ freezeEnd = freezeStart + Math.max(0, endTop - anchorOffsetEnd - layoutStart);
447
+ break;
448
+ }
449
+ }
450
+ const paddingHeight = Math.max(0, freezeEnd - freezeStart);
451
+ const plan = {
452
+ freezeStart,
453
+ freezeEnd,
454
+ stickyTop: 0,
455
+ paddingHeight
456
+ };
457
+ fresh[index] = plan;
458
+ return plan;
459
+ });
460
+ if (record) {
461
+ const windows = knownWindows();
462
+ recounts.forEach(({ index, counted, runs }) => {
463
+ runs.forEach((run) => run(windows));
464
+ record(index, counted);
465
+ });
466
+ }
467
+ return plans;
468
+ };
469
+ const planCover = (measurements, index, windows, { viewportHeight, documentMaxScroll, measureLiveEndTriggerTop }) => {
470
+ const measurement = measurements[index];
471
+ if (measurement.start.mode !== "clause") throw new Error("StickyScrollTrigger: internal error: a cover layer measurement carries an absolute start, which resolveStartSpec should have already rejected.");
472
+ const reached = (reachedAt) => reachedAt + dwellBeforeReach(reachedAt, windows);
473
+ const startReachedAt = measurement.triggerTop - measurement.start.anchorOffset;
474
+ const freezeStart = startReachedAt + dwellBeforeReach(startReachedAt, windows, { countTies: true });
475
+ let freezeEnd;
476
+ switch (measurement.end.mode) {
477
+ case "auto":
478
+ freezeEnd = reached(measurement.coverTop);
479
+ break;
480
+ case "dwell":
481
+ freezeEnd = freezeStart + measurement.end.distancePx;
482
+ break;
483
+ case "absolute":
484
+ freezeEnd = measurement.end.value;
485
+ break;
486
+ case "max":
487
+ freezeEnd = documentMaxScroll + measurement.end.offsetPx;
488
+ break;
489
+ case "clause": {
490
+ const anchorOffsetEnd = resolveAnchorTop(measurement.end.clause, measurement.endTriggerHeight, viewportHeight);
491
+ if (measurement.end.measureLive) freezeEnd = measureLiveEndTriggerTop(index) - anchorOffsetEnd;
492
+ else freezeEnd = reached((measurement.endTriggerIsSelf ? measurement.triggerTop : measurement.endTriggerIndex === null ? measurement.end.rawTop ?? 0 : measurements[measurement.endTriggerIndex].triggerTop) - anchorOffsetEnd);
493
+ break;
494
+ }
495
+ }
496
+ return {
497
+ freezeStart,
498
+ freezeEnd: Math.max(freezeStart, freezeEnd),
499
+ stickyTop: measurement.start.anchorOffset - (measurement.triggerTop - measurement.wrapperTop),
500
+ paddingHeight: null
501
+ };
502
+ };
503
+ const TIE_TOLERANCE_PX = .05;
504
+ const dwellBeforeReach = (reachedAt, windows, { countTies = false } = {}) => {
505
+ const tolerance = countTies ? -.05 : TIE_TOLERANCE_PX;
506
+ let earlierDwell = 0;
507
+ let counted = 0;
508
+ [...windows].sort((a, b) => a.freezeStart - b.freezeStart).forEach(({ freezeStart, freezeEnd }) => {
509
+ if (freezeStart < reachedAt + earlierDwell - tolerance) counted += freezeEnd - freezeStart;
510
+ earlierDwell += freezeEnd - freezeStart;
511
+ });
512
+ return counted;
513
+ };
514
+ const dwellConsumedAt = (scroll, windows) => windows.reduce((consumed, { freezeStart, freezeEnd }) => consumed + Math.min(Math.max(scroll - freezeStart, 0), freezeEnd - freezeStart), 0);
515
+ const componentsOf = (edges) => {
516
+ const visitOrder = edges.map(() => -1);
517
+ const lowLink = edges.map(() => 0);
518
+ const component = edges.map(() => -1);
519
+ const stack = [];
520
+ let visited = 0;
521
+ let components = 0;
522
+ const visit = (v) => {
523
+ visitOrder[v] = visited;
524
+ lowLink[v] = visited;
525
+ visited += 1;
526
+ stack.push(v);
527
+ for (const w of edges[v]) if (visitOrder[w] === -1) {
528
+ visit(w);
529
+ lowLink[v] = Math.min(lowLink[v], lowLink[w]);
530
+ } else if (component[w] === -1) lowLink[v] = Math.min(lowLink[v], visitOrder[w]);
531
+ if (lowLink[v] === visitOrder[v]) {
532
+ let w;
533
+ do {
534
+ w = stack.pop();
535
+ component[w] = components;
536
+ } while (w !== v);
537
+ components += 1;
538
+ }
539
+ };
540
+ edges.forEach((_, v) => {
541
+ if (visitOrder[v] === -1) visit(v);
542
+ });
543
+ return component;
544
+ };
545
+ const fallbackOrder = (measurements, counted) => {
546
+ const component = componentsOf(measurements.map(({ triggerEnclosedBy }, i) => [...counted[i], ...triggerEnclosedBy.filter((m) => m !== i && measurements[m].kind === "scene")]));
547
+ const rank = [];
548
+ measurements.map((_, i) => i).sort((a, b) => component[a] - component[b] || a - b).forEach((layer, position) => {
549
+ rank[layer] = position;
550
+ });
551
+ return { isBefore: (a, b) => rank[a] < rank[b] };
552
+ };
553
+ const planLayers = (measurements, deps) => {
554
+ const needsConvergence = measurements.filter(({ kind }) => kind === "scene").length > 1;
555
+ const liveTopCache = new Map();
556
+ const passDeps = {
557
+ ...deps,
558
+ measureLiveEndTriggerTop: (index) => {
559
+ const cached = liveTopCache.get(index);
560
+ if (cached !== void 0) return cached;
561
+ const value = deps.measureLiveEndTriggerTop(index);
562
+ liveTopCache.set(index, value);
563
+ return value;
564
+ }
565
+ };
566
+ const stateOf = (passPlans) => ({
567
+ paddings: passPlans.map((plan) => plan?.paddingHeight ?? null),
568
+ freezeStarts: passPlans.map((plan) => plan?.freezeStart ?? null)
569
+ });
570
+ const sameValues = (a, b) => a.every((value, i) => value === b[i] || value !== null && b[i] !== null && Math.abs(value - b[i]) <= .05);
571
+ const sameState = (a, b) => sameValues(a.paddings, b.paddings) && sameValues(a.freezeStarts, b.freezeStarts);
572
+ const average = (a, b) => a.map((value, i) => value === null ? null : (value + b[i]) / 2);
573
+ const settle = (order, record) => {
574
+ let plans = runPass(measurements, passDeps, null, order, record);
575
+ if (!needsConvergence) return plans;
576
+ const budget = order === null ? Math.max(64, 2 * measurements.length + 2) : 2 * measurements.length + 2;
577
+ let fed = stateOf(plans);
578
+ let fedBefore = null;
579
+ for (let pass = 0; pass < budget; pass += 1) {
580
+ plans = runPass(measurements, passDeps, fed, order, record);
581
+ const out = stateOf(plans);
582
+ if (sameState(out, fed)) return plans;
583
+ const flipped = fedBefore !== null && sameState(out, fedBefore);
584
+ fedBefore = fed;
585
+ fed = flipped ? {
586
+ paddings: average(out.paddings, fed.paddings),
587
+ freezeStarts: average(out.freezeStarts, fed.freezeStarts)
588
+ } : out;
589
+ }
590
+ return null;
591
+ };
592
+ const counted = measurements.map(() => new Set());
593
+ let settled = settle(null, (index, layers) => layers.forEach((k) => counted[index].add(k)));
594
+ if (settled === null) settled = settle(fallbackOrder(measurements, counted), null);
595
+ if (settled === null) throw new Error("StickyScrollTrigger: could not resolve endTrigger positions: some endTrigger references form a circular structural dependency that never settles. Point each endTrigger at an element that doesn't depend on it.");
596
+ const plans = settled;
597
+ const withTops = plans.map((plan, index) => {
598
+ if (plan === null) return null;
599
+ const outerDwell = plans.reduce((total, outer, k) => k > index && outer !== null && outer.freezeEnd <= plan.freezeStart + .05 ? total + outer.paddingHeight : total, 0);
600
+ return {
601
+ ...plan,
602
+ stickyTop: deps.structureTop - (plan.freezeStart - outerDwell)
603
+ };
604
+ });
605
+ const windows = withTops.filter((plan) => plan !== null);
606
+ const finalPlans = withTops.map((plan, index) => plan ?? planCover(measurements, index, windows, passDeps));
607
+ finalPlans.forEach((plan, index) => deps.onPlanned(index, plan));
608
+ return finalPlans;
609
+ };
173
610
  const OFFSET_PROPERTY = "--sst-scroll-margin-top-offset";
174
611
  let nextInstanceSuffix = 0;
175
612
  const supportsScrollDrivenAnimations = typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("animation-timeline", "scroll()");
@@ -191,8 +628,9 @@ var StickyScrollTrigger = (function() {
191
628
  declarations.push(`@supports (animation-timeline: scroll()) {[data-${instanceId}]{animation:${animations.join(",")};animation-timeline:${timelines.join(",")};animation-range:${ranges.join(",")}}}`);
192
629
  return declarations.join("");
193
630
  };
194
- const createScrollMarginSync = (rootElement) => {
631
+ const createScrollMarginSync = (rootElement, targetSelector) => {
195
632
  const instanceId = `sst${nextInstanceSuffix++}`;
633
+ const usesJsRamp = !usesCssRamp && targetSelector !== null;
196
634
  const snapshots = new WeakMap();
197
635
  let written = new Set();
198
636
  let sheet = null;
@@ -207,7 +645,7 @@ var StickyScrollTrigger = (function() {
207
645
  jsHost.style.setProperty(`--${instanceId}-c${index}`, `${consumed}px`);
208
646
  });
209
647
  };
210
- if (!usesCssRamp) window.addEventListener("scroll", applyJsRamp, { passive: true });
648
+ if (usesJsRamp) window.addEventListener("scroll", applyJsRamp, { passive: true });
211
649
  const restoreTarget = (target) => {
212
650
  const snapshot = snapshots.get(target);
213
651
  target.style.scrollMarginTop = snapshot ? snapshot.inline : "";
@@ -223,8 +661,8 @@ var StickyScrollTrigger = (function() {
223
661
  jsHost = null;
224
662
  };
225
663
  return {
226
- sync(scenes, host, targetSelector) {
227
- const ramps = scenes.filter((scene) => scene.freezeEnd > scene.freezeStart);
664
+ sync(scenes, host, measureNaturalTops) {
665
+ const ramps = scenes.filter((scene) => scene.freezeEnd > scene.freezeStart).sort((a, b) => a.freezeStart - b.freezeStart);
228
666
  if (targetSelector === null || !ramps.length || !host) {
229
667
  written.forEach(restoreTarget);
230
668
  written = new Set();
@@ -236,7 +674,7 @@ var StickyScrollTrigger = (function() {
236
674
  animationHost = host;
237
675
  animationHost.setAttribute(`data-${instanceId}`, "");
238
676
  }
239
- if (!usesCssRamp) {
677
+ if (usesJsRamp) {
240
678
  jsRamps = ramps;
241
679
  jsHost = host;
242
680
  applyJsRamp();
@@ -248,20 +686,22 @@ var StickyScrollTrigger = (function() {
248
686
  sheet.replaceSync(buildStylesheet(instanceId, ramps));
249
687
  }
250
688
  const targets = Array.from(rootElement.querySelectorAll(targetSelector));
689
+ const naturalTops = measureNaturalTops(targets);
251
690
  targets.forEach((target) => {
252
691
  const existing = snapshots.get(target);
253
692
  if (!existing) snapshots.set(target, { inline: target.style.scrollMarginTop });
254
693
  else if (written.has(target)) target.style.scrollMarginTop = existing.inline;
255
694
  });
256
695
  const consumed = ramps.map((_, index) => `var(--${instanceId}-c${index}, 0px)`).join(" + ");
257
- targets.forEach((target) => {
696
+ targets.forEach((target, targetIndex) => {
258
697
  const authorPx = parseFloat(getComputedStyle(target).scrollMarginTop) || 0;
259
- let lag = 0;
260
- ramps.forEach((scene) => {
261
- if (compareDocumentOrder(scene.trigger, target) >= 0) return;
262
- lag += scene.freezeEnd - scene.freezeStart;
263
- });
264
- target.style.scrollMarginTop = `calc(${authorPx}px + var(${OFFSET_PROPERTY}, 0px) + ${consumed} - ${lag}px)`;
698
+ let earlierDwell = 0;
699
+ const lag = ramps.map(({ freezeStart, freezeEnd }) => {
700
+ const margin = naturalTops[targetIndex] - authorPx + earlierDwell - freezeStart - TIE_TOLERANCE_PX;
701
+ earlierDwell += freezeEnd - freezeStart;
702
+ return `clamp(0px, (${margin}px - var(${OFFSET_PROPERTY}, 0px)) * 1000000, ${freezeEnd - freezeStart}px)`;
703
+ }).join(" + ");
704
+ target.style.scrollMarginTop = `calc(${authorPx}px + var(${OFFSET_PROPERTY}, 0px) + ${consumed} - (${lag}))`;
265
705
  });
266
706
  const next = new Set(targets);
267
707
  written.forEach((target) => {
@@ -270,7 +710,7 @@ var StickyScrollTrigger = (function() {
270
710
  written = next;
271
711
  },
272
712
  restore() {
273
- if (!usesCssRamp) window.removeEventListener("scroll", applyJsRamp);
713
+ if (usesJsRamp) window.removeEventListener("scroll", applyJsRamp);
274
714
  written.forEach(restoreTarget);
275
715
  written = new Set();
276
716
  clearAnimation();
@@ -317,228 +757,60 @@ var StickyScrollTrigger = (function() {
317
757
  }
318
758
  });
319
759
  };
320
- const resolveMaybeFn = (value) => typeof value === "function" ? value() : value;
321
- const KEYWORD_FRACTIONS = {
322
- top: 0,
323
- center: .5,
324
- bottom: 1
325
- };
326
- const signedPx = (sign, value, unit, refSize) => {
327
- const magnitude = unit === "%" ? parseFloat(value) / 100 * refSize : parseFloat(value);
328
- return sign?.startsWith("-") ? -magnitude : magnitude;
329
- };
330
- const CLAUSE_TOKEN_RE = /^(top|center|bottom|(?:\d+(?:\.\d*)?|\.\d+))?(%|px)?(?:([+-]=?)(\d+(?:\.\d*)?|\.\d+)(%|px)?)?$/;
331
- const parseClauseToken = (token, refSize) => {
332
- const match = CLAUSE_TOKEN_RE.exec(token);
333
- if (!match || !match[1] && !match[3]) {
334
- if (MAX_TOKEN_RE.test(token)) throw new Error(`StickyScrollTrigger: unsupported position clause "${token}": 'max' is GSAP's end-only keyword for the scroller's maximum scroll position.`);
335
- throw new Error(`StickyScrollTrigger: unsupported position clause "${token}"`);
336
- }
337
- const [, base, baseUnit, sign, offsetValue, offsetUnit] = match;
338
- if (base !== void 0 && sign && !sign.includes("=")) {
339
- const suggestion = `${base}${baseUnit ?? ""}${sign}=${offsetValue}${offsetUnit ?? ""}`;
340
- throw new Error(`StickyScrollTrigger: unsupported position clause "${token}": a signed offset needs an explicit '=' when it follows a keyword or number (GSAP needs it to tell "${base}" from the offset). Did you mean "${suggestion}"?`);
341
- }
342
- const isKeyword = base !== void 0 && base in KEYWORD_FRACTIONS;
343
- const basePercent = baseUnit === "%";
344
- return {
345
- fraction: isKeyword ? KEYWORD_FRACTIONS[base] : basePercent ? parseFloat(base) / 100 : 0,
346
- offsetPx: (!isKeyword && !basePercent && base !== void 0 ? parseFloat(base) : 0) + (sign ? signedPx(sign, offsetValue, offsetUnit, refSize) : 0)
347
- };
348
- };
349
- const isAbsoluteFormat = (resolved) => {
350
- if (typeof resolved === "number") return true;
351
- return resolved.trim() !== "" && !Number.isNaN(Number(resolved));
352
- };
353
- const resolveAbsolute = (resolved) => typeof resolved === "number" ? resolved : Number(resolved);
354
- const CLAMP_PREFIX = "clamp(";
355
- const resolveAnchorTop = (position, elementHeight, viewportHeight) => {
356
- const trimmed = position.trim();
357
- if (trimmed.startsWith(CLAMP_PREFIX)) {
358
- const inner = trimmed.slice(6).replace(/\)$/, "").trim();
359
- throw new Error(`StickyScrollTrigger: unsupported position clause "${trimmed}": GSAP's clamp() wrapper isn't supported here.` + (inner ? ` Did you mean "${inner}"?` : ""));
360
- }
361
- const [elementToken, viewportToken = "top"] = trimmed.split(/\s+/);
362
- const elementClause = parseClauseToken(elementToken, elementHeight);
363
- const viewportClause = parseClauseToken(viewportToken, viewportHeight);
364
- return viewportHeight * viewportClause.fraction + viewportClause.offsetPx - (elementHeight * elementClause.fraction + elementClause.offsetPx);
365
- };
366
- const DWELL_RELATIVE_RE = /^\+=(\d+(?:\.\d*)?|\.\d+)(%|px)?$/;
367
- const isDwellFormat = (resolved) => typeof resolved === "string" && DWELL_RELATIVE_RE.test(resolved.trim());
368
- const resolveDwell = (resolved, viewportHeight) => {
369
- const match = DWELL_RELATIVE_RE.exec(String(resolved).trim());
370
- if (!match) throw new Error(`StickyScrollTrigger: unsupported end format "${resolved}"`);
371
- const [, value, unit] = match;
372
- return signedPx(void 0, value, unit, viewportHeight);
373
- };
374
- const MAX_TOKEN_RE = /^max(?:([+-]=)(\d+(?:\.\d*)?|\.\d+)(%|px)?)?$/;
375
- const isMaxFormat = (resolved) => typeof resolved === "string" && MAX_TOKEN_RE.test(resolved.trim());
376
- const resolveMaxOffset = (resolved, viewportHeight) => {
377
- const match = MAX_TOKEN_RE.exec(resolved.trim());
378
- if (!match) throw new Error(`StickyScrollTrigger: unsupported max-position format "${resolved}"`);
379
- const [, sign, value, unit] = match;
380
- return sign ? signedPx(sign, value, unit, viewportHeight) : 0;
381
- };
382
- const gapsBeforeRawPosition = (measurements, paddingHeightsSoFar, previous, rawPosition, ownIndex) => {
383
- let total = 0;
384
- measurements.forEach((measurement, i) => {
385
- if (i === ownIndex || measurement.triggerTop >= rawPosition) return;
386
- const paddingHeight = paddingHeightsSoFar[i] !== void 0 ? paddingHeightsSoFar[i] : previous ? previous.paddings[i] : null;
387
- if (paddingHeight !== null && paddingHeight !== void 0) total += paddingHeight;
388
- });
389
- return total;
390
- };
391
- const runPass = (measurements, { viewportHeight, structureTop, documentMaxScroll, measureLiveEndTriggerTop }, previous) => {
392
- const naturalTops = [];
393
- const paddingHeightsSoFar = [];
394
- let precedingGaps = 0;
395
- return {
396
- plans: measurements.map((measurement, index) => {
397
- const naturalAbsoluteTop = measurement.triggerTop + precedingGaps;
398
- const freezeStart = measurement.start.mode === "absolute" ? measurement.start.value : naturalAbsoluteTop - measurement.start.anchorOffset;
399
- let freezeEnd;
400
- switch (measurement.end.mode) {
401
- case "auto":
402
- if (measurement.start.mode !== "clause") throw new Error("StickyScrollTrigger: internal error: an absolute start reached 'auto' end mode, which resolveStartSpec should have already rejected.");
403
- freezeEnd = freezeStart + Math.max(0, measurement.start.anchorOffset + (measurement.coverTop - measurement.triggerTop));
404
- break;
405
- case "dwell":
406
- freezeEnd = freezeStart + measurement.end.distancePx;
407
- break;
408
- case "absolute":
409
- freezeEnd = Math.max(freezeStart, measurement.end.value);
410
- break;
411
- case "max":
412
- freezeEnd = Math.max(freezeStart, documentMaxScroll + measurement.end.offsetPx);
413
- break;
414
- case "clause": {
415
- let endTop;
416
- if (measurement.endTriggerIsSelf) endTop = naturalAbsoluteTop;
417
- else {
418
- const known = measurement.endTriggerIndex === null ? void 0 : naturalTops[measurement.endTriggerIndex] !== void 0 ? naturalTops[measurement.endTriggerIndex] : previous ? previous.naturalTops[measurement.endTriggerIndex] : void 0;
419
- if (known !== void 0) endTop = known;
420
- else if (measurement.end.measureLive) endTop = measureLiveEndTriggerTop(index);
421
- else endTop = measurement.end.rawTop === null ? 0 : measurement.end.rawTop + gapsBeforeRawPosition(measurements, paddingHeightsSoFar, previous, measurement.end.rawTop, index);
422
- }
423
- const anchorOffsetEnd = resolveAnchorTop(measurement.end.clause, measurement.endTriggerHeight, viewportHeight);
424
- freezeEnd = Math.max(freezeStart, endTop - anchorOffsetEnd);
425
- break;
426
- }
427
- }
428
- let plan;
429
- if (measurement.kind === "cover") {
430
- if (measurement.start.mode !== "clause") throw new Error("StickyScrollTrigger: internal error: a cover layer measurement carries an absolute start, which resolveStartSpec should have already rejected.");
431
- plan = {
432
- freezeStart,
433
- freezeEnd,
434
- stickyTop: measurement.start.anchorOffset - (measurement.triggerTop - measurement.wrapperTop),
435
- paddingHeight: null
436
- };
437
- } else plan = {
438
- freezeStart,
439
- freezeEnd,
440
- stickyTop: structureTop - freezeStart,
441
- paddingHeight: Math.max(0, freezeEnd - freezeStart)
442
- };
443
- if (plan.paddingHeight !== null) precedingGaps += plan.paddingHeight;
444
- naturalTops[index] = naturalAbsoluteTop;
445
- paddingHeightsSoFar[index] = plan.paddingHeight;
446
- return plan;
447
- }),
448
- naturalTops
449
- };
450
- };
451
- const planLayers = (measurements, deps) => {
452
- const needsConvergence = measurements.some((measurement, index) => {
453
- if (measurement.end.mode !== "clause" || measurement.endTriggerIsSelf) return false;
454
- return measurement.endTriggerIndex === null ? measurement.end.rawTop !== null : measurement.endTriggerIndex >= index;
455
- });
456
- const liveTopCache = new Map();
457
- const passDeps = {
458
- ...deps,
459
- measureLiveEndTriggerTop: (index) => {
460
- const cached = liveTopCache.get(index);
461
- if (cached !== void 0) return cached;
462
- const value = deps.measureLiveEndTriggerTop(index);
463
- liveTopCache.set(index, value);
464
- return value;
465
- }
466
- };
467
- let { plans, naturalTops } = runPass(measurements, passDeps, null);
468
- if (needsConvergence) for (let pass = 0; pass < measurements.length; pass += 1) {
469
- const previous = {
470
- paddings: plans.map((plan) => plan.paddingHeight),
471
- naturalTops
472
- };
473
- const next = runPass(measurements, passDeps, previous);
474
- const stable = next.plans.every((plan, i) => plan.paddingHeight === plans[i].paddingHeight);
475
- plans = next.plans;
476
- naturalTops = next.naturalTops;
477
- if (stable) break;
478
- if (pass === measurements.length - 1) throw new Error("StickyScrollTrigger: could not resolve endTrigger positions: some endTrigger references form a circular structural dependency, each layer's end depending on a layer whose own end depends back on it. Point each endTrigger at a layer that doesn't depend on it.");
479
- }
480
- plans.forEach((plan, index) => deps.onPlanned(index, plan));
481
- return plans;
482
- };
483
- const EXCLUDED_VAR_KEYS = [
484
- "trigger",
485
- "start",
486
- "end",
487
- "endTrigger",
488
- "pin",
489
- "pinSpacing",
490
- "anticipatePin",
491
- "pinnedContainer",
492
- "pinReparent",
493
- "pinSpacer",
494
- "pinType",
495
- "horizontal",
496
- "scroller",
497
- "containerAnimation"
498
- ];
499
760
  const resolveEndSpec = (rootElement, viewportHeight, layer, endResolved, ownIndex, endTriggerIndex) => {
500
761
  if (endResolved === null) return { mode: "auto" };
501
- if (isDwellFormat(endResolved)) return {
502
- mode: "dwell",
503
- distancePx: Math.max(0, resolveDwell(endResolved, viewportHeight))
504
- };
505
- if (isAbsoluteFormat(endResolved)) return {
506
- mode: "absolute",
507
- value: resolveAbsolute(endResolved)
508
- };
509
- if (isMaxFormat(endResolved)) {
510
- if (layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has end "${endResolved}". GSAP's 'max' keyword isn't supported here: the layer's own dwell padding adds to the document's max scroll position, so the freeze window would depend on itself. Use createOverlapScroll, which adds no padding, or a dwell distance such as '+=500'.`);
511
- return {
512
- mode: "max",
513
- offsetPx: resolveMaxOffset(endResolved, viewportHeight)
762
+ const classified = classifyPosition(endResolved);
763
+ switch (classified.kind) {
764
+ case "dwell": return {
765
+ mode: "dwell",
766
+ distancePx: Math.max(0, resolveDwell(classified.value, viewportHeight))
514
767
  };
768
+ case "absolute": return {
769
+ mode: "absolute",
770
+ value: classified.value
771
+ };
772
+ case "max":
773
+ if (layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has end "${endResolved}". GSAP's 'max' keyword isn't supported here: the layer's own dwell padding adds to the document's max scroll position, so the freeze window would depend on itself. Use createOverlapScroll, which adds no padding, or a dwell distance such as '+=500'.`);
774
+ return {
775
+ mode: "max",
776
+ offsetPx: resolveMaxOffset(classified.value, viewportHeight)
777
+ };
778
+ case "clause": {
779
+ if (layer.kind !== "cover" && endTriggerIndex !== null && endTriggerIndex > ownIndex) throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)}'s endTrigger (${describeElement(layer.endTrigger)}) refers to a layer positioned later in DOM order, which isn't supported for createStickyTrigger. Point endTrigger at a layer earlier in DOM order, use an unregistered element at the same spot, or use a dwell distance such as '+=500'.`);
780
+ const unregistered = endTriggerIndex === null;
781
+ const insideRoot = rootElement.contains(layer.endTrigger);
782
+ if (unregistered && !insideRoot && layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has an endTrigger (${describeElement(layer.endTrigger)}) outside the shared container: the layer's own dwell keeps pushing it away, so the freeze window never settles. Point endTrigger at an element inside the container, or use a dwell distance such as '+=500'.`);
783
+ return {
784
+ mode: "clause",
785
+ clause: classified.value,
786
+ rawTop: unregistered && insideRoot ? documentTop(layer.endTrigger) : null,
787
+ measureLive: unregistered && !insideRoot
788
+ };
789
+ }
515
790
  }
516
- if (layer.kind !== "cover" && endTriggerIndex !== null && endTriggerIndex > ownIndex) throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)}'s endTrigger (${describeElement(layer.endTrigger)}) refers to a layer positioned later in DOM order, which isn't supported: this layer's own dwell padding pushes that one down, so the freeze window would depend on its own dwell. Point endTrigger at a layer earlier in DOM order, or use a dwell distance such as '+=500'.`);
517
- const unregistered = endTriggerIndex === null;
518
- const insideRoot = rootElement.contains(layer.endTrigger);
519
- if (unregistered && !insideRoot && layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has an endTrigger (${describeElement(layer.endTrigger)}) outside the shared container: the layer's own dwell keeps pushing it away, so the freeze window never settles. Point endTrigger at an element inside the container, or use a dwell distance such as '+=500'.`);
520
- return {
521
- mode: "clause",
522
- clause: endResolved,
523
- rawTop: unregistered && insideRoot ? documentTop(layer.endTrigger) : null,
524
- measureLive: unregistered && !insideRoot
525
- };
526
791
  };
527
792
  const resolveStartSpec = (layer, startResolved, elementHeight, viewportHeight) => {
528
- if (!isAbsoluteFormat(startResolved)) return {
529
- mode: "clause",
530
- anchorOffset: resolveAnchorTop(startResolved, elementHeight, viewportHeight)
531
- };
532
- if (layer.kind === "cover") throw new Error(`StickyScrollTrigger: createOverlapScroll's trigger ${describeElement(layer.trigger)} has start "${startResolved}", an absolute scroll position (GSAP reads any bare number this way). That isn't supported here: a cover layer's sticky position is computed relative to its own wrapper, so start must be a position clause such as 'bottom bottom'.`);
533
- return {
534
- mode: "absolute",
535
- value: resolveAbsolute(startResolved)
536
- };
793
+ const classified = classifyPosition(startResolved);
794
+ switch (classified.kind) {
795
+ case "absolute":
796
+ if (layer.kind === "cover") throw new Error(`StickyScrollTrigger: createOverlapScroll's trigger ${describeElement(layer.trigger)} has start "${startResolved}", an absolute scroll position (GSAP reads any bare number this way). That isn't supported here: a cover layer's sticky position is computed relative to its own wrapper, so start must be a position clause such as 'bottom bottom'.`);
797
+ return {
798
+ mode: "absolute",
799
+ value: classified.value
800
+ };
801
+ case "max":
802
+ case "dwell":
803
+ case "clause": return {
804
+ mode: "clause",
805
+ anchorOffset: resolveAnchorTop(classified.value, elementHeight, viewportHeight),
806
+ elementFraction: resolveElementFraction(classified.value)
807
+ };
808
+ }
537
809
  };
538
810
  const measureLayer = (rootElement, viewportHeight, layer, ownIndex, indexByTrigger) => {
539
811
  const startResolved = resolveMaybeFn(layer.start);
540
- const endResolved = layer.end === null ? null : resolveMaybeFn(layer.end);
541
- const elementHeight = layer.trigger.offsetHeight;
812
+ const endResolved = layer.end === null ? null : prefixSpacedRelativeEnd(startResolved, resolveMaybeFn(layer.end));
813
+ const elementHeight = measureUsedHeight(layer.trigger);
542
814
  const endTriggerIsSelf = layer.endTrigger === layer.trigger;
543
815
  const endTriggerIndex = indexByTrigger.get(layer.endTrigger) ?? null;
544
816
  const end = resolveEndSpec(rootElement, viewportHeight, layer, endResolved, ownIndex, endTriggerIndex);
@@ -547,14 +819,34 @@ var StickyScrollTrigger = (function() {
547
819
  kind: layer.kind,
548
820
  start,
549
821
  triggerTop: documentTop(layer.trigger),
822
+ triggerHeight: elementHeight,
823
+ triggerEnclosedBy: [...indexByTrigger].filter(([trigger]) => trigger.contains(layer.trigger)).map(([, index]) => index),
550
824
  wrapperTop: layer.wrapper ? documentTop(layer.wrapper) : 0,
551
825
  coverTop: layer.kind === "cover" ? documentTop(layer.cover) : 0,
552
826
  end,
553
827
  endTriggerIsSelf,
554
828
  endTriggerIndex,
555
- endTriggerHeight: end.mode === "clause" ? layer.endTrigger.offsetHeight : 0
829
+ endTriggerHeight: end.mode === "clause" ? measureUsedHeight(layer.endTrigger) : 0,
830
+ endTriggerEnclosedBy: end.mode === "clause" && !end.measureLive && !endTriggerIsSelf ? [...indexByTrigger].filter(([trigger]) => trigger.contains(layer.endTrigger)).map(([, index]) => index) : [],
831
+ endTriggerNests: end.mode === "clause" && !end.measureLive && !endTriggerIsSelf ? [...indexByTrigger].filter(([trigger]) => trigger !== layer.endTrigger && layer.endTrigger.contains(trigger)).map(([, index]) => index) : []
556
832
  };
557
833
  };
834
+ const EXCLUDED_VAR_KEYS = [
835
+ "trigger",
836
+ "start",
837
+ "end",
838
+ "endTrigger",
839
+ "pin",
840
+ "pinSpacing",
841
+ "anticipatePin",
842
+ "pinnedContainer",
843
+ "pinReparent",
844
+ "pinSpacer",
845
+ "pinType",
846
+ "horizontal",
847
+ "scroller",
848
+ "containerAnimation"
849
+ ];
558
850
  const topToStartClause = (top) => {
559
851
  const toClause = (value) => {
560
852
  if (!Number.isFinite(value)) throw new Error(`StickyScrollTrigger: createStickyPin's top must be a finite number, got ${value}.`);
@@ -562,10 +854,12 @@ var StickyScrollTrigger = (function() {
562
854
  };
563
855
  return typeof top === "function" ? () => toClause(top()) : toClause(top);
564
856
  };
565
- const resolvePinReleaseTop = (endTrigger, resolvedEnd, engageTop, viewportHeight) => {
566
- if (isDwellFormat(resolvedEnd)) return engageTop + resolveDwell(resolvedEnd, viewportHeight);
567
- if (isAbsoluteFormat(resolvedEnd)) return resolveAbsolute(resolvedEnd);
568
- return documentTop(endTrigger) - resolveAnchorTop(resolvedEnd, endTrigger.offsetHeight, viewportHeight);
857
+ const resolvePinReleaseScroll = (endTrigger, classifiedEnd, engageScroll, viewportHeight, toScroll) => {
858
+ switch (classifiedEnd.kind) {
859
+ case "dwell": return engageScroll + resolveDwell(classifiedEnd.value, viewportHeight);
860
+ case "absolute": return classifiedEnd.value;
861
+ case "clause": return toScroll(endTrigger, documentTop(endTrigger) - resolveAnchorTop(classifiedEnd.value, measureUsedHeight(endTrigger), viewportHeight));
862
+ }
569
863
  };
570
864
  const hasDuplicateTrigger = (list, trigger) => list.some((existing) => existing.trigger === trigger);
571
865
  var StickyScrollTrigger = class {
@@ -581,16 +875,15 @@ var StickyScrollTrigger = (function() {
581
875
  #scrollTriggerClass = null;
582
876
  #pinLayers = [];
583
877
  #scrollMarginSync;
584
- #scrollMarginTargets;
585
878
  constructor(root, options = {}) {
586
879
  this.#rootElement = resolveRoot(root);
587
- this.#scrollMarginSync = createScrollMarginSync(this.#rootElement);
588
- this.#scrollMarginTargets = options.scrollMarginTargets === void 0 ? "[id]" : options.scrollMarginTargets;
589
- if (this.#scrollMarginTargets !== null) try {
590
- this.#rootElement.querySelectorAll(this.#scrollMarginTargets);
880
+ const scrollMarginTargets = options.scrollMarginTargets === void 0 ? "[id]" : options.scrollMarginTargets;
881
+ if (scrollMarginTargets !== null) try {
882
+ this.#rootElement.querySelectorAll(scrollMarginTargets);
591
883
  } catch {
592
- throw new Error(`StickyScrollTrigger: scrollMarginTargets "${this.#scrollMarginTargets}" is not a valid CSS selector.`);
884
+ throw new Error(`StickyScrollTrigger: scrollMarginTargets "${scrollMarginTargets}" is not a valid CSS selector.`);
593
885
  }
886
+ this.#scrollMarginSync = createScrollMarginSync(this.#rootElement, scrollMarginTargets);
594
887
  }
595
888
  #unbuild() {
596
889
  if (!this.#built) return;
@@ -615,13 +908,20 @@ var StickyScrollTrigger = (function() {
615
908
  });
616
909
  }
617
910
  #captureScrollTriggerClass(self) {
911
+ if (this.#destroyed) return;
618
912
  this.#scrollTriggerClass = self.constructor;
619
913
  }
620
914
  #createAutoRefreshHandler(userOnRefreshInit) {
621
915
  return (self) => {
622
916
  this.#captureScrollTriggerClass(self);
623
917
  const result = userOnRefreshInit?.(self);
624
- this.refresh();
918
+ try {
919
+ this.refresh();
920
+ } catch (error) {
921
+ queueMicrotask(() => {
922
+ throw error;
923
+ });
924
+ }
625
925
  return result;
626
926
  };
627
927
  }
@@ -673,6 +973,24 @@ var StickyScrollTrigger = (function() {
673
973
  });
674
974
  };
675
975
  }
976
+ #resetPinStickyState() {
977
+ const snapshots = this.#pinLayers.filter((layer) => layer.inner).map(({ trigger }) => ({
978
+ trigger,
979
+ position: captureInlinePosition(trigger)
980
+ }));
981
+ snapshots.forEach(({ trigger }) => resetStickyPosition(trigger));
982
+ return () => {
983
+ snapshots.forEach(({ trigger, position }) => restoreInlinePosition(trigger, position));
984
+ };
985
+ }
986
+ #resetStickyState() {
987
+ const restoreSceneCoverStickyState = this.#resetSceneCoverStickyState();
988
+ const restorePinStickyState = this.#resetPinStickyState();
989
+ return () => {
990
+ restorePinStickyState();
991
+ restoreSceneCoverStickyState();
992
+ };
993
+ }
676
994
  #resetPinState() {
677
995
  const snapshots = this.#pinLayers.map((layer) => ({
678
996
  layer,
@@ -695,7 +1013,7 @@ var StickyScrollTrigger = (function() {
695
1013
  const restoreSceneCoverStickyState = this.#resetSceneCoverStickyState();
696
1014
  const restorePinState = this.#resetPinState();
697
1015
  try {
698
- this.#refreshPinLayers(viewportHeight);
1016
+ this.#refreshPinLayers(viewportHeight, measureDocumentHeightWithoutPinRanges());
699
1017
  } catch (error) {
700
1018
  restorePinState();
701
1019
  throw error;
@@ -703,19 +1021,25 @@ var StickyScrollTrigger = (function() {
703
1021
  restoreSceneCoverStickyState();
704
1022
  }
705
1023
  }
706
- #refreshPinLayers(viewportHeight) {
1024
+ #refreshPinLayers(viewportHeight, documentHeight) {
707
1025
  this.#pinLayers.forEach((layer) => {
708
1026
  if (!layer.inner) return;
709
- const resolvedEnd = resolveMaybeFn(layer.end);
710
- if (isMaxFormat(resolvedEnd)) throw new Error(`StickyScrollTrigger: createStickyPin's end "${resolvedEnd}" uses GSAP's 'max' keyword, which isn't supported here: the pin's own spacer height adds to the document's max scroll position, so it would depend on itself. Use a position clause against endTrigger, such as 'top top'.`);
711
1027
  const resolvedStart = resolveMaybeFn(layer.start);
1028
+ const resolvedEnd = prefixSpacedRelativeEnd(resolvedStart, resolveMaybeFn(layer.end));
1029
+ const classifiedEnd = classifyPosition(resolvedEnd);
1030
+ if (classifiedEnd.kind === "max") throw new Error(`StickyScrollTrigger: createStickyPin's end "${resolvedEnd}" uses GSAP's 'max' keyword, which isn't supported here: the pin's own spacer height adds to the document's max scroll position, so it would depend on itself. Use a position clause against endTrigger, such as 'top top'.`);
712
1031
  const triggerTop = documentTop(layer.trigger);
713
- const triggerHeight = layer.trigger.offsetHeight;
714
- if (isAbsoluteFormat(resolvedStart)) throw new Error(`StickyScrollTrigger: createStickyPin's start "${resolvedStart}" is an absolute scroll position (GSAP reads any bare number this way). A pin can't act on one: it engages when position:sticky engages, so start says where trigger sits in the viewport while pinned. Use the top option (top: ${resolvedStart}) for a px distance from the viewport's top edge, or a position clause such as 'top top'.`);
715
- const topPx = resolveAnchorTop(resolvedStart, triggerHeight, viewportHeight);
716
- const height = resolvePinReleaseTop(layer.endTrigger, resolvedEnd, triggerTop - topPx, viewportHeight) - triggerTop + topPx + triggerHeight;
1032
+ const triggerHeight = measureUsedHeight(layer.trigger);
1033
+ const triggerMarginBottom = parseFloat(getComputedStyle(layer.trigger).marginBottom) || 0;
1034
+ const classifiedStart = classifyPosition(resolvedStart);
1035
+ if (classifiedStart.kind === "absolute") throw new Error(`StickyScrollTrigger: createStickyPin's start "${resolvedStart}" is an absolute scroll position (GSAP reads any bare number this way). A pin can't act on one: it engages when position:sticky engages, so start says where trigger sits in the viewport while pinned. Use the top option (top: ${resolvedStart}) for a px distance from the viewport's top edge, or a position clause such as 'top top'.`);
1036
+ const topPx = resolveAnchorTop(classifiedStart.value, triggerHeight, viewportHeight);
1037
+ const toScroll = (element, reachedAt) => this.#addDwellBeforeReach(element, reachedAt);
1038
+ const releaseScroll = resolvePinReleaseScroll(layer.endTrigger, classifiedEnd, toScroll(layer.trigger, triggerTop - topPx), viewportHeight, toScroll);
1039
+ const height = releaseScroll - (this.#rootElement.contains(layer.trigger) ? dwellConsumedAt(releaseScroll, this.#sceneLayers()) : 0) - triggerTop + topPx + triggerHeight + triggerMarginBottom;
1040
+ const room = documentHeight > 0 ? documentHeight - triggerTop : Infinity;
717
1041
  applyStickyPosition(layer.trigger, topPx);
718
- layer.inner.style.height = `${Math.max(0, height)}px`;
1042
+ layer.inner.style.height = `${Math.max(0, Math.min(height, room))}px`;
719
1043
  });
720
1044
  }
721
1045
  #refreshScenesAndCovers(viewportHeight) {
@@ -723,11 +1047,14 @@ var StickyScrollTrigger = (function() {
723
1047
  const active = this.#layers.filter((layer) => layer.wrapper !== null);
724
1048
  if (!active.length) return;
725
1049
  const restoreStickyState = this.#resetSceneCoverStickyState();
1050
+ const restorePinStickyState = this.#resetPinStickyState();
726
1051
  try {
727
1052
  this.#planLayerPositions(viewportHeight, active);
728
1053
  } catch (error) {
729
1054
  restoreStickyState();
730
1055
  throw error;
1056
+ } finally {
1057
+ restorePinStickyState();
731
1058
  }
732
1059
  }
733
1060
  #planLayerPositions(viewportHeight, active) {
@@ -789,11 +1116,16 @@ var StickyScrollTrigger = (function() {
789
1116
  });
790
1117
  }
791
1118
  #syncScrollMargins() {
792
- this.#scrollMarginSync.sync(this.#layers.filter((layer) => layer.kind === "scene").map(({ trigger, freezeStart, freezeEnd }) => ({
793
- trigger,
1119
+ this.#scrollMarginSync.sync(this.#sceneLayers().map(({ freezeStart, freezeEnd }) => ({
794
1120
  freezeStart,
795
1121
  freezeEnd
796
- })), this.#outermostContainer, this.#scrollMarginTargets);
1122
+ })), this.#outermostContainer, (targets) => {
1123
+ if (!targets.length) return [];
1124
+ const restoreStickyState = this.#resetStickyState();
1125
+ const tops = targets.map((target) => documentTop(target));
1126
+ restoreStickyState();
1127
+ return tops;
1128
+ });
797
1129
  }
798
1130
  #assertNoExcludedVars(rest, context) {
799
1131
  const found = EXCLUDED_VAR_KEYS.filter((key) => key in rest);
@@ -915,25 +1247,36 @@ var StickyScrollTrigger = (function() {
915
1247
  const element = resolveElement(elementInput, "resolveScrollPosition");
916
1248
  const resolved = resolveMaybeFn(position);
917
1249
  const viewportHeight = measureViewportHeight();
918
- if (isMaxFormat(resolved)) return measureDocumentMaxScroll(viewportHeight) + resolveMaxOffset(resolved, viewportHeight);
919
- if (isAbsoluteFormat(resolved)) return resolveAbsolute(resolved);
920
- let gap = 0;
921
- this.#layers.forEach((layer) => {
922
- if (layer.kind !== "scene") return;
923
- if (compareDocumentOrder(layer.trigger, element) >= 0) return;
924
- gap += layer.freezeEnd - layer.freezeStart;
925
- });
926
- const anchorOffset = resolveAnchorTop(resolved, element.offsetHeight, viewportHeight);
927
- const restoreSceneCoverStickyState = this.#resetSceneCoverStickyState();
928
- const result = documentTop(element) + gap - anchorOffset;
929
- restoreSceneCoverStickyState();
930
- return result;
1250
+ const classified = classifyPosition(resolved);
1251
+ switch (classified.kind) {
1252
+ case "max": return measureDocumentMaxScroll(viewportHeight) + resolveMaxOffset(classified.value, viewportHeight);
1253
+ case "absolute": return classified.value;
1254
+ case "dwell":
1255
+ case "clause": return this.#resolveClauseScrollPosition(element, classified.value, viewportHeight);
1256
+ }
1257
+ }
1258
+ #resolveClauseScrollPosition(element, clause, viewportHeight) {
1259
+ const anchorOffset = resolveAnchorTop(clause, measureUsedHeight(element), viewportHeight);
1260
+ const restoreStickyState = this.#resetStickyState();
1261
+ const reachedAt = documentTop(element) - anchorOffset;
1262
+ restoreStickyState();
1263
+ return this.#addDwellBeforeReach(element, reachedAt);
1264
+ }
1265
+ #addDwellBeforeReach(element, reachedAt) {
1266
+ if (!this.#rootElement.contains(element)) return reachedAt;
1267
+ return reachedAt + dwellBeforeReach(reachedAt, this.#sceneLayers());
1268
+ }
1269
+ #sceneLayers() {
1270
+ return this.#layers.filter((layer) => layer.kind === "scene");
931
1271
  }
932
1272
  static getScrollTop(elementInput, instances) {
933
1273
  const element = resolveElement(elementInput, "StickyScrollTrigger.getScrollTop");
934
1274
  const owner = instances.find((instance) => instance.#rootElement.contains(element));
935
1275
  if (owner) return owner.resolveScrollPosition(element, "top top");
936
- return documentTop(element);
1276
+ const restores = instances.map((instance) => instance.#resetPinStickyState());
1277
+ const top = documentTop(element);
1278
+ restores.forEach((restore) => restore());
1279
+ return top;
937
1280
  }
938
1281
  createResolvedTrigger({ trigger: triggerInput, start = "top bottom", end = "bottom top", endTrigger: endTriggerInput, ...rest }) {
939
1282
  this.#assertNoExcludedVars(rest, "createResolvedTrigger");
@@ -943,7 +1286,12 @@ var StickyScrollTrigger = (function() {
943
1286
  ...rest,
944
1287
  trigger,
945
1288
  start: () => this.resolveScrollPosition(trigger, start),
946
- end: () => this.resolveScrollPosition(endTrigger, end)
1289
+ end: () => {
1290
+ const resolvedEnd = resolveMaybeFn(end);
1291
+ const classifiedEnd = classifyPosition(resolvedEnd);
1292
+ if (classifiedEnd.kind === "dwell") return this.resolveScrollPosition(trigger, start) + resolveDwell(classifiedEnd.value, measureViewportHeight());
1293
+ return this.resolveScrollPosition(endTrigger, prefixSpacedRelativeEnd(start, resolvedEnd));
1294
+ }
947
1295
  };
948
1296
  }
949
1297
  destroy() {
@@ -956,6 +1304,7 @@ var StickyScrollTrigger = (function() {
956
1304
  this.#builtLayers = [];
957
1305
  this.#pinLayers.forEach((layer) => this.#unwrapPinLayer(layer));
958
1306
  this.#pinLayers.length = 0;
1307
+ this.#scrollTriggerClass = null;
959
1308
  }
960
1309
  };
961
1310
  return StickyScrollTrigger;