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